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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.6.1
+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.6.1 → 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.6.1 → google_agents_cli-1.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.6.1"
+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.6.1 → google_agents_cli-1.8.0}/src/google/agents/cli/_adk_client.py

@@ -17,8 +17,10 @@
 from __future__ import annotations
 
 import asyncio
+import enum
 import json
 import logging
+import time
 from collections.abc import (
     AsyncGenerator,
     Iterable,
@@ -36,6 +38,20 @@ _APP_INFO_TIMEOUT = 10
 DEFAULT_WS_PATH = "/run_live"
 DEFAULT_TURN_TIMEOUT = 120  # seconds to wait for a turn's turnComplete
 
+# Live sessions where the server keeps working after a turnComplete report it
+# as `interactionStatus`. IN_PROGRESS means more model output is still coming;
+# anything else (IDLE, or its deprecated REQUIRES_ACTION spelling) ends the
+# turn. UNSPECIFIED is the enum's zero value and carries no signal.
+_STATUS_IN_PROGRESS = "IN_PROGRESS"
+_STATUS_UNSPECIFIED = "INTERACTION_STATUS_UNSPECIFIED"
+# An unrecognized status still ends the turn, but gets logged.
+_STATUS_TERMINAL = frozenset({"IDLE", "REQUIRES_ACTION"})
+
+# Fallback for models that don't report interactionStatus: ADK can schedule a
+# NON_BLOCKING tool's response past the terminator, and on the wire that is
+# indistinguishable from a call that is never answered.
+DEFAULT_DEFERRED_RESPONSE_TIMEOUT = 30
+
 # /run_live transcribes it back to text, so output stays gradable.
 DEFAULT_MODALITIES = ("AUDIO",)
 
@@ -285,12 +301,21 @@ async def _stream_live_events(
                 await ws.send(json.dumps({"content": content}))
 
                 boundary = _TurnBoundary()
+                # Set once a turnComplete arrives with a tool call still open.
+                deferred_deadline: float | None = None
                 while True:
+                    if deferred_deadline is None:
+                        timeout = float(DEFAULT_TURN_TIMEOUT)
+                    else:
+                        timeout = max(0.0, deferred_deadline - time.monotonic())
                     try:
-                        raw = await asyncio.wait_for(
-                            ws.recv(), timeout=DEFAULT_TURN_TIMEOUT
-                        )
+                        raw = await asyncio.wait_for(ws.recv(), timeout=timeout)
                     except TimeoutError:
+                        if deferred_deadline is not None:
+                            # Nothing followed the provisional terminator, so it
+                            # was the real end of the turn. An ordinary ending
+                            # for a fire-and-forget tool -- not a stall.
+                            break
                         logging.warning(
                             "Turn %d: no event for %ds, giving up on the turn.",
                             turn_index,
@@ -312,8 +337,23 @@ async def _stream_live_events(
                     if event is None:
                         continue
                     yield event
-                    if boundary.is_terminal(event):
+
+                    state = boundary.classify(event)
+                    if state is _Boundary.TERMINAL:
                         break
+                    if state is _Boundary.PROVISIONAL:
+                        deferred_deadline = (
+                            time.monotonic() + DEFAULT_DEFERRED_RESPONSE_TIMEOUT
+                        )
+                    elif deferred_deadline is not None:
+                        # Only the answer extends the wait: metadata frames
+                        # routinely follow a turnComplete and would hold it open.
+                        if _event_has_function_response(event):
+                            deferred_deadline = None  # full turn budget again
+                        elif _event_has_answer_content(event):
+                            deferred_deadline = (
+                                time.monotonic() + DEFAULT_DEFERRED_RESPONSE_TIMEOUT
+                            )
 
                 yield None  # end of turn
         finally:
@@ -323,15 +363,27 @@ async def _stream_live_events(
                 pass
 
 
+class _Boundary(enum.Enum):
+    """What one event means for the end of the current logical turn."""
+
+    CONTINUE = "continue"
+    PROVISIONAL = "provisional"
+    TERMINAL = "terminal"
+
+
 class _TurnBoundary:
-    """Detect the terminal turnComplete of one logical live turn."""
+    """Detect the end of one logical live turn.
+
+    Some live models answer one prompt with several turns and report
+    ``interactionStatus``; models that omit it use the heuristic below.
+    """
 
     def __init__(self) -> None:
         self._tool_call_open = False
         self._tool_response_seen = False
 
-    def is_terminal(self, event: dict) -> bool:
-        """Feed one event; return True if it ends the current logical turn."""
+    def classify(self, event: dict) -> _Boundary:
+        """Feed one event; report what it means for the current logical turn."""
         if _event_has_function_call(event):
             # Anything spoken before the call is not the post-tool answer.
             self._tool_call_open = True
@@ -343,14 +395,33 @@ class _TurnBoundary:
             self._tool_call_open = False
             self._tool_response_seen = False
 
-        if event.get("turnComplete"):
-            if self._tool_call_open and self._tool_response_seen:
-                # Terminator for the tool round-trip; keep reading for the answer.
-                self._tool_call_open = False
-                self._tool_response_seen = False
-                return False
-            return True
-        return False
+        if not event.get("turnComplete"):
+            return _Boundary.CONTINUE
+
+        status = str(event.get("interactionStatus") or "").upper()
+        # UNSPECIFIED carries no signal, so it falls through to the heuristic
+        # below rather than being read as an authoritative end of turn.
+        if status and status != _STATUS_UNSPECIFIED:
+            if status == _STATUS_IN_PROGRESS:
+                return _Boundary.CONTINUE
+            if status not in _STATUS_TERMINAL:
+                logging.debug(
+                    "Unrecognized interactionStatus %r; ending the turn.", status
+                )
+            return _Boundary.TERMINAL
+
+        if self._tool_call_open and self._tool_response_seen:
+            # Terminator for the tool round-trip; keep reading for the answer.
+            self._tool_call_open = False
+            self._tool_response_seen = False
+            return _Boundary.CONTINUE
+        if self._tool_call_open:
+            # A terminator while the call is still unanswered. Either the
+            # response was scheduled past it and the answer is still coming,
+            # or the call is never answered and this really is the end. The
+            # two shapes are identical here, so the caller waits it out.
+            return _Boundary.PROVISIONAL
+        return _Boundary.TERMINAL
 
 
 def _decode_ws_frame(raw) -> dict | None:

{google_agents_cli-1.6.1 → 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.6.1 → 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.6.1 → google_agents_cli-1.8.0}/src/google/agents/cli/_modes.py

@@ -25,7 +25,5 @@ MODE_ADK_LIVE = "adk_live"
 # message from these, so adding a mode is one edit per set rather than one per
 # call site.
 RUN_MODES = (MODE_A2A, MODE_ADK, MODE_ADK_LIVE)
-# A local server serves ADK only, so a2a needs a --url.
-LOCAL_RUN_MODES = (MODE_ADK, MODE_ADK_LIVE)
 # eval speaks ADK only.
 EVAL_MODES = (MODE_ADK, MODE_ADK_LIVE)

{google_agents_cli-1.6.1 → 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())

{google_agents_cli-1.6.1 → google_agents_cli-1.8.0}/src/google/agents/cli/_project.py

@@ -28,6 +28,10 @@ from typing import Any
 import click
 import yaml
 
+# Fallback for manifests written before the framework key existed. Those are all
+# ADK; new projects get the value from their template.
+DEFAULT_FRAMEWORK = "google-adk"
+
 
 @dataclass
 class ProjectConfig:
@@ -41,6 +45,7 @@ class ProjectConfig:
     base_template: str = "adk"
     acli_version: str = ""
     language: str = "python"
+    framework: str = DEFAULT_FRAMEWORK
     session_type: str = "none"
     cicd_runner: str = "skip"
     agent_gateway: bool = False
@@ -80,6 +85,7 @@ class ProjectConfig:
             data.get("acli_version") or data.get("version") or cfg.acli_version
         )
         cfg.language = data.get("language", cfg.language)
+        cfg.framework = data.get("framework", cfg.framework)
 
         create_params = data.get("create_params")
         if create_params is None: