João Westerberg

This commit introduces a **new shared test suite** (`session/session_test/service_suite.go`) to **standardize testing** for various session service implementations within the **`session` module**. It **refactors existing tests** for the `database`, `inmemory`, and `vertexai` session services to utilize this common suite, reducing test code duplication. This **refactoring** significantly improves the **test infrastructure** by ensuring consistent and comprehensive validation across different session backends. The change enhances maintainability and reliability for the core session management functionality.

This commit **fixes a bug** within the **LLM streaming response aggregator** (`internal/llminternal/stream_aggregator`) where the `Close` method failed to correctly preserve and propagate critical information. Specifically, **original error codes, error messages, and the LLM's finish reason** were not consistently maintained during stream aggregation. This ensures that downstream consumers reliably receive **accurate termination details** for LLM responses, particularly in scenarios involving tool calls or unexpected stream endings. The fix is validated by new test cases and updates to existing test expectations, confirming proper preservation of these details.

This commit implements **conformance fixes** to support changes in the YAML format and progressive SSE, primarily by enhancing the **replay plugin** within the conformance testing framework. It **modifies the `LLMRecording` structure** to allow for multiple LLM responses and updates the `replay_plugin` logic to correctly retrieve and verify these. A new mechanism is introduced in `invocation_replay_state` to **track consumed recordings**, improving the accuracy and robustness of **conformance testing** for complex LLM interactions. Minor style adjustments were also made to descriptions in `internal/configurable/conformance/functions.go` and `tool/exitlooptool/tool.go`.

This commit introduces **progressive Server-Sent Events (SSE)** support to the `streamingResponseAggregator` and enables **parallel execution of function calls** within the LLM's `base_flow`. This **new capability** significantly enhances the efficiency and responsiveness of streaming interactions by allowing partial text and function call arguments to be processed as they arrive, and by executing multiple function calls concurrently. The `internal/llminternal/stream_aggregator.go` module was **refactored** to manage this progressive aggregation, while `internal/llminternal/base_flow.go` was updated to orchestrate parallel function calls via `runOneStep` and `handleFunctionCalls`. Additionally, a **bug fix** in `Genai2LLMResponse` addresses correct handling of `FinishReasonStop` with empty content, ensuring more robust response processing. Extensive **testing** was added to validate these new features, including replay tests for parallel function calls across various Gemini models.

This commit introduces a **new capability** by registering an `ExampleTool` factory within the `configurable` system, allowing for dynamic creation and integration of this new tool. It also **enhances the `LLM Agent`'s instruction generation** for agent transfers, specifically by modifying how existing parts of the prompt are updated and including formatted target names. The work includes **refactoring** within the `replay plugin` to adjust error handling and remove unnecessary delays. A significant portion of this commit involves **updating numerous HTTP replay test data files** across various `agent` and `tool` modules to align with the revised system instructions and tool definitions, ensuring the test suite remains consistent with the updated LLM prompt structures.

This commit introduces a **new capability** by adding a configurable `pathPrefix` to the **API launcher**, enabling custom routing paths for the API. The `cmd/launcher/web/api/api.go` module now supports normalizing leading and trailing slashes for this prefix, enhancing flexibility in **API endpoint configuration**. Concurrently, the `cmd/launcher/web/web.go` module receives a **fix** to correctly iterate and set up only active sub-launchers, improving the robustness of the web launcher's initialization. This work provides greater control over **API routing** and refines the overall launcher architecture.

This commit introduces a **new feature** by adding `RunOption` types to the **`runner` module**, most notably the `WithStateDelta` option, to enhance state management during execution. The `Run` and `appendMessageToSession` methods in `runner/runner.go` are modified to accept and process these new options, allowing for dynamic state adjustments. Furthermore, the `RunSSEHandler` in `server/adkrest/controllers/runtime.go` is updated to incorporate `runner.WithStateDelta`, enabling the passing of **state deltas from incoming requests** directly to the runner. This significantly improves the flexibility of the **runner's execution context**, allowing external systems to influence its state dynamically.

This commit primarily delivers a **feature enhancement** for the **Gemini tool** and improves the **formatting of tool names** within LLM outputs. The `geminitool` now accepts a **custom description** during its instantiation, providing greater flexibility, with `RegisterToolFactory` updated to pass this new argument. Concurrently, the `internal/llminternal/contents_processor` module has been refined to display tool names in generated function call and response messages using backticks, significantly enhancing readability. This work also includes a minor formatting adjustment for the `exit_loop` tool's description and comprehensive test updates to align with these changes. The overall impact is a more adaptable `geminitool` and clearer, more consistent presentation of tool interactions.

This commit performs a **refactoring** and **maintenance** task by ensuring the `ArtifactDelta` field within `session.EventActions` is consistently initialized to an empty map. This change primarily affects the **event handling and callback mechanisms** across the `agent`, `internal/context`, `internal/llminternal`, and `session` modules, preventing potential nil pointer issues when accessing artifact change tracking data. Specifically, `ArtifactDelta` is now initialized during event creation via `session.NewEvent` and within various callback context and agent flow functions like `NewCallbackContext` and `runBeforeAgentCallbacks`. Numerous **unit tests** across the system have been updated to correctly reflect this new initialization behavior, ensuring robust handling of artifact deltas.

This commit introduces a **new capability** by adding an **example tool** within the `tool/exampletool` module, designed to enhance LLM requests. This tool dynamically injects few-shot examples as system instructions into the LLM prompt, improving the model's contextual understanding and response quality. It incorporates crucial **sanitization logic** for boundary tags like "End few-shot" to prevent prompt manipulation. Comprehensive unit tests in `tool/exampletool/tool_test.go` validate its functionality across various scenarios, including different model types and example formats, ensuring robust and reliable operation.

