@google/adk 2.2.0 → 2.2.1

package/dist/types/plugins/debug_logging_plugin.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import { BaseAgent } from '../agents/base_agent.js';
+import { Context } from '../agents/context.js';
+import { InvocationContext } from '../agents/invocation_context.js';
+import { Event } from '../events/event.js';
+import { LlmRequest } from '../models/llm_request.js';
+import { LlmResponse } from '../models/llm_response.js';
+import { BaseTool } from '../tools/base_tool.js';
+import { BasePlugin } from './base_plugin.js';
+declare const DEBUG_LOGGING_PLUGIN_SYMBOL: unique symbol;
+/**
+ * Options for configuring {@link DebugLoggingPlugin}.
+ */
+export interface DebugLoggingPluginOptions {
+    /**
+     * The name of the plugin instance.
+     * @defaultValue 'debug_logging_plugin'
+     */
+    name?: string;
+    /**
+     * Path to the output YAML debug file.
+     * @defaultValue 'adk_debug.yaml'
+     */
+    outputPath?: string;
+    /**
+     * Whether to include a session state snapshot at the end of each invocation.
+     * @defaultValue true
+     */
+    includeSessionState?: boolean;
+    /**
+     * Whether to include full system instructions in LLM request logs.
+     * @defaultValue true
+     */
+    includeSystemInstruction?: boolean;
+}
+/**
+ * A single debug log entry recorded during an invocation.
+ */
+export interface DebugEntry {
+    timestamp: string;
+    entry_type: string;
+    invocation_id?: string;
+    agent_name?: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Per-invocation debug state written as a YAML document.
+ */
+export interface InvocationDebugState {
+    invocation_id: string;
+    session_id: string;
+    app_name: string;
+    user_id?: string;
+    start_time: string;
+    entries: DebugEntry[];
+}
+/**
+ * Type guard to check if an object is an instance of {@link DebugLoggingPlugin}.
+ */
+export declare function isDebugLoggingPlugin(obj: unknown): obj is DebugLoggingPlugin;
+/**
+ * A plugin that captures complete debug information to a YAML file.
+ *
+ * This plugin records detailed interaction data including:
+ * - LLM requests (model, system instruction, contents, tools)
+ * - LLM responses (content, usage metadata, errors)
+ * - Function calls with arguments
+ * - Function responses with results
+ * - Events yielded from the runner
+ * - Session state at the end of each invocation
+ *
+ * Each invocation is appended to the output file as a separate YAML document
+ * (separated by `---`). Credentials, sensitive keys, `temp:`-scoped state keys,
+ * and armored private key blocks are automatically redacted to `[REDACTED]`.
+ */
+export declare class DebugLoggingPlugin extends BasePlugin {
+    readonly [DEBUG_LOGGING_PLUGIN_SYMBOL] = true;
+    readonly outputPath: string;
+    readonly includeSessionState: boolean;
+    readonly includeSystemInstruction: boolean;
+    private readonly invocationStates;
+    private warnedAboutOutputMode;
+    constructor(options?: DebugLoggingPluginOptions);
+    /**
+     * Exposes active invocation states for testing and inspection.
+     */
+    getInvocationState(invocationId: string): InvocationDebugState | undefined;
+    private getTimestamp;
+    /**
+     * Serializes a Gemini `Content` object to a dictionary for YAML output.
+     */
+    serializeContent(content: Content | null | undefined): Record<string, unknown> | null;
+    /**
+     * Safely serializes an arbitrary value to a YAML/JSON-compatible format with
+     * credential, sensitive key, and private key redaction.
+     */
+    safeSerialize(obj: unknown, depth?: number): unknown;
+    private addEntry;
+    onUserMessageCallback({ invocationContext, userMessage, }: {
+        invocationContext: InvocationContext;
+        userMessage: Content;
+    }): Promise<Content | undefined>;
+    beforeRunCallback({ invocationContext, }: {
+        invocationContext: InvocationContext;
+    }): Promise<Content | undefined>;
+    onEventCallback({ invocationContext, event, }: {
+        invocationContext: InvocationContext;
+        event: Event;
+    }): Promise<Event | undefined>;
+    afterRunCallback({ invocationContext, }: {
+        invocationContext: InvocationContext;
+    }): Promise<void>;
+    beforeAgentCallback({ callbackContext, }: {
+        agent: BaseAgent;
+        callbackContext: Context;
+    }): Promise<Content | undefined>;
+    afterAgentCallback({ callbackContext, }: {
+        agent: BaseAgent;
+        callbackContext: Context;
+    }): Promise<Content | undefined>;
+    beforeModelCallback({ callbackContext, llmRequest, }: {
+        callbackContext: Context;
+        llmRequest: LlmRequest;
+    }): Promise<LlmResponse | undefined>;
+    afterModelCallback({ callbackContext, llmResponse, }: {
+        callbackContext: Context;
+        llmResponse: LlmResponse;
+    }): Promise<LlmResponse | undefined>;
+    onModelErrorCallback({ callbackContext, llmRequest, error, }: {
+        callbackContext: Context;
+        llmRequest: LlmRequest;
+        error: Error;
+    }): Promise<LlmResponse | undefined>;
+    beforeToolCallback({ tool, toolArgs, toolContext, }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+    }): Promise<Record<string, unknown> | undefined>;
+    afterToolCallback({ tool, toolContext, result, }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+        result: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | undefined>;
+    onToolErrorCallback({ tool, toolArgs, toolContext, error, }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+        error: Error;
+    }): Promise<Record<string, unknown> | undefined>;
+}
+export {};

