@softactivate/adk 1.1.0

package/dist/types/auth/oauth2/oauth2_credential_exchanger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../auth_credential.js';
+import { AuthScheme, OAuthGrantType } from '../auth_schemes.js';
+import { BaseCredentialExchanger, ExchangeResult } from '../exchanger/base_credential_exchanger.js';
+/**
+ * Exchanges OAuth2 credentials from authorization responses using standard fetch.
+ */
+export declare class OAuth2CredentialExchanger implements BaseCredentialExchanger {
+    exchange({ authCredential, authScheme, }: {
+        authCredential: AuthCredential;
+        authScheme?: AuthScheme;
+    }): Promise<ExchangeResult>;
+}
+export declare function determineGrantType(authScheme: AuthScheme): OAuthGrantType | undefined;
+export declare function exchangeClientCredentials({ authCredential, authScheme, }: {
+    authCredential: AuthCredential;
+    authScheme: AuthScheme;
+}): Promise<ExchangeResult>;
+export declare function exchangeAuthorizationCode({ authCredential, authScheme, }: {
+    authCredential: AuthCredential;
+    authScheme: AuthScheme;
+}): Promise<ExchangeResult>;

package/dist/types/auth/oauth2/oauth2_credential_refresher.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../auth_credential.js';
+import { AuthScheme } from '../auth_schemes.js';
+import { BaseCredentialRefresher } from '../refresher/base_credential_refresher.js';
+/**
+ * Refreshes OAuth2 credentials using standard fetch.
+ */
+export declare class OAuth2CredentialRefresher implements BaseCredentialRefresher {
+    /**
+     * Check if the OAuth2 credential needs to be refreshed.
+     *
+     * @param authCredential The OAuth2 credential to check.
+     * @param authScheme The OAuth2 authentication scheme (optional).
+     * @returns True if the credential needs to be refreshed, False otherwise.
+     */
+    isRefreshNeeded(authCredential: AuthCredential): Promise<boolean>;
+    /**
+     * Refresh the OAuth2 credential.
+     *
+     * @param authCredential The OAuth2 credential to refresh.
+     * @param authScheme The OAuth2 authentication scheme.
+     * @returns The refreshed credential.
+     */
+    refresh(authCredential: AuthCredential, authScheme?: AuthScheme): Promise<AuthCredential>;
+}

