subagent-cli 0.1.1__tar.gz

subagent_cli-0.1.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build artifacts
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/subagent-cli/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

subagent_cli-0.1.1/.gitignore

@@ -0,0 +1,25 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.pytest_cache/
+
+# Virtual environments
+.venv
+
+# Local runtime artifacts
+.subagent/
+subagentd-status.json
+*.pid
+
+# Local AI agent work logs (not tracked)
+.agent-logs/
+.ai-worklog/
+worklog.local.md
+.internal/
+
+# Packaging / publishing local files
+.pypirc

subagent_cli-0.1.1/.python-version

@@ -0,0 +1 @@
+3.11

subagent_cli-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for contributing to `subagent-cli`.
+
+## Development Setup
+1. Install Python 3.11+ and `uv`.
+2. Sync dependencies:
+`uv sync`
+3. Run tests:
+`PYTHONPATH=src uv run python -m unittest discover -s tests -v`
+
+## Pull Request Checklist
+- Add or update tests for behavior changes.
+- Keep CLI/user-facing docs in sync (`README.md`, `docs/`).
+- Confirm all tests pass locally.
+
+## Release (Maintainers)
+### Trusted Publishing (recommended)
+1. Ensure version is updated (`pyproject.toml`, and package version if needed).
+2. Push the release commit and tag (for example `v0.1.1`).
+3. Create a GitHub Release from that tag.
+4. The workflow `.github/workflows/publish-pypi.yml` builds and publishes to PyPI via OIDC.
+
+PyPI trusted publisher settings should match:
+- Owner: `otakumesi`
+- Repository: `subagent-cli`
+- Workflow: `publish-pypi.yml`
+- Environment: `pypi`
+
+### Manual token-based publish (fallback)
+1. Build artifacts:
+`uv build`
+2. Validate package metadata:
+`uv run --group release python -m twine check dist/*`
+3. Upload to PyPI:
+`uv run --group release python -m twine upload dist/*`
+
+Notes:
+- Python requirement is 3.11+.
+- Keep PyPI credentials/tokens in local config (for example `.pypirc`, gitignored).

subagent_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 niitsuma-t
+
+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.

subagent_cli-0.1.1/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: subagent-cli
+Version: 0.1.1
+Summary: Protocol-agnostic worker orchestration CLI
+Author: niitsuma-t
+License: MIT License
+        
+        Copyright (c) 2026 niitsuma-t
+        
+        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.
+License-File: LICENSE
+Keywords: acp,agent,automation,cli,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
+# subagent-cli
+
+`subagent-cli` is a protocol-agnostic CLI for orchestrating worker agents from a parent controller.
+In practice, it is a control-plane CLI that a manager agent (for example Codex or Claude Code) can use to launch and coordinate other worker agents.
+The CLI surface is protocol-agnostic, while the current runtime implementation is ACP-based (`acp-stdio`).
+
+## Status
+- Alpha (`v0.1.x`)
+- Local single-host focused
+- Python 3.11+
+
+## Features
+- Worker lifecycle: start, list, show, inspect, stop
+- Turn operations: send, watch, wait, approve, cancel
+- Handoff workflow: `worker handoff` and `worker continue`
+- Strict approval flow with structured events
+- ACP runtime integration (`acp-stdio`) with runtime restart + session resume (`session/load`)
+
+## Install
+- From PyPI:
+`pip install subagent-cli`
+- From local artifacts:
+`pip install dist/subagent_cli-*.whl`
+
+## Quick Start
+1. Prepare config:
+`mkdir -p ~/.config/subagent && cp config.example.yaml ~/.config/subagent/config.yaml`
+2. Initialize a controller in your workspace:
+`subagent controller init --cwd .`
+3. Start a worker:
+`subagent worker start --cwd .`
+4. Send an instruction:
+`subagent send --worker <worker-id> --text "Investigate failing tests"`
+5. Watch events:
+`subagent watch --worker <worker-id> --ndjson`
+
+For local simulation/testing without a real ACP launcher:
+`subagent worker start --cwd . --debug-mode`
+
+## Configuration
+- Default config path: `~/.config/subagent/config.yaml`
+- Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
+- Example config: [config.example.yaml](config.example.yaml)
+
+## State
+- Default state DB: `~/.local/share/subagent/state.db`
+- Project hint file: `<workspace>/.subagent/controller.json`
+
+## Documentation
+- Architecture note: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Examples: [docs/examples](docs/examples)
+- Contributing and release process: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+MIT ([LICENSE](LICENSE))

subagent_cli-0.1.1/README.md

