Add installable OpenShell agent runner

[johnnygreco]

Summary

• add openshell-agent-runner, an installable Python package that exposes the oar CLI
• validate and run self-contained profile directories with native OpenShell sandbox commands
• provide validate, run, and read-only doctor commands, including a run --dry-run preview of every generated OpenShell command
• run Pi as an autonomous coding agent with explicit tools, skills, extensions, model settings, and a Pydantic-backed DocumentReview artifact
• add a repository-owned Dev Note review profile under .github/openshell-agents
• migrate repository-agent CI to consume the package and profiles, validate distributions, and build the pinned Pi image
• apply Ruff's Black-compatible formatter automatically through a pre-commit hook

Approach

The earlier PR implementation was a repository-specific shell runner under dev-tools/agents. This revision replaces that approach with a small package that can be installed and invoked with uvx while remaining the implementation used by this repository's CI.

OAR is deliberately an orchestrator rather than an agent framework. Each profile is a directory containing profile.yaml; that file explicitly identifies the policy, prompts, skills, and extensions within the same directory. YAML and invocation-specific CLI options determine what OpenShell uploads and runs. The sandboxed agent owns repository inspection, Git operations, tool use, analysis, and conclusions. OAR does not create or modify gateways, providers, inference routes, or source-control state.

The runner uses native OpenShell CLI operations for sandbox creation, file transfer, execution, ownership inspection, and deletion. This keeps --dry-run transparent and avoids duplicating OpenShell configuration behavior in the runner. Only the declared artifact is downloaded; it is validated with Pydantic and atomically published on the host.

User impact

Profiles can be checked and run locally with:

uvx --from ./projects/openshell-agent-runner oar validate PROFILE_DIRECTORY
uvx --from ./projects/openshell-agent-runner oar run PROFILE_DIRECTORY --task TASK --output PATH [OPTIONS]
uvx --from ./projects/openshell-agent-runner oar doctor [OPTIONS]

The repository workflow intentionally performs credential-free validation, packaging, command preview, and image build. Live inference remains an authenticated local or self-hosted CI operation.

Validation

• locked dependency synchronization
• repository and starter profile-directory validation
• no-execution dry-run of the complete OpenShell lifecycle
• Ruff format and lint checks
• ty static analysis
• pytest: 53 passed
• Python compilation and Pi shell syntax checks
• source distribution and wheel build
• wheel asset inspection and clean uvx validation
• pinned Pi Docker image build
• repository license-header check
• git diff --check

A bounded live OpenShell run was also completed during development using a three-file repository fixture. Pi produced a valid DocumentReview, host validation passed, and ownership-checked sandbox deletion was confirmed. Live inference is not executed by the GitHub-hosted workflow.