multi-agent-platform 0.1.0__py3-none-any.whl

cli/commands/action.py

@@ -0,0 +1,142 @@
+"""``map action ...`` sub-app — arch experiment 0519e2a3 PR7.
+
+Topic action item lifecycle. Action items are surfaced in
+``map todos.action_items`` (waker D6 stage: WAKE / STALE escalation).
+All command bodies lazy-import ``cli.main._run`` to break the
+``cli.main ↔ cli.commands.*`` import cycle.
+"""
+from __future__ import annotations
+
+import uuid
+
+import typer
+from map_client.client import MAPClient
+
+action_app = typer.Typer(help="Topic action item commands")
+
+
+@action_app.command("list")
+def action_list(
+    project: uuid.UUID | None = typer.Option(None, "--project"),
+    project_key: str | None = typer.Option(None, "--project-key"),
+    owner_agent_id: uuid.UUID | None = typer.Option(None, "--owner-agent-id"),
+    mine: bool = typer.Option(False, "--mine", help="Only action items assigned to the current agent."),
+    status: str | None = typer.Option("open", "--status"),
+    limit: int = typer.Option(100, "--limit", min=1, max=200),
+) -> None:
+    from map_types.enums import TopicActionItemStatus
+
+    from cli.main import _resolve_project, _run  # lazy: avoid cli.main ↔ cli.commands.* cycle
+
+    def action(c: MAPClient):
+        pid = _resolve_project(c, project, project_key)
+        owner = owner_agent_id
+        if mine:
+            owner = c.get_me().id
+        status_filter = TopicActionItemStatus(status) if status else None
+        return c.list_project_action_items(
+            pid,
+            owner_agent_id=owner,
+            status=status_filter,
+            limit=limit,
+        )
+
+    _run(action)
+
+
+@action_app.command("complete")
+def action_complete(
+    action_item_id: uuid.UUID = typer.Option(..., "--id", help="Action item UUID to mark done."),
+) -> None:
+    """Close an action item as done (open -> done)."""
+    from cli.main import _run  # lazy
+
+    def action(c: MAPClient):
+        return c.complete_action_item(action_item_id)
+
+    _run(action)
+
+
+@action_app.command("deliver")
+def action_deliver(
+    action_item_id: uuid.UUID = typer.Option(..., "--id", help="Action item UUID to deliver."),
+) -> None:
+    """Deliver an open action item (source topic may be closed/archived)."""
+    from cli.main import _run  # lazy
+
+    def action(c: MAPClient):
+        return c.deliver_action_item(action_item_id)
+
+    _run(action)
+
+
+@action_app.command("cancel")
+def action_cancel(
+    action_item_id: uuid.UUID = typer.Option(..., "--id", help="Action item UUID to cancel."),
+    reason: str = typer.Option(..., "--reason", help="Cancellation reason (length-validated by category)."),
+    category: str | None = typer.Option(
+        None,
+        "--category",
+        help="implementation | decision | unspecified (default). Affects reason length threshold.",
+    ),
+) -> None:
+    """Close an action item as cancelled (open -> cancelled)."""
+    from map_types.enums import ActionItemCategory
+    from map_types.schemas import ActionItemCancel
+
+    from cli.main import _run  # lazy
+
+    def action(c: MAPClient):
+        cat = ActionItemCategory(category) if category else None
+        payload = ActionItemCancel(reason=reason, category=cat)
+        return c.cancel_action_item(action_item_id, payload)
+
+    _run(action)
+
+
+@action_app.command("link")
+def action_link(
+    action_item_id: uuid.UUID = typer.Option(..., "--id", help="Action item UUID to link."),
+    experiment_id: uuid.UUID = typer.Option(
+        ...,
+        "--experiment-id",
+        help="Experiment UUID to attach to the action item (must share project).",
+    ),
+) -> None:
+    """Attach an experiment to an open action item so future experiment
+    ``done`` cascades the action item automatically."""
+    from cli.main import _run  # lazy
+
+    def action(c: MAPClient):
+        return c.link_action_item(action_item_id, experiment_id)
+
+    _run(action)
+
+
+@action_app.command("mark-wake-sent")
+def action_mark_wake_sent(
+    action_item_id: uuid.UUID = typer.Option(..., "--id", help="Action item UUID to wake."),
+) -> None:
+    """Bump wake_count + stamp last_woken_at + write ``action_item.wake_sent``
+    audit row. Used by the runtime-waker CLI to advance the three-stage
+    escalation timeline (experiment B / I4). Owner or admin only."""
+    from cli.main import _run  # lazy
+
+    def action(c: MAPClient):
+        return c.mark_wake_sent(action_item_id)
+
+    _run(action)
+
+
+@action_app.command("mark-stale")
+def action_mark_stale(
+    action_item_id: uuid.UUID = typer.Option(..., "--id", help="Action item UUID to mark stale."),
+) -> None:
+    """Stamp stale_at + write the ``action_item.stale`` audit row after the
+    4th unanswered wake. Admin only (system escalation, experiment B / I4)."""
+    from cli.main import _run  # lazy
+
+    def action(c: MAPClient):
+        return c.mark_stale(action_item_id)
+
+    _run(action)

