subagent-cli 0.1.1__py3-none-any.whl

subagent/worker_service.py

@@ -0,0 +1,362 @@
+"""Worker lifecycle service helpers."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .config import SubagentConfig
+from .controller_service import read_env_handle, resolve_controller_id
+from .errors import SubagentError
+from .paths import resolve_workspace_path
+from .runtime_service import launch_worker_runtime, stop_worker_runtime
+from .state import WORKER_STATE_ERROR, StateStore
+
+
+def resolve_worker_controller_id(
+    store: StateStore,
+    *,
+    workspace: Path,
+    explicit_controller_id: str | None = None,
+) -> str:
+    env_handle = read_env_handle()
+    env_controller_id: str | None = None
+    if env_handle is not None:
+        if env_handle.get("valid") is False:
+            raise SubagentError(
+                code="INVALID_CONTROLLER_HANDLE",
+                message="SUBAGENT_CTL_EPOCH is not a valid integer",
+            )
+        env_controller_id = str(env_handle["controllerId"])
+
+    target_controller_id = explicit_controller_id or env_controller_id
+    if target_controller_id is None:
+        target_controller_id = resolve_controller_id(
+            store,
+            workspace,
+            explicit_controller_id=None,
+        )
+    if target_controller_id is None:
+        raise SubagentError(
+            code="CONTROLLER_NOT_FOUND",
+            message=(
+                "Controller could not be resolved. Set SUBAGENT_CTL_* env vars, "
+                "use --controller-id, or run `subagent controller init` first."
+            ),
+            details={"workspaceKey": str(workspace)},
+        )
+
+    if env_handle is not None and "epoch" in env_handle and "token" in env_handle:
+        if env_controller_id != target_controller_id:
+            raise SubagentError(
+                code="INVALID_CONTROLLER_HANDLE",
+                message="SUBAGENT_CTL_ID does not match target controller",
+                details={
+                    "envControllerId": env_controller_id,
+                    "targetControllerId": target_controller_id,
+                },
+            )
+        valid = store.validate_handle(
+            target_controller_id,
+            int(env_handle["epoch"]),
+            str(env_handle["token"]),
+        )
+        if not valid:
+            raise SubagentError(
+                code="INVALID_CONTROLLER_HANDLE",
+                message="Controller handle is stale or invalid",
+                details={"controllerId": target_controller_id},
+            )
+    elif env_handle is not None:
+        raise SubagentError(
+            code="INVALID_CONTROLLER_HANDLE",
+            message="Incomplete controller handle in environment",
+            details={"env": env_handle},
+        )
+
+    controller = store.get_controller(target_controller_id)
+    if controller is None:
+        raise SubagentError(
+            code="CONTROLLER_NOT_FOUND",
+            message=f"Controller not found: {target_controller_id}",
+            details={"controllerId": target_controller_id},
+        )
+    return target_controller_id
+
+
+def _resolve_launcher(config: SubagentConfig, launcher: str | None) -> str:
+    value = launcher
+    if value is None:
+        default_launcher = config.defaults.get("launcher")
+        if isinstance(default_launcher, str) and default_launcher:
+            value = default_launcher
+    if value is None:
+        raise SubagentError(
+            code="LAUNCHER_NOT_FOUND",
+            message="Launcher is required. Set --launcher or defaults.launcher in config.",
+        )
+    if value not in config.launchers:
+        raise SubagentError(
+            code="LAUNCHER_NOT_FOUND",
+            message=f"Launcher not found: {value}",
+            details={"launcher": value},
+        )
+    return value
+
+
+def _resolve_profile(config: SubagentConfig, profile: str | None) -> str:
+    value = profile
+    if value is None:
+        default_profile = config.defaults.get("profile")
+        if isinstance(default_profile, str) and default_profile:
+            value = default_profile
+    if value is None:
+        raise SubagentError(
+            code="PROFILE_NOT_FOUND",
+            message="Profile is required. Set --profile or defaults.profile in config.",
+        )
+    if value not in config.profiles:
+        raise SubagentError(
+            code="PROFILE_NOT_FOUND",
+            message=f"Profile not found: {value}",
+            details={"profile": value},
+        )
+    return value
+
+
+def _resolve_packs(config: SubagentConfig, profile_name: str, packs: list[str]) -> list[str]:
+    resolved: list[str] = []
+    if packs:
+        resolved = packs
+    else:
+        profile = config.profiles[profile_name]
+        if profile.default_packs:
+            resolved = list(profile.default_packs)
+        else:
+            defaults_packs = config.defaults.get("packs")
+            if isinstance(defaults_packs, list):
+                resolved = [str(item) for item in defaults_packs]
+    for pack_name in resolved:
+        if pack_name not in config.packs:
+            raise SubagentError(
+                code="PACK_NOT_FOUND",
+                message=f"Pack not found: {pack_name}",
+                details={"pack": pack_name},
+            )
+    return resolved
+
+
+def start_worker(
+    store: StateStore,
+    config: SubagentConfig,
+    *,
+    workspace: Path,
+    worker_cwd: Path,
+    controller_id: str | None,
+    launcher: str | None,
+    profile: str | None,
+    packs: list[str],
+    label: str | None,
+    debug_mode: bool = False,
+) -> dict[str, Any]:
+    resolved_workspace = resolve_workspace_path(workspace)
+    target_controller_id = resolve_worker_controller_id(
+        store,
+        workspace=resolved_workspace,
+        explicit_controller_id=controller_id,
+    )
+    target_launcher = _resolve_launcher(config, launcher)
+    target_profile = _resolve_profile(config, profile)
+    target_packs = _resolve_packs(config, target_profile, packs)
+    resolved_cwd = resolve_workspace_path(worker_cwd)
+    resolved_label = label or "worker"
+
+    worker = store.create_worker(
+        controller_id=target_controller_id,
+        launcher=target_launcher,
+        profile=target_profile,
+        packs=target_packs,
+        cwd=str(resolved_cwd),
+        label=resolved_label,
+    )
+    launcher_entry = config.launchers[target_launcher]
+    if not debug_mode:
+        if launcher_entry.backend_kind != "acp-stdio":
+            raise SubagentError(
+                code="BACKEND_UNAVAILABLE",
+                message=f"Unsupported backend kind for runtime: {launcher_entry.backend_kind}",
+                details={"launcher": target_launcher, "backendKind": launcher_entry.backend_kind},
+            )
+        if shutil.which(launcher_entry.command) is None and "/" not in launcher_entry.command:
+            raise SubagentError(
+                code="BACKEND_UNAVAILABLE",
+                message=f"Launcher command not available: {launcher_entry.command}",
+                details={"launcher": target_launcher, "command": launcher_entry.command},
+            )
+        if "/" in launcher_entry.command and not Path(launcher_entry.command).expanduser().exists():
+            raise SubagentError(
+                code="BACKEND_UNAVAILABLE",
+                message=f"Launcher command not available: {launcher_entry.command}",
+                details={"launcher": target_launcher, "command": launcher_entry.command},
+            )
+        try:
+            launch_worker_runtime(
+                store,
+                worker_id=str(worker["worker_id"]),
+                launcher=launcher_entry,
+                cwd=str(resolved_cwd),
+            )
+        except SubagentError as error:
+            store.update_worker_state(
+                str(worker["worker_id"]),
+                next_state=WORKER_STATE_ERROR,
+                allow_any_transition=True,
+                last_error=error.message,
+            )
+            raise
+        refreshed = store.get_worker(str(worker["worker_id"]))
+        if refreshed is not None:
+            worker = refreshed
+    return {
+        "workerId": worker["worker_id"],
+        "controllerId": worker["controller_id"],
+        "sessionId": worker["session_id"],
+        "launcher": worker["launcher"],
+        "profile": worker["profile"],
+        "packs": worker["packs"],
+        "cwd": worker["cwd"],
+        "label": worker["label"],
+        "state": worker["state"],
+        "recoveryState": worker["recovery_state"],
+        "runtimePid": worker.get("runtime_pid"),
+        "runtimeSocket": worker.get("runtime_socket"),
+        "createdAt": worker["created_at"],
+    }
+
+
+def list_workers(
+    store: StateStore,
+    *,
+    controller_id: str | None = None,
+) -> list[dict[str, Any]]:
+    workers = store.list_workers(controller_id=controller_id)
+    return [
+        {
+            "workerId": row["worker_id"],
+            "controllerId": row["controller_id"],
+            "label": row["label"],
+            "launcher": row["launcher"],
+            "profile": row["profile"],
+            "state": row["state"],
+            "cwd": row["cwd"],
+            "sessionId": row["session_id"],
+            "activeTurnId": row.get("active_turn_id"),
+            "runtimePid": row.get("runtime_pid"),
+            "runtimeSocket": row.get("runtime_socket"),
+            "createdAt": row["created_at"],
+            "updatedAt": row["updated_at"],
+            "stoppedAt": row["stopped_at"],
+        }
+        for row in workers
+    ]
+
+
+def show_worker(store: StateStore, worker_id: str) -> dict[str, Any]:
+    worker = store.get_worker(worker_id)
+    if worker is None:
+        raise SubagentError(
+            code="WORKER_NOT_FOUND",
+            message=f"Worker not found: {worker_id}",
+            details={"workerId": worker_id},
+        )
+    return {
+        "workerId": worker["worker_id"],
+        "controllerId": worker["controller_id"],
+        "label": worker["label"],
+        "launcher": worker["launcher"],
+        "profile": worker["profile"],
+        "packs": worker["packs"],
+        "cwd": worker["cwd"],
+        "sessionId": worker["session_id"],
+        "activeTurnId": worker.get("active_turn_id"),
+        "runtimePid": worker.get("runtime_pid"),
+        "runtimeSocket": worker.get("runtime_socket"),
+        "state": worker["state"],
+        "recoveryState": worker["recovery_state"],
+        "createdAt": worker["created_at"],
+        "updatedAt": worker["updated_at"],
+        "stoppedAt": worker["stopped_at"],
+        "lastError": worker["last_error"],
+    }
+
+
+def stop_worker(store: StateStore, worker_id: str, *, force: bool = False) -> dict[str, Any]:
+    worker = store.get_worker(worker_id)
+    if worker is None:
+        raise SubagentError(
+            code="WORKER_NOT_FOUND",
+            message=f"Worker not found: {worker_id}",
+            details={"workerId": worker_id},
+        )
+    if worker.get("runtime_socket"):
+        stop_worker_runtime(store, worker_id=worker_id, reason="worker stopped by manager")
+    worker = store.stop_worker(worker_id, force=force)
+    return {
+        "workerId": worker["worker_id"],
+        "controllerId": worker["controller_id"],
+        "state": worker["state"],
+        "stoppedAt": worker["stopped_at"],
+        "updatedAt": worker["updated_at"],
+    }
+
+
+def inspect_worker(store: StateStore, worker_id: str, *, events_limit: int = 20) -> dict[str, Any]:
+    worker = show_worker(store, worker_id)
+    row = store.get_worker(worker_id)
+    assert row is not None
+    pending_approvals = store.list_pending_approval_requests(worker_id)
+    latest_handoff = store.get_latest_handoff_snapshot(worker_id)
+    events = store.list_worker_events(worker_id, limit=events_limit)
+    event_items = [
+        {
+            "eventId": event["event_id"],
+            "ts": event["ts"],
+            "type": event["event_type"],
+            "turnId": event.get("turn_id"),
+            "data": event["data"],
+        }
+        for event in events
+    ]
+
+    recovery_state = "restartable"
+    if latest_handoff is not None:
+        recovery_state = "handoff_available"
+    if str(row["state"]) == "stopped" and latest_handoff is None:
+        recovery_state = "lost"
+    worker["recoveryState"] = recovery_state
+    return {
+        "worker": worker,
+        "pendingApprovals": [
+            {
+                "requestId": req["request_id"],
+                "turnId": req.get("turn_id"),
+                "kind": req["kind"],
+                "message": req["message"],
+                "options": req["options"],
+                "createdAt": req["created_at"],
+            }
+            for req in pending_approvals
+        ],
+        "latestHandoff": (
+            {
+                "snapshotId": latest_handoff["snapshot_id"],
+                "handoffPath": latest_handoff["handoff_path"],
+                "checkpointPath": latest_handoff["checkpoint_path"],
+                "createdAt": latest_handoff["created_at"],
+            }
+            if latest_handoff is not None
+            else None
+        ),
+        "events": event_items,
+    }

subagent_cli-0.1.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,27 @@
+subagent/__init__.py,sha256=qnX1gfMPNNNem-NAVnTgNAksmtnx2akJGvHU0cWUtYk,135
+subagent/acp_client.py,sha256=VTkQtgV2-sD0_e2CNxsOxN5eKzrF8tulrGrwhYuuczY,12166
+subagent/approval_utils.py,sha256=hu55JOvFNpvmE1gGAilc_4g5wUP0OKL07BOFv36J1Z0,1755
+subagent/cli.py,sha256=j7FSR64XeA1Hy9dWdf0q7eb4mOLGn5SdP-qL3dosoak,41155
+subagent/config.py,sha256=RAl18DpwHP0KZFpWMz4vpSmPleQsxZBrjWLR7zbb_eI,11119
+subagent/constants.py,sha256=B7yVltkQh2AetpkUIJ3CE8rqWvB9lJVmbzawHHSbX9w,693
+subagent/controller_service.py,sha256=HpRs4Z8WxJZKlEkbDrF_1XJK8bkkrLREHqi5BBXMPNo,8396
+subagent/daemon.py,sha256=h0vdM1UX9hNZOorAq76VrVxLmV_wyM5LWJA2DkOsU2I,3726
+subagent/errors.py,sha256=8cInh4Ly_BGtIlRSVcbmG0pGuEYtCW_DSOgrUIS9l8A,637
+subagent/handoff_service.py,sha256=4Gol2MGl55WK27ftIIxmfzpLVxmzIgb7V2e8v5ys90Y,11727
+subagent/hints.py,sha256=Di71I3y5zlXp-EHGBOtxeho005yKdKs-2k24Npdg5QU,1067
+subagent/input_contract.py,sha256=00ep9qn_azDoSH8s5VjtRATnK5VBG8nlNT_kJrZyf1U,3469
+subagent/launcher_service.py,sha256=xGvi7xqT31ZXrPKfuyApL0_ymwo9yWg4RIHZtiJiUH4,919
+subagent/output.py,sha256=k-YUydAcmcZKO1gyJVpcbyssreJJTnrAvU1yiGk2bAA,1001
+subagent/paths.py,sha256=wswLFq4Hx7x00offBYksO-0eeNHbfnBQ4vzW7bVUzA8,1848
+subagent/prompt_service.py,sha256=f3T0emS9_JsIQo-CEHi2vusCMcMf5UiMPV2SZbkdefo,4046
+subagent/runtime_service.py,sha256=bi3ZkdsHNZUODX8VNAhMkDSU9dnaIUxlnF5eILhRfuc,10984
+subagent/simple_yaml.py,sha256=LeGdC0K_UQyilwAV7jY5JjMXHyJFLFRd7h55Sbv66FQ,6418
+subagent/state.py,sha256=1juhxJNFDd7rytjTMeEjsZ9FAgIxvzIghx0yRFbr5F8,37722
+subagent/turn_service.py,sha256=B15L5yKxXl8N7KiWsuoLcDf4L2-yaYtTrDLYYbyG1fE,17095
+subagent/worker_runtime.py,sha256=h_c7giLmqnRa2qD3o946DEQJ7j0fkIv96hzkrOppcP0,30255
+subagent/worker_service.py,sha256=S5BZZiQoYOI625r5d7IokfWqcnyi_aVH0nFNWMmWHSY,12992
+subagent_cli-0.1.1.dist-info/METADATA,sha256=9V0a_Rad7YjA7ZzgCkqUj7qoGjDj480AacWefyX1stE,3994
+subagent_cli-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+subagent_cli-0.1.1.dist-info/entry_points.txt,sha256=ej72eXylNqoh_MXworT0vZAvw-eRSB_DhAfmL8KDH6k,80
+subagent_cli-0.1.1.dist-info/licenses/LICENSE,sha256=HiXGtv_7dfZp45AN24NM90E2jwRj7JI9VnetTQ91Z_o,1067
+subagent_cli-0.1.1.dist-info/RECORD,,

subagent_cli-0.1.1.dist-info/WHEEL

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

subagent_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+subagent = subagent.cli:main
+subagentd = subagent.daemon:main

subagent_cli-0.1.1.dist-info/licenses/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.