keystone-cli 0.1.0__py3-none-any.whl

keystone_cli/commands/agent.py

@@ -0,0 +1,1017 @@
+"""``keystone agent`` — validate + run (local dev loop, FDP-3120).
+
+Thin layer: ``validate`` wraps ``keystone.agent_sdk.validate``; ``run`` loads the graph via the
+SDK loader and runs it locally (see :mod:`keystone_cli.runner`). No graph/manifest logic here.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from pathlib import Path
+
+import httpx
+import typer
+from keystone.agent_sdk import validate as sdk_validate
+from keystone.agent_sdk.bundle import SecretInBundleError, create_bundle
+from keystone.agent_sdk.provenance import SourceProvenance
+from keystone.agent_sdk.provenance import detect as detect_provenance
+
+from keystone_cli.auth import device_flow as df
+from keystone_cli.auth import token_store as ts
+from keystone_cli.runner import run_agent
+from keystone_cli.scaffold import TEMPLATES, ScaffoldError, scaffold
+
+agent_app = typer.Typer(
+    help="Author, validate, and run pro-code agents locally.",
+    no_args_is_help=True,
+)
+
+
+def _manifest_path(path: str) -> str:
+    """Accept either an agent.yaml file OR an agent project directory (→ its agent.yaml)."""
+    candidate = Path(path)
+    return str(candidate / "agent.yaml") if candidate.is_dir() else path
+
+
+def _upload_fields(manifest_text: str, sha256: str, provenance: SourceProvenance | None) -> dict[str, str]:
+    """Multipart form fields for POST /bundles.
+
+    ``source_provenance`` is OMITTED rather than sent empty when there is no git info: the server
+    treats absent as "unknown", and an empty-string field would have to be special-cased there. It is
+    also why the field is optional server-side — an older CLI must keep deploying.
+    """
+    fields = {"manifest": manifest_text, "sha256": sha256}
+    if provenance is not None:
+        fields["source_provenance"] = json.dumps(provenance.as_payload(), separators=(",", ":"))
+    return fields
+
+
+@agent_app.command()
+def init(
+    name: str = typer.Argument(..., help="Agent name (kebab-case) — also the project directory created."),
+    template: str = typer.Option("blank", "--template", help=f"One of: {', '.join(TEMPLATES)}."),
+) -> None:
+    """Scaffold a new agent project (FDP-3440 / US-3b) — passes validate + run --offline as generated."""
+    # Workspace pre-fill: the session's `keystone workspace use` choice, else a placeholder.
+    workspace = ts.load().workspace_name or "my-team"
+    try:
+        dest = scaffold(name, template, Path.cwd(), workspace)
+    except ScaffoldError as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    typer.secho(f"✓ created {dest} (template: {template})", fg=typer.colors.GREEN)
+    typer.echo("Next steps:")
+    typer.echo(f"  keystone agent validate {name}")
+    typer.echo(f"  keystone agent run {name} --offline --input '<json>'   # see {name}/README.md")
+    typer.echo(f"  keystone agent deploy {name} --publish")
+
+
+@agent_app.command()
+def validate(
+    path: str = typer.Argument("agent.yaml", help="Path to agent.yaml, or the agent project directory."),
+) -> None:
+    """Validate an agent.yaml (manifest schema + entrypoint importable). Exit 1 on errors."""
+    result = sdk_validate(_manifest_path(path))
+    if result.ok:
+        typer.secho(f"✓ {path} is valid", fg=typer.colors.GREEN)
+        return
+    for err in result.errors:
+        typer.secho(f"✗ {err}", fg=typer.colors.RED)
+    raise typer.Exit(1)
+
+
+@agent_app.command()
+def run(
+    path: str = typer.Argument("agent.yaml", help="Path to agent.yaml, or the agent project directory."),
+    input_: str = typer.Option("{}", "--input", help="JSON input for the agent graph."),
+    offline: bool = typer.Option(
+        False, "--offline", help="Mock rag/gateway calls — run with no live services or quota."
+    ),
+) -> None:
+    """Load the agent's graph via the SDK and run it locally with a per-node trace."""
+    manifest_path = _manifest_path(path)
+    result = sdk_validate(manifest_path)
+    if not result.ok or result.manifest is None:
+        for err in result.errors:
+            typer.secho(f"✗ {err}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    try:
+        inputs = json.loads(input_)
+    except json.JSONDecodeError as exc:
+        typer.secho(f"✗ --input is not valid JSON: {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    final = run_agent(
+        entrypoint=result.manifest.entrypoint,
+        project_dir=Path(manifest_path).resolve().parent,
+        inputs=inputs,
+        offline=offline,
+    )
+    typer.secho(f"\n✓ result: {json.dumps(final, default=str)}", fg=typer.colors.GREEN)
+
+
+@agent_app.command()
+def deploy(
+    path: str = typer.Argument(".", help="Agent project directory (or its agent.yaml)."),
+    api_base: str | None = typer.Option(
+        None, "--api-base", envvar="KEYSTONE_API_BASE", help="Platform API base (through Kong)."
+    ),
+    workspace_id: str | None = typer.Option(
+        None,
+        "--workspace-id",
+        help="Target workspace UUID. Defaults to the one set via `keystone workspace use`.",
+    ),
+    no_create: bool = typer.Option(
+        False,
+        "--no-create",
+        help="Don't auto-register the agent on first deploy — fail if it doesn't exist yet.",
+    ),
+    publish: bool = typer.Option(
+        False,
+        "--publish",
+        help="Once the build reaches staged, publish it to Live (deploy → build → publish in one command).",
+    ),
+    require_clean: bool = typer.Option(
+        False,
+        "--require-clean",
+        help="Refuse to deploy uncommitted changes. For CI, where an unreproducible build is a defect.",
+    ),
+) -> None:
+    """Package the project + upload to agent-hub for a server-side build. Requires `keystone login`.
+
+    validate → bundle (tar honouring .gitignore + SHA-256) → auth (cached/refreshed token) →
+    ``POST /api/agent-hub/v1/bundles`` through Kong. Idempotent by SHA-256 (re-deploy = same version).
+    On the FIRST deploy the agent header doesn't exist yet, so ``deploy`` auto-registers it
+    (``internal_pro_code``) and retries — one command for dev self-serve; opt out with ``--no-create``.
+    """
+    manifest_path = _manifest_path(path)
+    result = sdk_validate(manifest_path)  # preflight: fail fast before packaging/upload
+    if not result.ok or result.manifest is None:
+        for err in result.errors:
+            typer.secho(f"✗ {err}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    project_dir = Path(manifest_path).resolve().parent
+    try:
+        bundle = create_bundle(project_dir)
+    except SecretInBundleError as exc:
+        # Fail the deploy, don't warn-and-continue: once the bundle is uploaded the key is in S3 and
+        # in the image, and "we'll rotate it later" is not something a build step gets to decide.
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    except (NotADirectoryError, FileNotFoundError) as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    # Where this bundle came from. Recorded because the bundle is the WORKING DIRECTORY, not a git
+    # ref: without it, `bundle_sha256` proves two uploads were identical but never says which commit
+    # produced them — and says nothing at all if the tree had uncommitted edits.
+    provenance = detect_provenance(project_dir)
+    if provenance is None:
+        typer.secho(
+            "• no git provenance (not a repo, or no commits yet) — this version will not record a source commit.",
+            fg=typer.colors.YELLOW,
+        )
+    elif provenance.dirty:
+        # The one case that is genuinely unrecoverable: pinning the commit does not reproduce a tree
+        # that did not match it. Loud in dev, fatal under --require-clean.
+        message = (
+            f"uncommitted changes — the bundle is NOT reproducible from {provenance.summary()}. "
+            "Whatever ships is only in your working directory."
+        )
+        if require_clean:
+            typer.secho(f"✗ {message} (--require-clean)", fg=typer.colors.RED)
+            raise typer.Exit(1)
+        typer.secho(f"⚠ {message}", fg=typer.colors.YELLOW)
+    else:
+        typer.secho(f"• source {provenance.summary()}", fg=typer.colors.BLUE)
+
+    for env_file in bundle.skipped_env:
+        # Say it out loud. Silently dropping a file the dev put config in is how "it worked locally"
+        # turns into an hour of debugging a missing variable in the pod.
+        typer.secho(
+            f"• {env_file} not packaged (never is — secrets stay out of S3/ECR). Non-secret per-agent "
+            "config goes in agent.yaml `config:`; the API key is injected into the pod, not bundled.",
+            fg=typer.colors.YELLOW,
+        )
+
+    cfg = ts.load()
+    base = (api_base or cfg.api_base or ts.DEFAULT_API_BASE).rstrip("/")
+    if not base:
+        typer.secho("✗ no --api-base (or KEYSTONE_API_BASE) configured", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    # Workspace is caller-supplied (not in the JWT — the user picks it): --workspace-id wins, else the
+    # one saved by `keystone workspace use`. entity/user are edge-injected from the token, so they are
+    # NOT sent here (a client-set X-Entity-ID would be spoofable; the edge overrides it anyway).
+    workspace = workspace_id or cfg.workspace_id
+    if not workspace:
+        typer.secho(
+            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+    try:
+        token = df.get_access_token(cfg, save=ts.save)  # cached, or refreshed via the stored refresh token
+    except df.DeviceFlowError as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    name = result.manifest.name
+    manifest_text = Path(manifest_path).read_text(encoding="utf-8")
+    typer.echo(f"Uploading {name} — {bundle.file_count} files, sha256 {bundle.sha256[:12]}…")
+
+    def _upload(client: httpx.Client) -> httpx.Response:
+        return client.post(
+            f"{base}/api/agent-hub/v1/bundles",
+            headers={"Authorization": f"Bearer {token}", "X-Workspace-ID": workspace},
+            data=_upload_fields(manifest_text, bundle.sha256, provenance),
+            files={"bundle": ("bundle.tar.gz", bundle.data, "application/gzip")},
+        )
+
+    try:
+        with httpx.Client(timeout=120) as client:
+            resp = _upload(client)
+            # First deploy: the agent header doesn't exist yet (404 AGENT_NOT_FOUND). Auto-register it
+            # as a pro-code agent and retry, so `deploy` is one command for dev self-serve — the server
+            # still scopes it to the caller's workspace. Opt out with --no-create.
+            if resp.status_code == 404 and "AGENT_NOT_FOUND" in resp.text and not no_create:
+                typer.echo(f"  agent '{name}' not found — registering (internal_pro_code)…")
+                reg = client.post(
+                    f"{base}/api/agent-hub/v1/agents",
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "X-Workspace-ID": workspace,
+                        "Content-Type": "application/json",
+                    },
+                    json={
+                        "name": name,
+                        "display_name": name.replace("-", " ").title(),
+                        "agent_type": "internal_pro_code",
+                    },
+                )
+                # 409 = a concurrent deploy already registered it → proceed to re-upload regardless.
+                if reg.status_code not in (200, 201, 409):
+                    typer.secho(f"✗ auto-register failed ({reg.status_code}): {reg.text}", fg=typer.colors.RED)
+                    raise typer.Exit(1)
+                resp = _upload(client)
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ upload failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    if resp.status_code not in (200, 201, 202):
+        typer.secho(f"✗ deploy rejected ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    body = resp.json() if resp.content else {}
+    version = body.get("version") or body.get("version_id") or "?"
+    typer.secho(
+        f"✓ deployed {name} — version {version} (status {body.get('status', 'accepted')})",
+        fg=typer.colors.GREEN,
+    )
+
+    if publish:
+        version_id = body.get("version_id")
+        if not version_id:
+            typer.secho("✗ deploy did not return a version_id — cannot --publish.", fg=typer.colors.RED)
+            raise typer.Exit(1)
+        pub_headers = {"Authorization": f"Bearer {token}", "X-Workspace-ID": workspace}
+        try:
+            with httpx.Client(timeout=60) as client:
+                agent_id = _resolve_agent_id(client, base, pub_headers, name)
+                status = _wait_for_staged(client, base, pub_headers, agent_id, str(version_id))
+                if status == "live":
+                    typer.echo(f"  {version} is already live — nothing to publish.")
+                else:
+                    _do_publish(client, base, pub_headers, agent_id, str(version_id), name)
+        except httpx.RequestError as exc:
+            typer.secho(f"✗ publish failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+            raise typer.Exit(1) from exc
+
+
+@agent_app.command()
+def invoke(
+    agent: str = typer.Argument(..., help="Deployed agent name (as routed by the gateway), e.g. rag-qa."),
+    input_: str = typer.Option("{}", "--input", help="JSON input for the agent (matches its io_schema)."),
+    api_base: str | None = typer.Option(
+        None, "--api-base", envvar="KEYSTONE_API_BASE", help="Platform API base (through Kong)."
+    ),
+    workspace_id: str | None = typer.Option(
+        None, "--workspace-id", help="Target workspace UUID. Defaults to the one set via `keystone workspace use`."
+    ),
+    async_: bool = typer.Option(
+        False, "--async", help="Queue a background run (FDP-3332) and return the run_id immediately."
+    ),
+) -> None:
+    """Invoke a deployed agent through the gateway (Kong/JWT). Requires `keystone login`.
+
+    Sends the caller-supplied tenant scope the runtime needs downstream: ``X-Workspace-ID`` and a
+    fresh ``X-Correlation-ID``. The Stage tier is fully retired (FDP-2071) — no ``X-Stage-ID`` is
+    resolved or sent anywhere any more. entity/user are edge-injected
+    from the token (not sent here — a client-set value is spoofable and the edge overrides it
+    anyway). With ``--async`` the run is queued (202) — poll it with ``keystone agent runs get``.
+    """
+    try:
+        inputs = json.loads(input_)
+    except json.JSONDecodeError as exc:
+        typer.secho(f"✗ --input is not valid JSON: {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    cfg = ts.load()
+    base = (api_base or cfg.api_base or ts.DEFAULT_API_BASE).rstrip("/")
+    if not base:
+        typer.secho("✗ no --api-base (or KEYSTONE_API_BASE) configured", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    workspace = workspace_id or cfg.workspace_id
+    if not workspace:
+        typer.secho(
+            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+    try:
+        token = df.get_access_token(cfg, save=ts.save)  # cached, or refreshed via the stored refresh token
+    except df.DeviceFlowError as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    endpoint = "invoke-async" if async_ else "invoke"
+    gw_base = _agent_api_base(cfg, base)
+    url = f"{gw_base}/api/agent-service/v1/agents/{agent}/{endpoint}"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "X-Workspace-ID": workspace,
+        "X-Correlation-ID": str(uuid.uuid4()),
+    }
+    body: dict = {}
+    try:
+        with httpx.Client(timeout=120) as client:
+            for _attempt in range(_WARMING_MAX_ATTEMPTS):
+                resp = client.post(url, headers=headers, json={"inputs": inputs})
+                if resp.status_code not in (200, 202):
+                    typer.secho(f"✗ invoke rejected ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+                    raise typer.Exit(1)
+                body = resp.json() if resp.content else {}
+                if body.get("status") != "warming":
+                    break
+                # 202 warming = the gateway woke a scaled-to-zero/not-ready version and did
+                # NOT forward the request — no run exists, so re-POSTing is safe. Honour
+                # Retry-After (the gateway sets it) before trying again.
+                wait_s = float(resp.headers.get("retry-after", 5))
+                typer.secho(f"… {agent} — warming (cold start), retrying in {wait_s:.0f}s", fg=typer.colors.YELLOW)
+                time.sleep(wait_s)
+            else:
+                typer.secho(
+                    f"✗ {agent} — still warming after {_WARMING_MAX_ATTEMPTS} tries; retry shortly", fg=typer.colors.RED
+                )
+                raise typer.Exit(1)
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ invoke failed (is {gw_base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    _print_run_outcome(agent, body)
+
+
+# How many 5s polls to ride out the post-create authz propagation window (FDP-3443).
+# Observed on dev: the row lands in ~30s; 12 polls = 60s of headroom before giving up.
+_REGISTRY_PROPAGATION_POLLS = 12
+_FAILURE_STATUSES = ("failed", "cancelled", "expired")
+_PENDING_STATUSES = ("queued", "running", "cancelling", "awaiting_human", "warming")
+_WARMING_MAX_ATTEMPTS = 6
+# Transient run states the --wait poll keeps polling through ("warming" = the gateway is
+# still cold-starting the version pod; the GET itself was not served by the runtime).
+_WAIT_TRANSIENT_STATUSES = ("queued", "running", "cancelling", "warming")
+
+
+def _print_run_outcome(agent: str, body: dict) -> None:
+    """Shared outcome printer (FDP-3332): pending statuses are NOT failures — a queued or
+    HITL-paused run exits 0 with the handle to poll/respond with."""
+    status = body.get("status", "?")
+    run_id = body.get("run_id") or body.get("session_id", "?")
+    if status in _FAILURE_STATUSES:
+        typer.secho(f"✗ {agent} — {status}: {body.get('error') or 'no result'}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    if status in _PENDING_STATUSES:
+        typer.secho(f"… {agent} — {status} (run {run_id})", fg=typer.colors.YELLOW)
+        typer.echo(f"  poll with: keystone agent runs get {agent} {run_id} --wait")
+        return
+    typer.secho(f"✓ {agent} — {status} (session {body.get('session_id', run_id)})", fg=typer.colors.GREEN)
+    typer.echo(json.dumps(body.get("result"), indent=2, default=str, ensure_ascii=False))
+
+
+def _agent_api_base(cfg: ts.AuthConfig, control_base: str) -> str:
+    """Data-plane base for gateway calls — invoke/hitl/runs (FDP-3072 §11.4b).
+
+    The pro-code cluster gets its own edge hostname (``keystone-agent-api-<env>.aws.int…``);
+    control-plane calls (login/deploy/status, /users/me) always stay on ``api_base``. Until Ops
+    lands the new domain this falls back to the control-plane base, so behavior is unchanged.
+    Resolution: ``KEYSTONE_AGENT_API_BASE`` env → ``agent_api_base`` in the config file → fallback.
+    """
+    return (os.environ.get("KEYSTONE_AGENT_API_BASE") or cfg.agent_api_base or control_base).rstrip("/")
+
+
+def _gateway_ctx(api_base: str | None, workspace_id: str | None) -> tuple[str, dict[str, str]]:
+    """(base, headers) for gateway calls — same auth/tenant plumbing as `invoke` (FDP-3332).
+
+    The returned base is the DATA-PLANE one (`_agent_api_base`). The Stage tier is fully retired
+    (FDP-2071) — nothing is resolved or sent."""
+    cfg = ts.load()
+    base = (api_base or cfg.api_base or ts.DEFAULT_API_BASE).rstrip("/")
+    workspace = workspace_id or cfg.workspace_id
+    if not base or not workspace:
+        typer.secho("✗ need an api base + workspace — run `keystone workspace use` first.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    try:
+        token = df.get_access_token(cfg, save=ts.save)
+    except df.DeviceFlowError as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "X-Workspace-ID": workspace,
+        "X-Correlation-ID": str(uuid.uuid4()),
+    }
+    return _agent_api_base(cfg, base), headers
+
+
+runs_app = typer.Typer(help="Background runs (FDP-3332): poll or cancel an async invoke.")
+agent_app.add_typer(runs_app, name="runs")
+
+hitl_app = typer.Typer(help="Human-in-the-loop approvals (FDP-3336): list paused runs, respond.")
+agent_app.add_typer(hitl_app, name="hitl")
+
+
+@hitl_app.command("list")
+def hitl_list(
+    agent: str = typer.Argument(..., help="Deployed agent name."),
+    api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+) -> None:
+    """Approver inbox: this agent's runs paused ``awaiting_human`` (newest first)."""
+    base, headers = _gateway_ctx(api_base, workspace_id)
+    try:
+        with httpx.Client(timeout=30) as client:
+            resp = client.get(f"{base}/api/agent-service/v1/agents/{agent}/hitl/pending", headers=headers)
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ hitl list failed (is {base} reachable?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    if resp.status_code != 200:
+        typer.secho(f"✗ hitl list rejected ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    items = (resp.json() or {}).get("items", [])
+    if not items:
+        typer.echo(f"{agent}: no runs awaiting approval.")
+        return
+    for it in items:
+        # agent_version already carries its "v" prefix (platform convention) — print raw.
+        expiry = f"  expires {it['expires_at']} ({it.get('on_timeout') or 'expire'})" if it.get("expires_at") else ""
+        typer.echo(f"{it['run_id']}  {it.get('agent_version') or '?'}  {it.get('created_at') or ''}{expiry}")
+        typer.echo(f"  {json.dumps(it.get('payload', {}), ensure_ascii=False)}")
+
+
+@hitl_app.command("respond")
+def hitl_respond(
+    agent: str = typer.Argument(..., help="Deployed agent name."),
+    run_id: str = typer.Argument(..., help="Paused run to answer."),
+    approve: bool = typer.Option(..., "--approve/--reject", help="The verdict."),
+    note: str = typer.Option("", "--note", help="Optional note passed to the agent."),
+    input_json: str | None = typer.Option(None, "--input", help="Optional extra JSON handed to the agent."),
+    api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+) -> None:
+    """Answer a paused run — the decision becomes ``request_approval``'s return value.
+
+    202 = re-queued (poll ``runs get``); 409 = already answered (double-submit guard)."""
+    body: dict = {"approved": approve, "note": note}
+    if input_json:
+        try:
+            body["input"] = json.loads(input_json)
+        except json.JSONDecodeError as exc:
+            typer.secho(f"✗ --input is not valid JSON: {exc}", fg=typer.colors.RED)
+            raise typer.Exit(2) from exc
+    base, headers = _gateway_ctx(api_base, workspace_id)
+    # Pin the gateway to the version that owns this run's thread (D-M3-A session pin).
+    headers = {**headers, "X-Session-ID": run_id}
+    try:
+        with httpx.Client(timeout=30) as client:
+            resp = client.post(
+                f"{base}/api/agent-service/v1/agents/{agent}/hitl/{run_id}/respond", headers=headers, json=body
+            )
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ respond failed (is {base} reachable?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    if resp.status_code == 403:
+        typer.secho(f"✗ you are not in this run's approver list (run {run_id})", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    if resp.status_code == 409:
+        typer.secho(f"✗ run {run_id} has no open approval (already answered?)", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    if resp.status_code != 202:
+        typer.secho(f"✗ respond rejected ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    verdict = "approved" if approve else "rejected"
+    typer.secho(f"✓ {agent} — run {run_id} {verdict}; resuming (poll: keystone agent runs get)", fg=typer.colors.GREEN)
+
+
+@runs_app.command("get")
+def runs_get(
+    agent: str = typer.Argument(..., help="Deployed agent name."),
+    run_id: str = typer.Argument(..., help="run_id returned by `invoke --async`."),
+    wait: bool = typer.Option(False, "--wait", help="Poll until the run leaves queued/running."),
+    poll_seconds: float = typer.Option(3.0, "--poll-seconds", help="Poll interval with --wait."),
+    api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+) -> None:
+    """Fetch a background run's state (`--wait` polls to a settled state)."""
+    base, headers = _gateway_ctx(api_base, workspace_id)
+    url = f"{base}/api/agent-service/v1/agents/{agent}/runs/{run_id}"
+    try:
+        with httpx.Client(timeout=30) as client:
+            while True:
+                resp = client.get(url, headers=headers)
+                # 202 = gateway `warming` (cold-starting the version pod) — transient.
+                if resp.status_code not in (200, 202):
+                    typer.secho(f"✗ runs get failed ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+                    raise typer.Exit(1)
+                body = resp.json() if resp.content else {}
+                if not wait or body.get("status") not in _WAIT_TRANSIENT_STATUSES:
+                    break
+                time.sleep(poll_seconds)
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ runs get failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    _print_run_outcome(agent, body)
+
+
+@runs_app.command("cancel")
+def runs_cancel(
+    agent: str = typer.Argument(..., help="Deployed agent name."),
+    run_id: str = typer.Argument(..., help="run_id to cancel."),
+    api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+) -> None:
+    """Cancel a queued/running background run (terminal runs → 409)."""
+    base, headers = _gateway_ctx(api_base, workspace_id)
+    try:
+        with httpx.Client(timeout=30) as client:
+            resp = client.post(f"{base}/api/agent-service/v1/agents/{agent}/runs/{run_id}/cancel", headers=headers)
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ cancel failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    if resp.status_code not in (200, 202):
+        typer.secho(f"✗ cancel rejected ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    body = resp.json() if resp.content else {}
+    typer.secho(f"✓ {agent} — run {run_id}: {body.get('status', '?')}", fg=typer.colors.GREEN)
+
+
+@runs_app.command("list")
+def runs_list(
+    agent: str = typer.Argument(..., help="Deployed agent name."),
+    status: str | None = typer.Option(None, "--status", help="Filter by run status."),
+    limit: int = typer.Option(20, "--limit", help="Page size."),
+    offset: int = typer.Option(0, "--offset", help="Page offset (newest first)."),
+    api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+) -> None:
+    """List an agent's runs, newest first (FDP-3099 / FDP-4318 P1). Tenant+agent+user scoped server-side."""
+    base, headers = _gateway_ctx(api_base, workspace_id)
+    params: list[tuple[str, str]] = [("limit", str(limit)), ("offset", str(offset))]
+    if status:
+        params.append(("status", status))
+    url = f"{base}/api/agent-service/v1/agents/{agent}/runs"
+    try:
+        with httpx.Client(timeout=30) as client:
+            resp = client.get(url, headers=headers, params=params)
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ runs list failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    if resp.status_code == 202:  # gateway `warming` (cold-starting the version pod)
+        typer.secho(f"… {agent} is warming — retry in a moment.", fg=typer.colors.YELLOW)
+        raise typer.Exit(0)
+    if resp.status_code != 200:
+        typer.secho(f"✗ runs list failed ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    body = resp.json() if resp.content else {}
+    items = body.get("items", [])
+    total = body.get("total", len(items))
+    if not items:
+        typer.echo(f"no runs for {agent}.")
+        return
+    typer.echo(f"  {'RUN_ID':<36}  {'STATUS':<14}  {'VER':<5}  CREATED")
+    for it in items:
+        typer.echo(
+            f"  {it.get('run_id', ''):<36}  {it.get('status', ''):<14}  "
+            f"{(it.get('agent_version') or '-'):<5}  {it.get('created_at') or ''}"
+        )
+    typer.echo(f"\n  showing {len(items)} of {total} (offset {offset})")
+
+
+def _resolve_agent_id(client: httpx.Client, base: str, headers: dict[str, str], name: str) -> str:
+    """Look up an agent's UUID by its (workspace-unique) name."""
+    # `limit` is capped at 100 server-side; `q` narrows by name/display_name (substring) so the exact
+    # match is on the first page even in a busy workspace. Still exact-match client-side (q is fuzzy).
+    resp = client.get(f"{base}/api/agent-hub/v1/agents", headers=headers, params={"limit": 100, "q": name})
+    if resp.status_code != 200:
+        typer.secho(f"✗ could not list agents ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    for a in resp.json().get("data", []):
+        if a.get("name") == name:
+            return str(a["id"])
+    typer.secho(
+        f"✗ no agent '{name}' in this workspace — deploy it first (`keystone agent deploy`).",
+        fg=typer.colors.RED,
+    )
+    raise typer.Exit(1)
+
+
+def _pick_version(
+    client: httpx.Client, base: str, headers: dict[str, str], agent_id: str, version_tag: str | None
+) -> tuple[str, str]:
+    """Return (version_id, version_tag) to publish — a specific `--version`, else the latest staged."""
+    params: dict[str, object] = {"limit": 100, "sort_by": "created_at", "sort_order": "desc"}
+    if not version_tag:
+        params["status"] = "staged"
+    resp = client.get(f"{base}/api/agent-hub/v1/agents/{agent_id}/versions", headers=headers, params=params)
+    if resp.status_code != 200:
+        typer.secho(f"✗ could not list versions ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    versions = resp.json().get("data", [])
+    if version_tag:
+        for v in versions:
+            if v.get("version") == version_tag:
+                return str(v["id"]), version_tag
+        typer.secho(f"✗ version '{version_tag}' not found for '{agent_id}'.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    if not versions:
+        typer.secho(
+            "✗ no staged version to publish — run `keystone agent deploy` (or wait for the build to finish).",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+    top = versions[0]
+    return str(top["id"]), str(top.get("version", "?"))
+
+
+def _registry_still_propagating(resp: httpx.Response) -> bool:
+    """True for the 403 a JUST-created agent answers with (FDP-3443, dev-observed 2026-07-31).
+
+    Authz resolves the agent's owner from the **platform resource registry**, whose row is
+    published asynchronously on create. Between "agent registered" and "row visible" every read
+    fail-closes with ``AGENT_FORBIDDEN`` / ``reason: resource_registry_miss`` — so a first deploy
+    would abort right after uploading, `--publish` would never run, and the version silently sat
+    in `staged` while the operator thought it had gone Live. Retrying THIS reason (and only this
+    one — a real permission denial must still fail fast) rides out the propagation window.
+    """
+    if resp.status_code != 403:
+        return False
+    try:
+        details = resp.json().get("error", {}).get("details", {})
+    except ValueError:
+        return False
+    return details.get("reason") == "resource_registry_miss"
+
+
+def _wait_for_staged(client: httpx.Client, base: str, headers: dict[str, str], agent_id: str, version_id: str) -> str:
+    """Poll a version until it leaves `building`. Returns the terminal status (`staged`/`live`);
+    exits on `build_failed` or after ~4 min."""
+    propagation_retries = 0
+    for _ in range(48):
+        r = client.get(f"{base}/api/agent-hub/v1/agents/{agent_id}/versions/{version_id}", headers=headers)
+        if _registry_still_propagating(r):
+            propagation_retries += 1
+            if propagation_retries > _REGISTRY_PROPAGATION_POLLS:
+                typer.secho(
+                    "✗ the agent is registered but still not visible to authz "
+                    f"(resource_registry_miss for >{_REGISTRY_PROPAGATION_POLLS * 5}s). "
+                    "The build continues server-side — retry with `keystone agent status` / "
+                    "`keystone agent publish` in a moment.",
+                    fg=typer.colors.RED,
+                )
+                raise typer.Exit(1)
+            if propagation_retries == 1:
+                typer.echo("  waiting for the new agent to become visible to authz…")
+            time.sleep(5)
+            continue
+        if r.status_code != 200:
+            typer.secho(f"✗ could not read version status ({r.status_code}): {r.text}", fg=typer.colors.RED)
+            raise typer.Exit(1)
+        status = str(r.json().get("data", {}).get("status", ""))
+        if status in ("staged", "live"):
+            return status
+        if status == "build_failed":
+            typer.secho("✗ build failed — check the build logs (agent-hub / Kaniko Job).", fg=typer.colors.RED)
+            raise typer.Exit(1)
+        typer.echo(f"  build: {status}…")
+        time.sleep(5)
+    typer.secho(
+        "✗ timed out waiting for the build — check status, then run `keystone agent publish`.",
+        fg=typer.colors.RED,
+    )
+    raise typer.Exit(1)
+
+
+def _do_publish(
+    client: httpx.Client, base: str, headers: dict[str, str], agent_id: str, version_id: str, label: str
+) -> None:
+    """POST .../publish and report the result (shared by `publish` and `deploy --publish`)."""
+    resp = client.post(f"{base}/api/agent-hub/v1/agents/{agent_id}/versions/{version_id}/publish", headers=headers)
+    if resp.status_code not in (200, 201):
+        typer.secho(f"✗ publish rejected ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    body = resp.json().get("data", {}) if resp.content else {}
+    prev = body.get("previous_live_version")
+    demoted = f" (demoted {prev} → staged)" if prev else ""
+    typer.secho(f"✓ published {label} {body.get('version', '?')} → live{demoted}", fg=typer.colors.GREEN)
+    typer.echo("  the operator is deploying it now — `keystone agent invoke` works once the pod is Running.")
+
+
+@agent_app.command()
+def publish(
+    agent: str = typer.Argument(..., help="Agent name to publish, e.g. rag-qa."),
+    version: str | None = typer.Option(
+        None, "--version", help="Version tag to publish. Defaults to the latest staged version."
+    ),
+    api_base: str | None = typer.Option(
+        None, "--api-base", envvar="KEYSTONE_API_BASE", help="Platform API base (through Kong)."
+    ),
+    workspace_id: str | None = typer.Option(
+        None, "--workspace-id", help="Target workspace UUID. Defaults to the one set via `keystone workspace use`."
+    ),
+) -> None:
+    """Promote a staged version to Live (staged → live). Requires `keystone login`.
+
+    Resolves the agent by name, picks the version (``--version`` tag, else the latest staged), and
+    publishes it. The operator then deploys the per-agent pod and the gateway routes to it —
+    ``keystone agent invoke`` works once the pod is Running (a few seconds).
+    """
+    cfg = ts.load()
+    base = (api_base or cfg.api_base or ts.DEFAULT_API_BASE).rstrip("/")
+    workspace = workspace_id or cfg.workspace_id
+    if not workspace:
+        typer.secho(
+            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+    try:
+        token = df.get_access_token(cfg, save=ts.save)
+    except df.DeviceFlowError as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    headers = {"Authorization": f"Bearer {token}", "X-Workspace-ID": workspace}
+    try:
+        with httpx.Client(timeout=60) as client:
+            agent_id = _resolve_agent_id(client, base, headers, agent)
+            version_id, _ = _pick_version(client, base, headers, agent_id, version)
+            _do_publish(client, base, headers, agent_id, version_id, agent)
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ publish failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+
+@agent_app.command()
+def status(
+    agent: str = typer.Argument(..., help="Agent name, e.g. docs-qa."),
+    api_base: str | None = typer.Option(
+        None, "--api-base", envvar="KEYSTONE_API_BASE", help="Platform API base (through Kong)."
+    ),
+    workspace_id: str | None = typer.Option(
+        None, "--workspace-id", help="Target workspace UUID. Defaults to the one set via `keystone workspace use`."
+    ),
+) -> None:
+    """List an agent's versions + their status — the `live` (currently published) one is marked ``*``."""
+    cfg = ts.load()
+    base = (api_base or cfg.api_base or ts.DEFAULT_API_BASE).rstrip("/")
+    workspace = workspace_id or cfg.workspace_id
+    if not workspace:
+        typer.secho(
+            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+    try:
+        token = df.get_access_token(cfg, save=ts.save)
+    except df.DeviceFlowError as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    headers = {"Authorization": f"Bearer {token}", "X-Workspace-ID": workspace}
+    try:
+        with httpx.Client(timeout=60) as client:
+            agent_id = _resolve_agent_id(client, base, headers, agent)
+            resp = client.get(
+                f"{base}/api/agent-hub/v1/agents/{agent_id}/versions",
+                headers=headers,
+                params={"limit": 100, "sort_by": "created_at", "sort_order": "desc"},
+            )
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ status failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    if resp.status_code != 200:
+        typer.secho(f"✗ could not list versions ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    versions = resp.json().get("data", [])
+    if not versions:
+        typer.echo(f"{agent}: no versions yet — run `keystone agent deploy`.")
+        return
+    width = max(len("VERSION"), *(len(str(v.get("version", "?"))) for v in versions))
+    typer.echo(f"  {'VERSION':<{width}}  STATUS")
+    for v in versions:
+        ver = str(v.get("version", "?"))
+        st = str(v.get("status", "?"))
+        line = f"{'*' if st == 'live' else ' '} {ver:<{width}}  {st}"
+        typer.secho(line, fg=typer.colors.GREEN) if st == "live" else typer.echo(line)
+
+
+# ── retire / delete (FDP-3439 / US-24 — M4.4a) ──────────────────────────────
+
+
+def _hub_auth(api_base: str | None, workspace_id: str | None) -> tuple[str, dict[str, str]]:
+    """(base, headers) for agent-hub lifecycle calls — the login/workspace dance."""
+    cfg = ts.load()
+    base = (api_base or cfg.api_base or ts.DEFAULT_API_BASE).rstrip("/")
+    workspace = workspace_id or cfg.workspace_id
+    if not workspace:
+        typer.secho(
+            "✗ no workspace selected — run `keystone workspace use <name|id>` (or pass --workspace-id).",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+    try:
+        token = df.get_access_token(cfg, save=ts.save)
+    except df.DeviceFlowError as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    return base, {"Authorization": f"Bearer {token}", "X-Workspace-ID": workspace}
+
+
+def _list_versions(client: httpx.Client, base: str, headers: dict[str, str], agent_id: str) -> list[dict]:
+    resp = client.get(
+        f"{base}/api/agent-hub/v1/agents/{agent_id}/versions",
+        headers=headers,
+        params={"limit": 100, "sort_by": "created_at", "sort_order": "desc"},
+    )
+    if resp.status_code != 200:
+        typer.secho(f"✗ could not list versions ({resp.status_code}): {resp.text}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    return list(resp.json().get("data", []))
+
+
+def _open_approvals(client: httpx.Client, base: str, agent: str, hub_headers: dict[str, str]) -> list[dict] | None:
+    """Best-effort HITL guard (OQ-M4-6): open approvals via the gateway inbox. ``None`` =
+    could not check (cold pod / network) — callers WARN, they don't block.
+
+    FDP-2071: the retired stage lookup is gone — it used to make this guard silently SKIP
+    (return ``None``) on every post-stage workspace tree, i.e. the guard never actually ran."""
+    try:
+        resp = client.get(
+            f"{base}/api/agent-service/v1/agents/{agent}/hitl/pending",
+            headers={**hub_headers, "X-Correlation-ID": str(uuid.uuid4())},
+        )
+    except httpx.RequestError:
+        return None
+    if resp.status_code != 200:
+        return None
+    return list(resp.json().get("items", []))
+
+
+def _guard_open_approvals(
+    client: httpx.Client, base: str, agent: str, headers: dict[str, str], version: str | None
+) -> None:
+    """Block on open approvals for the target (all versions when ``version`` is None)."""
+    pending = _open_approvals(client, base, agent, headers)
+    if pending is None:
+        typer.secho("… could not check open approvals (inbox unreachable) — continuing", fg=typer.colors.YELLOW)
+        return
+    hits = [p for p in pending if version is None or p.get("agent_version") in (None, version)]
+    if hits:
+        typer.secho(
+            f"✗ {agent} has {len(hits)} open approval(s) awaiting a human — respond to them "
+            "(`keystone agent hitl list/respond`) or re-run with --force.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+
+
+@agent_app.command()
+def retire(
+    agent: str = typer.Argument(..., help="Agent name, e.g. rag-qa."),
+    version: str = typer.Option(..., "--version", help="Version tag to retire, e.g. v3."),
+    api_base: str | None = typer.Option(
+        None, "--api-base", envvar="KEYSTONE_API_BASE", help="Platform API base (through Kong)."
+    ),
+    workspace_id: str | None = typer.Option(
+        None, "--workspace-id", help="Target workspace UUID. Defaults to the one set via `keystone workspace use`."
+    ),
+    force: bool = typer.Option(False, "--force", help="Skip the open-approvals guard and the confirmation prompt."),
+) -> None:
+    """Retire ONE version — terminal (FDP-3439 / US-24). A Live version is unpublished first
+    (that traffic stops). The operator tears the version's pods/routes down on the retire
+    event. Idempotent: an already-retired version no-ops."""
+    base, headers = _hub_auth(api_base, workspace_id)
+    try:
+        with httpx.Client(timeout=60) as client:
+            agent_id = _resolve_agent_id(client, base, headers, agent)
+            versions = _list_versions(client, base, headers, agent_id)
+            v = next((x for x in versions if x.get("version") == version), None)
+            if v is None:
+                typer.secho(f"✗ version '{version}' not found for '{agent}'.", fg=typer.colors.RED)
+                raise typer.Exit(1)
+            status = str(v.get("status", ""))
+            if status == "retired":
+                typer.secho(f"✓ {agent} {version} is already retired — nothing to do", fg=typer.colors.GREEN)
+                return
+            if status not in ("staged", "live"):
+                typer.secho(
+                    f"✗ cannot retire a '{status}' version — only staged/live (delete the agent to drop drafts).",
+                    fg=typer.colors.RED,
+                )
+                raise typer.Exit(1)
+            if not force:
+                _guard_open_approvals(client, base, agent, headers, version)
+                live_warn = " (LIVE — it will be unpublished first and STOP SERVING)" if status == "live" else ""
+                typer.confirm(f"Retire {agent} {version}{live_warn}?", abort=True)
+            vid = str(v["id"])
+            if status == "live":
+                r = client.post(f"{base}/api/agent-hub/v1/agents/{agent_id}/versions/{vid}/unpublish", headers=headers)
+                if r.status_code not in (200, 201):
+                    typer.secho(f"✗ unpublish rejected ({r.status_code}): {r.text}", fg=typer.colors.RED)
+                    raise typer.Exit(1)
+                typer.echo(f"  unpublished {version} (live → staged)")
+            r = client.post(f"{base}/api/agent-hub/v1/agents/{agent_id}/versions/{vid}/retire", headers=headers)
+            if r.status_code not in (200, 201):
+                typer.secho(f"✗ retire rejected ({r.status_code}): {r.text}", fg=typer.colors.RED)
+                raise typer.Exit(1)
+            typer.secho(f"✓ retired {agent} {version} — the operator is tearing its pods down", fg=typer.colors.GREEN)
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ retire failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+
+@agent_app.command()
+def delete(
+    agent: str = typer.Argument(..., help="Agent name to delete ENTIRELY, e.g. rag-qa."),
+    api_base: str | None = typer.Option(
+        None, "--api-base", envvar="KEYSTONE_API_BASE", help="Platform API base (through Kong)."
+    ),
+    workspace_id: str | None = typer.Option(
+        None, "--workspace-id", help="Target workspace UUID. Defaults to the one set via `keystone workspace use`."
+    ),
+    force: bool = typer.Option(False, "--force", help="Skip the open-approvals guard and the confirmation prompt."),
+) -> None:
+    """Delete the WHOLE agent (FDP-3439 / US-24): unpublish Live, retire every staged/live
+    version, then soft-delete the registry entry. All traffic stops; pods/routes tear down
+    via the operator. Idempotent — each step skips what is already done."""
+    base, headers = _hub_auth(api_base, workspace_id)
+    try:
+        with httpx.Client(timeout=120) as client:
+            agent_id = _resolve_agent_id(client, base, headers, agent)
+            versions = _list_versions(client, base, headers, agent_id)
+            lives = [v for v in versions if v.get("status") == "live"]
+            active = [v for v in versions if v.get("status") in ("staged", "live")]
+            skipped = [v for v in versions if v.get("status") not in ("staged", "live", "retired")]
+            if not force:
+                _guard_open_approvals(client, base, agent, headers, None)
+                typer.confirm(
+                    f"DELETE agent '{agent}' — {len(versions)} version(s), {len(lives)} live? "
+                    "All of its traffic stops.",
+                    abort=True,
+                )
+            for v in lives:
+                r = client.post(
+                    f"{base}/api/agent-hub/v1/agents/{agent_id}/versions/{v['id']}/unpublish", headers=headers
+                )
+                if r.status_code not in (200, 201):
+                    typer.secho(
+                        f"✗ unpublish {v.get('version')} rejected ({r.status_code}): {r.text}", fg=typer.colors.RED
+                    )
+                    raise typer.Exit(1)
+                typer.echo(f"  unpublished {v.get('version')}")
+            for v in active:
+                r = client.post(f"{base}/api/agent-hub/v1/agents/{agent_id}/versions/{v['id']}/retire", headers=headers)
+                if r.status_code not in (200, 201):
+                    typer.secho(
+                        f"✗ retire {v.get('version')} rejected ({r.status_code}): {r.text}", fg=typer.colors.RED
+                    )
+                    raise typer.Exit(1)
+                typer.echo(f"  retired {v.get('version')}")
+            if skipped:
+                tags = ", ".join(str(v.get("version")) for v in skipped)
+                typer.echo(f"  skipped non-retirable version(s): {tags} (soft-deleted with the agent)")
+            r = client.delete(f"{base}/api/agent-hub/v1/agents/{agent_id}", headers=headers)
+            if r.status_code in (200, 204, 404):  # 404 = already gone (idempotent re-run)
+                typer.secho(
+                    f"✓ deleted {agent} (soft) — pods/routes tear down via the operator; "
+                    "the registry row is kept for audit.",
+                    fg=typer.colors.GREEN,
+                )
+                return
+            typer.secho(f"✗ delete rejected ({r.status_code}): {r.text}", fg=typer.colors.RED)
+            raise typer.Exit(1)
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ delete failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc