@softactivate/adk 1.1.0

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

@@ -0,0 +1,175 @@
+/**
+ * @license
+ * Copyright 2025 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, ContextCompactionTrigger } from './base_plugin.js';
+/**
+ * Manages the registration and execution of plugins.
+ *
+ * The PluginManager is an internal class that orchestrates the invocation of
+ * plugin callbacks at key points in the SDK's execution lifecycle. It maintains
+ * a list of registered plugins and ensures they are called in the order they
+ * were registered.
+ *
+ * The core execution logic implements an "early exit" strategy: if any plugin
+ * callback returns a non-`undefined` value, the execution of subsequent plugins
+ * for that specific event is halted, and the returned value is propagated up
+ * the call stack. This allows plugins to short-circuit operations like agent
+ * runs, tool calls, or model requests.
+ */
+export declare class PluginManager {
+    private readonly plugins;
+    /**
+     * Initializes the plugin service.
+     *
+     * @param plugins An optional list of plugins to register upon
+     *     initialization.
+     */
+    constructor(plugins?: BasePlugin[]);
+    /**
+     * Registers a new plugin.
+     *
+     * @param plugin The plugin instance to register.
+     * @throws If the same exact plugin or a plugin with the same name is already
+     *     registered.
+     */
+    registerPlugin(plugin: BasePlugin): void;
+    /**
+     * Retrieves a registered plugin by its name.
+     *
+     * @param pluginName The name of the plugin to retrieve.
+     * @returns The plugin instance if found, otherwise `undefined`.
+     */
+    getPlugin(pluginName: string): BasePlugin | undefined;
+    /**
+     * Runs the same callback for all plugins. This is a utility method to reduce
+     * duplication below.
+     *
+     * @param plugins The set of plugins to run
+     * @param callback A closure containing the callback method to run on each
+     *     plugin
+     * @param callbackName The name of the function being called in the closure
+     *     above. Used for logging purposes.
+     * @returns A promise containing the plugin method result. Must be casted to
+     *     the proper type for the plugin method.
+     */
+    private runCallbacks;
+    /**
+     * Runs the `onUserMessageCallback` for all plugins.
+     */
+    runOnUserMessageCallback({ userMessage, invocationContext, }: {
+        userMessage: Content;
+        invocationContext: InvocationContext;
+    }): Promise<Content | undefined>;
+    /**
+     * Runs the `beforeRunCallback` for all plugins.
+     */
+    runBeforeRunCallback({ invocationContext, }: {
+        invocationContext: InvocationContext;
+    }): Promise<Content | undefined>;
+    /**
+     * Runs the `afterRunCallback` for all plugins.
+     */
+    runAfterRunCallback({ invocationContext, }: {
+        invocationContext: InvocationContext;
+    }): Promise<void>;
+    /**
+     * Runs the `onEventCallback` for all plugins.
+     */
+    runOnEventCallback({ invocationContext, event, }: {
+        invocationContext: InvocationContext;
+        event: Event;
+    }): Promise<Event | undefined>;
+    /**
+     * Runs the `beforeAgentCallback` for all plugins.
+     */
+    runBeforeAgentCallback({ agent, callbackContext, }: {
+        agent: BaseAgent;
+        callbackContext: Context;
+    }): Promise<Content | undefined>;
+    /**
+     * Runs the `afterAgentCallback` for all plugins.
+     */
+    runAfterAgentCallback({ agent, callbackContext, }: {
+        agent: BaseAgent;
+        callbackContext: Context;
+    }): Promise<Content | undefined>;
+    /**
+     * Runs the `beforeToolSelection` for all plugins.
+     */
+    runBeforeToolSelection({ callbackContext, tools, }: {
+        callbackContext: Context;
+        tools: Readonly<Record<string, BaseTool>>;
+    }): Promise<Readonly<Record<string, BaseTool>> | undefined>;
+    /**
+     * Runs the `beforeContextCompaction` for all plugins.
+     */
+    runBeforeContextCompaction({ invocationContext, trigger, }: {
+        invocationContext: InvocationContext;
+        trigger: ContextCompactionTrigger;
+    }): Promise<void>;
+    /**
+     * Runs the `afterContextCompaction` for all plugins.
+     */
+    runAfterContextCompaction({ invocationContext, trigger, }: {
+        invocationContext: InvocationContext;
+        trigger: ContextCompactionTrigger;
+    }): Promise<void>;
+    /**
+     * Runs the `beforeToolCallback` for all plugins.
+     */
+    runBeforeToolCallback({ tool, toolArgs, toolContext, }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+    }): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Runs the `afterToolCallback` for all plugins.
+     */
+    runAfterToolCallback({ tool, toolArgs, toolContext, result, }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+        result: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Runs the `onModelErrorCallback` for all plugins.
+     */
+    runOnModelErrorCallback({ callbackContext, llmRequest, error, }: {
+        callbackContext: Context;
+        llmRequest: LlmRequest;
+        error: Error;
+    }): Promise<LlmResponse | undefined>;
+    /**
+     * Runs the `beforeModelCallback` for all plugins.
+     */
+    runBeforeModelCallback({ callbackContext, llmRequest, }: {
+        callbackContext: Context;
+        llmRequest: LlmRequest;
+    }): Promise<LlmResponse | undefined>;
+    /**
+     * Runs the `afterModelCallback` for all plugins.
+     */
+    runAfterModelCallback({ callbackContext, llmResponse, }: {
+        callbackContext: Context;
+        llmResponse: LlmResponse;
+    }): Promise<LlmResponse | undefined>;
+    /**
+     * Runs the `onToolErrorCallback` for all plugins.
+     */
+    runOnToolErrorCallback({ tool, toolArgs, toolContext, error, }: {
+        tool: BaseTool;
+        toolArgs: Record<string, unknown>;
+        toolContext: Context;
+        error: Error;
+    }): Promise<Record<string, unknown> | undefined>;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionCall } from '@google/genai';
+import { Context } from '../agents/context.js';
+import { Event } from '../events/event.js';
+import { BasePlugin } from '../plugins/base_plugin.js';
+import { BaseTool } from '../tools/base_tool.js';
+export declare const REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
+/**
+ * The outcome of a policy check.
+ */
+export declare enum PolicyOutcome {
+    DENY = "DENY",
+    CONFIRM = "CONFIRM",
+    ALLOW = "ALLOW"
+}
+export interface PolicyCheckResult {
+    outcome: string;
+    reason?: string;
+}
+export interface ToolCallPolicyContext {
+    tool: BaseTool;
+    toolArgs: Record<string, unknown>;
+}
+export interface BasePolicyEngine {
+    evaluate(context: ToolCallPolicyContext): Promise<PolicyCheckResult>;
+}
+export declare class InMemoryPolicyEngine implements BasePolicyEngine {
+    evaluate(): Promise<PolicyCheckResult>;
+}
+/**
+ *  Security Plugin for running Orcas agents.
+ */
+export declare class SecurityPlugin extends BasePlugin {
+    private readonly policyEngine;
+    constructor(params?: {
+        policyEngine?: BasePolicyEngine;
+    });
+    beforeToolCallback({ tool, toolArgs, toolContext, }: {
+        tool: BaseTool;
+        toolArgs: {
+            [key: string]: unknown;
+        };
+        toolContext: Context;
+    }): Promise<{
+        [key: string]: unknown;
+    } | undefined>;
+    private getToolCallCheckState;
+    private setToolCallCheckState;
+    private checkToolCallPolicy;
+}
+/**
+ * Gets the ask user confirmation function calls from the event.
+ * @param event The event to get the function calls from.
+ * @returns The ask user confirmation function calls.
+ */
+export declare function getAskUserConfirmationFunctionCalls(event: Event): FunctionCall[];

package/dist/types/runner/in_memory_runner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseAgent } from '../agents/base_agent.js';
+import { BasePlugin } from '../plugins/base_plugin.js';
+import { Runner } from './runner.js';
+export declare class InMemoryRunner extends Runner {
+    constructor({ agent, appName, plugins, }: {
+        agent: BaseAgent;
+        appName?: string;
+        plugins?: BasePlugin[];
+    });
+}

package/dist/types/runner/runner.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import { BaseAgent } from '../agents/base_agent.js';
+import { RunConfig } from '../agents/run_config.js';
+import { BaseArtifactService } from '../artifacts/base_artifact_service.js';
+import { BaseCredentialService } from '../auth/credential_service/base_credential_service.js';
+import { Event } from '../events/event.js';
+import { BaseMemoryService } from '../memory/base_memory_service.js';
+import { BasePlugin } from '../plugins/base_plugin.js';
+import { PluginManager } from '../plugins/plugin_manager.js';
+import { BaseSessionService } from '../sessions/base_session_service.js';
+/**
+ * The configuration parameters for the Runner.
+ */
+export interface RunnerConfig {
+    /**
+     * The application name.
+     */
+    appName: string;
+    /**
+     * The agent to run.
+     */
+    agent: BaseAgent;
+    plugins?: BasePlugin[];
+    artifactService?: BaseArtifactService;
+    sessionService: BaseSessionService;
+    memoryService?: BaseMemoryService;
+    credentialService?: BaseCredentialService;
+}
+/**
+ * A unique symbol to identify ADK agent classes.
+ * Defined once and shared by all Runner instances.
+ */
+declare const RUNNER_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of Runner.
+ * @param obj The object to check.
+ * @returns True if the object is an instance of Runner, false otherwise.
+ */
+export declare function isRunner(obj: unknown): obj is Runner;
+export declare class Runner {
+    readonly [RUNNER_SIGNATURE_SYMBOL] = true;
+    readonly appName: string;
+    readonly agent: BaseAgent;
+    readonly pluginManager: PluginManager;
+    readonly artifactService?: BaseArtifactService;
+    readonly sessionService: BaseSessionService;
+    readonly memoryService?: BaseMemoryService;
+    readonly credentialService?: BaseCredentialService;
+    constructor(input: RunnerConfig);
+    /**
+     * Runs the agent with a new, ephemeral session.
+     *
+     * @param params.userId The user ID of the session.
+     * @param params.newMessage A new message to append to the session.
+     * @param params.stateDelta An optional state delta to apply to the session.
+     * @param params.runConfig The run config for the agent.
+     * @yields The Events generated by the agent.
+     */
+    runEphemeral(params: {
+        userId: string;
+        newMessage: Content;
+        stateDelta?: Record<string, unknown>;
+        runConfig?: RunConfig;
+    }): AsyncGenerator<Event, void, undefined>;
+    /**
+     * Runs the agent with the given message, and returns an async generator of
+     * events.
+     *
+     * @param params.userId The user ID of the session.
+     * @param params.sessionId The session ID of the session.
+     * @param params.newMessage A new message to append to the session.
+     * @param params.stateDelta An optional state delta to apply to the session.
+     * @param params.runConfig The run config for the agent.
+     * @yields The events generated by the agent.
+     */
+    runAsync(params: {
+        userId: string;
+        sessionId: string;
+        newMessage: Content;
+        stateDelta?: Record<string, unknown>;
+        runConfig?: RunConfig;
+        abortSignal?: AbortSignal;
+    }): AsyncGenerator<Event, void, undefined>;
+    /**
+     * Saves artifacts from the message parts and replaces the inline data with
+     * a file name placeholder.
+     *
+     * @param invocationId The current invocation ID.
+     * @param userId The user ID of the session.
+     * @param sessionId The session ID of the session.
+     * @param message The message containing parts to process.
+     */
+    private saveArtifacts;
+    /**
+     * Determines the next agent to run to continue the session. This is primarily
+     * used for session resumption.
+     */
+    private determineAgentForResumption;
+    /**
+     * Whether the agent to run can transfer to any other agent in the agent tree.
+     *
+     * An agent is transferable if:
+     *  - It is an instance of `LlmAgent`.
+     *  - All its ancestors are also transferable (i.e., they have
+     *    `disallowTransferToParent` set to false).
+     *
+     * @param agentToRun The agent to check for transferability.
+     * @returns True if the agent can transfer, False otherwise.
+     */
+    private isRoutableLlmAgent;
+}
+export {};

