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

openshell_agent_runner/openshell.py

@@ -0,0 +1,162 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Build, execute, and inspect native OpenShell commands."""
+
+from __future__ import annotations
+
+import re
+import resource
+import shlex
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from functools import partial
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from openshell_agent_runner.artifacts import ARTIFACT_PATH
+from openshell_agent_runner.errors import ExecutionError
+
+if TYPE_CHECKING:
+    from openshell_agent_runner.harnesses.resources import PreparedResources
+    from openshell_agent_runner.runner import ResolvedRun, RunRequest
+
+MINIMUM_OPEN_SHELL_VERSION = (0, 0, 111)
+RESERVED_LABEL = "oar-run-id"
+VERSION_PATTERN = re.compile(r"\b(\d+)\.(\d+)\.(\d+)\b")
+
+
+@dataclass(frozen=True)
+class NativeTarget:
+    executable: str = "openshell"
+    gateway: str | None = None
+    workspace: str = "default"
+
+    def global_args(self) -> list[str]:
+        values: list[str] = []
+        if self.gateway:
+            values.extend(["--gateway", self.gateway])
+        values.extend(["--workspace", self.workspace])
+        return values
+
+
+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])
+    return command
+
+
+def sandbox_download(resolved: ResolvedRun, name: str, destination: Path) -> list[str]:
+    return [
+        resolved.request.openshell_bin,
+        "sandbox",
+        "download",
+        name,
+        ARTIFACT_PATH,
+        str(destination),
+        *_native_target_args(resolved.request),
+    ]
+
+
+def sandbox_get(request: RunRequest, name: str) -> list[str]:
+    return [
+        request.openshell_bin,
+        "sandbox",
+        "get",
+        name,
+        *_native_target_args(request),
+        "--output",
+        "json",
+    ]
+
+
+def sandbox_delete(request: RunRequest, name: str) -> list[str]:
+    return [
+        request.openshell_bin,
+        "sandbox",
+        "delete",
+        name,
+        *_native_target_args(request),
+    ]
+
+
+def run(
+    command: list[str],
+    timeout: int,
+    *,
+    capture: bool = False,
+    max_file_bytes: int | None = None,
+) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(
+            command,
+            check=True,
+            text=True,
+            capture_output=capture,
+            timeout=timeout,
+            preexec_fn=(
+                partial(_set_file_size_limit, max_file_bytes)
+                if max_file_bytes is not None
+                else None
+            ),
+        )
+    except (OSError, subprocess.CalledProcessError, subprocess.TimeoutExpired) as error:
+        raise ExecutionError(
+            f"command failed: {shlex.join(command)}: {error}"
+        ) from error
+
+
+def _set_file_size_limit(max_file_bytes: int) -> None:
+    resource.setrlimit(resource.RLIMIT_FSIZE, (max_file_bytes, max_file_bytes))
+
+
+def doctor(target: NativeTarget) -> list[tuple[str, str]]:
+    checks = []
+    for name, arguments in (
+        ("version", ["--version"]),
+        ("status", ["status"]),
+        ("inference", ["inference", "get"]),
+    ):
+        completed = _run_read_only(target, arguments)
+        result = completed.stdout.strip()
+        if name == "version":
+            match = VERSION_PATTERN.search(result)
+            if match is None:
+                raise ExecutionError(f"cannot parse OpenShell version: {result!r}")
+            version = tuple(int(part) for part in match.groups())
+            if version < MINIMUM_OPEN_SHELL_VERSION:
+                minimum = ".".join(str(part) for part in MINIMUM_OPEN_SHELL_VERSION)
+                raise ExecutionError(
+                    f"OpenShell {minimum} or newer is required; found {match.group(0)}"
+                )
+        checks.append((name, result))
+    return checks
+
+
+def _native_target_args(request: RunRequest) -> list[str]:
+    result: list[str] = []
+    if request.gateway:
+        result.extend(["--gateway", request.gateway])
+    result.extend(["--workspace", request.workspace])
+    return result
+
+
+def _run_read_only(
+    target: NativeTarget, arguments: Sequence[str]
+) -> subprocess.CompletedProcess[str]:
+    command = [target.executable, *arguments, *target.global_args()]
+    try:
+        return subprocess.run(command, check=True, text=True, capture_output=True)
+    except (OSError, subprocess.CalledProcessError) as error:
+        raise ExecutionError(
+            f"OpenShell check failed: {shlex.join(command)}: {error}"
+        ) from error

openshell_agent_runner/profile_init.py

@@ -0,0 +1,104 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Create editable profiles from resources packaged with OAR."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import tempfile
+from collections.abc import Sequence
+from enum import StrEnum
+from importlib.resources import as_file, files
+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",)
+
+
+class ThinkingLevel(StrEnum):
+    OFF = "off"
+    MINIMAL = "minimal"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    XHIGH = "xhigh"
+    MAX = "max"
+
+
+def initialize_profiles(
+    destination: Path,
+    profile_names: Sequence[str],
+    model_id: str,
+    thinking: ThinkingLevel,
+) -> tuple[Path, ...]:
+    """Create selected packaged profiles under destination."""
+    if not re.fullmatch(MODEL_IDENTIFIER_PATTERN, model_id):
+        raise ConfigurationError("--model must be a valid model identifier")
+
+    selected = tuple(profile_names) or PACKAGED_PROFILES
+    if len(selected) != len(set(selected)):
+        raise ConfigurationError("--profile values must be unique")
+    unknown = sorted(set(selected) - set(PACKAGED_PROFILES))
+    if unknown:
+        available = ", ".join(PACKAGED_PROFILES)
+        raise ConfigurationError(
+            f"unknown packaged profile {unknown[0]!r}; available profiles: {available}"
+        )
+
+    try:
+        destination.mkdir(parents=True, exist_ok=True)
+    except OSError as error:
+        raise ConfigurationError(
+            f"cannot create profile directory {destination}: {error}"
+        ) from error
+    if not destination.is_dir():
+        raise ConfigurationError(
+            f"profile destination is not a directory: {destination}"
+        )
+
+    targets = tuple(destination / name for name in selected)
+    collisions = [path for path in targets if path.exists() or path.is_symlink()]
+    if collisions:
+        raise ConfigurationError(f"profile destination already exists: {collisions[0]}")
+
+    try:
+        with tempfile.TemporaryDirectory(
+            prefix=".oar-init-", dir=destination
+        ) as staging:
+            staging_root = Path(staging)
+            with as_file(files("openshell_agent_runner.profiles")) as source_root:
+                staged_profiles = []
+                for name in selected:
+                    staged = staging_root / name
+                    shutil.copytree(source_root / name, staged)
+                    _configure_runtime(staged, model_id, thinking)
+                    load_profile(staged)
+                    staged_profiles.append(staged)
+                for staged, target in zip(staged_profiles, targets, strict=True):
+                    staged.rename(target)
+    except OSError as error:
+        raise ConfigurationError(f"cannot initialize profiles: {error}") from error
+
+    return targets
+
+
+def _configure_runtime(
+    profile_directory: Path, model_id: str, thinking: ThinkingLevel
+) -> None:
+    models_path = profile_directory / "models.json"
+    models = json.loads(models_path.read_text(encoding="utf-8"))
+    model = models["providers"]["openshell"]["models"][0]
+    model["id"] = model_id
+    model["reasoning"] = thinking is not ThinkingLevel.OFF
+    models_path.write_text(json.dumps(models, indent=2) + "\n", encoding="utf-8")
+
+    settings_path = profile_directory / "settings.json"
+    settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    settings["defaultModel"] = model_id
+    settings["defaultThinkingLevel"] = thinking.value
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")

openshell_agent_runner/profiles/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Profiles packaged with OpenShell Agent Runner."""

