keystone-cli 0.1.9__tar.gz → 0.1.16__tar.gz

{keystone_cli-0.1.9 → keystone_cli-0.1.16}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: keystone-cli
-Version: 0.1.9
+Version: 0.1.16
 Summary: Keystone pro-code agent CLI — author, validate, and run agents locally, then deploy and invoke them on the Keystone platform.
 Requires-Python: >=3.12
-Requires-Dist: keystone-agent-sdk<0.4,>=0.3
+Requires-Dist: keystone-agent-sdk<0.6,>=0.5
 Requires-Dist: keystone-request-context<0.4,>=0.3
 Requires-Dist: typer<1,>=0.12
 Requires-Dist: httpx<1,>=0.27

{keystone_cli-0.1.9 → keystone_cli-0.1.16}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keystone-cli"
-version = "0.1.9"
+version = "0.1.16"
 description = "Keystone pro-code agent CLI — author, validate, and run agents locally, then deploy and invoke them on the Keystone platform."
 requires-python = ">=3.12"
 dependencies = [
     # Pinned to a compatible range: on an index (Artifact Registry) an unpinned name resolves to
     # ANY published version — the wheel's metadata is the only pin that travels with it.
-    "keystone-agent-sdk>=0.3,<0.4",
+    "keystone-agent-sdk>=0.5,<0.6",
     # Transitive (the SDK's building-block clients) + used directly by `run` to set a local
     # caller-identity ContextVar and to patch the clients for --offline. uv sources are NOT
     # transitive, so declare it directly (cf. services/llm-gateway).
@@ -45,7 +45,7 @@ where = ["src"]
 keystone_cli = ["templates/*/*.tmpl", "templates/*/pkg/*.tmpl"]
 
 [tool.ruff]
-target-version = "py312"
+target-version = "0.1.16"
 line-length = 120
 
 [tool.ruff.lint]

{keystone_cli-0.1.9 → keystone_cli-0.1.16}/src/keystone_cli/__main__.py

@@ -7,6 +7,7 @@ import typer
 from keystone_cli._version import version_line
 from keystone_cli.commands.agent import agent_app
 from keystone_cli.commands.dev import dev
+from keystone_cli.commands.kb import kb_app
 from keystone_cli.commands.login import login
 from keystone_cli.commands.workspace import workspace_app
 
@@ -45,6 +46,7 @@ def version() -> None:
 
 app.add_typer(agent_app, name="agent")
 app.add_typer(workspace_app, name="workspace")
+app.add_typer(kb_app, name="kb")
 app.command(name="login")(login)
 app.command(name="dev")(dev)
 

{keystone_cli-0.1.9 → keystone_cli-0.1.16}/src/keystone_cli/auth/token_store.py

@@ -95,14 +95,62 @@ def load() -> AuthConfig:
     path = config_path()
     if not path.exists():
         return AuthConfig()
-    data = json.loads(path.read_text())
+    # FDP-4716: `save()` below writes this file with encoding="utf-8"; reading it back with the
+    # locale encoding made the two disagree on Windows, where a workspace name with diacritics
+    # turned a valid session into "not logged in".
+    data = json.loads(path.read_text(encoding="utf-8"))
     known = {f.name for f in fields(AuthConfig)}
     return AuthConfig(**{k: v for k, v in data.items() if k in known})
 
 
+def _ensure_private_dir(directory: Path) -> None:
+    """Config dir, owner-only. ``mode=`` is IGNORED when the directory already exists, so the chmod
+    is not redundant — it is the only thing that narrows a ``~/.keystone`` an older CLI left at 0755.
+
+    Best-effort on purpose: on a shared runner the directory can belong to someone else, and failing
+    the whole ``login`` over a directory bit would be worse than the bit. The FILE is the credential
+    and its mode is enforced unconditionally below; this is the layer around it.
+    """
+    directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+    try:
+        os.chmod(directory, 0o700)
+    except OSError:
+        pass
+
+
 def save(cfg: AuthConfig) -> None:
+    """Persist the config, with the credential never once readable by anyone else (FDP-4574).
+
+    This used to be ``write_text()`` then ``chmod(0o600)``. The end state was right, but between the
+    two calls the refresh token sat on disk at whatever the umask allowed — 0644 on a default box —
+    so on a shared host or CI runner any local user could read it and mint access tokens as the
+    developer until it was revoked. Applying permissions AFTER the content is the bug; the window is
+    the vulnerability, not the final mode, which is why the existing 0600 assertion never saw it.
+
+    So the bytes only ever land in a file that was created 0600. ``O_EXCL`` (after clearing a stale
+    temp) guarantees WE created it, so ``O_CREAT``'s mode really applies rather than being inherited
+    from a leftover file — the one way this shape can silently degrade. umask can only remove bits,
+    never add them, so a permissive umask cannot widen it.
+
+    ``os.replace`` then swaps the inode in atomically. Two things fall out for free: a crash can no
+    longer leave a half-written config that every later command fails to parse, and an existing
+    world-readable ``config.json`` from an older CLI is REPLACED rather than rewritten in place, so
+    it is fixed on the next save instead of keeping its old mode forever.
+
+    The temp carries the pid so two CLI processes saving at once (a `dev` watcher plus a command in
+    another terminal) cannot collide on ``O_EXCL``, and it is removed in a ``finally`` so a failed
+    save does not leave a token sitting in an orphan file.
+    """
     path = config_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    # Write then lock to 0600 (owner-only) — the refresh token is a credential.
-    path.write_text(json.dumps(asdict(cfg), indent=2))
-    path.chmod(0o600)
+    _ensure_private_dir(path.parent)
+    tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    tmp.unlink(missing_ok=True)
+    # O_BINARY (Windows only, 0 elsewhere) keeps newline handling in the text wrapper alone, the way
+    # open() does it — without it the CRT would translate as well, on top of the wrapper.
+    flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0)
+    try:
+        with os.fdopen(os.open(tmp, flags, 0o600), "w", encoding="utf-8") as fh:
+            fh.write(json.dumps(asdict(cfg), indent=2))
+        os.replace(tmp, path)
+    finally:
+        tmp.unlink(missing_ok=True)

