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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: keystone-cli
-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.
+Version: 0.2.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.11,>=0.10
+Requires-Dist: keystone-agent-sdk<0.14,>=0.13.3
 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.27 → keystone_cli-0.2.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keystone-cli"
-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."
+version = "0.2.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.10,<0.11",
+    "keystone-agent-sdk>=0.13.3,<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).
@@ -42,10 +42,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"]
+keystone_cli = ["templates/*/*.tmpl", "templates/*/pkg/*.tmpl", "skills/*/SKILL.md"]
 
 [tool.ruff]
-target-version = "0.1.27"
+target-version = "0.2.0"
 line-length = 120
 
 [tool.ruff.lint]
@@ -53,4 +53,4 @@ extend-select = ["E", "F", "I", "UP", "B", "A"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "-ra --strict-markers --cov=keystone_cli --cov-fail-under=80"
+addopts = "-ra --strict-markers --cov=keystone_cli --cov-fail-under=85"

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

@@ -10,7 +10,9 @@ 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.skills import skills_app
 from keystone_cli.commands.tool_credentials import tool_credentials_app
+from keystone_cli.commands.whoami import whoami
 from keystone_cli.commands.workspace import workspace_app
 
 # FDP-4360 — before Typer builds anything. `--help` is rendered inside `app()`, and the help
@@ -19,7 +21,7 @@ from keystone_cli.commands.workspace import workspace_app
 make_stdio_unicode_safe()
 
 app = typer.Typer(
-    help="Keystone pro-code agent CLI — author, validate, and run agents locally.",
+    help="Keystone CLI — build, test, deploy and operate pro-code agents.",
     no_args_is_help=True,
     add_completion=False,
 )
@@ -47,7 +49,11 @@ def _main(
 
 @app.command(name="version")
 def version() -> None:
-    """Show the CLI version, its target env, and the bundled agent-sdk version."""
+    """Show the CLI version, its target env and the bundled agent-sdk version.
+
+    Example:
+      keystone version
+    """
     typer.echo(version_line())
 
 
@@ -55,8 +61,10 @@ 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.add_typer(skills_app, name="skills")
 app.command(name="login")(login)
 app.command(name="dev")(dev)
+app.command(name="whoami")(whoami)
 
 
 if __name__ == "__main__":

keystone_cli-0.2.0/src/keystone_cli/agent_logs.py

@@ -0,0 +1,463 @@
+"""``keystone agent logs`` — the pure half: time windows, query params, rendering, paging, SSE.
+
+The command in :mod:`keystone_cli.commands.agent` owns auth, agent-name resolution and printing;
+everything here takes plain values or an ``httpx.Client`` so it is testable without a terminal.
+
+Backend: the agent-logs service on the CONTROL edge (``/api/agent-logs/v1``):
+
+* ``GET /agents/{agent_id}/logs`` — history, newest first, ``meta.next_before`` cursor, a window of
+  at most ``MAX_RANGE`` and ``limit`` ≤ 500 per page;
+* ``GET /agents/{agent_id}/logs/stream`` — Server-Sent Events: ``line`` events (same shape), a
+  ``: keep-alive`` comment every ~15 s, ``end`` after ~15 min (reconnect with ``since`` = the last
+  line's timestamp), ``error`` when the viewer fell too far behind.
+
+A line carries ``run_id`` and ``correlation_id`` (== a Langfuse trace id), which is what joins a
+run, its trace and its logs.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import dataclasses
+import json
+import re
+import socket
+import threading
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import httpx
+
+LOGS_PATH = "/api/agent-logs/v1/agents/{agent_id}/logs"
+STREAM_PATH = "/api/agent-logs/v1/agents/{agent_id}/logs/stream"
+
+#: The service's own vocabulary (structlog levels, lowest first); a level means "this and above".
+LEVELS = ("debug", "info", "warning", "error", "critical")
+#: The service refuses a wider window (``max_range_days``).
+MAX_RANGE = timedelta(days=7)
+#: Server page size cap.
+MAX_PAGE = 500
+
+_REL = re.compile(r"\A(\d+)([smhd])\Z")
+_UNITS = {"s": "seconds", "m": "minutes", "h": "hours", "d": "days"}
+
+
+class LogsError(Exception):
+    """A request the CLI can explain in one line (bad input, or a refusal from the service)."""
+
+
+def parse_time(raw: str, *, now: datetime | None = None) -> datetime:
+    """``15m`` / ``2h`` / ``3d`` / ``30s`` (that long ago) or an ISO-8601 instant → aware UTC."""
+    now = now or datetime.now(UTC)
+    text = raw.strip()
+    if m := _REL.match(text):
+        return now - timedelta(**{_UNITS[m.group(2)]: int(m.group(1))})
+    try:
+        when = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise LogsError(f"'{raw}' is not a time: use 15m, 2h, 3d or an ISO-8601 instant") from exc
+    return when if when.tzinfo else when.replace(tzinfo=UTC)
+
+
+def iso(when: datetime) -> str:
+    return when.astimezone(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def run_window(run: dict[str, Any], *, now: datetime | None = None) -> tuple[datetime, datetime]:
+    """The time window a run's logs fall in: a minute before it was created to five after it last
+    changed (log shipping lags a few seconds; a slow worker logs after the status flips).
+
+    Without it ``--run`` would search the default last 15 minutes and say "no logs" for any run
+    older than that — the most confusing answer it could give. A run read that carries no
+    timestamps (a background run's detail does not, today) gets the last 24 hours: the run filter
+    keeps that search narrow, and 15 minutes would miss anything older."""
+    now = now or datetime.now(UTC)
+    created = parse_stamp(run.get("created_at")) or now - timedelta(hours=24)
+    last = parse_stamp(run.get("updated_at")) or parse_stamp(run.get("completed_at")) or now
+    end = min(max(last, created) + timedelta(minutes=5), now)
+    # min(): a server clock ahead of this machine's must not yield an empty (inverted) window.
+    start = min(created, end) - timedelta(minutes=1)
+    if end - start > MAX_RANGE:
+        start = end - MAX_RANGE
+    return start, end
+
+
+def parse_stamp(raw: Any) -> datetime | None:
+    if not isinstance(raw, str) or not raw:
+        return None
+    try:
+        when = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return when if when.tzinfo else when.replace(tzinfo=UTC)
+
+
+@dataclass(frozen=True)
+class Filters:
+    """The filters history and stream share. ``None`` / empty = not sent."""
+
+    level: str | None = None
+    text: str | None = None
+    run_id: str | None = None
+    correlation_id: str | None = None
+    version: str | None = None
+    container: str | None = None
+    pods: tuple[str, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        if self.level is not None and self.level not in LEVELS:
+            raise LogsError(f"--level must be one of {', '.join(LEVELS)}")
+        if self.container is not None and self.container not in ("agent", "worker"):
+            raise LogsError("--container must be agent or worker")
+
+    def params(self) -> list[tuple[str, str]]:
+        out: list[tuple[str, str]] = []
+        for key, value in (
+            ("level", self.level),
+            ("q", self.text),
+            ("run_id", self.run_id),
+            ("correlation_id", self.correlation_id),
+            ("version", self.version),
+            ("container", self.container),
+        ):
+            if value:
+                out.append((key, value))
+        out.extend(("pod", p) for p in self.pods)
+        return out
+
+
+def explain(resp: httpx.Response) -> str:
+    """One line a person (or a coding agent) can act on, from the service's error envelope."""
+    try:
+        err = (resp.json() or {}).get("error") or {}
+    except ValueError:
+        err = {}
+    code, message = err.get("code", ""), err.get("message") or resp.text[:200]
+    hints = {
+        401: "your session is not accepted here — run `keystone login` again",
+        403: "you need trace:read on this agent (the same right that shows its traces)",
+        404: "no such agent for you in this workspace",
+        429: f"rate limited — retry in {resp.headers.get('Retry-After', 'a few')} s",
+        503: "log search is not configured in this environment",
+    }
+    hint = hints.get(resp.status_code)
+    head = f"{resp.status_code} {code}".strip()
+    return f"{head}: {message}" + (f" — {hint}" if hint else "")
+
+
+def fetch_history(
+    client: httpx.Client,
+    base: str,
+    headers: dict[str, str],
+    agent_id: str,
+    *,
+    start: datetime,
+    end: datetime,
+    filters: Filters,
+    limit: int,
+) -> tuple[list[dict[str, Any]], bool]:
+    """Up to ``limit`` lines in the window, OLDEST first (as a terminal reads), following
+    ``next_before`` across pages. Returns ``(lines, more)`` — ``more`` when the window held more
+    than ``limit`` (or the service truncated it), so the caller can say so."""
+    if end <= start:
+        raise LogsError("--since must be before --until")
+    if end - start > MAX_RANGE:
+        raise LogsError("the window is wider than 7 days — narrow --since/--until")
+    url = base + LOGS_PATH.format(agent_id=agent_id)
+    lines: list[dict[str, Any]] = []
+    before: str | None = None
+    truncated = False
+    while len(lines) < limit:
+        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()])
+        if resp.status_code != 200:
+            raise LogsError(explain(resp))
+        body = resp.json() or {}
+        page = body.get("data") or []
+        meta = body.get("meta") or {}
+        lines.extend(page)
+        before = meta.get("next_before")
+        truncated = truncated or bool(meta.get("truncated"))
+        if not page or not before:
+            before = None
+            break
+    more = truncated or before is not None or len(lines) > limit
+    lines = lines[:limit]
+    lines.reverse()
+    return lines, more
+
+
+def fetch_run_history(
+    client: httpx.Client,
+    base: str,
+    headers: dict[str, str],
+    agent_id: str,
+    *,
+    start: datetime,
+    end: datetime,
+    filters: Filters,
+    run_id: str,
+    trace_id: str | None,
+    limit: int,
+) -> tuple[list[dict[str, Any]], bool]:
+    """A run's lines, which no single filter finds (measured on dev, 2026-10-10):
+
+    * the runtime's own lines (both containers) carry ``run_id``; the background worker's carry
+      no correlation id;
+    * the agent author's own logging calls in a synchronous run carry the request's correlation
+      id (== the run's trace id) but no ``run_id``.
+
+    So it asks by ``run_id`` and, when the run has a trace id, by that too, and merges the two by
+    line id — oldest first, the newest ``limit`` kept."""
+    by_run, more_run = fetch_history(
+        client,
+        base,
+        headers,
+        agent_id,
+        start=start,
+        end=end,
+        filters=dataclasses.replace(filters, run_id=run_id, correlation_id=None),
+        limit=limit,
+    )
+    if not trace_id:
+        return by_run, more_run
+    by_trace, more_trace = fetch_history(
+        client,
+        base,
+        headers,
+        agent_id,
+        start=start,
+        end=end,
+        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
+
+
+def iter_sse(chunks: Iterator[str]) -> Iterator[tuple[str, str]]:
+    """``(event, data)`` from a text/event-stream. Comments (``: keep-alive``) surface as
+    ``("keep-alive", "")`` so a long-running reader still gets a chance to check its deadline."""
+    event, data = "message", []
+    for raw in chunks:
+        line = raw.rstrip("\r")
+        if line == "":
+            if data:
+                yield event, "\n".join(data)
+            event, data = "message", []
+            continue
+        if line.startswith(":"):
+            yield "keep-alive", ""
+            continue
+        key, _, value = line.partition(":")
+        value = value[1:] if value.startswith(" ") else value
+        if key == "event":
+            event = value
+        elif key == "data":
+            data.append(value)
+
+
+@dataclass
+class FollowState:
+    since: datetime
+    seen: set[str] = field(default_factory=set)
+    #: How many reconnects in a row ended before a single line arrived; caps a tight loop.
+    empty_reconnects: int = 0
+
+
+def follow(
+    client: httpx.Client,
+    base: str,
+    headers: dict[str, str],
+    agent_id: str,
+    *,
+    state: FollowState,
+    filters: Filters,
+    on_line: Callable[[dict[str, Any]], None],
+    should_stop: Callable[[], bool],
+    remaining: Callable[[], float | None] = lambda: None,
+    max_reconnects: int = 3,
+) -> str:
+    """Tail the stream until ``should_stop()`` says so (checked on every event and keep-alive).
+
+    The service closes a stream after ~15 min with ``end``; this reconnects from the last line's
+    timestamp and drops the overlap by line id, so the user sees one continuous tail. Returns why it
+    stopped: ``"stopped"`` (should_stop), or raises :class:`LogsError` on a refusal / ``error``.
+
+    ``remaining()`` — seconds left before a deadline, or None. The stream only wakes this loop on an
+    event or a keep-alive (~15 s), and every keep-alive resets a read timeout, so neither honours a
+    deadline (measured: ``--timeout 20`` ran 31 s). Instead the response is CLOSED when the time is
+    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)."""
+    url = base + STREAM_PATH.format(agent_id=agent_id)
+    while True:
+        params = [("since", iso(state.since)), *filters.params()]
+        left = remaining()
+        if left is not None and left <= 0:
+            return "stopped"
+        timeout = httpx.Timeout(30.0, read=None if left is None else max(0.5, min(left, 60.0)))
+        try:
+            reason = _one_stream(
+                client,
+                url,
+                headers,
+                params,
+                timeout=timeout,
+                close_after=left,
+                state=state,
+                on_line=on_line,
+                should_stop=should_stop,
+            )
+        except httpx.ReadTimeout:
+            reason = "stopped" if should_stop() else "timeout"
+        if reason == "stopped" or should_stop():
+            return "stopped"
+        if reason == "timeout":
+            continue  # the deadline is still ahead (read timeout capped at 60 s): reopen and keep going
+        state.empty_reconnects = 0 if reason == "got-line" else state.empty_reconnects + 1
+        if state.empty_reconnects > max_reconnects:
+            raise LogsError("the log stream keeps closing without sending anything — try again later")
+
+
+def _one_stream(
+    client: httpx.Client,
+    url: str,
+    headers: dict[str, str],
+    params: list[tuple[str, str]],
+    *,
+    timeout: httpx.Timeout,
+    close_after: float | None,
+    state: FollowState,
+    on_line: Callable[[dict[str, Any]], None],
+    should_stop: Callable[[], bool],
+) -> str:
+    """One SSE connection: ``"stopped"``, ``"got-line"`` or ``"empty"`` when the server ends it.
+    With ``close_after`` the connection is closed from a timer when that many seconds pass."""
+    with client.stream(
+        "GET", url, headers={**headers, "Accept": "text/event-stream"}, params=params, timeout=timeout
+    ) as resp:
+        if resp.status_code != 200:
+            resp.read()
+            raise LogsError(explain(resp))
+        expired = threading.Event()
+
+        def _expire() -> None:
+            expired.set()
+            # resp.close() alone does NOT interrupt a read already blocked in recv() on another
+            # thread (measured: it returned only at the next keep-alive, ~15 s late). Shutting the
+            # socket down does: recv() returns at once and the iteration below ends.
+            stream = resp.extensions.get("network_stream")
+            sock = stream.get_extra_info("socket") if stream is not None else None
+            if sock is not None:
+                with contextlib.suppress(OSError):
+                    sock.shutdown(socket.SHUT_RDWR)
+            resp.close()
+
+        timer = threading.Timer(close_after, _expire) if close_after is not None else None
+        if timer is not None:
+            timer.daemon = True
+            timer.start()
+        try:
+            return _read_events(resp, state=state, on_line=on_line, should_stop=should_stop)
+        except Exception:
+            if expired.is_set():
+                return "stopped"  # we closed it: the deadline, not a failure
+            raise
+        finally:
+            if timer is not None:
+                timer.cancel()
+
+
+def _read_events(
+    resp: httpx.Response,
+    *,
+    state: FollowState,
+    on_line: Callable[[dict[str, Any]], None],
+    should_stop: Callable[[], bool],
+) -> str:
+    got_line = False
+    for event, data in iter_sse(resp.iter_lines()):
+        if event == "line":
+            line = json.loads(data)
+            line_id = str(line.get("id", ""))
+            if line_id and line_id in state.seen:
+                continue
+            state.seen.add(line_id)
+            got_line = True
+            stamp = parse_stamp(line.get("timestamp"))
+            if stamp and stamp > state.since:
+                state.since = stamp
+            on_line(line)
+        elif event == "error":
+            payload = json.loads(data) if data else {}
+            raise LogsError(f"stream error: {payload.get('message') or payload}")
+        elif event == "end":
+            break
+        if should_stop():
+            return "stopped"
+    return "got-line" if got_line else "empty"
+
+
+_HEAD_CHARS = 300
+
+
+def clip(line: dict[str, Any], max_chars: int) -> dict[str, Any]:
+    """A copy of ``line`` with the message and every string field cut to ``max_chars`` (0 = whole).
+
+    Keeps the first few hundred characters and the END: a traceback's last frames and the
+    exception itself are what a reader — or a coding agent paying per token — needs, and the
+    middle frames (framework plumbing) are what a long one is mostly made of."""
+    if max_chars <= 0:
+        return line
+
+    def cut(value: Any) -> Any:
+        if not isinstance(value, str) or len(value) <= max_chars:
+            return value
+        head = min(_HEAD_CHARS, max_chars // 3)
+        tail = max_chars - head
+        dropped = len(value) - head - tail
+        return f"{value[:head]}\n… [{dropped} chars cut — --max-field-chars 0 for all] …\n{value[-tail:]}"
+
+    out = dict(line)
+    out["message"] = cut(line.get("message"))
+    if isinstance(line.get("fields"), dict):
+        out["fields"] = {k: cut(v) for k, v in line["fields"].items()}
+    return out
+
+
+def render(line: dict[str, Any]) -> str:
+    """``2026-10-10T08:01:02.123Z ERROR  [agent] message  run=1a2b3c4d k=v`` — one line per entry,
+    multi-line messages (tracebacks) indented under it so a grep for the header still works."""
+    level = str(line.get("level") or "info").upper()
+    container = line.get("container")
+    head = f"{line.get('timestamp', '')} {level:<8}" + (f" [{container}]" if container else "")
+    extras: list[str] = []
+    blocks: list[str] = []
+    if run := line.get("run_id"):
+        extras.append(f"run={str(run)[:8]}")
+    if ver := line.get("version"):
+        extras.append(f"ver={ver}")
+    for key, value in (line.get("fields") or {}).items():
+        text_value = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False)
+        if "\n" in text_value:
+            # A traceback (structlog's `exception`) is unreadable folded into the header line.
+            blocks.append(f"  {key}:\n" + "\n".join(f"    {ln}" for ln in text_value.splitlines()))
+        else:
+            extras.append(f"{key}={text_value}")
+    message = str(line.get("message") or "")
+    first, *rest = message.splitlines() or [""]
+    text = f"{head} {first}" + (f"  {' '.join(extras)}" if extras else "")
+    if rest:
+        text += "\n" + "\n".join(f"    {r}" for r in rest)
+    if blocks:
+        text += "\n" + "\n".join(blocks)
+    return text

keystone_cli-0.2.0/src/keystone_cli/agent_skills.py

@@ -0,0 +1,36 @@
+"""Claude Code skills shipped with the CLI — the agent-native half of the developer experience.
+
+A skill is a ``SKILL.md`` a coding agent loads on demand (``.claude/skills/<name>/SKILL.md`` in the
+project). ``keystone-debug`` teaches the loop this CLI supports end to end — invoke → ``logs --run``
+→ ``runs trace`` → fix → redeploy — and how to read the platform's error codes. LangSmith reported
+Claude Code going from 17% to 92% on their own tasks once given skills; the CLI alone is not enough
+for an agent to know which command answers which question.
+
+Skills ship as PACKAGE DATA (``keystone_cli/skills/<name>/SKILL.md``), like the templates, so
+``agent init`` and ``skills install`` work offline and always match the installed CLI's commands.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+SKILLS = ("keystone-debug",)
+
+
+def install(project: Path, *, force: bool = False) -> list[tuple[str, Path, bool]]:
+    """Write every shipped skill into ``project/.claude/skills/``.
+
+    Returns ``(name, path, written)`` per skill. An existing file is left alone unless ``force`` —
+    the team may have edited it, and a CLI upgrade must not silently throw that away."""
+    out: list[tuple[str, Path, bool]] = []
+    for name in SKILLS:
+        target = project / ".claude" / "skills" / name / "SKILL.md"
+        if target.exists() and not force:
+            out.append((name, target, False))
+            continue
+        text = resources.files("keystone_cli").joinpath("skills", name, "SKILL.md").read_text(encoding="utf-8")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text, encoding="utf-8")
+        out.append((name, target, True))
+    return out