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

graph_agents_cli/_response_schema.py

@@ -0,0 +1,264 @@
+# 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.
+
+"""A project's response schema (structured final answers): the check the CLI applies.
+
+A project that declares `<agent directory>/response_schema.json` answers in
+JSON of that shape (the template's `app_utils/structured.py`). The schema may
+use only the JSON Schema subset the runtime checks answers with, and its root
+is an object; `create --response-schema` refuses to seed any other file, and
+`lint` reports one. The rules are the template's own (the SHARED block below,
+byte-identical there), so a schema the CLI accepts starts the agent.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from pathlib import Path
+from typing import Any
+
+import click
+
+SCHEMA_FILENAME = "response_schema.json"
+
+
+class ResponseSchemaFileError(click.ClickException):
+    """A response schema that cannot be read or uses what the answer check cannot check (exit 3)."""
+
+    exit_code = 3
+
+    def __init__(self, path: str | Path, problems: list[str]) -> None:
+        self.path = Path(path)
+        self.problems = list(problems)
+        lines = "\n".join(f"  - {p}" for p in self.problems)
+        super().__init__(f"Invalid response schema {self.path}:\n{lines}")
+
+
+# --- BEGIN SHARED RESPONSE SCHEMA RULES ---
+# The JSON Schema subset a response schema may use, and the check of a schema
+# against it. The same block is in graph_agents_cli/_response_schema.py, which
+# `create --response-schema` and `lint` use: keep the two byte-identical
+# (tests/dev/test_response_schema_parity.py), so a schema the CLI accepts
+# starts the agent. No Jinja, no imports but json, math, re and typing.Any.
+
+# Keywords that are checked, and annotations that are allowed and ignored.
+VALIDATION_KEYWORDS = frozenset(
+    {
+        "type",
+        "enum",
+        "const",
+        "properties",
+        "required",
+        "additionalProperties",
+        "minProperties",
+        "maxProperties",
+        "items",
+        "minItems",
+        "maxItems",
+        "uniqueItems",
+        "minLength",
+        "maxLength",
+        "pattern",
+        "minimum",
+        "maximum",
+        "exclusiveMinimum",
+        "exclusiveMaximum",
+        "multipleOf",
+        "anyOf",
+        "oneOf",
+        "allOf",
+        "not",
+        "$ref",
+        "$defs",
+        "definitions",
+    }
+)
+ANNOTATION_KEYWORDS = frozenset(
+    {
+        "$schema",
+        "$id",
+        "$comment",
+        "title",
+        "description",
+        "default",
+        "examples",
+        "deprecated",
+        "readOnly",
+        "writeOnly",
+        "format",
+    }
+)
+SUPPORTED_KEYWORDS = VALIDATION_KEYWORDS | ANNOTATION_KEYWORDS
+JSON_TYPES = frozenset({"object", "array", "string", "integer", "number", "boolean", "null"})
+_SCHEMA_LISTS = ("anyOf", "oneOf", "allOf")
+_SCHEMA_MAPS = ("properties", "$defs", "definitions")
+_SCHEMA_VALUES = ("items", "additionalProperties", "not")
+_COUNTS = ("minProperties", "maxProperties", "minItems", "maxItems", "minLength", "maxLength")
+_NUMBERS = ("minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf")
+
+
+def _pointer(schema: Any, ref: str) -> Any:
+    """The subschema a local `$ref` (`#`, `#/$defs/name`, ...) names; KeyError when none."""
+    if ref == "#":
+        return schema
+    if not ref.startswith("#/"):
+        raise KeyError(ref)
+    node = schema
+    for raw in ref[2:].split("/"):
+        key = raw.replace("~1", "/").replace("~0", "~")
+        if isinstance(node, dict) and key in node:
+            node = node[key]
+        elif isinstance(node, list) and key.isdigit() and int(key) < len(node):
+            node = node[int(key)]
+        else:
+            raise KeyError(ref)
+    return node
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, int | float) and not isinstance(value, bool) and math.isfinite(value)
+
+
+def schema_problems(schema: Any) -> list[str]:
+    """What stops `schema` from being a response schema; empty when it can be one.
+
+    The root is an object schema (`"type": "object"`); every keyword anywhere
+    is one `SUPPORTED_KEYWORDS` lists, with a value of the right kind; every
+    `$ref` points inside the document; every `pattern` compiles.
+    """
+    if not isinstance(schema, dict):
+        return ["the schema must be a JSON object"]
+    problems: list[str] = []
+    if schema.get("type") != "object":
+        problems.append('$: the root must be an object schema ("type": "object")')
+
+    def walk(node: Any, where: str) -> None:
+        if isinstance(node, bool):
+            return
+        if not isinstance(node, dict):
+            problems.append(f"{where}: a schema must be an object or a boolean")
+            return
+        for key, value in node.items():
+            at = f"{where}.{key}"
+            if key not in SUPPORTED_KEYWORDS:
+                problems.append(f"{at}: `{key}` is not a keyword the answer check supports")
+            elif key == "type":
+                types = value if isinstance(value, list) else [value]
+                if not types or not all(t in JSON_TYPES for t in types):
+                    problems.append(f"{at}: must name JSON types ({', '.join(sorted(JSON_TYPES))})")
+            elif key == "required":
+                if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+                    problems.append(f"{at}: must be a list of property names")
+            elif key == "enum":
+                if not isinstance(value, list) or not value:
+                    problems.append(f"{at}: must be a non-empty list")
+            elif key in _COUNTS:
+                if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+                    problems.append(f"{at}: must be a whole number >= 0")
+            elif key in _NUMBERS:
+                if not _is_number(value) or (key == "multipleOf" and value <= 0):
+                    problems.append(
+                        f"{at}: must be a number" + (" > 0" if key == "multipleOf" else "")
+                    )
+            elif key == "uniqueItems":
+                if not isinstance(value, bool):
+                    problems.append(f"{at}: must be true or false")
+            elif key == "pattern":
+                try:
+                    re.compile(value)
+                except (re.error, TypeError) as exc:
+                    problems.append(f"{at}: not a regular expression ({exc})")
+            elif key == "$ref":
+                try:
+                    _pointer(schema, value if isinstance(value, str) else "")
+                except KeyError:
+                    problems.append(f"{at}: {value!r} does not point inside this schema")
+            elif key in _SCHEMA_LISTS:
+                if not isinstance(value, list) or not value:
+                    problems.append(f"{at}: must be a non-empty list of schemas")
+                else:
+                    for i, sub in enumerate(value):
+                        walk(sub, f"{at}[{i}]")
+            elif key in _SCHEMA_MAPS:
+                if not isinstance(value, dict):
+                    problems.append(f"{at}: must map names to schemas")
+                else:
+                    for name, sub in value.items():
+                        walk(sub, f"{at}.{name}")
+            elif key in _SCHEMA_VALUES:
+                if key == "items" and isinstance(value, list):
+                    problems.append(
+                        f"{at}: must be one schema (a list of schemas is not supported)"
+                    )
+                else:
+                    walk(value, at)
+
+    walk(schema, "$")
+    return problems
+
+
+# --- END SHARED RESPONSE SCHEMA RULES ---
+
+
+def read_schema(path: Path) -> tuple[dict[str, Any] | None, list[str]]:
+    """``(schema, [])`` for a file that can be the response schema, else ``(None, problems)``."""
+    try:
+        schema = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        return None, [f"not a JSON file ({exc})"]
+    problems = schema_problems(schema)
+    return (None, problems) if problems else (schema, [])
+
+
+def load_schema(path: str | Path) -> dict[str, Any]:
+    """The schema in ``path``; ``ResponseSchemaFileError`` listing every problem."""
+    schema, problems = read_schema(Path(path))
+    if schema is None:
+        raise ResponseSchemaFileError(path, problems)
+    return schema
+
+
+def schema_file(project_root: Path, agent_directory: str) -> Path:
+    """Where a project keeps its response schema."""
+    return project_root / agent_directory / SCHEMA_FILENAME
+
+
+def wiring_problems(project_root: Path, agent_directory: str) -> list[str]:
+    """What the project's ``agent.py`` lacks to answer in its response schema; empty when wired.
+
+    It builds the agent with ``response_format=response_format(model, tools)`` (else
+    every run ends with ``invalid_structured_response``) and has ``StructuredAnswer()``
+    in its middleware (else an answer that does not fit is not sent back to the model,
+    and the run ends with that error instead of the answer).
+    """
+    agent_py = f"{agent_directory}/agent.py"
+    try:
+        text = (project_root / agent_directory / "agent.py").read_text(encoding="utf-8")
+    except OSError:
+        return [f"{agent_py} cannot be read"]
+    problems = []
+    if "response_format(" not in text:
+        problems.append(
+            f"{agent_py} does not pass response_format=response_format(model, tools) to "
+            "create_agent: every run would end with invalid_structured_response"
+        )
+    if "StructuredAnswer(" not in text:
+        problems.append(
+            f"{agent_py} has no StructuredAnswer() (last) in middleware(): an answer that does "
+            "not fit would not go back to the model, and its run would end with "
+            "invalid_structured_response"
+        )
+    return problems

graph_agents_cli/_runner.py

@@ -0,0 +1,319 @@
+# 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.
+
+"""Subprocess helpers for agents CLI."""
+
+import io
+import os
+import shlex
+import subprocess
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+import click
+
+from graph_agents_cli import _tools
+
+# Set for an extension's command so any re-entry into `graph-agents-cli <cmd>` runs the
+# built-in instead of recursing back into the override.
+DISABLE_OVERRIDES_ENV = "GRAPH_AGENTS_CLI_DISABLE_OVERRIDES"
+# Exported so an extension's scripts can find sibling resources (templates etc.).
+EXTENSION_DIR_ENV = "GRAPH_AGENTS_CLI_EXTENSION_DIR"
+
+
+def redact_cmd(args: list[str]) -> str:
+    """Mask sensitive information in command arguments and return joined string.
+
+    Masks arguments like --github-pat and environment variables containing secrets.
+    """
+    redacted_cmd_list = list(args)
+    for i, arg in enumerate(args):
+        if arg == "--github-pat" and i + 1 < len(args):
+            redacted_cmd_list[i + 1] = "[REDACTED]"
+        elif any(
+            secret in arg for secret in ["GITHUB_PAT", "GH_TOKEN", "GITHUB_TOKEN", "GITHUB_APP_KEY"]
+        ):
+            redacted_cmd_list[i] = "[REDACTED]"
+
+    return shlex.join(redacted_cmd_list)
+
+
+def run(
+    args: list[str],
+    *,
+    cwd: str | Path | None = None,
+    env: dict | None = None,
+    capture: bool = False,
+    print_cmd: bool = True,
+    check: bool = True,
+    check_err_msg: str | None = None,
+    input_data: bytes | None = None,
+    timeout: int | None = None,
+    resolve_executable: bool = True,
+) -> subprocess.CompletedProcess:
+    """Run a subprocess, streaming output by default.
+
+    Args:
+        args: Command and arguments.
+        cwd: Working directory for the subprocess.
+        env: Extra environment variables. Merged with os.environ if provided.
+        capture: If True, capture stdout/stderr instead of streaming.
+            Defaults to False.
+        print_cmd: If True, print the command before executing.
+            Defaults to True.
+        check: If True, raise ClickException on non-zero exit.
+            Defaults to True.
+        check_err_msg: Error message prefix for check failures.
+        input_data: Bytes to feed to stdin of the subprocess.
+        timeout: Timeout in seconds for the subprocess.
+        resolve_executable: If True, resolve the executable path using require_tool.
+            Defaults to True.
+
+    Returns:
+        CompletedProcess instance.
+    """
+    cmd_str = redact_cmd(args)
+
+    if print_cmd:
+        click.secho(f"  ▸ {cmd_str}", fg="cyan", dim=True)
+
+    run_env = None
+    if env is not None:
+        run_env = {**os.environ, **env}
+
+    # Capture output as UTF-8 text (replacing undecodable bytes) unless we're
+    # piping raw bytes to stdin, where child output must stay bytes. Without an
+    # explicit encoding, subprocess uses the locale codec + strict errors, which
+    # raises UnicodeDecodeError on non-UTF-8 locales (e.g. cp1252 on Windows).
+    text_mode = input_data is None
+    text_kwargs = {"encoding": "utf-8", "errors": "replace"} if text_mode else {}
+
+    if capture:
+        result = run_resolved(
+            args,
+            resolve_executable=resolve_executable,
+            capture_output=True,
+            text=text_mode,
+            cwd=str(cwd) if cwd else None,
+            input=input_data,
+            env=run_env,
+            timeout=timeout,
+            **text_kwargs,
+        )
+    else:
+        # Under click.testing.CliRunner, sys.stdout is a StringIO-like object
+        # that doesn't have a fileno(). Subprocess on Windows requires a fileno.
+        # We check carefully to avoid issues with mocks or unusual environments.
+        use_fallback = True
+        if hasattr(sys.stdout, "fileno") and callable(sys.stdout.fileno):
+            try:
+                sys.stdout.fileno()
+                use_fallback = False
+            except (io.UnsupportedOperation, AttributeError, OSError):
+                pass
+
+        if not use_fallback:
+            result = run_resolved(
+                args,
+                resolve_executable=resolve_executable,
+                stdout=sys.stdout,
+                stderr=sys.stderr,
+                cwd=str(cwd) if cwd else None,
+                input=input_data,
+                env=run_env,
+                timeout=timeout,
+            )
+        else:
+            # Fallback to capture and manual emit for environments without a
+            # real stdout fileno (e.g. click.testing.CliRunner).
+            result = run_resolved(
+                args,
+                resolve_executable=resolve_executable,
+                capture_output=True,
+                text=text_mode,
+                cwd=str(cwd) if cwd else None,
+                input=input_data,
+                env=run_env,
+                timeout=timeout,
+                **text_kwargs,
+            )
+            # stdout/stderr are bytes when input_data is set (text=False).
+            for stream, content in (
+                (sys.stdout, result.stdout),
+                (sys.stderr, result.stderr),
+            ):
+                if not content:
+                    continue
+                if isinstance(content, bytes):
+                    content = content.decode(errors="replace")
+                stream.write(content)
+
+    if check and result.returncode != 0:
+        error_msg = check_err_msg or f"Command failed: {cmd_str}"
+        # When output was captured it never reached the console, so fold it into
+        # the error — otherwise the failure reason is lost. Streamed runs already
+        # printed it. stdout/stderr are bytes when input_data is set (text=False).
+        detail = ""
+        if capture:
+            captured = "\n".join(
+                part.strip()
+                for part in (result.stdout, result.stderr)
+                if isinstance(part, str) and part.strip()
+            )
+            if captured:
+                detail = f"\n{captured}"
+        raise click.ClickException(f"{error_msg} (exit code {result.returncode}){detail}")
+
+    return result
+
+
+def _looks_like_path(token: str) -> bool:
+    """A `run:` token the author wrote as a path, e.g. `scripts/run.py`."""
+    return "/" in token or os.sep in token
+
+
+def run_extension_command(
+    run_vector: Sequence[str],
+    extra_args: list[str],
+    *,
+    cwd: Path,
+    extension_root: Path,
+) -> int:
+    """Run an extension's declared `run:` vector with the user's argv appended.
+
+    Differs from `run` in ways an override needs: the vector is extension-supplied
+    and passed through verbatim (no `require_tool` resolution), the command is
+    not echoed, and the child's exit code is returned rather than raised, so the
+    override exits like the command it replaced.
+
+    Tokens that exist as paths under `extension_root` are made absolute, so a
+    vendored script is found regardless of cwd.
+    """
+    # Only tokens written as paths. Resolving every token would rewrite an
+    # ordinary argument that happens to name a file in the extension, e.g.
+    # `run: ["make", "build"]` in an extension that also ships `build/`.
+    resolved_vector = [
+        str((extension_root / tok).resolve())
+        if _looks_like_path(tok) and (extension_root / tok).exists()
+        else tok
+        for tok in run_vector
+    ]
+    result = run(
+        resolved_vector + list(extra_args),
+        cwd=cwd,
+        env={DISABLE_OVERRIDES_ENV: "1", EXTENSION_DIR_ENV: str(extension_root)},
+        print_cmd=False,
+        check=False,
+        resolve_executable=False,
+    )
+    return result.returncode
+
+
+def run_resolved(
+    args: list[str], *, resolve_executable: bool = True, **kwargs
+) -> subprocess.CompletedProcess:
+    """Wrapper around subprocess.run with optional executable resolution.
+
+    Args:
+        args: Command and arguments as a list of strings.
+        resolve_executable: If True, resolve the executable path using require_tool.
+            Defaults to True.
+        **kwargs: Additional keyword arguments passed to subprocess.run.
+
+    Raises:
+        ToolNotFoundError: If resolve_executable is True and the tool cannot be found.
+
+    Returns:
+        CompletedProcess instance.
+    """
+    if isinstance(args, str):
+        raise ValueError("args must be a list of strings, not a single string.")
+
+    if resolve_executable and args:
+        executable = args[0]
+        # Create a shallow copy to avoid modifying the original list passed by reference
+        args = args.copy()
+        args[0] = _tools.require_tool(executable)
+
+    return subprocess.run(args, **kwargs)
+
+
+def popen_resolved(
+    args: list[str], *, resolve_executable: bool = True, **kwargs
+) -> subprocess.Popen:
+    """Wrapper around subprocess.Popen with optional executable resolution.
+
+    Args:
+        args: Command and arguments as a list of strings.
+        resolve_executable: If True, resolve the executable path using require_tool.
+            Defaults to True.
+        **kwargs: Additional keyword arguments passed to subprocess.Popen.
+
+    Raises:
+        ToolNotFoundError: If resolve_executable is True and the tool cannot be found.
+
+    Returns:
+        Popen instance.
+    """
+    if isinstance(args, str):
+        raise ValueError("args must be a list of strings, not a single string.")
+
+    if resolve_executable and args:
+        executable = args[0]
+        # Create a shallow copy to avoid modifying the original list passed by reference
+        args = args.copy()
+        args[0] = _tools.require_tool(executable)
+
+    return subprocess.Popen(args, **kwargs)
+
+
+def popen_resolved_detached(
+    args: list[str], *, resolve_executable: bool = True, **kwargs
+) -> subprocess.Popen:
+    """Wrapper around subprocess.Popen for launching detached background processes.
+
+    Handles cross-platform differences for process detaching:
+    - On POSIX, sets start_new_session=True.
+    - On Windows, sets creationflags to DETACHED_PROCESS and CREATE_NEW_PROCESS_GROUP.
+    - Ensures stdin is redirected to subprocess.DEVNULL.
+
+    Args:
+        args: Command and arguments as a list of strings.
+        resolve_executable: If True, resolve the executable path using require_tool.
+            Defaults to True.
+        **kwargs: Additional keyword arguments passed to subprocess.Popen.
+
+    Raises:
+        ToolNotFoundError: If resolve_executable is True and the tool cannot be found.
+
+    Returns:
+        Popen instance.
+    """
+    stdin = kwargs.get("stdin")
+    if stdin is not None and stdin is not subprocess.DEVNULL:
+        raise ValueError("popen_resolved_detached only supports stdin=DEVNULL.")
+    kwargs["stdin"] = subprocess.DEVNULL
+
+    if os.name == "nt":
+        # Windows-specific process creation flags for detaching
+        create_new_process_group = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+        create_no_window = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+        flags = create_new_process_group | create_no_window
+        kwargs["creationflags"] = kwargs.get("creationflags", 0) | flags
+    else:
+        # POSIX way of detaching
+        kwargs["start_new_session"] = True
+
+    return popen_resolved(args, resolve_executable=resolve_executable, **kwargs)