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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.7.0
+Version: 1.8.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,42 @@ The best way to contribute is through feedback: bug reports, feature requests, a
 
 See the [contributing guide](CONTRIBUTING.md) for details.
 
+## Telemetry
+
+> **Note:** Telemetry is experimental and off by default. It only runs when
+> enabled with `AGENTS_CLI_EXPERIMENTS='{"cli_telemetry": true}'`.
+
+`agents-cli` can emit 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.8.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,42 @@ The best way to contribute is through feedback: bug reports, feature requests, a
 
 See the [contributing guide](CONTRIBUTING.md) for details.
 
+## Telemetry
+
+> **Note:** Telemetry is experimental and off by default. It only runs when
+> enabled with `AGENTS_CLI_EXPERIMENTS='{"cli_telemetry": true}'`.
+
+`agents-cli` can emit 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.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.7.0"
+version = "1.8.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",

{google_agents_cli-1.7.0 → google_agents_cli-1.8.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.8.0}/src/google/agents/cli/_experiments.py

@@ -28,9 +28,30 @@ class Experiment(NamedTuple):
 _REGISTRY: dict[str, Experiment] = {
     # Hides the `build` command until Go (compiled-language) support launches.
     "build_command": Experiment("build_command", bool, True),
+    # Gates CLI usage telemetry (see _telemetry.py). Off by default
+    # during validation. Users can opt out via DO_NOT_TRACK / AGENTS_CLI_TELEMETRY.
+    "cli_telemetry": Experiment("cli_telemetry", bool, False),
 }
 
 
+# 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 +66,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.8.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())