@google/adk 2.1.0 → 2.2.0

package/dist/types/tools/openapi_tool/auth/credential_exchangers/oauth2_exchanger.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../../../../auth/auth_credential.js';
+import { AuthScheme } from '../../../../auth/auth_schemes.js';
+import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
+/**
+ * Validates that the scheme and the credential can produce a bearer token.
+ *
+ * @param authScheme - The OpenID Connect or OAuth2 auth scheme.
+ * @param authCredential - The auth credential to validate.
+ * @throws Error - If the credential is absent, the scheme is
+ *     not OpenID Connect or OAuth2, or the credential carries neither `oauth2`
+ *     nor `http`.
+ */
+export declare function checkSchemeCredentialType(authScheme: AuthScheme, authCredential?: AuthCredential): asserts authCredential is AuthCredential;
+/**
+ * Converts an OAuth2 access token into an HTTP bearer credential.
+ *
+ * @param authCredential - The auth credential holding the access token.
+ * @returns A new credential holding the access token as an HTTP bearer token,
+ *     or the original credential when there is no access token to convert. The
+ *     input credential is never modified.
+ */
+export declare function generateAuthToken(authCredential: AuthCredential): AuthCredential;
+/**
+ * Exchanges an OAuth2 or OpenID Connect credential for an HTTP bearer one.
+ *
+ * @param authScheme - The auth scheme.
+ * @param authCredential - The auth credential.
+ * @returns The credential unchanged when it already carries `http`, a new HTTP
+ *     bearer credential when it carries an access token, or `null` when there
+ *     is no token to convert.
+ * @throws Error - If the scheme or the credential is invalid.
+ */
+export declare function exchangeCredential(authScheme: AuthScheme, authCredential?: AuthCredential): AuthCredential | null;
+/**
+ * Converts OAuth2 and OpenID Connect credentials into HTTP bearer credentials.
+ *
+ * Ports `OAuth2CredentialExchanger` from adk-python
+ * `src/google/adk/tools/openapi_tool/auth/credential_exchangers/oauth2_exchanger.py`
+ * at tag `v0.1.0`. The adk-js class carries a different name because
+ * `OAuth2CredentialExchanger` in `core/src/auth/oauth2/` already owns that one,
+ * and it solves a different problem: it fetches tokens from the token endpoint,
+ * where this class converts a token it is given.
+ */
+export declare class OAuth2BearerExchanger implements BaseCredentialExchanger {
+    exchange(params: {
+        authScheme?: AuthScheme;
+        authCredential: AuthCredential;
+    }): Promise<ExchangeResult>;
+}

package/dist/types/tools/openapi_tool/common/common.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { OpenAPIV3 } from 'openapi-types';
+import { ApiParameter } from '../openapi_spec_parser/operation_parser.js';
+/**
+ * The type hints these helpers emit are Python tokens, in a TypeScript SDK,
+ * on purpose. They are assembled into a tool description that reaches the
+ * model, so the same OpenAPI operation has to describe itself identically in
+ * adk-js and in adk-python. The reference is adk-python
+ * `src/google/adk/tools/openapi_tool/common/common.py`.
+ */
+/** Input to {@link createApiParameter}; `name` is derived when omitted. */
+export interface ApiParameterInit {
+    originalName: string;
+    paramLocation: string;
+    paramSchema: OpenAPIV3.SchemaObject;
+    description?: string;
+    name?: string;
+    required?: boolean;
+}
+/**
+ * Returns the Python type hint for an OpenAPI schema.
+ *
+ * @param schema The schema to describe, if any.
+ * @returns A Python type name such as `str`, `List[int]` or `Dict[str, Any]`.
+ *     A missing or unrecognised type gives `Any`.
+ */
+export declare function getTypeHint(schema: OpenAPIV3.SchemaObject | undefined): string;
+/**
+ * Generates the docstring line documenting one parameter.
+ *
+ * @param param The parameter to document.
+ * @returns A line of the form `name (type): description`, followed by an
+ *     indented property list when the schema is an object with properties.
+ */
+export declare function generateParamDoc(param: ApiParameter): string;
+/**
+ * Generates the docstring block documenting the return value.
+ *
+ * Uses the 2xx response with the smallest status code that has content.
+ *
+ * @param responses The responses of an OpenAPI operation.
+ * @returns A line of the form `Returns (type): description`, or `''` when no
+ *     2xx response has content.
+ */
+export declare function generateReturnDoc(responses: OpenAPIV3.ResponsesObject): string;
+/**
+ * Builds an {@link ApiParameter}, deriving the fields adk-python derives in
+ * `ApiParameter.model_post_init`.
+ *
+ * `name` falls back to the reserved-word-safe snake_case form of
+ * `originalName`, and `description` falls back to the schema description.
+ *
+ * @param init The parameter fields.
+ * @returns The parameter with its derived fields filled in.
+ */
+export declare function createApiParameter(init: ApiParameterInit): ApiParameter;