package/dist/types/sessions/base_session_service.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../events/event.js';
+import { Session } from './session.js';
+/**
+ * The configuration of getting a session.
+ */
+export interface GetSessionConfig {
+    /** The number of recent events to retrieve. */
+    numRecentEvents?: number;
+    /** Retrieve events after this timestamp. */
+    afterTimestamp?: number;
+}
+/**
+ * The parameters for `createSession`.
+ */
+export interface CreateSessionRequest {
+    /** The name of the application. */
+    appName: string;
+    /** The ID of the user. */
+    userId: string;
+    /** The initial state of the session. */
+    state?: Record<string, unknown>;
+    /** The ID of the session. A new ID will be generated if not provided. */
+    sessionId?: string;
+}
+/**
+ * The parameters for `getSession`.
+ */
+export interface GetSessionRequest {
+    /** The name of the application. */
+    appName: string;
+    /** The ID of the user. */
+    userId: string;
+    /** The ID of the session. */
+    sessionId: string;
+    /** The configurations for getting the session. */
+    config?: GetSessionConfig;
+}
+/**
+ * The parameters for `listSessions`.
+ */
+export interface ListSessionsRequest {
+    /** The name of the application. */
+    appName: string;
+    /** The ID of the user. */
+    userId: string;
+}
+/**
+ * The parameters for `deleteSession`.
+ */
+export interface DeleteSessionRequest {
+    /** The name of the application. */
+    appName: string;
+    /** The ID of the user. */
+    userId: string;
+    /** The ID of the session. */
+    sessionId: string;
+}
+/**
+ * The parameters for `appendEvent`.
+ */
+export interface AppendEventRequest {
+    /** The session to append the event to. */
+    session: Session;
+    /** The event to append. */
+    event: Event;
+}
+/**
+ * The response of listing sessions.
+ *
+ * The events and states are not set within each Session object.
+ */
+export interface ListSessionsResponse {
+    /** A list of sessions. */
+    sessions: Session[];
+}
+/**
+ * Base class for session services.
+ *
+ * The service provides a set of methods for managing sessions and events.
+ */
+export declare abstract class BaseSessionService {
+    /**
+     * Creates a new session.
+     *
+     * @param request The request to create a session.
+     * @return A promise that resolves to the newly created session instance.
+     */
+    abstract createSession(request: CreateSessionRequest): Promise<Session>;
+    /**
+     * Gets a session.
+     *
+     * @param request The request to get a session.
+     * @return A promise that resolves to the session instance or undefined if not
+     *     found.
+     */
+    abstract getSession(request: GetSessionRequest): Promise<Session | undefined>;
+    /**
+     * Gets a session or creates one if it doesn't exist.
+     *
+     * @param request The request to get or create a session.
+     * @return A promise that resolves to the session instance.
+     */
+    getOrCreateSession(request: CreateSessionRequest): Promise<Session>;
+    /**
+     * Lists sessions for a user.
+     *
+     * @param request The request to list sessions.
+     * @return A promise that resolves to a list of sessions for the user.
+     */
+    abstract listSessions(request: ListSessionsRequest): Promise<ListSessionsResponse>;
+    /**
+     * Deletes a session.
+     *
+     * @param request The request to delete a session.
+     * @return A promise that resolves when the session is deleted.
+     */
+    abstract deleteSession(request: DeleteSessionRequest): Promise<void>;
+    /**
+     * Appends an event to a session.
+     *
+     * @param request The request to append an event.
+     * @return A promise that resolves to the event that was appended.
+     */
+    appendEvent({ session, event }: AppendEventRequest): Promise<Event>;
+    /**
+     * Updates the session state based on the event.
+     *
+     * @param request The request to update the session state.
+     */
+    private updateSessionState;
+}
+/**
+ * Removes temporary state delta keys from the event.
+ */
+export declare function trimTempDeltaState(event: Event): Event;
+/**
+ * Merges app state, user state, and session state.
+ *
+ * @param appState The application state.
+ * @param userState The user state.
+ * @param sessionState The session state.
+ * @return The merged state.
+ */
+export declare function mergeStates(appState?: Record<string, unknown>, userState?: Record<string, unknown>, sessionState?: Record<string, unknown>): Record<string, unknown>;