package/dist/types/auth/oauth2/oauth2_discovery.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+/**
+ * Represents the OAuth2 authorization server metadata per RFC8414.
+ */
+export declare const AuthorizationServerMetadataSchema: z.ZodObject<{
+    issuer: z.ZodString;
+    authorization_endpoint: z.ZodString;
+    token_endpoint: z.ZodString;
+    scopes_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    registration_endpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AuthorizationServerMetadata = z.infer<typeof AuthorizationServerMetadataSchema>;
+/**
+ * Represents the OAuth2 protected resource metadata per RFC9728.
+ */
+export declare const ProtectedResourceMetadataSchema: z.ZodObject<{
+    resource: z.ZodString;
+    authorization_servers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ProtectedResourceMetadata = z.infer<typeof ProtectedResourceMetadataSchema>;
+/**
+ * Implements Metadata discovery for OAuth2 following RFC8414 and RFC9728.
+ */
+export declare class OAuth2DiscoveryManager {
+    /**
+     * Discovers the OAuth2 authorization server metadata.
+     */
+    discoverAuthServerMetadata(issuerUrl: string): Promise<AuthorizationServerMetadata | undefined>;
+    /**
+     * Discovers the OAuth2 protected resource metadata.
+     */
+    discoverResourceMetadata(resourceUrl: string): Promise<ProtectedResourceMetadata | undefined>;
+}

package/dist/types/auth/oauth2/oauth2_utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { OAuth2Auth } from '../auth_credential.js';
+import { AuthScheme } from '../auth_schemes.js';
+/**
+ * Returns the token endpoint for the given auth scheme.
+ */
+export declare function getTokenEndpoint(authScheme: AuthScheme): string | undefined;
+/**
+ * Fetches OAuth2 tokens from the endpoint using the given body.
+ */
+export declare function fetchOAuth2Tokens(endpoint: string, body: URLSearchParams): Promise<OAuth2Auth>;
+/**
+ * Parses the authorization code from an authorization response URI.
+ */
+export declare function parseAuthorizationCode(uri: string): string | undefined;
+/**
+ * Parameters for a Client Credentials token request.
+ */
+export interface ClientCredentialsParams {
+    grantType: 'client_credentials';
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Parameters for an Authorization Code token request.
+ */
+export interface AuthorizationCodeParams {
+    grantType: 'authorization_code';
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri?: string;
+    codeVerifier?: string;
+}
+/**
+ * Parameters for a Refresh Token request.
+ */
+export interface RefreshTokenParams {
+    grantType: 'refresh_token';
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+}
+/**
+ * Parameters for creating an OAuth2 token request body.
+ */
+export type OAuth2TokenRequestParams = ClientCredentialsParams | AuthorizationCodeParams | RefreshTokenParams;
+/**
+ * Creates URLSearchParams for an OAuth2 token request.
+ */
+export declare function createOAuth2TokenRequestBody(params: OAuth2TokenRequestParams): URLSearchParams;
+export declare function isTokenExpired(token: OAuth2Auth, leeway?: number): boolean;

package/dist/types/auth/refresher/base_credential_refresher.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredential } from '../auth_credential.js';
+import { AuthScheme } from '../auth_schemes.js';
+/**
+ * Base exception for credential refresh errors.
+ */
+export declare class CredentialRefresherError extends Error {
+    constructor(message: string);
+}
+/**
+ * Base interface for credential refreshers.
+ *
+ * Credential refreshers are responsible for checking if a credential is expired
+ * or needs to be refreshed, and for refreshing it if necessary.
+ */
+export interface BaseCredentialRefresher {
+    /**
+     * Checks if a credential needs to be refreshed.
+     *
+     * @param authCredential The credential to check.
+     * @param authScheme The authentication scheme (optional).
+     * @returns True if the credential needs to be refreshed, False otherwise.
+     */
+    isRefreshNeeded(authCredential: AuthCredential, authScheme?: AuthScheme): Promise<boolean>;
+    /**
+     * Refreshes a credential if needed.
+     *
+     * @param authCredential The credential to refresh.
+     * @param authScheme The authentication scheme (optional).
+     * @returns The refreshed credential.
+     * @throws {CredentialRefresherError} If credential refresh fails.
+     */
+    refresh(authCredential: AuthCredential, authScheme?: AuthScheme): Promise<AuthCredential>;
+}

package/dist/types/auth/refresher/credential_refresher_registry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthCredentialTypes } from '../auth_credential.js';
+import { BaseCredentialRefresher } from './base_credential_refresher.js';
+/**
+ * Registry for credential refresher instances.
+ */
+export declare class CredentialRefresherRegistry {
+    private readonly refreshers;
+    /**
+     * Register a refresher instance for a credential type.
+     *
+     * @param credentialType The credential type to register for.
+     * @param refresherInstance The refresher instance to register.
+     */
+    register(credentialType: AuthCredentialTypes, refresherInstance: BaseCredentialRefresher): void;
+    /**
+     * Get the refresher instance for a credential type.
+     *
+     * @param credentialType The credential type to get refresher for.
+     * @returns The refresher instance if registered, undefined otherwise.
+     */
+    getRefresher(credentialType: AuthCredentialTypes): BaseCredentialRefresher | undefined;
+}

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

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { InvocationContext } from '../agents/invocation_context.js';
+import { CodeExecutionInput, CodeExecutionResult } from './code_execution_utils.js';
+/**
+ * The parameters for executing code.
+ * */
+export interface ExecuteCodeParams {
+    /** The invocation context of the code execution. */
+    invocationContext: InvocationContext;
+    /** The input of the code execution. */
+    codeExecutionInput: CodeExecutionInput;
+}
+/**
+ * A unique symbol to identify BaseCodeExecutor classes.
+ * Defined once and shared by all BaseCodeExecutor instances.
+ */
+declare const BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of BaseCodeExecutor.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of BaseCodeExecutor, false otherwise.
+ */
+export declare function isBaseCodeExecutor(obj: unknown): obj is BaseCodeExecutor;
+/**
+ * The code executor allows the agent to execute code blocks from model
+ * responses and incorporate the execution results into the final response.
+ */
+export declare abstract class BaseCodeExecutor {
+    /** A unique symbol to identify BaseCodeExecutor class. */
+    readonly [BASE_CODE_EXECUTOR_SIGNATURE_SYMBOL] = true;
+    /**
+     * If true, extract and process data files from the model request
+     * and attach them to the code executor.
+     *
+     * Supported data file MimeTypes are [text/csv].
+     * Default to false.
+     */
+    optimizeDataFile: boolean;
+    /**
+     * Whether the code executor is stateful. Default to false.
+     */
+    stateful: boolean;
+    /**
+     * The number of attempts to retry on consecutive code execution errors.
+     * Default to 2.
+     */
+    errorRetryAttempts: number;
+    /**
+     * The list of the enclosing delimiters to identify the code blocks.
+     * For example, the delimiter('```javascript\\n', '\\n```') can be used to
+     * identify code blocks with the following format:
+     *
+     * ```javascript
+     *  console.log("hello")
+     * ```
+     */
+    codeBlockDelimiters: Array<[string, string]>;
+    /**
+     * The delimiters to format the code execution result.
+     */
+    executionResultDelimiters: [string, string];
+    /**
+     * Executes code and return the code execution result.
+     *
+     * @param params The parameters for executing code.
+     * @return The result of the code execution.
+     */
+    abstract executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult>;
+}
+export {};

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

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LlmRequest } from '../models/llm_request.js';
+import { BaseCodeExecutor, ExecuteCodeParams } from './base_code_executor.js';
+import { CodeExecutionResult } from './code_execution_utils.js';
+/**
+ * A unique symbol to identify BuiltInCodeExecutor classes.
+ * Defined once and shared by all BuiltInCodeExecutor instances.
+ */
+declare const BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of BuiltInCodeExecutor.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of BuiltInCodeExecutor, false otherwise.
+ */
+export declare function isBuiltInCodeExecutor(obj: unknown): obj is BuiltInCodeExecutor;
+/**
+ * A code executor that uses the Model's built-in code executor.
+ *
+ * Currently only supports Gemini 2.0+ models, but will be expanded to
+ * other models.
+ */
+export declare class BuiltInCodeExecutor extends BaseCodeExecutor {
+    /** A unique symbol to identify BuiltInCodeExecutor class. */
+    readonly [BUILT_IN_CODE_EXECUTOR_SIGNATURE_SYMBOL] = true;
+    executeCode(_params: ExecuteCodeParams): Promise<CodeExecutionResult>;
+    processLlmRequest(llmRequest: LlmRequest): void;
+}
+export {};

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

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content, Part } from '@google/genai';
+export declare enum FileContentEncoding {
+    UTF8 = "utf-8",
+    BASE64 = "base64"
+}
+/**
+ * A structure that contains a file name and its content
+ */
+export interface File {
+    /**
+     * The name of the file with file extension(e.g., ' file.csv')
+     * */
+    name: string;
+    /**
+     * The encoded bytes of the file content.
+     * */
+    content: string;
+    /**
+     * The encoding of the file content.
+     */
+    contentEncoding?: FileContentEncoding;
+    /**
+     * The mime type of the file (e.g., ' image / png')
+     * */
+    mimeType: string;
+}
+/**
+ * The language of the code to execute.
+ */
+export declare enum CodeExecutionLanguage {
+    UNSPECIFIED = "unspecified",
+    PYTHON = "python",
+    JAVASCRIPT = "javascript",
+    TYPESCRIPT = "typescript",
+    SHELL = "shell",
+    POWERSHELL = "powershell",
+    WINDOWS_CMD = "cmd"
+}
+/**
+ * A structure that contains the input of code execution.
+ * */
+export interface CodeExecutionInput {
+    /**
+     * The code to execute.
+     * */
+    code: string;
+    /**
+     * The language of the code to execute.
+     */
+    language: CodeExecutionLanguage;
+    /**
+     * The input files available to the code.
+     * */
+    inputFiles: File[];
+    /**
+     * The execution ID for the stateful code execution.
+     * */
+    executionId?: string;
+    /**
+     * Optional arguments to pass to the executed code/script.
+     */
+    args?: string[] | Record<string, string | number | boolean>;
+}
+/**
+ * A structure that contains the result of code execution.
+ * */
+export interface CodeExecutionResult {
+    /**
+     * The standard output of the code execution.
+     * */
+    stdout: string;
+    /**
+     * The standard error of the code execution.
+     * */
+    stderr: string;
+    /**
+     * The output files from the code execution.
+     * */
+    outputFiles: File[];
+}
+/**
+ * Gets the file content as a base64-encoded bytes.
+ *
+ * @param data The file content bytes.
+ * @return The file content as a base64-encoded bytes.
+ */
+export declare function getEncodedFileContent(data: string): string;
+/**
+ * Extracts the first code block from the content and truncate everything after
+ * it.
+ *
+ * @param content The mutable content to extract the code from.
+ * @param codeBlockDelimiters The list of the enclosing delimiters to identify
+ *     the code blocks.
+ * @return The first code block if found, otherwise None.
+ */
+export declare function extractCodeAndTruncateContent(content: Content, codeBlockDelimiters: Array<[string, string]>): string;
+/**
+ * Builds an executable code part with code string.
+ *
+ * @param code The code string.
+ * @return The constructed executable code part.
+ */
+export declare function buildExecutableCodePart(code: string): Part;
+/**
+ * Builds the code execution result part from the code execution result.
+ *
+ * @param codeExecutionResult The code execution result.
+ * @return The code execution result part.
+ */
+export declare function buildCodeExecutionResultPart(codeExecutionResult: CodeExecutionResult): Part;
+/**
+ * Converts the code execution parts to text parts in a Content.
+ *
+ * @param content The mutable content to convert the code execution parts to
+ *     text parts.
+ * @param codeBlockDelimiter The delimiter to format the code block.
+ * @param executionResultDelimiters The delimiter to format the code execution
+ *     result.
+ * @return The converted content.
+ */
+export declare function convertCodeExecutionParts(content: Content, codeBlockDelimiter: [string, string], executionResultDelimiters: [string, string]): void;

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

