openshell-agent-runner 0.0.1__py3-none-any.whl

openshell_agent_runner/config.py

@@ -0,0 +1,382 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Define, load, validate, and resolve agent profile configuration."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Sequence
+from pathlib import Path, PurePosixPath
+from typing import Annotated, Any, Literal
+
+import yaml
+from jsonschema import Draft202012Validator, SchemaError
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    ValidationError,
+    field_validator,
+)
+
+from openshell_agent_runner.errors import ConfigurationError
+
+IDENTIFIER_PATTERN = r"^[a-z][a-z0-9-]{0,62}$"
+RESOURCE_IDENTIFIER_PATTERN = r"^[a-z][a-z0-9_-]{0,62}$"
+MODEL_IDENTIFIER_PATTERN = r"^[A-Za-z0-9._:/-]{1,256}$"
+MODELS_FILENAME = "models.json"
+PROFILE_FILENAME = "profile.yaml"
+SETTINGS_FILENAME = "settings.json"
+_PI_RUNTIME_SETTING_KEYS = {
+    "defaultProvider",
+    "defaultModel",
+    "defaultThinkingLevel",
+}
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class SandboxConfig(StrictModel):
+    policy: Path
+    upload: list[str] = Field(default_factory=list)
+    env: list[str] = Field(default_factory=list)
+
+    @field_validator("upload")
+    @classmethod
+    def validate_uploads(cls, values: list[str]) -> list[str]:
+        validate_upload_mappings(values)
+        return values
+
+    @field_validator("env")
+    @classmethod
+    def validate_environment(cls, values: list[str]) -> list[str]:
+        validate_environment_assignments(values)
+        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
+    )
+    skills: list[Path] = Field(default_factory=list)
+    extensions: list[Path] = Field(default_factory=list)
+
+    @field_validator("tools", "skills", "extensions")
+    @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
+
+
+class ProfileConfig(StrictModel):
+    id: Annotated[str, Field(pattern=IDENTIFIER_PATTERN)]
+    description: str = Field(min_length=1, max_length=1000)
+    sandbox: SandboxConfig
+    tasks: dict[Annotated[str, Field(pattern=IDENTIFIER_PATTERN)], TaskConfig]
+
+    @field_validator("tasks")
+    @classmethod
+    def require_tasks(cls, value: dict[str, TaskConfig]) -> dict[str, TaskConfig]:
+        if not value:
+            raise ValueError("at least one task is required")
+        return value
+
+
+class PiRuntimeSettings(StrictModel):
+    provider: Literal["openshell"]
+    model: Annotated[str, Field(pattern=MODEL_IDENTIFIER_PATTERN)]
+    thinking: Literal["off", "minimal", "low", "medium", "high", "xhigh", "max"]
+
+
+class ResolvedProfile(StrictModel):
+    profile_path: Path
+    profile_dir: Path
+    profile: ProfileConfig
+    runtime: PiRuntimeSettings
+
+
+def load_profile(directory: Path) -> ResolvedProfile:
+    try:
+        profile_dir = directory.resolve(strict=True)
+    except OSError as error:
+        raise ConfigurationError(f"missing profile directory: {directory}") from error
+    if not profile_dir.is_dir():
+        raise ConfigurationError(
+            f"profile must be a directory containing {PROFILE_FILENAME}: {directory}"
+        )
+    candidate = profile_dir / PROFILE_FILENAME
+    try:
+        profile_path = candidate.resolve(strict=True)
+    except OSError as error:
+        raise ConfigurationError(
+            f"missing profile configuration: {candidate}"
+        ) from error
+    if not profile_path.is_relative_to(profile_dir) or not profile_path.is_file():
+        raise ConfigurationError(
+            f"profile configuration must be a file inside {profile_dir}: {candidate}"
+        )
+    try:
+        profile = ProfileConfig.model_validate(_load_yaml(profile_path))
+    except ValidationError as error:
+        raise ConfigurationError(f"invalid profile {profile_path}: {error}") from error
+    model_path = _inside(profile_dir, profile_dir / MODELS_FILENAME, "Pi models file")
+    settings_path = _inside(
+        profile_dir, profile_dir / SETTINGS_FILENAME, "Pi settings file"
+    )
+    model_id = _load_pi_model_id(model_path)
+    resolved = ResolvedProfile(
+        profile_path=profile_path,
+        profile_dir=profile_dir,
+        profile=profile,
+        runtime=_load_pi_runtime_settings(settings_path, model_id),
+    )
+    _validate_profile_resources(resolved)
+    return resolved
+
+
+def resolve_task(profile_directory: Path, task_id: str) -> ResolvedProfile:
+    resolved = load_profile(profile_directory)
+    if task_id not in resolved.profile.tasks:
+        raise ConfigurationError(
+            f"unknown task {task_id!r} for profile {resolved.profile.id!r}"
+        )
+    return resolved
+
+
+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("/"):
+            raise ValueError("uploads must use SOURCE:/ABSOLUTE/DESTINATION")
+        path = PurePosixPath(destination)
+        if destination.startswith("//") or str(path) != destination:
+            raise ValueError("upload destinations must use canonical absolute paths")
+        if ".." in path.parts:
+            raise ValueError("upload destinations must not contain '..'")
+        for reserved in (
+            PurePosixPath("/sandbox/artifacts"),
+            PurePosixPath("/sandbox/oar-runtime"),
+        ):
+            if path == reserved or path.is_relative_to(reserved):
+                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)
+
+
+def validate_environment_assignments(values: Sequence[str]) -> tuple[str, ...]:
+    if len(values) != len(set(values)):
+        raise ValueError("duplicate environment assignment")
+    assignments: dict[str, str] = {}
+    for value in values:
+        key, separator, assigned = value.partition("=")
+        if not separator or not assigned:
+            raise ValueError("environment must use non-empty KEY=VALUE syntax")
+        if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", key):
+            raise ValueError(f"invalid OpenShell environment name: {key!r}")
+        if key.startswith("OPENSHELL_"):
+            raise ValueError(
+                f"environment name uses reserved OPENSHELL_ prefix: {key!r}"
+            )
+        previous = assignments.get(key)
+        if previous is not None and previous != assigned:
+            raise ValueError(f"conflicting environment values for key {key!r}")
+        assignments[key] = assigned
+    return tuple(values)
+
+
+def _load_yaml(path: Path) -> Any:
+    try:
+        with path.open(encoding="utf-8") as stream:
+            return yaml.safe_load(stream)
+    except (OSError, UnicodeError) as error:
+        raise ConfigurationError(
+            f"cannot read configuration {path}: {error}"
+        ) from error
+    except yaml.YAMLError as error:
+        raise ConfigurationError(f"invalid YAML in {path}: {error}") from error
+
+
+def _load_pi_model_id(path: Path) -> str:
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise ConfigurationError(f"invalid Pi models file {path}: {error}") from error
+    providers = document.get("providers") if isinstance(document, dict) else None
+    if not isinstance(providers, dict) or set(providers) != {"openshell"}:
+        raise ConfigurationError(
+            "Pi models file must contain exactly one provider named 'openshell'"
+        )
+    provider = providers["openshell"]
+    models = provider.get("models") if isinstance(provider, dict) else None
+    if not isinstance(models, list) or len(models) != 1:
+        raise ConfigurationError(
+            "Pi models file must contain exactly one model under 'openshell'"
+        )
+    model = models[0]
+    model_id = model.get("id") if isinstance(model, dict) else None
+    if not isinstance(model_id, str) or not re.fullmatch(
+        MODEL_IDENTIFIER_PATTERN, model_id
+    ):
+        raise ConfigurationError("Pi model must have a valid string id")
+    return model_id
+
+
+def _load_pi_runtime_settings(path: Path, model_id: str) -> PiRuntimeSettings:
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise ConfigurationError(f"invalid Pi settings file {path}: {error}") from error
+    if not isinstance(document, dict):
+        raise ConfigurationError(f"Pi settings file must contain an object: {path}")
+    unexpected = set(document) - _PI_RUNTIME_SETTING_KEYS
+    missing = _PI_RUNTIME_SETTING_KEYS - set(document)
+    if unexpected or missing:
+        diagnostics = []
+        if missing:
+            diagnostics.append(f"missing {sorted(missing)}")
+        if unexpected:
+            diagnostics.append(f"unexpected {sorted(unexpected)}")
+        raise ConfigurationError(
+            f"Pi settings file must contain only runtime selection keys: "
+            f"{', '.join(diagnostics)}"
+        )
+    try:
+        runtime = PiRuntimeSettings.model_validate(
+            {
+                "provider": document.get("defaultProvider"),
+                "model": document.get("defaultModel"),
+                "thinking": document.get("defaultThinkingLevel"),
+            }
+        )
+    except ValidationError as error:
+        raise ConfigurationError(
+            f"invalid Pi runtime settings in {path}: {error}"
+        ) from error
+    if runtime.model != model_id:
+        raise ConfigurationError(
+            "Pi settings defaultModel must identify the model in models.json"
+        )
+    return runtime
+
+
+def _inside(
+    owner: Path, candidate: Path, description: str, *, directory: bool = False
+) -> Path:
+    try:
+        resolved = candidate.resolve(strict=True)
+    except OSError as error:
+        raise ConfigurationError(f"missing {description}: {candidate}") from error
+    owner_resolved = owner.resolve(strict=True)
+    if not resolved.is_relative_to(owner_resolved):
+        raise ConfigurationError(f"{description} escapes {owner_resolved}: {candidate}")
+    expected = "directory" if directory else "file"
+    if (directory and not resolved.is_dir()) or (
+        not directory and not resolved.is_file()
+    ):
+        raise ConfigurationError(f"{description} must be a {expected}: {candidate}")
+    return resolved
+
+
+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}")
+        if task.output_schema is not None:
+            schema = _inside(
+                directory,
+                directory / task.output_schema,
+                f"output schema for task {task_id}",
+            )
+            _validate_output_schema(schema)
+        for skill in task.skills:
+            skill_directory = _inside(
+                directory,
+                directory / skill,
+                f"skill for task {task_id}",
+                directory=True,
+            )
+            _inside(
+                skill_directory,
+                skill_directory / "SKILL.md",
+                f"SKILL.md for task {task_id}",
+            )
+            for descendant in skill_directory.rglob("*"):
+                if descendant.is_symlink():
+                    raise ConfigurationError(
+                        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}")
+
+
+def _validate_output_schema(path: Path) -> None:
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+        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)
+
+
+def _validate_schema_references(document: Any, path: Path) -> None:
+    if not isinstance(document, dict):
+        return
+
+    for key in {"pattern", "patternProperties"}:
+        if key in document:
+            raise ConfigurationError(
+                "output schemas do not support regular-expression keywords "
+                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("#")
+        ):
+            raise ConfigurationError(
+                f"output schema references must stay inside {path}: {document[key]!r}"
+            )
+
+    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)
+    for key in {"allOf", "anyOf", "oneOf", "prefixItems"}:
+        value = document.get(key)
+        if isinstance(value, list):
+            for schema in value:
+                _validate_schema_references(schema, path)
+    for key in {
+        "additionalProperties",
+        "contains",
+        "contentSchema",
+        "else",
+        "if",
+        "items",
+        "not",
+        "propertyNames",
+        "then",
+        "unevaluatedItems",
+        "unevaluatedProperties",
+    }:
+        _validate_schema_references(document.get(key), path)

