driangle-agentrunner 0.0.1__py3-none-any.whl

agentrunner/__init__.py

@@ -0,0 +1,35 @@
+"""agentrunner — Python library for programmatically invoking AI coding agents."""
+
+from .claudecode import ClaudeRunner, ClaudeRunOptions
+from .errors import (
+    CancelledError,
+    NonZeroExitError,
+    NoResultError,
+    NotFoundError,
+    ParseError,
+    RunnerError,
+    TimeoutError,
+)
+from .ollama import OllamaRunner, OllamaRunnerConfig, OllamaRunOptions
+from .types import Message, Result, Runner, RunOptions, Session, Usage
+
+__all__ = [
+    "CancelledError",
+    "ClaudeRunner",
+    "ClaudeRunOptions",
+    "Message",
+    "NoResultError",
+    "NonZeroExitError",
+    "NotFoundError",
+    "OllamaRunner",
+    "OllamaRunnerConfig",
+    "OllamaRunOptions",
+    "ParseError",
+    "Result",
+    "RunOptions",
+    "Runner",
+    "RunnerError",
+    "Session",
+    "TimeoutError",
+    "Usage",
+]

agentrunner/claudecode/__init__.py

@@ -0,0 +1,11 @@
+"""Claude Code runner for agentrunner."""
+
+from .options import ClaudeRunOptions
+from .runner import ClaudeRunner
+from .version import MIN_VERSION
+
+__all__ = [
+    "ClaudeRunner",
+    "ClaudeRunOptions",
+    "MIN_VERSION",
+]

agentrunner/claudecode/args.py

@@ -0,0 +1,51 @@
+"""Build CLI arguments from prompt and options."""
+
+from __future__ import annotations
+
+from .options import ClaudeRunOptions
+
+
+def build_args(prompt: str, options: ClaudeRunOptions | None = None) -> list[str]:
+    """Build CLI arguments from prompt and options."""
+    args = ["--print", "--output-format", "stream-json", "--verbose"]
+
+    if options is None:
+        args.extend(["--", prompt])
+        return args
+
+    # Common options.
+    if options.model:
+        args.extend(["--model", options.model])
+    if options.system_prompt:
+        args.extend(["--system-prompt", options.system_prompt])
+    if options.append_system_prompt:
+        args.extend(["--append-system-prompt", options.append_system_prompt])
+    if options.max_turns is not None and options.max_turns > 0:
+        args.extend(["--max-turns", str(options.max_turns)])
+    if options.skip_permissions:
+        args.append("--dangerously-skip-permissions")
+
+    # Claude-specific options.
+    if options.allowed_tools:
+        for tool in options.allowed_tools:
+            args.extend(["--allowedTools", tool])
+    if options.disallowed_tools:
+        for tool in options.disallowed_tools:
+            args.extend(["--disallowedTools", tool])
+    if options.mcp_config:
+        args.extend(["--mcp-config", options.mcp_config])
+    if options.json_schema:
+        args.extend(["--json-schema", options.json_schema])
+    if options.max_budget_usd is not None and options.max_budget_usd > 0:
+        args.extend(["--max-budget-usd", str(options.max_budget_usd)])
+    if options.resume:
+        args.extend(["--resume", options.resume])
+    if options.continue_session:
+        args.append("--continue")
+    if options.session_id:
+        args.extend(["--session-id", options.session_id])
+    if options.include_partial_messages:
+        args.append("--include-partial-messages")
+
+    args.extend(["--", prompt])
+    return args

agentrunner/claudecode/mapping.py

