@google/adk 1.5.0 → 2.0.0

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

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Inspection helpers for the "paused, waiting on a human" state.
+ *
+ * A pause is not visible in an event's text: it is carried in a `functionCall`
+ * part named `adk_request_*`, with the prompt buried in that call's `args`. A
+ * client that renders only text parts therefore shows the user nothing while
+ * the run sits blocked. These helpers flatten the three encodings into one
+ * shape so a caller need not know how each kind stores its id and prompt.
+ */
+import { AuthConfig } from '../auth/auth_tool.js';
+import { Event } from '../events/event.js';
+/**
+ * What a paused run is waiting for.
+ *
+ * - `input`: free-form or structured data (`RequestInput`).
+ * - `credential`: an auth credential, e.g. an API key or an OAuth flow.
+ * - `confirmation`: approval to run a tool guarded by `requireConfirmation`.
+ */
+export type UserInputKind = 'input' | 'credential' | 'confirmation';
+/** A single request for user input carried by an event. */
+export interface UserInputRequest {
+    kind: UserInputKind;
+    /**
+     * The id that answers this request: reply with a `functionResponse` carrying
+     * this same id (and {@link functionCallName}).
+     */
+    interruptId: string;
+    /** The name to answer with, alongside {@link interruptId}. */
+    functionCallName: string;
+    /** The node or agent that raised the request. */
+    author?: string;
+    /**
+     * Human-readable prompt for the user. Populated for every kind: the
+     * `RequestInput` message, the credential prompt, or the tool-confirmation
+     * hint. Absent when the raiser supplied none.
+     */
+    message?: string;
+    /** Structured data attached to the request (`RequestInput.payload`). */
+    payload?: unknown;
+    /** JSON schema the reply is expected to satisfy, when declared. */
+    responseSchema?: unknown;
+    /** `confirmation` only: the tool awaiting approval. */
+    toolName?: string;
+    /** `credential` only: the auth config to complete. */
+    authConfig?: AuthConfig;
+}
+/**
+ * Returns every user-input request carried by a single event, in part order.
+ *
+ * This reports what the event *asks for*; it does not know whether the request
+ * was later answered. Use {@link getPendingUserInputRequests} over a session's
+ * events to get only the ones still outstanding.
+ */
+export declare function getUserInputRequests(event: Event): UserInputRequest[];
+/** Whether this event asks the user for something. */
+export declare function requiresUserInput(event: Event): boolean;
+/**
+ * Returns the requests across a sequence of events that have not been answered
+ * yet, in the order they were raised.
+ *
+ * A request is answered by a later `functionResponse` part carrying the same
+ * id, which is how a resumed session records the user's reply. Pass a session's
+ * events to answer "is this session waiting on the user right now, and for
+ * what?".
+ */
+export declare function getPendingUserInputRequests(events: readonly Event[]): UserInputRequest[];

package/dist/types/apps/app.d.ts

@@ -3,8 +3,8 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { BaseAgent } from '../agents/base_agent.js';
 import { BasePlugin } from '../plugins/base_plugin.js';
+import { RunnableRoot } from '../workflow/run_node_as_invocation.js';
 import { ResumabilityConfig } from './resumability_config.js';
 /**
  * Ensures the provided application name is safe and intuitive.
@@ -26,7 +26,12 @@ export declare function isApp(obj: unknown): obj is App;
  */
 export interface AppOptions {
     name: string;
-    rootAgent: BaseAgent;
+    /**
+     * The root of the application. A bare node — a `Workflow`, most usefully —
+     * is accepted and adapted, so a graph does not have to be wrapped by hand to
+     * be an app root. Accepts the same set a `Runner` does.
+     */
+    rootAgent: RunnableRoot;
     plugins?: BasePlugin[];
     resumabilityConfig?: ResumabilityConfig;
 }
