@softactivate/adk 1.1.0 → 1.2.0

package/dist/esm/utils/streaming_utils.js

@@ -12,15 +12,8 @@ import { JSONPath } from "jsonpath-plus";
 import { generateClientFunctionCallId } from "../agents/functions.js";
 import { FeatureName, isFeatureEnabled } from "../features/feature_registry.js";
 import { createLlmResponse } from "../models/llm_response.js";
-class StreamingResponseAggregator {
-  constructor(isProgressiveMode = isFeatureEnabled(
-    FeatureName.PROGRESSIVE_SSE_STREAMING
-  )) {
-    this.isProgressiveMode = isProgressiveMode;
-    // For non-progressive SSE streaming mode
-    this.text = "";
-    this.thoughtText = "";
-    // For progressive SSE streaming mode: accumulate parts in order
+class ProgressiveStrategy {
+  constructor() {
     this.partsSequence = [];
     this.currentTextBuffer = "";
     this.currentFcArgs = {};
@@ -147,11 +140,6 @@ class StreamingResponseAggregator {
     if (!fc) {
       return;
     }
-    if (part.thoughtSignature) {
-      this.lastThoughtSignature = part.thoughtSignature;
-    } else if (this.lastThoughtSignature) {
-      part.thoughtSignature = this.lastThoughtSignature.toString();
-    }
     if (fc.partialArgs || fc.willContinue) {
       if (!fc.id && !this.currentFcId) {
         fc.id = generateClientFunctionCallId();
@@ -170,108 +158,102 @@ class StreamingResponseAggregator {
       }
     }
   }
-  async *processResponse(response) {
-    var _a, _b, _c;
-    this.response = response;
-    const llmResponse = createLlmResponse(response);
-    this.usageMetadata = llmResponse.usageMetadata;
-    if (llmResponse.groundingMetadata) {
-      this.groundingMetadata = llmResponse.groundingMetadata;
-    }
-    if (llmResponse.citationMetadata) {
-      this.citationMetadata = llmResponse.citationMetadata;
-    }
-    if (llmResponse.finishReason) {
-      this.finishReason = llmResponse.finishReason;
-    }
+  async *processResponse(llmResponse) {
+    var _a;
     if (llmResponse.content && llmResponse.content.parts) {
       for (const part of llmResponse.content.parts) {
-        if (part.thoughtSignature) {
-          this.lastThoughtSignature = part.thoughtSignature;
-        } else if (part.functionCall && this.lastThoughtSignature) {
-          part.thoughtSignature = this.lastThoughtSignature.toString();
+        if (part.text) {
+          const isThought = (_a = part.thought) != null ? _a : false;
+          if (this.currentTextBuffer && isThought !== this.currentTextIsThought) {
+            this.flushTextBufferToSequence();
+          }
+          if (!this.currentTextBuffer) {
+            this.currentTextIsThought = isThought;
+          }
+          this.currentTextBuffer += part.text;
+        } else if (part.functionCall) {
+          this.processFunctionCallPart(part);
+        } else {
+          this.flushTextBufferToSequence();
+          this.partsSequence.push(part);
         }
       }
     }
-    if (this.isProgressiveMode) {
-      if (llmResponse.content && llmResponse.content.parts) {
-        for (const part of llmResponse.content.parts) {
-          if (part.text) {
-            const isThought = (_a = part.thought) != null ? _a : false;
-            if (this.currentTextBuffer && isThought !== this.currentTextIsThought) {
-              this.flushTextBufferToSequence();
-            }
-            if (!this.currentTextBuffer) {
-              this.currentTextIsThought = isThought;
-            }
-            this.currentTextBuffer += part.text;
-          } else if (part.functionCall) {
-            this.processFunctionCallPart(part);
+    llmResponse.partial = true;
+    yield llmResponse;
+  }
+  close() {
+    this.flushTextBufferToSequence();
+    this.flushFunctionCallToSequence();
+    const finalParts = this.partsSequence;
+    if (finalParts.length === 0) {
+      return void 0;
+    }
+    return finalParts;
+  }
+}
+class NonProgressiveStrategy {
+  constructor() {
+    this.text = "";
+    this.thoughtText = "";
+  }
+  async *processResponse(llmResponse) {
+    var _a;
+    if ((_a = llmResponse.content) == null ? void 0 : _a.parts) {
+      const nonTextParts = [];
+      let sawTextPart = false;
+      for (const part of llmResponse.content.parts) {
+        if (typeof part.text === "string") {
+          sawTextPart = true;
+          if (part.thought) {
+            this.thoughtText += part.text;
           } else {
-            this.flushTextBufferToSequence();
-            this.partsSequence.push(part);
+            this.text += part.text;
           }
+          continue;
         }
+        if (part.functionCall && !part.functionCall.id) {
+          part.functionCall.id = generateClientFunctionCallId();
+        }
+        nonTextParts.push(part);
       }
-      llmResponse.partial = true;
-      yield llmResponse;
-      return;
-    }
-    if (llmResponse.content && llmResponse.content.parts && typeof ((_b = llmResponse.content.parts[0]) == null ? void 0 : _b.text) === "string") {
-      const part0 = llmResponse.content.parts[0];
-      const partText = part0.text || "";
-      if (part0.thought) {
-        this.thoughtText += partText;
-      } else {
-        this.text += partText;
-      }
-      llmResponse.partial = true;
-    } else if ((this.thoughtText || this.text) && (!llmResponse.content || !llmResponse.content.parts || !((_c = llmResponse.content.parts[0]) == null ? void 0 : _c.inlineData))) {
-      const parts = [];
-      if (this.thoughtText) {
-        parts.push({ text: this.thoughtText, thought: true });
+      if (nonTextParts.length > 0) {
+        if (this.thoughtText || this.text) {
+          const parts = [];
+          if (this.thoughtText) {
+            parts.push({ text: this.thoughtText, thought: true });
+          }
+          if (this.text) {
+            parts.push({ text: this.text });
+          }
+          yield {
+            content: {
+              role: "model",
+              parts
+            },
+            usageMetadata: llmResponse.usageMetadata,
+            partial: false
+          };
+          this.thoughtText = "";
+          this.text = "";
+        }
+        yield {
+          ...llmResponse,
+          content: {
+            role: llmResponse.content.role,
+            parts: nonTextParts
+          },
+          partial: false
+        };
+        return;
       }
-      if (this.text) {
-        parts.push({ text: this.text });
+      if (sawTextPart) {
+        llmResponse.partial = true;
       }
-      yield {
-        content: {
-          role: "model",
-          parts
-        },
-        usageMetadata: llmResponse.usageMetadata,
-        partial: false
-      };
-      this.thoughtText = "";
-      this.text = "";
     }
     yield llmResponse;
   }
   close() {
-    var _a, _b, _c, _d, _e, _f;
-    if (this.isProgressiveMode) {
-      this.flushTextBufferToSequence();
-      this.flushFunctionCallToSequence();
-      const finalParts = this.partsSequence;
-      if (finalParts.length === 0) {
-        return;
-      }
-      const candidate = (_b = (_a = this.response) == null ? void 0 : _a.candidates) == null ? void 0 : _b[0];
-      const finishReason = (_c = this.finishReason) != null ? _c : candidate == null ? void 0 : candidate.finishReason;
-      return {
-        content: {
-          role: "model",
-          parts: finalParts
-        },
-        groundingMetadata: this.groundingMetadata,
-        citationMetadata: this.citationMetadata,
-        errorCode: finishReason === FinishReason.STOP ? void 0 : finishReason,
-        errorMessage: finishReason === FinishReason.STOP ? void 0 : candidate == null ? void 0 : candidate.finishMessage,
-        usageMetadata: this.usageMetadata,
-        finishReason,
-        partial: false
-      };
-    }
     if (this.text || this.thoughtText) {
       const parts = [];
       if (this.thoughtText) {
@@ -280,25 +262,91 @@ class StreamingResponseAggregator {
       if (this.text) {
         parts.push({ text: this.text });
       }
-      const candidate = (_e = (_d = this.response) == null ? void 0 : _d.candidates) == null ? void 0 : _e[0];
-      const finishReason = (_f = this.finishReason) != null ? _f : candidate == null ? void 0 : candidate.finishReason;
-      return {
-        content: {
-          role: "model",
-          parts
-        },
-        groundingMetadata: this.groundingMetadata,
-        citationMetadata: this.citationMetadata,
-        errorCode: finishReason === FinishReason.STOP ? void 0 : finishReason,
-        errorMessage: finishReason === FinishReason.STOP ? void 0 : candidate == null ? void 0 : candidate.finishMessage,
-        usageMetadata: this.usageMetadata,
-        finishReason,
-        partial: false
-      };
+      return parts;
     }
     return void 0;
   }
 }
+class StreamingResponseAggregator {
+  constructor(isProgressiveMode = isFeatureEnabled(
+    FeatureName.PROGRESSIVE_SSE_STREAMING
+  )) {
+    this.isProgressiveMode = isProgressiveMode;
+    this.lastThoughtSignature = {};
+    this.sawFunctionCall = false;
+    this.strategy = this.isProgressiveMode ? new ProgressiveStrategy() : new NonProgressiveStrategy();
+  }
+  async *processResponse(response) {
+    var _a, _b;
+    const llmResponse = createLlmResponse(response);
+    const parts = (_b = (_a = llmResponse.content) == null ? void 0 : _a.parts) != null ? _b : [];
+    if (parts.some((part) => part.functionCall)) {
+      this.sawFunctionCall = true;
+    }
+    if (this.sawFunctionCall && llmResponse.finishReason === FinishReason.STOP && parts.length > 0 && parts.every(isEmptyContentPart)) {
+      if (llmResponse.usageMetadata) {
+        this.usageMetadata = llmResponse.usageMetadata;
+      }
+      if (llmResponse.groundingMetadata) {
+        this.groundingMetadata = llmResponse.groundingMetadata;
+      }
+      if (llmResponse.citationMetadata) {
+        this.citationMetadata = llmResponse.citationMetadata;
+      }
+      if (llmResponse.finishReason) {
+        this.finishReason = llmResponse.finishReason;
+      }
+      return;
+    }
+    this.response = response;
+    this.usageMetadata = llmResponse.usageMetadata;
+    if (llmResponse.groundingMetadata) {
+      this.groundingMetadata = llmResponse.groundingMetadata;
+    }
+    if (llmResponse.citationMetadata) {
+      this.citationMetadata = llmResponse.citationMetadata;
+    }
+    if (llmResponse.finishReason) {
+      this.finishReason = llmResponse.finishReason;
+    }
+    if (llmResponse.content && llmResponse.content.parts) {
+      for (const part of llmResponse.content.parts) {
+        if (part.thoughtSignature) {
+          this.lastThoughtSignature.value = part.thoughtSignature;
+        } else if (part.functionCall && this.lastThoughtSignature.value) {
+          part.thoughtSignature = this.lastThoughtSignature.value.toString();
+        }
+      }
+    }
+    yield* this.strategy.processResponse(llmResponse);
+  }
+  close() {
+    var _a, _b, _c;
+    const finalParts = this.strategy.close();
+    if (!finalParts) {
+      return void 0;
+    }
+    const candidate = (_b = (_a = this.response) == null ? void 0 : _a.candidates) == null ? void 0 : _b[0];
+    const finishReason = (_c = this.finishReason) != null ? _c : candidate == null ? void 0 : candidate.finishReason;
+    return {
+      content: {
+        role: "model",
+        parts: finalParts
+      },
+      groundingMetadata: this.groundingMetadata,
+      citationMetadata: this.citationMetadata,
+      errorCode: finishReason === FinishReason.STOP ? void 0 : finishReason,
+      errorMessage: finishReason === FinishReason.STOP ? void 0 : candidate == null ? void 0 : candidate.finishMessage,
+      usageMetadata: this.usageMetadata,
+      finishReason,
+      partial: false
+    };
+  }
+}
+function isEmptyContentPart(part) {
+  return !part.functionCall && !part.functionResponse && !part.fileData && !part.inlineData && !part.executableCode && !part.codeExecutionResult && (!part.text || part.text === "");
+}
 export {
-  StreamingResponseAggregator
+  StreamingResponseAggregator,
+  isEmptyContentPart
 };

package/dist/esm/utils/vertex_ai_utils.js

@@ -0,0 +1,22 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { getBooleanEnvVar } from "./env_aware_utils.js";
+function getExpressModeApiKey(project, location, expressModeApiKey) {
+  if ((project || location) && expressModeApiKey) {
+    throw new Error(
+      "Cannot specify project or location and expressModeApiKey. Either use project and location, or just the expressModeApiKey."
+    );
+  }
+  if (getBooleanEnvVar("GOOGLE_GENAI_USE_VERTEXAI")) {
+    return expressModeApiKey || process.env.GOOGLE_API_KEY;
+  }
+  return void 0;
+}
+export {
+  getExpressModeApiKey
+};

package/dist/esm/version.js

@@ -5,7 +5,7 @@ const require = topLevelCreateRequire(import.meta.url);
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-const version = "1.1.0";
+const version = "1.2.0";
 export {
   version
 };

package/dist/types/a2a/a2a_remote_agent.d.ts

@@ -16,11 +16,25 @@ export type A2AStreamEventData = Message | Task | TaskStatusUpdateEvent | TaskAr
 /**
  * Callback called before sending a request to the remote agent.
  * Allows modifying the request parameters.
+ *
+ * @param ctx - The current invocation context, providing access to session
+ *   state, agent metadata, and services.
+ * @param params - The A2A message send parameters that will be sent to the
+ *   remote agent. Mutations to this object are reflected in the outgoing
+ *   request.
+ * @returns A Promise or void. Returning a rejected Promise aborts the request.
  */
 export type BeforeA2ARequestCallback = (ctx: InvocationContext, params: MessageSendParams) => Promise<void> | void;
 /**
  * Callback called after receiving a response from the remote agent.
  * Allows inspecting or modifying the response.
+ *
+ * @param ctx - The current invocation context, providing access to session
+ *   state, agent metadata, and services.
+ * @param resp - The raw A2A stream event data received from the remote agent,
+ *   before conversion to an ADK event.
+ * @returns A Promise or void. Returning a rejected Promise stops further
+ *   processing of the response.
  */
 export type AfterA2ARequestCallback = (ctx: InvocationContext, resp: A2AStreamEventData) => Promise<void> | void;
 /**

package/dist/types/agents/processors/base_llm_processor.d.ts

@@ -8,20 +8,28 @@ import { LlmRequest } from '../../models/llm_request.js';
 import { LlmResponse } from '../../models/llm_response.js';
 import { InvocationContext } from '../invocation_context.js';
 /**
- * Base class for LLM request processor.
+ * Base class for LLM request processors. Implementations mutate or augment
+ * the {@link LlmRequest} before it is sent to the model.
  */
 export declare abstract class BaseLlmRequestProcessor {
     /**
-     * Runs the processor.
+     * Runs the processor, optionally yielding intermediate {@link Event}s.
+     *
+     * @param invocationContext - The current invocation context.
+     * @param llmRequest - The request object to populate or mutate in place.
      */
     abstract runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
 }
 /**
- * Base class for LLM response processor.
+ * Base class for LLM response processors. Implementations inspect or
+ * transform the {@link LlmResponse} after it is received from the model.
  */
 export declare abstract class BaseLlmResponseProcessor {
     /**
-     * Processes the LLM response.
+     * Runs the processor, optionally yielding intermediate {@link Event}s.
+     *
+     * @param invocationContext - The current invocation context.
+     * @param llmResponse - The response received from the model.
      */
     abstract runAsync(invocationContext: InvocationContext, llmResponse: LlmResponse): AsyncGenerator<Event, void, void>;
 }

package/dist/types/agents/processors/basic_llm_request_processor.d.ts

@@ -7,6 +7,11 @@ import { Event } from '../../events/event.js';
 import { LlmRequest } from '../../models/llm_request.js';
 import { InvocationContext } from '../invocation_context.js';
 import { BaseLlmRequestProcessor } from './base_llm_processor.js';
+/**
+ * Populates the {@link LlmRequest} with model configuration derived from the
+ * agent, including the model name, generation config, output schema, and live
+ * connect settings.
+ */
 export declare class BasicLlmRequestProcessor extends BaseLlmRequestProcessor {
     runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
 }

package/dist/types/agents/processors/identity_llm_request_processor.d.ts

@@ -7,6 +7,10 @@ import { Event } from '../../events/event.js';
 import { LlmRequest } from '../../models/llm_request.js';
 import { InvocationContext } from '../invocation_context.js';
 import { BaseLlmRequestProcessor } from './base_llm_processor.js';
+/**
+ * Appends identity instructions to the {@link LlmRequest} system prompt,
+ * informing the model of the agent's name and description.
+ */
 export declare class IdentityLlmRequestProcessor extends BaseLlmRequestProcessor {
     runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, undefined>;
 }

package/dist/types/agents/processors/request_confirmation_llm_request_processor.d.ts

@@ -6,6 +6,11 @@
 import { Event } from '../../events/event.js';
 import { InvocationContext } from '../invocation_context.js';
 import { BaseLlmRequestProcessor } from './base_llm_processor.js';
+/**
+ * Resumes tool calls that were paused for user confirmation. Scans the session
+ * event history for pending confirmation responses and re-invokes the
+ * corresponding tools before the next LLM turn.
+ */
 export declare class RequestConfirmationLlmRequestProcessor extends BaseLlmRequestProcessor {
     /** Handles tool confirmation information to build the LLM request. */
     runAsync(invocationContext: InvocationContext): AsyncGenerator<Event, void, void>;

package/dist/types/agents/run_config.d.ts

@@ -78,6 +78,21 @@ export interface RunConfig {
      */
     pauseOnToolCalls?: boolean;
 }
+/**
+ * Creates a {@link RunConfig} with production-safe defaults.
+ *
+ * Default values applied when the corresponding field is absent from `params`:
+ * - `saveInputBlobsAsArtifacts` → `false`
+ * - `supportCfc` → `false`
+ * - `enableAffectiveDialog` → `false`
+ * - `streamingMode` → {@link StreamingMode.NONE}
+ * - `maxLlmCalls` → `500` (validated via `validateMaxLlmCalls`)
+ * - `pauseOnToolCalls` → `false`
+ *
+ * @param params - Optional partial {@link RunConfig} overriding defaults.
+ * @returns A merged {@link RunConfig} object.
+ * @throws {Error} When `params.maxLlmCalls` exceeds `Number.MAX_SAFE_INTEGER`.
+ */
 export declare function createRunConfig(params?: Partial<RunConfig>): {
     speechConfig?: SpeechConfig | undefined;
     responseModalities?: Modality[] | undefined;

package/dist/types/code_executors/agent_engine_sandbox_code_executor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Client } from '@google-cloud/vertexai';
+import { BaseCodeExecutor, ExecuteCodeParams } from './base_code_executor.js';
+import { CodeExecutionResult } from './code_execution_utils.js';
+/**
+ * Options for AgentEngineSandboxCodeExecutor.
+ */
+export interface AgentEngineSandboxCodeExecutorOptions {
+    /**
+     * If set, load the existing resource name of the code execution sandbox.
+     * Format: projects/123/locations/us-central1/reasoningEngines/456/sandboxEnvironments/789
+     */
+    sandboxResourceName?: string;
+    /**
+     * The resource name of the agent engine to use to create the code execution sandbox.
+     * Format: projects/123/locations/us-central1/reasoningEngines/456
+     */
+    agentEngineResourceName?: string;
+    /**
+     * Project ID to use. If not provided, read from GOOGLE_CLOUD_PROJECT env var.
+     */
+    projectId?: string;
+    /**
+     * Location to use. If not provided, read from GOOGLE_CLOUD_LOCATION env var or default to 'us-central1'.
+     */
+    location?: string;
+    /**
+     * Optional client instance to use. If not provided, a new one will be created.
+     * Primarily for testing.
+     */
+    client?: Client;
+}
+/**
+ * A code executor that uses Agent Engine Code Execution Sandbox to execute code.
+ */
+export declare class AgentEngineSandboxCodeExecutor extends BaseCodeExecutor {
+    sandboxResourceName?: string;
+    agentEngineResourceName?: string;
+    private projectId?;
+    private location?;
+    private client;
+    private agentEngineCreationPromise?;
+    constructor(options?: AgentEngineSandboxCodeExecutorOptions);
+    executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult>;
+    private getOrCreateAgentEngine;
+    private getOrCreateSandbox;
+}

package/dist/types/common.d.ts

@@ -73,6 +73,8 @@ export type { Example } from './examples/example.js';
 export type { BaseMemoryService, SearchMemoryRequest, SearchMemoryResponse, } from './memory/base_memory_service.js';
 export { InMemoryMemoryService } from './memory/in_memory_memory_service.js';
 export type { MemoryEntry } from './memory/memory_entry.js';
+export { VertexAiMemoryBankService } from './memory/vertex_ai_memory_bank_service.js';
+export type { VertexAiMemoryBankServiceOptions } from './memory/vertex_ai_memory_bank_service.js';
 export { ApigeeLlm } from './models/apigee_llm.js';
 export type { ApigeeLlmParams } from './models/apigee_llm.js';
 export { BaseLlm, isBaseLlm } from './models/base_llm.js';

package/dist/types/events/event_actions.d.ts

@@ -58,17 +58,35 @@ export interface EventActions {
     };
 }
 /**
- * Creates an EventActions object.
+ * Creates an {@link EventActions} object with default empty-dict values for
+ * all dictionary fields.
+ *
+ * @param state - Optional partial {@link EventActions} whose properties
+ *   override the defaults. Dictionary fields (`stateDelta`, `artifactDelta`,
+ *   `requestedAuthConfigs`, `requestedToolConfirmations`) default to `{}`;
+ *   scalar fields (`skipSummarization`, `transferToAgent`, `escalate`) default
+ *   to `undefined`.
+ * @returns A fully populated {@link EventActions} object.
  */
 export declare function createEventActions(state?: Partial<EventActions>): EventActions;
 /**
- * Merges a list of EventActions objects into a single EventActions object.
+ * Merges a list of {@link EventActions} objects into a single
+ * {@link EventActions} object.
  *
- * 1. It merges dictionaries (stateDelta, artifactDelta, requestedAuthConfigs)
- * by adding all the properties from each source.
+ * Merge semantics:
+ * 1. **Dictionary fields** (`stateDelta`, `artifactDelta`,
+ *    `requestedAuthConfigs`, `requestedToolConfirmations`) — all entries from
+ *    every source are combined via `Object.assign`. Later sources win on
+ *    duplicate keys.
+ * 2. **Scalar fields** (`skipSummarization`, `transferToAgent`, `escalate`) —
+ *    last-writer-wins: the value from the last source that sets the field is
+ *    kept.
  *
- * 2. For other properties (skipSummarization,transferToAgent, escalate), the
- * last one wins.
+ * @param sources - Ordered list of partial {@link EventActions} to merge.
+ *   Falsy entries are silently skipped.
+ * @param target - Optional base {@link EventActions} to merge into. When
+ *   provided it is used as the starting state before applying `sources`.
+ * @returns A new {@link EventActions} containing the merged result.
  */
 export declare function mergeEventActions(sources: Array<Partial<EventActions>>, target?: EventActions): EventActions;
 export {};

package/dist/types/events/structured_events.d.ts

@@ -7,17 +7,30 @@ import { CodeExecutionResult, ExecutableCode, FunctionCall, FunctionResponse } f
 import { Event } from './event.js';
 /**
  * The types of events that can be parsed from a raw Event.
+ *
+ * Each value corresponds to one category of structured output that
+ * {@link toStructuredEvents} may produce from a raw {@link Event}.
  */
 export declare enum EventType {
+    /** A reasoning trace (thought) emitted by the model. */
     THOUGHT = "thought",
+    /** A text delta intended for the end user. */
     CONTENT = "content",
+    /** A request from the model to execute a tool (function call). */
     TOOL_CALL = "tool_call",
+    /** The result returned by a tool execution (function response). */
     TOOL_RESULT = "tool_result",
+    /** A request from the model to execute code. */
     CALL_CODE = "call_code",
+    /** The result of a code execution. */
     CODE_RESULT = "code_result",
+    /** A runtime error signalled via `event.errorCode`. */
     ERROR = "error",
+    /** A generic activity or status update. */
     ACTIVITY = "activity",
+    /** A request for the user to confirm one or more tool calls. */
     TOOL_CONFIRMATION = "tool_confirmation",
+    /** The agent has produced its final response for this turn. */
     FINISHED = "finished"
 }
 /**

package/dist/types/examples/example_util.d.ts

@@ -8,6 +8,31 @@ import { Example } from './example.js';
 /**
  * Converts a list of examples to a string that can be used in a system
  * instruction.
+ *
+ * When `model` is undefined or contains `"gemini-2"`, function calls and
+ * responses are formatted with plain triple-backtick fences. For other model
+ * names the legacy `tool_code` / `tool_outputs` fences are used instead.
+ *
+ * @param examples - The few-shot examples to convert.
+ * @param model - Optional model name used to select the function-call fence
+ *   style. Defaults to the gemini-2 style when omitted.
+ * @returns A formatted string wrapped in `<EXAMPLES>…</EXAMPLES>` tags,
+ *   suitable for inclusion in a system instruction.
  */
 export declare function convertExamplesToText(examples: Example[], model?: string): string;
+/**
+ * Builds the few-shot portion of a system instruction from a list of examples
+ * or a {@link BaseExampleProvider}.
+ *
+ * @param examples - Either an array of {@link Example} objects or a
+ *   {@link BaseExampleProvider} whose `getExamples` method is called with
+ *   `query` to obtain the examples dynamically.
+ * @param query - The user query passed to {@link BaseExampleProvider.getExamples}
+ *   when `examples` is a provider. Ignored when `examples` is an array.
+ * @param model - Optional model name forwarded to
+ *   {@link convertExamplesToText} to select the function-call fence style.
+ * @returns A formatted string ready to be appended to a system instruction.
+ * @throws {Error} When `examples` is neither an array nor a
+ *   {@link BaseExampleProvider}.
+ */
 export declare function buildExampleSi(examples: Example[] | BaseExampleProvider, query: string, model?: string): string;