driangle-agentrunner 0.0.1__tar.gz

driangle_agentrunner-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+settings.local.json
+node_modules
+dist
+docs/.vitepress/dist
+docs/.vitepress/cache
+__pycache__/
+*.pyc
+
+# Compiled Go binaries
+examples/go/claudecode/claudecode
+examples/go/ollama/ollama
+
+# Platform binaries (placed by CI before publishing)
+npm/*/bin/
+python/channel/src/agentrunner_channel/bin/

driangle_agentrunner-0.0.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: driangle-agentrunner
+Version: 0.0.1
+Summary: Python library for programmatically invoking AI coding agents
+Project-URL: Homepage, https://github.com/driangle/agentrunner
+Project-URL: Repository, https://github.com/driangle/agentrunner
+Project-URL: Issues, https://github.com/driangle/agentrunner/issues
+Author: driangle
+License-Expression: MIT
+Requires-Python: >=3.11
+Provides-Extra: channel
+Requires-Dist: agentrunner-channel>=0.0.1; extra == 'channel'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentrunner (Python)
+
+Python library for programmatically invoking AI coding agents. Part of the [agentrunner](../) monorepo.
+
+## Supported CLIs
+
+| Runner      | CLI Version | Status |
+|-------------|-------------|--------|
+| Claude Code | >= 1.0.12   | ✅      |
+
+## Requirements
+
+- Python >= 3.11
+- Claude Code CLI >= 1.0.12
+
+## Installation
+
+```bash
+pip install agentrunner
+```
+
+## Quick Start
+
+```python
+import asyncio
+from agentrunner.claudecode import create_claude_runner, ClaudeRunOptions
+
+runner = create_claude_runner()
+
+async def main():
+    # Simple run
+    result = await runner.run("What files are in this directory?", ClaudeRunOptions(
+        working_dir="/path/to/project",
+        skip_permissions=True,
+    ))
+    print(result.text)
+
+    # Streaming
+    stream = await runner.run_stream("Explain this codebase")
+    async for message in stream:
+        print(message.type, message.raw)
+
+asyncio.run(main())
+```
+
+## API
+
+### `create_claude_runner(config?)`
+
+Creates a runner for the Claude Code CLI.
+
+**Config options (`ClaudeRunnerConfig`):**
+
+| Field    | Type       | Default    | Description                          |
+|----------|------------|------------|--------------------------------------|
+| `binary` | `str`      | `"claude"` | CLI binary name or path              |
+| `spawn`  | `SpawnFn`  | —          | Custom spawn function (for testing)  |
+| `logger` | `Logger`   | —          | Logger for debug output (opt-in)     |
+
+### `runner.run(prompt, options?)`
+
+Execute a prompt and return the final `Result`.
+
+### `runner.run_stream(prompt, options?)`
+
+Execute a prompt and stream messages as they arrive. Returns `AsyncIterable[Message]`.
+
+### `runner.start(prompt, options?)`
+
+Launch an agent process and return a `Session` for full lifecycle control.
+
+### Run Options
+
+Common options (`RunOptions`):
+
+| Field                 | Type             | Description                          |
+|-----------------------|------------------|--------------------------------------|
+| `model`               | `str`            | Model name or alias                  |
+| `system_prompt`       | `str`            | System prompt override               |
+| `append_system_prompt`| `str`            | Appended to default system prompt    |
+| `working_dir`         | `str`            | Working directory for subprocess     |
+| `env`                 | `dict[str, str]` | Additional environment variables     |
+| `max_turns`           | `int`            | Maximum agentic turns                |
+| `timeout`             | `float`          | Timeout in milliseconds              |
+| `skip_permissions`    | `bool`           | Skip permission prompts              |
+
+Claude-specific options (`ClaudeRunOptions` extends `RunOptions`):
+
+| Field                    | Type        | Description                        |
+|--------------------------|-------------|------------------------------------|
+| `allowed_tools`          | `list[str]` | Tools the agent may use            |
+| `disallowed_tools`       | `list[str]` | Tools the agent may not use        |
+| `mcp_config`             | `str`       | Path to MCP server config          |
+| `json_schema`            | `str`       | JSON Schema for structured output  |
+| `max_budget_usd`         | `float`     | Cost limit in USD                  |
+| `resume`                 | `str`       | Session ID to resume               |
+| `continue_session`       | `bool`      | Continue most recent session       |
+| `session_id`             | `str`       | Specific session ID                |
+| `include_partial_messages`| `bool`     | Stream partial/incremental messages|
+| `on_message`             | `callable`  | Callback for each streamed message |
+
+### Result
+
+| Field        | Type    | Description                     |
+|--------------|---------|---------------------------------|
+| `text`       | `str`   | Final response text             |
+| `is_error`   | `bool`  | Whether the run ended in error  |
+| `exit_code`  | `int`   | Process exit code               |
+| `usage`      | `Usage` | Token counts                    |
+| `cost_usd`   | `float` | Estimated cost in USD           |
+| `duration_ms`| `float` | Wall-clock duration in ms       |
+| `session_id` | `str`   | Session ID for resumption       |
+
+### Session
+
+| Attribute  | Type                     | Description                           |
+|------------|--------------------------|---------------------------------------|
+| `messages` | `AsyncIterable[Message]` | Iterate messages as they arrive       |
+| `result`   | `Future[Result]`         | Resolves when the agent finishes      |
+| `abort()`  | —                        | Terminate the agent process           |
+| `send()`   | —                        | Reserved (raises `RuntimeError`)      |
+
+### Error Classes
+
+All errors extend `RunnerError`:
+
+- `NotFoundError` — CLI binary not found
+- `TimeoutError` — execution timed out
+- `NonZeroExitError` — CLI exited with non-zero code (has `.exit_code`)
+- `ParseError` — failed to parse CLI output
+- `CancelledError` — execution cancelled
+- `NoResultError` — stream ended without a result message
+
+```python
+from agentrunner import TimeoutError
+
+try:
+    await runner.run("complex task", ClaudeRunOptions(timeout=30_000))
+except TimeoutError:
+    print("Timed out!")
+```
+
+## Usage Examples
+
+### Session Resume
+
+```python
+# First run — capture the session ID.
+result = await runner.run("Set up the project structure")
+session_id = result.session_id
+
+# Resume the same session later.
+result = await runner.run("Now add tests", ClaudeRunOptions(resume=session_id))
+```
+
+### Session Object
+
+```python
+session = runner.start("Explain this code", ClaudeRunOptions(max_turns=1, timeout=30_000))
+
+async for msg in session.messages:
+    print(f"[{msg.type}] {msg.raw[:80]}")
+
+result = await session.result
+print(f"Response: {result.text}")
+```
+
+### Streaming with Partial Messages
+
+```python
+from agentrunner.claudecode import parse
+
+stream = await runner.run_stream("List fun facts", ClaudeRunOptions(
+    include_partial_messages=True,
+))
+async for msg in stream:
+    if msg.type == "assistant":
+        parsed = parse(msg.raw)
+        if parsed.type == "stream_event":
+            import json
+            raw = json.loads(msg.raw)
+            delta = raw.get("event", {}).get("delta", {})
+            if delta.get("type") == "text_delta":
+                print(delta["text"], end="", flush=True)
+```
+
+## Development
+
+```bash
+cd python
+pip install -e ".[dev]"   # install with dev dependencies
+ruff check src/ tests/    # lint
+python -m pytest           # run tests
+```
+
+Or from the repo root:
+
+```bash
+make check-python  # build + lint + test
+make check         # all libraries
+```

driangle_agentrunner-0.0.1/README.md

@@ -0,0 +1,201 @@
+# agentrunner (Python)
+
+Python library for programmatically invoking AI coding agents. Part of the [agentrunner](../) monorepo.
+
+## Supported CLIs
+
+| Runner      | CLI Version | Status |
+|-------------|-------------|--------|
+| Claude Code | >= 1.0.12   | ✅      |
+
+## Requirements
+
+- Python >= 3.11
+- Claude Code CLI >= 1.0.12
+
+## Installation
+
+```bash
+pip install agentrunner
+```
+
+## Quick Start
+
+```python
+import asyncio
+from agentrunner.claudecode import create_claude_runner, ClaudeRunOptions
+
+runner = create_claude_runner()
+
+async def main():
+    # Simple run
+    result = await runner.run("What files are in this directory?", ClaudeRunOptions(
+        working_dir="/path/to/project",
+        skip_permissions=True,
+    ))
+    print(result.text)
+
+    # Streaming
+    stream = await runner.run_stream("Explain this codebase")
+    async for message in stream:
+        print(message.type, message.raw)
+
+asyncio.run(main())
+```
+
+## API
+
+### `create_claude_runner(config?)`
+
+Creates a runner for the Claude Code CLI.
+
+**Config options (`ClaudeRunnerConfig`):**
+
+| Field    | Type       | Default    | Description                          |
+|----------|------------|------------|--------------------------------------|
+| `binary` | `str`      | `"claude"` | CLI binary name or path              |
+| `spawn`  | `SpawnFn`  | —          | Custom spawn function (for testing)  |
+| `logger` | `Logger`   | —          | Logger for debug output (opt-in)     |
+
+### `runner.run(prompt, options?)`
+
+Execute a prompt and return the final `Result`.
+
+### `runner.run_stream(prompt, options?)`
+
+Execute a prompt and stream messages as they arrive. Returns `AsyncIterable[Message]`.
+
+### `runner.start(prompt, options?)`
+
+Launch an agent process and return a `Session` for full lifecycle control.
+
+### Run Options
+
+Common options (`RunOptions`):
+
+| Field                 | Type             | Description                          |
+|-----------------------|------------------|--------------------------------------|
+| `model`               | `str`            | Model name or alias                  |
+| `system_prompt`       | `str`            | System prompt override               |
+| `append_system_prompt`| `str`            | Appended to default system prompt    |
+| `working_dir`         | `str`            | Working directory for subprocess     |
+| `env`                 | `dict[str, str]` | Additional environment variables     |
+| `max_turns`           | `int`            | Maximum agentic turns                |
+| `timeout`             | `float`          | Timeout in milliseconds              |
+| `skip_permissions`    | `bool`           | Skip permission prompts              |
+
+Claude-specific options (`ClaudeRunOptions` extends `RunOptions`):
+
+| Field                    | Type        | Description                        |
+|--------------------------|-------------|------------------------------------|
+| `allowed_tools`          | `list[str]` | Tools the agent may use            |
+| `disallowed_tools`       | `list[str]` | Tools the agent may not use        |
+| `mcp_config`             | `str`       | Path to MCP server config          |
+| `json_schema`            | `str`       | JSON Schema for structured output  |
+| `max_budget_usd`         | `float`     | Cost limit in USD                  |
+| `resume`                 | `str`       | Session ID to resume               |
+| `continue_session`       | `bool`      | Continue most recent session       |
+| `session_id`             | `str`       | Specific session ID                |
+| `include_partial_messages`| `bool`     | Stream partial/incremental messages|
+| `on_message`             | `callable`  | Callback for each streamed message |
+
+### Result
+
+| Field        | Type    | Description                     |
+|--------------|---------|---------------------------------|
+| `text`       | `str`   | Final response text             |
+| `is_error`   | `bool`  | Whether the run ended in error  |
+| `exit_code`  | `int`   | Process exit code               |
+| `usage`      | `Usage` | Token counts                    |
+| `cost_usd`   | `float` | Estimated cost in USD           |
+| `duration_ms`| `float` | Wall-clock duration in ms       |
+| `session_id` | `str`   | Session ID for resumption       |
+
+### Session
+
+| Attribute  | Type                     | Description                           |
+|------------|--------------------------|---------------------------------------|
+| `messages` | `AsyncIterable[Message]` | Iterate messages as they arrive       |
+| `result`   | `Future[Result]`         | Resolves when the agent finishes      |
+| `abort()`  | —                        | Terminate the agent process           |
+| `send()`   | —                        | Reserved (raises `RuntimeError`)      |
+
+### Error Classes
+
+All errors extend `RunnerError`:
+
+- `NotFoundError` — CLI binary not found
+- `TimeoutError` — execution timed out
+- `NonZeroExitError` — CLI exited with non-zero code (has `.exit_code`)
+- `ParseError` — failed to parse CLI output
+- `CancelledError` — execution cancelled
+- `NoResultError` — stream ended without a result message
+
+```python
+from agentrunner import TimeoutError
+
+try:
+    await runner.run("complex task", ClaudeRunOptions(timeout=30_000))
+except TimeoutError:
+    print("Timed out!")
+```
+
+## Usage Examples
+
+### Session Resume
+
+```python
+# First run — capture the session ID.
+result = await runner.run("Set up the project structure")
+session_id = result.session_id
+
+# Resume the same session later.
+result = await runner.run("Now add tests", ClaudeRunOptions(resume=session_id))
+```
+
+### Session Object
+
+```python
+session = runner.start("Explain this code", ClaudeRunOptions(max_turns=1, timeout=30_000))
+
+async for msg in session.messages:
+    print(f"[{msg.type}] {msg.raw[:80]}")
+
+result = await session.result
+print(f"Response: {result.text}")
+```
+
+### Streaming with Partial Messages
+
+```python
+from agentrunner.claudecode import parse
+
+stream = await runner.run_stream("List fun facts", ClaudeRunOptions(
+    include_partial_messages=True,
+))
+async for msg in stream:
+    if msg.type == "assistant":
+        parsed = parse(msg.raw)
+        if parsed.type == "stream_event":
+            import json
+            raw = json.loads(msg.raw)
+            delta = raw.get("event", {}).get("delta", {})
+            if delta.get("type") == "text_delta":
+                print(delta["text"], end="", flush=True)
+```
+
+## Development
+
+```bash
+cd python
+pip install -e ".[dev]"   # install with dev dependencies
+ruff check src/ tests/    # lint
+python -m pytest           # run tests
+```
+
+Or from the repo root:
+
+```bash
+make check-python  # build + lint + test
+make check         # all libraries
+```

driangle_agentrunner-0.0.1/channel/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentrunner-channel"
+version = "0.0.1"
+description = "agentrunner-channel binary distribution"
+requires-python = ">=3.11"
+license = "MIT"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentrunner_channel"]
+
+[tool.hatch.build]
+artifacts = ["src/agentrunner_channel/bin/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

driangle_agentrunner-0.0.1/channel/src/agentrunner_channel/__init__.py

@@ -0,0 +1,41 @@
+"""Resolve the agentrunner-channel binary path."""
+
+import os
+import platform
+import shutil
+from pathlib import Path
+
+
+def binary_path() -> str:
+    """Return the path to the agentrunner-channel binary.
+
+    Resolution order:
+        1. AGENTRUNNER_CHANNEL_BIN environment variable
+        2. Bundled binary in this package's bin/ directory
+        3. agentrunner-channel on $PATH
+
+    Raises:
+        FileNotFoundError: if the binary cannot be found.
+    """
+    env_path = os.environ.get("AGENTRUNNER_CHANNEL_BIN")
+    if env_path:
+        return env_path
+
+    name = (
+        "agentrunner-channel.exe"
+        if platform.system() == "Windows"
+        else "agentrunner-channel"
+    )
+    bundled = Path(__file__).parent / "bin" / name
+    if bundled.exists():
+        return str(bundled)
+
+    found = shutil.which("agentrunner-channel")
+    if found:
+        return found
+
+    raise FileNotFoundError(
+        "agentrunner-channel binary not found. "
+        "Install the agentrunner-channel package for your platform, "
+        "add it to $PATH, or set AGENTRUNNER_CHANNEL_BIN."
+    )

driangle_agentrunner-0.0.1/channel/tests/test_binary.py

@@ -0,0 +1,19 @@
+"""Tests for channel binary resolution."""
+
+import os
+
+import pytest
+
+from agentrunner_channel import binary_path
+
+
+class TestBinaryPath:
+    def test_env_override(self, monkeypatch):
+        monkeypatch.setenv("AGENTRUNNER_CHANNEL_BIN", "/custom/agentrunner-channel")
+        assert binary_path() == "/custom/agentrunner-channel"
+
+    def test_not_found_raises(self, monkeypatch):
+        monkeypatch.delenv("AGENTRUNNER_CHANNEL_BIN", raising=False)
+        monkeypatch.setattr("shutil.which", lambda _: None)
+        with pytest.raises(FileNotFoundError, match="agentrunner-channel binary not found"):
+            binary_path()

driangle_agentrunner-0.0.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "driangle-agentrunner"
+version = "0.0.1"
+description = "Python library for programmatically invoking AI coding agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "driangle" },
+]
+
+[project.urls]
+Homepage = "https://github.com/driangle/agentrunner"
+Repository = "https://github.com/driangle/agentrunner"
+Issues = "https://github.com/driangle/agentrunner/issues"
+
+[project.optional-dependencies]
+channel = [
+    "agentrunner-channel>=0.0.1",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentrunner"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]

driangle_agentrunner-0.0.1/src/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",
+]

driangle_agentrunner-0.0.1/src/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",
+]

driangle_agentrunner-0.0.1/src/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