Add installable OpenShell agent runner

[johnnygreco]

Summary

• add openshell-agent-runner, an installable Python package with the oar CLI
• provide packaged starter profiles through oar init, plus profile validation, dry-run previews, task execution, and read-only OpenShell diagnostics
• launch Pi in an ephemeral OpenShell sandbox with explicit tools, skills, extensions, model settings, uploads, and optional structured output
• add the repository's Dev Note reviewer profile under .github/openshell-agents
• run repository-agent CI through the packaged runner and validate the wheel, Pi image, extensions, profiles, and documentation
• add focused developer and local release workflows for the new project

Approach

OAR is deliberately a small orchestrator, not another agent framework. A profile directory owns stable task behavior: its OpenShell policy, Pi model settings, prompts, tools, skills, extensions, uploads, and optional JSON Schema. CLI options provide values that vary by run, such as the task, input, output, gateway, and workspace.

The runner preserves OpenShell's native lifecycle and configuration. It creates a persistent sandbox, uploads task and runtime files, executes the Pi harness, downloads and validates one declared result, verifies sandbox ownership, and deletes the sandbox. oar run --dry-run prints those exact commands without making changes.

OAR does not create or modify gateways, providers, credentials, workspaces, inference routes, or source-control state. Those remain owned by OpenShell and the sandboxed agent.

Quick start

export MODEL_ID="provider/model"

uvx --from openshell-agent-runner oar init ./profiles --model "$MODEL_ID"
uvx --from openshell-agent-runner oar validate ./profiles/reviewer
uvx --from openshell-agent-runner oar doctor --gateway openshell

uvx --from openshell-agent-runner oar run ./profiles/reviewer \
  --task review \
  --gateway openshell \
  --input document.md \
  --output review.md

Validation

• make check: Ruff format and lint, ty, 104 pytest tests, Python compilation, and shell syntax
• make build: source distribution and wheel
• built-wheel uvx initialization, validation, and lifecycle preview
• packaged wheel asset inspection
• strict documentation build and local HTTP preview
• repository profile and pre-commit configuration validation
• repository-wide license-header check
• git diff --check
• independent runtime/security, integration/release, and product/complexity reviews: clean

GitHub-hosted CI performs credential-free validation, packaging, command preview, image build, and extension checks. It does not run live inference.

[github-actions]

Documentation preview

The preview has been removed.