@@ -0,0 +1,59 @@
+"""Map Claude stream-json types to common types."""
+
+from __future__ import annotations
+
+import json
+
+from ..types import Result, Usage
+from .types import StreamMessage
+
+_TYPE_MAP = {
+    "system": "system",
+    "assistant": "assistant",
+    "result": "result",
+}
+
+
+def map_message_type(raw_type: str, raw_line: str) -> str:
+    """Map Claude stream-json type to common MessageType.
+
+    Uses the raw JSON line to distinguish tool_use and tool_result subtypes
+    from generic assistant/user messages, matching the INTERFACE.md taxonomy.
+    """
+    if raw_type in _TYPE_MAP:
+        return _TYPE_MAP[raw_type]
+
+    if raw_type == "user":
+        try:
+            d = json.loads(raw_line)
+            for block in d.get("content", []):
+                if isinstance(block, dict) and block.get("type") == "tool_result":
+                    return "tool_result"
+        except (json.JSONDecodeError, TypeError):
+            pass
+        return "user"
+
+    if raw_type == "stream_event":
+        return "assistant"
+
+    return raw_type
+
+
+def map_result(msg: StreamMessage, fallback_session_id: str) -> Result:
+    """Map a StreamMessage result to a common Result."""
+    usage = Usage(
+        input_tokens=msg.usage.input_tokens if msg.usage else 0,
+        output_tokens=msg.usage.output_tokens if msg.usage else 0,
+        cache_creation_input_tokens=msg.usage.cache_creation_input_tokens if msg.usage else 0,
+        cache_read_input_tokens=msg.usage.cache_read_input_tokens if msg.usage else 0,
+    )
+
+    return Result(
+        text=msg.result or "",
+        is_error=msg.is_error or False,
+        exit_code=0,
+        usage=usage,
+        cost_usd=msg.total_cost_usd or 0,
+        duration_ms=msg.duration_ms or 0,
+        session_id=msg.session_id or fallback_session_id,
+    )

agentrunner/claudecode/options.py

