google-agents-cli 1.7.0__tar.gz → 1.9.0__tar.gz

{google_agents_cli-1.7.0 → google_agents_cli-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.7.0
+Version: 1.9.0
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11
@@ -157,6 +157,8 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 
 </details>
 
+
+
 ## How it works
 
 <div align="center">
@@ -206,6 +208,39 @@ The best way to contribute is through feedback: bug reports, feature requests, a
 
 See the [contributing guide](CONTRIBUTING.md) for details.
 
+## Telemetry
+
+By default, `agents-cli` emits a single usage signal per command invocation to help
+improve the tool and better understand how it's used. Each signal
+is a structured log entry written to **your own Google Cloud project**:
+`GOOGLE_CLOUD_PROJECT`, or else the default project of your Application Default
+Credentials (`logName=projects/<project>/logs/agents-cli`), where you can query
+it in Cloud Logging. It records only the metadata such as command name
+(e.g. `deploy`, `scaffold.create`), exit code, error class, duration (measured
+from command dispatch to exit, so it excludes CLI startup), CLI/Python versions,
+and OS — never file contents, arguments, or other input. Commands added by
+extensions are recorded without their names.
+
+The request that writes the entry also carries usage metadata in its
+`User-Agent` and `X-Goog-Api-Client` headers, which Google receives for
+agents-cli usage analytics: the CLI and Python versions, the OS and its release,
+the CPU architecture, the command name and a random per-invocation ID. The log
+entry's contents, such as the exit code, error class and duration, stay in your
+project.
+
+To opt out of sending telemetry, use one of the following environment variables:
+
+```bash
+# our cli-specific variable
+# 0, false, no, or off (case-insensitive):
+export AGENTS_CLI_TELEMETRY=0
+
+# donottrack.sh standard variable
+export DO_NOT_TRACK=1
+```
+
+Use `agents-cli info` to see the current telemetry state.
+
 ## Terms of Service
 
 `agents-cli` leverages Google Cloud APIs. When you deploy agents, you'll be deploying resources in your own Google Cloud project and will be responsible for those resources. Please review the [Google Cloud Service Terms](https://cloud.google.com/terms/service-terms) for details.

{google_agents_cli-1.7.0 → google_agents_cli-1.9.0}/README.md

@@ -116,6 +116,8 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 
 </details>
 
+
+
 ## How it works
 
 <div align="center">
@@ -165,6 +167,39 @@ The best way to contribute is through feedback: bug reports, feature requests, a
 
 See the [contributing guide](CONTRIBUTING.md) for details.
 
+## Telemetry
+
+By default, `agents-cli` emits a single usage signal per command invocation to help
+improve the tool and better understand how it's used. Each signal
+is a structured log entry written to **your own Google Cloud project**:
+`GOOGLE_CLOUD_PROJECT`, or else the default project of your Application Default
+Credentials (`logName=projects/<project>/logs/agents-cli`), where you can query
+it in Cloud Logging. It records only the metadata such as command name
+(e.g. `deploy`, `scaffold.create`), exit code, error class, duration (measured
+from command dispatch to exit, so it excludes CLI startup), CLI/Python versions,
+and OS — never file contents, arguments, or other input. Commands added by
+extensions are recorded without their names.
+
+The request that writes the entry also carries usage metadata in its
+`User-Agent` and `X-Goog-Api-Client` headers, which Google receives for
+agents-cli usage analytics: the CLI and Python versions, the OS and its release,
+the CPU architecture, the command name and a random per-invocation ID. The log
+entry's contents, such as the exit code, error class and duration, stay in your
+project.
+
+To opt out of sending telemetry, use one of the following environment variables:
+
+```bash
+# our cli-specific variable
+# 0, false, no, or off (case-insensitive):
+export AGENTS_CLI_TELEMETRY=0
+
+# donottrack.sh standard variable
+export DO_NOT_TRACK=1
+```
+
+Use `agents-cli info` to see the current telemetry state.
+
 ## Terms of Service
 
 `agents-cli` leverages Google Cloud APIs. When you deploy agents, you'll be deploying resources in your own Google Cloud project and will be responsible for those resources. Please review the [Google Cloud Service Terms](https://cloud.google.com/terms/service-terms) for details.

{google_agents_cli-1.7.0 → google_agents_cli-1.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.7.0"
+version = "1.9.0"
 description = "Agents CLI — Agent Development Lifecycle toolchain for ADK"
 readme = "README.md"
 license = "Apache-2.0"
@@ -101,6 +101,9 @@ include = [
   "tools/**/*.py",
   # First-party extensions ship real code; lint them like the rest.
   "extensions/**/*.py",
+  # The lift report builder and the eval tools.
+  "evals/report/**/*.py",
+  "evals/tools/**/*.py",
 ]
 exclude = [
     "src/google/agents/cli/scaffold/agents",
@@ -136,6 +139,7 @@ ignore = ["E501", "C901", "RUF001", "UP036", "RUF067", "RUF069"]
 [tool.ruff.lint.flake8-tidy-imports.banned-api]
 "rich.console.Console" = { msg = "Use `google.agents.cli._output.Console` instead to ensure project-wide defaults (soft_wrap=True) are applied." }
 "agentplatform.Client" = { msg = "Use `google.agents.cli._agent_platform.AgentPlatformClient` instead, so the client retries throttled requests." }
+"agentplatform._genai" = { msg = "Private SDK module that can change without notice. Use `types` from `google.agents.cli._agent_platform_types` for SDK types." }
 
 [tool.ruff.lint.pylint]
 max-positional-args = 5

google_agents_cli-1.9.0/src/google/agents/cli/_agent_platform_types.py

@@ -0,0 +1,31 @@
+# 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.
+
+"""Agent Platform SDK types, imported through the SDK's public path.
+
+Use ``types.EvalCase``, ``types.evals.AgentEvent``, etc. from here rather than
+importing ``agentplatform._genai`` directly.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # The public `agentplatform.types` is served by an untyped module
+    # `__getattr__`, which type checkers resolve to Unknown. Point them at the
+    # module it returns so the SDK models stay type-checked.
+    from agentplatform._genai import types  # noqa: TID251
+else:
+    from agentplatform import types
+
+__all__ = ["types"]

{google_agents_cli-1.7.0 → google_agents_cli-1.9.0}/src/google/agents/cli/_click.py

@@ -24,6 +24,20 @@ import click
 
 from google.agents.cli._experiments import resolve_experiment
 
+# Key under which the dispatched subcommand chain is recorded on ``ctx.meta``
+# (root -> leaf, e.g. ``["scaffold", "create"]``). ``ctx.meta`` is shared across
+# the whole context tree, so every level appends to the same list and any
+# context can read the full path. Consumed by ``_telemetry``.
+COMMAND_PATH_META_KEY = "agents_cli.command_path"
+# Set on ``ctx.meta`` once the resolved leaf command actually runs, so a help
+# view (``--help``, or a group given no subcommand) can be told apart from a
+# run. Consumed by ``_telemetry``.
+COMMAND_INVOKED_META_KEY = "agents_cli.command_invoked"
+# Marks a recorded path segment that an extension serves: ``generate~ext`` for
+# an overridden built-in. A command an extension adds is recorded as the bare
+# marker, never by name, since the extension author chose that name.
+EXTENSION_PATH_MARKER = "~ext"
+
 
 class LazyGroup(click.Group):
     """Click group that defers importing subcommand modules until needed.
@@ -104,6 +118,33 @@ class LazyGroup(click.Group):
             self.commands[cmd_name] = cmd
         return super().get_command(ctx, cmd_name)
 
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        cmd_name, cmd, rest = super().resolve_command(ctx, args)
+        if cmd_name is not None and cmd is not None:
+            # Record the dispatched command chain on ctx.meta as Click resolves
+            # each level, so we can avoid parsing arguments later. Recorded here
+            # rather than in get_command, which also runs for lookups that
+            # aren't dispatch (e.g. listing commands for shell completion).
+            ctx.meta.setdefault(COMMAND_PATH_META_KEY, []).append(
+                self._path_segment(cmd_name)
+            )
+            _flag_invocation(cmd)
+        return cmd_name, cmd, rest
+
+    def _path_segment(self, cmd_name: str) -> str:
+        """The recorded path segment for a dispatched ``cmd_name``.
+
+        Overrides only apply to built-ins and added commands never share a
+        built-in's name, so an extension-served built-in name is an override.
+        """
+        if cmd_name not in self._overrides:
+            return cmd_name
+        if cmd_name in self._lazy_commands or cmd_name in self.commands:
+            return f"{cmd_name}{EXTENSION_PATH_MARKER}"
+        return EXTENSION_PATH_MARKER
+
     def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
         rows: list[tuple[str, str]] = []
         for name in self.list_commands(ctx):
@@ -122,6 +163,30 @@ class LazyGroup(click.Group):
                 formatter.write_dl(rows)
 
 
+def _flag_invocation(cmd: Any) -> None:
+    """Make a leaf command set ``COMMAND_INVOKED_META_KEY`` when it runs.
+
+    Click handles ``--help`` while parsing arguments and exits before calling
+    ``invoke``, so the flag stays unset for help views. Groups only dispatch,
+    so they are left alone.
+
+    This wraps ``invoke`` on the command object itself, which is shared for the
+    whole process, the same way ``patch_source_in_help`` wraps
+    ``format_epilog``. The ``_invocation_flagged`` marker keeps it idempotent.
+    """
+    if isinstance(cmd, click.Group) or getattr(cmd, "_invocation_flagged", False):
+        return
+
+    original = cmd.invoke
+
+    def _invoke(ctx: click.Context) -> Any:
+        ctx.meta[COMMAND_INVOKED_META_KEY] = True
+        return original(ctx)
+
+    cmd.invoke = _invoke
+    cmd._invocation_flagged = True
+
+
 def _source_path(cmd: Any) -> str | None:
     """Resolve the absolute file path of a command's callback module."""
     cb = cmd.callback

{google_agents_cli-1.7.0 → google_agents_cli-1.9.0}/src/google/agents/cli/_experiments.py

@@ -31,6 +31,24 @@ _REGISTRY: dict[str, Experiment] = {
 }
 
 
+# String spellings accepted for boolean experiments, e.g. '{"x": "false"}'.
+# bool("false") is True, so strings can't go through the plain type cast.
+_TRUE_STRINGS = frozenset({"1", "true", "yes", "on"})
+_FALSE_STRINGS = frozenset({"0", "false", "no", "off"})
+
+
+def _cast(exp: Experiment, val: Any) -> Any:
+    """Cast an override value to the experiment's type."""
+    if exp.value_type is bool and isinstance(val, str):
+        normalized = val.strip().lower()
+        if normalized in _TRUE_STRINGS:
+            return True
+        if normalized in _FALSE_STRINGS:
+            return False
+        raise ValueError(f"expected true/false, 1/0, yes/no or on/off, got {val!r}")
+    return exp.value_type(val)
+
+
 def resolve_experiment(label: str) -> Any:
     """Returns the value for the given experiment label."""
     if label not in _REGISTRY:
@@ -45,8 +63,7 @@ def resolve_experiment(label: str) -> Any:
             overrides = json.loads(env_val)
             if label in overrides:
                 val = overrides[label]
-                # Cast to correct type if necessary
-                return exp.value_type(val)
+                return _cast(exp, val)
         except Exception as e:
             logging.warning(
                 f"Failed to apply AGENTS_CLI_EXPERIMENTS override for '{label}', "

{google_agents_cli-1.7.0 → google_agents_cli-1.9.0}/src/google/agents/cli/_output.py

@@ -16,15 +16,11 @@
 
 import json
 import sys
-from enum import IntEnum
 from typing import Any
 
+import click
 from rich.console import Console as _RichConsole  # noqa: TID251
-
-
-class ExitCode(IntEnum):
-    OK = 0
-    ERROR = 1
+from rich.markup import escape
 
 
 class Console(_RichConsole):
@@ -40,7 +36,19 @@ def emit(data: dict) -> None:
     print(json.dumps(data), file=sys.stdout)
 
 
-def emit_error(msg: str, code: int = ExitCode.ERROR) -> None:
-    """Write error message to stderr and exit."""
-    print(json.dumps({"error": msg}), file=sys.stderr)
-    raise SystemExit(code)
+def print_error(message: str) -> None:
+    """Print an error message to stderr with a red "❌ Error:" prefix."""
+    # escape() so text like "[cyan]" or "[0]" in the message is shown as-is.
+    Console(stderr=True, highlight=False).print(
+        f"[bold red]❌ Error:[/bold red] {escape(message)}"
+    )
+
+
+def print_click_exception(e: click.ClickException) -> None:
+    """Show a ClickException like Click does, but with a red "❌ Error:" prefix."""
+    if isinstance(e, click.UsageError) and e.ctx is not None:
+        hint = ""
+        if e.ctx.command.get_help_option(e.ctx) is not None:
+            hint = f"Try '{e.ctx.command_path} {e.ctx.help_option_names[0]}' for help.\n"
+        click.echo(f"{e.ctx.get_usage()}\n{hint}", err=True, color=e.ctx.color)
+    print_error(e.format_message())

{google_agents_cli-1.7.0 → google_agents_cli-1.9.0}/src/google/agents/cli/_runner.py

@@ -14,6 +14,7 @@
 
 """Subprocess helpers for agents CLI."""
 
+import contextlib
 import io
 import os
 import shlex
@@ -222,6 +223,30 @@ def run_extension_command(
     return result.returncode
 
 
+@contextlib.contextmanager
+def _wrap_launch_errors(executable: str | None, args: list[str]):
+    """Turn a resolved tool's launch-time OSError into a ToolNotExecutableError.
+
+    On Windows, shutil.which doesn't check ACLs or security policies, so a
+    blocked tool resolves fine and only fails at launch, even with check=False.
+    Only ERROR_ACCESS_DENIED maps to PermissionError; policy blocks (e.g.
+    WinError 4551 from Application Control) surface as a plain OSError.
+    FileNotFoundError and unresolved executables (``executable is None``) keep
+    the raw error so callers' own handling still applies.
+    """
+    try:
+        yield
+    except FileNotFoundError:
+        raise
+    except (PermissionError, OSError) as e:
+        if executable is None:
+            raise
+        msg = f"'{executable}' was found at '{args[0]}' but could not be executed: {e}"
+        if _tools.is_windows():
+            msg += "\n  It may be blocked by a security policy (e.g. AppLocker, WDAC, Defender)."
+        raise _tools.ToolNotExecutableError(msg) from e
+
+
 def run_resolved(
     args: list[str], *, resolve_executable: bool = True, **kwargs
 ) -> subprocess.CompletedProcess:
@@ -235,6 +260,8 @@ def run_resolved(
 
     Raises:
         ToolNotFoundError: If resolve_executable is True and the tool cannot be found.
+        ToolNotExecutableError: If resolve_executable is True and the OS refuses
+            to execute the resolved tool.
 
     Returns:
         CompletedProcess instance.
@@ -242,13 +269,15 @@ def run_resolved(
     if isinstance(args, str):
         raise ValueError("args must be a list of strings, not a single string.")
 
+    executable = None
     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)
+    with _wrap_launch_errors(executable, args):
+        return subprocess.run(args, **kwargs)
 
 
 def popen_resolved(
@@ -264,6 +293,8 @@ def popen_resolved(
 
     Raises:
         ToolNotFoundError: If resolve_executable is True and the tool cannot be found.
+        ToolNotExecutableError: If resolve_executable is True and the OS refuses
+            to execute the resolved tool.
 
     Returns:
         Popen instance.
@@ -271,13 +302,15 @@ def popen_resolved(
     if isinstance(args, str):
         raise ValueError("args must be a list of strings, not a single string.")
 
+    executable = None
     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)
+    with _wrap_launch_errors(executable, args):
+        return subprocess.Popen(args, **kwargs)
 
 
 def popen_resolved_detached(
@@ -298,6 +331,8 @@ def popen_resolved_detached(
 
     Raises:
         ToolNotFoundError: If resolve_executable is True and the tool cannot be found.
+        ToolNotExecutableError: If resolve_executable is True and the OS refuses
+            to execute the resolved tool.
 
     Returns:
         Popen instance.