@@ -44,7 +49,7 @@ export interface AppOptions {
 export declare class App {
     readonly [APP_SIGNATURE_SYMBOL] = true;
     readonly name: string;
-    readonly rootAgent: BaseAgent | any;
+    readonly rootAgent: RunnableRoot;
     readonly plugins: BasePlugin[];
     readonly resumabilityConfig?: ResumabilityConfig;
     constructor(options: AppOptions);

package/dist/types/artifacts/gcs_artifact_service.d.ts

@@ -3,12 +3,19 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { StorageOptions } from '@google-cloud/storage';
+import type { StorageOptions } from '@google-cloud/storage';
 import { Part } from '@google/genai';
 import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from './base_artifact_service.js';
 export declare class GcsArtifactService implements BaseArtifactService {
-    private readonly bucket;
+    private readonly bucketName;
+    private readonly storageOptions?;
+    private bucketPromise?;
     constructor(bucket: string, options?: StorageOptions);
+    /**
+     * Resolves the GCS bucket handle, loading the `@google-cloud/storage`
+     * optional peer on first use.
+     */
+    private getBucket;
     saveArtifact(request: SaveArtifactRequest): Promise<number>;
     loadArtifact(request: LoadArtifactRequest): Promise<Part | undefined>;
     listArtifactKeys(request: ListArtifactKeysRequest): Promise<string[]>;

package/dist/types/auth/credential_response_binding.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthConfig } from './auth_tool.js';
+/**
+ * Reconciles a credential response with the request that asked for it.
+ *
+ * The request is agent-authored and defines the question: which scheme, from
+ * which authorization server, under which key, on behalf of which client. The
+ * response is client-authored and carries one thing — the credential material
+ * the user obtained. Everything else it contains is discarded, because a
+ * response that gets to restate the question also decides whether the
+ * credential is exchanged at all, where the exchange sends the client secret,
+ * and which waiting tool picks the result up.
+ *
+ * The request is typed loosely on purpose: it is read back off the wire out of
+ * a function call's args, so it can arrive missing the fields its type
+ * promises. Returns `undefined` when it is too incomplete to be an authority,
+ * or when the response carries nothing that answers it — either way there is
+ * nothing that can safely be stored.
+ */
+export declare function bindCredentialResponse(request: Partial<AuthConfig>, response: unknown): AuthConfig | undefined;

package/dist/types/auth/credential_service/in_memory_credential_service.d.ts

@@ -12,6 +12,17 @@ import { BaseCredentialService } from './base_credential_service.js';
  * implementation of credential service
  */
 export declare class InMemoryCredentialService implements BaseCredentialService {
+    /**
+     * A map from app name to a map from user ID to a map from credential key to
+     * credential.
+     *
+     * `appName`, `userId` and `credentialKey` are all attacker-influenced, so
+     * every level is created with `Object.create(null)`. On an ordinary `{}`
+     * literal a key of `__proto__` resolves to the inherited `__proto__`
+     * accessor rather than creating an own property, so nested assignment
+     * pollutes every object in the process, and a lookup of an inherited key
+     * such as `toString` returns a function instead of `undefined`.
+     */
     private readonly credentials;
     loadCredential(authConfig: AuthConfig, toolContext: Context): Promise<AuthCredential | undefined>;
     saveCredential(authConfig: AuthConfig, toolContext: Context): Promise<void>;

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

@@ -23,6 +23,10 @@ export interface UnsafeLocalCodeExecutorOptions {
     pythonCommandPath?: string;
     /**
      * The command to run Shell code. Default is `bash`.
+     *
+     * When it names `powershell` or `pwsh` (with or without `.exe`) the script
+     * is written as `.ps1` and run through PowerShell rather than as a bare
+     * shell script.
      */
     shellCommandPath?: string;
 }
@@ -33,7 +37,7 @@ export interface UnsafeLocalCodeExecutorOptions {
  * **Execution Details**:
  * - **JavaScript**: Executed via `node` (defaults to `process.execPath`).
  * - **Python**: Executed via `python3` on Unix, and `python` on Windows.
- * - **Shell**: Executed via `bash` on Unix, and defaults to `powershell` (injecting ExecutionPolicy Bypass) or `cmd.exe` on Windows.
+ * - **Shell**: Executed via `bash` on Unix, and defaults to `powershell` (injecting `-NoProfile` and `-ExecutionPolicy Bypass`) or `cmd.exe` (injecting `/D`) on Windows.
  *
  * WARNING: This executor runs code in the local environment without sandboxing or security restrictions.
  * Use with caution and only for trusted code.

package/dist/types/common.d.ts

@@ -8,9 +8,9 @@ export type { ActiveStreamingToolParams } from './agents/active_streaming_tool.j
 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 { findEventByFunctionCallId, findMatchingFunctionCall, functionsExportedForTestingOnly, } from './agents/functions.js';
-export { InvocationContext } from './agents/invocation_context.js';
-export type { InvocationContextParams } from './agents/invocation_context.js';
+export { REQUEST_CONFIRMATION_FUNCTION_CALL_NAME, REQUEST_CREDENTIAL_FUNCTION_CALL_NAME, REQUEST_INPUT_FUNCTION_CALL_NAME, findEventByFunctionCallId, findMatchingFunctionCall, functionsExportedForTestingOnly, } from './agents/functions.js';
+export { InvocationContext, requireAgent } from './agents/invocation_context.js';
+export type { InvocationContextParams, WorkflowInstructionScope, } from './agents/invocation_context.js';
 export { LiveRequestQueue } from './agents/live_request_queue.js';
 export type { LiveRequest } from './agents/live_request_queue.js';
 export { LlmAgent as Agent, LlmAgent, isLlmAgent } from './agents/llm_agent.js';
@@ -30,6 +30,8 @@ export { StreamingMode } from './agents/run_config.js';
 export type { RunConfig } from './agents/run_config.js';
 export { SequentialAgent, isSequentialAgent } from './agents/sequential_agent.js';
 export type { TranscriptionEntry } from './agents/transcription_entry.js';
+export { getPendingUserInputRequests, getUserInputRequests, requiresUserInput, } from './agents/user_input_request.js';
+export type { UserInputKind, UserInputRequest, } from './agents/user_input_request.js';
 export { createResumabilityConfig } from './apps/resumability_config.js';
 export type { ResumabilityConfig } from './apps/resumability_config.js';
 export type { BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest, } from './artifacts/base_artifact_service.js';
@@ -70,10 +72,12 @@ export { TrajectoryThoughtPruningCompactor } from './context/trajectory_thought_
 export type { TrajectoryThoughtPruningCompactorOptions } from './context/trajectory_thought_pruning_compactor.js';
 export { TruncatingContextCompactor } from './context/truncating_context_compactor.js';
 export type { TruncatingContextCompactorOptions } from './context/truncating_context_compactor.js';
+export { BaseEnvironment } from './environment/base_environment.js';
+export type { ExecutionResult } from './environment/base_environment.js';
 export { isCompactedEvent, isScratchpadEvent } from './events/compacted_event.js';
 export type { CompactedEvent } from './events/compacted_event.js';
 export { createEvent, generateClientFunctionCallId, getFunctionCalls, getFunctionResponses, hasThoughts, hasTrailingCodeExecutionResult, isFinalResponse, populateClientFunctionCallId, pruneThoughts, stringifyContent, } from './events/event.js';
-export type { Event } from './events/event.js';
+export type { CreateEventParams, Event, NodeInfo, Route, RouteKey, } from './events/event.js';
 export { createEventActions } from './events/event_actions.js';
 export type { EventActions } from './events/event_actions.js';
 export { EventType, toStructuredEvents } from './events/structured_events.js';
@@ -101,7 +105,7 @@ export { BasePlugin, ContextCompactionTrigger } from './plugins/base_plugin.js';
 export { GlobalInstructionPlugin } from './plugins/global_instruction_plugin.js';
 export { LoggingPlugin } from './plugins/logging_plugin.js';
 export { PluginManager } from './plugins/plugin_manager.js';
-export { InMemoryPolicyEngine, PolicyOutcome, REQUEST_CONFIRMATION_FUNCTION_CALL_NAME, SecurityPlugin, getAskUserConfirmationFunctionCalls, } from './plugins/security_plugin.js';
+export { InMemoryPolicyEngine, PolicyOutcome, SecurityPlugin, getAskUserConfirmationFunctionCalls, } from './plugins/security_plugin.js';
 export type { BasePolicyEngine, PolicyCheckResult, ToolCallPolicyContext, } from './plugins/security_plugin.js';
 export { InMemoryRunner } from './runner/in_memory_runner.js';
 export { Runner, determineAgentForResumption, findEventByLastFunctionResponseId, isRoutableLlmAgent, isRunner, } from './runner/runner.js';
@@ -111,7 +115,7 @@ 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 { State } from './sessions/state.js';
+export { State, StateSchemaError, isStateSchemaError } from './sessions/state.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';
@@ -122,8 +126,10 @@ 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';
 export { EXIT_LOOP, ExitLoopTool } from './tools/exit_loop_tool.js';
+export { FINISH_TASK_SUCCESS_RESULT, FINISH_TASK_TOOL_NAME, FinishTaskTool, } from './tools/finish_task_tool.js';
 export { FunctionTool, isFunctionTool } from './tools/function_tool.js';
-export type { ToolExecuteArgument, ToolExecuteFunction, ToolInputParameters, ToolOptions, } from './tools/function_tool.js';
+export type { RequireConfirmation, ToolExecuteArgument, ToolExecuteFunction, ToolInputParameters, ToolOptions, } from './tools/function_tool.js';
+export { getUserChoiceTool } from './tools/get_user_choice_tool.js';
 export { GOOGLE_MAPS_GROUNDING, GoogleMapsGroundingTool, } from './tools/google_maps_grounding_tool.js';
 export { GOOGLE_SEARCH, GoogleSearchTool } from './tools/google_search_tool.js';
 export { LOAD_ARTIFACTS, LoadArtifactsTool, } from './tools/load_artifacts_tool.js';
@@ -132,15 +138,19 @@ export { LOAD_WEB_PAGE, loadWebPage } from './tools/load_web_page.js';
 export type { LoadWebPageOptions } from './tools/load_web_page.js';
 export { LongRunningFunctionTool } from './tools/long_running_tool.js';
 export { PRELOAD_MEMORY, PreloadMemoryTool, } from './tools/preload_memory_tool.js';
-export { ToolConfirmation } from './tools/tool_confirmation.js';
+export { requestInputTool } from './tools/request_input_tool.js';
+export { IntentMismatchError, ToolConfirmation, isIntentMismatchError, } from './tools/tool_confirmation.js';
+export type { IntentMismatchReason } from './tools/tool_confirmation.js';
 export { URL_CONTEXT, UrlContextTool } from './tools/url_context_tool.js';
 export { VertexAiSearchTool } from './tools/vertex_ai_search_tool.js';
 export type { DataStoreParams, SearchEngineParams, VertexAISearchConfig, VertexAISearchDataStoreSpec, VertexAiSearchToolParams, } from './tools/vertex_ai_search_tool.js';
 export { VertexRagRetrievalTool } from './tools/vertex_rag_retrieval_tool.js';
+export { AsyncQueue } from './utils/async_queue.js';
 export { getClientLabels, runWithClientLabel } from './utils/client_labels.js';
 export { LogLevel, getLogger, setLogLevel, setLogger } from './utils/logger.js';
 export type { Logger } from './utils/logger.js';
 export { isGemini2OrAbove, isGemini3xFlashLive } from './utils/model_name.js';
+export type { SchemaLike } from './utils/schema.js';
 export { zodObjectToSchema } from './utils/simple_zod_to_json.js';
 export { Task } from './utils/task.js';
 export type { TaskExecutable } from './utils/task.js';
@@ -169,6 +179,8 @@ export { ToolAuthHandler } from './tools/openapi_tool/openapi_spec_parser/tool_a
 export type { AuthPreparationResult } from './tools/openapi_tool/openapi_spec_parser/tool_auth_handler.js';
 export { OpenAPIToolset } from './tools/openapi_tool/openapi_toolset.js';
 export { RestApiTool, createRestApiTool, } from './tools/openapi_tool/rest_api_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 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 * from './apps/app.js';
 export * from './artifacts/base_artifact_service.js';
 export * from './features/feature_registry.js';

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

@@ -20,5 +20,4 @@ export declare class AgentControlledContextCompactor implements BaseContextCompa
     shouldCompact(invocationContext: InvocationContext): boolean;
     compact(invocationContext: InvocationContext): Promise<void>;
     private clearFlags;
-    private getActiveEvents;
 }

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

@@ -4,6 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Event } from '../events/event.js';
+/**
+ * Filters the events to return only the active events since the latest compaction.
+ * If no compaction has occurred, returns all events.
+ *
+ * @param events The full history of events.
+ * @returns The active events, starting with the latest CompactedEvent if present.
+ */
+export declare function getActiveEvents(events: Event[]): Event[];
 /**
  * Determines the baseline index to retain from active raw events,
  * ensuring we don't split between a function call and its response.

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

@@ -32,7 +32,6 @@ export declare class TokenBasedContextCompactor implements BaseContextCompactor
     private readonly eventRetentionSize;
     private readonly summarizer;
     constructor(options: TokenBasedContextCompactorOptions);
-    private getActiveEvents;
     shouldCompact(invocationContext: InvocationContext): boolean | Promise<boolean>;
     compact(invocationContext: InvocationContext): Promise<void>;
 }

package/dist/types/environment/base_environment.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Result of a shell command executed in a {@link BaseEnvironment}.
+ *
+ * This is distinct from `CodeExecutionResult`, which is produced by the code
+ * executors: a code executor runs a code *snippet* and reports the files it
+ * produced, whereas an environment runs a *shell command* inside a working
+ * directory and reports its process exit status.
+ *
+ * A command that succeeds with no output yields
+ * `{exitCode: 0, stdout: '', stderr: '', timedOut: false}`.
+ */
+export interface ExecutionResult {
+    /** The exit code of the process. `0` on success. */
+    exitCode: number;
+    /** Standard output captured from the process. `''` when nothing was written. */
+    stdout: string;
+    /** Standard error captured from the process. `''` when nothing was written. */
+    stderr: string;
+    /** Whether the execution exceeded the timeout. `false` when it completed. */
+    timedOut: boolean;
+}
+/**
+ * Abstract base class for code execution environments.
+ *
+ * An environment provides the ability to execute shell commands, read files,
+ * and write files within a working directory. Concrete implementations include
+ * local subprocess execution, sandboxed execution, container environments, and
+ * cloud-hosted environments.
+ *
+ * Lifecycle:
+ * 1. Construct the environment.
+ * 2. Call {@link initialize} before first use.
+ * 3. Use {@link execute}, {@link readFile}, {@link writeFile}.
+ * 4. Call {@link close} when done.
+ */
+export declare abstract class BaseEnvironment {
+    /**
+     * Backing flag for {@link isInitialized}.
+     *
+     * Subclasses own this flag: set it in {@link initialize} and clear it in
+     * {@link close}.
+     */
+    protected initialized: boolean;
+    /** Whether the environment has been initialized. */
+    get isInitialized(): boolean;
+    /**
+     * Initializes the environment (e.g. creates the working directory).
+     *
+     * Called before first use. The default implementation is a no-op and leaves
+     * {@link isInitialized} `false`. Subclasses must be idempotent and must set
+     * {@link initialized}.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Releases resources held by the environment.
+     *
+     * The default implementation is a no-op. Subclasses must be idempotent and
+     * must clear {@link initialized}.
+     */
+    close(): Promise<void>;
+    /** The absolute path to the environment's working directory. */
+    abstract get workingDir(): string;
+    /**
+     * Executes a shell command in the working directory.
+     *
+     * @param command The shell command string to execute.
+     * @param timeoutSeconds Maximum execution time in seconds. `undefined` means
+     *   no limit.
+     * @returns The exit code, stdout, stderr, and timeout status. A non-zero exit
+     *   code is reported in the result, not thrown.
+     */
+    abstract execute(command: string, timeoutSeconds?: number): Promise<ExecutionResult>;
+    /**
+     * Reads a file from the environment's filesystem.
+     *
+     * @param filePath Absolute or working-dir-relative path to the file.
+     * @returns The raw file contents.
+     */
+    abstract readFile(filePath: string): Promise<Uint8Array>;
+    /**
+     * Writes content to a file in the environment's filesystem.
+     *
+     * Parent directories are created automatically if they do not exist.
+     *
+     * @param filePath Absolute or working-dir-relative path to the file.
+     * @param content The string or raw bytes to write.
+     */
+    abstract writeFile(filePath: string, content: string | Uint8Array): Promise<void>;
+    /**
+     * Throws if {@link initialize} has not been called.
+     *
+     * Implementations should call this at the start of every operation that needs
+     * a live working directory.
+     */
+    protected assertInitialized(): void;
+}

package/dist/types/environment/local_environment.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseEnvironment, ExecutionResult } from './base_environment.js';
+/** Options for {@link LocalEnvironment}. */
+export interface LocalEnvironmentOptions {
+    /**
+     * Absolute path to the workspace directory. Created by
+     * {@link LocalEnvironment.initialize} if it does not exist, and never deleted
+     * by {@link LocalEnvironment.close}. If omitted, a temporary directory is
+     * created on `initialize()` and removed on `close()`.
+     */
+    workingDir?: string;
+    /** Extra variables merged over `process.env` for every executed command. */
+    envVars?: Record<string, string>;
+}
+/**
+ * Executes commands via local child processes, scoped to a working directory.
+ *
+ * When `workingDir` is not specified, a temporary directory is created on
+ * {@link initialize} and removed on {@link close}.
+ *
+ * WARNING: this class runs arbitrary shell strings on the host with **no
+ * sandboxing** and no sanitisation — the caller is responsible for trusting the
+ * command. It is a building block; tools built on top of it are responsible for
+ * gating execution behind an explicit user confirmation.
+ *
+ * Further limitations, all shared with the adk-python reference implementation:
+ * - stdout and stderr are buffered fully in memory with no cap, so a command
+ *   producing unbounded output will grow the heap until it fails.
+ * - The child inherits the whole of `process.env`, so any secret in the parent
+ *   environment is visible to the command.
+ * - A timeout sends `SIGKILL` to the spawned shell; processes it forked itself
+ *   may survive, and anything they write after the kill is not captured. On
+ *   Windows such a survivor also keeps the working directory locked, so a
+ *   {@link close} following a timeout can fail to remove a temporary workspace.
+ * - File paths are confined to the working directory by a lexical check only
+ *   (see {@link readFile} and {@link writeFile}).
+ */
+export declare class LocalEnvironment extends BaseEnvironment {
+    private currentWorkingDir?;
+    private readonly envVars?;
+    private autoCreated;
+    constructor(options?: LocalEnvironmentOptions);
+    get workingDir(): string;
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    execute(command: string, timeoutSeconds?: number): Promise<ExecutionResult>;
+    /**
+     * Reads a file from the working directory.
+     *
+     * `filePath` is confined to the working directory by a lexical check on the
+     * resolved path, which is not a sandbox.
+     *
+     * @throws If the environment is not initialized, if the path escapes the
+     *   working directory, or — as `ENOENT` — if the file does not exist.
+     */
+    readFile(filePath: string): Promise<Uint8Array>;
+    /**
+     * Writes a file in the working directory, creating parent directories.
+     *
+     * `filePath` is confined to the working directory by a lexical check on the
+     * resolved path, which is not a sandbox. No newline translation is applied,
+     * so explicit CRLF sequences are preserved.
+     *
+     * @throws If the environment is not initialized or the path escapes the
+     *   working directory.
+     */
+    writeFile(filePath: string, content: string | Uint8Array): Promise<void>;
+}

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

@@ -6,6 +6,53 @@
 import { FunctionCall, FunctionResponse } from '@google/genai';
 import { LlmResponse } from '../models/llm_response.js';
 import { EventActions } from './event_actions.js';
+/**
+ * A unique symbol identifying ADK Event objects.
+ *
+ * Events are plain objects produced by {@link createEvent} rather than class
+ * instances, so they carry this signature as a brand and `isEvent` checks for
+ * it — mirroring the `Symbol.for('google.adk.*')` guards used across ADK (e.g.
+ * `isBaseTool`, `isBaseAgent`).
+ */
+declare const EVENT_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * A single route key emitted by a routing node and matched against graph edge
+ * routes. Mirrors the graph's `RouteValue`.
+ */
+export type RouteKey = string | number | boolean;
+/**
+ * The route(s) a routing node emits: a single key fires one branch; an array
+ * fires every branch whose route matches any listed key (multi-route dispatch).
+ */
+export type Route = RouteKey | RouteKey[];
+/**
+ * Workflow-node provenance attached to an event.
+ *
+ * Mirrors `google/adk-python` `Event.node_info`. Present only on events emitted
+ * from within a workflow node.
+ */
+export interface NodeInfo {
+    /** The workflow node path that produced this event (e.g. `wf.child.0`). */
+    path?: string;
+    /**
+     * The node paths this event's output serves as the output for: the emitting
+     * node first, then any ancestor that delegated its own output to it.
+     *
+     * A node that runs a child with `useAsOutput` takes the child's output as its
+     * own, so one event is the result for several nodes at once. Recording that
+     * on the event is what lets a resumed run tell which nodes already produced a
+     * result, instead of re-running an ancestor whose output only ever existed on
+     * a descendant's event.
+     *
+     * Mirrors adk-python's `node_info.output_for`, which is likewise a list.
+     */
+    outputFor?: string[];
+    /**
+     * Whether the event's textual content should be promoted to the node's
+     * structured output.
+     */
+    messageAsOutput?: boolean;
+}
 /**
  * Represents an event in a conversation between agents and users.
 
@@ -13,6 +60,14 @@ import { EventActions } from './event_actions.js';
   taken by the agents like function calls, etc.
  */
 export interface Event extends LlmResponse {
+    /**
+     * Signature brand identifying this object as an ADK {@link Event}.
+     *
+     * Set by {@link createEvent} and checked by `isEvent`. Optional because
+     * events are also reconstructed from storage/session payloads, where the
+     * (non-serializable) brand is absent.
+     */
+    readonly [EVENT_SIGNATURE_SYMBOL]?: true;
     /**
      * The unique identifier of the event.
      * Do not assign the ID. It will be assigned by the session.
@@ -51,6 +106,36 @@ export interface Event extends LlmResponse {
      * The timestamp of the event.
      */
     timestamp: number;
+    /**
+     * Workflow: the structured output produced by the emitting node, if any.
+     *
+     * First-class field mirroring `google/adk-python` `Event.output`. Used by the
+     * workflow engine to carry a node's return value alongside its content.
+     */
+    output?: unknown;
+    /**
+     * Workflow: the route key(s) emitted by a routing node, used by the graph to
+     * select the matching outgoing edge(s). A single value fires one branch; an
+     * array fires every branch whose route matches any listed value (multi-route
+     * dispatch). Mirrors Python `Event.route`.
+     */
+    route?: Route;
+    /**
+     * Workflow: provenance of the emitting node. Mirrors Python `Event.node_info`.
+     */
+    nodeInfo?: NodeInfo;
+    /**
+     * Workflow: scope tag used to isolate multi-agent conversations so peer
+     * scopes don't see each other's events. Mirrors Python
+     * `Event.isolation_scope`.
+     */
+    isolationScope?: string;
+}
+/**
+ * Parameters for creating an event with partial fields.
+ */
+export interface CreateEventParams extends Omit<Partial<Event>, 'actions'> {
+    actions?: Partial<EventActions>;
 }
 /**
  * Creates an event from a partial event.
@@ -58,7 +143,7 @@ export interface Event extends LlmResponse {
  * @param params The partial event to create the event from.
  * @returns The event.
  */
-export declare function createEvent(params?: Partial<Event>): Event;
+export declare function createEvent(params?: CreateEventParams): Event;
 /**
  * Returns whether the event is the final response of the agent.
  */
@@ -103,6 +188,13 @@ export declare function hasThoughts(event: Event): boolean;
  * Returns a copy of the event with all thought parts removed.
  */
 export declare function pruneThoughts(event: Event): Event;
+/**
+ * Type guard to check if an object is an instance of Event.
+ *
+ * @param obj The object to check.
+ * @returns True if the object matches the Event structure.
+ */
+export declare function isEvent(obj: unknown): obj is Event;
 /**
  * Generates a new unique ID for the event.
  */
@@ -121,3 +213,4 @@ export declare function transformToCamelCaseEvent(event: Record<string, unknown>
  * @returns The snake_cased Event object.
  */
 export declare function transformToSnakeCaseEvent(event: Event): Record<string, unknown>;
+export {};

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

@@ -56,6 +56,16 @@ export interface EventActions {
     requestedToolConfirmations: {
         [key: string]: ToolConfirmation;
     };
+    /**
+     * Workflow: a serialized node/agent state snapshot used for resumable
+     * checkpointing. Mirrors Python `EventActions.agent_state`.
+     */
+    agentState?: Record<string, unknown>;
+    /**
+     * Workflow: marks that the emitting agent/workflow has reached the end of its
+     * execution for this invocation. Mirrors Python `EventActions.end_of_agent`.
+     */
+    endOfAgent?: boolean;
 }
 /**
  * Creates an {@link EventActions} object with default empty-dict values for