subagent-cli 0.1.1__py3-none-any.whl

subagent/daemon.py

@@ -0,0 +1,133 @@
+"""Minimal local daemon process for subagent runtime bootstrap."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from .constants import DAEMON_STATUS_PATH
+from .output import emit_json
+from .paths import resolve_state_dir
+from .state import StateStore
+
+app = typer.Typer(help="subagentd: local control-plane daemon")
+
+
+def _utc_now() -> str:
+    return datetime.now(tz=UTC).replace(microsecond=0).isoformat()
+
+
+def _status_path_for_state_dir(state_dir: Path) -> Path:
+    default_parent = DAEMON_STATUS_PATH.parent
+    if state_dir == default_parent:
+        return DAEMON_STATUS_PATH
+    return state_dir / "subagentd-status.json"
+
+
+def _write_status(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+@app.command("run")
+def run_daemon(
+    once: bool = typer.Option(
+        False,
+        "--once",
+        help="Initialize state and exit immediately (bootstrap mode).",
+    ),
+    heartbeat_seconds: int = typer.Option(
+        5,
+        "--heartbeat-seconds",
+        min=1,
+        help="Heartbeat update interval when running foreground.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON response."),
+) -> None:
+    state_dir = resolve_state_dir()
+    store = StateStore(state_dir / "state.db")
+    store.bootstrap()
+    status_path = _status_path_for_state_dir(state_dir)
+    base_payload = {
+        "schemaVersion": "v1",
+        "pid": os.getpid(),
+        "stateDir": str(state_dir),
+        "dbPath": str(store.db_path),
+        "startedAt": _utc_now(),
+        "lastHeartbeatAt": _utc_now(),
+        "mode": "once" if once else "foreground",
+    }
+    _write_status(status_path, base_payload)
+
+    if once:
+        if json_output:
+            emit_json(base_payload)
+        else:
+            typer.echo(f"subagentd initialized: {store.db_path}")
+        return
+
+    if json_output:
+        emit_json(base_payload)
+    else:
+        typer.echo(f"subagentd running (pid={base_payload['pid']})")
+    try:
+        while True:
+            time.sleep(heartbeat_seconds)
+            base_payload["lastHeartbeatAt"] = _utc_now()
+            _write_status(status_path, base_payload)
+    except KeyboardInterrupt:
+        base_payload["stoppedAt"] = _utc_now()
+        _write_status(status_path, base_payload)
+        raise typer.Exit(code=0)
+
+
+@app.command("status")
+def daemon_status(
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON response."),
+) -> None:
+    state_dir = resolve_state_dir()
+    status_path = _status_path_for_state_dir(state_dir)
+    if not status_path.exists():
+        payload = {
+            "schemaVersion": "v1",
+            "running": False,
+            "stateDir": str(state_dir),
+            "statusFile": str(status_path),
+        }
+        if json_output:
+            emit_json(payload)
+        else:
+            typer.echo("subagentd not initialized")
+        raise typer.Exit(code=1)
+    payload = json.loads(status_path.read_text(encoding="utf-8"))
+    pid = payload.get("pid")
+    running = False
+    if isinstance(pid, int):
+        try:
+            os.kill(pid, 0)
+        except OSError:
+            running = False
+        else:
+            running = True
+    payload["running"] = running
+    if json_output:
+        emit_json(payload)
+    else:
+        typer.echo(
+            f"subagentd running={running} pid={payload.get('pid')} "
+            f"startedAt={payload.get('startedAt')}"
+        )
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

subagent/errors.py

@@ -0,0 +1,24 @@
+"""Typed errors with stable error codes for CLI contracts."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class SubagentError(Exception):
+    """Error mapped to the versioned CLI error envelope."""
+
+    code: str
+    message: str
+    retryable: bool = False
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "code": self.code,
+            "message": self.message,
+            "retryable": self.retryable,
+        }
+        if self.details:
+            payload["details"] = self.details
+        return payload

subagent/handoff_service.py

