opensaddle 1.0.0__py3-none-any.whl

opensaddle/__init__.py

@@ -0,0 +1,5 @@
+"""opensaddle package."""
+
+__all__ = ["__version__"]
+
+__version__ = "1.0.0"

opensaddle/__main__.py

@@ -0,0 +1,7 @@
+"""Run the opensaddle CLI with ``python -m opensaddle``."""
+
+from opensaddle.cli.main import app
+
+
+if __name__ == "__main__":
+    app()

opensaddle/adapters/__init__.py

@@ -0,0 +1 @@
+"""Agent adapter implementations."""

opensaddle/adapters/base.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class CliExecutionMode(str, Enum):
+    EXEC = "exec"
+    PTY = "pty"
+
+
+class TemplateRenderError(ValueError):
+    """Raised when a command template cannot be rendered."""
+
+
+class _StrictTemplateValues(dict[str, str]):
+    def __missing__(self, key: str) -> str:
+        raise TemplateRenderError(f"missing template value: {key}")
+
+
+@dataclass(slots=True)
+class UsageReport:
+    confidence: str
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class CommandCapture:
+    argv: list[str]
+    cwd: str
+    exit_code: int | None
+    stdout: str
+    stderr: str
+    timed_out: bool
+    duration_seconds: float
+    execution_mode: str = CliExecutionMode.EXEC.value
+    env: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class CliExecutionResult:
+    capture: CommandCapture
+    usage: UsageReport | None = None
+
+
+class UsageParser(Protocol):
+    def parse(self, *, capture: CommandCapture) -> UsageReport | None:
+        """Extract usage information from a finished command."""
+
+
+@dataclass(slots=True)
+class NullUsageParser:
+    def parse(self, *, capture: CommandCapture) -> UsageReport | None:
+        return None
+
+
+@dataclass(slots=True)
+class CliCommandTemplate:
+    argv: list[str]
+    env: dict[str, str] = field(default_factory=dict)
+
+    def render(self, context: dict[str, Any]) -> tuple[list[str], dict[str, str]]:
+        rendered_context = _StrictTemplateValues(
+            {key: "" if value is None else str(value) for key, value in context.items()}
+        )
+        argv = [part.format_map(rendered_context) for part in self.argv]
+        env = {
+            key: value.format_map(rendered_context)
+            for key, value in self.env.items()
+        }
+        return argv, env
+
+
+@dataclass(slots=True)
+class AgentInvocation:
+    instruction: str
+    workdir: Path
+    model: str | None = None
+    timeout_seconds: float | None = None
+    extra_context: dict[str, Any] = field(default_factory=dict)

