graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/_chat_client.py

@@ -0,0 +1,462 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Synchronous client for the chat API (``POST /chat``, SSE) of a scaffolded agent.
+
+The server side is ``POST /chat`` streaming server-sent events, ``GET /health``,
+``GET /threads``, ``GET /threads/{thread_id}/messages`` and the approval routes
+(``GET /approvals``, ``GET /threads/{thread_id}/approvals``, ``POST
+/threads/{thread_id}/approvals/{approval_id}``). This module is the only
+client-side implementation of that surface; ``run``, ``approvals`` and
+``eval generate`` build on it.
+
+A run that reaches a call its API's policy gates pauses: its stream ends with
+``message.end`` whose ``status`` is ``awaiting_approval`` and whose
+``approval`` names the call. Deciding it (``decide_approval``) resumes the run
+and streams the continuation with the same events as ``POST /chat``.
+
+Only ``httpx`` is imported here: no model SDK, no framework. Clients come from
+``graph_agents_cli._http``: a request to the local server never goes through a
+proxy, and a remote one fails with one line when the environment names a proxy
+httpx cannot use.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Iterator, Mapping
+from typing import Any, NamedTuple
+from urllib.parse import quote
+
+import httpx
+
+from graph_agents_cli import _http
+
+# Event names the scaffolded app streams from POST /chat.
+EVENT_MESSAGE_START = "message.start"
+EVENT_MESSAGE_DELTA = "message.delta"
+EVENT_TOOL_CALL = "tool.call"
+EVENT_TOOL_RESULT = "tool.result"
+EVENT_MESSAGE_END = "message.end"
+EVENT_ERROR = "error"
+
+KNOWN_EVENTS = frozenset(
+    {
+        EVENT_MESSAGE_START,
+        EVENT_MESSAGE_DELTA,
+        EVENT_TOOL_CALL,
+        EVENT_TOOL_RESULT,
+        EVENT_MESSAGE_END,
+        EVENT_ERROR,
+    }
+)
+
+# `message.end` status of a run paused on a gated call (its payload has `approval`).
+STATUS_AWAITING_APPROVAL = "awaiting_approval"
+# The decisions `POST /threads/{thread_id}/approvals/{approval_id}` takes.
+DECISION_APPROVE = "approve"
+DECISION_REJECT = "reject"
+DECISIONS = (DECISION_APPROVE, DECISION_REJECT)
+# The 409 code of `POST /chat` on a thread whose run waits for an approval.
+APPROVAL_PENDING = "approval_pending"
+
+# Scalar timeout kept for callers that pass one number (every phase applies it).
+DEFAULT_TIMEOUT = 120.0
+# The streaming call: connecting must be quick, but a healthy agent may send no
+# event for minutes while a tool or a non-streaming model phase runs. The read
+# timeout bounds that gap without treating it as "unreachable"; ``post_chat``
+# reads this at call time so a caller (or a test) may replace it.
+STREAM_READ_TIMEOUT = 600.0
+STREAM_TIMEOUT = httpx.Timeout(connect=10.0, read=STREAM_READ_TIMEOUT, write=10.0, pool=10.0)
+
+
+class SseEvent(NamedTuple):
+    """One parsed server-sent event.
+
+    ``data`` is the JSON-decoded payload when the ``data:`` lines form valid
+    JSON, otherwise the raw joined string. ``raw`` is always the joined string.
+    """
+
+    event: str
+    data: Any
+    raw: str = ""
+    id: str | None = None
+
+
+# `scheme://user:password@`: the userinfo of any URL in a text.
+_URL_USERINFO = re.compile(r"(\b[A-Za-z][A-Za-z0-9+.-]*://)[^/\s@]+@")
+
+
+def redact_credentials(text: str) -> str:
+    """``text`` with the ``user:password@`` of every URL in it replaced by ``***@``."""
+    return _URL_USERINFO.sub(r"\1***@", text or "")
+
+
+class ChatClientError(Exception):
+    """Base class for chat client failures."""
+
+
+class ChatHTTPError(ChatClientError):
+    """The server answered with an HTTP error status before streaming.
+
+    ``url`` and the message never carry the URL's credentials (``***@``).
+    """
+
+    def __init__(self, status_code: int, body: str, url: str = "") -> None:
+        self.status_code = status_code
+        self.body = body
+        self.url = redact_credentials(url)
+        super().__init__(f"HTTP {status_code} from {self.url or 'server'}: {body}")
+
+
+def _normalise_base(base_url: str) -> str:
+    return base_url.rstrip("/")
+
+
+def _decode_data(raw: str) -> Any:
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return raw
+
+
+def iter_sse(lines: Iterable[str]) -> Iterator[SseEvent]:
+    """Parse a stream of text lines into :class:`SseEvent` objects.
+
+    Follows the WHATWG event-stream grammar: ``:`` lines are comments
+    (keep-alives) and are dropped, ``data:`` lines accumulate joined by
+    ``\\n``, ``event:`` names the event (default ``message``), ``id:`` is kept,
+    ``retry:`` and unknown fields are ignored, and a blank line dispatches the
+    pending event. A pending event at end of stream is dispatched as well, so a
+    server that closes without a trailing blank line still delivers its last
+    event. Events with no data are dropped, as the spec requires.
+    """
+    event_name = ""
+    data_lines: list[str] = []
+    event_id: str | None = None
+
+    def flush() -> SseEvent | None:
+        nonlocal event_name, data_lines, event_id
+        if not data_lines:
+            event_name = ""
+            event_id = None
+            return None
+        raw = "\n".join(data_lines)
+        ev = SseEvent(event_name or "message", _decode_data(raw), raw, event_id)
+        event_name = ""
+        data_lines = []
+        event_id = None
+        return ev
+
+    for line in lines:
+        # Accept both bare and CRLF-terminated lines from any source.
+        line = line.rstrip("\r\n")
+        if line == "":
+            ev = flush()
+            if ev is not None:
+                yield ev
+            continue
+        if line.startswith(":"):
+            continue  # comment / keep-alive
+        field, sep, value = line.partition(":")
+        if sep and value.startswith(" "):
+            value = value[1:]
+        if field == "data":
+            data_lines.append(value)
+        elif field == "event":
+            event_name = value
+        elif field == "id":
+            event_id = value
+        # retry: and unknown fields are ignored.
+
+    ev = flush()
+    if ev is not None:
+        yield ev
+
+
+def _iter_stream_lines(chunks: Iterable[str]) -> Iterator[str]:
+    """Split decoded text chunks into lines on LF, CR or CRLF only.
+
+    ``httpx.Response.iter_lines`` uses ``str.splitlines`` semantics and also
+    breaks on U+0085, U+2028, U+2029, VT, FF, FS, GS and RS, which are legal
+    inside a ``data:`` payload (the scaffolded server encodes with
+    ``ensure_ascii=False``); the event-stream grammar recognises only CR, LF
+    and CRLF as line terminators. A trailing CR is held back until the next
+    chunk shows whether an LF follows, so a CRLF split across chunks is one
+    line break, and a partial last line is flushed at end of stream.
+    """
+    buf = ""
+    for chunk in chunks:
+        buf += chunk
+        while True:
+            i_n = buf.find("\n")
+            i_r = buf.find("\r")
+            if i_n == -1 and i_r == -1:
+                break
+            if i_r != -1 and (i_n == -1 or i_r < i_n):
+                if i_r == len(buf) - 1:
+                    break  # trailing CR: wait to see whether an LF follows
+                end = i_r + 2 if buf[i_r + 1] == "\n" else i_r + 1
+                yield buf[:i_r]
+                buf = buf[end:]
+            else:
+                yield buf[:i_n]
+                buf = buf[i_n + 1 :]
+    if buf:
+        yield buf.rstrip("\r")
+
+
+def _stream_headers(headers: Mapping[str, str] | None) -> dict[str, str]:
+    merged: dict[str, str] = {}
+    if headers:
+        merged.update(headers)
+    # Do not override an explicit Accept from the caller.
+    if not any(k.lower() == "accept" for k in merged):
+        merged["Accept"] = "text/event-stream"
+    return merged
+
+
+def post_chat(
+    base_url: str,
+    message: str,
+    *,
+    thread_id: str | None = None,
+    headers: Mapping[str, str] | None = None,
+    timeout: float | httpx.Timeout | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> Iterator[SseEvent]:
+    """POST ``/chat`` and yield the streamed events as they arrive.
+
+    ``timeout`` defaults to :data:`STREAM_TIMEOUT` (looked up at call time): a
+    short connect phase and a long per-read gap. A scalar applies to every
+    phase. Raises :class:`ChatHTTPError` when the response status is not 2xx
+    (the body is read fully so the caller can show it), and lets ``httpx``
+    transport errors propagate so callers can distinguish "unreachable"
+    (``ConnectError``) from a stalled stream (``ReadTimeout``) and from
+    "refused".
+    """
+    base = _normalise_base(base_url)
+    body: dict[str, Any] = {"message": message, "metadata": dict(metadata or {})}
+    if thread_id:
+        body["thread_id"] = thread_id
+    yield from _post_stream(f"{base}/chat", body, headers=headers, timeout=timeout)
+
+
+def _post_stream(
+    url: str,
+    body: Mapping[str, Any],
+    *,
+    headers: Mapping[str, str] | None,
+    timeout: float | httpx.Timeout | None,
+) -> Iterator[SseEvent]:
+    """POST ``body`` as JSON and yield the SSE events of the answer (``post_chat``'s rules)."""
+    if timeout is None:
+        timeout = STREAM_TIMEOUT
+    with (
+        _http.client(url, timeout=timeout) as client,
+        client.stream("POST", url, json=dict(body), headers=_stream_headers(headers)) as resp,
+    ):
+        if resp.status_code >= 400:
+            resp.read()
+            raise ChatHTTPError(resp.status_code, resp.text, url)
+        yield from iter_sse(_iter_stream_lines(resp.iter_text()))
+
+
+def path_segment(value: str, what: str) -> str:
+    """``value`` as one URL path segment: percent-encoded, so no id can reach another route.
+
+    An approval id or a thread id comes from a server payload or the command
+    line; ``../chat``, ``a/b``, ``.`` or ``..`` must stay one segment of the
+    approval route. Percent-encoding leaves dots alone, and a client drops a
+    ``.``/``..`` segment (or the one before it), so their dots are encoded too.
+    """
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{what} must be a non-empty string")
+    segment = quote(value, safe="")
+    return segment.replace(".", "%2E") if segment in (".", "..") else segment
+
+
+def approval_url(base_url: str, thread_id: str, approval_id: str | None = None) -> str:
+    """``<base>/threads/<thread_id>/approvals[/<approval_id>]`` with each id one segment."""
+    url = f"{_normalise_base(base_url)}/threads/{path_segment(thread_id, 'thread id')}/approvals"
+    if approval_id is not None:
+        url += f"/{path_segment(approval_id, 'approval id')}"
+    return url
+
+
+def decide_approval(
+    base_url: str,
+    thread_id: str,
+    approval_id: str,
+    decision: str,
+    *,
+    comment: str | None = None,
+    headers: Mapping[str, str] | None = None,
+    timeout: float | httpx.Timeout | None = None,
+) -> Iterator[SseEvent]:
+    """Approve or reject a pending approval; yield the events of the resumed run.
+
+    ``POST /threads/{thread_id}/approvals/{approval_id}`` with
+    ``{"decision": "approve"|"reject", "comment": ...}`` and nothing else: the
+    server binds the decision to the call it recorded, so the client never
+    sends (or could change) the call itself. The answer is an SSE stream of the
+    continuation, with the same events as ``POST /chat``. A refusal is a
+    :class:`ChatHTTPError`: 403 (not an allowed approver), 404 (no such
+    approval or thread), 409 (already decided), 410 (expired, which rejected
+    the call).
+    """
+    if decision not in DECISIONS:
+        raise ValueError(f"decision must be one of {', '.join(DECISIONS)}")
+    body: dict[str, Any] = {"decision": decision}
+    if comment:
+        body["comment"] = comment
+    url = approval_url(base_url, thread_id, approval_id)
+    yield from _post_stream(url, body, headers=headers, timeout=timeout)
+
+
+def _json_list(resp: httpx.Response, url: str, key: str) -> list[dict[str, Any]]:
+    if resp.status_code >= 400:
+        raise ChatHTTPError(resp.status_code, resp.text, url)
+    try:
+        data = resp.json()
+    except ValueError:
+        raise ChatClientError(
+            f"unexpected answer from {redact_credentials(url)}: not JSON"
+        ) from None
+    if isinstance(data, dict):
+        data = data.get(key, [])
+    if not isinstance(data, list):
+        raise ChatClientError(f"unexpected answer from {redact_credentials(url)}: not a list")
+    return [item for item in data if isinstance(item, dict)]
+
+
+def list_approvals(
+    base_url: str,
+    thread_id: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    timeout: float = 30.0,
+) -> list[dict[str, Any]]:
+    """GET ``/threads/{thread_id}/approvals``: the thread's approvals, pending or decided.
+
+    The server may wrap the list as ``{"approvals": [...]}``; both shapes are accepted.
+    """
+    url = approval_url(base_url, thread_id)
+    resp = _http.get(url, headers=dict(headers or {}), timeout=timeout)
+    return _json_list(resp, url, "approvals")
+
+
+def list_visible_approvals(
+    base_url: str,
+    *,
+    status: str | None = None,
+    headers: Mapping[str, str] | None = None,
+    limit: int = 100,
+    offset: int = 0,
+    timeout: float = 30.0,
+) -> list[dict[str, Any]]:
+    """GET ``/approvals``: across threads, the approvals the caller may see (one page).
+
+    The caller's own, the ones naming one of its roles (it may decide them),
+    and every one for a read-across role; each row carries its ``thread_id``.
+    An agent without this route answers 404 or 405 (a :class:`ChatHTTPError`).
+    """
+    url = f"{_normalise_base(base_url)}/approvals"
+    params: dict[str, Any] = {"limit": limit, "offset": offset}
+    if status:
+        params["status"] = status
+    resp = _http.get(url, params=params, headers=dict(headers or {}), timeout=timeout)
+    return _json_list(resp, url, "approvals")
+
+
+def list_threads(
+    base_url: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    limit: int = 100,
+    offset: int = 0,
+    timeout: float = 30.0,
+) -> list[dict[str, Any]]:
+    """GET ``/threads``: the caller's own threads (``{thread_id, ...}`` rows), one page."""
+    url = f"{_normalise_base(base_url)}/threads"
+    resp = _http.get(
+        url,
+        params={"limit": limit, "offset": offset},
+        headers=dict(headers or {}),
+        timeout=timeout,
+    )
+    return _json_list(resp, url, "threads")
+
+
+def delete_thread(
+    base_url: str,
+    thread_id: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    timeout: float = 30.0,
+) -> None:
+    """DELETE ``/threads/{thread_id}``: the thread with its runs and its approvals.
+
+    Only its owner may. Raises :class:`ChatHTTPError` on any status but 2xx
+    (a 404 too: the route may be missing as well as the thread), and lets
+    transport errors propagate.
+    """
+    url = f"{_normalise_base(base_url)}/threads/{path_segment(thread_id, 'thread id')}"
+    resp = _http.delete(url, headers=dict(headers or {}), timeout=timeout)
+    if resp.status_code >= 300:
+        raise ChatHTTPError(resp.status_code, resp.text, url)
+
+
+def get_health(
+    base_url: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    timeout: float = 10.0,
+) -> dict[str, Any]:
+    """GET ``/health`` and return its JSON body.
+
+    Raises :class:`ChatHTTPError` on a non-2xx status and lets transport
+    errors propagate.
+    """
+    url = f"{_normalise_base(base_url)}/health"
+    resp = _http.get(url, headers=dict(headers or {}), timeout=timeout)
+    if resp.status_code >= 400:
+        raise ChatHTTPError(resp.status_code, resp.text, url)
+    data = resp.json()
+    return data if isinstance(data, dict) else {"status": data}
+
+
+def get_thread_messages(
+    base_url: str,
+    thread_id: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    timeout: float = 30.0,
+) -> list[dict[str, Any]]:
+    """GET ``/threads/{thread_id}/messages`` and return the ordered messages.
+
+    The server may wrap the list as ``{"messages": [...]}``; both shapes are
+    accepted.
+    """
+    url = f"{_normalise_base(base_url)}/threads/{thread_id}/messages"
+    resp = _http.get(url, headers=dict(headers or {}), timeout=timeout)
+    if resp.status_code >= 400:
+        raise ChatHTTPError(resp.status_code, resp.text, url)
+    data = resp.json()
+    if isinstance(data, dict):
+        data = data.get("messages", [])
+    return list(data)

graph_agents_cli/_click.py

@@ -0,0 +1,157 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Click helpers: lazy command loading and source-path display in --help."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from typing import Any
+
+import click
+
+from graph_agents_cli._experiments import resolve_experiment
+
+
+class LazyGroup(click.Group):
+    """Click group that defers importing subcommand modules until needed.
+
+    Register subcommands with `add_lazy_command(name, "module.path:obj",
+    short_help)`. The module is imported only when the command is actually
+    invoked (e.g. `tool name ...`) or when its own help is requested
+    (`tool name --help`). The parent group's --help (`tool --help`) renders
+    the supplied `short_help` strings directly without triggering any imports.
+
+    `short_help` must match the real command's docstring summary; the parity
+    test in tests/unittests/cli/test_click.py enforces this.
+
+    Pattern reference:
+    https://click.palletsprojects.com/en/stable/complex/#lazily-loading-subcommands
+
+    TODO: Python 3.15 introduces a native `lazy` import keyword (PEP 810). Once
+    our minimum Python version reaches 3.15, the `add_lazy_command` mechanism
+    here may become redundant — revisit and consider simplifying.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._lazy_commands: dict[str, tuple[str, str]] = {}
+        # name -> experiment label
+        self._experiment_gates: dict[str, str] = {}
+        self._overrides: dict[str, click.Command] = {}
+
+    def add_lazy_command(
+        self,
+        name: str,
+        import_path: str,
+        short_help: str,
+        experiment: str | None = None,
+    ) -> None:
+        """Register a subcommand for lazy loading.
+
+        If `experiment` is given, the command is only listed and invocable when
+        that experiment resolves truthy; otherwise it behaves as if it were
+        never registered (hidden from --help, "No such command" on invoke).
+
+        The experiment gate is resolved per invocation in `list_commands`/`get_command`,
+        not at this registration call: `main` is built once at import, so
+        guarding registration would freeze visibility before a unit test could
+        override the experiment.
+        """
+        self._lazy_commands[name] = (import_path, short_help)
+        if experiment is not None:
+            self._experiment_gates[name] = experiment
+
+    def _is_visible(self, name: str) -> bool:
+        """True if `name` is not hidden via experiment."""
+        label = self._experiment_gates.get(name)
+        if label is None:
+            return True
+        return bool(resolve_experiment(label))
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        names = set(super().list_commands(ctx)) | set(self._lazy_commands) | set(self._overrides)
+        return sorted(filter(self._is_visible, names))
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        # Overrides are consulted only after the visibility check, so an installed
+        # extension cannot expose a command that is gated off.
+        if not self._is_visible(cmd_name):
+            return None
+        if cmd_name in self._overrides:
+            return self._overrides[cmd_name]
+        if cmd_name in self._lazy_commands and cmd_name not in self.commands:
+            import_path, _ = self._lazy_commands[cmd_name]
+            module_path, attr = import_path.split(":")
+            cmd = getattr(importlib.import_module(module_path), attr)
+            patch_source_in_help(cmd)
+            self.commands[cmd_name] = cmd
+        return super().get_command(ctx, cmd_name)
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        rows: list[tuple[str, str]] = []
+        for name in self.list_commands(ctx):
+            if name in self._overrides:
+                rows.append((name, self._overrides[name].get_short_help_str(limit=1000)))
+                continue
+            if name in self.commands:
+                # Don't truncate — Click's default of 45 would cut our docstring summaries.
+                rows.append((name, self.commands[name].get_short_help_str(limit=1000)))
+                continue
+            lazy = self._lazy_commands.get(name)
+            if lazy is not None:
+                rows.append((name, lazy[1]))
+        if rows:
+            with formatter.section("Commands"):
+                formatter.write_dl(rows)
+
+
+def _source_path(cmd: Any) -> str | None:
+    """Resolve the absolute file path of a command's callback module."""
+    cb = cmd.callback
+    if cb is None:
+        return None
+    try:
+        mod = importlib.import_module(cb.__module__)
+        return inspect.getfile(mod)
+    except Exception:
+        return None
+
+
+def patch_source_in_help(cmd: Any) -> None:
+    """Recursively patch all commands to show source location in --help epilog.
+
+    Idempotent: a command registered as lazy in two parents (e.g., the
+    `create` alias) would otherwise get its `format_epilog` wrapped twice
+    and render two `Source:` lines.
+    """
+    if getattr(cmd, "_source_patched", False):
+        return
+
+    original = cmd.format_epilog
+
+    def _patched(ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        original(ctx, formatter)
+        path = _source_path(cmd)
+        if path:
+            formatter.write("\n")
+            formatter.write(f"Source: {path}\n")
+
+    cmd.format_epilog = _patched
+    cmd._source_patched = True
+
+    if isinstance(cmd, click.Group):
+        for sub in cmd.commands.values():
+            patch_source_in_help(sub)