package/dist/types/plugins/tool_call_integrity_plugin.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Optional HMAC integrity check for function calls stored in the session.
+ *
+ * Mirrors adk-python's `google.adk.plugins._tool_call_integrity_plugin`.
+ */
+import { Content } from '@google/genai';
+import { Context } from '../agents/context.js';
+import { InvocationContext } from '../agents/invocation_context.js';
+import { Event } from '../events/event.js';
+import { BaseTool } from '../tools/base_tool.js';
+import { BasePlugin } from './base_plugin.js';
+/** `customMetadata` key holding `{functionCallId: stamp}`. */
+export declare const TOOL_CALL_HMAC_METADATA_KEY = "__adk_internal_fc_hmac";
+/** A function call in the session failed its integrity check. */
+export declare class ToolCallIntegrityError extends Error {
+    constructor(message: string);
+}
+/** Options for {@link ToolCallIntegrityPlugin}. */
+export interface ToolCallIntegrityPluginOptions {
+    /**
+     * The HMAC key, or a list of keys during rotation. The first key stamps new
+     * calls; every key is accepted when verifying.
+     */
+    secretKey: Uint8Array | readonly Uint8Array[];
+    /**
+     * Log a warning instead of throwing for function calls that have no stamp,
+     * such as calls stored before the plugin was installed. Such calls also run,
+     * so this reports tampering that removes a stamp but does not prevent it. A
+     * stamp that is present but wrong is always rejected. Defaults to `false`.
+     */
+    allowUnstampedCalls?: boolean;
+    /** The plugin name. Defaults to `'tool_call_integrity'`. */
+    name?: string;
+}
+/**
+ * Stamps function calls and verifies them before runs and tool calls.
+ *
+ * `onEventCallback` adds `"v1:" + HMAC-SHA256(key, payload)` for each function
+ * call to `event.customMetadata["__adk_internal_fc_hmac"]`, and throws
+ * {@link ToolCallIntegrityError} for a response that repeats a call ID before
+ * it is stored. `beforeRunCallback` recomputes the HMAC for every function call
+ * with an ID in the session history, answered or not, and throws when a stamp
+ * is wrong, malformed, repeated or left over from a call that no longer
+ * matches. `beforeToolCallback` lets a tool run only when every stored copy of
+ * its call verifies and the tool's name and arguments match one of them; it
+ * always refuses a call with no ID. Unstamped calls are rejected unless
+ * `allowUnstampedCalls` is set, in which case they are logged.
+ *
+ * Events without function calls are ignored. Events marked as restored are not
+ * verified, and their function calls are never executed. ADK marks events
+ * restored by `adk run --replay`, and {@link prepareRestoredEvent} marks events
+ * that your code copies. Anyone who can write to the session store can also
+ * set the marker, but `beforeToolCallback` still refuses those events' calls.
+ *
+ * `PluginManager` re-throws plugin errors as a generic `Error`; the
+ * {@link ToolCallIntegrityError} is its `cause`.
+ *
+ * Register this plugin before other plugins. `PluginManager` stops at the first
+ * `onEventCallback` that returns an event, and a later plugin must not change
+ * function calls or replace `customMetadata`.
+ *
+ * Requires the Web Crypto API (`globalThis.crypto.subtle`), available in
+ * browsers and in Node.js 19 and later.
+ *
+ * Example:
+ * ```typescript
+ * const plugin = new ToolCallIntegrityPlugin({secretKey: keyBytes});
+ * const app = {name: 'my_app', rootAgent: agent, plugins: [plugin]};
+ *
+ * // Key rotation: stamp with the new key, accept both.
+ * new ToolCallIntegrityPlugin({secretKey: [newKeyBytes, oldKeyBytes]});
+ * ```
+ */
+export declare class ToolCallIntegrityPlugin extends BasePlugin {
+    private readonly keys;
+    private readonly allowUnstampedCalls;
+    private cryptoKeys?;
+    /**
+     * @throws {Error} If `secretKey` is empty or contains a key that is not
+     *     non-empty bytes.
+     */
+    constructor(options: ToolCallIntegrityPluginOptions);
+    /**
+     * Returns a copy with internal metadata removed and marked as restored.
+     *
+     * Use it on events that your code copies into another session, so that the
+     * history passes the integrity check. The copy only keeps the history: its
+     * function calls are never executed.
+     *
+     * @param event The event to copy. It is not modified.
+     * @returns The marked copy, ready to append to the new session.
+     */
+    static prepareRestoredEvent(event: Event): Event;
+    private getCryptoKeys;
+    private sign;
+    /** `subtle.verify` compares in constant time. */
+    private verify;
+    private unstamped;
+    onEventCallback({ invocationContext, event, }: {
+        invocationContext: InvocationContext;
+        event: Event;
+    }): Promise<Event | undefined>;
+    beforeRunCallback({ invocationContext, }: {
+        invocationContext: InvocationContext;
+    }): Promise<Content | undefined>;
+    beforeToolCallback({ tool, toolArgs, toolContext, }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+    }): Promise<Record<string, unknown> | undefined>;
+}

package/dist/types/version.d.ts

@@ -3,4 +3,4 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const version = "2.2.0";
+export declare const version = "2.2.1";