@@ -0,0 +1,354 @@
+"""Handoff artifact generation and continue flow."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from pathlib import Path
+from typing import Any
+
+from .config import SubagentConfig
+from .errors import SubagentError
+from .paths import resolve_handoffs_dir, resolve_workspace_path
+from .state import StateStore
+from .turn_service import send_message
+from .worker_service import start_worker
+
+
+def _safe_text(value: Any, default: str) -> str:
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return default
+
+
+def _pick_task_from_events(events: list[dict[str, Any]]) -> str:
+    for event in events:
+        if str(event.get("event_type")) != "message.sent":
+            continue
+        data = event.get("data")
+        if not isinstance(data, dict):
+            continue
+        text = data.get("text")
+        if isinstance(text, str) and text.strip():
+            return text.strip()
+    return "Continue the previous worker task safely."
+
+
+def _pick_turn_id(events: list[dict[str, Any]]) -> str | None:
+    for event in reversed(events):
+        turn_id = event.get("turn_id")
+        if isinstance(turn_id, str) and turn_id:
+            return turn_id
+    return None
+
+
+def _build_handoff_markdown(
+    *,
+    worker: dict[str, Any],
+    task: str,
+    completed_lines: list[str],
+    pending_lines: list[str],
+    risk_lines: list[str],
+    handoff_path: Path,
+    checkpoint_path: Path,
+) -> str:
+    files_of_interest = "- (not captured in v1 fallback handoff)"
+    commands_run = "- (not captured in v1 fallback handoff)"
+    completed = "\n".join(completed_lines or ["- No completed steps captured yet."])
+    pending = "\n".join(pending_lines or ["- No explicit pending items captured."])
+    risks = "\n".join(risk_lines or ["- No explicit risks captured."])
+    recommended = (
+        f"- Run `subagent worker continue --from-worker {worker['worker_id']}` to continue with a new worker."
+    )
+    artifacts = "\n".join(
+        [
+            f"- {handoff_path}",
+            f"- {checkpoint_path}",
+        ]
+    )
+    lines = [
+        "# Handoff",
+        "",
+        "## Task",
+        task,
+        "",
+        "## Goal",
+        "Continue from the latest known context and complete the pending work safely.",
+        "",
+        "## Current Status",
+        f"Worker `{worker['worker_id']}` is currently `{worker['state']}`.",
+        "",
+        "## Completed",
+        completed,
+        "",
+        "## Pending",
+        pending,
+        "",
+        "## Files of Interest",
+        files_of_interest,
+        "",
+        "## Commands Run",
+        commands_run,
+        "",
+        "## Risks / Notes",
+        risks,
+        "",
+        "## Recommended Next Step",
+        recommended,
+        "",
+        "## Artifacts",
+        artifacts,
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def create_handoff(
+    store: StateStore,
+    *,
+    worker_id: str,
+    handoffs_dir: Path | None = None,
+) -> 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},
+        )
+    events = store.list_worker_events(worker_id)
+    task = _pick_task_from_events(events)
+    source_turn_id = _pick_turn_id(events)
+
+    completed_lines: list[str] = []
+    pending_lines: list[str] = []
+    for event in events:
+        event_type = str(event.get("event_type"))
+        turn_id = event.get("turn_id")
+        if event_type == "turn.completed":
+            data = event.get("data") if isinstance(event.get("data"), dict) else {}
+            outcome = _safe_text(data.get("outcome"), "completed")
+            completed_lines.append(f"- Turn `{turn_id}` completed with outcome `{outcome}`.")
+        if event_type == "approval.requested":
+            data = event.get("data") if isinstance(event.get("data"), dict) else {}
+            request_id = _safe_text(data.get("requestId"), "unknown")
+            pending_lines.append(f"- Approval decision pending for request `{request_id}`.")
+
+    pending_requests = store.list_pending_approval_requests(worker_id)
+    risk_lines = [
+        f"- Pending approval request `{req['request_id']}` may block continuation."
+        for req in pending_requests
+    ]
+
+    root = resolve_handoffs_dir(handoffs_dir)
+    snapshot_id = f"hs_{uuid.uuid4().hex[:10]}"
+    snapshot_dir = root / worker_id / snapshot_id
+    snapshot_dir.mkdir(parents=True, exist_ok=True)
+    handoff_path = snapshot_dir / "handoff.md"
+    checkpoint_path = snapshot_dir / "checkpoint.json"
+
+    markdown = _build_handoff_markdown(
+        worker=worker,
+        task=task,
+        completed_lines=completed_lines,
+        pending_lines=pending_lines,
+        risk_lines=risk_lines,
+        handoff_path=handoff_path,
+        checkpoint_path=checkpoint_path,
+    )
+    handoff_path.write_text(markdown, encoding="utf-8")
+
+    checkpoint = {
+        "schemaVersion": "v1",
+        "workerId": worker["worker_id"],
+        "controllerId": worker["controller_id"],
+        "launcher": worker["launcher"],
+        "profile": worker["profile"],
+        "packs": worker["packs"],
+        "cwd": worker["cwd"],
+        "state": "handoff_ready",
+        "sourceTurnId": source_turn_id,
+        "handoffPath": str(handoff_path),
+        "artifacts": [str(handoff_path)],
+        "filesChanged": [],
+    }
+    checkpoint_path.write_text(
+        json.dumps(checkpoint, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+    snapshot = store.register_handoff_snapshot(
+        worker_id=worker_id,
+        source_turn_id=source_turn_id,
+        handoff_path=str(handoff_path),
+        checkpoint_path=str(checkpoint_path),
+    )
+    return {
+        "snapshotId": snapshot["snapshot_id"],
+        "workerId": worker_id,
+        "handoffPath": str(handoff_path),
+        "checkpointPath": str(checkpoint_path),
+        "sourceTurnId": source_turn_id,
+    }
+
+
+def _load_checkpoint_if_exists(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def resolve_handoff_input(
+    store: StateStore,
+    *,
+    from_worker: str | None,
+    from_handoff: Path | None,
+    handoffs_dir: Path | None = None,
+) -> dict[str, Any]:
+    if bool(from_worker) == bool(from_handoff):
+        raise SubagentError(
+            code="INVALID_ARGUMENT",
+            message="Specify exactly one of --from-worker or --from-handoff.",
+        )
+
+    if from_worker:
+        latest = store.get_latest_handoff_snapshot(from_worker)
+        if latest is None:
+            created = create_handoff(store, worker_id=from_worker, handoffs_dir=handoffs_dir)
+            handoff_path = Path(created["handoffPath"]).expanduser().resolve()
+            checkpoint_path = Path(created["checkpointPath"]).expanduser().resolve()
+            checkpoint = _load_checkpoint_if_exists(checkpoint_path)
+            return {
+                "sourceWorkerId": from_worker,
+                "handoffPath": handoff_path,
+                "checkpointPath": checkpoint_path,
+                "checkpoint": checkpoint,
+            }
+        handoff_path = Path(str(latest["handoff_path"])).expanduser().resolve()
+        checkpoint_path = Path(str(latest["checkpoint_path"])).expanduser().resolve()
+        checkpoint = _load_checkpoint_if_exists(checkpoint_path)
+        return {
+            "sourceWorkerId": from_worker,
+            "handoffPath": handoff_path,
+            "checkpointPath": checkpoint_path,
+            "checkpoint": checkpoint,
+        }
+
+    assert from_handoff is not None
+    handoff_path = from_handoff.expanduser().resolve()
+    if not handoff_path.exists():
+        raise SubagentError(
+            code="HANDOFF_NOT_FOUND",
+            message=f"Handoff file not found: {handoff_path}",
+            details={"handoffPath": str(handoff_path)},
+        )
+    checkpoint_path = handoff_path.parent / "checkpoint.json"
+    checkpoint = _load_checkpoint_if_exists(checkpoint_path)
+    source_worker_id = checkpoint.get("workerId")
+    source_worker = str(source_worker_id) if isinstance(source_worker_id, str) else None
+    return {
+        "sourceWorkerId": source_worker,
+        "handoffPath": handoff_path,
+        "checkpointPath": checkpoint_path if checkpoint_path.exists() else None,
+        "checkpoint": checkpoint,
+    }
+
+
+def continue_worker(
+    store: StateStore,
+    config: SubagentConfig,
+    *,
+    from_worker: str | None,
+    from_handoff: Path | None,
+    launcher: str | None,
+    profile: str | None,
+    packs: list[str],
+    cwd: Path | None,
+    label: str | None,
+    controller_id: str | None,
+    handoffs_dir: Path | None = None,
+    debug_mode: bool = False,
+    execution_mode: str = "strict",
+) -> dict[str, Any]:
+    source = resolve_handoff_input(
+        store,
+        from_worker=from_worker,
+        from_handoff=from_handoff,
+        handoffs_dir=handoffs_dir,
+    )
+    checkpoint = source.get("checkpoint", {})
+    if not isinstance(checkpoint, dict):
+        checkpoint = {}
+
+    source_handoff_path = Path(source["handoffPath"])
+    source_worker_id = source.get("sourceWorkerId")
+    checkpoint_launcher = checkpoint.get("launcher")
+    checkpoint_profile = checkpoint.get("profile")
+    checkpoint_packs = checkpoint.get("packs")
+    checkpoint_cwd = checkpoint.get("cwd")
+    checkpoint_controller = checkpoint.get("controllerId")
+
+    target_launcher = launcher or (str(checkpoint_launcher) if isinstance(checkpoint_launcher, str) else None)
+    target_profile = profile or (str(checkpoint_profile) if isinstance(checkpoint_profile, str) else None)
+    target_packs: list[str]
+    if packs:
+        target_packs = packs
+    elif isinstance(checkpoint_packs, list):
+        target_packs = [str(item) for item in checkpoint_packs]
+    else:
+        target_packs = []
+
+    target_cwd = resolve_workspace_path(cwd if cwd is not None else Path(str(checkpoint_cwd)) if isinstance(checkpoint_cwd, str) else Path.cwd())
+    target_controller = controller_id or (
+        str(checkpoint_controller) if isinstance(checkpoint_controller, str) else None
+    )
+    target_label = label or (
+        f"continued-from-{source_worker_id}" if isinstance(source_worker_id, str) and source_worker_id else "continued-worker"
+    )
+
+    started = start_worker(
+        store,
+        config,
+        workspace=target_cwd,
+        worker_cwd=target_cwd,
+        controller_id=target_controller,
+        launcher=target_launcher,
+        profile=target_profile,
+        packs=target_packs,
+        label=target_label,
+        debug_mode=debug_mode,
+    )
+
+    prompt_text = (
+        "Read the handoff document and continue from the previous worker context. "
+        "Validate with the repository state and proceed with the next safe step."
+    )
+    blocks = [
+        {
+            "type": "resource_link",
+            "resource": {
+                "uri": source_handoff_path.as_uri(),
+                "mimeType": "text/markdown",
+            },
+        }
+    ]
+    turn = send_message(
+        store,
+        worker_id=str(started["workerId"]),
+        text=prompt_text,
+        blocks=blocks,
+        request_approval=False,
+        config=config,
+        execution_mode=execution_mode,
+    )
+    return {
+        "sourceWorkerId": source_worker_id,
+        "sourceHandoffPath": str(source_handoff_path),
+        "checkpointPath": str(source["checkpointPath"]) if source.get("checkpointPath") else None,
+        "worker": started,
+        "bootstrapTurn": turn,
+    }

subagent/hints.py

@@ -0,0 +1,36 @@
+"""Project-local controller hint read/write helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .constants import SCHEMA_VERSION
+from .paths import project_hint_path
+
+
+def read_project_hint(workspace: Path) -> dict[str, Any] | None:
+    hint_path = project_hint_path(workspace)
+    if not hint_path.exists():
+        return None
+    try:
+        payload = json.loads(hint_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(payload, dict):
+        return None
+    return payload
+
+
+def write_project_hint(workspace: Path, *, controller_id: str, label: str) -> Path:
+    hint_path = project_hint_path(workspace)
+    hint_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "schemaVersion": SCHEMA_VERSION,
+        "controllerId": controller_id,
+        "label": label,
+        "workspaceKey": str(workspace),
+    }
+    hint_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    return hint_path

