@google/adk 2.4.0 → 2.5.0

package/dist/types/cli/cli_eval.d.ts

@@ -6,7 +6,8 @@
 import { BaseAgent } from '../agents/base_agent.js';
 import { BaseArtifactService } from '../artifacts/base_artifact_service.js';
 import { BaseSessionService } from '../sessions/base_session_service.js';
-import { EvaluationItem } from './utils/evals.js';
+import { Session } from '../sessions/session.js';
+import { EvalCase, EvalSet, EvaluationItem } from './utils/evals.js';
 /**
  * Error message when evaluation dependencies are missing.
  */
@@ -65,15 +66,38 @@ export interface InvocationEvalMetricResult {
  * Complete evaluation result for a single eval case in an evalset.
  */
 export interface EvalResult {
-    eval_set_file: string;
+    /**
+     * @deprecated Use {@link eval_set_id} instead.
+     */
+    eval_set_file?: string;
+    eval_set_id: string;
     eval_id: string;
     final_eval_status: EvalStatus;
-    eval_metric_results: Array<[EvalMetric, EvalMetricResult]>;
+    /**
+     * @deprecated Use {@link overall_eval_metric_results} instead.
+     */
+    eval_metric_results?: Array<[EvalMetric, EvalMetricResult]>;
     overall_eval_metric_results: EvalMetricResult[];
     eval_metric_result_per_invocation: InvocationEvalMetricResult[];
     session_id: string;
+    session_details?: Session;
     user_id?: string;
 }
+/**
+ * Case-level evaluation result alias matching the persisted eval set schema.
+ */
+export type EvalCaseResult = EvalResult;
+/**
+ * Eval-set-level evaluation result persisted by {@link LocalEvalSetResultsManager}.
+ */
+export interface EvalSetResult {
+    evalSetResultId: string;
+    evalSetResultName: string;
+    evalSetId: string;
+    evalCaseResults: RunEvalResult[];
+    /** Creation time in seconds since the Unix epoch, as used in result IDs. */
+    creationTimestamp: number;
+}
 /**
  * Request payload for adding a session to an eval set (`add_session`).
  */
@@ -90,18 +114,26 @@ export interface RunEvalRequest {
     evalMetrics: EvalMetric[];
 }
 /**
- * Result returned for a single evaluation case by the `run_eval` endpoint.
+ * Result returned for a single evaluation case by the `run_eval` and
+ * `eval_results` endpoints.
  */
-export interface RunEvalResult extends EvalResult {
-    evalSetFile: string;
+export interface RunEvalResult {
+    /**
+     * @deprecated Use {@link evalSetId} instead.
+     */
+    evalSetFile?: string;
     evalSetId: string;
     evalId: string;
     finalEvalStatus: EvalStatus;
-    evalMetricResults: Array<[EvalMetric, EvalMetricResult]>;
+    /**
+     * @deprecated Use {@link overallEvalMetricResults} instead.
+     */
+    evalMetricResults?: Array<[EvalMetric, EvalMetricResult]>;
     overallEvalMetricResults: EvalMetricResult[];
     evalMetricResultPerInvocation: InvocationEvalMetricResult[];
     userId?: string;
     sessionId: string;
+    sessionDetails?: Session;
 }
 /**
  * Initial session metadata for an evaluation case.
@@ -127,7 +159,7 @@ export type EvalSetItem = EvalEntry;
  * Options for running evaluations via `runEvals`.
  */
 export interface RunEvalsOptions {
-    evalCasesByEvalSetId: Record<string, EvalEntry[] | string[]>;
+    evalCasesByEvalSetId: Record<string, Array<EvalEntry | EvalCase> | string[]>;
     rootAgent: BaseAgent;
     resetFunc?: () => void | Promise<void>;
     evalMetrics?: EvalMetric[];
@@ -170,4 +202,135 @@ export declare function parseAndGetEvalsToRun(evalSetFilePaths: string[]): Recor
  * Runs a collection of evaluation cases against `rootAgent` and yields an
  * `EvalResult` for each case.
  */
-export declare function runEvals(optionsOrMap: RunEvalsOptions | Record<string, EvalEntry[] | string[]>, rootAgentArg?: BaseAgent, resetFuncArg?: () => void | Promise<void>, evalMetricsArg?: EvalMetric[], printDetailedResultsArg?: boolean, sessionServiceArg?: BaseSessionService, artifactServiceArg?: BaseArtifactService): AsyncGenerator<EvalResult, void, void>;
+export declare function runEvals(optionsOrMap: RunEvalsOptions | Record<string, Array<EvalEntry | EvalCase> | string[]>, rootAgentArg?: BaseAgent, resetFuncArg?: () => void | Promise<void>, evalMetricsArg?: EvalMetric[], printDetailedResultsArg?: boolean, sessionServiceArg?: BaseSessionService, artifactServiceArg?: BaseArtifactService): AsyncGenerator<EvalResult, void, void>;
+/** Parameters for {@link createEvalSetResult}. */
+export interface CreateEvalSetResultParams {
+    appName: string;
+    evalSetId: string;
+    evalCaseResults: ReadonlyArray<EvalCaseResult | RunEvalResult>;
+    /**
+     * Creation time in seconds since the Unix epoch. Seconds, not milliseconds,
+     * keep result IDs and file names in the format the ADK web UI reads.
+     * Defaults to the current time.
+     */
+    creationTimestamp?: number;
+}
+/**
+ * Creates a new {@link EvalSetResult} for the given application, eval set ID,
+ * and case results.
+ */
+export declare function createEvalSetResult({ appName, evalSetId, evalCaseResults, creationTimestamp, }: CreateEvalSetResultParams): EvalSetResult;
+/**
+ * Parses an {@link EvalSetResult} from JSON text. Accepts camelCase or
+ * snake_case keys, and both plain JSON objects and legacy double-encoded JSON
+ * strings.
+ */
+export declare function parseEvalSetResultJson(evalSetResultJson: string): EvalSetResult;
+/** Parameters for {@link LocalEvalSetResultsManager.saveEvalSetResult}. */
+export interface SaveEvalSetResultParams {
+    appName: string;
+    evalSetId: string;
+    evalCaseResults: ReadonlyArray<EvalCaseResult | RunEvalResult>;
+}
+/**
+ * Manages persistence of {@link EvalSetResult} objects on the local filesystem
+ * under `<agentsDir>/<appName>/.adk/eval_history/`.
+ */
+export declare class LocalEvalSetResultsManager {
+    private readonly agentsDir;
+    constructor(agentsDir: string);
+    /**
+     * Creates and saves a new {@link EvalSetResult} for `evalCaseResults`.
+     */
+    saveEvalSetResult({ appName, evalSetId, evalCaseResults, }: SaveEvalSetResultParams): EvalSetResult;
+    /**
+     * Loads an {@link EvalSetResult} by `appName` and `evalSetResultId`.
+     *
+     * @throws {NotFoundError} If the result file does not exist.
+     */
+    getEvalSetResult(appName: string, evalSetResultId: string): EvalSetResult;
+    /**
+     * Lists all saved eval set result IDs for `appName`.
+     */
+    listEvalSetResults(appName: string): string[];
+    private getEvalHistoryDir;
+}
+/**
+ * Normalizes an arbitrary parsed JSON object into an {@link EvalCase},
+ * accepting both camelCase and snake_case keys.
+ *
+ * @throws {InputValidationError} If required fields are missing or invalid.
+ */
+export declare function normalizeEvalCase(raw: unknown): EvalCase;
+/**
+ * Converts a legacy array of {@link EvalEntry} JSON objects into a structured
+ * {@link EvalSet}.
+ *
+ * @param evalSetId The identifier for the resulting eval set.
+ * @param evalSetInJsonFormat Array of legacy eval case objects.
+ * @returns The converted {@link EvalSet}.
+ * @throws {InputValidationError} If the input array or any entry is malformed.
+ */
+export declare function convertEvalSetToSchema(evalSetId: string, evalSetInJsonFormat: unknown): EvalSet;
+/**
+ * Loads an {@link EvalSet} from a file on disk, supporting both the structured
+ * {@link EvalSet} JSON format and the legacy {@link EvalEntry} array format.
+ *
+ * @param evalSetFilePath Path to the `.evalset.json` file.
+ * @param evalSetId Fallback eval set ID used when converting legacy arrays.
+ * @returns The parsed {@link EvalSet}.
+ */
+export declare function loadEvalSetFromFile(evalSetFilePath: string, evalSetId: string): EvalSet;
+/**
+ * Manages local {@link EvalSet} files on disk under
+ * `<agentsDir>/<appName>/<evalSetId>.evalset.json`.
+ */
+export declare class LocalEvalSetsManager {
+    private readonly agentsDir;
+    constructor(agentsDir: string);
+    /**
+     * Loads an {@link EvalSet} identified by `appName` and `evalSetId`, or
+     * returns `undefined` if the file does not exist.
+     */
+    getEvalSet(appName: string, evalSetId: string): EvalSet | undefined;
+    /**
+     * Creates an empty {@link EvalSet} file for `appName` and `evalSetId`.
+     *
+     * @throws {InputValidationError} If `evalSetId` is invalid or the eval set
+     *     already exists.
+     */
+    createEvalSet(appName: string, evalSetId: string): EvalSet;
+    /**
+     * Lists all eval set IDs stored under `appName`, sorted alphabetically.
+     */
+    listEvalSets(appName: string): string[];
+    /**
+     * Adds `evalCase` to the {@link EvalSet} identified by `appName` and
+     * `evalSetId`.
+     *
+     * @throws {NotFoundError} If the eval set does not exist.
+     * @throws {InputValidationError} If `evalCase.evalId` is invalid or already exists.
+     */
+    addEvalCase(appName: string, evalSetId: string, evalCase: EvalCase): void;
+    /**
+     * Returns a single {@link EvalCase} by `appName`, `evalSetId`, and
+     * `evalCaseId`, or `undefined` if not found.
+     */
+    getEvalCase(appName: string, evalSetId: string, evalCaseId: string): EvalCase | undefined;
+    /**
+     * Updates an existing {@link EvalCase} in the {@link EvalSet} identified by
+     * `appName` and `evalSetId`.
+     *
+     * @throws {NotFoundError} If the eval set or eval case is not found.
+     */
+    updateEvalCase(appName: string, evalSetId: string, updatedEvalCase: EvalCase): void;
+    /**
+     * Deletes an {@link EvalCase} identified by `appName`, `evalSetId`, and
+     * `evalCaseId`.
+     *
+     * @throws {NotFoundError} If the eval set or eval case to delete is not found.
+     */
+    deleteEvalCase(appName: string, evalSetId: string, evalCaseId: string): void;
+    private getEvalSetFilePath;
+    private writeEvalSet;
+}

package/dist/types/cli/utils/cleanup.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Runner } from '../../runner/runner.js';
+/**
+ * Maximum time in milliseconds to wait for all runners to close during cleanup.
+ */
+export declare const RUNNER_CLEANUP_TIMEOUT_MS = 30000;
+/**
+ * Closes all provided {@link Runner} instances concurrently, waiting up to
+ * {@link RUNNER_CLEANUP_TIMEOUT_MS} milliseconds and logging a warning if any
+ * close task does not complete in time.
+ *
+ * @param runners The runner instances to close.
+ */
+export declare function closeRunners(runners: readonly Runner[]): Promise<void>;

package/dist/types/cli/utils/envs.d.ts

@@ -16,8 +16,18 @@ export declare function walkToRootUntilFound(folder: string, filename?: string):
  * Walks up from the agent directory to the root directory and loads the first
  * `.env` file found into `process.env` with override semantics.
  *
- * @param agentName The name or path of the agent.
- * @param agentParentFolder The parent directory containing the agent. Defaults to `'.'`.
- * @param filename The dotenv filename to search for. Defaults to `'.env'`.
+ * When `agentParentFolder` is given, `agentName` must be a single path segment
+ * that resolves inside it. When `agentParentFolder` is omitted, `agentName` may
+ * be a path, but it must not be `.` or contain a `..` segment. These checks
+ * are lexical: they do not follow symlinks.
+ *
+ * @param agentName The name of the agent, or a path to it when
+ *     `agentParentFolder` is omitted.
+ * @param agentParentFolder The directory that contains the agent. Optional.
+ * @param filename The dotenv file name to search for. Must be a single path
+ *     segment. Defaults to `'.env'`.
+ * @throws {InputValidationError} If `agentName`, `agentParentFolder` or
+ *     `filename` is invalid, or if `agentName` resolves outside
+ *     `agentParentFolder`.
  */
 export declare function loadDotenvForAgent(agentName: string, agentParentFolder?: string, filename?: string): void;

package/dist/types/cli/utils/evals.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Part } from '@google/genai';
+import { Content, FunctionCall, FunctionResponse, Part } from '@google/genai';
 import { BaseAgent } from '../../agents/base_agent.js';
 import { Session } from '../../sessions/session.js';
 /**
@@ -27,14 +27,77 @@ export interface EvaluationItem {
     expected_intermediate_agent_responses: IntermediateAgentResponseItem[];
     reference: string;
 }
+/**
+ * Intermediate tool uses and sub-agent responses recorded during an evaluation
+ * invocation.
+ */
+export interface EvalIntermediateData {
+    toolUses: FunctionCall[];
+    /**
+     * Expected responses for entries in {@link toolUses}, matched by `id`. When
+     * an eval runs, a matching response replaces the real tool call, so the
+     * response acts as a mock tool output.
+     */
+    toolResponses?: FunctionResponse[];
+    intermediateResponses: IntermediateAgentResponseItem[];
+}
+/**
+ * Represents a single user-to-agent invocation in an evaluation case.
+ */
+export interface EvalInvocation {
+    invocationId?: string;
+    userContent: Content;
+    finalResponse?: Content;
+    intermediateData?: EvalIntermediateData;
+    creationTimestamp?: number;
+}
+/**
+ * Initial session metadata for an {@link EvalCase}.
+ */
+export interface EvalSessionInput {
+    appName: string;
+    userId: string;
+    state: Record<string, unknown>;
+}
+/**
+ * A structured evaluation case containing a multi-turn conversation and
+ * optional initial session state.
+ */
+export interface EvalCase {
+    evalId: string;
+    conversation: EvalInvocation[];
+    sessionInput?: EvalSessionInput;
+    creationTimestamp?: number;
+}
+/**
+ * A named collection of {@link EvalCase} items stored in an `.evalset.json`
+ * file.
+ */
+export interface EvalSet {
+    evalSetId: string;
+    name?: string;
+    description?: string;
+    evalCases: EvalCase[];
+    creationTimestamp?: number;
+}
 /**
  * Converts a session into a list of evaluation items suitable for saving into
  * an evalset or running through `runEvals`.
  *
+ * @deprecated Use {@link convertSessionToEvalInvocations} instead.
  * @param session The session whose events should be converted.
  * @returns An array of `EvaluationItem` records, one per user turn.
  */
 export declare function convertSessionToEvalFormat(session?: Session): EvaluationItem[];
+/**
+ * Converts a session into a list of {@link EvalInvocation} items, grouping each
+ * user turn with its subsequent agent tool calls, intermediate responses, and
+ * final response.
+ *
+ * @param session The session whose events should be converted.
+ * @returns An array of {@link EvalInvocation} records, one per user turn.
+ */
+export declare function convertSessionToEvalInvocations(session?: Session): EvalInvocation[];
 /**
  * Creates a state object initialized with empty strings `''` for all `{var}`
  * placeholders referenced in the instruction strings of `agent` and its

package/dist/types/cli/utils/logs.d.ts

@@ -5,7 +5,10 @@
  */
 import { LogLevel } from '../../utils/logger.js';
 /**
- * Standard log format template for CLI log output.
+ * Legacy Python `logging.Formatter` template string retained for compatibility.
+ *
+ * @deprecated Unused by `adk-js` loggers. ADK CLI stderr and file loggers
+ *     format records directly as `<ISO-8601 timestamp> - <LEVEL> - <message>`.
  */
 export declare const LOGGING_FORMAT = "%(asctime)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s";
 /**
@@ -18,11 +21,16 @@ export interface LogToTmpFolderOptions {
     subFolder?: string;
     /** Prefix for generated log files. Defaults to `'agent'`. */
     logFilePrefix?: string;
-    /** Timestamp suffix for the log filename. Defaults to `YYYYMMDD_HHMMSS`. */
+    /**
+     * Timestamp suffix for the log filename. Defaults to `YYYYMMDD_HHMMSS_<pid>`.
+     * If a file with the resulting name already exists, a numeric `_<n>` suffix
+     * is appended; an existing file is never overwritten.
+     */
     logFileTimestamp?: string;
 }
 /**
  * Configures the global ADK logger to write formatted log records to `stderr`.
+ * Closes the log file that `logToTmpFolder` opened, if any.
  *
  * @param level The minimum `LogLevel` to emit. Defaults to `LogLevel.INFO`.
  */
