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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: keystone-cli
-Version: 0.1.16
+Version: 0.1.27
 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.6,>=0.5
+Requires-Dist: keystone-agent-sdk<0.11,>=0.10
 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.16 → keystone_cli-0.1.27}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keystone-cli"
-version = "0.1.16"
+version = "0.1.27"
 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.5,<0.6",
+    "keystone-agent-sdk>=0.10,<0.11",
     # 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 = "0.1.16"
+target-version = "0.1.27"
 line-length = 120
 
 [tool.ruff.lint]

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

@@ -4,13 +4,20 @@ from __future__ import annotations
 
 import typer
 
+from keystone_cli._stdio import make_stdio_unicode_safe
 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.tool_credentials import tool_credentials_app
 from keystone_cli.commands.workspace import workspace_app
 
+# FDP-4360 — before Typer builds anything. `--help` is rendered inside `app()`, and the help
+# text comes from docstrings carrying `→` and `─`, so a hook that ran per-command would be too
+# late for the very invocation QC reported first. No-op on a console that already copes.
+make_stdio_unicode_safe()
+
 app = typer.Typer(
     help="Keystone pro-code agent CLI — author, validate, and run agents locally.",
     no_args_is_help=True,
@@ -47,6 +54,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.add_typer(tool_credentials_app, name="tool-credentials")
 app.command(name="login")(login)
 app.command(name="dev")(dev)
 

keystone_cli-0.1.27/src/keystone_cli/_stdio.py

@@ -0,0 +1,68 @@
+"""Make stdout/stderr able to carry the CLI's own glyphs (FDP-4360).
+
+Every command prints at least one of ``✓ ✗ → ─ ⚠ ↻``, and Typer renders ``--help`` from
+docstrings that contain them too. On a console whose encoding cannot represent those — a
+Windows cp1252 shell is the reported case, but any ``LANG=C`` box behaves the same — writing
+them raises ``UnicodeEncodeError`` and the command dies at the moment it reports success.
+QC hit exactly that: ``keystone agent init`` created the project and then crashed printing
+``✓``, so the user saw only a traceback and had no way to tell the work had been done.
+
+The fix is deliberately conditional rather than unconditional. A stream that can already
+carry the glyphs is left alone — that keeps a deliberate ``PYTHONIOENCODING`` honoured, and
+keeps this from being one more global that reaches into a process it does not own.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import IO, Any
+
+#: The characters the CLI actually emits that cp1252 (and most 8-bit encodings) cannot carry.
+#: Taken from the source, not guessed: ``— … • · §`` ARE representable in cp1252 and so would
+#: hide the problem if the probe included only them.
+_PROBE = "→✓✗─⚠↻"
+
+
+def _can_carry_glyphs(stream: IO[Any]) -> bool:
+    encoding = getattr(stream, "encoding", None)
+    if not encoding:
+        # No declared encoding (a pipe wrapper, a test double). Nothing to prove it cannot
+        # cope, and nothing to reconfigure either — treat it as fine and leave it be.
+        return True
+    try:
+        _PROBE.encode(encoding)
+    except (UnicodeEncodeError, LookupError):
+        return False
+    return True
+
+
+def make_stdio_unicode_safe(streams: tuple[IO[Any], ...] | None = None) -> None:
+    """Re-open stdout/stderr as UTF-8 when their current encoding cannot carry our glyphs.
+
+    Called once from the CLI entry point, before Typer builds anything — ``--help`` is
+    rendered during ``app()``, so a later hook would already be too late.
+
+    Three things are deliberately tolerated rather than raised on, because a CLI that cannot
+    fix its console must still run the command the user asked for:
+
+    * a stream with no ``reconfigure`` (``io.TextIOWrapper`` has it; pytest's capture object
+      and anything hand-rolled may not),
+    * ``reconfigure`` refusing — a detached or closed stream,
+    * UTF-8 itself being rejected, in which case the encoding is left as it is and only the
+      error handler is relaxed, so an unencodable glyph degrades to ``?`` instead of a crash.
+    """
+    for stream in streams if streams is not None else (sys.stdout, sys.stderr):
+        if _can_carry_glyphs(stream):
+            continue
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, OSError, LookupError):
+            # Last resort: keep the console's own encoding and stop it from raising. The
+            # glyphs become '?', which is a cosmetic loss; the crash was a functional one.
+            try:
+                reconfigure(errors="replace")
+            except (ValueError, OSError):
+                pass

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

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import json
 import os
+import sys
 from dataclasses import asdict, dataclass, fields
 from pathlib import Path
 
@@ -85,6 +86,46 @@ class AuthConfig:
     env: str = ""
 
 
+def endpoint_env(cfg: AuthConfig) -> str | None:
+    """Which env's BAKED endpoints this config carries (issuer or api_base match), or None.
+
+    None for an empty config and for custom endpoints (a deliberate ``--api-base`` / ``--issuer``
+    pointing somewhere no env bakes), so only a config that is recognisably ANOTHER env's is flagged.
+    """
+    for env, (issuer, api_base, _agent) in _ENV_DEFAULTS.items():
+        if (cfg.issuer and cfg.issuer == issuer) or (cfg.api_base and cfg.api_base.rstrip("/") == api_base):
+            return env
+    return None
+
+
+def endpoints_belong_to_other_env(cfg: AuthConfig) -> str | None:
+    """The OTHER env whose endpoints this config carries (vs. this package's ``BUILD_ENV``), else None.
+
+    FDP-3072: the ``env`` stamp alone is not proof. A config stamped ``env=prod`` can still hold the
+    dev issuer/api_base (seen 2026-09-30 after installing the prod package over a dev login): the
+    stamp matched, so ``login`` kept the cache and every command silently went to dev.
+    """
+    env = endpoint_env(cfg)
+    return env if env is not None and env != BUILD_ENV else None
+
+
+_warned_mismatch = False
+
+
+def _warn_if_other_env(cfg: AuthConfig) -> None:
+    """One stderr line per process — a warning, never a block (custom endpoints are never flagged)."""
+    global _warned_mismatch
+    other = endpoints_belong_to_other_env(cfg)
+    if other is None or _warned_mismatch:
+        return
+    _warned_mismatch = True
+    print(
+        f"⚠ {config_path()} points at the {other} endpoints, but this is the {BUILD_ENV} CLI — "
+        f"commands would go to {other}. Run `keystone login` to reset it to {BUILD_ENV}.",
+        file=sys.stderr,
+    )
+
+
 def config_path() -> Path:
     """Config file path. ``KEYSTONE_CONFIG`` overrides (tests); default ``~/.keystone/config.json``."""
     override = os.environ.get("KEYSTONE_CONFIG")
@@ -100,7 +141,9 @@ def load() -> AuthConfig:
     # 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})
+    cfg = AuthConfig(**{k: v for k, v in data.items() if k in known})
+    _warn_if_other_env(cfg)
+    return cfg
 
 
 def _ensure_private_dir(directory: Path) -> None:

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

@@ -1486,6 +1486,12 @@ _GRANT_NAMESPACE = {
     "memory": "memory:",
     "skill": "skill:",
 }
+#: Every name agent-hub acts on (AgentManifestAclGrants): the four above plus rag, whose access is
+#: the per-KB grant instead of a service-level one. Anything else mints nothing and is not in the
+#: invocation ticket's scope either, so every call to it fails at runtime — FDP-5461: doctor used to
+#: skip such a name exactly like rag and still say "wiring looks complete".
+_KNOWN_SERVICES = frozenset(_GRANT_NAMESPACE) | {"rag"}
+_KB_QUERY = "knowledge-base:query"
 
 
 @agent_app.command()
@@ -1532,12 +1538,22 @@ def doctor(
                 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"))
+            kbs = _doctor_string_list(deps, "knowledge_bases")
             agentic_kbs = _doctor_string_list(deps, "agentic_knowledge_bases")
             typer.echo(f"  declared: {', '.join(sorted(declared)) or '(none)'}")
 
+            problems += _doctor_check_unknown_services(declared)
+            if "rag" in declared and not kbs and deps.get("manage_knowledge_bases") is not True:
+                # Advice, not a failure: nothing to query yet, but the agent may be given KBs later.
+                typer.secho(
+                    "  ! rag       declared with no knowledge_bases (and no manage_knowledge_bases) — "
+                    "every KB call will 403 until you list the KBs it may read.",
+                    fg=typer.colors.YELLOW,
+                )
             entries = _doctor_acl_entries(client, base, headers, agent_id)
             if entries is not None:
                 problems += _doctor_check_grants(entries, declared)
+                problems += _doctor_check_kbs(entries, kbs)
                 problems += _doctor_check_agentic_kbs(entries, agentic_kbs)
             if "memory" in declared:
                 problems += _doctor_check_memory(client, base, headers, agent_id, workspace)
@@ -1626,13 +1642,49 @@ def _doctor_check_agentic_kbs(entries: list[dict], declared_agentic: list[str])
     return 1
 
 
+def _doctor_check_unknown_services(declared: set[str]) -> int:
+    """A declared service agent-hub does not know — almost always a typo (FDP-5461)."""
+    unknown = sorted(declared - _KNOWN_SERVICES)
+    for svc in unknown:
+        typer.secho(
+            f"  ✗ {svc:9} is not a building block — nothing is granted for it and every call to it "
+            f"fails. Check the name (known: {', '.join(sorted(_KNOWN_SERVICES))}).",
+            fg=typer.colors.RED,
+        )
+    return len(unknown)
+
+
+def _doctor_check_kbs(entries: list[dict], declared_kbs: list[str]) -> int:
+    """Did `dependencies.knowledge_bases` actually mint `knowledge-base:query` per KB?
+
+    Counted, not matched by id, for the reason given on the agentic check below: an entry may be a
+    KB NAME that agent-hub resolved at publish. A name it could not resolve is kept as-is and simply
+    mints nothing, so a short count is how a misspelt or foreign KB shows up here.
+    """
+    if not declared_kbs:
+        return 0
+    granted = [r for r in entries if str(r.get("permission", "")) == _KB_QUERY]
+    want = len(declared_kbs)
+    if len(granted) >= want:
+        typer.secho(f"  ✓ rag       {_KB_QUERY} on {len(granted)} KB(s)", fg=typer.colors.GREEN)
+        return 0
+    typer.secho(
+        f"  ✗ rag       declares {want} KB(s) but only {len(granted)} {_KB_QUERY} grant(s) landed — "
+        "an entry names a KB that does not exist in this workspace (or is misspelt). Fix "
+        "knowledge_bases and re-publish.",
+        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.
+            # rag: its access IS the per-KB grant (_doctor_check_kbs). An unknown name was already
+            # reported by _doctor_check_unknown_services — not silently skipped any more.
             continue
         matching = sorted(p for p in held if p.startswith(prefix))
         if matching:

{keystone_cli-0.1.16 → keystone_cli-0.1.27}/src/keystone_cli/commands/login.py

@@ -61,7 +61,15 @@ def login(
     # cached (no silent wrong-realm). Same env keeps the cache; flags still override.
     cfg = ts.load()
     same_env = (cfg.env == ts.BUILD_ENV) if cfg.env else (not cfg.issuer or cfg.issuer == ts.DEFAULT_ISSUER)
-    if not same_env:
+    # FDP-3072: the stamp can match while the endpoints are another env's (env=prod holding dev URLs).
+    # Treat that as cross-env too, or the stale endpoints survive every login.
+    stale_env = ts.endpoints_belong_to_other_env(cfg)
+    if stale_env is not None:
+        typer.secho(
+            f"  cached config pointed at the {stale_env} endpoints — resetting to the {ts.BUILD_ENV} defaults",
+            fg=typer.colors.YELLOW,
+        )
+    if not same_env or stale_env is not None:
         cfg = ts.AuthConfig()
     cfg.env = ts.BUILD_ENV
     cfg.issuer = issuer or cfg.issuer or ts.DEFAULT_ISSUER

keystone_cli-0.1.27/src/keystone_cli/commands/tool_credentials.py

@@ -0,0 +1,153 @@
+"""``keystone tool-credentials`` — the secrets a pro-code agent's catalogue tools authenticate with.
+
+FDP-3087 P3. A tool credential is created here, then named in ``agent.yaml``::
+
+    dependencies:
+      tool_buckets: [crm_api]
+      tool_credentials:
+        crm_api: crm-prod-token
+
+The value goes to platform once, which writes it to AWS Secrets Manager; nothing ever gives it back
+— not platform, not this CLI. Only the platform's tool gateway reads it, when an agent calls a tool.
+
+**The value is never taken from the command line.** An argument lands in shell history and in
+``ps`` output for every user on the machine; it is read from a hidden prompt, or from stdin with
+``--from-stdin`` (``pass show crm | keystone tool-credentials create crm-prod-token --from-stdin``).
+"""
+
+from __future__ import annotations
+
+import sys
+
+import httpx
+import typer
+
+from keystone_cli.commands.agent import _hub_auth
+
+tool_credentials_app = typer.Typer(
+    help="Manage the credentials your agents' catalogue tools authenticate with.", no_args_is_help=True
+)
+
+_PATH = "/api/platform/v1/tool-credentials"
+
+
+def _fail(response: httpx.Response, what: str) -> None:
+    try:
+        body = response.json()
+        detail = body.get("detail") or body.get("title") or body
+    except ValueError:
+        detail = response.text[:300]
+    typer.secho(f"✗ {what} failed ({response.status_code}): {detail}", fg=typer.colors.RED)
+    raise typer.Exit(1)
+
+
+def _read_value(from_stdin: bool) -> str:
+    if from_stdin:
+        # One trailing newline is what `echo` / `pass show` add; anything else is the user's.
+        value = sys.stdin.read()
+        value = value[:-1] if value.endswith("\n") else value
+        value = value[:-1] if value.endswith("\r") else value
+    else:
+        value = typer.prompt("Value", hide_input=True, confirmation_prompt=True)
+    if not value.strip():
+        typer.secho("✗ the value is empty", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    return value
+
+
+def _resolve_id(client: httpx.Client, base: str, headers: dict[str, str], ref: str) -> str:
+    """Accept a name or an id — people remember names, the API speaks ids."""
+    response = client.get(f"{base}{_PATH}", headers=headers)
+    if response.status_code != httpx.codes.OK:
+        _fail(response, "lookup")
+    for item in response.json().get("data", []):
+        if ref in (item.get("id"), item.get("name")):
+            return str(item["id"])
+    typer.secho(f"✗ no tool credential named or with id {ref!r} in this workspace", fg=typer.colors.RED)
+    raise typer.Exit(1)
+
+
+@tool_credentials_app.command("list")
+def list_credentials(
+    api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+) -> None:
+    """List the tool credentials in this workspace (names and hints — never values)."""
+    base, headers = _hub_auth(api_base, workspace_id)
+    with httpx.Client(timeout=30) as client:
+        response = client.get(f"{base}{_PATH}", headers=headers)
+    if response.status_code != httpx.codes.OK:
+        _fail(response, "list")
+    items = response.json().get("data", [])
+    if not items:
+        typer.echo("no tool credentials in this workspace")
+        return
+    typer.echo(f"  {'NAME':32} {'ID':38} {'HINT':8} UPDATED")
+    for item in items:
+        hint = f"…{item['value_hint']}" if item.get("value_hint") else "—"
+        typer.echo(
+            f"  {str(item.get('name', ''))[:32]:32} {item.get('id', ''):38} {hint:8} {item.get('updated_at', '')}"
+        )
+
+
+@tool_credentials_app.command("create")
+def create_credential(
+    name: str = typer.Argument(..., help="Unique per workspace — what agent.yaml refers to."),
+    description: str = typer.Option("", "--description"),
+    from_stdin: bool = typer.Option(False, "--from-stdin", help="Read the value from stdin instead of a prompt."),
+    api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+) -> None:
+    """Create a tool credential. For basic auth the value is `user:password`."""
+    value = _read_value(from_stdin)
+    base, headers = _hub_auth(api_base, workspace_id)
+    body: dict[str, str] = {"name": name, "value": value}
+    if description:
+        body["description"] = description
+    with httpx.Client(timeout=30) as client:
+        response = client.post(f"{base}{_PATH}", headers=headers, json=body)
+    if response.status_code not in (httpx.codes.OK, httpx.codes.CREATED):
+        _fail(response, "create")
+    data = response.json().get("data", {})
+    typer.secho(f"✓ created {data.get('name')} — {data.get('id')}", fg=typer.colors.GREEN)
+    typer.echo(f"  use it in agent.yaml:  dependencies.tool_credentials.<bucket>: {data.get('name')}")
+
+
+@tool_credentials_app.command("rotate")
+def rotate_credential(
+    ref: str = typer.Argument(..., help="Name or id."),
+    from_stdin: bool = typer.Option(False, "--from-stdin", help="Read the new value from stdin."),
+    api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+) -> None:
+    """Replace the value. Agents keep working and pick the new value up within a minute."""
+    value = _read_value(from_stdin)
+    base, headers = _hub_auth(api_base, workspace_id)
+    with httpx.Client(timeout=30) as client:
+        cred_id = _resolve_id(client, base, headers, ref)
+        response = client.put(f"{base}{_PATH}/{cred_id}/value", headers=headers, json={"value": value})
+    if response.status_code != httpx.codes.OK:
+        _fail(response, "rotate")
+    typer.secho(f"✓ rotated {ref} — agents use the new value within 60 s", fg=typer.colors.GREEN)
+
+
+@tool_credentials_app.command("delete")
+def delete_credential(
+    ref: str = typer.Argument(..., help="Name or id."),
+    force: bool = typer.Option(False, "--force", "--yes", "-y", help="Skip the confirmation."),
+    api_base: str | None = typer.Option(None, "--api-base", envvar="KEYSTONE_API_BASE"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+) -> None:
+    """Delete a tool credential. Agents that use it start failing those tool calls within 60 s."""
+    if not force:
+        typer.confirm(
+            f"Delete tool credential {ref}? Agents using it will fail their tool calls within a minute.",
+            abort=True,
+        )
+    base, headers = _hub_auth(api_base, workspace_id)
+    with httpx.Client(timeout=30) as client:
+        cred_id = _resolve_id(client, base, headers, ref)
+        response = client.delete(f"{base}{_PATH}/{cred_id}", headers=headers)
+    if response.status_code not in (httpx.codes.OK, httpx.codes.NO_CONTENT):
+        _fail(response, "delete")
+    typer.secho(f"✓ deleted {ref}", fg=typer.colors.GREEN)

{keystone_cli-0.1.16 → keystone_cli-0.1.27}/src/keystone_cli/runner.py

@@ -48,6 +48,7 @@ _OFFLINE_KB: dict[str, Any] = {
     "top_k": 5,
     "similarity_threshold": 0.0,
     "reranker": "none",
+    "doc_routing_enabled": False,
     "chunk_count": 1,
     "file_count": 1,
     # The per-KB caps rag returns (schemas/kb.py) — precisely the values an agent would read to

{keystone_cli-0.1.16 → keystone_cli-0.1.27}/src/keystone_cli/scaffold.py

@@ -19,6 +19,10 @@ from keystone.agent_sdk.manifest import validate_agent_name
 TEMPLATES = (
     "blank",
     "llm",
+    # FDP-5328 — `llm` with a token-streaming reply: the node calls the model through ChatKeystone,
+    # which is what stream_mode=messages republishes. Kept separate rather than changing `llm`, so
+    # the plainest template stays one client call a newcomer can read without LangChain.
+    "llm-streaming",
     "rag-qa",
     "tool-agent",
     "hitl",

{keystone_cli-0.1.16 → keystone_cli-0.1.27}/src/keystone_cli/templates/hitl/README.md.tmpl

@@ -29,5 +29,17 @@ keystone agent hitl list __AGENT_NAME__
 keystone agent hitl respond __AGENT_NAME__ <run-id> --approve --note "ok"
 ```
 
-Use `--reject` to send it down the declined branch instead. See `examples/getting-started.html`
+Use `--reject` to send it down the declined branch instead.
+
+## Before you change `approve`
+
+- **The node re-runs on resume.** Everything above `request_approval` in a node runs again when
+  the approver answers. Keep it the first statement, and put any paid call before it inside a
+  `@durable_task` so the resume replays the result instead of paying twice.
+- **Never catch it.** `request_approval` pauses by raising `GraphInterrupt`, which is an
+  `Exception`. A `try/except Exception` around it swallows the pause: the run finishes without
+  waiting and the high-impact action goes through unapproved.
+- **Several approvals are fine in sequence** (each one pauses, one at a time). Approvals that
+  would pause **in parallel** — parallel branches or `Send` fan-out — are not supported: only the
+  first reaches an approver. See `examples/getting-started.html`
 for the full flow and the `demo-helpdesk` / `support-triage` examples for richer HITL graphs.

{keystone_cli-0.1.16 → keystone_cli-0.1.27}/src/keystone_cli/templates/hitl/pkg/graph.py.tmpl

@@ -9,10 +9,14 @@
 ``request_approval`` — the run parks as ``awaiting_human`` until a person answers with
 ``keystone agent hitl respond``. Routine requests skip straight to release.
 
-Two rules the platform enforces for HITL (see keystone.agent_sdk.request_approval):
-  * Call ``request_approval`` EARLY in the node — on resume the whole node re-runs up to it,
-    so nothing paid/side-effecting may run before it. Here it is the first statement.
-  * Paid work goes through ``@durable_task`` so a crash-resume replays it, never re-bills it.
+Three HITL rules (full text in keystone.agent_sdk.request_approval):
+  * The node body RE-RUNS from the top on every resume, so anything before
+    ``request_approval`` runs again. Call it EARLY — here it is the first statement.
+  * Paid work goes through ``@durable_task``: on a resume (or a crash-resume) it replays its
+    stored result instead of calling the model again, so it is billed once.
+  * NEVER wrap ``request_approval`` in ``try/except Exception``. It pauses by raising
+    ``GraphInterrupt``; a broad except swallows it, the run never waits for the approver, and
+    the action that needed approval happens anyway.
 
 Offline the model stub isn't valid JSON, so ``assess`` defaults to routine and the run
 completes without ever pausing (a local run has no checkpointer to park on).

keystone_cli-0.1.27/src/keystone_cli/templates/llm-streaming/README.md.tmpl

@@ -0,0 +1,46 @@
+# __AGENT_NAME__
+
+Scaffolded from the **llm-streaming** template — the `llm` agent, but the reply streams **token by
+token**. One node calls the model through **llm-gateway** via `ChatKeystone`.
+
+```
+__PKG__/graph.py   # respond: ChatKeystone(client=get_gateway_client()).ainvoke(...) → reply
+agent.yaml         # declares llm-gateway + the model; io_schema = { prompt }
+```
+
+## Why a separate template
+
+`POST …/invoke/stream?stream_mode=messages` republishes the chunks a LangChain **chat model**
+produces while a node runs. The `llm` template calls `GatewayClient.chat()` — plain HTTP — so its
+stream carries state updates and **no tokens**. `ChatKeystone` wraps the same pooled client, so
+grants, budget, identity and tracing behave exactly as in `llm`.
+
+## Run it locally
+
+```bash
+keystone agent validate .
+keystone agent run . --input '{"prompt": "explain retries in one sentence"}' --offline
+```
+
+`--offline` mocks the gateway call and does not stream; it proves the wiring only.
+
+## Deploy, then watch it stream
+
+```bash
+keystone agent deploy . --publish
+```
+
+The CLI has no streaming subcommand yet, so stream with `curl` (`-N` turns off buffering — without
+it the tokens arrive all at once and look like no streaming at all):
+
+```bash
+curl -N -X POST "$AGENT_API/api/agent-service/v1/agents/__AGENT_NAME__/invoke/stream?stream_mode=messages" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"inputs": {"prompt": "explain retries in one sentence"}}'
+```
+
+Each `event: token` frame is one chunk. If you only see `state` frames and one final answer, the
+node is not calling a chat model — check it still goes through `ChatKeystone`.
+
+The model in `dependencies.models` must be granted to your workspace, or deploy fails preflight
+with `422 AGENT_DEPENDENCY_NOT_GRANTED`.

keystone_cli-0.1.27/src/keystone_cli/templates/llm-streaming/agent.yaml.tmpl

@@ -0,0 +1,39 @@
+# bundle-rev: 0001 — bump this string to force a rebuild (agent-hub dedups identical bundles by SHA-256)
+# __AGENT_NAME__ — scaffolded by `keystone agent init` (template: llm-streaming).
+# The llm template, but the reply streams token by token: the node calls the model through
+# ChatKeystone (a LangChain chat model over the gateway client), which is what LangGraph's
+# stream_mode=messages republishes. Same inputs, same output, same grants as `llm`.
+# Local loop:
+#   keystone agent validate .
+#   keystone agent run . --input '{"prompt": "explain retries in one sentence"}' --offline
+# Deploy (server-side build — no Dockerfile needed):
+#   keystone agent deploy . --publish
+name: __AGENT_NAME__
+workspace: __WORKSPACE__
+framework: langgraph@1
+entrypoint: __PKG__.graph:make_graph
+runtime: python3.12
+resources:
+  timeout_seconds: 60
+# Enforced at invoke (FDP-4694): a payload that breaks this is refused with 422 BEFORE a run
+# starts, naming the field. Extra keys are allowed — add `additionalProperties: false` if you
+# want them rejected too. Declaring nothing here means every input is accepted.
+io_schema:
+  type: object
+  properties:
+    prompt:
+      type: string
+  required: [prompt]
+dependencies:
+  services: [llm-gateway]
+  models: [bedrock/anthropic.claude-sonnet-4-6]
+# Guardrails policy, applied by `await guard_input(messages=turn)` with no config= (FDP-4567).
+# Declare `guardrails` under dependencies.services too, or the grant is never minted.
+# guardrails:
+#   input:  {pii: {enabled: true, on_detect: mask}}
+#   output: {secrets: {enabled: true, on_detect: block}}
+identity:
+  scopes: [gateway:chat]
+# Per-agent config — injected into the pod as env by the operator.
+config:
+  RT_AGENT_MODEL: "bedrock/anthropic.claude-sonnet-4-6"

keystone_cli-0.1.27/src/keystone_cli/templates/llm-streaming/pkg/graph.py.tmpl

@@ -0,0 +1,53 @@
+"""__AGENT_NAME__ — an llm-gateway agent whose reply STREAMS token by token.
+
+Same shape as the ``llm`` template, one difference that matters: the model is called through
+``ChatKeystone`` instead of ``GatewayClient.chat()``.
+
+Why that is the whole trick: ``POST …/invoke/stream?stream_mode=messages`` republishes the chunks a
+LangChain *chat model* produces while a node runs. A node that calls raw HTTP produces none, so the
+stream carries state updates and no tokens — however fast the model answers. ``ChatKeystone`` wraps
+the SAME pooled gateway client, so model grants, budget, caller identity and tracing are unchanged.
+
+Nothing in this file streams by itself: ``ainvoke`` returns the full reply to the graph, and the
+runtime taps the tokens on the way. ``invoke`` (non-streaming) keeps working exactly like ``llm``.
+
+Local loop:
+    keystone agent run . --input '{"prompt": "explain retries in one sentence"}' --offline
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TypedDict
+
+from keystone.agent_sdk import ChatKeystone
+from keystone.agent_sdk.clients import get_gateway_client
+from langchain_core.messages import HumanMessage, SystemMessage
+from langgraph.graph import StateGraph
+
+_SYSTEM = "You are a concise, helpful assistant. Answer in a few sentences."
+
+
+class State(TypedDict, total=False):
+    prompt: str
+    reply: str
+
+
+async def respond(state: State) -> dict[str, str]:
+    # Hand the model the pooled per-run client (get_gateway_client) rather than letting it build
+    # one: a client constructed per call opens a connection pool that is never closed (FDP-4567).
+    model = ChatKeystone(
+        client=get_gateway_client(),
+        model=os.environ.get("RT_AGENT_MODEL", "bedrock/anthropic.claude-sonnet-4-6"),
+    )
+    answer = await model.ainvoke([SystemMessage(_SYSTEM), HumanMessage(state.get("prompt", ""))])
+    # `.content`, not `.text`: a property in langchain-core 1.x, a deprecated method before it.
+    return {"reply": answer.content}
+
+
+def make_graph():
+    g = StateGraph(State)
+    g.add_node("respond", respond)
+    g.set_entry_point("respond")
+    g.set_finish_point("respond")
+    return g