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

openshell_agent_runner-0.0.3/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: openshell-agent-runner
+Version: 0.0.3
+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) runs an agent task in an isolated OpenShell sandbox
+and saves the result to a file. Use it to review code, review technical writing,
+or run your own tasks from a terminal or CI job.
+
+```text
+Profile + input → OAR → Agent in a temporary sandbox → Result file
+                            sandbox removed when the run ends
+```
+
+A **profile** packages prompts, reusable skills, and settings. A **task** is one
+job in that profile; it selects the prompt and skills to use. OAR includes two
+ready-to-use reviewers:
+
+| Profile | Task | Input |
+| --- | --- | --- |
+| `code-reviewer` | `review-repository` | A local project directory |
+| `technical-writing-reviewer` | `review-document` | A text file, such as Markdown or `.txt` |
+
+## Get started
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/) and
+OpenShell 0.0.111 or newer, with a running gateway and configured inference.
+If OpenShell is not ready, follow its
+[quickstart](https://docs.nvidia.com/openshell/latest/get-started/quickstart).
+OAR uses that setup to create sandboxes and reach your model.
+
+**1. Install OAR and check your connection.**
+
+```bash
+uv tool install openshell-agent-runner
+oar doctor
+```
+
+Alternatively, use `uvx --from openshell-agent-runner oar` in place of `oar`.
+
+These commands use your selected OpenShell gateway and its `default` workspace.
+For another target, add `--gateway NAME --workspace NAME` to `doctor` and `run`.
+
+**2. Create your profiles.** Replace `YOUR_MODEL_ID` with the model ID shown in
+the inference output from `oar doctor`.
+
+```bash
+oar init ./profiles --model YOUR_MODEL_ID
+```
+
+This creates editable copies of both reviewers. For a model without reasoning
+support, add `--thinking off`.
+
+**3. Review a document.** Replace `./README.md` with an existing text file.
+
+```bash
+oar run ./profiles/technical-writing-reviewer \
+  --task review-document \
+  --input ./README.md \
+  --output ./review.json
+```
+
+Open `review.json` for the verdict, a score from 0 to 100, and specific findings.
+OAR saves the validated result and removes the sandbox. Add `--dry-run` to
+preview the operation without launching an agent.
+
+## Review code
+
+Pass a local project directory. Optional `focus` and `context` values help the
+reviewer understand what matters for this run:
+
+```bash
+oar run ./profiles/code-reviewer \
+  --task review-repository \
+  --input ./my-project \
+  --prompt-var focus="src/auth and tests/auth" \
+  --prompt-var context="A small internal tool; keep recommendations proportionate." \
+  --output ./code-review.json
+```
+
+The agent works on an uploaded copy. Changes in the sandbox stay there; only the
+result is downloaded. A `focus` value guides attention but does not limit which
+files are uploaded.
+
+## Learn more
+
+- [Get started](https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/): setup and your first review.
+- [Run reviews](https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/reviews/): inputs, focus, context, and scores.
+- [Customize profiles](https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/profiles/): prompts, variables, skills, and output formats.
+- [Command reference](https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/reference/): options, CI behavior, and troubleshooting.
+
+For help with a specific task:
+
+```bash
+oar run ./profiles/code-reviewer --task review-repository --help
+```
+
+## Develop OAR
+
+From `projects/openshell-agent-runner`, run:
+
+```bash
+make check
+make build
+```
+
+`make check` includes CLI workflows against a simulated OpenShell. With Docker,
+run `make test-runtime` to exercise the real Pi harness without external inference.
+For runtime changes, one live CI task checks input transfer, prompt variables,
+structured output, and sandbox cleanup. It does not grade reviewer opinions.
+
+Use `uv run --frozen oar` in this directory to run the checked-out code instead
+of the installed release. Run a focused test with
+`make test PYTEST_ARGS="tests/test_config.py"`. See
+[RELEASING.md](https://github.com/NVIDIA/OpenShell-Research/blob/main/projects/openshell-agent-runner/RELEASING.md)
+for publishing, and the
+[repository CI guide](https://github.com/NVIDIA/OpenShell-Research/blob/main/docs/development/ci.md)
+for automated project reviews and the live OAR smoke test.

openshell_agent_runner-0.0.3/README.md

@@ -0,0 +1,115 @@
+# OpenShell Agent Runner
+
+OpenShell Agent Runner (OAR) runs an agent task in an isolated OpenShell sandbox
+and saves the result to a file. Use it to review code, review technical writing,
+or run your own tasks from a terminal or CI job.
+
+```text
+Profile + input → OAR → Agent in a temporary sandbox → Result file
+                            sandbox removed when the run ends
+```
+
+A **profile** packages prompts, reusable skills, and settings. A **task** is one
+job in that profile; it selects the prompt and skills to use. OAR includes two
+ready-to-use reviewers:
+
+| Profile | Task | Input |
+| --- | --- | --- |
+| `code-reviewer` | `review-repository` | A local project directory |
+| `technical-writing-reviewer` | `review-document` | A text file, such as Markdown or `.txt` |
+
+## Get started
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/) and
+OpenShell 0.0.111 or newer, with a running gateway and configured inference.
+If OpenShell is not ready, follow its
+[quickstart](https://docs.nvidia.com/openshell/latest/get-started/quickstart).
+OAR uses that setup to create sandboxes and reach your model.
+
+**1. Install OAR and check your connection.**
+
+```bash
+uv tool install openshell-agent-runner
+oar doctor
+```
+
+Alternatively, use `uvx --from openshell-agent-runner oar` in place of `oar`.
+
+These commands use your selected OpenShell gateway and its `default` workspace.
+For another target, add `--gateway NAME --workspace NAME` to `doctor` and `run`.
+
+**2. Create your profiles.** Replace `YOUR_MODEL_ID` with the model ID shown in
+the inference output from `oar doctor`.
+
+```bash
+oar init ./profiles --model YOUR_MODEL_ID
+```
+
+This creates editable copies of both reviewers. For a model without reasoning
+support, add `--thinking off`.
+
+**3. Review a document.** Replace `./README.md` with an existing text file.
+
+```bash
+oar run ./profiles/technical-writing-reviewer \
+  --task review-document \
+  --input ./README.md \
+  --output ./review.json
+```
+
+Open `review.json` for the verdict, a score from 0 to 100, and specific findings.
+OAR saves the validated result and removes the sandbox. Add `--dry-run` to
+preview the operation without launching an agent.
+
+## Review code
+
+Pass a local project directory. Optional `focus` and `context` values help the
+reviewer understand what matters for this run:
+
+```bash
+oar run ./profiles/code-reviewer \
+  --task review-repository \
+  --input ./my-project \
+  --prompt-var focus="src/auth and tests/auth" \
+  --prompt-var context="A small internal tool; keep recommendations proportionate." \
+  --output ./code-review.json
+```
+
+The agent works on an uploaded copy. Changes in the sandbox stay there; only the
+result is downloaded. A `focus` value guides attention but does not limit which
+files are uploaded.
+
+## Learn more
+
+- [Get started](https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/): setup and your first review.
+- [Run reviews](https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/reviews/): inputs, focus, context, and scores.
+- [Customize profiles](https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/profiles/): prompts, variables, skills, and output formats.
+- [Command reference](https://nvidia.github.io/OpenShell-Research/documentation/openshell-agent-runner/reference/): options, CI behavior, and troubleshooting.
+
+For help with a specific task:
+
+```bash
+oar run ./profiles/code-reviewer --task review-repository --help
+```
+
+## Develop OAR
+
+From `projects/openshell-agent-runner`, run:
+
+```bash
+make check
+make build
+```
+
+`make check` includes CLI workflows against a simulated OpenShell. With Docker,
+run `make test-runtime` to exercise the real Pi harness without external inference.
+For runtime changes, one live CI task checks input transfer, prompt variables,
+structured output, and sandbox cleanup. It does not grade reviewer opinions.
+
+Use `uv run --frozen oar` in this directory to run the checked-out code instead
+of the installed release. Run a focused test with
+`make test PYTEST_ARGS="tests/test_config.py"`. See
+[RELEASING.md](https://github.com/NVIDIA/OpenShell-Research/blob/main/projects/openshell-agent-runner/RELEASING.md)
+for publishing, and the
+[repository CI guide](https://github.com/NVIDIA/OpenShell-Research/blob/main/docs/development/ci.md)
+for automated project reviews and the live OAR smoke test.

{openshell_agent_runner-0.0.2 → openshell_agent_runner-0.0.3}/src/openshell_agent_runner/cli.py

@@ -120,9 +120,16 @@ def run(
     output: Annotated[
         Path, typer.Option("--output", help="Host path for the agent result.")
     ],
-    input_document: Annotated[
+    input_path: Annotated[
         Path | None,
-        typer.Option("--input", help="Host document required by document tasks."),
+        typer.Option("--input", help="Host input required by the selected task."),
+    ] = None,
+    prompt_variable: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--prompt-var",
+            help="Non-secret NAME=VALUE prompt variable. Repeat for several.",
+        ),
     ] = None,
     upload: Annotated[
         list[str] | None,
@@ -159,7 +166,8 @@ def run(
         profile_directory=profile,
         task_id=task,
         output=output,
-        input_document=input_document,
+        input_path=input_path,
+        prompt_variables=prompt_variable or (),
         uploads=upload or (),
         environments=environment or (),
         gateway=gateway,
@@ -185,12 +193,17 @@ def doctor(
         str, typer.Option("--workspace", help="OpenShell workspace name.")
     ] = "default",
 ) -> None:
-    """Check OpenShell readiness without changing its state."""
+    """Inspect OpenShell connection and configuration without changing its state."""
     try:
         checks = run_doctor(NativeTarget(gateway=gateway, workspace=workspace))
     except OarError as error:
         _fail(error)
     typer.echo("\n\n".join(result for _, result in checks))
+    typer.echo(
+        "\nThese are configuration checks, not an inference request. "
+        "Before running a task, confirm that an inference provider and model "
+        "are listed above."
+    )
 
 
 def _fail(error: OarError) -> NoReturn:
@@ -227,8 +240,10 @@ def _render_task_help(
         _help_command(f"  oar run {shlex.quote(str(profile_directory))} \\"),
         _help_command(f"    --task {shlex.quote(task_id)} \\"),
     ]
-    if task.required_input == "document":
-        usage_lines.append(_help_command("    --input DOCUMENT \\"))
+    if task.required_input is not None:
+        usage_lines.append(
+            _help_command(f"    --input {task.required_input.upper()} \\")
+        )
     usage_lines.append(_help_command("    --output OUTPUT"))
 
     upload_lines = [_help_heading("Additional configured uploads:")]
@@ -244,6 +259,22 @@ def _render_task_help(
         environment_lines.append("  None. Add values with --env KEY=VALUE.")
 
     input_lines = _required_input_help(task.required_input)
+    prompt_variable_lines = [_help_heading("Prompt variables:")]
+    if task.prompt_variables:
+        for name, variable in task.prompt_variables.items():
+            requirement = (
+                f"Default: {variable.default}"
+                if variable.default is not None
+                else "Required."
+            )
+            prompt_variable_lines.extend(
+                [
+                    _help_command(f"  --prompt-var {name}=VALUE"),
+                    f"    {variable.description} {requirement}",
+                ]
+            )
+    else:
+        prompt_variable_lines.append("  None.")
 
     output_description = (
         f"JSON validated against {task.output_schema}."
@@ -260,6 +291,8 @@ def _render_task_help(
             "",
             *input_lines,
             "",
+            *prompt_variable_lines,
+            "",
             *upload_lines,
             "",
             *environment_lines,
@@ -274,10 +307,15 @@ def _render_task_help(
 def _required_input_help(required_input: str | None) -> list[str]:
     if required_input is None:
         return [_help_heading("Required input:"), "  None."]
+    description = (
+        "Host document to review."
+        if required_input == "document"
+        else "Host code repository to review."
+    )
     return [
         _help_heading("Required argument:"),
-        _help_command("  --input DOCUMENT"),
-        "    Host document to review.",
+        _help_command(f"  --input {required_input.upper()}"),
+        f"    {description}",
     ]
 
 

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

@@ -23,6 +23,11 @@ from pydantic import (
 )
 
 from openshell_agent_runner.errors import ConfigurationError
+from openshell_agent_runner.prompt_templates import (
+    BUILTIN_PROMPT_VARIABLES,
+    PROMPT_VARIABLE_NAME_PATTERN,
+    validate_prompt_template,
+)
 
 IDENTIFIER_PATTERN = r"^[a-z][a-z0-9-]{0,62}$"
 RESOURCE_IDENTIFIER_PATTERN = r"^[a-z][a-z0-9_-]{0,62}$"
@@ -62,6 +67,7 @@ class SandboxConfig(StrictModel):
 
 
 ToolName = Annotated[str, Field(pattern=RESOURCE_IDENTIFIER_PATTERN)]
+PromptVariableName = Annotated[str, Field(pattern=PROMPT_VARIABLE_NAME_PATTERN)]
 
 
 class ExtensionConfig(StrictModel):
@@ -76,10 +82,18 @@ class ExtensionConfig(StrictModel):
         return values
 
 
+class PromptVariableConfig(StrictModel):
+    description: str = Field(min_length=1, max_length=1000)
+    default: str | None = Field(default=None, min_length=1)
+
+
 class TaskConfig(StrictModel):
     description: str | None = Field(default=None, min_length=1, max_length=1000)
-    required_input: Literal["document"] | None = None
+    required_input: Literal["document", "repository"] | None = None
     prompt: Path
+    prompt_variables: dict[PromptVariableName, PromptVariableConfig] = Field(
+        default_factory=dict
+    )
     output_schema: Path | None = None
     tools: list[ToolName] = Field(default_factory=list)
     skills: list[Path] = Field(default_factory=list)
@@ -125,6 +139,11 @@ class TaskConfig(StrictModel):
                 f"{sorted(BUILTIN_PI_TOOLS)}; declare each custom tool under a "
                 "referenced extension"
             )
+        if self.skills and "read" not in self.tools:
+            raise ValueError(
+                "tasks with skills must include 'read' in tools so Pi can "
+                "discover and load the skills"
+            )
         return self
 
 
@@ -345,7 +364,23 @@ def _validate_profile_resources(resolved: ResolvedProfile) -> None:
     directory = resolved.profile_dir
     _inside(directory, directory / resolved.profile.sandbox.policy, "sandbox policy")
     for task_id, task in resolved.profile.tasks.items():
-        _inside(directory, directory / task.prompt, f"prompt for task {task_id}")
+        prompt = _inside(
+            directory, directory / task.prompt, f"prompt for task {task_id}"
+        )
+        available_builtins = (
+            BUILTIN_PROMPT_VARIABLES if task.required_input is not None else frozenset()
+        )
+        try:
+            template = prompt.read_text(encoding="utf-8")
+            validate_prompt_template(
+                template,
+                task.prompt_variables.keys(),
+                available_builtins,
+            )
+        except (OSError, UnicodeError, ValueError) as error:
+            raise ConfigurationError(
+                f"invalid prompt template for task {task_id}: {error}"
+            ) from error
         if task.output_schema is not None:
             schema = _inside(
                 directory,

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

@@ -6,6 +6,7 @@
 import json
 import shutil
 import tempfile
+from collections.abc import Mapping
 from importlib.resources import files
 from pathlib import Path
 
@@ -15,6 +16,7 @@ from openshell_agent_runner.config import (
     ResolvedProfile,
 )
 from openshell_agent_runner.harnesses.resources import PreparedResources
+from openshell_agent_runner.prompt_templates import render_prompt_template
 
 SANDBOX_RUNTIME_ROOT = "/sandbox/oar-runtime"
 
@@ -23,13 +25,19 @@ def image_directory() -> Path:
     return Path(str(files("openshell_agent_runner.harnesses.pi") / "runtime" / "image"))
 
 
-def prepare_resources(resolved: ResolvedProfile, task_id: str) -> PreparedResources:
+def prepare_resources(
+    resolved: ResolvedProfile,
+    task_id: str,
+    prompt_variables: Mapping[str, str] | None = None,
+) -> PreparedResources:
     temporary = tempfile.TemporaryDirectory(prefix="oar-pi-")
     runtime = Path(temporary.name) / "runtime"
     (runtime / "skills").mkdir(parents=True, exist_ok=True)
     (runtime / "extensions").mkdir(parents=True, exist_ok=True)
     task = resolved.profile.tasks[task_id]
-    shutil.copy2(resolved.profile_dir / task.prompt, runtime / "prompt.md")
+    template = (resolved.profile_dir / task.prompt).read_text(encoding="utf-8")
+    rendered_prompt = render_prompt_template(template, prompt_variables or {})
+    (runtime / "prompt.md").write_text(rendered_prompt, encoding="utf-8")
     shutil.copy2(resolved.profile_dir / MODELS_FILENAME, runtime / MODELS_FILENAME)
     shutil.copy2(resolved.profile_dir / SETTINGS_FILENAME, runtime / SETTINGS_FILENAME)
     arguments = [

{openshell_agent_runner-0.0.2 → openshell_agent_runner-0.0.3}/src/openshell_agent_runner/harnesses/pi/runtime/extensions/validate-tools.ts

@@ -19,10 +19,10 @@ export function findMissingTools(
 }
 
 export default function (pi: ExtensionAPI) {
-  pi.on("before_agent_start", (_event, context) => {
-    const availableTools = context.getAllTools();
+  pi.on("before_agent_start", () => {
+    const availableTools = pi.getAllTools();
     const missingTools = findMissingTools(requestedTools, availableTools);
-    const activeTools = context.getActiveTools();
+    const activeTools = pi.getActiveTools();
     const activeNames = new Set(activeTools);
     const inactiveTools = requestedTools.filter((name) => !activeNames.has(name));
     const unavailableTools = [...new Set([...missingTools, ...inactiveTools])];

{openshell_agent_runner-0.0.2 → openshell_agent_runner-0.0.3}/src/openshell_agent_runner/harnesses/pi/runtime/image/exec.sh

@@ -25,6 +25,7 @@ for required in "$payload/prompt.md" "$payload/models.json" "$payload/settings.j
     exit 2
   fi
 done
+ln -s /usr/local/lib/node_modules "$payload/node_modules"
 
 pi_home=/sandbox/pi-home
 mkdir -p "$pi_home/.pi/agent" /sandbox/artifacts /sandbox/tmp

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

@@ -131,6 +131,8 @@ def run(
             command,
             check=True,
             text=True,
+            # Native commands are noninteractive; do not drain a caller's task list.
+            stdin=subprocess.DEVNULL,
             capture_output=capture,
             timeout=timeout,
             preexec_fn=(

{openshell_agent_runner-0.0.2 → openshell_agent_runner-0.0.3}/src/openshell_agent_runner/profile_init.py

@@ -17,7 +17,7 @@ from pathlib import Path
 from openshell_agent_runner.config import MODEL_IDENTIFIER_PATTERN, load_profile
 from openshell_agent_runner.errors import ConfigurationError
 
-PACKAGED_PROFILES = ("reviewer",)
+PACKAGED_PROFILES = ("code-reviewer", "technical-writing-reviewer")
 
 
 class ThinkingLevel(StrEnum):

openshell_agent_runner-0.0.3/src/openshell_agent_runner/profiles/code-reviewer/profile.yaml

@@ -0,0 +1,21 @@
+id: code-reviewer
+description: Review an input code repository for concrete engineering issues.
+
+sandbox:
+  policy: policy.yaml
+
+tasks:
+  review-repository:
+    description: Review an input code repository and return a structured result.
+    required_input: repository
+    prompt: prompt-repository.md
+    prompt_variables:
+      focus:
+        description: Files, directories, behavior, or risks that deserve special attention.
+        default: Review the complete repository.
+      context:
+        description: Intent, constraints, non-goals, or maturity that should calibrate the review.
+        default: No additional context was provided.
+    output_schema: schemas/review.json
+    tools: [read, grep, find, ls, bash]
+    skills: [skills/review-code]

openshell_agent_runner-0.0.3/src/openshell_agent_runner/profiles/code-reviewer/prompt-repository.md

@@ -0,0 +1,15 @@
+# Review the input code repository
+
+Work as a code review agent. Load and follow the `review-code` skill.
+
+Review the repository at `{{ oar.input_path }}`, originally provided as
+`{{ oar.input_name }}`.
+
+Review focus: {{ focus }}
+
+Additional context: {{ context }}
+
+Treat the focus as a priority, not permission to ignore directly related code.
+Review the repository as it exists; do not assume it represents a pull request
+or has useful Git history. Do not edit source files. Finish only by submitting a
+result that satisfies the configured output schema.