openshell_agent_runner/profiles/reviewer/models.json

@@ -0,0 +1,19 @@
+{
+  "providers": {
+    "openshell": {
+      "baseUrl": "https://inference.local/v1",
+      "api": "openai-completions",
+      "apiKey": "unused",
+      "authHeader": true,
+      "compat": {
+        "supportsDeveloperRole": false
+      },
+      "models": [
+        {
+          "id": "MODEL_ID",
+          "reasoning": true
+        }
+      ]
+    }
+  }
+}

openshell_agent_runner/profiles/reviewer/policy.yaml

@@ -0,0 +1,15 @@
+version: 1
+
+filesystem_policy:
+  include_workdir: false
+  read_only: [/usr, /lib, /proc, /dev/urandom, /etc, /opt/oar]
+  read_write: [/workspace, /sandbox, /tmp, /dev/null]
+
+landlock:
+  compatibility: hard_requirement
+
+process:
+  run_as_user: "1000"
+  run_as_group: "1000"
+
+network_policies: {}

openshell_agent_runner/profiles/reviewer/profile.yaml

@@ -0,0 +1,12 @@
+id: reviewer
+description: Review a required input document and publish the result.
+
+sandbox:
+  policy: policy.yaml
+
+tasks:
+  review:
+    description: Review an input document and return a useful written result.
+    required_input: document
+    prompt: prompt.md
+    tools: [read, grep, find, ls, bash]

openshell_agent_runner/profiles/reviewer/prompt.md