subagent/input_contract.py

@@ -0,0 +1,121 @@
+"""Helpers for `--input` JSON contract and duplicate field protection."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .errors import SubagentError
+
+
+def load_input_payload(input_path: str | None) -> dict[str, Any] | None:
+    if input_path is None:
+        return None
+    if input_path == "-":
+        import sys
+
+        raw = sys.stdin.read()
+    else:
+        raw = Path(input_path).read_text(encoding="utf-8")
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise SubagentError(
+            code="INVALID_INPUT",
+            message="--input must contain valid JSON",
+            details={"error": str(error)},
+        ) from error
+    if not isinstance(payload, dict):
+        raise SubagentError(
+            code="INVALID_INPUT",
+            message="--input JSON must be an object",
+        )
+    return payload
+
+
+def reject_duplicates(
+    payload: dict[str, Any] | None,
+    *,
+    flag_values: dict[str, Any],
+    value_is_default: dict[str, bool],
+    mapping: dict[str, str],
+) -> None:
+    if payload is None:
+        return
+    for json_field, flag_name in mapping.items():
+        if json_field not in payload:
+            continue
+        if flag_name not in flag_values:
+            continue
+        if value_is_default.get(flag_name, True):
+            continue
+        raise SubagentError(
+            code="INVALID_INPUT",
+            message=f"Field `{json_field}` is provided by both --input and flags.",
+            details={"field": json_field, "flag": flag_name},
+        )
+
+
+def read_string(payload: dict[str, Any], key: str) -> str | None:
+    value = payload.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise SubagentError(
+            code="INVALID_INPUT",
+            message=f"`{key}` must be a string",
+        )
+    return value
+
+
+def read_bool(payload: dict[str, Any], key: str) -> bool | None:
+    if key not in payload:
+        return None
+    value = payload[key]
+    if not isinstance(value, bool):
+        raise SubagentError(
+            code="INVALID_INPUT",
+            message=f"`{key}` must be a boolean",
+        )
+    return value
+
+
+def read_string_list(payload: dict[str, Any], key: str) -> list[str] | None:
+    if key not in payload:
+        return None
+    value = payload[key]
+    if not isinstance(value, list):
+        raise SubagentError(
+            code="INVALID_INPUT",
+            message=f"`{key}` must be a list of strings",
+        )
+    out: list[str] = []
+    for idx, item in enumerate(value):
+        if not isinstance(item, str):
+            raise SubagentError(
+                code="INVALID_INPUT",
+                message=f"`{key}[{idx}]` must be a string",
+            )
+        out.append(item)
+    return out
+
+
+def read_blocks(payload: dict[str, Any], key: str = "blocks") -> list[dict[str, Any]] | None:
+    if key not in payload:
+        return None
+    value = payload[key]
+    if not isinstance(value, list):
+        raise SubagentError(
+            code="INVALID_INPUT",
+            message=f"`{key}` must be a list",
+        )
+    blocks: list[dict[str, Any]] = []
+    for idx, item in enumerate(value):
+        if not isinstance(item, dict):
+            raise SubagentError(
+                code="INVALID_INPUT",
+                message=f"`{key}[{idx}]` must be an object",
+            )
+        blocks.append(item)
+    return blocks

subagent/launcher_service.py

@@ -0,0 +1,30 @@
+"""Launcher helper operations (e.g., probe)."""
+
+from __future__ import annotations
+
+import shutil
+from typing import Any
+
+from .config import SubagentConfig
+from .errors import SubagentError
+
+
+def probe_launcher(config: SubagentConfig, launcher_name: str) -> dict[str, Any]:
+    launcher = config.launchers.get(launcher_name)
+    if launcher is None:
+        raise SubagentError(
+            code="LAUNCHER_NOT_FOUND",
+            message=f"Launcher not found: {launcher_name}",
+            details={"launcher": launcher_name},
+        )
+    command_path = shutil.which(launcher.command)
+    available = command_path is not None
+    return {
+        "name": launcher.name,
+        "backendKind": launcher.backend_kind,
+        "command": launcher.command,
+        "resolvedCommandPath": command_path,
+        "available": available,
+        "args": launcher.args,
+        "envKeys": sorted(launcher.env.keys()),
+    }