subagent-cli 0.1.1__py3-none-any.whl

subagent/output.py

@@ -0,0 +1,41 @@
+"""Output helpers for human and JSON responses."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, NoReturn
+
+import typer
+
+from .constants import SCHEMA_VERSION
+from .errors import SubagentError
+
+
+def ok_envelope(event_type: str, data: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "ok": True,
+        "type": event_type,
+        "data": data,
+    }
+
+
+def error_envelope(error: SubagentError) -> dict[str, Any]:
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "ok": False,
+        "type": "error",
+        "error": error.to_dict(),
+    }
+
+
+def emit_json(payload: dict[str, Any]) -> None:
+    typer.echo(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+
+
+def emit_error_and_exit(error: SubagentError, json_output: bool = False) -> NoReturn:
+    if json_output:
+        emit_json(error_envelope(error))
+    else:
+        typer.echo(f"{error.code}: {error.message}", err=True)
+    raise typer.Exit(code=1)

subagent/paths.py

@@ -0,0 +1,63 @@
+"""Filesystem path resolution helpers."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .constants import (
+    DEFAULT_CONFIG_PATH,
+    DEFAULT_HANDOFFS_DIR,
+    DEFAULT_STATE_DB_PATH,
+    DEFAULT_STATE_DIR,
+    ENV_CONFIG_PATH,
+    ENV_STATE_DIR,
+    PROJECT_HINT_DIRNAME,
+    PROJECT_HINT_FILENAME,
+)
+
+
+def resolve_workspace_path(cwd: Path | None = None) -> Path:
+    return (cwd or Path.cwd()).expanduser().resolve()
+
+
+def resolve_config_path(config_path: Path | None = None) -> Path:
+    if config_path is not None:
+        return config_path.expanduser().resolve()
+    env_value = os.environ.get(ENV_CONFIG_PATH)
+    if env_value:
+        return Path(env_value).expanduser().resolve()
+    return DEFAULT_CONFIG_PATH
+
+
+def resolve_state_dir(state_dir: Path | None = None) -> Path:
+    if state_dir is not None:
+        return state_dir.expanduser().resolve()
+    env_value = os.environ.get(ENV_STATE_DIR)
+    if env_value:
+        return Path(env_value).expanduser().resolve()
+    return DEFAULT_STATE_DIR
+
+
+def resolve_state_db_path(state_dir: Path | None = None) -> Path:
+    resolved_state_dir = resolve_state_dir(state_dir)
+    default_parent = DEFAULT_STATE_DB_PATH.parent
+    if resolved_state_dir == default_parent:
+        return DEFAULT_STATE_DB_PATH
+    return resolved_state_dir / "state.db"
+
+
+def resolve_handoffs_dir(state_dir: Path | None = None) -> Path:
+    resolved_state_dir = resolve_state_dir(state_dir)
+    default_parent = DEFAULT_HANDOFFS_DIR.parent
+    if resolved_state_dir == default_parent:
+        return DEFAULT_HANDOFFS_DIR
+    return resolved_state_dir / "handoffs"
+
+
+def ensure_parent_dir(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def project_hint_path(workspace: Path) -> Path:
+    return workspace / PROJECT_HINT_DIRNAME / PROJECT_HINT_FILENAME

subagent/prompt_service.py

@@ -0,0 +1,114 @@
+"""Prompt rendering helpers for manager/worker targets."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .config import Pack, Profile, SubagentConfig
+from .errors import SubagentError
+
+MANAGER_PROMPT_BASE = """You are a manager agent coordinating worker subagents with `subagent` CLI.
+
+Read this quick workflow first:
+1. Initialize controller in the workspace:
+   subagent controller init --cwd <workspace>
+2. Start a worker:
+   subagent worker start --cwd <workspace>
+3. Send work:
+   subagent send --worker <worker-id> --text "<instruction>"
+4. Monitor progress:
+   subagent watch --worker <worker-id> --ndjson
+5. If approval is requested:
+   subagent approve --worker <worker-id> --request <request-id> --option-id <option-id>
+
+Operational rules:
+- Keep instructions short, concrete, and outcome-oriented.
+- Use `--json` for machine-readable responses and `--input` for JSON-driven calls.
+- Treat `waiting_approval` as a blocking state; resolve via `approve` or `cancel`.
+- Use handoff flow for continuation: `worker handoff` -> `worker continue`.
+- Prefer strict mode for production; use `--debug-mode` only for local simulation/testing.
+"""
+
+
+def _render_worker_prompt(profile: Profile, packs: list[Pack]) -> str:
+    lines: list[str] = []
+    if profile.bootstrap.strip():
+        lines.append(profile.bootstrap.strip())
+    else:
+        lines.append("You are a worker subagent.")
+    lines.append("Use STATUS:, ASK:, BLOCKED:, and DONE: prefixes when helpful.")
+    lines.append("Keep updates concise and action-oriented.")
+    if packs:
+        lines.append("")
+        lines.append("Additional pack instructions:")
+        for pack in packs:
+            lines.append(f"- Pack `{pack.name}`: {pack.description or '(no description)'}")
+            if pack.prompt.strip():
+                lines.append(pack.prompt.strip())
+    return "\n".join(lines).strip()
+
+
+def render_prompt(
+    config: SubagentConfig,
+    *,
+    target: str,
+    profile_name: str | None = None,
+    pack_names: list[str] | None = None,
+) -> dict[str, Any]:
+    if target not in {"manager", "worker"}:
+        raise SubagentError(
+            code="INVALID_ARGUMENT",
+            message=f"Unknown prompt target: {target}",
+            details={"target": target},
+        )
+
+    if target == "manager":
+        return {
+            "target": "manager",
+            "prompt": MANAGER_PROMPT_BASE,
+        }
+
+    selected_profile_name = profile_name
+    if selected_profile_name is None:
+        default_profile = config.defaults.get("profile")
+        if isinstance(default_profile, str) and default_profile:
+            selected_profile_name = default_profile
+    if selected_profile_name is None:
+        raise SubagentError(
+            code="PROFILE_NOT_FOUND",
+            message="Profile is required for worker prompt rendering.",
+        )
+    profile = config.profiles.get(selected_profile_name)
+    if profile is None:
+        raise SubagentError(
+            code="PROFILE_NOT_FOUND",
+            message=f"Profile not found: {selected_profile_name}",
+            details={"profile": selected_profile_name},
+        )
+
+    selected_pack_names = list(pack_names or [])
+    if not selected_pack_names:
+        selected_pack_names = list(profile.default_packs)
+        if not selected_pack_names:
+            defaults_packs = config.defaults.get("packs")
+            if isinstance(defaults_packs, list):
+                selected_pack_names = [str(item) for item in defaults_packs]
+
+    packs: list[Pack] = []
+    for pack_name in selected_pack_names:
+        pack = config.packs.get(pack_name)
+        if pack is None:
+            raise SubagentError(
+                code="PACK_NOT_FOUND",
+                message=f"Pack not found: {pack_name}",
+                details={"pack": pack_name},
+            )
+        packs.append(pack)
+
+    prompt = _render_worker_prompt(profile, packs)
+    return {
+        "target": "worker",
+        "profile": profile.name,
+        "packs": [pack.name for pack in packs],
+        "prompt": prompt,
+    }

subagent/runtime_service.py

@@ -0,0 +1,342 @@
+"""Worker runtime process management and IPC helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from .config import Launcher, SubagentConfig
+from .errors import SubagentError
+from .state import StateStore
+
+
+def runtime_socket_path(store: StateStore, worker_id: str) -> Path:
+    digest = hashlib.sha1(f"{store.db_path}:{worker_id}".encode("utf-8")).hexdigest()[:16]
+    return Path("/tmp") / f"subagent-rt-{digest}.sock"
+
+
+def runtime_log_path(store: StateStore, worker_id: str) -> Path:
+    return store.db_path.parent / "runtimes" / f"{worker_id}.log"
+
+
+def _send_socket_request(
+    socket_path: Path,
+    *,
+    method: str,
+    params: dict[str, Any],
+    timeout_seconds: float,
+) -> dict[str, Any]:
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
+            client.settimeout(timeout_seconds)
+            client.connect(str(socket_path))
+            payload = {
+                "method": method,
+                "params": params,
+            }
+            request_data = (json.dumps(payload, ensure_ascii=False) + "\n").encode("utf-8")
+            client.sendall(request_data)
+            chunks: list[bytes] = []
+            while True:
+                block = client.recv(4096)
+                if not block:
+                    break
+                chunks.append(block)
+                if b"\n" in block:
+                    break
+    except (FileNotFoundError, ConnectionRefusedError, socket.timeout, OSError) as exc:
+        raise SubagentError(
+            code="BACKEND_UNAVAILABLE",
+            message="Worker runtime is not reachable.",
+            details={
+                "socketPath": str(socket_path),
+                "method": method,
+                "error": str(exc),
+            },
+        ) from exc
+    raw = b"".join(chunks).decode("utf-8", errors="replace").strip()
+    if not raw:
+        raise SubagentError(
+            code="BACKEND_PROTOCOL_ERROR",
+            message="Worker runtime returned an empty response.",
+            details={"socketPath": str(socket_path), "method": method},
+        )
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise SubagentError(
+            code="BACKEND_PROTOCOL_ERROR",
+            message="Worker runtime returned invalid JSON.",
+            details={"socketPath": str(socket_path), "method": method, "response": raw},
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise SubagentError(
+            code="BACKEND_PROTOCOL_ERROR",
+            message="Worker runtime returned non-object response.",
+            details={"socketPath": str(socket_path), "method": method, "response": parsed},
+        )
+    return parsed
+
+
+def runtime_request(
+    store: StateStore,
+    *,
+    worker_id: str,
+    method: str,
+    params: dict[str, Any],
+    timeout_seconds: float = 30.0,
+) -> 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},
+        )
+    socket_path_raw = worker.get("runtime_socket")
+    if not isinstance(socket_path_raw, str) or not socket_path_raw:
+        raise SubagentError(
+            code="BACKEND_UNAVAILABLE",
+            message="Worker runtime is not initialized.",
+            details={"workerId": worker_id},
+        )
+    socket_path = Path(socket_path_raw)
+    response = _send_socket_request(
+        socket_path,
+        method=method,
+        params=params,
+        timeout_seconds=timeout_seconds,
+    )
+    ok = response.get("ok")
+    if ok is not True:
+        error_payload = response.get("error")
+        if isinstance(error_payload, dict):
+            raise SubagentError(
+                code=str(error_payload.get("code", "BACKEND_RPC_ERROR")),
+                message=str(error_payload.get("message", "Worker runtime request failed.")),
+                retryable=bool(error_payload.get("retryable", False)),
+                details=error_payload.get("details")
+                if isinstance(error_payload.get("details"), dict)
+                else {},
+            )
+        raise SubagentError(
+            code="BACKEND_RPC_ERROR",
+            message="Worker runtime request failed.",
+            details={"response": response},
+        )
+    result = response.get("result")
+    if not isinstance(result, dict):
+        raise SubagentError(
+            code="BACKEND_PROTOCOL_ERROR",
+            message="Worker runtime response missing result object.",
+            details={"response": response},
+        )
+    return result
+
+
+def _runtime_launch_command(
+    *,
+    store: StateStore,
+    worker_id: str,
+    socket_path: Path,
+    launcher: Launcher,
+    cwd: str,
+) -> list[str]:
+    return [
+        sys.executable,
+        "-m",
+        "subagent.worker_runtime",
+        "--db-path",
+        str(store.db_path),
+        "--worker-id",
+        worker_id,
+        "--socket-path",
+        str(socket_path),
+        "--launcher-command",
+        launcher.command,
+        "--launcher-args-json",
+        json.dumps(launcher.args, ensure_ascii=False),
+        "--launcher-env-json",
+        json.dumps(launcher.env, ensure_ascii=False),
+        "--cwd",
+        cwd,
+    ]
+
+
+def launch_worker_runtime(
+    store: StateStore,
+    *,
+    worker_id: str,
+    launcher: Launcher,
+    cwd: str,
+    timeout_seconds: float = 10.0,
+) -> dict[str, Any]:
+    socket_path = runtime_socket_path(store, worker_id)
+    if socket_path.exists():
+        socket_path.unlink()
+
+    log_path = runtime_log_path(store, worker_id)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    command = _runtime_launch_command(
+        store=store,
+        worker_id=worker_id,
+        socket_path=socket_path,
+        launcher=launcher,
+        cwd=cwd,
+    )
+    with log_path.open("a", encoding="utf-8") as log_file:
+        process = subprocess.Popen(
+            command,
+            stdout=log_file,
+            stderr=log_file,
+            stdin=subprocess.DEVNULL,
+            start_new_session=True,
+            text=True,
+            env=dict(os.environ),
+        )
+    store.set_worker_runtime_endpoint(
+        worker_id,
+        runtime_pid=process.pid,
+        runtime_socket=str(socket_path),
+    )
+
+    deadline = time.monotonic() + timeout_seconds
+    last_error: str | None = None
+    while time.monotonic() < deadline:
+        if process.poll() is not None:
+            last_error = f"runtime exited with code {process.returncode}"
+            break
+        if socket_path.exists():
+            try:
+                response = _send_socket_request(
+                    socket_path,
+                    method="ping",
+                    params={},
+                    timeout_seconds=1.0,
+                )
+            except SubagentError as error:
+                last_error = error.message
+            else:
+                if response.get("ok") is True:
+                    return {
+                        "pid": process.pid,
+                        "socketPath": str(socket_path),
+                        "logPath": str(log_path),
+                    }
+        time.sleep(0.1)
+    try:
+        process.terminate()
+        process.wait(timeout=1.0)
+    except Exception:  # pragma: no cover - cleanup best effort
+        try:
+            process.kill()
+        except Exception:
+            pass
+    store.clear_worker_runtime_endpoint(worker_id)
+    raise SubagentError(
+        code="BACKEND_UNAVAILABLE",
+        message="Failed to start worker runtime.",
+        details={
+            "workerId": worker_id,
+            "command": command,
+            "socketPath": str(socket_path),
+            "logPath": str(log_path),
+            "error": last_error,
+        },
+    )
+
+
+def restart_worker_runtime(
+    store: StateStore,
+    config: SubagentConfig,
+    *,
+    worker_id: str,
+    timeout_seconds: float = 10.0,
+) -> 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},
+        )
+    launcher_name = worker.get("launcher")
+    if not isinstance(launcher_name, str) or not launcher_name:
+        raise SubagentError(
+            code="BACKEND_UNAVAILABLE",
+            message="Worker launcher is not set.",
+            details={"workerId": worker_id},
+        )
+    launcher = config.launchers.get(launcher_name)
+    if launcher is None:
+        raise SubagentError(
+            code="LAUNCHER_NOT_FOUND",
+            message=f"Launcher not found: {launcher_name}",
+            details={"workerId": worker_id, "launcher": launcher_name},
+        )
+    if launcher.backend_kind != "acp-stdio":
+        raise SubagentError(
+            code="BACKEND_UNAVAILABLE",
+            message=f"Unsupported backend kind for runtime: {launcher.backend_kind}",
+            details={"workerId": worker_id, "launcher": launcher_name, "backendKind": launcher.backend_kind},
+        )
+    command = launcher.command
+    if shutil.which(command) is None and "/" not in command:
+        raise SubagentError(
+            code="BACKEND_UNAVAILABLE",
+            message=f"Launcher command not available: {command}",
+            details={"workerId": worker_id, "launcher": launcher_name, "command": command},
+        )
+    if "/" in command and not Path(command).expanduser().exists():
+        raise SubagentError(
+            code="BACKEND_UNAVAILABLE",
+            message=f"Launcher command not available: {command}",
+            details={"workerId": worker_id, "launcher": launcher_name, "command": command},
+        )
+    worker_cwd = worker.get("cwd")
+    if not isinstance(worker_cwd, str) or not worker_cwd:
+        raise SubagentError(
+            code="BACKEND_UNAVAILABLE",
+            message="Worker cwd is not available.",
+            details={"workerId": worker_id},
+        )
+    return launch_worker_runtime(
+        store,
+        worker_id=worker_id,
+        launcher=launcher,
+        cwd=worker_cwd,
+        timeout_seconds=timeout_seconds,
+    )
+
+
+def stop_worker_runtime(
+    store: StateStore,
+    *,
+    worker_id: str,
+    reason: str = "worker stopped",
+) -> None:
+    worker = store.get_worker(worker_id)
+    if worker is None:
+        return
+    runtime_socket = worker.get("runtime_socket")
+    if isinstance(runtime_socket, str) and runtime_socket:
+        try:
+            runtime_request(
+                store,
+                worker_id=worker_id,
+                method="stop",
+                params={"reason": reason},
+                timeout_seconds=5.0,
+            )
+        except SubagentError:
+            # Stopping should be best-effort.
+            pass
+    store.clear_worker_runtime_endpoint(worker_id)