Metadata-Version: 2.5
Name: openshell-agent-runner
Version: 0.0.1
Summary: Launch ephemeral agents for single tasks in OpenShell sandboxes.
Project-URL: Repository, https://github.com/NVIDIA/OpenShell-Research
Project-URL: Documentation, https://github.com/NVIDIA/OpenShell-Research/blob/main/projects/openshell-agent-runner/docs/index.md
Author: NVIDIA CORPORATION & AFFILIATES
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: jsonschema<5,>=4.25
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml<7,>=6
Requires-Dist: typer<1,>=0.16
Description-Content-Type: text/markdown

# OpenShell Agent Runner

`openshell-agent-runner` provides the `oar` CLI for launching an ephemeral agent
to accomplish one configured task. Each `oar run` creates an isolated OpenShell
sandbox, runs the task, publishes one result, and removes the sandbox. This
single-task lifecycle makes OAR a natural fit for CI jobs and other automated
workflows that need bounded agent execution.

OAR has four commands:

```text
oar init PROFILE_ROOT --model MODEL_ID [OPTIONS]
oar validate PROFILE_DIRECTORY
oar run PROFILE_DIRECTORY --task TASK --output PATH [OPTIONS]
oar doctor [OPTIONS]
```

The profile defines what the ephemeral agent can see and do. OAR uploads the
declared inputs, starts Pi for the selected task, captures its result, optionally
validates it against a configured JSON Schema, publishes it atomically, and
deletes the sandbox. Repository inspection, Git operations, and conclusions
belong to Pi inside the sandbox.

## Why OAR fits CI

- Each invocation has a bounded lifecycle: one task, one ephemeral sandbox, one
  result, then cleanup.
- Profiles can be versioned with the repository so agent behavior, permissions,
  model settings, and output contracts are reviewable inputs to the job.
- Stable exit codes and an explicit `--output` path let later CI steps consume
  the result or fail the job.

The CI worker must be able to reach an existing OpenShell gateway with an
inference route for the profile's model. OAR uses that configured runtime; it
does not provision providers or credentials.

## Documentation

