coding-agent-cli 0.1.0__py3-none-any.whl

coding_agent_cli/types.py

@@ -0,0 +1,90 @@
+"""Public value types: requests, results, usage, diagnostics, and capabilities."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from types import MappingProxyType
+
+
+class Outcome(StrEnum):
+    """How a run ended. ``retryable`` means possibly transient, not safe to replay."""
+
+    SUCCESS = "success"
+    RETRYABLE = "retryable"
+    AGENT_FATAL = "agent_fatal"
+    REQUEST_FATAL = "request_fatal"
+    CANCELLED = "cancelled"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Diagnostic:
+    code: str
+    message: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Usage:
+    """Token usage for one invocation. Unknown values are ``None``, never zero.
+
+    ``input`` includes cache reads and writes once.
+    """
+
+    input: int | None = None
+    output: int | None = None
+    cache_read: int | None = None
+    cache_write: int | None = None
+    context_used: int | None = None
+    context_window: int | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Request:
+    """One prompt for one driver. ``env`` overlays the inherited environment."""
+
+    driver: str
+    prompt: str
+    cwd: Path
+    session_id: str | None = None
+    model: str | None = None
+    reasoning: str | None = None
+    system_prompt: str | None = None
+    args: tuple[str, ...] = ()
+    env: Mapping[str, str] = field(default_factory=lambda: MappingProxyType({}))
+    timeout_s: float | None = None
+    executable: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "cwd", Path(self.cwd))
+        object.__setattr__(self, "args", tuple(self.args))
+        object.__setattr__(self, "env", MappingProxyType(dict(self.env)))
+        if self.timeout_s is not None:
+            if isinstance(self.timeout_s, bool) or not math.isfinite(self.timeout_s) or self.timeout_s <= 0:
+                raise ValueError("timeout_s must be None or a finite positive number")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Result:
+    outcome: Outcome
+    text: str = ""
+    session_id: str | None = None
+    model: str | None = None
+    usage: Usage = Usage()
+    returncode: int | None = None
+    error: Diagnostic | None = None
+    warnings: tuple[Diagnostic, ...] = ()
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Capabilities:
+    """What a driver can do on this machine. ``None`` means unverified."""
+
+    available: bool
+    executable: Path | None = None
+    structured_streaming: bool | None = None
+
+
+__all__ = ["Capabilities", "Diagnostic", "Outcome", "Request", "Result", "Usage"]

coding_agent_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: coding-agent-cli
+Version: 0.1.0
+Summary: Run coding-agent CLIs from Python, stream typed events, and get a classified result.
+Project-URL: Homepage, https://github.com/sitien173/coding-agent-cli
+Project-URL: Issues, https://github.com/sitien173/coding-agent-cli/issues
+Project-URL: Changelog, https://github.com/sitien173/coding-agent-cli/blob/main/CHANGELOG.md
+Author: sitien173
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,claude,cli,codex,coding-agent,subprocess
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# coding-agent-cli
+
+[![CI](https://github.com/sitien173/coding-agent-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/sitien173/coding-agent-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/coding-agent-cli)](https://pypi.org/project/coding-agent-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/coding-agent-cli)](https://pypi.org/project/coding-agent-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Run coding-agent CLIs from Python, stream typed events, and get a classified result.
+
+Built-in drivers: `claude`, `codex`, `pi`, and `agy`. Python 3.12 or later on Linux, macOS, and Windows. No runtime dependencies.
+
+## Install
+
+```bash
+pip install coding-agent-cli
+```
+
+The CLIs themselves are not bundled. Install and log in to each one you use.
+
+## Quick start
+
+```python
+import asyncio
+from pathlib import Path
+
+from coding_agent_cli import Request, run
+
+
+async def main() -> None:
+    result = await run(Request(driver="claude", prompt="Summarize README.md", cwd=Path.cwd()))
+    print(result.outcome, result.text)
+
+
+asyncio.run(main())
+```
+
+### Streaming events
+
+Use `stream` inside `async with`. Leaving the block, by `break` or by an exception, cancels the run and kills the process tree.
+
+```python
+from coding_agent_cli import RunCompleted, TextDelta, stream
+
+
+async def main() -> None:
+    async with stream(Request(driver="codex", prompt="List the tests", cwd=Path.cwd())) as events:
+        async for event in events:
+            if isinstance(event, TextDelta):
+                print(event.text, end="")
+            elif isinstance(event, RunCompleted):
+                print("\n", event.result.outcome)
+```
+
+`run` also accepts `on_event`, an async callback that receives the same events. An exception raised by `on_event` is raised from `run` after the process tree is killed.
+
+### Synchronous use
+
+```python
+from coding_agent_cli import run_sync
+
+result = run_sync(Request(driver="pi", prompt="Hello", cwd=Path.cwd()))
+```
+
+`run_sync` raises `RuntimeError` when called inside a running event loop. Await `run` there instead.
+
+### Checking a CLI
+
+```python
+from coding_agent_cli import check
+
+caps = await check(Request(driver="agy", prompt="", cwd=Path.cwd()))
+print(caps.available, caps.executable, caps.structured_streaming)
+```
+
+## Request
+
+| Field | Meaning |
+|---|---|
+| `driver` | Driver name, such as `claude`. |
+| `prompt` | The prompt text. |
+| `cwd` | Working directory for the CLI. |
+| `session_id` | Resume this CLI session. |
+| `model` | Portable model option. |
+| `reasoning` | Portable reasoning or effort option. |
+| `system_prompt` | Portable system prompt option. |
+| `args` | Extra CLI arguments, appended by the driver. |
+| `env` | Variables layered over the inherited environment. |
+| `timeout_s` | Wall-clock limit in seconds. |
+| `executable` | Path or name of the CLI to run instead of the default. |
+
+## Portable options
+
+| Option | claude | codex | pi | agy |
+|---|---|---|---|---|
+| `model` | `--model` | `--model` | `--model` | `--model` |
+| `reasoning` | `--effort` | `-c model_reasoning_effort=<value>` | `--thinking` | unsupported |
+| `system_prompt` | `--system-prompt` | unsupported | `--system-prompt` | unsupported |
+
+An unsupported option returns a `request_fatal` result with code `unsupported_option`. Setting a portable option and the same flag in `args` returns `invalid_args`. So does passing a flag the driver owns for its transport, such as `--output-format`.
+
+## Permission and approval flags
+
+The drivers never add a permission, approval, or sandbox-bypass flag. A run that needs tools without prompts must pass the flag through `args`:
+
+| CLI | Flag for unattended runs | Notes |
+|---|---|---|
+| claude | `--permission-mode bypassPermissions` | `--dangerously-skip-permissions` is equivalent. |
+| codex | `--dangerously-bypass-approvals-and-sandbox` | Also accepted as `--yolo`. Use only inside an external sandbox. |
+| pi | none | `--approve` trusts project-local files for the run. It is not a tool-permission bypass. |
+| agy | `--dangerously-skip-permissions` | Auto-approves all tool permission requests. |
+
+```python
+Request(driver="codex", prompt="Fix the failing test", cwd=repo, args=("--dangerously-bypass-approvals-and-sandbox",))
+```
+
+These flags give the agent full control of the machine it runs on. Use them only in an environment you are prepared to lose.
+
+## Events
+
+Every event has a `kind`, a `sequence` that strictly increases within a run, an optional `entity_id`, and a `schema_version`. Each run ends with exactly one `RunCompleted`, sent after the process tree is gone.
+
+| Class | `kind` | Fields |
+|---|---|---|
+| `SessionIdentified` | `session.identified` | `session_id` |
+| `MessageStarted` | `assistant.message.started` | none |
+| `TextDelta` | `assistant.text.delta` | `text` |
+| `MessageCompleted` | `assistant.message.completed` | none |
+| `ToolStarted` | `tool.started` | `tool`, `activity`, `input` |
+| `ToolCompleted` | `tool.completed` | `status` |
+| `UsageUpdated` | `usage.updated` | `usage` |
+| `RunCompleted` | `run.completed` | `result` |
+
+## Outcomes
+
+| `Outcome` | Meaning |
+|---|---|
+| `success` | The CLI finished and returned text. |
+| `retryable` | Possibly transient: timeout, service error, nonzero exit, or no output. |
+| `agent_fatal` | The CLI cannot run here: missing CLI, spawn failure, or authentication. |
+| `request_fatal` | The request itself is wrong: bad arguments, unsupported option, invalid model, or context overflow. |
+| `cancelled` | The caller cancelled the run. |
+
+`Result.error` holds a `Diagnostic` with a `code` and `message`. `Result.warnings` holds non-fatal diagnostics.
+
+**Retryable is not replay-safe.** A `retryable` run may already have edited files, run commands, or spent tokens. Check the working tree before you send the same prompt again.
+
+## Cancellation
+
+Pass an `asyncio.Event` as `cancel`. Setting it ends the run with a `cancelled` result that keeps any partial text. From another thread, set it through the loop:
+
+```python
+cancel = asyncio.Event()
+loop = asyncio.get_running_loop()
+# in the other thread:
+loop.call_soon_threadsafe(cancel.set)
+```
+
+## Custom drivers
+
+A driver implements the `Driver` protocol: `async check(req, *, refresh=False) -> Capabilities` and `async run(req, *, on_event, cancel, on_spawn) -> Result`. Register it in a `DriverRegistry` and pass the registry to any entry point:
+
+```python
+from coding_agent_cli import DriverRegistry
+
+registry = DriverRegistry()
+registry.register("my-cli", MyDriver())
+result = await run(Request(driver="my-cli", prompt="Hi", cwd=Path.cwd()), registry=registry)
+```
+
+`DriverRegistry(builtins=False)` starts empty. An unknown driver name raises `KeyError`.
+
+## Known limits
+
+- **Windows process trees.** Cleanup uses `taskkill /T /F`. A descendant whose launcher exits first can be missed. Job Objects are not used in 0.1.
+- **Live behavior.** The test suite uses fake CLIs. The live tests in `tests/test_live.py` run the real CLIs and are excluded by default: `uv run pytest -m live -rP`.
+
+## Contributing
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the coding standard, and the pull request process. Report security problems privately as described in [SECURITY.md](SECURITY.md). Everyone taking part follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+```bash
+uv sync
+uv run ruff format --check && uv run ruff check
+uv run pyright
+uv run pytest
+```
+
+## License
+
+[MIT](LICENSE)
+
+## Provenance
+
+This library is extracted from the CLI-driver layer of [Refract](https://github.com/sitien173/refract), a multi-model coordination tool. Its drivers, process handling, and many of its tests are ported from Refract under the MIT license.

coding_agent_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+coding_agent_cli/__init__.py,sha256=pJOCmzDrPkmYoPQ3kOAL6dvW2LqkQmacadBF1eQ7zh0,984
+coding_agent_cli/_args.py,sha256=tvhtVoSXxEUETHU15NXYa0bdeMN8A7ATiTzwPsgpj6E,2658
+coding_agent_cli/_classify.py,sha256=XDfAbffiUxiil7hKsxRag4NZDOmVLbqv8fYujGKcBpY,5968
+coding_agent_cli/_platform.py,sha256=XDLr8fdWwhIUOjPL-3NUSoxtGKofftIpbx2IkEURaXE,5853
+coding_agent_cli/_process.py,sha256=2qxwlXxS4aMo_ZhkLAcCM70EUsE1u-twkTn53aHCnNk,12135
+coding_agent_cli/api.py,sha256=eGRlWhhYySw4mNcuQHQ1uZ-BNuEbcshr6GpGklJF9MQ,6461
+coding_agent_cli/events.py,sha256=5PtWqj86L6BYjUWAeo-gM-UdERR274QzITzJ9w8Wq6c,2637
+coding_agent_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+coding_agent_cli/registry.py,sha256=f4ATw4FyXUlFlQS1Czdus7hctuxXq46PWwvGLpbUEQM,2146
+coding_agent_cli/types.py,sha256=frJle_B0eNIwA9N96KO63p9K0ZTBLmolo-i5AaWnhWA,2677
+coding_agent_cli/_drivers/__init__.py,sha256=HbBnDjil7mpdJneUR6s2H-YkeHaf4byOCoSO_yP5Qmg,71
+coding_agent_cli/_drivers/_common.py,sha256=ExMTkqK0dhSD3wxKRST9XbpJ7_Cd_VG0BvM58wIDbIY,11224
+coding_agent_cli/_drivers/_usage.py,sha256=AIPCXjLVRIOF68L810mWLGg_-BYGTIAQrSuuZIWS-fg,2565
+coding_agent_cli/_drivers/agy.py,sha256=cW0cyF6Ln1c3thzpoI_umY0cr47tcT5SNPC5Alpl3bc,13249
+coding_agent_cli/_drivers/claude.py,sha256=CJmcyBbagmNc2WW2nU6MuG_tB4EMa7xEVf0qom9CW1Q,11183
+coding_agent_cli/_drivers/codex.py,sha256=SBWz9ZDcJLBDyCF8fB7K56V2fKQtgo_RC-i91pX60Yo,13071
+coding_agent_cli/_drivers/codex_rollout.py,sha256=kiAmJj638SKi3C7q_jHI3qWFoC95pjSgetiWTuCSZWM,16015
+coding_agent_cli/_drivers/pi.py,sha256=CcTNnLLVisI60OJds87aPKcuQyLlHgEHuFTif71iljY,12279
+coding_agent_cli-0.1.0.dist-info/METADATA,sha256=c5FJ7TDI228jkt7_svawoYPrlkOwV7S3jNP4cIz_Ch0,8720
+coding_agent_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+coding_agent_cli-0.1.0.dist-info/licenses/LICENSE,sha256=QVZC8PROzGZpwHMdk5lfzO7ZKkamSU7ktYCKw9fOPG4,1066
+coding_agent_cli-0.1.0.dist-info/RECORD,,

coding_agent_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

coding_agent_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sitien173
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.