coding-agent-cli 0.1.0__tar.gz

coding_agent_cli-0.1.0/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,md}]
+indent_size = 2

coding_agent_cli-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,31 @@
+name: Bug report
+description: Something does not work as documented
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: Include the `Result.outcome` and `Result.error` if relevant. Remove prompts, tokens, and private paths.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: coding-agent-cli, Python, OS, and the CLI's `--version` output
+    validations:
+      required: true

coding_agent_cli-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/sitien173/coding-agent-cli/security/advisories/new
+    about: Report security problems privately.

coding_agent_cli-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,17 @@
+name: Feature request
+description: Suggest a new driver, option, or behavior
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do, and what blocks you today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+    validations:
+      required: true

coding_agent_cli-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## Summary
+
+<!-- What changes and why. Link the issue: Fixes #123 -->
+
+## Checklist
+
+- [ ] `uv run ruff format --check`, `uv run ruff check`, `uv run pyright`, and `uv run pytest` pass
+- [ ] Tests cover the change
+- [ ] PR title follows Conventional Commits, such as `feat: add X` or `fix(codex): handle Y`
+- [ ] README updated if public behavior or signatures changed
+- [ ] No driver adds a permission, approval, or sandbox-bypass flag

coding_agent_cli-0.1.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

coding_agent_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - run: uv run ruff format --check
+      - run: uv run ruff check
+      - run: uv run pyright
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, python: "3.12" }
+          - { os: macos-latest, python: "3.12" }
+          - { os: windows-latest, python: "3.12" }
+          - { os: ubuntu-latest, python: "3.13" }
+          - { os: ubuntu-latest, python: "3.14" }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run pytest
+      - run: uv run pyright

coding_agent_cli-0.1.0/.github/workflows/pr-title.yml

@@ -0,0 +1,18 @@
+name: PR title
+
+# Squash merges use the PR title as the commit message, and release-please reads those commits.
+
+on:
+  pull_request_target:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  conventional:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

