keystone-cli 0.2.2__tar.gz → 0.3.0__tar.gz

{keystone_cli-0.2.2 → keystone_cli-0.3.0}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.4
 Name: keystone-cli
-Version: 0.2.2
+Version: 0.3.0
 Summary: Keystone pro-code agent CLI — build, test, deploy and operate agents on the Keystone platform.
 Requires-Python: >=3.12
-Requires-Dist: keystone-agent-sdk<0.14,>=0.13.3
+Requires-Dist: keystone-agent-sdk<0.14,>=0.13.10
 Requires-Dist: keystone-request-context<0.4,>=0.3
 Requires-Dist: typer<1,>=0.12
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: truststore<1,>=0.10
+Requires-Dist: pytest<9,>=8
 Provides-Extra: dev
 Requires-Dist: pytest<9,>=8; extra == "dev"
 Requires-Dist: pytest-cov<7,>=6; extra == "dev"

{keystone_cli-0.2.2 → keystone_cli-0.3.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keystone-cli"
-version = "0.2.2"
+version = "0.3.0"
 description = "Keystone pro-code agent CLI — build, test, deploy and operate agents 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.13.3,<0.14",
+    "keystone-agent-sdk>=0.13.10,<0.14",
     # 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).
@@ -21,6 +21,9 @@ dependencies = [
     # FDP-6328 — verify TLS through the OS trust store (keystone_cli/_tls.py), so a corporate CA in
     # the macOS Keychain / Windows store works without SSL_CERT_FILE. Pure Python, no dependencies.
     "truststore>=0.10,<1",
+    # FDP-6569 — `keystone agent test` runs the project's unit tests in this environment (the one
+    # `agent run` uses), so pytest ships with the CLI. anyio, their async plugin, comes with httpx.
+    "pytest>=8,<9",
 ]
 
 [project.optional-dependencies]
@@ -45,10 +48,10 @@ where = ["src"]
 
 # `agent init` templates ride INSIDE the wheel (offline scaffold — no network fetch).
 [tool.setuptools.package-data]
-keystone_cli = ["templates/*/*.tmpl", "templates/*/pkg/*.tmpl", "skills/*/SKILL.md"]
+keystone_cli = ["templates/*/*.tmpl", "templates/*/pkg/*.tmpl", "templates/*/tests/*.tmpl", "skills/*/SKILL.md"]
 
 [tool.ruff]
-target-version = "0.2.2"
+target-version = "0.3.0"
 line-length = 120
 
 [tool.ruff.lint]

{keystone_cli-0.2.2 → keystone_cli-0.3.0}/src/keystone_cli/__main__.py

@@ -11,6 +11,7 @@ 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.prompt import prompt_app
 from keystone_cli.commands.skills import skills_app
 from keystone_cli.commands.tool_credentials import tool_credentials_app
 from keystone_cli.commands.whoami import whoami
@@ -21,8 +22,47 @@ from keystone_cli.commands.workspace import workspace_app
 # late for the very invocation QC reported first. No-op on a console that already copes.
 make_stdio_unicode_safe()
 
+#: Shown under the command list (FDP-6604): where to start, what changes the CLI, what the exit codes
+#: mean. Every KEYSTONE_* variable the code reads is listed — test_help_quality enforces it.
+EPILOG = """\b
+Get started:
+  keystone login
+  keystone workspace use <name>
+  keystone agent init my-agent --template llm
+  keystone agent validate my-agent
+  keystone agent test my-agent
+  keystone agent deploy my-agent --publish --wait
+  keystone agent invoke my-agent --input '{"prompt": "hi"}'
+Fields of agent.yaml: keystone agent manifest. Each command: --help.
+
+\b
+Environment:
+  KEYSTONE_CONFIG          config file (default ~/.keystone/config.json);
+                           use one file per environment
+  KEYSTONE_API_BASE        platform API URL (overrides the saved one)
+  KEYSTONE_AGENT_API_BASE  agent API URL: invoke, runs, hitl, threads
+  KEYSTONE_TOKEN           access token, used as given and never renewed
+                           (for CI)
+  KEYSTONE_ISSUER          login: Keycloak realm URL
+  KEYSTONE_CLIENT_ID       login: client id
+  KEYSTONE_CLIENT_SECRET   login --client-credentials: client secret
+  KEYSTONE_NO_BROWSER      login: do not open a browser
+  KEYSTONE_SYSTEM_TRUST    0: do not trust the OS certificate store
+
+\b
+Exit codes:
+  0  done
+  1  failed (the message says why)
+  2  usage error: an unknown command or option, a missing
+     argument, or a field name that agent manifest does not know
+  agent test returns the exit code of pytest. agent fetch returns 1 when
+  it stops early, and still writes what it got.
+  With --json, a failed command prints {"error": ..., "exit_code": ...}
+  on stdout and the message on stderr."""
+
 app = typer.Typer(
     help="Keystone CLI — build, test, deploy and operate pro-code agents.",
+    epilog=EPILOG,
     no_args_is_help=True,
     add_completion=False,
 )
@@ -66,6 +106,7 @@ app.add_typer(workspace_app, name="workspace")
 app.add_typer(kb_app, name="kb")
 app.add_typer(tool_credentials_app, name="tool-credentials")
 app.add_typer(skills_app, name="skills")
+app.add_typer(prompt_app, name="prompt")
 app.command(name="login")(login)
 app.command(name="dev")(dev)
 app.command(name="whoami")(whoami)

keystone_cli-0.3.0/src/keystone_cli/_jsonout.py

@@ -0,0 +1,161 @@
+"""``--json`` output shared by the read commands (FDP-6604).
+
+A script or a coding agent should not parse a table. Every list / get / status / current command
+prints the API's own answer with ``--json`` — the same body, not a reshaped copy, so it carries
+every field the table leaves out. ``test_help_quality`` enforces that these commands have the flag.
+
+:func:`json_errors` keeps stdout parseable while such a command runs: see its docstring.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import functools
+import io
+import json
+import re
+import sys
+from collections.abc import Callable
+from typing import Any, TextIO, cast
+
+import typer
+
+#: What every ``--json`` help says about a failure (a command with its own --json text appends it).
+JSON_FAIL_NOTE = (
+    'If the command fails before its answer, it prints {"error": ..., "exit_code": ...}; '
+    "a stream ends with that object."
+)
+JSON_HELP = f"Print the raw JSON answer instead of a table, for scripts and agents. {JSON_FAIL_NOTE}"
+
+#: The names a command's ``--json`` flag has in this CLI (``prompt`` and ``kb files`` use as_json).
+JSON_PARAMS = ("json_out", "as_json")
+
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+class _JsonRun:
+    """One ``--json`` command run: the real stdout, the text it printed elsewhere, what it answered."""
+
+    def __init__(self, stdout: TextIO) -> None:
+        self.stdout = stdout
+        self.text: list[str] = []
+        self.printed = False
+        self.streamed = False
+
+    def emit(self, text: str) -> None:
+        self.printed = True
+        self.stdout.write(text + "\n")
+        self.stdout.flush()
+
+    def error_text(self) -> str:
+        """From the last ✗ line to the end: the reason it stopped, with the lines that explain it."""
+        lines = [_ANSI.sub("", ln).strip() for ln in "".join(self.text).splitlines()]
+        lines = [ln for ln in lines if ln]
+        last = max((i for i, ln in enumerate(lines) if ln.startswith("✗")), default=len(lines) - 1)
+        reason = " ".join(lines[max(last, 0) :])
+        return reason.lstrip("✗").strip() or "the command failed"
+
+    def fail(self, exit_code: int, error: str | None = None) -> None:
+        # A one-document answer stays as it is (runs get of a failed run). A stream gets the error
+        # as its last line, so a consumer can tell a broken stream from one that ended.
+        if not self.printed or self.streamed:
+            self.emit(json.dumps({"error": error or self.error_text(), "exit_code": exit_code}, ensure_ascii=False))
+
+
+class _Recorded(io.TextIOBase):
+    """stdout and stderr while a ``--json`` command runs: written to stderr, and kept for the error."""
+
+    def __init__(self, target: TextIO, run: _JsonRun) -> None:
+        self._target = target
+        self._run = run
+
+    def write(self, s: str | bytes) -> int:  # ty: click may hand bytes to a stream it cannot classify
+        text = s.decode("utf-8", "replace") if isinstance(s, bytes) else s
+        self._run.text.append(text)
+        self._target.write(text)
+        return len(s)
+
+    def flush(self) -> None:
+        self._target.flush()
+
+    def isatty(self) -> bool:
+        return self._target.isatty()
+
+
+#: The ``--json`` run in progress. A module global, not a ContextVar: one command runs per process,
+#: and a worker thread (fetch-style thread pools) must see it too, or its answer would go to stderr.
+_CURRENT: _JsonRun | None = None
+
+
+def echo_json(value: Any) -> None:
+    """The answer of a ``--json`` command: the only output that reaches stdout while it runs."""
+    _write(json.dumps(value, indent=2, ensure_ascii=False, default=str))
+
+
+def echo_json_line(value: Any) -> None:
+    """One JSON object on one line, for a command that streams (``logs --follow --json``)."""
+    if _CURRENT is not None:
+        _CURRENT.streamed = True
+    _write(json.dumps(value, ensure_ascii=False, default=str))
+
+
+def _write(text: str) -> None:
+    if _CURRENT is None:
+        typer.echo(text)
+    else:
+        _CURRENT.emit(text)
+
+
+def _exception_exit(exc: Exception) -> tuple[int, str]:
+    """A click-style exception (BadParameter, UsageError...) carries its exit code and message."""
+    code = getattr(exc, "exit_code", None)
+    format_message = getattr(exc, "format_message", None)
+    message = format_message() if callable(format_message) else f"{type(exc).__name__}: {exc}"
+    return (code if isinstance(code, int) and code else 1), message
+
+
+def json_errors[F: Callable[..., Any]](fn: F) -> F:
+    """Keep stdout JSON only while a command runs with ``--json``.
+
+    * stdout carries only :func:`echo_json` / :func:`echo_json_line`. Everything else the command
+      prints — ✗ / ! lines, hints, a confirm prompt — goes to stderr, so it cannot break the JSON.
+      A streaming command still streams: each answer line is written at once.
+    * If the command stops before its answer, stdout gets
+      ``{"error": <from its last ✗ line>, "exit_code": <code>}``: on a non-zero exit, an abort, or
+      an exception (raised again, so a traceback still shows on stderr). A command that printed
+      its one answer and then failed (``runs get`` of a failed run) keeps it; a stream gets the
+      error object as its last line.
+
+    A usage error (an unknown option, exit 2) happens before the command runs; Typer prints it to
+    stderr. ``test_help_quality`` checks that every command with ``--json`` has this decorator.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        global _CURRENT  # noqa: PLW0603 — one command per process; reset in `finally`
+        if not any(kwargs.get(name) for name in JSON_PARAMS):
+            return fn(*args, **kwargs)
+        run = _JsonRun(sys.stdout)
+        stderr = sys.stderr
+        _CURRENT = run
+        try:
+            with (
+                contextlib.redirect_stdout(cast("TextIO", _Recorded(stderr, run))),
+                contextlib.redirect_stderr(cast("TextIO", _Recorded(stderr, run))),
+            ):
+                return fn(*args, **kwargs)
+        except typer.Exit as exc:
+            if exc.exit_code:
+                run.fail(exc.exit_code)
+            raise
+        except typer.Abort:
+            run.fail(1, "aborted")
+            raise
+        except Exception as exc:
+            run.fail(*_exception_exit(exc))
+            raise
+        finally:
+            _CURRENT = None
+
+    setattr(wrapper, "_json_errors", True)  # noqa: B010 — read by test_help_quality
+    return cast("F", wrapper)

{keystone_cli-0.2.2 → keystone_cli-0.3.0}/src/keystone_cli/agent_logs.py

@@ -147,10 +147,25 @@ def explain(resp: httpx.Response) -> str:
     return f"{head}: {message}" + (f" — {hint}" if hint else "")
 
 
+#: A function that returns valid auth headers per request (a long paging run outlives a 300 s token).
+HeaderSource = Callable[[], dict[str, str]]
+#: Headers, or a source of them.
+Headers = dict[str, str] | HeaderSource
+
+
+def merge_lines(*batches: list[dict[str, Any]], limit: int) -> tuple[list[dict[str, Any]], bool]:
+    """Batches of lines → unique by line id, oldest first, the newest ``limit`` kept.
+    Returns ``(lines, cut)``; ``cut`` when the union held more than ``limit``."""
+    merged = {str(line.get("id")): line for batch in batches for line in batch}
+    epoch = datetime(1970, 1, 1, tzinfo=UTC)  # by parsed time: mixed-precision ISO stamps mis-sort as text
+    lines = sorted(merged.values(), key=lambda ln: (parse_stamp(ln.get("timestamp")) or epoch, str(ln.get("id"))))
+    return (lines[-limit:] if limit else []), len(lines) > limit
+
+
 def fetch_history(
     client: httpx.Client,
     base: str,
-    headers: dict[str, str],
+    headers: Headers,
     agent_id: str,
     *,
     start: datetime,
@@ -173,7 +188,8 @@ def fetch_history(
         params = [("from", iso(start)), ("to", iso(end)), ("limit", str(min(MAX_PAGE, limit - len(lines))))]
         if before:
             params.append(("before", before))
-        resp = client.get(url, headers=headers, params=[*params, *filters.params()])
+        page_headers = headers if isinstance(headers, dict) else headers()
+        resp = client.get(url, headers=page_headers, params=[*params, *filters.params()])
         if resp.status_code != 200:
             raise LogsError(explain(resp))
         body = resp.json() or {}
@@ -194,7 +210,7 @@ def fetch_history(
 def fetch_run_history(
     client: httpx.Client,
     base: str,
-    headers: dict[str, str],
+    headers: Headers,
     agent_id: str,
     *,
     start: datetime,
@@ -235,11 +251,8 @@ def fetch_run_history(
         filters=dataclasses.replace(filters, run_id=None, correlation_id=trace_id),
         limit=limit,
     )
-    merged = {str(line.get("id")): line for line in [*by_run, *by_trace]}
-    epoch = datetime(1970, 1, 1, tzinfo=UTC)  # by parsed time: mixed-precision ISO stamps mis-sort as text
-    lines = sorted(merged.values(), key=lambda ln: (parse_stamp(ln.get("timestamp")) or epoch, str(ln.get("id"))))
-    more = more_run or more_trace or len(lines) > limit
-    return lines[-limit:], more
+    lines, cut = merge_lines(by_run, by_trace, limit=limit)
+    return lines, more_run or more_trace or cut
 
 
 def iter_sse(chunks: Iterator[str]) -> Iterator[tuple[str, str]]:
@@ -275,7 +288,7 @@ class FollowState:
 def follow(
     client: httpx.Client,
     base: str,
-    headers: dict[str, str],
+    headers: dict[str, str] | Callable[[], dict[str, str]],
     agent_id: str,
     *,
     state: FollowState,
@@ -297,7 +310,10 @@ def follow(
     up — a timer on the connection — and the read that was waiting returns at once. The read
     timeout still bounds the wait for the response headers (the server backfills before sending
     them). An idle stream is never torn down early, so no extra reconnects (each costs a Splunk
-    backfill and a rate-limit slot)."""
+    backfill and a rate-limit slot).
+
+    ``headers`` may be a callable, asked again for every connection (FDP-6283): a reconnect comes
+    ~15 min after the first connection, long after a 300 s access token has expired."""
     url = base + STREAM_PATH.format(agent_id=agent_id)
     while True:
         params = [("since", iso(state.since)), *filters.params()]
@@ -309,7 +325,7 @@ def follow(
             reason = _one_stream(
                 client,
                 url,
-                headers,
+                headers if isinstance(headers, dict) else headers(),
                 params,
                 timeout=timeout,
                 close_after=left,

{keystone_cli-0.2.2 → keystone_cli-0.3.0}/src/keystone_cli/auth/token_store.py

@@ -149,6 +149,12 @@ def config_path() -> Path:
     return Path(override) if override else Path.home() / ".keystone" / "config.json"
 
 
+def platform_base(cfg: AuthConfig, override: str | None = None) -> str:
+    """Platform API URL: ``override`` (a command's ``--api-base``), then ``KEYSTONE_API_BASE``, then
+    the saved one, then the build default. The one place this order is written."""
+    return (override or os.environ.get("KEYSTONE_API_BASE") or cfg.api_base or DEFAULT_API_BASE).rstrip("/")
+
+
 def load() -> AuthConfig:
     path = config_path()
     if not path.exists():