@@ -32,6 +40,15 @@ export declare function setupAdkLogger(level?: LogLevel): void;
  * file in the system temporary directory and updates the `<prefix>.latest.log`
  * symlink to point to the newest file.
  *
+ * The log directory is restricted to the current user (mode `0o700`) and the
+ * log file is created with mode `0o600`. If `<tmp>/<subFolder>` is a symlink,
+ * is not a directory, or is owned by another user, the logs go to
+ * `<tmp>/<subFolder>_<uid>` instead. Records are written through the file
+ * descriptor opened at creation. The default timestamp includes the
+ * process ID. If the log filename is already taken, a numeric `_<n>` suffix is
+ * appended so that an existing file is never overwritten. The path of the log
+ * file is printed to `stderr`.
+ *
  * @param options Configuration options for the temporary log file.
  * @returns The absolute path to the created log file.
  */

package/dist/types/cli/utils/path_validation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Validates that a caller-supplied identifier is a safe single path segment and
+ * cannot traverse directories.
+ *
+ * This is a lexical check on the string only. It does not resolve symlinks and
+ * is not a sandbox.
+ *
+ * @param value The caller-supplied identifier. Non-string values are rejected.
+ * @param fieldName Human-readable field name used in error messages.
+ * @throws {InputValidationError} If `value` is not a non-empty string, or if it
+ *     contains a null byte, a path separator, a drive prefix, or is `.` or `..`.
+ */
+export declare function validatePathSegment(value: string, fieldName: string): void;
+/**
+ * Returns whether `target` is lexically inside `baseDir` and is not `baseDir`
+ * itself.
+ *
+ * Both paths should already be absolute. This compares strings after
+ * `path.relative`. It does not follow symlinks and is not a sandbox.
+ *
+ * @param baseDir The absolute directory that must contain `target`.
+ * @param target The absolute path to check.
+ * @returns `true` if `target` is a strict descendant of `baseDir`.
+ */
+export declare function isStrictlyInside(baseDir: string, target: string): boolean;

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