opensaddle/adapters/cli.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from opensaddle.adapters.base import (
+    AgentInvocation,
+    CliExecutionMode,
+    CliCommandTemplate,
+    CliExecutionResult,
+    CommandCapture,
+    NullUsageParser,
+    UsageParser,
+    UsageReport,
+)
+from opensaddle.audit.stream import AuditStream
+from opensaddle.execution.pty import PtyCommandRunner
+
+
+def _normalize_output(value: str | bytes | None) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    return value
+
+
+@dataclass(slots=True)
+class RegexUsageParser:
+    pattern: str
+    confidence: str = "parsed"
+    flags: int = re.MULTILINE
+
+    def parse(self, *, capture: CommandCapture) -> UsageReport | None:
+        match = re.search(self.pattern, capture.stdout, self.flags)
+        if not match:
+            return None
+        raw = match.groupdict()
+        return UsageReport(
+            confidence=self.confidence,
+            prompt_tokens=int(raw["prompt"]) if raw.get("prompt") else None,
+            completion_tokens=int(raw["completion"]) if raw.get("completion") else None,
+            total_tokens=int(raw["total"]) if raw.get("total") else None,
+            raw=raw,
+        )
+
+
+@dataclass(slots=True)
+class CliAgentAdapter:
+    name: str
+    command_template: CliCommandTemplate
+    usage_parser: UsageParser = field(default_factory=NullUsageParser)
+    timeout_seconds: float | None = None
+    execution_mode: CliExecutionMode = CliExecutionMode.EXEC
+    pty_rows: int = 40
+    pty_columns: int = 120
+    pty_term: str = "xterm-256color"
+
+    def run(
+        self,
+        invocation: AgentInvocation,
+        *,
+        audit_stream: AuditStream | None = None,
+        base_env: dict[str, str] | None = None,
+        clean_env: bool = False,
+        command_prefix: list[str] | None = None,
+    ) -> CliExecutionResult:
+        context: dict[str, Any] = {
+            "instruction": invocation.instruction,
+            "model": invocation.model or "",
+            "workdir": str(invocation.workdir),
+        }
+        context.update(invocation.extra_context)
+        argv, rendered_env = self.command_template.render(context)
+        if command_prefix:
+            argv = [*command_prefix, *argv]
+        timeout_seconds = invocation.timeout_seconds or self.timeout_seconds
+        env = {} if clean_env else dict(os.environ)
+        env.update(base_env or {})
+        env.update(rendered_env)
+
+        if audit_stream is not None:
+            audit_stream.record(
+                "command_started",
+                actor="agent",
+                payload={
+                    "argv": argv,
+                    "cwd": str(invocation.workdir),
+                    "execution_mode": self.execution_mode.value,
+                },
+            )
+
+        started_at = time.perf_counter()
+        capture = self._run_command(
+            argv=argv,
+            workdir=invocation.workdir,
+            env=env,
+            rendered_env=rendered_env,
+            timeout_seconds=timeout_seconds,
+            started_at=started_at,
+        )
+
+        if audit_stream is not None:
+            audit_stream.record(
+                "command_finished",
+                actor="agent",
+                payload={
+                    "argv": argv,
+                    "cwd": str(invocation.workdir),
+                    "exit_code": capture.exit_code,
+                    "timed_out": capture.timed_out,
+                    "duration_seconds": capture.duration_seconds,
+                    "execution_mode": capture.execution_mode,
+                },
+            )
+            if capture.stdout:
+                audit_stream.record(
+                    "agent_stdout",
+                    actor="agent",
+                    payload={"text": capture.stdout},
+                )
+            if capture.stderr:
+                audit_stream.record(
+                    "agent_stderr",
+                    actor="agent",
+                    payload={"text": capture.stderr},
+                )
+
+        usage = self.usage_parser.parse(capture=capture)
+        return CliExecutionResult(capture=capture, usage=usage)
+
+    def _run_command(
+        self,
+        *,
+        argv: list[str],
+        workdir: Path,
+        env: dict[str, str],
+        rendered_env: dict[str, str],
+        timeout_seconds: float | None,
+        started_at: float,
+    ) -> CommandCapture:
+        if self.execution_mode is CliExecutionMode.PTY:
+            return PtyCommandRunner(
+                rows=self.pty_rows,
+                columns=self.pty_columns,
+                term=self.pty_term,
+            ).run(
+                argv=argv,
+                workdir=workdir,
+                env=env,
+                timeout_seconds=timeout_seconds,
+                rendered_env=rendered_env,
+            )
+
+        try:
+            completed = subprocess.run(
+                argv,
+                cwd=workdir,
+                env=env or None,
+                capture_output=True,
+                text=True,
+                timeout=timeout_seconds,
+                check=False,
+            )
+            return CommandCapture(
+                argv=argv,
+                cwd=str(workdir),
+                exit_code=completed.returncode,
+                stdout=completed.stdout,
+                stderr=completed.stderr,
+                timed_out=False,
+                duration_seconds=time.perf_counter() - started_at,
+                execution_mode=CliExecutionMode.EXEC.value,
+                env=rendered_env,
+            )
+        except subprocess.TimeoutExpired as exc:
+            return CommandCapture(
+                argv=argv,
+                cwd=str(workdir),
+                exit_code=None,
+                stdout=_normalize_output(exc.stdout),
+                stderr=_normalize_output(exc.stderr),
+                timed_out=True,
+                duration_seconds=time.perf_counter() - started_at,
+                execution_mode=CliExecutionMode.EXEC.value,
+                env=rendered_env,
+            )

opensaddle/agent_presets.py