package/dist/types/tools/openapi_tool/openapi_spec_parser/openapi_spec_parser.d.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { OpenAPIV3 } from 'openapi-types';
+import { AuthCredential } from '../../../auth/auth_credential.js';
 import { ApiParameter } from './operation_parser.js';
 export interface OperationEndpoint {
     baseUrl: string;
@@ -18,6 +19,12 @@ export interface ParsedOperation {
     parameters: ApiParameter[];
     returnValue?: ApiParameter;
     authScheme?: OpenAPIV3.SecuritySchemeObject;
+    /**
+     * Credential for the operation. The parser leaves this undefined; a caller
+     * that builds a `ParsedOperation` by hand can set it, and `OpenAPIToolset`
+     * passes it to the tool it creates.
+     */
+    authCredential?: AuthCredential;
 }
 export declare class OpenApiSpecParser {
     private preservePropertyNames;

package/dist/types/tools/openapi_tool/openapi_spec_parser/operation_parser.d.ts

@@ -19,13 +19,32 @@ export interface ApiParameter {
  * that are compatible with Gemini's tool function declarations.
  */
 export declare class OperationParser {
-    private readonly operation;
     private params;
     private returnValue?;
     private preservePropertyNames;
-    constructor(operation: OpenAPIV3.OperationObject, options?: {
+    private readonly operation;
+    /**
+     * @param operation The operation to parse. A string is parsed as JSON, and a
+     *     plain object is used as given.
+     * @param options.preservePropertyNames Keeps the original parameter and
+     *     function names instead of converting them to snake_case.
+     * @param options.shouldParse Whether to parse the operation during
+     *     construction. Defaults to `true`.
+     */
+    constructor(operation: OpenAPIV3.OperationObject | Record<string, unknown> | string, options?: {
         preservePropertyNames?: boolean;
+        shouldParse?: boolean;
     });
+    /**
+     * Builds a parser from parameters that were already parsed, without walking
+     * the operation again.
+     *
+     * @param operation The operation the parameters came from.
+     * @param params The parsed parameters.
+     * @param returnValue The parsed return value, if any.
+     * @returns A parser holding the given parameters.
+     */
+    static load(operation: OpenAPIV3.OperationObject | Record<string, unknown> | string, params: ApiParameter[], returnValue?: ApiParameter): OperationParser;
     private getParamName;
     private processOperationParameters;
     private processRequestBody;
@@ -56,4 +75,39 @@ export declare class OperationParser {
      * @returns A string representing the description.
      */
     getDescription(): string;
+    /**
+     * Gets the name of the security scheme this operation declares.
+     *
+     * Only operation-level security is considered. Document-level security is
+     * not visible from here, so a caller that needs the fallback uses
+     * `OpenApiSpecParser` instead.
+     *
+     * @returns The first declared scheme name, or `''` when the operation
+     *     declares none.
+     */
+    getAuthSchemeName(): string;
+    /**
+     * Gets the parsed return value of the operation.
+     *
+     * @returns The return value, or `undefined` when the parser was constructed
+     *     with `shouldParse: false` and nothing was loaded.
+     */
+    getReturnValue(): ApiParameter | undefined;
+    /**
+     * Gets the Python-style type hint of the return value.
+     *
+     * @returns A type name such as `str`, or `Any` when the operation declares
+     *     no typed 2xx response.
+     */
+    getReturnTypeHint(): string;
+    /**
+     * Generates a Python-style docstring describing the operation, every
+     * parameter and the return value.
+     *
+     * The type names inside it are Python's, because the artifact is a docstring
+     * in adk-python's format and the same text reaches the model in both SDKs.
+     *
+     * @returns The generated docstring.
+     */
+    getPydocString(): string;
 }

package/dist/types/tools/openapi_tool/openapi_spec_parser/tool_auth_handler.d.ts

@@ -3,21 +3,89 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { OpenAPIV3 } from 'openapi-types';
 import { Context } from '../../../agents/context.js';
 import { AuthCredential } from '../../../auth/auth_credential.js';
+import { AuthScheme } from '../../../auth/auth_schemes.js';
+import { BaseCredentialExchanger } from '../../../auth/exchanger/base_credential_exchanger.js';
+/** The outcome of preparing a tool's credential. */
 export interface AuthPreparationResult {
     state: 'pending' | 'done';
+    authScheme?: AuthScheme;
     authCredential?: AuthCredential;
 }
+/** Collaborators a caller may substitute when building a {@link ToolAuthHandler}. */
+export interface ToolAuthHandlerOptions {
+    /** Key under which a credential service loads and saves this credential. */
+    credentialKey?: string;
+    /** Exchanger to use instead of the default `AutoAuthCredentialExchanger`. */
+    credentialExchanger?: BaseCredentialExchanger;
+    /** Store to use instead of one built over the tool's own context. */
+    credentialStore?: ToolContextCredentialStore;
+}
+/**
+ * Stores and retrieves exchanged credentials in the session state carried by a
+ * {@link Context}.
+ */
+export declare class ToolContextCredentialStore {
+    private readonly context;
+    constructor(context: Context);
+    /**
+     * Returns the state key that holds the credential exchanged for this scheme
+     * and credential pair.
+     *
+     * Both operands are hashed into the key, so two tools configured with
+     * different schemes, or with different credentials under one scheme, never
+     * share a slot.
+     *
+     * The key deliberately carries no `temp:` prefix. Session state is a copy and
+     * only the delta is persisted, and `temp:` is cleared at the end of a run,
+     * while an exchanged token has to stay readable across runs.
+     */
+    getCredentialKey(authScheme?: AuthScheme, authCredential?: AuthCredential): string;
+    /**
+     * Returns the credential stored for this scheme and credential pair, or
+     * `undefined` when there is none.
+     *
+     * @throws Error if the state entry under the key is not an
+     *     {@link AuthCredential}, which means something else wrote to the key.
+     */
+    getCredential(authScheme?: AuthScheme, authCredential?: AuthCredential): AuthCredential | undefined;
+    storeCredential(key: string, credential: AuthCredential): void;
+    /**
+     * Makes the credential under `key` unreadable again.
+     *
+     * adk-python deletes the state entry. `State` has no delete, so this writes
+     * `undefined`, which `State.get` returns for a missing key as well, and
+     * {@link getCredential} therefore misses exactly as a delete would make it.
+     */
+    removeCredential(key: string): void;
+}
 export declare class ToolAuthHandler {
     private readonly context;
     private readonly authScheme?;
     private readonly authCredential?;
     private readonly credentialKey?;
-    constructor(context: Context, authScheme?: OpenAPIV3.SecuritySchemeObject | undefined, authCredential?: AuthCredential | undefined, credentialKey?: string | undefined);
-    static fromToolContext(context: Context, authScheme?: OpenAPIV3.SecuritySchemeObject, authCredential?: AuthCredential, options?: {
-        credentialKey?: string;
-    }): ToolAuthHandler;
+    private readonly credentialExchanger?;
+    private readonly credentialStore;
+    constructor(context: Context, authScheme?: AuthScheme, authCredential?: AuthCredential, options?: ToolAuthHandlerOptions);
+    static fromToolContext(context: Context, authScheme?: AuthScheme, authCredential?: AuthCredential, options?: ToolAuthHandlerOptions): ToolAuthHandler;
     prepareAuthCredentials(): Promise<AuthPreparationResult>;
+    /**
+     * Exchanges `credential`, or returns `undefined` when the exchange failed.
+     *
+     * An exchange failure is transient far more often than it is fatal, so it
+     * becomes a `pending` result the client can resume from rather than an
+     * exception that fails the whole tool call.
+     */
+    private tryExchange;
+    /**
+     * Asks the client for a credential, after checking that an interactive
+     * scheme has the OAuth2 client configuration it cannot proceed without.
+     *
+     * @throws Error if an `oauth2` or `openIdConnect` scheme has no OAuth2
+     *     credential.
+     * @throws AuthCredentialMissingError if that credential omits `clientId` or
+     *     `clientSecret`.
+     */
+    private requestCredential;
 }

package/dist/types/tools/openapi_tool/openapi_toolset.d.ts

@@ -8,6 +8,7 @@ import { ReadonlyContext } from '../../agents/readonly_context.js';
 import { AuthCredential } from '../../auth/auth_credential.js';
 import { BaseTool } from '../base_tool.js';
 import { BaseToolset, ToolPredicate } from '../base_toolset.js';
+import { RestApiTool } from './rest_api_tool.js';
 export declare class OpenAPIToolset extends BaseToolset {
     private tools;
     constructor(options?: {
@@ -23,5 +24,15 @@ export declare class OpenAPIToolset extends BaseToolset {
         headerProvider?: (context: ReadonlyContext) => Record<string, string>;
     });
     getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
+    /**
+     * Returns the parsed tool with the given name, or `undefined` when the spec
+     * produced no such tool.
+     *
+     * The lookup is over every tool parsed from the spec and does not apply
+     * `toolFilter`, which selects what an agent exposes to the model rather than
+     * what the toolset holds. When the toolset was constructed with `prefix`,
+     * pass the prefixed name.
+     */
+    getTool(toolName: string): RestApiTool | undefined;
     close(): Promise<void>;
 }

package/dist/types/tools/openapi_tool/rest_api_tool.d.ts

@@ -8,8 +8,26 @@ import { OpenAPIV3 } from 'openapi-types';
 import { ReadonlyContext } from '../../agents/readonly_context.js';
 import { AuthCredential } from '../../auth/auth_credential.js';
 import { BaseTool, RunAsyncToolRequest } from '../base_tool.js';
-import { ApiParameter } from './openapi_spec_parser/operation_parser.js';
+import { ApiParameter, OperationParser } from './openapi_spec_parser/operation_parser.js';
 import { OperationEndpoint } from './openapi_spec_parser/openapi_spec_parser.js';
+/**
+ * The parsed operation `createRestApiTool` accepts.
+ *
+ * `name` and `description` are optional and are derived from the operation
+ * when they are absent. `parameters` and `returnValue` carry an operation the
+ * caller has already parsed, so its names, locations and schemas stay
+ * authoritative.
+ */
+export interface ParsedOperationInput {
+    name?: string;
+    description?: string;
+    endpoint: OperationEndpoint;
+    operation: OpenAPIV3.OperationObject;
+    authScheme?: OpenAPIV3.SecuritySchemeObject;
+    authCredential?: AuthCredential;
+    parameters?: ApiParameter[];
+    returnValue?: ApiParameter;
+}
 export declare class RestApiTool extends BaseTool {
     private readonly endpoint;
     private readonly operation;
@@ -22,6 +40,7 @@ export declare class RestApiTool extends BaseTool {
         preservePropertyNames?: boolean;
         headerProvider?: (context: ReadonlyContext) => Record<string, string>;
         credentialKey?: string;
+        operationParser?: OperationParser;
     });
     configureAuthScheme(authScheme: OpenAPIV3.SecuritySchemeObject): void;
     configureAuthCredential(authCredential: AuthCredential): void;
@@ -34,17 +53,32 @@ export interface PreparedParams {
     headers: Record<string, string>;
     body: unknown;
     bodyData: Record<string, unknown>;
+    cookies: Record<string, string>;
 }
 export declare function prepareRequestParams(endpoint: OperationEndpoint, parameters: ApiParameter[], args: Record<string, unknown>): PreparedParams;
 export declare function prepareRequestBody(requestBody: OpenAPIV3.RequestBodyObject | OpenAPIV3.ReferenceObject | undefined, body: unknown, bodyData: Record<string, unknown>, headers: Record<string, string>): unknown;
-export declare function createRestApiTool(parsed: {
-    name: string;
-    description: string;
-    endpoint: OperationEndpoint;
-    operation: OpenAPIV3.OperationObject;
-    authScheme?: OpenAPIV3.SecuritySchemeObject;
-}, options?: {
+/**
+ * Builds a `RestApiTool` from a parsed operation.
+ *
+ * @param parsed The operation, with the parameters already parsed when the
+ *   caller has them.
+ * @param options Options forwarded to the tool and to its operation parser.
+ * @returns The tool for that operation.
+ */
+export declare function createRestApiTool(parsed: ParsedOperationInput, options?: {
     preservePropertyNames?: boolean;
     headerProvider?: (context: ReadonlyContext) => Record<string, string>;
     credentialKey?: string;
 }): RestApiTool;
+/**
+ * Builds a `RestApiTool` from the JSON string form of a parsed operation.
+ *
+ * This is the only entry point that accepts undecoded input, so it is where
+ * the auth scheme is checked. A scheme reaching `createRestApiTool` as an
+ * object is already constrained by its type.
+ *
+ * @param parsedOperationJson A serialized {@link ParsedOperationInput}.
+ * @returns The tool for that operation.
+ * @throws {Error} If the auth scheme does not declare a known `type`.
+ */
+export declare function createRestApiToolFromJson(parsedOperationJson: string): RestApiTool;

package/dist/types/tools/tool_context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The tool-facing names for the unified agent context.
+ *
+ * `ToolContext` and `CallbackContext` are aliases of {@link Context}, not
+ * subclasses, so a context the framework builds satisfies either name. This
+ * mirrors `adk-python`'s `google.adk.tools.tool_context`, which binds
+ * `ToolContext = Context`.
+ *
+ * Python also re-exports `AuthHandler`, `AuthConfig` and `AuthCredential` from
+ * this module. adk-js does not: the package `exports` map has no entry for this
+ * path, so no consumer can import them from here, and all three already ship
+ * from the package root.
+ */
+export { Context as CallbackContext, Context as ToolContext, } from '../agents/context.js';

package/dist/types/tools/webmcp/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * `@google/adk/tools/webmcp` subpath: the WebMCP tools only, without the full
+ * ADK barrel. Also re-exported from `@google/adk`.
+ */
+export * from './webmcp_tool.js';
+export * from './webmcp_toolset.js';
+export * from './webmcp_types.js';

package/dist/types/tools/webmcp/webmcp_tool.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { BaseTool, RunAsyncToolRequest } from '../base_tool.js';
+import { WebMCPDocument, WebMCPRegisteredTool } from './webmcp_types.js';
+/** Parameters for {@link WebMCPTool}. */
+export interface WebMCPToolParams {
+    /** The tool as reported by `document.modelContext.getTools()`. */
+    tool: WebMCPRegisteredTool;
+    /**
+     * Overrides the name exposed to the model, which the toolset uses to apply
+     * its prefix. Defaults to the tool's own name.
+     */
+    name?: string;
+    /** Document to read `modelContext` from. Defaults to the global document. */
+    document?: WebMCPDocument;
+}
+/**
+ * A tool registered by the page on `document.modelContext`.
+ *
+ * Converts the tool's JSON Schema into a Gemini `FunctionDeclaration` and
+ * executes it through `document.modelContext.executeTool()`, so the page runs
+ * its own handler and updates its own UI.
+ *
+ * A tool annotated `consequentialHint` reports itself as requiring
+ * confirmation, so significant page actions flow through ADK's existing tool
+ * confirmation rather than firing unprompted.
+ */
+export declare class WebMCPTool extends BaseTool {
+    readonly webmcpTool: WebMCPRegisteredTool;
+    private readonly doc?;
+    constructor(params: WebMCPToolParams);
+    /**
+     * The tool's JSON Schema as an object.
+     *
+     * `inputSchema` is specified as an object, but a browser handing back a JSON
+     * string would otherwise convert to a parameterless declaration, leaving the
+     * model no argument names to fill in — it then calls the tool with `{}`.
+     */
+    private resolveInputSchema;
+    _getDeclaration(): FunctionDeclaration;
+    checkRequireConfirmation(): Promise<boolean>;
+    runAsync(request: RunAsyncToolRequest): Promise<unknown>;
+}

package/dist/types/tools/webmcp/webmcp_toolset.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReadonlyContext } from '../../agents/readonly_context.js';
+import { BaseTool } from '../base_tool.js';
+import { BaseToolset, ToolPredicate } from '../base_toolset.js';
+import { WebMCPDocument } from './webmcp_types.js';
+/** Options for {@link WebMCPToolset}. */
+export interface WebMCPToolsetOptions {
+    /** Restricts which tools reach the model, by name or predicate. */
+    toolFilter?: ToolPredicate | string[];
+    /** Prefixes every discovered tool name with `${prefix}_`. */
+    prefix?: string;
+    /**
+     * Secure origins to also collect tools from, for cross-origin iframes. A
+     * cross-origin tool is only returned if its page also exposed it to this
+     * origin via `exposedTo`.
+     */
+    fromOrigins?: string[];
+    /** Document to read `modelContext` from. Defaults to the global document. */
+    document?: WebMCPDocument;
+}
+/**
+ * A toolset backed by the tools a web page registers with WebMCP.
+ *
+ * WebMCP lets a page declare typed, callable tools on `document.modelContext`.
+ * This toolset surfaces them to an in-browser agent, so the agent drives the
+ * page through the handlers it published instead of scraping the DOM. Each
+ * tool's own `execute` runs in the page, so its UI updates as a side effect.
+ *
+ * Unlike {@link MCPToolset}, nothing is transported anywhere: discovery and
+ * execution are same-document browser calls.
+ *
+ * Outside a browser, or in a browser without WebMCP, `getTools()` returns an
+ * empty array rather than throwing, so this is safe to construct anywhere.
+ *
+ * @example
+ * ```ts
+ * import {LlmAgent} from '@google/adk';
+ * import {WebMCPToolset} from '@google/adk/tools/webmcp';
+ *
+ * const agent = new LlmAgent({
+ *   name: 'page_agent',
+ *   model: 'gemini-3.8-live',
+ *   tools: [new WebMCPToolset()],
+ * });
+ * ```
+ *
+ * @see https://developer.chrome.com/docs/ai/webmcp
+ */
+export declare class WebMCPToolset extends BaseToolset {
+    private readonly doc?;
+    private readonly fromOrigins?;
+    private readonly changeListeners;
+    constructor(options?: WebMCPToolsetOptions);
+    /** Whether this document exposes WebMCP. */
+    isSupported(): boolean;
+    getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
+    /**
+     * Subscribes to the WebMCP `toolchange` event, which fires when the page
+     * registers or removes tools. Returns an unsubscribe function.
+     */
+    onToolChange(listener: () => void): () => void;
+    close(): Promise<void>;
+}

package/dist/types/tools/webmcp/webmcp_types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Minimal structural types for the WebMCP browser API.
+ *
+ * Declared here rather than taken from the `webmcp-types` package so the core
+ * package gains no dependency for a browser-only, still-experimental API. They
+ * describe only the surface this toolset uses.
+ *
+ * @see https://developer.chrome.com/docs/ai/webmcp
+ */
+/** Metadata a page may attach to a registered tool. */
+export interface WebMCPToolAnnotations {
+    /** The tool only reads state. */
+    readOnlyHint?: boolean;
+    /** The tool's output may contain untrusted content. */
+    untrustedContentHint?: boolean;
+    /** The tool performs a significant or non-reversible real-world action. */
+    consequentialHint?: boolean;
+}
+/** A tool as reported by `document.modelContext.getTools()`. */
+export interface WebMCPRegisteredTool {
+    name: string;
+    title?: string;
+    description?: string;
+    /**
+     * JSON Schema for the tool's arguments.
+     *
+     * Typed loosely on purpose: the specification says object, but browsers have
+     * been observed handing back a JSON string, and a schema that is silently
+     * misread leaves the model unable to pass any arguments at all.
+     */
+    inputSchema?: object | string;
+    annotations?: WebMCPToolAnnotations;
+    origin?: string;
+}
+/** Options accepted by `getTools()`. */
+export interface WebMCPGetToolsOptions {
+    /** Secure origins to include tools from, for cross-origin iframes. */
+    fromOrigins?: string[];
+}
+/** Options accepted by `executeTool()`. */
+export interface WebMCPExecuteToolOptions {
+    signal?: AbortSignal;
+}
+/** The `document.modelContext` object. */
+export interface WebMCPModelContext extends EventTarget {
+    getTools(options?: WebMCPGetToolsOptions): Promise<WebMCPRegisteredTool[]>;
+    executeTool(tool: WebMCPRegisteredTool, args?: unknown, options?: WebMCPExecuteToolOptions): Promise<unknown>;
+}
+/** A Document that may expose WebMCP. */
+export interface WebMCPDocument {
+    modelContext?: WebMCPModelContext;
+}
+/**
+ * Returns the WebMCP entry point for a document, or undefined when the browser
+ * does not expose one.
+ */
+export declare function getModelContext(doc?: WebMCPDocument): WebMCPModelContext | undefined;
+/**
+ * Whether WebMCP is available.
+ *
+ * False outside a browser and in browsers without the API, so importing this
+ * module from Node is harmless.
+ */
+export declare function isWebMCPSupported(doc?: WebMCPDocument): boolean;

package/dist/types/utils/case_utils.d.ts

@@ -10,3 +10,39 @@
  * @returns The converted value.
  */
 export declare function camelCaseKeys(val: unknown): unknown;
+/**
+ * Converts one string into snake_case.
+ *
+ * Handles lowerCamelCase, UpperCamelCase and space-separated text, as well as
+ * acronyms such as `REST API` and runs of consecutive uppercase letters.
+ *
+ * The `Name` suffix separates this from `toSnakeCase` in
+ * `object_notation_utils.ts`, which converts the keys of an object and takes a
+ * different argument.
+ *
+ * @example
+ * ```ts
+ * toSnakeCaseName('camelCase'); // 'camel_case'
+ * toSnakeCaseName('UpperCamelCase'); // 'upper_camel_case'
+ * toSnakeCaseName('REST API'); // 'rest_api'
+ * ```
+ *
+ * @param text The input string.
+ * @returns The snake_case form of `text`.
+ */
+export declare function toSnakeCaseName(text: string): string;
+/**
+ * Prefixes a Python keyword, the way adk-python's `rename_python_keywords`
+ * does. Mirrors the reference exactly: the set is Python's, not TypeScript's.
+ *
+ * @example
+ * ```ts
+ * renameReservedKeywords('in'); // 'param_in'
+ * renameReservedKeywords('total'); // 'total'
+ * ```
+ *
+ * @param s The candidate identifier.
+ * @param prefix The prefix to add when `s` is reserved.
+ * @returns `prefix + s` when `s` is reserved, otherwise `s` unchanged.
+ */
+export declare function renameReservedKeywords(s: string, prefix?: string): string;