openshell-agent-runner 0.0.1__tar.gz → 0.0.2__tar.gz

openshell_agent_runner-0.0.2/PKG-INFO

@@ -0,0 +1,164 @@
+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.

openshell_agent_runner-0.0.2/README.md

@@ -0,0 +1,141 @@
+# 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.

{openshell_agent_runner-0.0.1 → openshell_agent_runner-0.0.2}/pyproject.toml

@@ -31,7 +31,7 @@ openshell-agent-runner = "openshell_agent_runner.cli:app"
 
 [project.urls]
 Repository = "https://github.com/NVIDIA/OpenShell-Research"
-Documentation = "https://github.com/NVIDIA/OpenShell-Research/blob/main/projects/openshell-agent-runner/docs/index.md"
+Documentation = "https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/"
 
 [dependency-groups]
 dev = [
@@ -51,6 +51,7 @@ source = "uv-dynamic-versioning"
 [tool.uv-dynamic-versioning]
 vcs = "git"
 style = "pep440"
+pattern-prefix = "oar-"
 bump = true
 
 [tool.hatch.build.targets.wheel]

{openshell_agent_runner-0.0.1 → openshell_agent_runner-0.0.2}/src/openshell_agent_runner/config.py

@@ -19,6 +19,7 @@ from pydantic import (
     Field,
     ValidationError,
     field_validator,
+    model_validator,
 )
 
 from openshell_agent_runner.errors import ConfigurationError
@@ -29,6 +30,8 @@ MODEL_IDENTIFIER_PATTERN = r"^[A-Za-z0-9._:/-]{1,256}$"
 MODELS_FILENAME = "models.json"
 PROFILE_FILENAME = "profile.yaml"
 SETTINGS_FILENAME = "settings.json"
+BUILTIN_PI_TOOLS = frozenset({"bash", "edit", "find", "grep", "ls", "read", "write"})
+SUBMIT_RESULT_TOOL = "submit_result"
 _PI_RUNTIME_SETTING_KEYS = {
     "defaultProvider",
     "defaultModel",
@@ -58,24 +61,72 @@ class SandboxConfig(StrictModel):
         return values
 
 
+ToolName = Annotated[str, Field(pattern=RESOURCE_IDENTIFIER_PATTERN)]
+
+
+class ExtensionConfig(StrictModel):
+    path: Path
+    tools: list[ToolName] = Field(default_factory=list)
+
+    @field_validator("tools")
+    @classmethod
+    def require_unique_tools(cls, values: list[str]) -> list[str]:
+        if len(values) != len(set(values)):
+            raise ValueError("extension tool entries must be unique")
+        return values
+
+
 class TaskConfig(StrictModel):
     description: str | None = Field(default=None, min_length=1, max_length=1000)
     required_input: Literal["document"] | None = None
     prompt: Path
     output_schema: Path | None = None
-    tools: list[Annotated[str, Field(pattern=RESOURCE_IDENTIFIER_PATTERN)]] = Field(
-        default_factory=list
-    )
+    tools: list[ToolName] = Field(default_factory=list)
     skills: list[Path] = Field(default_factory=list)
-    extensions: list[Path] = Field(default_factory=list)
+    extensions: list[ExtensionConfig] = Field(default_factory=list)
 
-    @field_validator("tools", "skills", "extensions")
+    @field_validator("tools", "skills")
     @classmethod
     def require_unique_resources(cls, values: list[object]) -> list[object]:
         if len(values) != len(set(values)):
             raise ValueError("resource entries must be unique")
         return values
 
+    @field_validator("extensions")
+    @classmethod
+    def require_unique_extensions(
+        cls, values: list[ExtensionConfig]
+    ) -> list[ExtensionConfig]:
+        paths = [extension.path for extension in values]
+        if len(paths) != len(set(paths)):
+            raise ValueError("extension paths must be unique")
+        return values
+
+    @model_validator(mode="after")
+    def require_known_tools(self) -> TaskConfig:
+        declared_custom_tools: set[str] = set()
+        for extension in self.extensions:
+            for tool in extension.tools:
+                if tool in BUILTIN_PI_TOOLS or tool == SUBMIT_RESULT_TOOL:
+                    raise ValueError(
+                        f"extension tool {tool!r} conflicts with a reserved tool"
+                    )
+                if tool in declared_custom_tools:
+                    raise ValueError(
+                        f"custom tool {tool!r} is declared by multiple extensions"
+                    )
+                declared_custom_tools.add(tool)
+
+        available_tools = BUILTIN_PI_TOOLS | declared_custom_tools
+        unknown_tools = sorted(set(self.tools) - available_tools)
+        if unknown_tools:
+            raise ValueError(
+                f"unknown tools {unknown_tools}; Pi built-ins are "
+                f"{sorted(BUILTIN_PI_TOOLS)}; declare each custom tool under a "
+                "referenced extension"
+            )
+        return self
+
 
 class ProfileConfig(StrictModel):
     id: Annotated[str, Field(pattern=IDENTIFIER_PATTERN)]
@@ -155,7 +206,6 @@ def resolve_task(profile_directory: Path, task_id: str) -> ResolvedProfile:
 def validate_upload_mappings(values: Sequence[str]) -> tuple[str, ...]:
     if len(values) != len(set(values)):
         raise ValueError("duplicate upload mapping")
-    destinations: dict[str, str] = {}
     for value in values:
         source, separator, destination = value.rpartition(":")
         if not separator or not source or not destination.startswith("/"):
@@ -169,16 +219,11 @@ def validate_upload_mappings(values: Sequence[str]) -> tuple[str, ...]:
             PurePosixPath("/sandbox/artifacts"),
             PurePosixPath("/sandbox/oar-runtime"),
         ):
-            if path == reserved or path.is_relative_to(reserved):
+            if path.is_relative_to(reserved) or reserved.is_relative_to(path):
                 raise ValueError(
                     "upload destination is reserved for runner resources: "
                     f"{destination}"
                 )
-        normalized = str(path)
-        previous = destinations.get(normalized)
-        if previous is not None and previous != source:
-            raise ValueError(f"conflicting upload destination: {destination}")
-        destinations[normalized] = source
     return tuple(values)
 
 
@@ -326,7 +371,11 @@ def _validate_profile_resources(resolved: ResolvedProfile) -> None:
                         f"skill for task {task_id} contains a symlink: {descendant}"
                     )
         for extension in task.extensions:
-            _inside(directory, directory / extension, f"extension for task {task_id}")
+            _inside(
+                directory,
+                directory / extension.path,
+                f"extension for task {task_id}",
+            )
 
 
 def _validate_output_schema(path: Path) -> None:
@@ -335,10 +384,10 @@ def _validate_output_schema(path: Path) -> None:
         Draft202012Validator.check_schema(document)
     except (OSError, UnicodeError, json.JSONDecodeError, SchemaError) as error:
         raise ConfigurationError(f"invalid output schema {path}: {error}") from error
-    _validate_schema_references(document, path)
+    _validate_schema_references(document)
 
 
-def _validate_schema_references(document: Any, path: Path) -> None:
+def _validate_schema_references(document: Any) -> None:
     if not isinstance(document, dict):
         return
 
@@ -349,23 +398,22 @@ def _validate_schema_references(document: Any, path: Path) -> None:
                 f"({key}) because host and sandbox engines use different dialects"
             )
     for key in {"$ref", "$dynamicRef", "$recursiveRef"}:
-        if key in document and (
-            not isinstance(document[key], str) or not document[key].startswith("#")
-        ):
+        if key in document:
             raise ConfigurationError(
-                f"output schema references must stay inside {path}: {document[key]!r}"
+                "output schemas do not support reference keywords "
+                f"({key}) because the submission tool nests the schema"
             )
 
     for key in {"$defs", "definitions", "properties", "dependentSchemas"}:
         value = document.get(key)
         if isinstance(value, dict):
             for schema in value.values():
-                _validate_schema_references(schema, path)
+                _validate_schema_references(schema)
     for key in {"allOf", "anyOf", "oneOf", "prefixItems"}:
         value = document.get(key)
         if isinstance(value, list):
             for schema in value:
-                _validate_schema_references(schema, path)
+                _validate_schema_references(schema)
     for key in {
         "additionalProperties",
         "contains",
@@ -379,4 +427,4 @@ def _validate_schema_references(document: Any, path: Path) -> None:
         "unevaluatedItems",
         "unevaluatedProperties",
     }:
-        _validate_schema_references(document.get(key), path)
+        _validate_schema_references(document.get(key))

{openshell_agent_runner-0.0.1 → openshell_agent_runner-0.0.2}/src/openshell_agent_runner/harnesses/pi/resources.py

@@ -3,6 +3,7 @@
 
 """Materialize the explicit native-upload runtime bundle for Pi."""
 
+import json
 import shutil
 import tempfile
 from importlib.resources import files
@@ -66,15 +67,34 @@ def prepare_resources(resolved: ResolvedProfile, task_id: str) -> PreparedResour
         shutil.copytree(resolved.profile_dir / skill, target)
         arguments.extend(["--skill", f"{SANDBOX_RUNTIME_ROOT}/skills/{target.name}"])
     for index, extension in enumerate(task.extensions):
