subagent-cli 0.1.2__tar.gz → 0.1.4__tar.gz

subagent_cli-0.1.4/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: subagent-cli
+Version: 0.1.4
+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
+
+[![PyPI version](https://img.shields.io/pypi/v/subagent-cli)](https://pypi.org/project/subagent-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/subagent-cli)](https://pypi.org/project/subagent-cli/)
+[![License](https://img.shields.io/github/license/otakumesi/subagent-cli)](LICENSE)
+[![Publish to PyPI](https://github.com/otakumesi/subagent-cli/actions/workflows/publish-pypi.yml/badge.svg)](https://github.com/otakumesi/subagent-cli/actions/workflows/publish-pypi.yml)
+[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)](https://pypi.org/project/subagent-cli/)
+
+Orchestrate coding agents from another coding agent, cleanly and safely.  
+`subagent-cli` turns a manager coding agent (for example Codex or Claude Code) into a practical control plane for starting worker coding agents, sending turns, handling approvals, and continuing handoffs. 🤖
+
+The command interface is protocol-agnostic, and the current runtime backend is ACP-based (`acp-stdio`).
+
+## Why subagent-cli? 🚀
+- Run multi-agent workflows from one place (`worker start` to `worker continue`).
+- Keep control explicit with strict approval operations and structured event flow.
+- Recover cleanly with runtime restart + session resume (`session/load`).
+- Stay local-first and scriptable with a single CLI surface.
+
+## Current Scope 🧭
+- 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`)
+
+## Install 📦
+With `uv` (recommended):
+```bash
+uv tool install subagent-cli
+```
+
+From PyPI:
+```bash
+pip install subagent-cli
+```
+
+From local artifacts:
+```bash
+pip install dist/subagent_cli-*.whl
+```
+
+## Quick Start ⚡
+1. Bootstrap your local config.
+```bash
+subagent config init --scope user
+```
+
+2. Set launcher command/args/env in `~/.config/subagent/config.yaml`.
+
+3. Initialize a controller in your workspace (run once per workspace, by you or your manager agent).
+```bash
+subagent controller init --cwd .
+```
+
+4. Hand off from here to your manager agent (Codex / Claude Code).  
+Ask the manager agent to run `subagent prompt render --target manager` as its first step.  
+Use this instruction template:
+
+```text
+Act as the project manager for this repository.
+Use subagent-cli as the control plane and progress this task by delegating to worker agents.
+If worker startup or turn operations fail due to sandbox limits, request approval for out-of-sandbox execution and retry.
+
+Required workflow:
+1) First, run `subagent prompt render --target manager` and follow that output.
+2) Check command help before execution (for example `subagent worker --help`, `subagent send --help`, `subagent approve --help`).
+3) Break the task into small executable chunks.
+4) Start/coordinate workers with subagent-cli.
+5) Use `send` as the default turn driver (`send` waits by default).
+6) If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
+7) Use `watch` only when detailed event streaming/debugging is needed.
+8) Use handoff/continue when context gets large.
+9) Verify results (tests or checks) before reporting completion.
+
+Task to execute:
+<your task here>
+```
+
+After handoff, the manager agent's standard lifecycle is:
+`worker start` -> `send` -> (`approve` -> `send` as needed) -> `handoff` -> `continue`
+
+For a single command that sends and waits for terminal-or-approval events:
+```bash
+subagent send --worker <worker-id> --text "<instruction>" --json
+```
+
+Opt out of waiting when needed:
+```bash
+subagent send --worker <worker-id> --text "<instruction>" --no-wait --json
+```
+
+Manual wait mode (advanced cursor control) still exists:
+```bash
+subagent wait --worker <worker-id> --until turn_end --timeout-seconds 60 --json
+```
+
+For local simulation/testing without a real ACP launcher:
+```bash
+subagent worker start --cwd . --debug-mode
+```
+
+## Troubleshooting 🛠️
+- Ensure both the runtime and your manager/worker agent sandbox allow what your launcher needs.
+- Some launchers require outbound network access, but agent sandbox policies can block network even when the host machine itself has connectivity.
+- If state path resolution fails, run commands from inside your workspace root (or set `SUBAGENT_STATE_DIR` explicitly).
+- Preflight launcher availability:
+```bash
+subagent launcher probe <launcher-name> --json
+```
+- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under `<workspace>/.subagent/state/runtimes/` (default) or `$SUBAGENT_STATE_DIR/runtimes/` (when overridden).
+- For cut-down local testing without backend connectivity:
+```bash
+subagent worker start --cwd . --debug-mode
+```
+
+## Configuration ⚙️
+- Resolution order: `--config` > `SUBAGENT_CONFIG` > nearest `<cwd-or-parent>/.subagent/config.yaml` > `~/.config/subagent/config.yaml`
+- Generate user config: `subagent config init --scope user`
+- Generate project config: `subagent config init --scope project --cwd .`
+- `config init` defaults: `codex` -> `npx -y @zed-industries/codex-acp`, `claude-code` -> `npx -y @zed-industries/claude-agent-acp`
+- Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
+- Example config: [config.example.yaml](config.example.yaml)
+- Launchers support either split style (`command: npx`, `args: ["-y", "..."]`) or inline style (`command: "npx -y ..."`) for probe/start/restart.
+
+## State 💾
+- Default state DB: `<workspace>/.subagent/state/state.db`
+- Override state dir: `SUBAGENT_STATE_DIR=/path/to/state-dir`
+- If workspace root cannot be detected and no override is set, commands fail with `WORKSPACE_ROOT_NOT_FOUND`
+- 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.4/README.md

@@ -0,0 +1,143 @@
+# subagent-cli
+
+[![PyPI version](https://img.shields.io/pypi/v/subagent-cli)](https://pypi.org/project/subagent-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/subagent-cli)](https://pypi.org/project/subagent-cli/)
+[![License](https://img.shields.io/github/license/otakumesi/subagent-cli)](LICENSE)
+[![Publish to PyPI](https://github.com/otakumesi/subagent-cli/actions/workflows/publish-pypi.yml/badge.svg)](https://github.com/otakumesi/subagent-cli/actions/workflows/publish-pypi.yml)
+[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)](https://pypi.org/project/subagent-cli/)
+
+Orchestrate coding agents from another coding agent, cleanly and safely.  
+`subagent-cli` turns a manager coding agent (for example Codex or Claude Code) into a practical control plane for starting worker coding agents, sending turns, handling approvals, and continuing handoffs. 🤖
+
+The command interface is protocol-agnostic, and the current runtime backend is ACP-based (`acp-stdio`).
+
+## Why subagent-cli? 🚀
+- Run multi-agent workflows from one place (`worker start` to `worker continue`).
+- Keep control explicit with strict approval operations and structured event flow.
+- Recover cleanly with runtime restart + session resume (`session/load`).
+- Stay local-first and scriptable with a single CLI surface.
+
+## Current Scope 🧭
+- 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`)
+
+## Install 📦
+With `uv` (recommended):
+```bash
+uv tool install subagent-cli
+```
+
+From PyPI:
+```bash
+pip install subagent-cli
+```
+
+From local artifacts:
+```bash
+pip install dist/subagent_cli-*.whl
+```
+
+## Quick Start ⚡
+1. Bootstrap your local config.
+```bash
+subagent config init --scope user
+```
+
+2. Set launcher command/args/env in `~/.config/subagent/config.yaml`.
+
+3. Initialize a controller in your workspace (run once per workspace, by you or your manager agent).
+```bash
+subagent controller init --cwd .
+```
+
+4. Hand off from here to your manager agent (Codex / Claude Code).  
+Ask the manager agent to run `subagent prompt render --target manager` as its first step.  
+Use this instruction template:
+
+```text
+Act as the project manager for this repository.
+Use subagent-cli as the control plane and progress this task by delegating to worker agents.
+If worker startup or turn operations fail due to sandbox limits, request approval for out-of-sandbox execution and retry.
+
+Required workflow:
+1) First, run `subagent prompt render --target manager` and follow that output.
+2) Check command help before execution (for example `subagent worker --help`, `subagent send --help`, `subagent approve --help`).
+3) Break the task into small executable chunks.
+4) Start/coordinate workers with subagent-cli.
+5) Use `send` as the default turn driver (`send` waits by default).
+6) If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
+7) Use `watch` only when detailed event streaming/debugging is needed.
+8) Use handoff/continue when context gets large.
+9) Verify results (tests or checks) before reporting completion.
+
+Task to execute:
+<your task here>
+```
+
+After handoff, the manager agent's standard lifecycle is:
+`worker start` -> `send` -> (`approve` -> `send` as needed) -> `handoff` -> `continue`
+
+For a single command that sends and waits for terminal-or-approval events:
+```bash
+subagent send --worker <worker-id> --text "<instruction>" --json
+```
+
+Opt out of waiting when needed:
+```bash
+subagent send --worker <worker-id> --text "<instruction>" --no-wait --json
+```
+
+Manual wait mode (advanced cursor control) still exists:
+```bash
+subagent wait --worker <worker-id> --until turn_end --timeout-seconds 60 --json
+```
+
+For local simulation/testing without a real ACP launcher:
+```bash
+subagent worker start --cwd . --debug-mode
+```
+
+## Troubleshooting 🛠️
+- Ensure both the runtime and your manager/worker agent sandbox allow what your launcher needs.
+- Some launchers require outbound network access, but agent sandbox policies can block network even when the host machine itself has connectivity.
+- If state path resolution fails, run commands from inside your workspace root (or set `SUBAGENT_STATE_DIR` explicitly).
+- Preflight launcher availability:
+```bash
+subagent launcher probe <launcher-name> --json
+```
+- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under `<workspace>/.subagent/state/runtimes/` (default) or `$SUBAGENT_STATE_DIR/runtimes/` (when overridden).
+- For cut-down local testing without backend connectivity:
+```bash
+subagent worker start --cwd . --debug-mode
+```
+
+## Configuration ⚙️
+- Resolution order: `--config` > `SUBAGENT_CONFIG` > nearest `<cwd-or-parent>/.subagent/config.yaml` > `~/.config/subagent/config.yaml`
+- Generate user config: `subagent config init --scope user`
+- Generate project config: `subagent config init --scope project --cwd .`
+- `config init` defaults: `codex` -> `npx -y @zed-industries/codex-acp`, `claude-code` -> `npx -y @zed-industries/claude-agent-acp`
+- Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
+- Example config: [config.example.yaml](config.example.yaml)
+- Launchers support either split style (`command: npx`, `args: ["-y", "..."]`) or inline style (`command: "npx -y ..."`) for probe/start/restart.
+
+## State 💾
+- Default state DB: `<workspace>/.subagent/state/state.db`
+- Override state dir: `SUBAGENT_STATE_DIR=/path/to/state-dir`
+- If workspace root cannot be detected and no override is set, commands fail with `WORKSPACE_ROOT_NOT_FOUND`
+- 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.2 → subagent_cli-0.1.4}/config.example.yaml