{keystone_cli-0.1.9 → keystone_cli-0.1.16}/src/keystone_cli/commands/agent.py

@@ -77,6 +77,11 @@ def validate(
 ) -> None:
     """Validate an agent.yaml (manifest schema + entrypoint importable). Exit 1 on errors."""
     result = sdk_validate(_manifest_path(path))
+    # Notes print on BOTH paths and never change the exit code — they are things that are valid but
+    # will not behave as the author expects (a declared block that needs a second step). Printing
+    # them only on success would hide them exactly when someone is already debugging.
+    for note in result.notes:
+        typer.secho(f"NOTE {note}", fg=typer.colors.YELLOW)
     if result.ok:
         typer.secho(f"✓ {path} is valid", fg=typer.colors.GREEN)
         return
@@ -112,6 +117,7 @@ def run(
         project_dir=Path(manifest_path).resolve().parent,
         inputs=inputs,
         offline=offline,
+        config=result.manifest.config,
     )
     typer.secho(f"\n✓ result: {json.dumps(final, default=str)}", fg=typer.colors.GREEN)
 
@@ -151,6 +157,12 @@ def deploy(
     wait_timeout: int = typer.Option(
         180, "--wait-timeout", help="Seconds to wait for the pod to become ready under --wait."
     ),
+    allow_secrets: bool = typer.Option(
+        False,
+        "--allow-secrets",
+        help="Package files that name a secret-looking variable anyway (fixtures, doc examples). "
+        "Does NOT override the hard block on an actual credential.",
+    ),
 ) -> None:
     """Package the project + upload to agent-hub for a server-side build. Requires `keystone login`.
 
@@ -172,11 +184,28 @@ def deploy(
     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.
+        # No flag lifts this one — the patterns it fires on are a credential and nothing else.
         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
+    # The softer tier (FDP-4715). Matched on the variable NAME, so it can be a fixture or a doc
+    # example — but the default has to be "stop", because the cost is asymmetric: a needless
+    # --allow-secrets costs one re-run, an uploaded credential costs a rotation plus a
+    # blast-radius review, and the bundle outlives the agent (retire/delete cleanup is still off).
+    if bundle.secret_warnings and not allow_secrets:
+        for warning in bundle.secret_warnings:
+            typer.secho(f"✗ {warning.describe()}", fg=typer.colors.RED)
+        typer.secho(
+            "Not packaging these. Move the value to .env (never bundled) and let the operator "
+            "inject it, or reference it from agent.yaml `config:` — re-run with --allow-secrets if "
+            "it really is a placeholder or a fixture.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+    for warning in bundle.secret_warnings:
+        typer.secho(f"⚠ {warning.describe()} — packaged anyway (--allow-secrets).", fg=typer.colors.YELLOW)
     # 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.
@@ -437,19 +466,39 @@ _WARMING_MAX_ATTEMPTS = 6
 _WAIT_TRANSIENT_STATUSES = ("queued", "running", "cancelling", "warming")
 
 
+def _assistant_note(body: dict) -> str:
+    """`· assistant <name>` when the run had one — FDP-4717 (2).
+
+    The runtime has recorded this since W1 (``agent_sessions.assistant_id`` / ``assistant_name``,
+    commented there as "metadata for run list/detail") and the API returns it on BOTH the list rows
+    and the detail read. Only the CLI never showed it, so from a terminal there was no way to tell
+    which assistant drove a run — which is most of the point of having assistants.
+
+    Falls back to the id when the name is absent (an assistant deleted after the run, say), and
+    returns "" when there is neither, so a plain run's output is byte-identical to before.
+    """
+    label = body.get("assistant_name") or body.get("assistant_id")
+    return f" · assistant {label}" if label else ""
+
+
 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)
+        typer.secho(
+            f"✗ {agent} — {status}: {body.get('error') or 'no result'}{_assistant_note(body)}", 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.secho(f"… {agent} — {status} (run {run_id}){_assistant_note(body)}", 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.secho(
+        f"✓ {agent} — {status} (session {body.get('session_id', run_id)}){_assistant_note(body)}",
+        fg=typer.colors.GREEN,
+    )
     typer.echo(json.dumps(body.get("result"), indent=2, default=str, ensure_ascii=False))
 
 
@@ -661,11 +710,21 @@ def runs_list(
     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:
+    # FDP-4717 (2): ASSISTANT. Width from the data so a long assistant name does not shove CREATED
+    # off the line, and the column is DROPPED entirely when no run in the page had one — an agent
+    # that never uses assistants should not pay a column of dashes for the feature.
+    names = [str(it.get("assistant_name") or it.get("assistant_id") or "") for it in items]
+    awidth = max((len(n) for n in names), default=0)
+    if awidth:
+        awidth = max(awidth, len("ASSISTANT"))
+        typer.echo(f"  {'RUN_ID':<36}  {'STATUS':<14}  {'VER':<5}  {'ASSISTANT':<{awidth}}  CREATED")
+    else:
+        typer.echo(f"  {'RUN_ID':<36}  {'STATUS':<14}  {'VER':<5}  CREATED")
+    for it, name in zip(items, names, strict=True):
+        assistant = f"{(name or '-'):<{awidth}}  " if awidth else ""
         typer.echo(
             f"  {it.get('run_id', ''):<36}  {it.get('status', ''):<14}  "
-            f"{(it.get('agent_version') or '-'):<5}  {it.get('created_at') or ''}"
+            f"{(it.get('agent_version') or '-'):<5}  {assistant}{it.get('created_at') or ''}"
         )
     typer.echo(f"\n  showing {len(items)} of {total} (offset {offset})")
 
@@ -731,7 +790,10 @@ def _export_trace(
     trace = (resp.json() or {}).get("data", {})
     payload = json.dumps(trace, indent=2, ensure_ascii=False)
     if output:
-        Path(output).write_text(payload)
+        # FDP-4716: `ensure_ascii=False` above means the payload carries the real characters, so
+        # the write has to name the encoding — otherwise saving a trace with Vietnamese text
+        # raises UnicodeEncodeError on Windows.
+        Path(output).write_text(payload, encoding="utf-8")
         typer.secho(f"✓ wrote trace {trace_id} → {output} ({len(payload)} bytes)", fg=typer.colors.GREEN)
         return
     typer.echo(payload)
@@ -1071,7 +1133,10 @@ def threads_history(
 def threads_delete(
     agent: str = typer.Argument(..., help="Deployed agent name."),
     thread_id: str = typer.Argument(..., help="Thread id = the conversation's session_id (its root run_id)."),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt (CI)."),
+    # FDP-4717 (3): `--force` is an alias, not a second flag. `retire`/`delete` took only
+    # `--force` and this took only `--yes`/`-y`, so a CI script had to remember which verb used
+    # which — and `threads delete --force` failed with `No such option`. All three now accept both.
+    yes: bool = typer.Option(False, "--yes", "-y", "--force", help="Skip the confirmation prompt (CI)."),
     api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
     workspace_id: str | None = typer.Option(None, "--workspace-id"),
 ) -> None:
@@ -1287,6 +1352,12 @@ def _warm_up_until_ready(gw_base: str, headers: dict[str, str], agent: str, *, t
     ``502 GW_UPSTREAM_UNAVAILABLE`` past the deadline means it never came up (most often a boot crash
     — CrashLoopBackOff / CreateContainerError). Exits 1 with the reason on timeout."""
     url = f"{gw_base}/api/agent-service/v1/agents/{agent}/runs"