@@ -32,12 +32,20 @@ export interface ContainerCodeExecutorOptions {
     networkEnabled?: boolean;
     /**
      * Wall-clock timeout in seconds for a single execution. Must be greater than
-     * 0; defaults to 300. Every execution shares one long-lived container, so an
-     * unbounded run (e.g. a loop emitted by the model) would burn that
-     * container's CPU for every later caller. Raise it rather than remove it for
-     * a computation that legitimately runs longer.
+     * 0; defaults to 300. Each session runs in its own long-lived container, so
+     * an unbounded run (e.g. a loop emitted by the model) would burn that
+     * container's CPU for every later call in the same session. Raise it rather
+     * than remove it for a computation that legitimately runs longer.
      */
     timeoutSeconds?: number;
+    /**
+     * Maximum number of session containers to keep running concurrently.
+     * When exceeded, the least recently used idle session container is stopped
+     * and evicted. A container that is running code is never evicted, so the
+     * count can exceed the limit until that run ends. Must be a positive
+     * integer.
+     */
+    maxContainers?: number;
     /**
      * Injected Docker client, primarily for testing so unit tests never touch a
      * real Docker daemon. Defaults to a new client built from `baseUrl`.
@@ -65,7 +73,8 @@ export interface ContainerCodeExecutorOptions {
  * background processes persist into a later, unrelated session's execution.
  * A container is still reused across multiple calls *within* the same
  * session, so the per-call container-startup cost is paid once per session,
- * not once per call.
+ * not once per call. Set `maxContainers` to bound how many session containers
+ * run at once; beyond it, the least recently used idle one is stopped.
  *
  * Limitations: this executor runs a code string only. `inputFiles` and `args`
  * on the request are not copied into the container, and output files are not
@@ -78,8 +87,20 @@ export declare class ContainerCodeExecutor extends BaseCodeExecutor {
     private readonly dockerPath?;
     private readonly containerOptions;
     private readonly timeoutSeconds;
+    private readonly maxContainers?;
+    /** Started session containers, ordered from least to most recently used. */
     private readonly containers;
+    /** Container starts that are still in flight, keyed by session. */
     private readonly initPromises;
+    /**
+     * Number of `executeCode` calls in progress per session. A session with a
+     * call in progress is never evicted, so a run is not stopped midway.
+     */
+    private readonly activeExecutions;
+    /** Shared image build, so the image is built at most once per executor. */
+    private buildPromise?;
+    private closing;
+    private closePromise?;
     constructor(options?: ContainerCodeExecutorOptions);
     executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult>;
     /**
@@ -90,12 +111,32 @@ export declare class ContainerCodeExecutor extends BaseCodeExecutor {
      */
     private describeExit;
     /**
-     * Stops and removes every session's container. Safe to call when none has
-     * been started; provided for deterministic teardown in tests and app
+     * Stops and removes every session's container. Waits for container starts
+     * that are still in flight, so no container is left running after it
+     * resolves. Safe to call when none has been started, and concurrent calls
+     * share one teardown. Provided for deterministic teardown in tests and app
      * shutdown.
      */
     close(): Promise<void>;
-    /** Lazily builds/starts the given session's container exactly once. */
+    private stopAll;
+    /**
+     * Returns the given session's container, starting it if needed. Concurrent
+     * calls for one session share a single in-flight start, and reuse marks the
+     * container as the most recently used.
+     */
     private ensureContainer;
+    /**
+     * Builds the image from `dockerPath` once and shares the build across every
+     * session. A failed build is cleared so the next call retries it.
+     */
+    private ensureImageBuilt;
     private initContainer;
+    /**
+     * Stops the least recently used idle session containers until the count is
+     * within `maxContainers`. A session with a call in progress is skipped, which
+     * includes the caller that just registered its container; if every session
+     * is busy, the overshoot stays until a call ends. The stop is not awaited so
+     * the caller is not delayed by another session's teardown.
+     */
+    private evictLeastRecentlyUsed;
 }