cli/commands/agent.py

@@ -0,0 +1,117 @@
+"""``map agent ...`` sub-app — arch experiment 0519e2a3 PR3.
+
+Mirrors ``GET /api/v1/agents`` + ``/api/v1/agents/me`` for the CLI.
+Distinct from ``map persona ...`` which manages the local
+``.map/agents.yaml`` identity config.
+
+Commands:
+* ``map agent show`` — current MAP agent identity (== ``map me``)
+* ``map agent list`` — agents visible to the caller
+* ``map agent escalation-target`` — STATE_MACHINE.* error escalation
+  contact resolver (I1(c))
+
+The user-facing ``map persona list`` / ``map persona whoami`` path is
+unchanged — this sub-app is additive.
+"""
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+import typer
+
+agent_app = typer.Typer(help="Agent commands (server-side identity)")
+
+
+def _parse_uuid(raw: str | None, *, field: str) -> uuid.UUID | None:
+    if raw is None:
+        return None
+    try:
+        return uuid.UUID(raw)
+    except ValueError as exc:
+        raise typer.BadParameter(f"{field} must be a UUID, got {raw!r}") from exc
+
+
+@agent_app.command("show")
+def agent_show() -> None:
+    """Show the current MAP agent identity (== ``map me`` / ``map persona whoami``)."""
+    from cli.main import _run  # lazy: avoid cli.main ↔ cli.commands.agent cycle
+
+    def action(c: Any) -> Any:
+        return c.get_me()
+
+    _run(action)
+
+
+@agent_app.command("list")
+def agent_list(
+    project_id: str | None = typer.Option(None, "--project-id", help="Filter by project UUID."),
+    role: str | None = typer.Option(
+        None, "--role", help="Filter by role (admin | agent)."
+    ),
+) -> None:
+    """List agents visible to the caller.
+
+    Admins see every agent. Project-bound agents see admins and agents
+    in their own project. Use ``--project-id`` / ``--role`` to narrow.
+    """
+    from cli.main import _run  # lazy: see agent_show
+
+    pid = _parse_uuid(project_id, field="project_id")
+
+    def action(c: Any) -> Any:
+        return c.list_agents(project_id=pid, role=role)
+
+    _run(action)
+
+
+@agent_app.command("escalation-target")
+def agent_escalation_target(
+    experiment_id: str | None = typer.Option(
+        None,
+        "--experiment-id",
+        help="Experiment UUID — its escalation_target_agent_id override takes precedence.",
+    ),
+) -> None:
+    """Resolve the escalation contact for a STATE_MACHINE.* error.
+
+    Server runs the 3-tier rule (override → caller → same-role → admin)
+    and returns the chosen agent + the tier that picked it. CLI uses
+    this on ``MAPHTTPError`` to append ``Escalation: @<name>`` to the
+    error output.
+    """
+    from cli.main import _run  # lazy: see agent_show
+
+    eid = _parse_uuid(experiment_id, field="experiment_id")
+
+    def action(c: Any) -> Any:
+        return c.get_escalation_target(experiment_id=eid)
+
+    _run(action)
+
+
+@agent_app.command("register")
+def agent_register(
+    name: str = typer.Option(..., "--name", help="Unique agent name (1..128 chars)."),
+    role: str = typer.Option("agent", "--role", help="admin | agent (default agent)."),
+    project_key: str | None = typer.Option(
+        None, "--project-key", help="Project key for role=agent (mutually exclusive with --project-id)."
+    ),
+    project_id: str | None = typer.Option(
+        None, "--project-id", help="Project UUID for role=agent (mutually exclusive with --project-key)."
+    ),
+) -> None:
+    """Register a new agent (admin-only; role=agent requires a project)."""
+    from cli.main import _run  # lazy: see agent_show
+
+    pid = _parse_uuid(project_id, field="project_id")
+
+    def action(c: Any) -> Any:
+        return c.register_agent(
+            name=name,
+            role=role,
+            project_key=project_key,
+            project_id=pid,
+        )
+
+    _run(action, admin=True)