+    # The gateway requires X-Correlation-ID on every proxied request (agent-gateway identity.py); the
+    # edge injects X-Entity-ID/X-User-ID from the JWT but NOT the correlation id — the caller sets it,
+    # like every other data-plane call (invoke / runs). Reusing the publish headers alone omitted it,
+    # so the probe got 400 GW_MISSING_CORRELATION_ID, which the loop below mistook for "still warming"
+    # and waited out to the deadline → a false "did not become Running".
+    headers = {**headers, "X-Correlation-ID": str(uuid.uuid4())}
     deadline = time.monotonic() + timeout_s
     progress = _BuildProgress(sys.stdout.isatty(), label="Warming up ", noun="warm")
     last = "starting"
@@ -1311,7 +1382,20 @@ def _warm_up_until_ready(gw_base: str, headers: dict[str, str], agent: str, *, t
                 last = "upstream unavailable"
                 progress.tick("upstream unavailable")
                 time.sleep(5)
-            else:  # e.g. route not learned yet right after publish — keep waiting briefly
+            elif resp.status_code == 400:
+                # A rejected request (missing / invalid header) never turns into a 200 by waiting —
+                # fail fast and name it, so it is not mistaken for a boot crash or silently waited out.
+                progress.close()
+                typer.secho(f"✗ warm-up probe rejected: HTTP 400 {resp.text[:200]}", fg=typer.colors.RED)
+                typer.secho(
+                    "  This is a gateway request-validation error, not a pod boot failure — the "
+                    "published version is likely serving. Verify with `keystone agent status` / "
+                    "`keystone agent invoke`; if it persists, the agent-service edge is dropping an "
+                    "identity header.",
+                    fg=typer.colors.RED,
+                )
+                raise typer.Exit(1)
+            else:  # e.g. 404 route not learned yet / 403 authz still propagating — keep waiting briefly
                 last = f"HTTP {resp.status_code}"
                 progress.tick(last)
                 time.sleep(5)
@@ -1386,6 +1470,201 @@ def publish(
         raise typer.Exit(1) from exc
 
 
+#: service declared in `dependencies.services` -> the permission NAMESPACE its grants live under.
+#: Checked by prefix, not by an exact permission list, ON PURPOSE: the authoritative list is
+#: AgentManifestAclGrants (Java), and a second copy here would drift the first time someone adds a
+#: permission. "Is there any memory:* grant?" stays true across that change; "is memory:search
+#: present?" would not.
+#: rag's agentic endpoints are gated on this, separately from plain `knowledge-base:query`. It is
+#: absent from _GRANT_NAMESPACE because rag has no workspace-level grant at all — this one is
+#: per-KB, and is checked against `dependencies.agentic_knowledge_bases` instead.
+_KB_QUERY_AGENTIC = "knowledge-base:query:agentic"
+
+_GRANT_NAMESPACE = {
+    "llm-gateway": "llm:",
+    "guardrails": "guardrails:",
+    "memory": "memory:",
+    "skill": "skill:",
+}
+
+
+@agent_app.command()
+def doctor(
+    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:
+    """Check a deployed agent is actually wired up — grants minted, memory registered.
+
+    Declaring a building block is necessary but not always sufficient, and the gaps only show up
+    as a 403 or 404 on the first real call. This asks the control plane the same questions up
+    front: did agent-hub mint a grant for every service the manifest declares, and (for memory)
+    does the agent have the tenant row that the grant alone does not create.
+    """
+    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}
+    problems = 0
+    try:
+        with httpx.Client(timeout=60) as client:
+            agent_id = _resolve_agent_id(client, base, headers, agent)
+            typer.echo(f"{agent}  ({agent_id})")
+
+            deps = _doctor_live_dependencies(client, base, headers, agent_id)
+            if deps is None:
+                typer.secho("  ? no live version — publish one, then re-run.", fg=typer.colors.YELLOW)
+                raise typer.Exit(1)
+            declared = set(_doctor_string_list(deps, "services"))
+            agentic_kbs = _doctor_string_list(deps, "agentic_knowledge_bases")
+            typer.echo(f"  declared: {', '.join(sorted(declared)) or '(none)'}")
+
+            entries = _doctor_acl_entries(client, base, headers, agent_id)
+            if entries is not None:
+                problems += _doctor_check_grants(entries, declared)
+                problems += _doctor_check_agentic_kbs(entries, agentic_kbs)
+            if "memory" in declared:
+                problems += _doctor_check_memory(client, base, headers, agent_id, workspace)
+            if "skill" in declared:
+                # Not a failure: a workspace grant is all agent-hub can mint, by decision.
+                typer.secho(
+                    "  ! skill   search/list work from the workspace grant. Content routes "
+                    "(get/skill-md/files/read/grep/glob) are checked per-skill — if one 403s, "
+                    "grant that skill explicitly. Grants are on-behalf-of, so the invoking "
+                    "user's rights count too.",
+                    fg=typer.colors.YELLOW,
+                )
+    except httpx.RequestError as exc:
+        typer.secho(f"✗ doctor failed (is {base} reachable / are you on the network?): {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+
+    if problems:
+        typer.secho(f"\n✗ {problems} problem(s) — the agent will fail on those at runtime.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    typer.secho("\n✓ wiring looks complete", fg=typer.colors.GREEN)
+
+
+def _doctor_live_dependencies(client: httpx.Client, base: str, headers: dict, agent_id: str) -> dict | None:
+    """`dependencies` of the LIVE version — what the agent is actually running, not your checkout."""
+    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:
+        return None
+    live = next((v for v in resp.json().get("data", []) if v.get("status") == "live"), None)
+    if live is None:
+        return None
+    manifest = live.get("manifest") or {}
+    return manifest.get("dependencies") or {}
+
+
+def _doctor_string_list(deps: dict, key: str) -> list[str]:
+    return [str(x) for x in (deps.get(key) or []) if isinstance(x, str)]
+
+
+def _doctor_acl_entries(client: httpx.Client, base: str, headers: dict, agent_id: str) -> list[dict] | None:
+    """The agent's ACL entries, fetched once and shared by every grant check below."""
+    resp = client.get(
+        f"{base}/api/platform/v1/acl-entries",
+        headers=headers,
+        params={"subject_type": "agent", "subject_id": agent_id, "limit": 100},
+    )
+    if resp.status_code != 200:
+        typer.secho(f"  ? grants   could not read acl-entries ({resp.status_code})", fg=typer.colors.YELLOW)
+        return None
+    return [r for r in resp.json().get("data", []) if isinstance(r, dict)]
+
+
+def _doctor_check_agentic_kbs(entries: list[dict], declared_agentic: list[str]) -> int:
+    """Did `dependencies.agentic_knowledge_bases` actually mint `knowledge-base:query:agentic`?
+
+    Counted rather than matched by id on purpose: the manifest may declare a KB by NAME, and
+    agent-hub resolves it at publish, so the name in the manifest and the resource_id on the grant
+    are legitimately different strings. A count mismatch is still conclusive enough to be worth
+    reporting — nothing else mints this permission.
+    """
+    if not declared_agentic:
+        return 0
+    granted = [r for r in entries if str(r.get("permission", "")) == _KB_QUERY_AGENTIC]
+    want = len(declared_agentic)
+    if len(granted) >= want:
+        typer.secho(f"  ✓ rag       {_KB_QUERY_AGENTIC} on {len(granted)} KB(s)", fg=typer.colors.GREEN)
+        return 0
+    if not granted:
+        typer.secho(
+            f"  ✗ rag       declares {want} agentic KB(s) but holds no {_KB_QUERY_AGENTIC} grant — "
+            "agentic_search/agentic_answer will 403. Check every entry in "
+            "agentic_knowledge_bases also appears in knowledge_bases, spelled identically, "
+            "then re-publish.",
+            fg=typer.colors.RED,
+        )
+        return 1
+    typer.secho(
+        f"  ✗ rag       declares {want} agentic KB(s) but only {len(granted)} grant(s) landed — "
+        "an entry probably names a KB that knowledge_bases does not, or that does not exist in "
+        "this workspace.",
+        fg=typer.colors.RED,
+    )
+    return 1
+
+
+def _doctor_check_grants(entries: list[dict], declared: set[str]) -> int:
+    held = {str(r.get("permission", "")) for r in entries}
+    problems = 0
+    for svc in sorted(declared):
+        prefix = _GRANT_NAMESPACE.get(svc)
+        if prefix is None:
+            # rag is the deliberate case: its access IS the per-KB grant, not a service-level one.
+            continue
+        matching = sorted(p for p in held if p.startswith(prefix))
+        if matching:
+            typer.secho(f"  ✓ {svc:9} {', '.join(matching)}", fg=typer.colors.GREEN)
+        else:
+            problems += 1
+            typer.secho(
+                f"  ✗ {svc:9} no {prefix}* grant — every call 403s. Re-publish so agent-hub mints it.",
+                fg=typer.colors.RED,
+            )
+    return problems
+
+
+def _doctor_check_memory(client: httpx.Client, base: str, headers: dict, agent_id: str, workspace: str) -> int:
+    """The row memory keeps in its OWN table. A grant does not create it."""
+    resp = client.get(f"{base}/api/memory/v1/agents/{agent_id}/stats", headers=headers)
+    if resp.status_code == 200:
+        typer.secho("  ✓ memory    registered in memory's tenant table", fg=typer.colors.GREEN)
+        return 0
+    if resp.status_code == 404:
+        typer.secho(
+            "  ✗ memory    NOT registered (404 MEM_AGENT_NOT_FOUND) — the grant is not enough. Fix:\n"
+            f"              POST {base}/api/memory/v1/workspaces/{workspace}/agents "
+            f'{{"agent_id": "{agent_id}"}}\n'
+            "              or set AGENT_HUB_MEMORY_AUTO_PROVISION_ENABLED on agent-hub and re-publish.",
+            fg=typer.colors.RED,
+        )
+        return 1
+    typer.secho(f"  ? memory    unexpected status {resp.status_code} from stats", fg=typer.colors.YELLOW)
+    return 0
+
+
 @agent_app.command()
 def status(
     agent: str = typer.Argument(..., help="Agent name, e.g. docs-qa."),
@@ -1534,7 +1813,10 @@ def retire(
     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."),
+    # FDP-4717 (3): `--yes`/`-y` accepted as aliases — see `threads delete`.
+    force: bool = typer.Option(
+        False, "--force", "--yes", "-y", 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
@@ -1582,13 +1864,25 @@ def retire(
 @agent_app.command()
 def delete(
     agent: str = typer.Argument(..., help="Agent name to delete ENTIRELY, e.g. rag-qa."),
+    purge_knowledge_bases: bool = typer.Option(
+        False,
+        "--purge-knowledge-bases",
+        help=(
+            "Also delete the knowledge bases this agent created. OFF by default: an agent's KBs "
+            "normally outlive it as ordinary workspace resources, still reachable by anyone with "
+            "the workspace role."
+        ),
+    ),
     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."),
+    # FDP-4717 (3): `--yes`/`-y` accepted as aliases — see `threads delete`.
+    force: bool = typer.Option(
+        False, "--force", "--yes", "-y", 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
@@ -1629,7 +1923,14 @@ def delete(
             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)
+            r = client.delete(
+                f"{base}/api/agent-hub/v1/agents/{agent_id}",
+                headers=headers,
+                # Sent only when asked. agent-hub defaults it to false, so omitting it would work
+                # too — spelling it out keeps the request readable in a proxy log, where "was the
+                # corpus deleted?" is a question someone will eventually have to answer.
+                params={"purge_knowledge_bases": str(purge_knowledge_bases).lower()},
+            )
             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; "

{keystone_cli-0.1.9 → keystone_cli-0.1.16}/src/keystone_cli/commands/dev.py

@@ -48,6 +48,7 @@ def dev(
         project_dir=Path(manifest_path).resolve().parent,
         initial_input=initial,
         offline=offline,
+        config=result.manifest.config,
     )