@@ -0,0 +1,85 @@
+import { State } from '../sessions/state.js';
+import { File } from './code_execution_utils.js';
+/**
+ * The parameters for updating the code execution result.
+ * */
+export interface UpdateCodeExecutionResultParams {
+    invocationId: string;
+    code: string;
+    resultStdout: string;
+    resultStderr: string;
+}
+/**
+ * The persistent context used to configure the code executor.
+ */
+export declare class CodeExecutorContext {
+    private readonly sessionState;
+    private readonly context;
+    constructor(sessionState: State);
+    /**
+     * Gets the state delta to update in the persistent session state.
+     * @return The state delta to update in the persistent session state.
+     */
+    getStateDelta(): Record<string, unknown>;
+    /**
+     * Gets the execution ID for the code executor.
+     * @return The execution ID for the code executor.
+     */
+    getExecutionId(): string | undefined;
+    /**
+     * Sets the execution ID for the code executor.
+     * @param executionId The execution ID to set.
+     */
+    setExecutionId(executionId: string): void;
+    /**
+     * Gets the processed file names from the session state.
+     * @return A list of processed file names in the code executor context.
+     */
+    getProcessedFileNames(): string[];
+    /**
+     * Adds the processed file names to the session state.
+     * @param fileNames The file names to add to the session state.
+     */
+    addProcessedFileNames(fileNames: string[]): void;
+    /**
+     * Gets the input files from the session state.
+     * @return A list of input files in the code executor context.
+     */
+    getInputFiles(): File[];
+    /**
+     * Adds the input files to the session state.
+     * @param inputFiles The input files to add to the session state.
+     */
+    addInputFiles(inputFiles: File[]): void;
+    clearInputFiles(): void;
+    /**
+     * Gets the error count from the session state.
+     * @param invocationId The invocation ID to get the error count for.
+     * @return The error count for the given invocation ID.
+     */
+    getErrorCount(invocationId: string): number;
+    /**
+     * Increments the error count from the session state.
+     * @param invocationId The invocation ID to increment the error count for.
+     */
+    incrementErrorCount(invocationId: string): void;
+    /**
+     * Resets the error count from the session state.
+     * @param invocationId The invocation ID to reset the error count for.
+     */
+    resetErrorCount(invocationId: string): void;
+    /**
+     * Updates the code execution result.
+     * @param invocationId The invocation ID to update the code execution result
+     *     for.
+     * @param code The code to execute.
+     * @param resultStdout The standard output of the code execution.
+     * @param resultStderr The standard error of the code execution.
+     */
+    updateCodeExecutionResult({ invocationId, code, resultStdout, resultStderr, }: UpdateCodeExecutionResultParams): void;
+    /**
+     * Gets the code execution context from the session state.
+     * @return The code execution context for the given invocation ID.
+     */
+    getCodeExecutionContext(): Record<string, unknown>;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseCodeExecutor, ExecuteCodeParams } from './base_code_executor.js';
+import { CodeExecutionResult } from './code_execution_utils.js';
+/**
+ * Options for UnsafeLocalCodeExecutor.
+ */
+export interface UnsafeLocalCodeExecutorOptions {
+    /**
+     * Timeout for code execution in seconds. Default is 30.
+     */
+    timeoutSeconds?: number;
+    /**
+     * The command to run JavaScript code. Default is `process.execPath` (Node.js).
+     */
+    commandPath?: string;
+    /**
+     * The command to run Python code. Default is `python3`.
+     */
+    pythonCommandPath?: string;
+    /**
+     * The command to run Shell code. Default is `bash`.
+     */
+    shellCommandPath?: string;
+}
+/**
+ * A code executor that unsafely executes code in the local context.
+ * Supports JavaScript, Python, and Shell capabilities cross-platform.
+ *
+ * **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.
+ *
+ * WARNING: This executor runs code in the local environment without sandboxing or security restrictions.
+ * Use with caution and only for trusted code.
+ */
+export declare class UnsafeLocalCodeExecutor extends BaseCodeExecutor {
+    private readonly timeoutSeconds;
+    private readonly nodeCommandPath;
+    private readonly pythonCommandPath;
+    private readonly shellCommandPath;
+    constructor(options?: UnsafeLocalCodeExecutorOptions);
+    executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult>;
+}