pysolated 0.1.0__py3-none-any.whl

pysolated/__init__.py

@@ -0,0 +1,177 @@
+"""pysolated — orchestrate AI coding agents inside sandboxes via `run()`."""
+
+from __future__ import annotations
+
+from .agents import (
+    ClaudeCode,
+    Codex,
+    CodexEffort,
+    PermissionMode,
+    claude_code,
+    codex,
+    parse_codex_session_usage,
+    parse_codex_stream_line,
+    parse_session_usage,
+    parse_stream_line,
+)
+from .completion import match_completion_signal
+from .core import (
+    AgentCommandOptions,
+    AgentProvider,
+    Command,
+    Display,
+    ExecResult,
+    ResultEvent,
+    RunResult,
+    Sandbox,
+    SandboxProvider,
+    SessionIdEvent,
+    Severity,
+    StreamEvent,
+    TextEvent,
+    ToolCallEvent,
+    Usage,
+)
+from .display import FileDisplay, TerminalDisplay
+from .errors import (
+    AgentExecutionError,
+    BranchAlreadyCheckedOutError,
+    IdleTimeoutError,
+    MergeConflictError,
+    PysolatedError,
+)
+from .orchestrator import (
+    DEFAULT_COMPLETION_SIGNAL,
+    DEFAULT_COMPLETION_TIMEOUT_SECONDS,
+    DEFAULT_IDLE_TIMEOUT_SECONDS,
+    DEFAULT_IDLE_WARNING_INTERVAL_SECONDS,
+    run,
+)
+from .prompts import (
+    PromptArgumentError,
+    PromptError,
+    PromptExecutor,
+    PromptExpansionError,
+    expand_shell_expressions,
+    resolve_prompt,
+    substitute_arguments,
+)
+from .sandboxes import (
+    Docker,
+    DockerHandle,
+    DockerImageNotFoundError,
+    DockerImageUidMismatchError,
+    DockerLaunchError,
+    Mount,
+    NoSandbox,
+    NoSandboxHandle,
+    Podman,
+    PodmanHandle,
+    PodmanImageNotFoundError,
+    PodmanLaunchError,
+    docker,
+    no_sandbox,
+    podman,
+)
+from .structured_output import (
+    Output,
+    OutputDefinition,
+    OutputObject,
+    OutputString,
+    StructuredOutputError,
+    extract_structured_output,
+)
+from .worktrees import (
+    BranchStrategy,
+    FinalizedRun,
+    HeadStrategy,
+    MergeToHeadStrategy,
+    NamedBranchStrategy,
+    PreparedRun,
+)
+
+__all__ = [
+    # Entry point
+    "run",
+    # Providers
+    "claude_code",
+    "ClaudeCode",
+    "codex",
+    "Codex",
+    "CodexEffort",
+    "no_sandbox",
+    "NoSandbox",
+    "NoSandboxHandle",
+    "podman",
+    "Podman",
+    "PodmanHandle",
+    "docker",
+    "Docker",
+    "DockerHandle",
+    "Mount",
+    "PermissionMode",
+    # Display
+    "TerminalDisplay",
+    "FileDisplay",
+    # Seams (Protocols)
+    "AgentProvider",
+    "SandboxProvider",
+    "Sandbox",
+    "Display",
+    # Pure parsers / matchers
+    "parse_stream_line",
+    "parse_session_usage",
+    "parse_codex_stream_line",
+    "parse_codex_session_usage",
+    "match_completion_signal",
+    # Prompt pipeline
+    "resolve_prompt",
+    "substitute_arguments",
+    "expand_shell_expressions",
+    "PromptExecutor",
+    # Structured output
+    "Output",
+    "OutputDefinition",
+    "OutputObject",
+    "OutputString",
+    "extract_structured_output",
+    # Defaults
+    "DEFAULT_COMPLETION_SIGNAL",
+    "DEFAULT_IDLE_TIMEOUT_SECONDS",
+    "DEFAULT_COMPLETION_TIMEOUT_SECONDS",
+    "DEFAULT_IDLE_WARNING_INTERVAL_SECONDS",
+    # Branch strategies
+    "BranchStrategy",
+    "HeadStrategy",
+    "MergeToHeadStrategy",
+    "NamedBranchStrategy",
+    "PreparedRun",
+    "FinalizedRun",
+    # Value types
+    "RunResult",
+    "Usage",
+    "Command",
+    "ExecResult",
+    "AgentCommandOptions",
+    "StreamEvent",
+    "TextEvent",
+    "ToolCallEvent",
+    "SessionIdEvent",
+    "ResultEvent",
+    "Severity",
+    # Errors
+    "PysolatedError",
+    "AgentExecutionError",
+    "BranchAlreadyCheckedOutError",
+    "IdleTimeoutError",
+    "MergeConflictError",
+    "PromptError",
+    "PromptArgumentError",
+    "PromptExpansionError",
+    "StructuredOutputError",
+    "PodmanImageNotFoundError",
+    "PodmanLaunchError",
+    "DockerImageNotFoundError",
+    "DockerImageUidMismatchError",
+    "DockerLaunchError",
+]