package/dist/types/sessions/database_session_service.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Options as MikroDBOptions } from '@mikro-orm/core';
+import { Event } from '../events/event.js';
+import { AppendEventRequest, BaseSessionService, CreateSessionRequest, DeleteSessionRequest, GetSessionRequest, ListSessionsRequest, ListSessionsResponse } from './base_session_service.js';
+import { Session } from './session.js';
+/**
+ * Checks if a URI is a database connection URI.
+ *
+ * @param uri The URI to check.
+ * @returns True if the URI is a database connection URI, false otherwise.
+ */
+export declare function isDatabaseConnectionString(uri?: string): boolean;
+/**
+ * A session service that uses a SQL database for storage via MikroORM.
+ */
+export declare class DatabaseSessionService extends BaseSessionService {
+    private orm?;
+    private initialized;
+    private options?;
+    private connectionString?;
+    constructor(connectionStringOrOptions: MikroDBOptions | string);
+    init(): Promise<void>;
+    createSession({ appName, userId, state, sessionId, }: CreateSessionRequest): Promise<Session>;
+    getSession({ appName, userId, sessionId, config, }: GetSessionRequest): Promise<Session | undefined>;
+    listSessions({ appName, userId, }: ListSessionsRequest): Promise<ListSessionsResponse>;
+    deleteSession({ appName, userId, sessionId, }: DeleteSessionRequest): Promise<void>;
+    appendEvent({ session, event, }: AppendEventRequest): Promise<Event>;
+}