cli/commands/audit.py

@@ -0,0 +1,68 @@
+"""``map audit ...`` sub-app — arch experiment 0519e2a3 PR5.
+
+Admin-only audit log surface — wraps ``GET /api/v1/audit``.
+
+Bypasses the shared ``_run`` wrapper on purpose: the API returns
+``(rows, total)`` which we render as a header line + YAML rows rather
+than a raw tuple. The shared wrapper would YAML-dump the tuple as
+``[rows, total]`` which is the wrong shape for a greppable timeline.
+"""
+from __future__ import annotations
+
+import uuid
+
+import typer
+from map_client.exceptions import MAPHTTPError
+
+audit_app = typer.Typer(help="Audit log commands (admin)")
+
+
+@audit_app.command("list")
+def audit_list(
+    kind: str | None = typer.Option(
+        None,
+        "--kind",
+        help="Filter by AuditLog.action (e.g. review_item.mutation).",
+    ),
+    experiment_id: uuid.UUID | None = typer.Option(
+        None,
+        "--experiment",
+        help="Filter to a single experiment (matches payload_json.experiment_id).",
+    ),
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(50, "--page-size", min=1, max=200),
+) -> None:
+    """List global audit log entries (admin only).
+
+    Examples::
+
+        map audit list
+        map audit list --kind review_item.mutation
+        map audit list --kind review_item.mutation --experiment <uuid>
+    """
+    from cli.main import _admin_client_ctx, _print_json
+
+    try:
+        with _admin_client_ctx() as client:
+            items, total = client.list_audit_global(
+                page=page,
+                page_size=page_size,
+                kind=kind,
+                experiment_id=experiment_id,
+            )
+    except MAPHTTPError as exc:
+        suffix = ""
+        error_code = getattr(exc, "error_code", None)
+        hint = getattr(exc, "hint", None)
+        if error_code:
+            suffix += f" [error_code={error_code}]"
+        if hint:
+            suffix += f"\nHint: {hint}"
+        typer.echo(f"Error {exc.status_code}: {exc.detail}{suffix}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(
+        f"# audit_log total={total} returned={len(items)} "
+        f"kind={kind or '*'} experiment={experiment_id or '*'}"
+    )
+    _print_json(items)

cli/commands/docs.py