pysolated/agents/__init__.py

@@ -0,0 +1,45 @@
+"""Agent providers — command building and stream parsing.
+
+v1 ships one provider, `claude_code`. The stream parser and usage parser are
+pure module-level functions (the provider delegates to them) so they can be
+table-tested directly without constructing a provider.
+
+The package layout mirrors `sandboxes/` (see issue #24):
+
+- `claude_code.py` — the Claude Code provider plus its pure parsers.
+- `_parsing.py` — shared stream-parsing helpers (the tool-input allowlist and
+  the assistant-content block parser) that Claude — and the later Copilot
+  provider — both use.
+- `_registry.py` — empty scaffold for the registry + `build_agent` to land in
+  a follow-up slice (issue #32).
+"""
+
+from __future__ import annotations
+
+from .claude_code import (
+    ClaudeCode,
+    PermissionMode,
+    claude_code,
+    parse_session_usage,
+    parse_stream_line,
+)
+from .codex import (
+    Codex,
+    CodexEffort,
+    codex,
+    parse_codex_session_usage,
+    parse_codex_stream_line,
+)
+
+__all__ = [
+    "ClaudeCode",
+    "Codex",
+    "CodexEffort",
+    "PermissionMode",
+    "claude_code",
+    "codex",
+    "parse_codex_session_usage",
+    "parse_codex_stream_line",
+    "parse_session_usage",
+    "parse_stream_line",
+]

pysolated/agents/_parsing.py

@@ -0,0 +1,55 @@
+"""Shared stream-parsing helpers used by multiple agent providers.
+
+Claude Code — and the later Copilot provider — both emit stream-json with an
+`assistant` content-block shape; this module centralises that parsing and the
+allowlist of tool names whose input fields we are willing to surface.
+"""
+
+from __future__ import annotations
+
+from ..core import StreamEvent, TextEvent, ToolCallEvent
+
+# Allowlisted tools, mapped to the input field carrying the display arg.
+# Anything not listed here is dropped — we never surface arbitrary tool input.
+TOOL_ARG_FIELDS: dict[str, str] = {
+    "Bash": "command",
+    "WebSearch": "query",
+    "WebFetch": "url",
+    "Agent": "description",
+}
+
+
+def parse_assistant_content_blocks(content: list[object]) -> list[StreamEvent]:
+    """Decode an `assistant` message's `content` blocks into stream events.
+
+    Pure. Text blocks concatenate into `TextEvent`s; allowlisted `tool_use`
+    blocks become `ToolCallEvent`s. Pending text is flushed before each tool
+    call so events stay in source order. Unknown / wrong-typed blocks are
+    silently skipped.
+    """
+    events: list[StreamEvent] = []
+    texts: list[str] = []
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        block_type = block.get("type")
+        if block_type == "text" and isinstance(block.get("text"), str):
+            texts.append(block["text"])
+        elif (
+            block_type == "tool_use"
+            and isinstance(block.get("name"), str)
+            and isinstance(block.get("input"), dict)
+        ):
+            arg_field = TOOL_ARG_FIELDS.get(block["name"])
+            if arg_field is None:
+                continue  # not allowlisted
+            arg_value = block["input"].get(arg_field)
+            if not isinstance(arg_value, str):
+                continue  # missing / wrong-typed arg field
+            if texts:
+                events.append(TextEvent(text="".join(texts)))
+                texts = []
+            events.append(ToolCallEvent(name=block["name"], args=arg_value))
+    if texts:
+        events.append(TextEvent(text="".join(texts)))
+    return events