coding_agent_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,116 @@
+name: Release
+
+# Pushes to main run release-please, which keeps a release PR open with the next version and changelog.
+# Merging that PR creates the tag and GitHub Release, then this workflow builds and publishes to PyPI.
+# Pushing a v* tag by hand also publishes; use it for the first release.
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@v5
+      # release-please bumps pyproject.toml but not uv.lock, so `uv sync --locked` would fail on the release PR.
+      - if: steps.release.outputs.pr
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ fromJSON(steps.release.outputs.pr).headBranchName }}
+      - if: steps.release.outputs.pr
+        uses: astral-sh/setup-uv@v10.3.3
+      - if: steps.release.outputs.pr
+        run: |
+          uv lock
+          if ! git diff --quiet uv.lock; then
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git commit -am "chore: update uv.lock for release"
+            git push
+          fi
+
+  build:
+    needs: release-please
+    if: >-
+      !failure() && !cancelled() &&
+      (needs.release-please.outputs.release_created == 'true' || startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.tag.outputs.tag }}
+    steps:
+      - id: tag
+        run: echo "tag=${RP_TAG:-$GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+        env:
+          RP_TAG: ${{ needs.release-please.outputs.tag_name }}
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ steps.tag.outputs.tag }}
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          python-version: "3.12"
+      - name: Check tag matches package version
+        run: |
+          version=$(uv version --short)
+          test "v$version" = "$TAG" || { echo "::error::tag $TAG does not match version $version"; exit 1; }
+        env:
+          TAG: ${{ steps.tag.outputs.tag }}
+      - run: uv sync --locked
+      - run: uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    if: ${{ !failure() && !cancelled() && needs.build.result == 'success' }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/coding-agent-cli/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.3
+
+  github-release:
+    needs: [build, publish]
+    if: ${{ !failure() && !cancelled() && needs.publish.result == 'success' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Attach artifacts, creating the release for hand-pushed tags
+        run: |
+          gh release view "$TAG" >/dev/null 2>&1 || gh release create "$TAG" --verify-tag --generate-notes --title "$TAG"
+          gh release upload "$TAG" dist/* --clobber
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ needs.build.outputs.tag }}

coding_agent_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

coding_agent_cli-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

coding_agent_cli-0.1.0/AGENTS.md

@@ -0,0 +1,47 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository. Humans should read [CONTRIBUTING.md](CONTRIBUTING.md), which this file follows.
+
+## Project
+
+`coding-agent-cli` is a stdlib-only Python 3.12+ library. It runs coding-agent CLIs (`claude`, `codex`, `pi`, `agy`) as subprocesses, streams typed events, and returns a classified `Result`.
+
+## Layout
+
+| Path | Contents |
+|---|---|
+| `src/coding_agent_cli/api.py` | Public entry points: `run`, `stream`, `run_sync`, `check` |
+| `src/coding_agent_cli/types.py`, `events.py` | Public frozen dataclasses |
+| `src/coding_agent_cli/registry.py` | `Driver` protocol and `DriverRegistry` |
+| `src/coding_agent_cli/_process.py`, `_platform.py` | Subprocess transport and process-tree kill |
+| `src/coding_agent_cli/_args.py`, `_classify.py` | Argument validation and outcome classification |
+| `src/coding_agent_cli/_drivers/` | Built-in drivers and shared `CliDriver` helpers |
+| `tests/fixtures/fake_cli/` | Fake CLIs used by all unit tests |
+| `docs/plans/coding-agent-cli/` | Design, plan, and phase journals |
+
+## Commands
+
+Prefix uv commands with `export VIRTUAL_ENV=;` if a foreign virtualenv is active.
+
+```bash
+uv sync
+uv run ruff format && uv run ruff check --fix
+uv run pyright
+uv run pytest
+```
+
+All four must pass before you finish. Do not run `pytest -m live` unless asked; it calls real CLIs and spends tokens.
+
+## Hard rules
+
+- Never add a runtime dependency.
+- Never make a driver add a permission, approval, or sandbox-bypass flag.
+- Never log prompts, argv, or environment values.
+- Every exit path must kill the process tree and delete temp files.
+- Reuse helpers in `_drivers/_common.py` and `_args.py` before writing new ones.
+- Keep public signatures in sync with the README examples.
+- Do not push, tag, or publish.
+
+## Style
+
+Follow the coding standard in [CONTRIBUTING.md](CONTRIBUTING.md#coding-standard). Match the surrounding code. Keep diffs minimal and add a test for every behavior change.

coding_agent_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+First release. Extracted from the CLI-driver layer of Refract.
+
+- `run`, `stream`, `run_sync`, and `check` entry points for running coding-agent CLIs from Python.
+- Typed events with a strictly increasing `sequence`, ending with exactly one `RunCompleted`.
+- A classified `Result` with `Outcome` and `Diagnostic`.
+- Built-in drivers for `claude`, `pi`, `codex`, and `agy`, and a `DriverRegistry` for custom drivers.
+- Process-tree cleanup on completion, cancel, timeout, and callback failure.
+- No permission or approval flag is ever added; callers pass them through `args`.

coding_agent_cli-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

coding_agent_cli-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Expected behavior
+
+- Show empathy and kindness toward other people.
+- Respect differing opinions, viewpoints, and experiences.
+- Give and gracefully accept constructive feedback.
+- Take responsibility for mistakes and learn from them.
+
+## Unacceptable behavior
+
+- Sexualized language or imagery, and sexual attention or advances of any kind.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information without their explicit permission.
+- Other conduct that could reasonably be considered inappropriate in a professional setting.
+
+## Reporting
+
+Report unacceptable behavior to the maintainer, [@sitien173](https://github.com/sitien173), by private contact through GitHub. You can also use GitHub's [report content](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) feature. Reports are reviewed promptly and kept confidential.
+
+## Enforcement
+
+The maintainer may remove, edit, or reject comments, commits, code, issues, and other contributions that violate this code, and may warn, suspend, or ban contributors. The full enforcement guidelines are in the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/#enforcement-guidelines).

coding_agent_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing
+
+Thanks for helping improve coding-agent-cli. This guide covers setup, the coding standard, and how changes get merged.
+
+## Ground rules
+
+- Be respectful. All participation follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+- Report security problems privately. See [SECURITY.md](SECURITY.md). Do not open a public issue.
+- Open an issue before a large change, so the design can be agreed first.
+
+## Setup
+
+You need Python 3.12 or later and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/sitien173/coding-agent-cli.git
+cd coding-agent-cli
+uv sync
+```
+
+## Checks
+
+Every pull request must pass the same checks CI runs:
+
+```bash
+uv run ruff format --check
+uv run ruff check
+uv run pyright
+uv run pytest
+```
+
+`uv run ruff format` and `uv run ruff check --fix` correct most style problems.
+
+Live tests run the real CLIs and are excluded by default. Run them only with the CLIs installed and logged in:
+
+```bash
+uv run pytest -m live -rP
+```
+
+## Coding standard
+
+### Style
+
+- Ruff formats and lints the code. The line length is 120. Configuration lives in `pyproject.toml`.
+- Pyright checks types. New code is fully annotated, and `pyright` must report 0 errors.
+- Write `from __future__ import annotations` at the top of each module.
+- Public names are listed in `__all__`. Modules and names that start with `_` are private.
+
+### Design rules
+
+- **No runtime dependencies.** The library uses the standard library only.
+- **No implicit permissions.** A driver never adds a permission, approval, or sandbox-bypass flag. Callers pass these through `Request.args`.
+- **No leaked processes.** Every exit path kills the CLI's whole process tree: completion, cancel, timeout, and a raising callback.
+- **No sensitive logging.** Never log prompts, argv, or environment values.
+- **Typed, frozen values.** Requests, results, and events are frozen dataclasses. Unknown values are `None`, never zero.
+- **One `RunCompleted`.** Each run emits exactly one, last, after the process tree is gone, with a strictly increasing `sequence`.
+
+### Tests
+
+- Every behavior change comes with a test. Write the failing test first when you can.
+- Tests use the fake CLIs in `tests/fixtures/fake_cli`. Unit tests never call a real coding-agent CLI.
+- A new driver needs argv tests proving it adds no permission flag for any option combination.
+
+### Adding a driver
+
+1. Subclass `CliDriver` in `src/coding_agent_cli/_drivers/`. Follow `claude.py` or `pi.py`.
+2. Declare the driver-owned transport flags and the `portable_flags` it supports.
+3. Register it in `_builtin_drivers()` in `registry.py`.
+4. Add a driver test module, argv policy tests, and a row in each README table.
+
+## Commits and pull requests
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`. Mark breaking changes with `!`, as in `feat!:`.
+- Pull requests are squash-merged, so the PR title becomes the commit message. A check enforces the Conventional Commits format on PR titles.
+- Keep each pull request to one change. Every changed line should trace to that change.
+- Do not edit `CHANGELOG.md` or the version by hand. Both are generated from commit messages at release time.
+- Fill in the pull request template.
+
+## Releases
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please):
+
+1. Each push to `main` updates an open release PR. It bumps the version in `pyproject.toml`, `__init__.py`, and `uv.lock`, and adds the changelog entry.
+2. While the version is below 1.0, `feat:` bumps the minor version and `fix:` bumps the patch version. A breaking change also bumps the minor version.
+3. A maintainer merges the release PR when ready. The workflow tags `vX.Y.Z`, creates the GitHub Release, tests, builds, publishes to PyPI through trusted publishing, and attaches the wheel and sdist to the release.
+
+Publishing waits for approval on the `pypi` environment. Pushing a `vX.Y.Z` tag by hand runs the same build and publish; the tag must match the version in `pyproject.toml`.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the [MIT License](LICENSE).

coding_agent_cli-0.1.0/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.