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

graph_agents_cli/_approvals.py

@@ -0,0 +1,400 @@
+# 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.
+
+"""Client side of the human approval gate: the paused call, shown safely, and how to decide it.
+
+An API's ``approval`` block in ``api-policy.yaml`` makes the agent pause
+before sending a gated call. The chat API then ends the run's stream with
+``message.end`` whose ``status`` is ``awaiting_approval`` and whose
+``approval`` describes the call (``approval_id``, ``api``, ``method``,
+``path``, ``query``, ``body``, ``operation_id``, ``reason``, ``approvers``,
+``expires_at``). ``GET /threads/{thread_id}/approvals`` lists a thread's
+approvals and ``POST /threads/{thread_id}/approvals/{approval_id}`` decides
+one. ``run``, ``approvals`` and ``eval generate`` share this module. A decision
+this agent relays to another agent carries ``effect`` (the call that will
+actually happen there) and ``nested`` (the approvals it passes through): they
+are printed first.
+
+Everything in an approval except its id came, one way or another, from the
+model (the path's ids, the body, the stated reason), and the model may have
+read text an attacker wrote. A human decides from what is printed here, so
+it is printed in full (never cut) and with every control, format and
+separator character escaped: no text can move the cursor, recolour the
+screen, reorder characters or fake a line of this output.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shlex
+import unicodedata
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from graph_agents_cli._api_policy import (
+    HTTP_METHODS,
+    REQUESTER_APPROVER,
+    path_matches,
+    path_template_problem,
+)
+from graph_agents_cli._chat_client import DECISION_APPROVE, DECISION_REJECT
+
+# Approval statuses the server reports.
+STATUS_PENDING = "pending"
+STATUS_APPROVED = "approved"
+STATUS_REJECTED = "rejected"
+STATUS_EXPIRED = "expired"
+
+# What an eval case's `approvals` instructions and `expect.approvals` match a gate on.
+MATCH_KEYS = ("api", "operation_id", "method", "path")
+
+# The refusals of `POST /threads/{thread_id}/approvals/{approval_id}`.
+DECISION_REFUSALS: dict[int, str] = {
+    403: (
+        "you are not an allowed approver of this call. requester is the principal who "
+        "started the run; role:<name> is any other principal holding that role (a requester "
+        "decides their own call only when requester is listed)"
+    ),
+    404: "no such approval on that thread (a wrong id, or the thread was deleted)",
+    409: "it is not pending any more: it was already decided (an approval is single-use)",
+    410: "it expired, which rejected the call: nothing was sent; ask the agent again",
+}
+
+_ESCAPED_CATEGORIES = frozenset({"Cc", "Cf", "Zl", "Zp", "Cs", "Co", "Cn"})
+
+
+def safe_text(value: Any) -> str:
+    """``value`` as one line of terminal-safe text.
+
+    Every control (C0, DEL, C1), format (bidi overrides, zero-width marks),
+    line/paragraph separator, surrogate, private-use or unassigned character is
+    written as its ``\\x``/``\\u``/``\\U`` escape, so what the terminal shows
+    is exactly what the value holds.
+    """
+    text = value if isinstance(value, str) else str(value)
+    out: list[str] = []
+    for char in text:
+        if unicodedata.category(char) in _ESCAPED_CATEGORIES:
+            code = ord(char)
+            if code <= 0xFF:
+                out.append(f"\\x{code:02x}")
+            elif code <= 0xFFFF:
+                out.append(f"\\u{code:04x}")
+            else:
+                out.append(f"\\U{code:08x}")
+        else:
+            out.append(char)
+    return "".join(out)
+
+
+# What streamed agent text may not send to the terminal: C0 controls but tab and
+# newline (ESC starts every cursor, colour and conceal sequence), DEL, C1 controls
+# (0x9b is a one-byte CSI) and the bidi embedding, override and isolate marks.
+_TERMINAL_CONTROLS = re.compile("[\\x00-\\x08\\x0b-\\x1f\\x7f-\\x9f\\u202a-\\u202e\\u2066-\\u2069]")
+
+
+def terminal_text(text: str) -> str:
+    """Streamed agent text with the characters that steer a terminal escaped.
+
+    Line breaks and tabs stay (a reply has paragraphs), so the text reads as
+    written; nothing in it can hide, recolour or overwrite the lines around
+    it, such as the approval shown before "Approve? [y/N]".
+    """
+    return _TERMINAL_CONTROLS.sub(lambda m: safe_text(m.group(0)), text)
+
+
+def json_lines(value: Any) -> list[str]:
+    """``value`` as indented JSON, one terminal-safe line per list item.
+
+    ``json.dumps`` escapes the newlines inside strings, so the line breaks left
+    are the ones indentation adds; each line is then passed through ``safe_text``.
+    """
+    try:
+        text = json.dumps(value, indent=2, ensure_ascii=False, sort_keys=True, default=str)
+    except (TypeError, ValueError):
+        text = repr(value)
+    return [safe_text(line) for line in text.split("\n")]
+
+
+def _opt_str(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+@dataclass(frozen=True)
+class Approval:
+    """One approval: the paused call and who may decide it."""
+
+    approval_id: str
+    thread_id: str | None = None
+    api: str | None = None
+    method: str | None = None
+    path: str | None = None
+    query: Any = None
+    body: Any = None
+    operation_id: str | None = None
+    reason: str | None = None
+    approvers: tuple[str, ...] = ()
+    expires_at: str | None = None
+    # pending / approved / rejected / expired (listings); None in a paused run's payload.
+    status: str | None = None
+    decided_at: str | None = None
+    comment: str | None = None
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @classmethod
+    def from_payload(cls, payload: Any, *, thread_id: str | None = None) -> Approval | None:
+        """An approval from the server's JSON (a paused run's or a listing row); None without an id."""
+        if not isinstance(payload, Mapping):
+            return None
+        approval_id = _opt_str(payload.get("approval_id")) or _opt_str(payload.get("id"))
+        if approval_id is None:
+            return None
+        approvers = payload.get("approvers")
+        method = _opt_str(payload.get("method"))
+        return cls(
+            approval_id=approval_id,
+            thread_id=_opt_str(payload.get("thread_id")) or thread_id,
+            api=_opt_str(payload.get("api")),
+            method=method.upper() if method else None,
+            path=_opt_str(payload.get("path")),
+            query=payload.get("query"),
+            body=payload.get("body"),
+            operation_id=_opt_str(payload.get("operation_id")),
+            reason=_opt_str(payload.get("reason")),
+            approvers=tuple(str(a) for a in approvers) if isinstance(approvers, list) else (),
+            expires_at=_opt_str(payload.get("expires_at")),
+            status=_opt_str(payload.get("status")),
+            decided_at=_opt_str(payload.get("decided_at")),
+            comment=_opt_str(payload.get("comment")),
+            raw=dict(payload),
+        )
+
+    @property
+    def pending(self) -> bool:
+        """True unless a listing says it was decided or expired."""
+        return self.status in (None, STATUS_PENDING)
+
+    @property
+    def requester_may_decide(self) -> bool:
+        """Whether the principal who started the run is one of the approvers."""
+        return REQUESTER_APPROVER in self.approvers
+
+    def call_line(self) -> str:
+        """``POST /orders/ORD-1/cancel (api orders, operation cancelOrder)``, terminal-safe."""
+        call = f"{safe_text(self.method or '?')} {safe_text(self.path or '?')}"
+        details = []
+        if self.api:
+            details.append(f"api {safe_text(self.api)}")
+        if self.operation_id:
+            details.append(f"operation {safe_text(self.operation_id)}")
+        return f"{call} ({', '.join(details)})" if details else call
+
+    def effect_lines(self) -> list[str]:
+        """What a relayed decision will do (``effect``) and through which approvals (``nested``).
+
+        ``orders (via billing) will POST /orders/ORD-1002/cancel (cancelOrder), as reported
+        by orders``, its body, and one ``via`` line per agent; empty for any other approval.
+        """
+        effect = self.raw.get("effect")
+        if not isinstance(effect, Mapping):
+            return []
+        via = [str(v) for v in effect.get("via") or [] if v]
+        agent = str(effect.get("agent") or "?")
+        hops = via[:-1] if via and via[-1] == agent else via
+        who = safe_text(agent) + (f" (via {', '.join(safe_text(h) for h in hops)})" if hops else "")
+        what = f"{safe_text(effect.get('method') or '?')} {safe_text(effect.get('path') or '?')}"
+        if effect.get("operation_id"):
+            what += f" ({safe_text(effect['operation_id'])})"
+        reported = f", as reported by {safe_text(via[-1])}" if via else ""
+        lines = [f"  effect:      {who} will {what}{reported}"]
+        for key in ("query", "body"):
+            if effect.get(key) not in (None, {}, [], ""):
+                shown = json_lines(effect[key])
+                lines.append(f"    {key + ':':<11}{shown[0]}")
+                lines.extend(f"               {line}" for line in shown[1:])
+        if effect.get("expires_at"):
+            lines.append(
+                f"    expires:   {safe_text(effect['expires_at'])} (at {safe_text(agent)})"
+            )
+        level, depth = self.raw.get("nested"), 0
+        while isinstance(level, Mapping) and depth < 8:
+            decided = safe_text(level.get("decide_with") or "?")
+            lines.append(
+                f"  via:         {safe_text(level.get('agent') or '?')} approval "
+                f"{safe_text(level.get('approval_id') or '?')} (decided there: {decided})"
+            )
+            level, depth = level.get("nested"), depth + 1
+        return lines
+
+    def lines(self) -> list[str]:
+        """The approval in full, as the human deciding it must see it (what it will do first)."""
+        lines = [*self.effect_lines(), f"  call:        {self.call_line()}"]
+        if self.query not in (None, {}, [], ""):
+            query = json_lines(self.query)
+            lines.append(f"  query:       {query[0]}")
+            lines.extend(f"               {line}" for line in query[1:])
+        if self.body is not None:
+            body = json_lines(self.body)
+            lines.append(f"  body:        {body[0]}")
+            lines.extend(f"               {line}" for line in body[1:])
+        else:
+            lines.append("  body:        (none)")
+        if self.reason:
+            lines.append(f"  reason:      {safe_text(self.reason)}")
+        approvers = ", ".join(safe_text(a) for a in self.approvers) or "(not stated)"
+        lines.append(f"  approvers:   {approvers}")
+        if self.expires_at:
+            lines.append(f"  expires at:  {safe_text(self.expires_at)}")
+        if self.status:
+            status = safe_text(self.status)
+            if self.decided_at:
+                status += f" at {safe_text(self.decided_at)}"
+            lines.append(f"  status:      {status}")
+        if self.comment:
+            lines.append(f"  comment:     {safe_text(self.comment)}")
+        lines.append(f"  approval id: {safe_text(self.approval_id)}")
+        if self.thread_id:
+            lines.append(f"  thread:      {safe_text(self.thread_id)}")
+        return lines
+
+
+# The marker `run` puts where it leaves a credential out of a printed command.
+REDACTED_MARK = "<redacted>"
+
+
+def decide_commands(
+    approval: Approval,
+    thread_id: str,
+    flags: str = "",
+    *,
+    verbs: Sequence[str] = ("approve",),
+    options: str = "",
+) -> list[str]:
+    """The ``graph-agents-cli approvals approve|reject ...`` commands that decide ``approval``.
+
+    Ids come from the server: they are shell-quoted so a pasted command runs
+    exactly one ``graph-agents-cli`` invocation, and an id that starts with
+    ``-`` goes after ``--`` so it cannot be read as an option (``--url=...``
+    would send the decision elsewhere). ``flags`` (``--url``, headers with
+    credentials redacted) and ``options`` (``--comment ...``) start with a
+    space when not empty.
+    """
+    approval_id = shlex.quote(approval.approval_id)
+    where = f"--thread-id {shlex.quote(thread_id)}{flags}{options}"
+    commands = []
+    for verb in verbs:
+        if approval.approval_id.startswith("-"):
+            commands.append(f"graph-agents-cli approvals {verb} {where} -- {approval_id}")
+        else:
+            commands.append(f"graph-agents-cli approvals {verb} {approval_id} {where}")
+    return commands
+
+
+def awaiting_lines(approval: Approval, thread_id: str | None, flags: str = "") -> list[str]:
+    """What a paused run prints: who decides, and the exact commands to decide it."""
+    who = ", ".join(safe_text(a) for a in approval.approvers) or "an allowed approver"
+    lines = [
+        f"Awaiting approval by {who}: the call was not sent; the run is paused until it is decided."
+    ]
+    if thread_id:
+        (approve,) = decide_commands(approval, thread_id, flags, verbs=(DECISION_APPROVE,))
+        (reject,) = decide_commands(
+            approval, thread_id, flags, verbs=(DECISION_REJECT,), options=' --comment "<why>"'
+        )
+        lines.append(f"  Approve: {approve}")
+        lines.append(f"  Reject:  {reject}")
+        if REDACTED_MARK in flags:
+            lines.append("  (re-supply the redacted credential values)")
+        if not approval.approvers:
+            lines.append(
+                "  The server did not say who may decide it: an allowed approver runs these "
+                "commands with their own credentials."
+            )
+        elif not approval.requester_may_decide:
+            lines.append(
+                "  Only another principal can decide it (requester is not an approver): send "
+                "them these commands; they run them with their own credentials."
+            )
+    if approval.expires_at:
+        lines.append(f"  It expires (rejected, nothing sent) at {safe_text(approval.expires_at)}.")
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Eval: matching a gate
+# ---------------------------------------------------------------------------
+
+
+def match_problem(match: Any) -> str | None:
+    """Why an eval ``match`` object cannot name a gated call, or None.
+
+    ``{"operation_id": ...}`` or ``{"method": ..., "path": ...}`` (a path
+    template: ``{name}`` matches one segment), or all three; ``api`` narrows
+    it to one API.
+    """
+    if not isinstance(match, Mapping) or not match:
+        return 'must be an object like {"operation_id": "..."} or {"method": "...", "path": "..."}'
+    unknown = sorted(set(match) - set(MATCH_KEYS), key=str)
+    if unknown:
+        return f"unknown key(s) {', '.join(map(str, unknown))} (known: {', '.join(MATCH_KEYS)})"
+    for key in MATCH_KEYS:
+        if key in match and not (isinstance(match[key], str) and match[key].strip()):
+            return f"{key} must be a non-empty string"
+    has_endpoint = "method" in match and "path" in match
+    if "operation_id" not in match and not has_endpoint:
+        return "needs operation_id, or method and path"
+    if ("method" in match) != ("path" in match):
+        return "method and path go together"
+    if "method" in match and match["method"].upper() not in HTTP_METHODS:
+        return f"unknown HTTP method {match['method']!r} (allowed: {', '.join(HTTP_METHODS)})"
+    if "path" in match:
+        problem = path_template_problem(match["path"])
+        if problem:
+            return f"path {problem}"
+    return None
+
+
+def call_matches(match: Mapping[str, Any], call: Mapping[str, Any] | Approval) -> bool:
+    """Whether a valid ``match`` names the call: every key it gives must agree."""
+    if isinstance(call, Approval):
+        call = {
+            "api": call.api,
+            "operation_id": call.operation_id,
+            "method": call.method,
+            "path": call.path,
+        }
+    if "api" in match and call.get("api") != match["api"]:
+        return False
+    if "operation_id" in match and call.get("operation_id") != match["operation_id"]:
+        return False
+    if "method" in match and str(call.get("method") or "").upper() != match["method"].upper():
+        return False
+    if "path" in match:
+        path = call.get("path")
+        if not isinstance(path, str) or not path_matches(match["path"], path):
+            return False
+    return True
+
+
+def describe_match(match: Mapping[str, Any]) -> str:
+    """``cancelOrder`` / ``POST /orders/{id}/cancel`` / ``orders: cancelOrder POST /...``."""
+    parts = []
+    if match.get("operation_id"):
+        parts.append(str(match["operation_id"]))
+    if match.get("method"):
+        parts.append(f"{str(match['method']).upper()} {match.get('path')}")
+    text = " ".join(parts)
+    return f"{match['api']}: {text}" if match.get("api") else text

graph_agents_cli/_build.py

@@ -0,0 +1,186 @@
+# 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.
+
+"""Which build of graph-agents-cli is running.
+
+A release and the builds made between two releases share one version string,
+so the version alone cannot tell them apart. Every wheel therefore records the
+source it was built from in ``graph_agents_cli/_build_info.json``, written by
+``hatch_build.py`` at the repository root: the git commit, whether the files
+that go into the wheel had uncommitted changes, and whether the commit carries
+the release tag ``v<version>``. A source checkout (an editable install, ``uv
+run`` in the repository) reads the same facts from git when asked.
+
+The build id is the version for a release build, ``<version>+g<commit7>`` for
+any other commit and ``<version>+g<commit7>.dirty`` when the tree had
+uncommitted changes. A build whose source is unknown (built from a tree without
+git and without the file) is identified by its version only and has no commit.
+
+The build hook loads this module from the source tree by path, before the
+package's dependencies exist, so it uses the standard library only.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+PACKAGE_NAME = "graph-agents-cli"
+BUILD_INFO_FILENAME = "_build_info.json"
+BUILD_INFO_FORMAT = 1
+# The paths whose content goes into the wheel (relative to the repository root):
+# an uncommitted change under one of them makes the build "dirty".
+SOURCE_PATHS = ("src", "pyproject.toml", "hatch_build.py")
+_COMMIT_RE = re.compile(r"[0-9a-f]{40}([0-9a-f]{24})?")  # SHA-1 or SHA-256 object names
+_GIT_TIMEOUT_S = 15
+# Variables that would point git at another repository than the one asked about.
+_GIT_REDIRECTS = ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY")
+
+
+@dataclass(frozen=True)
+class BuildInfo:
+    """The version plus the source facts of one build."""
+
+    version: str
+    commit: str | None = None
+    dirty: bool = False
+    release: bool = False
+
+    @property
+    def id(self) -> str:
+        """``0.2.0`` (release or unknown source), ``0.2.0+g1a2b3c4`` or ``0.2.0+g1a2b3c4.dirty``."""
+        if self.commit is None or (self.release and not self.dirty):
+            return self.version
+        return f"{self.version}+g{self.commit[:7]}{'.dirty' if self.dirty else ''}"
+
+    @property
+    def is_release(self) -> bool:
+        """Built from the commit the release tag ``v<version>`` names, with no local change."""
+        return self.commit is not None and self.release and not self.dirty
+
+    def describe(self) -> str:
+        """One line for ``info``: the id and where it comes from."""
+        if self.commit is None:
+            return f"{self.id} (source unknown: not built from a git checkout)"
+        if self.is_release:
+            return f"{self.id} (release, commit {self.commit[:12]})"
+        if self.dirty:
+            return f"{self.id} (commit {self.commit[:12]} with uncommitted changes)"
+        return f"{self.id} (commit {self.commit[:12]}, not a release)"
+
+
+def _git(root: Path, *args: str) -> str | None:
+    """``git -C root <args>`` stdout (stripped), or None when git fails or is missing."""
+    env = {k: v for k, v in os.environ.items() if k not in _GIT_REDIRECTS}
+    env["GIT_OPTIONAL_LOCKS"] = "0"  # a status must not rewrite the index
+    try:
+        proc = subprocess.run(
+            ["git", "-C", str(root), *args],
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT_S,
+            env=env,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip()
+
+
+def git_facts(root: str | os.PathLike[str], version: str) -> dict[str, object] | None:
+    """The build facts of the git checkout whose top level is ``root``; None when it is not one.
+
+    ``dirty`` is true when a file under :data:`SOURCE_PATHS` differs from the
+    commit (untracked files included, ignored ones not); when git cannot say,
+    the build counts as dirty. ``release`` is true only for a clean tree whose
+    commit carries the tag ``v<version>``.
+    """
+    root_path = Path(root).resolve()
+    top = _git(root_path, "rev-parse", "--show-toplevel")
+    if not top or Path(top).resolve() != root_path:
+        return None  # not a checkout, or a directory inside another repository
+    commit = _git(root_path, "rev-parse", "--verify", "HEAD^{commit}")
+    if not commit or _COMMIT_RE.fullmatch(commit) is None:
+        return None
+    status = _git(root_path, "status", "--porcelain", "--untracked-files=all", "--", *SOURCE_PATHS)
+    dirty = status is None or bool(status)
+    tags = (_git(root_path, "tag", "--points-at", "HEAD") or "").split()
+    return {
+        "format": BUILD_INFO_FORMAT,
+        "version": version,
+        "commit": commit,
+        "dirty": dirty,
+        "release": not dirty and f"v{version}" in tags,
+    }
+
+
+def _from_facts(version: str, facts: object) -> BuildInfo | None:
+    if not isinstance(facts, dict):
+        return None
+    commit = facts.get("commit")
+    if not isinstance(commit, str) or _COMMIT_RE.fullmatch(commit) is None:
+        return None
+    dirty = facts.get("dirty") is not False  # anything but an explicit false counts as dirty
+    return BuildInfo(
+        version=version,
+        commit=commit,
+        dirty=dirty,
+        release=facts.get("release") is True and not dirty,
+    )
+
+
+def _installed_version() -> str:
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as dist_version
+
+    try:
+        return dist_version(PACKAGE_NAME)
+    except PackageNotFoundError:
+        return "0.0.0"  # the unknown-version sentinel of scaffold.utils.version
+
+
+def build_of_package(package_dir: Path, version: str) -> BuildInfo:
+    """The build of the package at ``package_dir``.
+
+    The recorded ``_build_info.json`` wins (an installed wheel); a package that
+    lives at ``<checkout>/src/graph_agents_cli`` reads the checkout's git facts;
+    anything else is a build of unknown source.
+    """
+    info_file = package_dir / BUILD_INFO_FILENAME
+    if info_file.is_file():
+        try:
+            recorded = _from_facts(version, json.loads(info_file.read_text(encoding="utf-8")))
+        except (OSError, ValueError):
+            recorded = None
+        if recorded is not None:
+            return recorded
+    root = package_dir.parent.parent
+    if package_dir.parent.name == "src" and (root / "pyproject.toml").is_file():
+        from_git = _from_facts(version, git_facts(root, version))
+        if from_git is not None:
+            return from_git
+    return BuildInfo(version=version)
+
+
+@functools.cache
+def current_build() -> BuildInfo:
+    """The running build (computed once per process)."""
+    return build_of_package(Path(__file__).resolve().parent, _installed_version())

graph_agents_cli/_build_info.json

@@ -0,0 +1,7 @@
+{
+  "commit": "01c0236b8b6fada8d22673e4608c9cb49b6bcf2e",
+  "dirty": false,
+  "format": 1,
+  "release": true,
+  "version": "0.3.1"
+}