subagent-cli 0.1.1__py3-none-any.whl

subagent/config.py

@@ -0,0 +1,305 @@
+"""Config model and loader for launchers / profiles / packs."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+from .errors import SubagentError
+from .paths import resolve_config_path
+from .simple_yaml import ParseError as SimpleYamlParseError
+from .simple_yaml import parse_yaml_subset
+
+
+def _ensure_mapping(value: Any, *, field_name: str) -> Mapping[str, Any]:
+    if isinstance(value, Mapping):
+        return value
+    raise SubagentError(
+        code="CONFIG_PARSE_ERROR",
+        message=f"`{field_name}` must be a mapping",
+        details={"field": field_name},
+    )
+
+
+def _ensure_string_list(value: Any, *, field_name: str) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise SubagentError(
+            code="CONFIG_PARSE_ERROR",
+            message=f"`{field_name}` must be a list",
+            details={"field": field_name},
+        )
+    string_values: list[str] = []
+    for idx, item in enumerate(value):
+        if not isinstance(item, str):
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"`{field_name}[{idx}]` must be a string",
+                details={"field": field_name, "index": idx},
+            )
+        string_values.append(item)
+    return string_values
+
+
+def _ensure_string_map(value: Any, *, field_name: str) -> dict[str, str]:
+    if value is None:
+        return {}
+    mapping = _ensure_mapping(value, field_name=field_name)
+    string_map: dict[str, str] = {}
+    for key, item in mapping.items():
+        if not isinstance(key, str):
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"`{field_name}` key must be string",
+                details={"field": field_name},
+            )
+        if not isinstance(item, str):
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"`{field_name}.{key}` must be string",
+                details={"field": field_name, "key": key},
+            )
+        string_map[key] = item
+    return string_map
+
+
+@dataclass(slots=True)
+class Launcher:
+    name: str
+    backend_kind: str
+    command: str
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "backend": {"kind": self.backend_kind},
+            "command": self.command,
+            "args": self.args,
+            "env": self.env,
+        }
+
+
+@dataclass(slots=True)
+class Profile:
+    name: str
+    prompt_language: str = "en"
+    response_language: str = "same_as_manager"
+    auto_handoff: str | None = None
+    policy_preset: str | None = None
+    default_packs: list[str] = field(default_factory=list)
+    bootstrap: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "promptLanguage": self.prompt_language,
+            "responseLanguage": self.response_language,
+            "autoHandoff": self.auto_handoff,
+            "policyPreset": self.policy_preset,
+            "defaultPacks": self.default_packs,
+            "bootstrap": self.bootstrap,
+        }
+
+
+@dataclass(slots=True)
+class Pack:
+    name: str
+    description: str = ""
+    prompt: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "prompt": self.prompt,
+        }
+
+
+@dataclass(slots=True)
+class SubagentConfig:
+    path: Path
+    loaded: bool
+    launchers: dict[str, Launcher] = field(default_factory=dict)
+    profiles: dict[str, Profile] = field(default_factory=dict)
+    packs: dict[str, Pack] = field(default_factory=dict)
+    policy_presets: dict[str, Any] = field(default_factory=dict)
+    defaults: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": str(self.path),
+            "loaded": self.loaded,
+            "launchers": {name: launcher.to_dict() for name, launcher in self.launchers.items()},
+            "profiles": {name: profile.to_dict() for name, profile in self.profiles.items()},
+            "packs": {name: pack.to_dict() for name, pack in self.packs.items()},
+            "policyPresets": self.policy_presets,
+            "defaults": self.defaults,
+        }
+
+
+def _load_raw_config(config_path: Path) -> Mapping[str, Any]:
+    contents = config_path.read_text(encoding="utf-8")
+
+    # Use YAML if available; fallback to JSON for sandbox/offline bootstrap.
+    try:
+        import yaml  # type: ignore[import-not-found]
+    except ModuleNotFoundError:
+        try:
+            parsed = json.loads(contents)
+        except json.JSONDecodeError as exc:
+            try:
+                parsed = parse_yaml_subset(contents)
+            except SimpleYamlParseError as yaml_exc:
+                raise SubagentError(
+                    code="CONFIG_PARSE_ERROR",
+                    message=(
+                        "Failed to parse config as JSON or YAML subset. "
+                        "Install PyYAML for full YAML support."
+                    ),
+                    details={
+                        "path": str(config_path),
+                        "jsonError": str(exc),
+                        "yamlError": str(yaml_exc),
+                    },
+                ) from yaml_exc
+    else:
+        try:
+            parsed = yaml.safe_load(contents)
+        except Exception as exc:  # pragma: no cover - parser raises varied exceptions
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"Failed to parse config file: {config_path}",
+                details={"path": str(config_path), "error": str(exc)},
+            ) from exc
+
+    if parsed is None:
+        parsed = {}
+    return _ensure_mapping(parsed, field_name="root")
+
+
+def _parse_launchers(raw: Any) -> dict[str, Launcher]:
+    mapping = _ensure_mapping(raw or {}, field_name="launchers")
+    launchers: dict[str, Launcher] = {}
+    for name, payload in mapping.items():
+        entry = _ensure_mapping(payload, field_name=f"launchers.{name}")
+        backend = _ensure_mapping(entry.get("backend", {}), field_name=f"launchers.{name}.backend")
+        command = entry.get("command")
+        if not isinstance(command, str) or not command.strip():
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"`launchers.{name}.command` must be a non-empty string",
+                details={"launcher": name},
+            )
+        launchers[name] = Launcher(
+            name=name,
+            backend_kind=str(backend.get("kind", "acp-stdio")),
+            command=command,
+            args=_ensure_string_list(entry.get("args"), field_name=f"launchers.{name}.args"),
+            env=_ensure_string_map(entry.get("env"), field_name=f"launchers.{name}.env"),
+        )
+    return launchers
+
+
+def _parse_profiles(raw: Any) -> dict[str, Profile]:
+    mapping = _ensure_mapping(raw or {}, field_name="profiles")
+    profiles: dict[str, Profile] = {}
+    for name, payload in mapping.items():
+        entry = _ensure_mapping(payload, field_name=f"profiles.{name}")
+        prompt_language = entry.get("promptLanguage", "en")
+        response_language = entry.get("responseLanguage", "same_as_manager")
+        auto_handoff = entry.get("autoHandoff")
+        policy_preset = entry.get("policyPreset")
+        bootstrap = entry.get("bootstrap", "")
+        if not isinstance(prompt_language, str) or not isinstance(response_language, str):
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"`profiles.{name}` language fields must be strings",
+                details={"profile": name},
+            )
+        if auto_handoff is not None and not isinstance(auto_handoff, str):
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"`profiles.{name}.autoHandoff` must be string or null",
+                details={"profile": name},
+            )
+        if policy_preset is not None and not isinstance(policy_preset, str):
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"`profiles.{name}.policyPreset` must be string or null",
+                details={"profile": name},
+            )
+        if not isinstance(bootstrap, str):
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"`profiles.{name}.bootstrap` must be a string",
+                details={"profile": name},
+            )
+        profiles[name] = Profile(
+            name=name,
+            prompt_language=prompt_language,
+            response_language=response_language,
+            auto_handoff=auto_handoff,
+            policy_preset=policy_preset,
+            default_packs=_ensure_string_list(
+                entry.get("defaultPacks"),
+                field_name=f"profiles.{name}.defaultPacks",
+            ),
+            bootstrap=bootstrap,
+        )
+    return profiles
+
+
+def _parse_packs(raw: Any) -> dict[str, Pack]:
+    mapping = _ensure_mapping(raw or {}, field_name="packs")
+    packs: dict[str, Pack] = {}
+    for name, payload in mapping.items():
+        entry = _ensure_mapping(payload, field_name=f"packs.{name}")
+        description = entry.get("description", "")
+        prompt = entry.get("prompt", "")
+        if not isinstance(description, str) or not isinstance(prompt, str):
+            raise SubagentError(
+                code="CONFIG_PARSE_ERROR",
+                message=f"`packs.{name}` fields must be strings",
+                details={"pack": name},
+            )
+        packs[name] = Pack(name=name, description=description, prompt=prompt)
+    return packs
+
+
+def load_config(config_path: Path | None = None) -> SubagentConfig:
+    resolved_path = resolve_config_path(config_path)
+    if not resolved_path.exists():
+        return SubagentConfig(path=resolved_path, loaded=False)
+    raw = _load_raw_config(resolved_path)
+    policy_presets = raw.get("policyPresets", {})
+    defaults = raw.get("defaults", {})
+    if policy_presets is None:
+        policy_presets = {}
+    if defaults is None:
+        defaults = {}
+    if not isinstance(policy_presets, dict):
+        raise SubagentError(
+            code="CONFIG_PARSE_ERROR",
+            message="`policyPresets` must be a mapping",
+            details={"field": "policyPresets"},
+        )
+    if not isinstance(defaults, dict):
+        raise SubagentError(
+            code="CONFIG_PARSE_ERROR",
+            message="`defaults` must be a mapping",
+            details={"field": "defaults"},
+        )
+    return SubagentConfig(
+        path=resolved_path,
+        loaded=True,
+        launchers=_parse_launchers(raw.get("launchers")),
+        profiles=_parse_profiles(raw.get("profiles")),
+        packs=_parse_packs(raw.get("packs")),
+        policy_presets=policy_presets,
+        defaults=defaults,
+    )

subagent/constants.py

@@ -0,0 +1,21 @@
+"""Shared constants used across the subagent CLI."""
+
+from pathlib import Path
+
+APP_NAME = "subagent"
+SCHEMA_VERSION = "v1"
+
+ENV_CONFIG_PATH = "SUBAGENT_CONFIG"
+ENV_STATE_DIR = "SUBAGENT_STATE_DIR"
+ENV_CTL_ID = "SUBAGENT_CTL_ID"
+ENV_CTL_EPOCH = "SUBAGENT_CTL_EPOCH"
+ENV_CTL_TOKEN = "SUBAGENT_CTL_TOKEN"
+
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / APP_NAME / "config.yaml"
+DEFAULT_STATE_DIR = Path.home() / ".local" / "share" / APP_NAME
+DEFAULT_STATE_DB_PATH = DEFAULT_STATE_DIR / "state.db"
+DAEMON_STATUS_PATH = DEFAULT_STATE_DIR / "subagentd-status.json"
+DEFAULT_HANDOFFS_DIR = DEFAULT_STATE_DIR / "handoffs"
+
+PROJECT_HINT_DIRNAME = ".subagent"
+PROJECT_HINT_FILENAME = "controller.json"

subagent/controller_service.py

@@ -0,0 +1,267 @@
+"""Controller ownership orchestration."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .constants import ENV_CTL_EPOCH, ENV_CTL_ID, ENV_CTL_TOKEN
+from .errors import SubagentError
+from .hints import read_project_hint, write_project_hint
+from .paths import resolve_workspace_path
+from .state import ControllerHandle, StateStore
+
+
+def _generate_controller_id() -> str:
+    return f"ctl_{uuid.uuid4().hex[:10]}"
+
+
+@dataclass(slots=True)
+class InitializedController:
+    controller_id: str
+    label: str
+    workspace_key: str
+    hint_path: str
+    owner: ControllerHandle
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "controllerId": self.controller_id,
+            "label": self.label,
+            "workspaceKey": self.workspace_key,
+            "hintPath": self.hint_path,
+            "owner": self.owner.to_dict(),
+        }
+
+
+def resolve_controller_id(
+    store: StateStore,
+    workspace: Path,
+    *,
+    explicit_controller_id: str | None = None,
+) -> str | None:
+    if explicit_controller_id:
+        return explicit_controller_id
+    hint = read_project_hint(workspace)
+    if hint and isinstance(hint.get("controllerId"), str):
+        return str(hint["controllerId"])
+    row = store.get_controller_by_workspace(str(workspace))
+    if row:
+        return str(row["controller_id"])
+    return None
+
+
+def init_controller(
+    store: StateStore,
+    *,
+    workspace: Path,
+    controller_id: str | None,
+    label: str,
+    pid: int | None = None,
+) -> InitializedController:
+    resolved_workspace = resolve_workspace_path(workspace)
+    existing_id = resolve_controller_id(
+        store,
+        resolved_workspace,
+        explicit_controller_id=controller_id,
+    )
+    target_controller_id = existing_id or _generate_controller_id()
+    controller_row = store.register_controller(
+        controller_id=target_controller_id,
+        label=label,
+        workspace_key=str(resolved_workspace),
+    )
+    owner = store.acquire_owner_handle(
+        target_controller_id,
+        takeover=False,
+        pid=pid if pid is not None else os.getpid(),
+    )
+    hint_path = write_project_hint(
+        resolved_workspace,
+        controller_id=target_controller_id,
+        label=str(controller_row["label"]),
+    )
+    return InitializedController(
+        controller_id=target_controller_id,
+        label=str(controller_row["label"]),
+        workspace_key=str(resolved_workspace),
+        hint_path=str(hint_path),
+        owner=owner,
+    )
+
+
+def attach_controller(
+    store: StateStore,
+    *,
+    workspace: Path,
+    controller_id: str | None,
+    takeover: bool,
+    pid: int | None = None,
+) -> InitializedController:
+    resolved_workspace = resolve_workspace_path(workspace)
+    target_controller_id = resolve_controller_id(
+        store,
+        resolved_workspace,
+        explicit_controller_id=controller_id,
+    )
+    if target_controller_id is None:
+        raise SubagentError(
+            code="CONTROLLER_NOT_FOUND",
+            message=(
+                "Controller could not be resolved. Specify --controller-id "
+                "or run `subagent controller init` first."
+            ),
+            details={"workspaceKey": str(resolved_workspace)},
+        )
+    controller_row = store.get_controller(target_controller_id)
+    if controller_row is None:
+        raise SubagentError(
+            code="CONTROLLER_NOT_FOUND",
+            message=f"Controller not found: {target_controller_id}",
+            details={"controllerId": target_controller_id},
+        )
+    owner = store.acquire_owner_handle(
+        target_controller_id,
+        takeover=takeover,
+        pid=pid if pid is not None else os.getpid(),
+    )
+    hint_path = write_project_hint(
+        resolved_workspace,
+        controller_id=target_controller_id,
+        label=str(controller_row["label"]),
+    )
+    return InitializedController(
+        controller_id=target_controller_id,
+        label=str(controller_row["label"]),
+        workspace_key=str(resolved_workspace),
+        hint_path=str(hint_path),
+        owner=owner,
+    )
+
+
+def read_env_handle() -> dict[str, Any] | None:
+    controller_id = os.environ.get(ENV_CTL_ID)
+    epoch_text = os.environ.get(ENV_CTL_EPOCH)
+    token = os.environ.get(ENV_CTL_TOKEN)
+    if not controller_id or not epoch_text or not token:
+        return None
+    try:
+        epoch = int(epoch_text)
+    except ValueError:
+        return {
+            "controllerId": controller_id,
+            "epochRaw": epoch_text,
+            "token": token,
+            "valid": False,
+            "reason": "ENV_EPOCH_NOT_INTEGER",
+        }
+    return {
+        "controllerId": controller_id,
+        "epoch": epoch,
+        "token": token,
+    }
+
+
+def shell_env_exports(handle: ControllerHandle) -> list[str]:
+    return [
+        f"export {ENV_CTL_ID}={handle.controller_id}",
+        f"export {ENV_CTL_EPOCH}={handle.epoch}",
+        f"export {ENV_CTL_TOKEN}={handle.token}",
+    ]
+
+
+def release_controller(
+    store: StateStore,
+    *,
+    workspace: Path,
+    controller_id: str | None,
+    force: bool,
+) -> dict[str, Any]:
+    resolved_workspace = resolve_workspace_path(workspace)
+    target_controller_id = resolve_controller_id(
+        store,
+        resolved_workspace,
+        explicit_controller_id=controller_id,
+    )
+    if target_controller_id is None:
+        raise SubagentError(
+            code="CONTROLLER_NOT_FOUND",
+            message="Controller could not be resolved for release.",
+            details={"workspaceKey": str(resolved_workspace)},
+        )
+    env_handle = read_env_handle()
+    epoch: int | None = None
+    token: str | None = None
+    if env_handle is not None and "epoch" in env_handle and "token" in env_handle:
+        if str(env_handle.get("controllerId")) == target_controller_id:
+            epoch = int(env_handle["epoch"])
+            token = str(env_handle["token"])
+    return store.release_owner_handle(
+        controller_id=target_controller_id,
+        epoch=epoch,
+        token=token,
+        force=force,
+    )
+
+
+def recover_controllers(store: StateStore, *, workspace: Path | None = None) -> dict[str, Any]:
+    workspace_key = str(resolve_workspace_path(workspace)) if workspace is not None else None
+    controllers = store.list_controllers()
+    active_instances = store.list_active_instances()
+    active_by_controller = {str(item["controller_id"]): item for item in active_instances}
+
+    recovered: list[dict[str, Any]] = []
+    for controller in controllers:
+        controller_id = str(controller["controller_id"])
+        if workspace_key and str(controller["workspace_key"]) != workspace_key:
+            continue
+        active = active_by_controller.get(controller_id)
+        owner_alive: bool | None = None
+        if active is not None and active.get("pid") is not None:
+            pid = int(active["pid"])
+            try:
+                os.kill(pid, 0)
+            except OSError:
+                owner_alive = False
+            else:
+                owner_alive = True
+        if active is None:
+            state = "dormant"
+        elif owner_alive is True:
+            state = "active"
+        elif owner_alive is False:
+            state = "orphaned"
+        else:
+            state = "conflicted"
+        recovered.append(
+            {
+                "controllerId": controller_id,
+                "label": controller["label"],
+                "workspaceKey": controller["workspace_key"],
+                "state": state,
+                "activeOwner": (
+                    {
+                        "instanceId": active["instance_id"],
+                        "epoch": active["epoch"],
+                        "pid": active["pid"],
+                        "createdAt": active["created_at"],
+                        "alive": owner_alive,
+                    }
+                    if active is not None
+                    else None
+                ),
+                "suggestedAction": (
+                    f"subagent controller attach --cwd {controller['workspace_key']} --takeover"
+                    if state in {"orphaned", "conflicted"}
+                    else None
+                ),
+            }
+        )
+    return {
+        "count": len(recovered),
+        "items": recovered,
+        "workspaceFilter": workspace_key,
+    }