@@ -0,0 +1,179 @@
+"""``map docs ...`` sub-app — arch experiment 0519e2a3 PR7.
+
+Repo-bundled documentation surface — no MAP API required.
+``docs error-codes`` reads ``docs/error-codes/index.json`` from the
+repo root and renders the catalog as a YAML table or filtered JSON.
+
+The repo-root discovery helper (``_resolve_repo_root``) and the index
+loader (``_load_error_codes_index``) are co-located here because they
+are only used by this command. The loader reads ``_cli_options`` from
+``cli.main`` lazily inside the function body to break the
+``cli.main ↔ cli.commands.*`` import cycle.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+
+docs_app = typer.Typer(help="Repo-bundled documentation commands (no API).")
+
+
+_ERROR_CODES_INDEX_RELATIVE = "docs/error-codes/index.json"
+
+_ERROR_CODES_SEARCH_FIELDS: tuple[str, ...] = (
+    "code",
+    "category",
+    "title",
+    "description",
+    "hint",
+    "docs_url",
+    "owner_experiment",
+    "since_version",
+)
+
+
+def _resolve_repo_root(start: Path | None = None) -> Path:
+    """Walk upward from ``start`` (or cwd) until a directory containing
+    ``docs/error-codes/index.json`` is found. Falls back to the start
+    directory if not found, so the loader can produce a clean error.
+    """
+    current = (start or Path.cwd()).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / _ERROR_CODES_INDEX_RELATIVE).is_file():
+            return candidate
+    return current
+
+
+def _load_error_codes_index(
+    project_root: Path | None = None,
+) -> tuple[Path, dict[str, Any]]:
+    from cli.main import _cli_options  # lazy: avoid cli.main ↔ cli.commands.* cycle
+
+    repo_root = _resolve_repo_root(project_root or _cli_options.get("project_root"))
+    index_path = repo_root / _ERROR_CODES_INDEX_RELATIVE
+    if not index_path.is_file():
+        typer.echo(
+            f"Error: error codes index not found at {index_path}. "
+            "Run from the repo root or pass --project-root.",
+            err=True,
+        )
+        raise typer.Exit(2)
+    try:
+        raw = yaml.safe_load(index_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        typer.echo(f"Error: failed to parse {index_path}: {exc}", err=True)
+        raise typer.Exit(2) from None
+    if not isinstance(raw, dict) or not isinstance(raw.get("codes"), list):
+        typer.echo(
+            f"Error: {index_path} must be a JSON object with a 'codes' list.",
+            err=True,
+        )
+        raise typer.Exit(2)
+    return index_path, raw
+
+
+def _match_error_code(code_entry: dict[str, Any], keywords: list[str]) -> bool:
+    if not keywords:
+        return True
+    haystack_parts: list[str] = []
+    for field in _ERROR_CODES_SEARCH_FIELDS:
+        value = code_entry.get(field)
+        if value is None:
+            continue
+        haystack_parts.append(str(value))
+    haystack = "\n".join(haystack_parts).lower()
+    return all(kw.lower() in haystack for kw in keywords)
+
+
+def _search_keywords_to_list(raw: list[str] | None) -> list[str]:
+    """Normalize --search repeats: split comma-separated, strip, drop empties,
+    preserve order, dedupe while preserving order.
+    """
+    if not raw:
+        return []
+    out: list[str] = []
+    seen: set[str] = set()
+    for item in raw:
+        for piece in str(item).split(","):
+            kw = piece.strip()
+            if not kw or kw in seen:
+                continue
+            seen.add(kw)
+            out.append(kw)
+    return out
+
+
+@docs_app.command("error-codes")
+def docs_error_codes(
+    search: list[str] | None = typer.Option(
+        None,
+        "--search",
+        help=(
+            "Keyword filter (case-insensitive substring match against "
+            "code / category / title / description / hint / docs_url / "
+            "owner_experiment / since_version). Repeat for AND of "
+            "multiple keywords, or comma-separate in one value."
+        ),
+    ),
+    project_root: Path | None = typer.Option(
+        None,
+        "--project-root",
+        help="Repo root containing docs/error-codes/index.json (default: walk up from cwd).",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit the raw index.json payload (machine-readable) instead of the default YAML table.",
+    ),
+) -> None:
+    """List MAP error codes from ``docs/error-codes/index.json``."""
+    from cli.main import _print_json  # lazy
+
+    index_path, payload = _load_error_codes_index(project_root)
+    keywords = _search_keywords_to_list(search)
+    codes = payload.get("codes") or []
+    matched = [entry for entry in codes if isinstance(entry, dict) and _match_error_code(entry, keywords)]
+
+    if as_json:
+        if keywords:
+            _print_json({"schema_version": payload.get("schema_version"), "codes": matched})
+        else:
+            _print_json(payload)
+        return
+
+    schema_version = payload.get("schema_version")
+    generated_at = payload.get("generated_at")
+    owner_experiment = payload.get("owner_experiment")
+    header_lines = [
+        f"# error codes index: {index_path}",
+        f"# schema_version: {schema_version}",
+        f"# generated_at: {generated_at}",
+        f"# owner_experiment: {owner_experiment}",
+    ]
+    if keywords:
+        header_lines.append(f"# search: {', '.join(keywords)} (AND)")
+    header_lines.append(f"# matched: {len(matched)}/{len(codes)}")
+    typer.echo("\n".join(header_lines))
+    if not matched:
+        return
+    table_rows: list[list[str]] = []
+    for entry in matched:
+        table_rows.append(
+            [
+                str(entry.get("code", "")),
+                str(entry.get("category", "")),
+                str(entry.get("http_status", "")),
+                str(entry.get("title", "")),
+                str(entry.get("owner_experiment", "")),
+            ]
+        )
+    header = ["code", "category", "http", "title", "owner_experiment"]
+    widths = [max(len(h), *(len(row[i]) for row in table_rows)) for i, h in enumerate(header)]
+    sep = "-+-".join("-" * w for w in widths)
+    typer.echo(" | ".join(h.ljust(widths[i]) for i, h in enumerate(header)))
+    typer.echo(sep)
+    for row in table_rows:
+        typer.echo(" | ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)))