Spring-clean OpenShell Agent Runner

Author: johnnygreco

.github/workflows/repository-agents.yml

@@ -75,17 +75,12 @@ jobs:
         working-directory: projects/openshell-agent-runner
         run: |
           uv run pre-commit validate-config ../../.pre-commit-config.yaml
-          uv run ruff format --check .
-          uv run ruff check .
-          uv run ty check
-          uv run pytest
-          python -m compileall -q src tests
-          bash -n src/openshell_agent_runner/harnesses/pi/runtime/image/exec.sh
+          make check
 
       - name: Build distributions
         working-directory: projects/openshell-agent-runner
         run: |
-          uv build
+          make build
           wheel="$(find dist -name '*.whl' -print -quit)"
           python -m zipfile -l "$wheel" | grep -F 'harnesses/pi/runtime/image/Dockerfile'
           python -m zipfile -l "$wheel" | grep -F 'harnesses/pi/runtime/image/exec.sh'
@@ -136,11 +131,9 @@ jobs:
             --volume "$PWD/projects/openshell-agent-runner/tests/fixtures/tools.json:/sandbox/tools.json:ro" \
             --volume "$PWD/projects/openshell-agent-runner/src/openshell_agent_runner/harnesses/pi/runtime/extensions/submit-result.ts:/sandbox/oar-submit-result.ts:ro" \
             --volume "$PWD/projects/openshell-agent-runner/src/openshell_agent_runner/harnesses/pi/runtime/extensions/validate-tools.ts:/sandbox/oar-validate-tools.ts:ro" \
+            --volume "$PWD/projects/openshell-agent-runner/tests/fixtures/validate-pi-extensions.mjs:/sandbox/validate-pi-extensions.mjs:ro" \
             openshell-agent-runner-pi:ci \
-            -c "ln -s /usr/local/lib/node_modules /sandbox/node_modules && node \
-              --experimental-strip-types --no-warnings --input-type=module \
-              --eval \"await import('/sandbox/oar-submit-result.ts'); \
-                const validator = await import('/sandbox/oar-validate-tools.ts'); \
-                if (validator.findMissingTools(['missing'], [{name: 'read'}])[0] !== 'missing') process.exit(1); \
-                let handler; validator.default({on: (event, value) => {if (event === 'before_agent_start') handler = value;}}); \
-                await handler({}, {getAllTools: () => [{name: 'read'}], getActiveTools: () => ['read']});\""
+            -c "ln -s /usr/local/lib/node_modules /sandbox/node_modules && \
+              node \
+              --experimental-strip-types --no-warnings \
+              /sandbox/validate-pi-extensions.mjs"

plans/openshell-agent-runner-refactor.md

@@ -15,4 +15,4 @@
   and optional JSON Schema validation are the output boundary; they do not
   attest agent-produced claims.
 - Use `apply_patch` for edits and `uv` for dependencies, builds, and execution.
-- Before handing off, run `uv sync --locked`, Ruff, ty, pytest, and `uv build`.
+- Before handing off, run `make check` and `make build`.

projects/openshell-agent-runner/AGENTS.md

@@ -3,6 +3,10 @@
 
 .DEFAULT_GOAL := help
 
+UV ?= uv
+UV_RUN := $(UV) run --frozen
+PYTEST_ARGS ?=
+
 PUBLISH_FLAGS :=
 ifdef DRY_RUN
 PUBLISH_FLAGS += --dry-run
@@ -14,7 +18,7 @@ ifdef RETRY_ARTIFACT
 PUBLISH_FLAGS += --retry-artifact $(RETRY_ARTIFACT)
 endif
 
-.PHONY: help publish
+.PHONY: help sync test format-check lint typecheck check build clean publish
 
 help: ## Show available targets and configurable variables.
 	@awk 'BEGIN {FS = ":.*## "}; /^[a-zA-Z0-9_.-]+:.*## / {printf "  %-12s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
@@ -23,6 +27,33 @@ help: ## Show available targets and configurable variables.
 	@printf "  DRY_RUN=1          Validate a release without tagging or uploading\n"
 	@printf "  ALLOW_NON_MAIN=1   Permit release validation or publishing off main\n"
 	@printf "  RETRY_ARTIFACT=... Retry a missing wheel, sdist, or both after a failed upload\n"
+	@printf "  PYTEST_ARGS=...    Extra pytest paths or flags\n"
+
+sync: ## Install locked runtime and development dependencies.
+	$(UV) sync --locked
+
+test: ## Run tests; pass paths or flags with PYTEST_ARGS.
+	$(UV_RUN) pytest $(PYTEST_ARGS)
+
+format-check: ## Check Python formatting.
+	$(UV_RUN) ruff format --check .
+
+lint: ## Run Ruff lint checks.
+	$(UV_RUN) ruff check .
+
+typecheck: ## Run ty type checks.
+	$(UV_RUN) ty check
+
+check: sync format-check lint typecheck test ## Run the full project checks.
+	$(UV_RUN) python -m compileall -q src tests
+	bash -n src/openshell_agent_runner/harnesses/pi/runtime/image/exec.sh
+
+build: ## Build the source distribution and wheel.
+	$(UV) build --clear --no-sources
+
+clean: ## Remove build, test, lint, and Python cache artifacts.
+	rm -rf build dist .pytest_cache .ruff_cache
+	find src tests -type d -name __pycache__ -prune -exec rm -rf {} +
 
 publish: ## Validate or publish a release; requires VERSION.
 ifndef VERSION