@@ -2,15 +2,19 @@ launchers:
   codex:
     backend:
       kind: acp-stdio
-    command: codex-acp
-    args: []
+    command: npx
+    args:
+      - -y
+      - "@zed-industries/codex-acp"
     env: {}
 
   claude-code:
     backend:
       kind: acp-stdio
-    command: claude-code-acp
-    args: []
+    command: npx
+    args:
+      - -y
+      - "@zed-industries/claude-agent-acp"
     env: {}
 
 profiles:

{subagent_cli-0.1.2 → subagent_cli-0.1.4}/docs/ARCHITECTURE.md

@@ -25,6 +25,7 @@
 - handoff store with `handoff.md` + `checkpoint.json`
 - `--input` JSON contract (major commands) with duplicate-field rejection
 - owner handle model: `controllerId + epoch + token`
+- workspace-scoped runtime state by default: `<workspace-root>/.subagent/state` (or `SUBAGENT_STATE_DIR` override)
 - project-local hint: `<workspace>/.subagent/controller.json`
 - versioned envelope for JSON responses
 
@@ -32,3 +33,4 @@
 - 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)
+- commands that need implicit state path fail with `WORKSPACE_ROOT_NOT_FOUND` when workspace root cannot be inferred

subagent_cli-0.1.4/docs/examples/checkpoint.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "v1",
+  "workerId": "w_123",
+  "controllerId": "ctl_abc123",
+  "launcher": "codex",
+  "profile": "worker-default",
+  "packs": ["repo-conventions"],
+  "cwd": "/path/to/workspace",
+  "state": "handoff_ready",
+  "sourceTurnId": "turn_07",
+  "handoffPath": "/path/to/workspace/.subagent/state/handoffs/w_123/hs_abc123/handoff.md",
+  "artifacts": ["/path/to/workspace/.subagent/state/handoffs/w_123/hs_abc123/handoff.md"],
+  "filesChanged": []
+}

{subagent_cli-0.1.2 → subagent_cli-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "subagent-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "Protocol-agnostic worker orchestration CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{subagent_cli-0.1.2 → subagent_cli-0.1.4}/src/subagent/__init__.py

@@ -2,6 +2,6 @@
 
 from .constants import SCHEMA_VERSION
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 __all__ = ["SCHEMA_VERSION", "__version__"]