@@ -0,0 +1,194 @@
+"""Built-in YAML presets for common coding-agent CLIs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+
+
+@dataclass(frozen=True, slots=True)
+class AgentPreset:
+    """A built-in agent config snippet that still uses the generic CLI adapter."""
+
+    agent_id: str
+    command: str
+    exec_argv: tuple[str, ...]
+    models: tuple[dict[str, str], ...] = ()
+    usage_parser_kind: str | None = None
+    usage_parser_path_glob: str | None = None
+
+    def to_config(self) -> dict[str, Any]:
+        config: dict[str, Any] = {
+            "adapter": "cli",
+            "command": self.command,
+            "modes": {
+                "exec": {
+                    "argv": list(self.exec_argv),
+                },
+                "pty": {
+                    "enabled": False,
+                },
+            },
+        }
+        if self.models:
+            config["models"] = [dict(binding) for binding in self.models]
+        if self.usage_parser_kind is not None:
+            usage_parser = {"kind": self.usage_parser_kind}
+            if self.usage_parser_path_glob is not None:
+                usage_parser["path_glob"] = self.usage_parser_path_glob
+            config["usage_parser"] = usage_parser
+        return config
+
+
+BUILTIN_AGENT_PRESETS: dict[str, AgentPreset] = {
+    "codex": AgentPreset(
+        agent_id="codex",
+        command="codex",
+        exec_argv=("codex", "exec", "--model", "{model}", "{instruction}"),
+        models=(
+            {
+                "id": "gpt-5",
+                "cost_profile": "openai_gpt5",
+                "success_prior": "strong_coding",
+            },
+            {
+                "id": "gpt-5-mini",
+                "cost_profile": "openai_gpt5_mini",
+                "success_prior": "cheap_coding",
+            },
+        ),
+        usage_parser_kind="estimated",
+    ),
+    "claude_code": AgentPreset(
+        agent_id="claude_code",
+        command="claude",
+        exec_argv=("claude", "-p", "--model", "{model}", "{instruction}"),
+        usage_parser_kind="transcript_json",
+        usage_parser_path_glob=".claude/**/*.json",
+    ),
+    "github_copilot": AgentPreset(
+        agent_id="github_copilot",
+        command="copilot",
+        exec_argv=("copilot", "-p", "--model", "{model}", "{instruction}"),
+        usage_parser_kind="estimated",
+    ),
+    "aider": AgentPreset(
+        agent_id="aider",
+        command="aider",
+        exec_argv=(
+            "aider",
+            "--model",
+            "{model}",
+            "--yes",
+            "--no-auto-commits",
+            "--message",
+            "{instruction}",
+        ),
+        usage_parser_kind="estimated",
+    ),
+    "cursor": AgentPreset(
+        agent_id="cursor",
+        command="agent",
+        exec_argv=(
+            "agent",
+            "-p",
+            "--model",
+            "{model}",
+            "--output-format",
+            "text",
+            "{instruction}",
+        ),
+        usage_parser_kind="estimated",
+    ),
+    "amp": AgentPreset(
+        agent_id="amp",
+        command="amp",
+        exec_argv=(
+            "amp",
+            "--execute",
+            "{instruction}",
+            "--stream-json",
+        ),
+        usage_parser_kind="stream_json",
+    ),
+    "antigravity": AgentPreset(
+        agent_id="antigravity",
+        command="agy",
+        exec_argv=(
+            "agy",
+            "--model",
+            "{model}",
+            "--prompt",
+            "{instruction}",
+        ),
+        usage_parser_kind="estimated",
+    ),
+    "claw": AgentPreset(
+        agent_id="claw",
+        command="openclaw",
+        exec_argv=(
+            "openclaw",
+            "infer",
+            "model",
+            "run",
+            "--local",
+            "--model",
+            "{model}",
+            "--prompt",
+            "{instruction}",
+            "--json",
+        ),
+        usage_parser_kind="json",
+    ),
+    "hermes": AgentPreset(
+        agent_id="hermes",
+        command="hermes",
+        exec_argv=(
+            "hermes",
+            "chat",
+            "--model",
+            "{model}",
+            "-q",
+            "{instruction}",
+        ),
+        usage_parser_kind="estimated",
+    ),
+    "pi": AgentPreset(
+        agent_id="pi",
+        command="pi",
+        exec_argv=(
+            "pi",
+            "--approve",
+            "--model",
+            "{model}",
+            "-p",
+            "{instruction}",
+        ),
+        usage_parser_kind="estimated",
+    ),
+}
+
+
+def builtin_agent_preset_names() -> tuple[str, ...]:
+    """Return built-in preset ids in stable display order."""
+    return tuple(BUILTIN_AGENT_PRESETS)
+
+
+def builtin_agent_configs() -> dict[str, dict[str, Any]]:
+    """Return the `agents:` mapping used by generated configs."""
+    return {
+        preset.agent_id: preset.to_config()
+        for preset in BUILTIN_AGENT_PRESETS.values()
+    }
+
+
+def render_agent_preset_fragment(preset_name: str) -> str:
+    """Render one built-in preset as a YAML fragment for docs and examples."""
+    try:
+        preset = BUILTIN_AGENT_PRESETS[preset_name]
+    except KeyError as exc:
+        available = ", ".join(builtin_agent_preset_names())
+        raise ValueError(f"unknown built-in preset '{preset_name}' (expected one of: {available})") from exc
+    return yaml.safe_dump({preset.agent_id: preset.to_config()}, sort_keys=False).strip() + "\n"

opensaddle/audit/__init__.py

@@ -0,0 +1 @@
+"""Audit stream helpers."""