openshell_agent_runner/errors.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Package-specific errors with stable CLI exit classifications."""
+
+
+class OarError(Exception):
+    """Base expected runner error."""
+
+
+class ConfigurationError(OarError):
+    """Invalid configuration or invocation (exit code 2)."""
+
+
+class ExecutionError(OarError):
+    """OpenShell or agent execution failure (exit code 1)."""
+
+
+class ArtifactError(OarError):
+    """Missing or invalid required artifact (exit code 3)."""

openshell_agent_runner/harnesses/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Bundled agent harnesses."""

openshell_agent_runner/harnesses/pi/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pi coding-agent harness."""

openshell_agent_runner/harnesses/pi/resources.py

@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Materialize the explicit native-upload runtime bundle for Pi."""
+
+import shutil
+import tempfile
+from importlib.resources import files
+from pathlib import Path
+
+from openshell_agent_runner.config import (
+    MODELS_FILENAME,
+    SETTINGS_FILENAME,
+    ResolvedProfile,
+)
+from openshell_agent_runner.harnesses.resources import PreparedResources
+
+SANDBOX_RUNTIME_ROOT = "/sandbox/oar-runtime"
+
+
+def image_directory() -> Path:
+    return Path(str(files("openshell_agent_runner.harnesses.pi") / "runtime" / "image"))
+
+
+def prepare_resources(resolved: ResolvedProfile, task_id: str) -> 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")
+    shutil.copy2(resolved.profile_dir / MODELS_FILENAME, runtime / MODELS_FILENAME)
+    shutil.copy2(resolved.profile_dir / SETTINGS_FILENAME, runtime / SETTINGS_FILENAME)
+    arguments = [
+        "--provider",
+        resolved.runtime.provider,
+        "--model",
+        resolved.runtime.model,
+        "--thinking",
+        resolved.runtime.thinking,
+    ]
+    tools = list(task.tools)
+    if task.output_schema is not None:
+        shutil.copy2(
+            resolved.profile_dir / task.output_schema, runtime / "output.schema.json"
+        )
+        submit_result = Path(
+            str(
+                files("openshell_agent_runner.harnesses.pi")
+                / "runtime"
+                / "extensions"
+                / "submit-result.ts"
+            )
+        )
+        shutil.copy2(submit_result, runtime / "extensions" / "oar-submit-result.ts")
+        tools.append("submit_result")
+        arguments.extend(
+            [
+                "--extension",
+                f"{SANDBOX_RUNTIME_ROOT}/extensions/oar-submit-result.ts",
+            ]
+        )
+    arguments.extend(["--tools", ",".join(tools)] if tools else ["--no-tools"])
+    for index, skill in enumerate(task.skills):
+        target = runtime / "skills" / f"{index:02d}-{skill.name}"
+        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)
+        arguments.extend(
+            ["--extension", f"{SANDBOX_RUNTIME_ROOT}/extensions/{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",
+    ]
+    if task.output_schema is not None:
+        uploads.append(
+            f"{runtime / 'output.schema.json'}:{SANDBOX_RUNTIME_ROOT}/output.schema.json"
+        )
+    uploads.extend(
+        f"{path}:{SANDBOX_RUNTIME_ROOT}/skills"
+        for path in sorted((runtime / "skills").iterdir())
+    )
+    uploads.extend(
+        f"{path}:{SANDBOX_RUNTIME_ROOT}/extensions/{path.name}"
+        for path in sorted((runtime / "extensions").iterdir())
+    )
+    return PreparedResources(temporary, tuple(uploads), tuple(arguments))

openshell_agent_runner/harnesses/pi/runtime/extensions/submit-result.ts

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import Ajv2020 from "ajv/dist/2020.js";
+import { Type } from "typebox";
+
+const runtimeRoot = process.env.OAR_RUNTIME_ROOT || "/sandbox/oar-runtime";
+const schema = JSON.parse(
+  readFileSync(`${runtimeRoot}/output.schema.json`, "utf8"),
+);
+// Match Python jsonschema's Draft 2020-12 behavior: extension keywords and
+// formats remain annotations, while standard structural keywords are enforced.
+const validate = new Ajv2020({
+  allErrors: true,
+  strict: false,
+  validateFormats: false,
+}).compile(schema);
+const parameters = Type.Object({ result: Type.Unsafe(schema) });
+const outputDirectory = "/sandbox/artifacts";
+const outputPath = `${outputDirectory}/result`;
+
+const submitResult = defineTool({
+  name: "submit_result",
+  label: "Submit Result",
+  description: "Validate and save the final task result.",
+  promptSnippet: "Submit the final result using the configured output schema",
+  promptGuidelines: [
+    "Call submit_result only when the task is complete.",
+    "Correct every validation error and call submit_result again if it is rejected.",
+    "Do not return the result as assistant text.",
+  ],
+  parameters,
+  async execute(_toolCallId, { result }) {
+    if (!validate(result)) {
+      const diagnostics = (validate.errors || [])
+        .slice(0, 12)
+        .map((error) => `${error.instancePath || "/"}: ${error.message || "invalid"}`)
+        .join("\n");
+      return {
+        content: [{ type: "text" as const, text: `Result rejected:\n${diagnostics}` }],
+        details: { accepted: false, diagnostics },
+        isError: true,
+      };
+    }
+
+    mkdirSync(outputDirectory, { recursive: true, mode: 0o700 });
+    const temporaryPath = `${outputPath}.tmp`;
+    writeFileSync(temporaryPath, `${JSON.stringify(result, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    renameSync(temporaryPath, outputPath);
+    return {
+      content: [{ type: "text" as const, text: "Result accepted." }],
+      details: { accepted: true, outputPath },
+      terminate: true,
+    };
+  },
+});
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(submitResult);
+}

openshell_agent_runner/harnesses/pi/runtime/image/Dockerfile

@@ -0,0 +1,28 @@
+FROM node:24-bookworm-slim@sha256:3638d9a6fe4030bd716be989438248074489337ba3275657f93595428be4fc03
+
+ARG PI_VERSION=0.84.2
+ARG AJV_VERSION=8.20.0
+ARG TYPEBOX_VERSION=1.3.16
+
+ENV NODE_PATH=/usr/local/lib/node_modules
+
+RUN apt-get update \
+    && apt-get install --yes --no-install-recommends ca-certificates git iproute2 python3 ripgrep \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm install --global --ignore-scripts \
+        "@earendil-works/pi-coding-agent@${PI_VERSION}" \
+        "ajv@${AJV_VERSION}" \
+        "typebox@${TYPEBOX_VERSION}" \
+    && npm cache clean --force >/dev/null 2>&1 \
+    && test "$(pi --version)" = "${PI_VERSION}"
+
+RUN mkdir -p /opt/oar/pi /sandbox/artifacts /sandbox/tmp /workspace \
+    && chown -R node:node /sandbox /workspace
+
+COPY exec.sh /opt/oar/pi/exec.sh
+RUN chmod 0755 /opt/oar/pi/exec.sh \
+    && chmod -R a+rX,a-w /opt/oar
+
+WORKDIR /sandbox
+USER node

openshell_agent_runner/harnesses/pi/runtime/image/exec.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+umask 077
+
+model_id=""
+arguments=("$@")
+for ((index = 0; index < ${#arguments[@]}; index++)); do
+  if [[ "${arguments[$index]}" == "--model" && $((index + 1)) -lt ${#arguments[@]} ]]; then
+    model_id="${arguments[$((index + 1))]}"
+    break
+  fi
+done
+if [[ ! "$model_id" =~ ^[A-Za-z0-9._:/-]{1,256}$ ]]; then
+  echo "Pi harness: --model is missing or invalid" >&2
+  exit 2
+fi
+
+payload=${OAR_RUNTIME_ROOT:-/sandbox/oar-runtime}
+for required in "$payload/prompt.md" "$payload/models.json" "$payload/settings.json"; do
+  if [[ ! -f "$required" ]]; then
+    echo "Pi harness: missing required file: $required" >&2
+    exit 2
+  fi
+done
+
+pi_home=/sandbox/pi-home
+mkdir -p "$pi_home/.pi/agent" /sandbox/artifacts /sandbox/tmp
+install -m 0600 "$payload/models.json" "$pi_home/.pi/agent/models.json"
+install -m 0600 "$payload/settings.json" "$pi_home/.pi/agent/settings.json"
+
+export HOME="$pi_home"
+export TMPDIR=/sandbox/tmp
+export PI_OFFLINE=1
+export PI_SKIP_VERSION_CHECK=1
+export PI_TELEMETRY=0
+export OAR_MODEL_ID="$model_id"
+
+agent_workdir=${REPOSITORY_ROOT:-/sandbox}
+if [[ ! -d "$agent_workdir" ]]; then
+  echo "Pi harness: REPOSITORY_ROOT is not a directory: $agent_workdir" >&2
+  exit 2
+fi
+cd "$agent_workdir"
+
+stdout_path=/sandbox/artifacts/result.stdout
+result_path=/sandbox/artifacts/result
+pi \
+  --print \
+  --no-session \
+  --no-extensions \
+  --no-skills \
+  --no-prompt-templates \
+  --no-themes \
+  --no-context-files \
+  --no-approve \
+  --offline \
+  "$@" \
+  <"$payload/prompt.md" \
+  >"$stdout_path"
+
+if [[ -s "$result_path" ]]; then
+  rm -f "$stdout_path"
+else
+  mv "$stdout_path" "$result_path"
+fi

openshell_agent_runner/harnesses/resources.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared resources prepared by an agent harness."""
+
+import tempfile
+from dataclasses import dataclass
+
+
+@dataclass
+class PreparedResources:
+    temporary: tempfile.TemporaryDirectory[str]
+    uploads: tuple[str, ...]
+    arguments: tuple[str, ...]
+
+    def close(self) -> None:
+        self.temporary.cleanup()