package/dist/types/common.d.ts

@@ -9,6 +9,7 @@ export { BaseAgent, isBaseAgent } from './agents/base_agent.js';
 export type { AfterAgentCallback, BaseAgentConfig, BeforeAgentCallback, SingleAgentCallback, } from './agents/base_agent.js';
 export { Context } from './agents/context.js';
 export { REQUEST_CONFIRMATION_FUNCTION_CALL_NAME, REQUEST_CREDENTIAL_FUNCTION_CALL_NAME, REQUEST_INPUT_FUNCTION_CALL_NAME, findEventByFunctionCallId, findMatchingFunctionCall, functionsExportedForTestingOnly, handleFunctionCallsLive, isToolNotFound, } from './agents/functions.js';
+export { injectSessionState } from './agents/instructions.js';
 export { InvocationContext, LlmCallsLimitExceededError, isLlmCallsLimitExceededError, requireAgent, } from './agents/invocation_context.js';
 export type { InvocationContextParams, WorkflowInstructionScope, } from './agents/invocation_context.js';
 export { LangGraphAgent, getLastHumanMessages, isLangGraphAgent, } from './agents/langgraph_agent.js';
@@ -138,7 +139,9 @@ export type { AppendEventRequest, CreateSessionRequest, DeleteSessionRequest, Ge
 export { InMemorySessionService } from './sessions/in_memory_session_service.js';
 export { createSession } from './sessions/session.js';
 export type { CompositeSessionKey, Session } from './sessions/session.js';
+export { StaleSessionError, isStaleSessionError, } from './sessions/stale_session_error.js';
 export { State, StateSchemaError, isStateSchemaError } from './sessions/state.js';
+export type { ContentCapturingMode, ExperimentalFeature, TelemetryConfig, } from './telemetry/api/instrumentation.js';
 export { AgentTool, isAgentTool } from './tools/agent_tool.js';
 export type { AgentToolConfig } from './tools/agent_tool.js';
 export { BaseTool, isBaseTool } from './tools/base_tool.js';
@@ -146,6 +149,12 @@ export type { BaseToolParams, RunAsyncToolRequest, ToolProcessLlmRequest, } from
 export { BaseToolset, isBaseToolset } from './tools/base_toolset.js';
 export type { ToolPredicate } from './tools/base_toolset.js';
 export { BuiltInTool } from './tools/built_in_tool.js';
+export { BaseComputer, ComputerEnvironment, isBaseComputer, } from './tools/computer_use/base_computer.js';
+export type { ComputerState, ScrollDirection, } from './tools/computer_use/base_computer.js';
+export { ComputerUseTool, isComputerUseTool, } from './tools/computer_use/computer_use_tool.js';
+export type { ComputerUseFunction, ComputerUseToolOptions, } from './tools/computer_use/computer_use_tool.js';
+export { ComputerUseToolset, adaptComputerUseTool, isComputerUseToolset, } from './tools/computer_use/computer_use_toolset.js';
+export type { AdaptComputerUseToolParams, AdaptedComputerUseFunction, ComputerUseToolsetOptions, } from './tools/computer_use/computer_use_toolset.js';
 export { ConsolidateContextTool } from './tools/consolidate_context_tool.js';
 export { ENTERPRISE_WEB_SEARCH, EnterpriseWebSearchTool, } from './tools/enterprise_web_search_tool.js';
 export { ExampleTool } from './tools/example_tool.js';
@@ -185,6 +194,8 @@ export { getClientLabels, runWithClientLabel } from './utils/client_labels.js';
 export { toGeminiSchema } from './utils/gemini_schema_util.js';
 export type { MCPToolSchema } from './utils/gemini_schema_util.js';
 export { genaiSchemaToJsonSchema } from './utils/genai_schema_to_json.js';
+export { newId, resetIdProvider, setIdProvider } from './utils/id_provider.js';
+export type { IdProvider } from './utils/id_provider.js';
 export { LogLevel, getLogger, logger, resetLogger, setLogLevel, setLogger, } from './utils/logger.js';
 export type { Logger } from './utils/logger.js';
 export { isGemini2OrAbove, isGemini35LiveTranslate, isGemini3xFlashLive, isGemini3xLive, } from './utils/model_name.js';
@@ -204,19 +215,15 @@ export { SearchSkillsTool } from './tools/skill/search_skills_tool.js';
 export * from './artifacts/base_artifact_service.js';
 export * from './features/feature_registry.js';
 export * from './memory/base_memory_service.js';
-export * from './sessions/base_session_service.js';
+export { mergeStates, trimTempDeltaState, trimTempState, } from './sessions/base_session_service.js';
 export * from './tools/base_tool.js';
-export { BaseNode, BranchPath, DEFAULT_ROUTE, Edge, FunctionNode, Graph, JoinNode, NodeContext, NodeReportedError, NodeSchemaValidationError, NodeStatus, NodeTimeoutError, NodeTool, ParallelWorker, RequestInput, START, ToolNode, Workflow, WorkflowNode, asRunnableRoot, commonPrefixOf, createNodeErrorEvent, createNodeState, createSubBranch, isNodeErrorEvent, isNodeReportedError, isNodeSchemaValidationError, isNodeState, isNodeTimeoutError, isRequestInput, isRunnableRoot, isWorkflow, node, normalizeRetryExceptions, prepareRetryConfig, } from './workflow/index.js';
+export { BaseNode, BranchPath, DEFAULT_ROUTE, Edge, FunctionNode, Graph, JoinNode, NodeContext, NodeReportedError, NodeSchemaValidationError, NodeStatus, NodeTimeoutError, NodeTool, ParallelWorker, RequestInput, START, ToolNode, Workflow, WorkflowNode, asRunnableRoot, commonPrefixOf, createNodeErrorEvent, createNodeState, createSubBranch, isNodeErrorEvent, isNodeReportedError, isNodeSchemaValidationError, isNodeState, isNodeTimeoutError, isParallelWorker, isRequestInput, isRunnableRoot, isWorkflow, node, normalizeRetryExceptions, prepareRetryConfig, } from './workflow/index.js';
 export type { BaseNodeConfig, BuildNodeOptions, ChainElement, CreateNodeErrorEventParams, DynamicEntry, EdgeItem, ErrorClass, FunctionNodeConfig, FunctionNodeHandler, FunctionNodeResult, NodeContextOptions, NodeErrorEvent, NodeLike, NodeOptions, NodeResult, NodeState, ParallelWorkerConfig, PreparedRetryConfig, RequestInputParams, RetryConfig, RouteValue, RoutingMap, RunNodeOptions, RunnableNode, RunnableRoot, ScheduleDynamicNode, ScheduleDynamicNodeOptions, ToolNodeConfig, WorkflowConfig, } from './workflow/index.js';
 export { App, isApp, validateAppName } from './apps/app.js';
 export type { AppOptions } from './apps/app.js';
-export * from './artifacts/base_artifact_service.js';
-export * from './features/feature_registry.js';
-export * from './memory/base_memory_service.js';
-export * from './sessions/base_session_service.js';
-export * from './tools/base_tool.js';
-export { convertSessionToEvalFormat, createEmptyState, } from './cli/utils/evals.js';
-export type { EvaluationItem, IntermediateAgentResponseItem, ToolUseItem, } from './cli/utils/evals.js';
+export { RUNNER_CLEANUP_TIMEOUT_MS, closeRunners } from './cli/utils/cleanup.js';
+export { convertSessionToEvalFormat, convertSessionToEvalInvocations, createEmptyState, } from './cli/utils/evals.js';
+export type { EvalCase, EvalIntermediateData, EvalInvocation, EvalSessionInput, EvalSet, EvaluationItem, IntermediateAgentResponseItem, ToolUseItem, } from './cli/utils/evals.js';
 export { buildFunctionDeclarationForLangchain, buildFunctionDeclarationForParamsForCrewai, buildFunctionDeclarationUtil, } from './tools/function_tool.js';
 export type { CallLiveToolRequest } from './tools/function_tool.js';
 export type { LoadMemoryResponse, LoadMemoryToolOptions, } from './tools/load_memory_tool.js';

package/dist/types/context/compaction_utils.d.ts

@@ -24,7 +24,19 @@ export declare function isEventVisibleInIsolationScope(event: Event, currentIsol
  * Determines the baseline index to retain from active raw events,
  * ensuring we don't split between a function call and its response.
  *
- * @param rawEvents The active raw events to consider for compaction.
+ * Two checks protect a pair, mirroring the two places that can otherwise
+ * observe half of it:
+ * - Adjacent pairs: while the event before the split contains a function call
+ *   and the event at the split contains a function response, move the split
+ *   earlier.
+ * - Non-adjacent pairs: extend the retained tail back to the nearest preceding
+ *   call for every retained response ID, following any dependencies that
+ *   extension exposes. This matches the content builder, which pairs calls and
+ *   responses by ID alone after filtering by scope and branch, so a call on a
+ *   sub-agent branch answered by an unbranched user response is still kept.
+ *
+ * @param rawEvents The active raw events to consider for compaction. They are
+ *   already filtered to the caller's isolation scope.
  * @param eventRetentionSize The minimum number of raw events to keep at the end of the session.
  * @returns The index in `rawEvents` at which to split. Events before this index will be compacted.
  */

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

@@ -201,6 +201,9 @@ export declare function pruneThoughts(event: Event): Event;
 export declare function isEvent(obj: unknown): obj is Event;
 /**
  * Generates a new unique ID for the event.
+ *
+ * The ID comes from the provider set with `setIdProvider`, or is 8 random
+ * alphanumeric characters when none is set.
  */
 export declare function createNewEventId(): string;
 /**

package/dist/types/features/feature_registry.d.ts

@@ -7,6 +7,7 @@
  * Feature names.
  */
 export declare enum FeatureName {
+    COMPUTER_USE = "COMPUTER_USE",
     PROGRESSIVE_SSE_STREAMING = "PROGRESSIVE_SSE_STREAMING"
 }
 /**