@@ -0,0 +1,33 @@
+"""Configuration and option types for the Claude Code runner."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from ..types import RunOptions
+
+
+class Logger(Protocol):
+    """Logger interface for debug output. Opt-in, disabled by default.
+
+    Compatible with ``logging.getLogger()``.
+    """
+
+    def debug(self, message: str, *args: object, **kwargs: object) -> None: ...
+    def error(self, message: str, *args: object, **kwargs: object) -> None: ...
+
+
+@dataclass
+class ClaudeRunOptions(RunOptions):
+    """Claude Code-specific options that extend the common RunOptions."""
+
+    allowed_tools: list[str] | None = None
+    disallowed_tools: list[str] | None = None
+    mcp_config: str | None = None
+    json_schema: str | None = None
+    max_budget_usd: float | None = None
+    resume: str | None = None
+    continue_session: bool = False
+    session_id: str | None = None
+    include_partial_messages: bool = False

agentrunner/claudecode/parser.py

@@ -0,0 +1,152 @@
+"""Parse Claude Code CLI stream-json output lines."""
+
+from __future__ import annotations
+
+import json
+
+from .types import (
+    AssistantMessage,
+    ContentBlock,
+    ContentBlockInfo,
+    Delta,
+    MessageStartData,
+    ResultUsage,
+    StreamEventInner,
+    StreamMessage,
+    StreamUsage,
+)
+
+
+def _parse_content_block(raw: dict) -> ContentBlock:
+    return ContentBlock(
+        type=raw.get("type", ""),
+        text=raw.get("text"),
+        thinking=raw.get("thinking"),
+        name=raw.get("name"),
+        input=raw.get("input"),
+        content=raw.get("content"),
+    )
+
+
+def _parse_assistant_message(raw: dict) -> AssistantMessage:
+    content = [_parse_content_block(b) for b in raw.get("content", [])]
+    return AssistantMessage(
+        model=raw.get("model"),
+        id=raw.get("id"),
+        content=content,
+        stop_reason=raw.get("stop_reason"),
+    )
+
+
+def _parse_result_usage(raw: dict) -> ResultUsage:
+    return ResultUsage(
+        input_tokens=raw.get("input_tokens", 0),
+        output_tokens=raw.get("output_tokens", 0),
+        cache_creation_input_tokens=raw.get("cache_creation_input_tokens", 0),
+        cache_read_input_tokens=raw.get("cache_read_input_tokens", 0),
+    )
+
+
+def _parse_delta(raw: dict) -> Delta:
+    return Delta(
+        type=raw.get("type"),
+        text=raw.get("text"),
+        thinking=raw.get("thinking"),
+        partial_json=raw.get("partial_json"),
+        stop_reason=raw.get("stop_reason"),
+        stop_sequence=raw.get("stop_sequence"),
+    )
+
+
+def _parse_content_block_info(raw: dict) -> ContentBlockInfo:
+    return ContentBlockInfo(
+        type=raw.get("type", ""),
+        name=raw.get("name"),
+        id=raw.get("id"),
+    )
+
+
+def _parse_stream_usage(raw: dict) -> StreamUsage:
+    return StreamUsage(
+        input_tokens=raw.get("input_tokens", 0),
+        output_tokens=raw.get("output_tokens", 0),
+    )
+
+
+def _parse_message_start_data(raw: dict) -> MessageStartData:
+    usage = None
+    if "usage" in raw and isinstance(raw["usage"], dict):
+        usage = _parse_stream_usage(raw["usage"])
+    return MessageStartData(
+        model=raw.get("model", ""),
+        id=raw.get("id", ""),
+        usage=usage,
+    )
+
+
+def _parse_stream_event(raw: dict) -> StreamEventInner | None:
+    if not isinstance(raw, dict) or not isinstance(raw.get("type"), str):
+        return None
+
+    event = StreamEventInner(type=raw["type"])
+    event.index = raw.get("index")
+
+    if "delta" in raw and isinstance(raw["delta"], dict):
+        event.delta = _parse_delta(raw["delta"])
+    if "content_block" in raw and isinstance(raw["content_block"], dict):
+        event.content_block = _parse_content_block_info(raw["content_block"])
+    if "message" in raw and isinstance(raw["message"], dict):
+        event.message = _parse_message_start_data(raw["message"])
+    if "usage" in raw and isinstance(raw["usage"], dict):
+        event.usage = _parse_stream_usage(raw["usage"])
+
+    return event
+
+
+def parse(line: str) -> StreamMessage:
+    """Parse a single JSON line into a StreamMessage.
+
+    For assistant-type lines, content blocks are lifted from the nested
+    'message' wrapper into StreamMessage.content for convenient access.
+    """
+    raw = json.loads(line)
+
+    if not isinstance(raw, dict) or not isinstance(raw.get("type"), str):
+        raise ValueError("not a valid stream message: missing type field")
+
+    msg = StreamMessage(
+        type=raw["type"],
+        subtype=raw.get("subtype"),
+        session_id=raw.get("session_id"),
+        model=raw.get("model"),
+    )
+
+    # Result fields.
+    if "result" in raw:
+        msg.result = raw["result"]
+    if "is_error" in raw:
+        msg.is_error = raw["is_error"]
+    if "total_cost_usd" in raw:
+        msg.total_cost_usd = raw["total_cost_usd"]
+    if "duration_ms" in raw:
+        msg.duration_ms = raw["duration_ms"]
+    if "duration_api_ms" in raw:
+        msg.duration_api_ms = raw["duration_api_ms"]
+    if "num_turns" in raw:
+        msg.num_turns = raw["num_turns"]
+    if "usage" in raw and isinstance(raw["usage"], dict):
+        msg.usage = _parse_result_usage(raw["usage"])
+
+    # Assistant message.
+    if "message" in raw and isinstance(raw["message"], dict):
+        msg.message = _parse_assistant_message(raw["message"])
+
+    # Lift content from assistant message.
+    if msg.type == "assistant" and msg.message and msg.message.content:
+        msg.content = msg.message.content
+
+    # Stream event.
+    if msg.type == "stream_event" and "event" in raw:
+        msg.event = _parse_stream_event(raw["event"])
+
+    return msg

agentrunner/claudecode/process.py

@@ -0,0 +1,68 @@
+"""Process helpers: logging, error collection, spawn resolution."""
+
+from __future__ import annotations
+
+import asyncio
+import shlex
+from typing import Protocol
+
+from .options import Logger
+
+
+class SpawnFn(Protocol):
+    """Function that spawns an async subprocess.
+
+    Internal protocol used for dependency injection in tests.
+    """
+
+    async def __call__(
+        self,
+        program: str,
+        *args: str,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> asyncio.subprocess.Process: ...
+
+
+def log_cmd(
+    logger: Logger | None,
+    binary: str,
+    args: list[str],
+    cwd: str | None = None,
+) -> None:
+    """Log the command about to be executed."""
+    if not logger:
+        return
+
+    cmd = " ".join(shlex.quote(a) for a in [binary, *args])
+    logger.debug("executing CLI command", extra={"cmd": cmd, "dir": cwd or ""})
+
+
+async def default_spawn(
+    program: str,
+    *args: str,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+) -> asyncio.subprocess.Process:
+    return await asyncio.create_subprocess_exec(
+        program,
+        *args,
+        cwd=cwd,
+        env=env,
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+
+def collect_error_detail(stderr: str, stdout_errors: list[str]) -> str:
+    """Build a human-readable error string from stderr and unparseable stdout lines."""
+    parts: list[str] = []
+    trimmed = stderr.strip()
+    if trimmed:
+        parts.append(trimmed)
+    if stdout_errors:
+        parts.append("\n".join(stdout_errors))
+    if not parts:
+        return "unknown error (no output from CLI)"
+    return "\n".join(parts)

agentrunner/claudecode/runner.py

@@ -0,0 +1,270 @@
+"""Claude Code runner implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import AsyncIterator
+from typing import Any
+
+from ..errors import (
+    CancelledError,
+    NonZeroExitError,
+    NoResultError,
+    NotFoundError,
+    TimeoutError,
+)
+from ..types import Message, Result
+from .args import build_args
+from .mapping import map_message_type, map_result
+from .options import ClaudeRunOptions, Logger
+from .parser import parse
+from .process import SpawnFn, collect_error_detail, default_spawn, log_cmd
+from .types import StreamMessage
+from .version import check_version
+
+
+class ClaudeSession:
+    """Session encapsulates a running Claude Code agent process.
+
+    Supports ``async for msg in session`` to iterate messages,
+    and ``await session.result`` to get the final result.
+    """
+
+    def __init__(
+        self,
+        logger: Logger | None,
+        spawn_fn: SpawnFn,
+        binary: str,
+        prompt: str,
+        options: ClaudeRunOptions,
+    ) -> None:
+        self._logger = logger
+        self._spawn_fn = spawn_fn
+        self._binary = binary
+        self._prompt = prompt
+        self._options = options
+
+        self._loop = asyncio.get_running_loop()
+        self._queue: asyncio.Queue[Message | None] = asyncio.Queue()
+        self._result_future: asyncio.Future[Result] = self._loop.create_future()
+        self._process: asyncio.subprocess.Process | None = None
+        self._aborted = False
+        self._timed_out = False
+        self._task: asyncio.Task[None] | None = None
+
+        # Launch the background task.
+        self._task = asyncio.ensure_future(self._run_process())
+
+    async def _run_process(self) -> None:
+        args = build_args(self._prompt, self._options)
+        env = {**os.environ, **self._options.env} if self._options.env else None
+
+        log_cmd(self._logger, self._binary, args, self._options.working_dir)
+
+        try:
+            self._process = await self._spawn_fn(
+                self._binary,
+                *args,
+                cwd=self._options.working_dir,
+                env=env,
+            )
+        except FileNotFoundError:
+            err = NotFoundError(f"failed to start {self._binary}: command not found")
+            self._result_future.set_exception(err)
+            await self._queue.put(None)
+            return
+
+        if self._process.stdout is None:
+            err = NotFoundError(f"failed to start {self._binary}: no stdout")
+            self._result_future.set_exception(err)
+            await self._queue.put(None)
+            return
+
+        # Set up timeout (options.timeout is in seconds).
+        timeout_handle: asyncio.TimerHandle | None = None
+        if self._options.timeout is not None and self._options.timeout > 0:
+            timeout_handle = self._loop.call_later(self._options.timeout, self._on_timeout)
+
+        init_session_id = ""
+        result_msg: StreamMessage | None = None
+        stdout_errors: list[str] = []
+
+        try:
+            while True:
+                raw_line = await self._process.stdout.readline()
+                if not raw_line:
+                    break
+
+                line = raw_line.decode("utf-8", errors="replace").rstrip("\n").rstrip("\r")
+                if not line:
+                    continue
+
+                if self._aborted or self._timed_out:
+                    break
+
+                try:
+                    parsed = parse(line)
+                except Exception:
+                    stdout_errors.append(line)
+                    continue
+
+                if parsed.type == "system" and parsed.subtype == "init" and parsed.session_id:
+                    init_session_id = parsed.session_id
+                if parsed.type == "result":
+                    result_msg = parsed
+
+                msg = Message(type=map_message_type(parsed.type, line), raw=line)
+
+                await self._queue.put(msg)
+
+            # Wait for process to finish.
+            await self._process.wait()
+
+            if timeout_handle:
+                timeout_handle.cancel()
+
+            if self._timed_out:
+                self._result_future.set_exception(TimeoutError("execution timed out"))
+                return
+
+            if self._aborted:
+                self._result_future.set_exception(CancelledError("execution cancelled"))
+                return
+
+            if result_msg:
+                self._result_future.set_result(map_result(result_msg, init_session_id))
+                return
+
+            exit_code = self._process.returncode
+            if exit_code is not None and exit_code != 0:
+                stderr_bytes = await self._process.stderr.read() if self._process.stderr else b""
+                stderr = stderr_bytes.decode("utf-8", errors="replace")
+                detail = collect_error_detail(stderr, stdout_errors)
+                if self._logger:
+                    self._logger.error(
+                        "CLI command failed",
+                        extra={
+                            "exit_code": exit_code,
+                            "stderr": stderr.strip(),
+                            "stdout_errors": stdout_errors,
+                        },
+                    )
+                self._result_future.set_exception(
+                    NonZeroExitError(exit_code, f"exit {exit_code}: {detail}")
+                )
+                return
+
+            self._result_future.set_exception(NoResultError())
+        finally:
+            await self._queue.put(None)
+            if self._process.returncode is None:
+                try:
+                    self._process.kill()
+                except ProcessLookupError:
+                    pass
+            if timeout_handle:
+                timeout_handle.cancel()
+
+    def _on_timeout(self) -> None:
+        self._timed_out = True
+        if self._process and self._process.returncode is None:
+            try:
+                self._process.kill()
+            except ProcessLookupError:
+                pass
+
+    def __aiter__(self) -> AsyncIterator[Message]:
+        return self._message_iter()
+
+    async def _message_iter(self) -> AsyncIterator[Message]:
+        while True:
+            msg = await self._queue.get()
+            if msg is None:
+                break
+            yield msg
+
+    @property
+    def result(self) -> asyncio.Future[Result]:
+        return self._result_future
+
+    def abort(self) -> None:
+        self._aborted = True
+        if self._process and self._process.returncode is None:
+            try:
+                self._process.kill()
+            except ProcessLookupError:
+                pass
+
+    def send(self, input: Any) -> None:
+        raise NotImplementedError("send is not yet supported")
+
+
+class ClaudeRunner:
+    """Claude Code runner.
+
+    Construct directly with keyword arguments::
+
+        runner = ClaudeRunner(binary="/usr/local/bin/claude", logger=my_logger)
+
+    For testing, pass ``_spawn`` to inject a fake subprocess spawner::
+
+        runner = ClaudeRunner(_spawn=my_fake_spawn)
+    """
+
+    def __init__(
+        self,
+        *,
+        binary: str = "claude",
+        logger: Logger | None = None,
+        _spawn: SpawnFn | None = None,
+    ) -> None:
+        self._binary = binary
+        self._logger = logger
+        self._spawn_fn: SpawnFn = _spawn or default_spawn
+        self._has_custom_spawn = _spawn is not None
+        self._version_checked = False
+
+    async def _ensure_version(self) -> None:
+        """Check the CLI version once per runner instance."""
+        if self._version_checked or self._has_custom_spawn:
+            return
+        await check_version(self._binary)
+        self._version_checked = True
+
+    def start(
+        self,
+        prompt: str,
+        options: ClaudeRunOptions | None = None,
+    ) -> ClaudeSession:
+        return ClaudeSession(
+            self._logger,
+            self._spawn_fn,
+            self._binary,
+            prompt,
+            options or ClaudeRunOptions(),
+        )
+
+    async def run(
+        self,
+        prompt: str,
+        options: ClaudeRunOptions | None = None,
+    ) -> Result:
+        await self._ensure_version()
+        session = self.start(prompt, options)
+        async for _msg in session:
+            pass
+        return await session.result
+
+    async def run_stream(
+        self,
+        prompt: str,
+        options: ClaudeRunOptions | None = None,
+    ) -> ClaudeSession:
+        """Start a session and return it for streaming.
+
+        The returned session is async-iterable and also provides
+        ``session.result`` and ``session.abort()``.
+        """
+        await self._ensure_version()
+        return self.start(prompt, options)