pysolated/agents/_registry.py

@@ -0,0 +1,85 @@
+"""Agent registry + CLI-builder.
+
+A name → factory map keyed on each provider's ``.name``, plus ``build_agent``
+— the CLI's one resolver. Library callers construct providers directly via
+their typed factories and never touch this module; it exists only for the
+string-name boundary the CLI (and later init/config) sits behind.
+
+``build_agent`` applies provider-specific option handling here so the CLI
+grows no ``if name == …`` ladder as agents are added. Argument errors raise
+``ValueError``; the CLI translates that into ``typer.Exit(2)``, consistent
+with the existing ``--prompt`` / ``--prompt-arg`` rejections.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from ..core import AgentProvider
+from .claude_code import PermissionMode, claude_code
+from .codex import codex
+
+_CLAUDE_CODE_DEFAULT_MODEL = "claude-opus-4-7"
+
+
+def _build_claude_code(
+    *,
+    model: str | None,
+    effort: str | None,
+    permission_mode: str | None,
+) -> AgentProvider:
+    if effort is not None:
+        raise ValueError("--effort is not supported by the claude-code agent.")
+    resolved_model = model if model is not None else _CLAUDE_CODE_DEFAULT_MODEL
+    return claude_code(
+        resolved_model,
+        permission_mode=permission_mode,  # type: ignore[arg-type]
+    )
+
+
+def _build_codex(
+    *,
+    model: str | None,
+    effort: str | None,
+    permission_mode: str | None,
+) -> AgentProvider:
+    if permission_mode is not None:
+        raise ValueError("--permission-mode is not supported by the codex agent.")
+    if model is None:
+        raise ValueError("--model is required for the codex agent.")
+    return codex(model, effort=effort)  # type: ignore[arg-type]
+
+
+# Keyed on the provider's ``.name``. Each entry resolves CLI options into a
+# concrete provider; provider-specific rejections live here, not in the CLI.
+_REGISTRY: dict[
+    str,
+    Callable[..., AgentProvider],
+] = {
+    "claude-code": _build_claude_code,
+    "codex": _build_codex,
+}
+
+
+def agent_names() -> list[str]:
+    """The registered agent names, in insertion order — for error messages."""
+    return list(_REGISTRY)
+
+
+def build_agent(
+    name: str,
+    *,
+    model: str | None,
+    effort: str | None = None,
+    permission_mode: PermissionMode | None = None,
+) -> AgentProvider:
+    """Resolve a CLI agent name to a configured ``AgentProvider``.
+
+    Raises ``ValueError`` for an unknown name, a model that's required but
+    missing for the chosen agent, or a flag the chosen agent does not accept.
+    """
+    factory = _REGISTRY.get(name)
+    if factory is None:
+        valid = ", ".join(agent_names())
+        raise ValueError(f"Unknown --agent {name!r}. Valid agents: {valid}.")
+    return factory(model=model, effort=effort, permission_mode=permission_mode)

pysolated/agents/claude_code.py

@@ -0,0 +1,161 @@
+"""The Claude Code agent provider.
+
+The stream parser and usage parser are pure module-level functions (the
+provider delegates to them) so they can be table-tested directly without
+constructing a provider.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Literal
+
+from ..core import (
+    AgentCommandOptions,
+    Command,
+    SessionIdEvent,
+    StreamEvent,
+    Usage,
+)
+from ._parsing import parse_assistant_content_blocks
+
+
+def parse_stream_line(line: str) -> list[StreamEvent]:
+    """Decode one Claude `stream-json` JSONL line into zero or more events.
+
+    Pure. Non-JSON / unknown / malformed lines yield no events.
+
+    - `assistant` lines yield `text` events (content text blocks concatenated)
+      and `tool_call` events for allowlisted tools, in source order.
+    - `system`/`init` lines yield a single `session_id` event.
+    """
+    if not line.startswith("{"):
+        return []
+    try:
+        obj = json.loads(line)
+    except (json.JSONDecodeError, ValueError):
+        return []
+    if not isinstance(obj, dict):
+        return []
+
+    message = obj.get("message")
+    if (
+        obj.get("type") == "assistant"
+        and isinstance(message, dict)
+        and isinstance(message.get("content"), list)
+    ):
+        return parse_assistant_content_blocks(message["content"])
+
+    if (
+        obj.get("type") == "system"
+        and obj.get("subtype") == "init"
+        and isinstance(obj.get("session_id"), str)
+    ):
+        return [SessionIdEvent(session_id=obj["session_id"])]
+
+    return []
+
+
+_USAGE_FIELDS = (
+    "input_tokens",
+    "cache_creation_input_tokens",
+    "cache_read_input_tokens",
+    "output_tokens",
+)
+
+
+def parse_session_usage(content: str) -> Usage | None:
+    """Extract the session's authoritative token usage from streamed content.
+
+    Pure. Scans the accumulated stream-json content from the end and returns the
+    first complete usage block it finds, or `None` when no usage was emitted.
+
+    The authoritative totals live on the terminal `result` line: an `assistant`
+    line's usage is the `message_start` snapshot, captured before the response
+    streamed, so its `output_tokens` is only a partial count (often 1). Scanning
+    from the end reaches the `result` line first, so its totals win; an
+    `assistant` line is the fallback for truncated streams that never reached a
+    `result`. The usage block sits at the top level on a `result` line and under
+    `message` on an `assistant` line.
+    """
+    for line in reversed(content.split("\n")):
+        if not line.startswith("{"):
+            continue
+        try:
+            obj = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue
+        if not isinstance(obj, dict):
+            continue
+        if obj.get("type") == "result":
+            usage = obj.get("usage")
+        elif obj.get("type") == "assistant":
+            message = obj.get("message")
+            usage = message.get("usage") if isinstance(message, dict) else None
+        else:
+            continue
+        if not isinstance(usage, dict):
+            continue
+        if all(isinstance(usage.get(name), int) for name in _USAGE_FIELDS):
+            return Usage(
+                input_tokens=usage["input_tokens"],
+                cache_creation_input_tokens=usage["cache_creation_input_tokens"],
+                cache_read_input_tokens=usage["cache_read_input_tokens"],
+                output_tokens=usage["output_tokens"],
+            )
+    return None
+
+
+# Maps directly to Claude's `--permission-mode` flag. Mutually exclusive with
+# `--dangerously-skip-permissions` on Claude's CLI.
+PermissionMode = Literal[
+    "default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"
+]
+
+
+@dataclass(frozen=True)
+class ClaudeCode:
+    """The Claude Code agent provider.
+
+    Build it via `claude_code(...)` rather than constructing directly.
+    """
+
+    model: str
+    permission_mode: PermissionMode | None = None
+    env: dict[str, str] = field(default_factory=dict)
+    name: str = "claude-code"
+
+    def build_command(self, options: AgentCommandOptions) -> Command:
+        """Build the print-mode argv, with the prompt delivered on stdin.
+
+        `permission_mode` and `--dangerously-skip-permissions` are mutually
+        exclusive: an explicit mode replaces the default skip-permissions flag.
+        """
+        argv = ["claude", "--print", "--verbose"]
+        if self.permission_mode is not None:
+            argv += ["--permission-mode", self.permission_mode]
+        else:
+            argv.append("--dangerously-skip-permissions")
+        argv += ["--output-format", "stream-json", "--model", self.model, "-p", "-"]
+        return Command(argv=argv, stdin=options.prompt)
+
+    def parse_stream_line(self, line: str) -> list[StreamEvent]:
+        return parse_stream_line(line)
+
+    def parse_session_usage(self, content: str) -> Usage | None:
+        return parse_session_usage(content)
+
+
+def claude_code(
+    model: str,
+    *,
+    permission_mode: PermissionMode | None = None,
+    env: dict[str, str] | None = None,
+) -> ClaudeCode:
+    """Create a Claude Code agent provider.
+
+    `model` selects the Claude model. `permission_mode`, when given, replaces the
+    default `--dangerously-skip-permissions` flag (the two are mutually exclusive).
+    """
+    return ClaudeCode(model=model, permission_mode=permission_mode, env=env or {})