@@ -0,0 +1,5 @@
+# Review the input document
+
+Act as a coding agent. Inspect `/workspace/input/document.md`, using the declared
+tools as needed. Return a concise Markdown review that identifies the document's
+strengths and the most useful improvements to its clarity and completeness.

openshell_agent_runner/profiles/reviewer/settings.json

@@ -0,0 +1,5 @@
+{
+  "defaultProvider": "openshell",
+  "defaultModel": "MODEL_ID",
+  "defaultThinkingLevel": "high"
+}

openshell_agent_runner/runner.py

@@ -0,0 +1,277 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Resolve and run one configured task in an OpenShell sandbox."""
+
+from __future__ import annotations
+
+import json
+import secrets
+import shlex
+import sys
+import tempfile
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import openshell_agent_runner.openshell as openshell
+from openshell_agent_runner.artifacts import (
+    MAX_ARTIFACT_BYTES,
+    atomic_publish,
+    validate_artifact,
+)
+from openshell_agent_runner.config import (
+    ResolvedProfile,
+    resolve_task,
+    validate_environment_assignments,
+    validate_upload_mappings,
+)
+from openshell_agent_runner.errors import ConfigurationError, ExecutionError
+from openshell_agent_runner.harnesses.pi.resources import (
+    image_directory,
+    prepare_resources,
+)
+
+
+@dataclass(frozen=True)
+class RunRequest:
+    profile_directory: Path
+    task_id: str
+    output: Path
+    input_document: Path | None = None
+    uploads: Sequence[str] = ()
+    environments: Sequence[str] = ()
+    gateway: str | None = None
+    workspace: str = "default"
+    timeout_seconds: int = 1200
+    keep_sandbox: bool = False
+    openshell_bin: str = "openshell"
+
+
+@dataclass(frozen=True)
+class ResolvedRun:
+    request: RunRequest
+    profile: ResolvedProfile
+    uploads: tuple[str, ...]
+    environments: tuple[str, ...]
+    create_command: tuple[str, ...]
+
+
+def resolve_run(request: RunRequest) -> ResolvedRun:
+    profile = resolve_task(request.profile_directory, request.task_id)
+    task = profile.profile.tasks[request.task_id]
+    document_upload = _resolve_document_upload(request, task.required_input)
+    uploads = _validate_uploads(
+        [
+            *profile.profile.sandbox.upload,
+            *([document_upload] if document_upload else []),
+            *request.uploads,
+        ]
+    )
+    environments = _validate_environments(
+        [
+            *([_DOCUMENT_INPUT_ENVIRONMENT] if document_upload else []),
+            *profile.profile.sandbox.env,
+            *request.environments,
+        ]
+    )
+    sandbox = profile.profile.sandbox
+    command = [request.openshell_bin, "sandbox", "create"]
+    if request.gateway:
+        command.extend(["--gateway", request.gateway])
+    command.extend(
+        [
+            "--workspace",
+            request.workspace,
+            "--from",
+            str(image_directory()),
+            "--policy",
+            str(profile.profile_dir / sandbox.policy),
+        ]
+    )
+    for upload in uploads:
+        command.extend(["--upload", upload])
+    for environment in environments:
+        command.extend(["--env", environment])
+    command.extend(["--no-auto-providers", "--no-tty", "--approval-mode", "auto"])
+    return ResolvedRun(
+        request=request,
+        profile=profile,
+        uploads=uploads,
+        environments=environments,
+        create_command=tuple(command),
+    )
+
+
+def render_dry_run(request: RunRequest) -> str:
+    """Render the exact nominal command sequence without executing subprocesses."""
+    resolved = resolve_run(request)
+    name, token = _identity()
+    resources = prepare_resources(resolved.profile, request.task_id)
+    try:
+        with tempfile.TemporaryDirectory(prefix="oar-output-") as directory:
+            downloaded = Path(directory) / "output.download"
+            commands = [
+                (
+                    "create",
+                    openshell.sandbox_create(resolved, resources, name, token),
+                ),
+                (
+                    "download",
+                    openshell.sandbox_download(resolved, name, downloaded),
+                ),
+            ]
+            if not request.keep_sandbox:
+                commands.extend(
+                    [
+                        (
+                            "verify ownership",
+                            openshell.sandbox_get(request, name),
+                        ),
+                        (
+                            "delete",
+                            openshell.sandbox_delete(request, name),
+                        ),
+                    ]
+                )
+            lines = [
+                "Dry run: no commands were executed.",
+                f"Profile: {resolved.profile.profile.id}",
+                f"Task: {request.task_id}",
+                f"Sandbox: {name}",
+                "OpenShell commands:",
+                *(f"[{label}] {shlex.join(command)}" for label, command in commands),
+                "Host actions:",
+                _validation_preview(resolved, downloaded),
+                f"[publish] atomically replace {request.output}",
+            ]
+            if request.keep_sandbox:
+                lines.append("[cleanup] skipped because --keep-sandbox is set")
+            else:
+                lines.append(
+                    "[cleanup] ownership verification and deletion also run after "
+                    "failures when the sandbox can be inspected"
+                )
+            return "\n".join(lines) + "\n"
+    finally:
+        resources.close()
+
+
+def run_agent(request: RunRequest) -> str:
+    resolved = resolve_run(request)
+    name, token = _identity()
+    resources = prepare_resources(resolved.profile, request.task_id)
+    create = openshell.sandbox_create(resolved, resources, name, token)
+    primary_error: BaseException | None = None
+    try:
+        openshell.run(create, request.timeout_seconds)
+        task = resolved.profile.profile.tasks[request.task_id]
+        with tempfile.TemporaryDirectory(prefix="oar-output-") as directory:
+            downloaded = Path(directory) / "output.download"
+            downloaded.touch(mode=0o600)
+            openshell.run(
+                openshell.sandbox_download(resolved, name, downloaded),
+                120,
+                max_file_bytes=MAX_ARTIFACT_BYTES,
+            )
+            schema_path = (
+                resolved.profile.profile_dir / task.output_schema
+                if task.output_schema is not None
+                else None
+            )
+            validate_artifact(downloaded, schema_path)
+            atomic_publish(downloaded, request.output)
+        return name
+    except BaseException as error:
+        primary_error = error
+        raise
+    finally:
+        resources.close()
+        if request.keep_sandbox:
+            print(f"oar: sandbox name (--keep-sandbox): {name}", file=sys.stderr)
+        else:
+            try:
+                _verify_ownership(request, name, token)
+                openshell.run(openshell.sandbox_delete(request, name), 60)
+            except ExecutionError as cleanup_error:
+                if primary_error is None:
+                    raise
+                print(
+                    f"oar: cleanup failed after primary error: {cleanup_error}",
+                    file=sys.stderr,
+                )
+
+
+def _validate_uploads(values: Sequence[str]) -> tuple[str, ...]:
+    try:
+        return validate_upload_mappings(values)
+    except ValueError as error:
+        raise ConfigurationError(str(error)) from error
+
+
+def _validate_environments(values: Sequence[str]) -> tuple[str, ...]:
+    try:
+        return validate_environment_assignments(values)
+    except ValueError as error:
+        raise ConfigurationError(str(error)) from error
+
+
+def _resolve_document_upload(
+    request: RunRequest, required_input: str | None
+) -> str | None:
+    if required_input is None:
+        if request.input_document is not None:
+            raise ConfigurationError(
+                f"task {request.task_id!r} does not accept --input"
+            )
+        return None
+    if request.input_document is None:
+        raise ConfigurationError(f"task {request.task_id!r} requires --input DOCUMENT")
+    try:
+        document = request.input_document.resolve(strict=True)
+    except OSError as error:
+        raise ConfigurationError(
+            f"input document does not exist: {request.input_document}"
+        ) from error
+    if not document.is_file():
+        raise ConfigurationError(f"input document must be a file: {document}")
+    return f"{document}:{_DOCUMENT_INPUT_PATH}"
+
+
+def _validation_preview(resolved: ResolvedRun, downloaded: Path) -> str:
+    task = resolved.profile.profile.tasks[resolved.request.task_id]
+    if task.output_schema is None:
+        return f"[validate] {downloaded} is present, non-empty, and bounded"
+    schema = resolved.profile.profile_dir / task.output_schema
+    return f"[validate] {downloaded} as JSON against {schema}"
+
+
+def _identity() -> tuple[str, str]:
+    token = secrets.token_hex(8)[:15]
+    return f"oar-{token}", token
+
+
+def _verify_ownership(request: RunRequest, name: str, token: str) -> None:
+    command = openshell.sandbox_get(request, name)
+    result = openshell.run(command, 30, capture=True)
+    try:
+        document = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise ExecutionError(
+            f"cleanup ownership response was invalid for {name}"
+        ) from error
+    labels = document.get("labels") if isinstance(document, dict) else None
+    owned = (
+        isinstance(document, dict)
+        and document.get("name") == name
+        and isinstance(labels, dict)
+        and labels.get(openshell.RESERVED_LABEL) == token
+    )
+    if not owned:
+        raise ExecutionError(
+            f"refusing to delete sandbox with mismatched ownership: {name}"
+        )
+
+
+_DOCUMENT_INPUT_PATH = "/workspace/input/document.md"
+_DOCUMENT_INPUT_ENVIRONMENT = "REPOSITORY_ROOT=/workspace/input"