-        target = runtime / "extensions" / f"{index:02d}-{extension.name}"
-        shutil.copy2(resolved.profile_dir / extension, target)
+        target = runtime / "extensions" / f"{index:02d}-{extension.path.name}"
+        shutil.copy2(resolved.profile_dir / extension.path, target)
         arguments.extend(
             ["--extension", f"{SANDBOX_RUNTIME_ROOT}/extensions/{target.name}"]
         )
+    expected_tools = runtime / "tools.json"
+    expected_tools.write_text(f"{json.dumps(tools)}\n", encoding="utf-8")
+    validate_tools = Path(
+        str(
+            files("openshell_agent_runner.harnesses.pi")
+            / "runtime"
+            / "extensions"
+            / "validate-tools.ts"
+        )
+    )
+    validator_target = runtime / "extensions" / "oar-validate-tools.ts"
+    shutil.copy2(validate_tools, validator_target)
+    arguments.extend(
+        [
+            "--extension",
+            f"{SANDBOX_RUNTIME_ROOT}/extensions/{validator_target.name}",
+        ]
+    )
     uploads = [
         f"{runtime / 'prompt.md'}:{SANDBOX_RUNTIME_ROOT}/prompt.md",
         f"{runtime / 'models.json'}:{SANDBOX_RUNTIME_ROOT}/models.json",
         f"{runtime / 'settings.json'}:{SANDBOX_RUNTIME_ROOT}/settings.json",
+        f"{expected_tools}:{SANDBOX_RUNTIME_ROOT}/tools.json",
     ]
     if task.output_schema is not None:
         uploads.append(

openshell_agent_runner-0.0.2/src/openshell_agent_runner/harnesses/pi/runtime/extensions/validate-tools.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { readFileSync } from "node:fs";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const runtimeRoot = process.env.OAR_RUNTIME_ROOT || "/sandbox/oar-runtime";
+const requestedTools = JSON.parse(
+  readFileSync(`${runtimeRoot}/tools.json`, "utf8"),
+) as string[];
+
+export function findMissingTools(
+  requested: string[],
+  available: Array<{ name: string }>,
+): string[] {
+  const availableNames = new Set(available.map((tool) => tool.name));
+  return requested.filter((name) => !availableNames.has(name));
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_agent_start", (_event, context) => {
+    const availableTools = context.getAllTools();
+    const missingTools = findMissingTools(requestedTools, availableTools);
+    const activeTools = context.getActiveTools();
+    const activeNames = new Set(activeTools);
+    const inactiveTools = requestedTools.filter((name) => !activeNames.has(name));
+    const unavailableTools = [...new Set([...missingTools, ...inactiveTools])];
+    if (unavailableTools.length === 0) return;
+
+    const availableNames = availableTools
+      .map((tool) => tool.name)
+      .sort()
+      .join(", ");
+    process.stderr.write(
+      `OAR tool validation failed: unavailable tools: ${unavailableTools.join(", ")}. ` +
+        `Registered tools: ${availableNames || "none"}. ` +
+        `Active tools: ${activeTools.sort().join(", ") || "none"}.\n`,
+    );
+    process.exit(2);
+  });
+}

{openshell_agent_runner-0.0.1 → openshell_agent_runner-0.0.2}/src/openshell_agent_runner/openshell.py

@@ -43,18 +43,48 @@ class NativeTarget:
 
 def sandbox_create(
     resolved: ResolvedRun,
-    resources: PreparedResources,
     name: str,
     token: str,
 ) -> list[str]:
     command = [*resolved.create_command, "--name", name]
-    for upload in resources.uploads:
-        command.extend(["--upload", upload])
     command.extend(["--label", f"{RESERVED_LABEL}={token}"])
-    command.extend(["--", "bash", "/opt/oar/pi/exec.sh", *resources.arguments])
+    command.extend(["--detach", "--", "sleep", "infinity"])
     return command
 
 
+def sandbox_upload(request: RunRequest, name: str, mapping: str) -> list[str]:
+    source, _, destination = mapping.rpartition(":")
+    return [
+        request.openshell_bin,
+        "sandbox",
+        "upload",
+        name,
+        source,
+        destination,
+        *_native_target_args(request),
+    ]
+
+
+def sandbox_exec(
+    resolved: ResolvedRun,
+    resources: PreparedResources,
+    name: str,
+) -> list[str]:
+    return [
+        resolved.request.openshell_bin,
+        "sandbox",
+        "exec",
+        "--name",
+        name,
+        "--no-tty",
+        *_native_target_args(resolved.request),
+        "--",
+        "bash",
+        "/opt/oar/pi/exec.sh",
+        *resources.arguments,
+    ]
+
+
 def sandbox_download(resolved: ResolvedRun, name: str, destination: Path) -> list[str]:
     return [
         resolved.request.openshell_bin,