package/dist/types/sessions/db/operations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MikroORM, Options as MikroORMOptions } from '@mikro-orm/core';
+/**
+ * Parses a database connection URI and returns MikroORM Options.
+ *
+ * @param uri The database connection URI (e.g., "postgres://user:password@host:port/database")
+ * @returns MikroORM Options configured for the database
+ * @throws Error if the URI is invalid or unsupported
+ */
+export declare function getConnectionOptionsFromUri(uri: string): Promise<MikroORMOptions>;
+/**
+ * Creates a database and tables if they don't exist.
+ *
+ * @param orm The MikroORM instance.
+ * @returns Promise<void>
+ */
+export declare function ensureDatabaseCreated(orm: MikroORM): Promise<void>;
+/**
+ * Validates the schema version.
+ *
+ * @param orm The MikroORM instance.
+ * @throws Error if the schema version is not compatible.
+ */
+export declare function validateDatabaseSchemaVersion(orm: MikroORM): Promise<void>;

package/dist/types/sessions/db/schema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { PrimaryKey } from '@mikro-orm/core';
+import { Event } from '../../events/event.js';
+export declare const SCHEMA_VERSION_KEY = "schema_version";
+export declare const SCHEMA_VERSION_1_JSON = "1";
+export declare class StorageMetadata {
+    key: string;
+    value: string;
+}
+export declare class StorageAppState {
+    appName: string;
+    state: Record<string, unknown>;
+    updateTime: Date;
+}
+export declare class StorageUserState {
+    [PrimaryKey.name]?: [string, string] | undefined;
+    appName: string;
+    userId: string;
+    state: Record<string, unknown>;
+    updateTime: Date;
+}
+export declare class StorageSession {
+    [PrimaryKey.name]?: [string, string, string] | undefined;
+    id: string;
+    appName: string;
+    userId: string;
+    state: Record<string, unknown>;
+    createTime: Date;
+    updateTime: Date;
+}
+export declare class StorageEvent {
+    [PrimaryKey.name]?: [string, string, string, string] | undefined;
+    id: string;
+    appName: string;
+    userId: string;
+    sessionId: string;
+    invocationId: string;
+    timestamp: Date;
+    eventData: Event;
+}
+export declare const ENTITIES: (typeof StorageMetadata | typeof StorageAppState | typeof StorageEvent)[];

package/dist/types/sessions/in_memory_session_service.d.ts

@@ -0,0 +1,30 @@
+import { Event } from '../events/event.js';
+import { AppendEventRequest, BaseSessionService, CreateSessionRequest, DeleteSessionRequest, GetSessionRequest, ListSessionsRequest, ListSessionsResponse } from './base_session_service.js';
+import { Session } from './session.js';
+/**
+ * Checks if the given URI is an in-memory memory service URI.
+ */
+export declare function isInMemoryConnectionString(uri?: string): boolean;
+/**
+ * An in-memory implementation of the session service.
+ */
+export declare class InMemorySessionService extends BaseSessionService {
+    /**
+     * A map from app name to a map from user ID to a map from session ID to
+     * session.
+     */
+    private sessions;
+    /**
+     * A map from app name to a map from user ID to a map from key to the value.
+     */
+    private userState;
+    /**
+     * A map from app name to a map from key to the value.
+     */
+    private appState;
+    createSession({ appName, userId, state, sessionId, }: CreateSessionRequest): Promise<Session>;
+    getSession({ appName, userId, sessionId, config, }: GetSessionRequest): Promise<Session | undefined>;
+    listSessions({ appName, userId, }: ListSessionsRequest): Promise<ListSessionsResponse>;
+    deleteSession({ appName, userId, sessionId, }: DeleteSessionRequest): Promise<void>;
+    appendEvent({ session, event, }: AppendEventRequest): Promise<Event>;
+}

package/dist/types/sessions/registry.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseSessionService } from './base_session_service.js';
+export declare function getSessionServiceFromUri(uri: string): BaseSessionService;