- [Launch ephemeral agents with OAR](https://github.com/NVIDIA/OpenShell-Research/blob/main/projects/openshell-agent-runner/docs/index.md):
  install, run a starter task, and understand the execution lifecycle.

## Requirements

- [`uv`](https://docs.astral.sh/uv/).
- OpenShell 0.0.111 or newer.
- A running OpenShell gateway that the host can reach.
- An inference route and its model ID.

OAR uses the gateway's `default` workspace unless `--workspace` selects another
one. An OpenShell workspace is a gateway-side namespace for sandboxes,
inference routes, and access controls; it is not the `/workspace` directory
inside a sandbox.

## Quick start

Create every profile packaged with OAR, check the gateway, and preview the
starter review task:

```bash
export MODEL_ID="provider/model"

uvx --from openshell-agent-runner oar init ./profiles \
  --model "$MODEL_ID"
uvx --from openshell-agent-runner oar doctor --gateway openshell
uvx --from openshell-agent-runner oar validate ./profiles/reviewer
uvx --from openshell-agent-runner oar run ./profiles/reviewer \
  --task review \
  --gateway openshell \
  --input document.md \
  --output review.md \
  --dry-run
```

Replace `provider/model` with the model ID configured on your inference route
and `openshell` with your gateway name. Remove `--dry-run` after `doctor`
confirms that the gateway and route are ready.

`init` copies packaged profiles into an ordinary local directory so they can be
inspected, edited, and committed. Omit `--profile` to create all packaged
profiles, or select one or more explicitly:

```bash
uvx --from openshell-agent-runner oar init ./profiles \
  --profile reviewer \
  --model "$MODEL_ID" \
  --thinking high
```

The `openshell` Pi provider, managed inference URL, and non-secret adapter value
are generated by OAR. `MODEL_ID` is only a shell variable passed to the required
`--model` option; OAR does not read it implicitly. Pass `--thinking off` when
the selected model does not support reasoning.

## Development install

Directly from this checkout:

```bash
uvx --from ./projects/openshell-agent-runner oar --help
```

For an editable development environment:

```bash
uv sync --project projects/openshell-agent-runner --locked
uv run --project projects/openshell-agent-runner pre-commit install
uv run --project projects/openshell-agent-runner oar --help
```

The pre-commit hook automatically applies Ruff's Black-compatible formatter to
staged Python files in this project. Hook installation is required once per
checkout.

See the [release instructions](https://github.com/NVIDIA/OpenShell-Research/blob/main/projects/openshell-agent-runner/RELEASING.md)
for package publication. The release command builds and publishes only
`openshell-agent-runner`; it does not package other projects in this repository.

OAR consumes existing OpenShell state and never creates or changes gateways,
providers, workspaces, or inference routes.

## Validate a profile

Pass the profile directory containing `profile.yaml`:

```bash
uv run --project projects/openshell-agent-runner oar validate \
  ./profiles/reviewer
```

Validation loads every referenced prompt, policy, skill, extension, and optional
output schema; rejects unknown keys and path escapes; and checks each schema.

## Check OpenShell

`doctor` performs read-only checks of the OpenShell CLI, selected gateway, and
inference configuration:

```bash
uv run --project projects/openshell-agent-runner oar doctor \
  --gateway openshell
```

## Run a profile task

Show help for a specific task by placing its profile and task before `--help`:

```bash
uv run --project projects/openshell-agent-runner oar run \
  ./profiles/reviewer \
  --task review \
  --help
```

This prints focused task help from the executable profile and task
configuration: the invocation, configured uploads and environment, and the
resulting output. Generic CLI options remain in `oar run --help`.

```bash
uv run --project projects/openshell-agent-runner oar run \
  .github/openshell-agents/profiles/dev-note-reviewer \
  --task editorial \
  --gateway openshell \
  --upload .:/workspace/source \
  --upload .git:/workspace/source/.git \
  --env REVIEW_TARGET_PATH=docs/dev-notes/posts/2026-08-07-formal-methods-ai-generated-robot-actions.md \
  --output /tmp/dev-note-review.json
```

The supported run options are deliberately small:

- `--task`: task identifier from the profile.
- `--output`: host destination for the agent result.
- `--input`: host document required by tasks declaring `required_input: document`.
- `--upload`: repeatable native OpenShell `SOURCE:DESTINATION` mapping.
- `--env`: repeatable non-secret `KEY=VALUE` sandbox environment value. Keys use
  shell identifier syntax; OpenShell reserves the `OPENSHELL_` prefix.
- `--gateway`: select an existing OpenShell gateway.
- `--workspace`: select a gateway-side OpenShell namespace. It defaults to
  `default` and is unrelated to the sandbox's `/workspace` directory.
- `--timeout-seconds`: maximum agent runtime.
- `--keep-sandbox`: retain the sandbox for deliberate debugging.
- `--dry-run`: print the complete command sequence and host actions without
  executing anything.

A source can be a file or directory. For native file uploads, the destination
is the exact filename; for directory uploads, it is the destination directory.
OAR does not add repository, snapshot, changed-file, or Git abstractions. The
first upload above uses OpenShell's default Git-aware filtering, while the
explicit `.git` upload provides repository history without also uploading every
ignored file. Review upload contents before sending private source to a remote
gateway. OAR always preserves OpenShell's Git-aware filtering; upload an ignored
file explicitly when a task genuinely needs it.

### Inspect the execution

Add `--dry-run` to the same `run` invocation:

```bash
uv run --project projects/openshell-agent-runner oar run \
  .github/openshell-agents/profiles/dev-note-reviewer \
  --task editorial \
  --gateway openshell \
  --upload .:/workspace/source \
  --upload .git:/workspace/source/.git \
  --env REVIEW_TARGET_PATH=docs/dev-notes/posts/2026-08-07-formal-methods-ai-generated-robot-actions.md \
  --output /tmp/dev-note-review.json \
  --dry-run
```

The preview prints the exact dynamically generated `openshell sandbox create`,
`download`, ownership `get`, and `delete` commands in execution order. It also
shows host-side result validation and atomic publication. Temporary paths,
sandbox identity, and the ownership token are generated exactly as they are for
a real run, but no subprocess or sandbox operation is executed.

## Profile format

A profile contains only settings that can change model behavior, sandbox
permissions, inputs, or task execution:

```yaml
id: reviewer
description: Review an uploaded document.

sandbox:
  policy: policy.yaml
  upload: []
  env: []

tasks:
  review:
    required_input: document
    prompt: prompt.md
    tools: [read, grep, find, ls, bash]
    skills: []
    extensions: []
```

Each profile directory must contain `profile.yaml`, `models.json`, and
`settings.json`. Profile-owned paths resolve relative to that directory. Native
upload sources retain OpenShell's current-directory semantics.

`models.json` is Pi's native provider and model registry. OAR requires exactly
one provider named `openshell` and exactly one model. `settings.json` is Pi's
native runtime selection and must set `defaultProvider`, `defaultModel`, and
`defaultThinkingLevel`. OAR copies both files unchanged and passes that same
selection explicitly as `--provider`, `--model`, and `--thinking`, so every task
uses one visible runtime configuration. Never place real credentials in these
files; OpenShell supplies inference access.

Profiles created by `oar init` use this minimal Pi model configuration:

```json
{
  "providers": {
    "openshell": {
      "baseUrl": "https://inference.local/v1",
      "api": "openai-completions",
      "apiKey": "unused",
      "authHeader": true,
      "compat": {
        "supportsDeveloperRole": false
      },
      "models": [
        {
          "id": "provider/model",
          "reasoning": true
        }
      ]
    }
  }
}
```

The matching runtime selection is:

```json
{
  "defaultProvider": "openshell",
  "defaultModel": "provider/model",
  "defaultThinkingLevel": "high"
}
```

Pi supplies conservative defaults for omitted model capabilities. `oar init`
sets `reasoning` from the selected thinking level and retains the compatibility
override required by the OpenAI-compatible route. Add explicit model behavior
to the initialized profile when the selected route needs it.

### Result protocol

By default, OAR captures Pi's final headless response and publishes it without
interpreting its contents. The result must exist, be non-empty, and fit within
the one-MiB transport limit. OAR applies that limit to the download process and
checks the downloaded file again before publication.

A task can optionally require structured JSON by referencing a JSON Schema:

```yaml
tasks:
  review:
    prompt: prompt.md
    output_schema: schemas/review.json
    tools: [read, grep, find, ls, bash]
```

OAR uploads the schema and automatically enables the generic `submit_result`
tool. Invalid submissions return schema diagnostics to Pi so it can correct and
resubmit within the same session. OAR validates the accepted JSON against the
same Draft 2020-12 schema again before publishing it. Pi's tool parameters use
TypeBox, as required by its extension API, while the submitted result is
validated with Ajv. The schema and its domain concepts belong entirely to the
profile; OAR has no built-in review result type. JSON Schema extension keywords
and `format` values are treated as annotations rather than additional validation
rules on both sides. OAR rejects `pattern` and `patternProperties` because Python
and JavaScript use different regular-expression dialects; use `enum`, `const`,
length, and numeric constraints for portable validation.

OAR fixes implementation details that do not change the intended result: Pi is
the harness, its image is bundled with the package, autonomous approval and
provider isolation are enabled, the result is written to a standard sandbox
path, and the result size guard is one MiB.

The package includes a repository-neutral `reviewer` profile. Run `oar init` to
create an editable local copy. Its `review` task requires `--input DOCUMENT` and
uploads that file to OAR's standard document location in the sandbox.

## Image contract

The runner packages the Pi image context, pins the tested Pi version, and
installs the read-only harness under `/opt/oar`. OAR passes that packaged
context to native `openshell sandbox create`; profiles do not select an image.
This keeps the harness implementation and image contract in one release unit.

## Security boundary

- Pi runs as the image's unprivileged user under the profile policy.
- Caller uploads under `/workspace` and generated resources under
  `/sandbox/oar-runtime` are writable because OpenShell performs uploads through
  the workload policy.
- `/sandbox/oar-runtime` and `/sandbox/artifacts` are reserved for the runner;
  profile and command-line uploads cannot write there.
- Source changes are disposable and are never synchronized back.
- Only OAR's standard result path is downloaded.
- Host-side transport checks, optional JSON Schema validation, and atomic
  publication are the result acceptance boundary.
- Result claims and provenance remain agent-produced; schema
  validation does not independently prove their factual accuracy.
- `--env` is for non-secret values. Credentials remain in OpenShell's provider
  and inference mechanisms.
- Cleanup checks a reserved ownership label before deleting the sandbox.

The supplied Dev Note policy permits no ordinary network egress. Inference uses
OpenShell's managed inference path.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Execution completed and the output validated. |
| `1` | OpenShell execution, timeout, missing remote output, download size limit, ownership inspection, or cleanup failed. |
| `2` | CLI input or profile configuration was invalid. |
| `3` | A downloaded output was empty, invalid, or failed its contract. |

## Development

Run from `projects/openshell-agent-runner`:

```bash
uv sync --locked
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest
uv build
```

The repository workflow validates the repository and starter profiles, runs the
credential-free suite, builds the distributions, verifies the wheel contents,
and builds the Pi image. Real inference requires an authenticated OpenShell
gateway and is intentionally not run on GitHub-hosted workers.
