Metadata-Version: 2.5
Name: openshell-agent-runner
Version: 0.0.2
Summary: Launch ephemeral agents for single tasks in OpenShell sandboxes.
Project-URL: Repository, https://github.com/NVIDIA/OpenShell-Research
Project-URL: Documentation, https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/
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 (OAR) launches one ephemeral agent for one configured
task. Each `oar run` creates an isolated OpenShell sandbox, runs Pi with the
selected profile, publishes one result, and removes the sandbox. This bounded
lifecycle works well in CI jobs and other automated workflows.

OAR uses an existing OpenShell gateway, workspace, and inference route. It does
not create or change providers, credentials, gateways, workspaces, or routes.

## Requirements

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

## Quick start

Create the profiles packaged with OAR. `MODEL_ID` is an ordinary shell variable;
replace its value with the model ID configured on your inference route.

```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
```

Validate the included reviewer profile and preview its task:

```bash
printf '# Review me\n\nA short document.\n' > document.md
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 /tmp/oar-review.md \
  --dry-run
```

Replace `openshell` with your gateway name. Remove `--dry-run` to launch the
agent and write its result to `/tmp/oar-review.md`.

`oar init` copies the packaged profiles into an ordinary directory so you can
inspect, edit, and commit them. Omit `--profile` to create all packaged profiles,
or repeat `--profile NAME` to select a subset.

## Profiles

A profile contains `profile.yaml`, Pi's `models.json` and `settings.json`, an
OpenShell policy, and the prompts or other files referenced by its tasks. The
profile owns stable behavior and permissions; the CLI supplies values that vary
for each run, such as the task, inputs, output path, gateway, and workspace.

```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: []
```

`tools` is a strict allowlist. OAR recognizes Pi's built-in `bash`, `edit`,
`find`, `grep`, `ls`, `read`, and `write` tools. Custom tools must be declared by
an extension used by the same task:

```yaml
tasks:
  check:
    prompt: prompts/check.md
    tools: [read, custom_check]
    extensions:
      - path: extensions/custom-check.ts
        tools: [custom_check]
```

`oar validate` rejects unknown fields, missing or escaping resources, invalid
schemas, and tools that are not built in or declared by a referenced extension.
The runtime also verifies that Pi actually registered every selected tool before
the first model request.

Add `output_schema` to a task when its result must be JSON. OAR exposes the
built-in Pi `submit_result` extension for that task, lets Pi correct invalid
submissions during the session, and validates the downloaded result against the
same Draft 2020-12 schema before publishing it.

## 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]
```

- `init` creates editable copies of profiles packaged with OAR.
- `validate` checks a profile and all of its local resources without running it.
- `doctor` performs read-only OpenShell gateway and inference checks.
- `run` launches a task, or prints its resolved operations with `--dry-run`.

Run `oar COMMAND --help` for command options. For task-specific help, select the
profile and task before `--help`:

```bash
uvx --from openshell-agent-runner oar run \
  ./profiles/reviewer --task review --help
```

## Documentation

The [OAR guide](https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/)
explains profile inputs, tools and extensions, uploads, the run lifecycle,
structured results, security boundaries, and exit codes.

## Development

From `projects/openshell-agent-runner`:

```bash
make check
make build
```

Run a focused test with `make test PYTEST_ARGS="tests/test_config.py"`. Use
`make clean` to remove generated build and cache files. See
[RELEASING.md](https://github.com/NVIDIA/OpenShell-Research/blob/main/projects/openshell-agent-runner/RELEASING.md)
for the local PyPI release process.