This commit introduces a **new `replayPlugin`** within the **ADK conformance framework**, designed to enable deterministic replay of recorded LLM and tool interactions. The plugin, implemented primarily in `replay_plugin.go`, intercepts ADK callbacks such as `beforeModel` and `beforeTool` to mock responses using pre-defined `LLMRecording` and `ToolRecording` data structures. This **new capability** significantly enhances **conformance testing** by providing a reliable mechanism to validate agent logic against fixed interaction sequences, improving test stability and debugging efficiency. It also includes utilities in `yaml_utils.go` to normalize "Python-isms" in recorded data, ensuring seamless unmarshaling and broader compatibility for the replay process.

This commit **introduces a new configurable agent system** and an **ADK CLI initializer**, enabling the definition and loading of agents, tools, and callbacks directly from YAML configurations. It establishes the `internal/configurable` package with utilities for registering and resolving these components, alongside conformance examples for various functions and callbacks. The new `cmd/internal/adkcli/main.go` provides a CLI entry point to scan for `root_agent.yaml` files and launch agents, significantly enhancing the **Agent Development Kit's (ADK) initialization and configurability** for testing and deployment.

This commit introduces a **feature enhancement** to the **`model/gemini` package** by integrating an `http.RoundTripper` to merge additional header values into outgoing requests. Concurrently, it implements a **defensive programming fix** within the `NewModel` constructor, ensuring that the provided `http.Client` configuration is copied to prevent unintended mutation of the original client. This change significantly improves the **flexibility of API request customization** for the Gemini model and enhances **client configuration stability**, verified by new comprehensive test cases.

This commit **enhances the data models** for `LLMResponse` and `adkrest` events to include previously missing fields. Specifically, a **new `ModelVersion` field** is added to the `model.LLMResponse` struct, which is now populated from `genai` responses via `internal/llminternal/converters/converters.go`, providing more granular model information. Concurrently, the **`server/adkrest/internal/models` event data model** is expanded with additional fields, and a custom `MarshalJSON` method is introduced to correctly handle `genai.FunctionCall` arguments. This **feature enhancement** improves data fidelity and compatibility across the system, particularly for LLM responses and event logging within the `adkrest` module, with corresponding **test cases** updated to reflect these model changes.

This commit **refactors** the **`SequentialAgent`** within the `agent/workflowagents` subsystem by **removing its direct dependency on `LoopAgent`**. This significant architectural change simplifies the `SequentialAgent`'s internal structure and execution model, promoting greater independence. The creation logic for `New` has been reimplemented, and a new `Run` method is introduced to enable direct sequential execution, streamlining how sequential workflows are managed. This work enhances the modularity and maintainability of the agent system by reducing inter-agent coupling.

This commit primarily **fixes race conditions and deadlocks** within the **parallel agent** and **session management** subsystems. It introduces **thread-safe event appending and state updates** in `InMemorySession` by adding mutexes and cloning data, while also modifying the `All` method in `session/database/session.go` to prevent deadlocks. These changes ensure proper synchronization between sub-agents and the main runner, centralizing concurrency management and preventing data corruption. New tests, including `TestParallelAgent_StateSync` and a deadlock test for `AppendEvent`, have been added to validate these concurrency fixes. This significantly improves the **stability and reliability** of concurrent operations and parallel agent execution.

This commit introduces a **new `functioncallmodifier` plugin** to enhance the **LLM agent's ability to dynamically manage and process function calls**. This **new capability** allows the system to **modify function call declarations before model invocation** and then **extract specific arguments to the session state after the model's response**. To support this, the `internal/llminternal/base_flow.go` module was updated to populate function call IDs in LLM responses, ensuring proper integration. The plugin is thoroughly covered by **new unit and integration tests**, with related test infrastructure refactored to use a shared Gemini client configuration utility.

This commit provides a **bug fix** to ensure **temporary state deltas** are correctly applied to the **local session state** within an invocation, preventing inconsistencies and potential panics. Specifically, the `session` module's `appendEvent` and `updateSessionState` methods across `database`, `inmemory`, and `vertexai` implementations were modified to apply these deltas locally while trimming them before persistence in the event history. This reordering and explicit handling of temporary state ensures that agents, such as the `loopagent`, operate with the most current session data. A nil check was also added in `agent/workflowagents/loopagent/agent.go` as a defensive measure. New tests were added to verify this behavior across different session types, significantly improving overall **session management reliability**.

This commit introduces a **new feature** to enable **human-in-the-loop confirmation** for actions performed by **MCP toolsets**. It integrates confirmation logic into the `Run` method of `tool/functiontool/function.go`, allowing tools to request user approval based on either static configuration flags or dynamic `RequireConfirmationProvider` implementations defined within `tool/mcptoolset/set.go`. This enhancement provides greater **safety and control** by requiring explicit user consent before sensitive operations are executed by **MCP tools**. The change includes comprehensive test cases and new HTTP recording data to validate various confirmation scenarios.

This commit **fixes a bug** where the `InvocationID` was incorrectly replaced or lost when an `InvocationContext` was duplicated or updated. The core change modifies the `internal/context` package, ensuring `NewInvocationContext` preserves an existing `InvocationID` and the `InvocationID` accessor uses the stored parameter. This fix propagates the correct `InvocationID` within the **LLM agent's** `run` method, the **parallel agent's** sub-agent context creation, and the **runner's** context updates during message appending. The change guarantees consistent invocation tracking across various agent and runner operations, significantly improving traceability and debugging.