@@ -0,0 +1,55 @@
+# subagent-cli
+
+`subagent-cli` is a protocol-agnostic CLI for orchestrating worker agents from a parent controller.
+In practice, it is a control-plane CLI that a manager agent (for example Codex or Claude Code) can use to launch and coordinate other worker agents.
+The CLI surface is protocol-agnostic, while the current runtime implementation is ACP-based (`acp-stdio`).
+
+## Status
+- Alpha (`v0.1.x`)
+- Local single-host focused
+- Python 3.11+
+
+## Features
+- Worker lifecycle: start, list, show, inspect, stop
+- Turn operations: send, watch, wait, approve, cancel
+- Handoff workflow: `worker handoff` and `worker continue`
+- Strict approval flow with structured events
+- ACP runtime integration (`acp-stdio`) with runtime restart + session resume (`session/load`)
+
+## Install
+- From PyPI:
+`pip install subagent-cli`
+- From local artifacts:
+`pip install dist/subagent_cli-*.whl`
+
+## Quick Start
+1. Prepare config:
+`mkdir -p ~/.config/subagent && cp config.example.yaml ~/.config/subagent/config.yaml`
+2. Initialize a controller in your workspace:
+`subagent controller init --cwd .`
+3. Start a worker:
+`subagent worker start --cwd .`
+4. Send an instruction:
+`subagent send --worker <worker-id> --text "Investigate failing tests"`
+5. Watch events:
+`subagent watch --worker <worker-id> --ndjson`
+
+For local simulation/testing without a real ACP launcher:
+`subagent worker start --cwd . --debug-mode`
+
+## Configuration
+- Default config path: `~/.config/subagent/config.yaml`
+- Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
+- Example config: [config.example.yaml](config.example.yaml)
+
+## State
+- Default state DB: `~/.local/share/subagent/state.db`
+- Project hint file: `<workspace>/.subagent/controller.json`
+
+## Documentation
+- Architecture note: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Examples: [docs/examples](docs/examples)
+- Contributing and release process: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+MIT ([LICENSE](LICENSE))

subagent_cli-0.1.1/config.example.yaml

@@ -0,0 +1,52 @@
+launchers:
+  codex:
+    backend:
+      kind: acp-stdio
+    command: codex-acp
+    args: []
+    env: {}
+
+  claude-code:
+    backend:
+      kind: acp-stdio
+    command: claude-code-acp
+    args: []
+    env: {}
+
+profiles:
+  worker-default:
+    promptLanguage: en
+    responseLanguage: same_as_manager
+    autoHandoff: turn_end
+    policyPreset: safe-default
+    defaultPacks:
+      - repo-conventions
+    bootstrap: |
+      You are a worker subagent.
+      Use STATUS:, ASK:, BLOCKED:, and DONE: prefixes when helpful.
+      Keep messages concise and actionable.
+
+packs:
+  repo-conventions:
+    description: Follow repository coding conventions and keep diffs small.
+    prompt: |
+      Read existing conventions before editing.
+      Prefer minimal, explicit changes.
+
+  python-test-fix:
+    description: Fix flaky Python tests with minimal change scope.
+    prompt: |
+      Reproduce failing tests first.
+      Add regression coverage where practical.
+
+policyPresets:
+  safe-default:
+    filesystem: workspace-write
+    network: ask
+    dangerousCommands: deny
+
+defaults:
+  launcher: codex
+  profile: worker-default
+  packs:
+    - repo-conventions

subagent_cli-0.1.1/docs/ARCHITECTURE.md

@@ -0,0 +1,34 @@
+# subagent v1 Architecture Memo
+
+## Layers
+- CLI surface: `subagent` Typer commands for controller/config operations.
+- Local control plane: `subagentd` minimal bootstrap/status process.
+- Runtime state: sqlite-backed `StateStore` for controller ownership.
+- Config registry: loader for `launchers` / `profiles` / `packs` from config.
+
+## Current v1 Scope (Implemented)
+- `launcher/profile/pack`: `list`, `show`
+- `launcher`: `probe`
+- `prompt`: `render` (manager/worker)
+- `controller`: `init`, `attach`, `status`, `recover`, `release`
+- `worker`: `start`, `list`, `show`, `inspect`, `stop`, `handoff`, `continue`
+- turn operations: `send`, `watch`, `wait`, `approve`, `cancel`
+- normalized event journal and approval queue
+- persistent `acp-stdio` worker runtime:
+  - `worker start` launches runtime (`initialize` -> `session/new`)
+  - restart path attempts `session/load` using stored `sessionId`, then falls back to `session/new`
+  - `send` uses runtime IPC to execute `session/prompt`
+  - `cancel` propagates to runtime (`session/cancel`)
+  - live permission flow pauses on `session/request_permission` and resumes via `approve`
+  - runtime IPC retries once with auto-restart when runtime socket is unreachable
+- explicit local simulation mode (`--debug-mode` or `--request-approval`)
+- handoff store with `handoff.md` + `checkpoint.json`
+- `--input` JSON contract (major commands) with duplicate-field rejection
+- owner handle model: `controllerId + epoch + token`
+- project-local hint: `<workspace>/.subagent/controller.json`
+- versioned envelope for JSON responses
+
+## Current Limitations
+- local single-host control plane only (`subagentd` is minimal bootstrap/status)
+- no queued turn execution; `send` is rejected while worker is busy
+- resume strategy is handoff-first (no bit-perfect backend session resurrection)

subagent_cli-0.1.1/docs/examples/checkpoint.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "v1",
+  "sourceWorkerId": "w_123",
+  "createdAt": "2026-03-01T22:10:00Z",
+  "summary": {
+    "task": "Investigate flaky payments retry test",
+    "state": "idle",
+    "lastCompletedTurnId": "turn_07"
+  },
+  "artifacts": {
+    "handoff": "handoff.md",
+    "eventsPath": "events/w_123.ndjson"
+  }
+}

subagent_cli-0.1.1/docs/examples/handoff.md

@@ -0,0 +1,36 @@
+# Handoff
+
+## Task
+Investigate flaky payments retry test and implement a minimal safe fix.
+
+## Goal
+Stabilize retry test behavior and add regression coverage.
+
+## Current Status
+Root cause identified in retry backoff clock handling.
+
+## Completed
+- Reproduced flaky test locally.
+- Isolated nondeterministic timestamp calculation.
+
+## Pending
+- Patch retry timing comparison.
+- Add deterministic regression test.
+- Re-run targeted test suite.
+
+## Files of Interest
+- `payments/retry.py`
+- `tests/payments/test_retry.py`
+
+## Commands Run
+- `uv run pytest tests/payments/test_retry.py -k flaky_case`
+
+## Risks / Notes
+- Retry logic is shared by multiple payment flows.
+- Validate no behavior regression for max retry cap.
+
+## Recommended Next Step
+Implement deterministic clock injection in retry calculation and add focused regression test.
+
+## Artifacts
+- `checkpoint.json`

subagent_cli-0.1.1/docs/examples/normalized-event.ndjson

@@ -0,0 +1,4 @@
+{"schemaVersion":"v1","eventId":"ev_01","ts":"2026-03-01T22:00:00Z","workerId":"w_123","type":"worker.started","data":{"launcher":"codex","profile":"worker-default","state":"idle"}}
+{"schemaVersion":"v1","eventId":"ev_02","ts":"2026-03-01T22:00:05Z","workerId":"w_123","type":"turn.started","data":{"turnId":"turn_01"}}
+{"schemaVersion":"v1","eventId":"ev_03","ts":"2026-03-01T22:00:12Z","workerId":"w_123","type":"progress.message","data":{"role":"assistant","text":"STATUS: Investigating flaky payments retry test."}}
+{"schemaVersion":"v1","eventId":"ev_04","ts":"2026-03-01T22:00:20Z","workerId":"w_123","type":"turn.completed","data":{"turnId":"turn_01","state":"idle"}}

subagent_cli-0.1.1/docs/examples/worker-continue-flow.md

@@ -0,0 +1,13 @@
+# Worker Continue Flow (v1)
+
+1. Create handoff from previous worker:
+`subagent worker handoff --worker w_123`
+
+2. Start a new worker from the handoff artifact:
+`subagent worker continue --from-worker w_123 --launcher codex --profile worker-default`
+
+3. Watch normalized events from the new worker:
+`subagent watch --worker w_456 --follow --ndjson`
+
+4. Continue by sending a new instruction:
+`subagent send --worker w_456 --text "Proceed with the minimal fix and add regression coverage."`

subagent_cli-0.1.1/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "subagent-cli"
+version = "0.1.1"
+description = "Protocol-agnostic worker orchestration CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "niitsuma-t" }]
+keywords = ["cli", "agent", "orchestration", "acp", "automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.24.1",
+]
+
+[project.scripts]
+subagent = "subagent.cli:main"
+subagentd = "subagent.daemon:main"
+
+[build-system]
+requires = ["hatchling>=1.26.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/subagent"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]
+release = [
+    "twine>=6.2.0",
+]

subagent_cli-0.1.1/src/subagent/__init__.py

@@ -0,0 +1,7 @@
+"""subagent CLI package."""
+
+from .constants import SCHEMA_VERSION
+
+__version__ = "0.1.1"
+
+__all__ = ["SCHEMA_VERSION", "__version__"]