@opperai/agents 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1927 @@
+import { ZodType, z, ZodTypeAny, ZodIssue } from 'zod';
+import { Opper } from 'opperai';
+import { Implementation } from '@modelcontextprotocol/sdk/types.js';
+import { JsonSchema7Type } from 'zod-to-json-schema';
+
+interface Success<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+interface Failure<E> {
+    readonly ok: false;
+    readonly error: E;
+}
+type Result<T, E = Error> = Success<T> | Failure<E>;
+declare const Result: {
+    ok<T>(value: T): Success<T>;
+    err<E>(error: E): Failure<E>;
+    isOk<T, E>(result: Result<T, E>): result is Success<T>;
+    isErr<T, E>(result: Result<T, E>): result is Failure<E>;
+    map<T, E, U>(result: Result<T, E>, mapper: (value: T) => U): Result<U, E>;
+    mapError<T, E, F>(result: Result<T, E>, mapper: (error: E) => F): Result<T, F>;
+    unwrapOr<T, E>(result: Result<T, E>, fallback: T): T;
+};
+declare const ok: <T>(value: T) => Success<T>;
+declare const err: <E>(error: E) => Failure<E>;
+
+declare const ToolMetadataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+declare const ToolCallRecordSchema: z.ZodObject<{
+    id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    toolName: z.ZodString;
+    input: z.ZodUnknown;
+    output: z.ZodOptional<z.ZodUnknown>;
+    success: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        message: z.ZodString;
+    }, "passthrough", ZodTypeAny, z.objectOutputType<{
+        message: z.ZodString;
+    }, ZodTypeAny, "passthrough">, z.objectInputType<{
+        message: z.ZodString;
+    }, ZodTypeAny, "passthrough">>]>>;
+    startedAt: z.ZodDefault<z.ZodNumber>;
+    finishedAt: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", ZodTypeAny, {
+    id: string;
+    toolName: string;
+    startedAt: number;
+    metadata: Record<string, unknown>;
+    input?: unknown;
+    output?: unknown;
+    success?: boolean | undefined;
+    error?: string | z.objectOutputType<{
+        message: z.ZodString;
+    }, ZodTypeAny, "passthrough"> | undefined;
+    finishedAt?: number | undefined;
+}, {
+    toolName: string;
+    id?: string | undefined;
+    input?: unknown;
+    output?: unknown;
+    success?: boolean | undefined;
+    error?: string | z.objectInputType<{
+        message: z.ZodString;
+    }, ZodTypeAny, "passthrough"> | undefined;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+type ToolCallRecord = z.infer<typeof ToolCallRecordSchema>;
+declare const ToolResultSuccessSchema: z.ZodEffects<z.ZodObject<{
+    toolName: z.ZodString;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    finishedAt: z.ZodOptional<z.ZodNumber>;
+} & {
+    success: z.ZodLiteral<true>;
+    output: z.ZodAny;
+}, "strip", ZodTypeAny, {
+    toolName: string;
+    success: true;
+    metadata: Record<string, unknown>;
+    output?: any;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+}, {
+    toolName: string;
+    success: true;
+    output?: any;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>, {
+    toolName: string;
+    success: true;
+    metadata: Record<string, unknown>;
+    output?: any;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+}, {
+    toolName: string;
+    success: true;
+    output?: any;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+declare const ToolResultFailureSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    finishedAt: z.ZodOptional<z.ZodNumber>;
+} & {
+    success: z.ZodLiteral<false>;
+    error: z.ZodUnion<[z.ZodString, ZodType<Error, z.ZodTypeDef, Error>]>;
+}, "strip", ZodTypeAny, {
+    toolName: string;
+    success: false;
+    error: string | Error;
+    metadata: Record<string, unknown>;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+}, {
+    toolName: string;
+    success: false;
+    error: string | Error;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+declare const ToolResultSchema: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
+    toolName: z.ZodString;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    finishedAt: z.ZodOptional<z.ZodNumber>;
+} & {
+    success: z.ZodLiteral<true>;
+    output: z.ZodAny;
+}, "strip", ZodTypeAny, {
+    toolName: string;
+    success: true;
+    metadata: Record<string, unknown>;
+    output?: any;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+}, {
+    toolName: string;
+    success: true;
+    output?: any;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>, {
+    toolName: string;
+    success: true;
+    metadata: Record<string, unknown>;
+    output?: any;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+}, {
+    toolName: string;
+    success: true;
+    output?: any;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>, z.ZodObject<{
+    toolName: z.ZodString;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    finishedAt: z.ZodOptional<z.ZodNumber>;
+} & {
+    success: z.ZodLiteral<false>;
+    error: z.ZodUnion<[z.ZodString, ZodType<Error, z.ZodTypeDef, Error>]>;
+}, "strip", ZodTypeAny, {
+    toolName: string;
+    success: false;
+    error: string | Error;
+    metadata: Record<string, unknown>;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+}, {
+    toolName: string;
+    success: false;
+    error: string | Error;
+    startedAt?: number | undefined;
+    finishedAt?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>]>;
+type ToolResultData = z.infer<typeof ToolResultSchema>;
+interface ToolExecutionContext {
+    agentContext: AgentContext;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+    /**
+     * Span ID for this tool execution (used as parent for nested operations)
+     */
+    spanId?: string;
+}
+interface ToolSuccess<TOutput> {
+    success: true;
+    toolName: string;
+    output: TOutput;
+    metadata: Record<string, unknown>;
+    startedAt?: number;
+    finishedAt?: number;
+}
+interface ToolFailure {
+    success: false;
+    toolName: string;
+    error: Error | string;
+    metadata: Record<string, unknown>;
+    startedAt?: number;
+    finishedAt?: number;
+}
+type ToolResult<TOutput = unknown> = ToolSuccess<TOutput> | ToolFailure;
+interface ToolDefinition<TInput, TOutput> {
+    name: string;
+    description?: string;
+    schema?: ZodType<TInput>;
+    execute: (input: TInput, context: ToolExecutionContext) => MaybePromise<ToolResult<TOutput>>;
+    metadata?: Record<string, unknown>;
+    timeoutMs?: number;
+}
+type MaybePromise<T> = T | Promise<T>;
+type Tool<TInput, TOutput> = ToolDefinition<TInput, TOutput>;
+interface ToolProvider {
+    setup(agent: BaseAgent<unknown, unknown>): Promise<Array<Tool<unknown, unknown>>>;
+    teardown(): Promise<void>;
+}
+interface ToolResultInit {
+    metadata?: Record<string, unknown>;
+    startedAt?: number;
+    finishedAt?: number;
+}
+declare const ToolResultFactory: {
+    success<TOutput>(toolName: string, output: TOutput, init?: ToolResultInit): ToolSuccess<TOutput>;
+    failure(toolName: string, error: Error | string, init?: ToolResultInit): ToolFailure;
+    isSuccess<TOutput>(result: ToolResult<TOutput>): result is ToolSuccess<TOutput>;
+    isFailure<TOutput>(result: ToolResult<TOutput>): result is ToolFailure;
+};
+declare const createToolCallRecord: (input: Partial<ToolCallRecord>) => ToolCallRecord;
+declare const validateToolInput: <TSchema extends ZodTypeAny>(schema: TSchema, payload: unknown) => Result<z.infer<TSchema>, z.ZodError<z.infer<TSchema>>>;
+declare const coerceToolDefinition: <TInput, TOutput>(definition: ToolDefinition<TInput, TOutput>) => Tool<TInput, TOutput>;
+declare const isToolProvider: (value: unknown) => value is ToolProvider;
+declare const normalizeToolEntries: (entries: Array<Tool<unknown, unknown> | ToolProvider>) => {
+    tools: Array<Tool<unknown, unknown>>;
+    providers: Array<ToolProvider>;
+};
+
+declare const UsageSchema: z.ZodObject<{
+    requests: z.ZodDefault<z.ZodNumber>;
+    inputTokens: z.ZodDefault<z.ZodNumber>;
+    outputTokens: z.ZodDefault<z.ZodNumber>;
+    totalTokens: z.ZodDefault<z.ZodNumber>;
+    cost: z.ZodDefault<z.ZodObject<{
+        generation: z.ZodDefault<z.ZodNumber>;
+        platform: z.ZodDefault<z.ZodNumber>;
+        total: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        generation: number;
+        platform: number;
+        total: number;
+    }, {
+        generation?: number | undefined;
+        platform?: number | undefined;
+        total?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cost: {
+        generation: number;
+        platform: number;
+        total: number;
+    };
+}, {
+    requests?: number | undefined;
+    inputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+    totalTokens?: number | undefined;
+    cost?: {
+        generation?: number | undefined;
+        platform?: number | undefined;
+        total?: number | undefined;
+    } | undefined;
+}>;
+type Usage = z.infer<typeof UsageSchema>;
+declare const ExecutionCycleSchema: z.ZodObject<{
+    iteration: z.ZodNumber;
+    thought: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+    toolCalls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        toolName: z.ZodString;
+        input: z.ZodUnknown;
+        output: z.ZodOptional<z.ZodUnknown>;
+        success: z.ZodOptional<z.ZodBoolean>;
+        error: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+            message: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            message: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            message: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>]>>;
+        startedAt: z.ZodDefault<z.ZodNumber>;
+        finishedAt: z.ZodOptional<z.ZodNumber>;
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        toolName: string;
+        startedAt: number;
+        metadata: Record<string, unknown>;
+        input?: unknown;
+        output?: unknown;
+        success?: boolean | undefined;
+        error?: string | z.objectOutputType<{
+            message: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        finishedAt?: number | undefined;
+    }, {
+        toolName: string;
+        id?: string | undefined;
+        input?: unknown;
+        output?: unknown;
+        success?: boolean | undefined;
+        error?: string | z.objectInputType<{
+            message: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        startedAt?: number | undefined;
+        finishedAt?: number | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }>, "many">>;
+    results: z.ZodDefault<z.ZodArray<z.ZodUnknown, "many">>;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    iteration: number;
+    toolCalls: {
+        id: string;
+        toolName: string;
+        startedAt: number;
+        metadata: Record<string, unknown>;
+        input?: unknown;
+        output?: unknown;
+        success?: boolean | undefined;
+        error?: string | z.objectOutputType<{
+            message: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        finishedAt?: number | undefined;
+    }[];
+    results: unknown[];
+    timestamp: number;
+    thought?: unknown;
+}, {
+    iteration: number;
+    thought?: unknown;
+    toolCalls?: {
+        toolName: string;
+        id?: string | undefined;
+        input?: unknown;
+        output?: unknown;
+        success?: boolean | undefined;
+        error?: string | z.objectInputType<{
+            message: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        startedAt?: number | undefined;
+        finishedAt?: number | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[] | undefined;
+    results?: unknown[] | undefined;
+    timestamp?: number | undefined;
+}>;
+type ExecutionCycle = z.infer<typeof ExecutionCycleSchema>;
+interface AgentContextOptions {
+    agentName: string;
+    sessionId?: string;
+    parentSpanId?: string | null;
+    goal?: unknown;
+    metadata?: Record<string, unknown>;
+}
+interface AgentContextSnapshot {
+    agentName: string;
+    sessionId: string;
+    parentSpanId: string | null;
+    iteration: number;
+    goal?: unknown;
+    executionHistory: ExecutionCycle[];
+    usage: Usage;
+    toolCalls: ToolCallRecord[];
+    metadata: Record<string, unknown>;
+    startedAt: number;
+    updatedAt: number;
+}
+interface IterationSummary {
+    iteration: number;
+    thought: Record<string, unknown>;
+    toolCalls: Array<{
+        toolName: string;
+        success?: boolean;
+    }>;
+    results: unknown[];
+}
+declare class AgentContext {
+    readonly agentName: string;
+    readonly sessionId: string;
+    parentSpanId: string | null;
+    iteration: number;
+    goal?: unknown;
+    readonly executionHistory: ExecutionCycle[];
+    readonly toolCalls: ToolCallRecord[];
+    usage: Usage;
+    metadata: Record<string, unknown>;
+    readonly startedAt: number;
+    updatedAt: number;
+    constructor(options: AgentContextOptions);
+    updateUsage(delta: Usage): void;
+    addCycle(cycle: ExecutionCycle): ExecutionCycle;
+    recordToolCall(call: Omit<ToolCallRecord, "id">): ToolCallRecord;
+    getContextSize(): number;
+    getLastNCycles(count?: number): ExecutionCycle[];
+    getLastIterationsSummary(count?: number): IterationSummary[];
+    setMetadata(key: string, value: unknown): void;
+    clearHistory(): void;
+    snapshot(): AgentContextSnapshot;
+    private touch;
+}
+
+/**
+ * Log levels
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+/**
+ * Logger interface for agent output
+ */
+interface AgentLogger {
+    /**
+     * Log a debug message
+     */
+    debug(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, error?: Error | unknown, meta?: Record<string, unknown>): void;
+    /**
+     * Get current log level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+}
+declare class ConsoleLogger implements AgentLogger {
+    private level;
+    constructor(level?: LogLevel);
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, error?: Error | unknown, meta?: Record<string, unknown>): void;
+    getLevel(): LogLevel;
+    setLevel(level: LogLevel): void;
+}
+/**
+ * No-op logger that suppresses all output
+ */
+declare class SilentLogger implements AgentLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, error?: Error | unknown, meta?: Record<string, unknown>): void;
+    getLevel(): LogLevel;
+    setLevel(level: LogLevel): void;
+}
+/**
+ * Get the default logger
+ */
+declare function getDefaultLogger(): AgentLogger;
+/**
+ * Set the default logger
+ */
+declare function setDefaultLogger(logger: AgentLogger): void;
+
+declare const HookEvents: {
+    readonly AgentStart: "agent:start";
+    readonly AgentEnd: "agent:end";
+    readonly LoopStart: "loop:start";
+    readonly LoopEnd: "loop:end";
+    readonly LlmCall: "llm:call";
+    readonly LlmResponse: "llm:response";
+    readonly ThinkEnd: "think:end";
+    readonly BeforeTool: "tool:before";
+    readonly AfterTool: "tool:after";
+    readonly ToolError: "tool:error";
+    readonly MemoryRead: "memory:read";
+    readonly MemoryWrite: "memory:write";
+    readonly MemoryError: "memory:error";
+};
+type HookEventName = (typeof HookEvents)[keyof typeof HookEvents];
+interface HookPayloadMap {
+    [HookEvents.AgentStart]: {
+        context: AgentContext;
+    };
+    [HookEvents.AgentEnd]: {
+        context: AgentContext;
+        result?: unknown;
+        error?: unknown;
+    };
+    [HookEvents.LoopStart]: {
+        context: AgentContext;
+    };
+    [HookEvents.LoopEnd]: {
+        context: AgentContext;
+    };
+    [HookEvents.LlmCall]: {
+        context: AgentContext;
+        callType: string;
+    };
+    [HookEvents.LlmResponse]: {
+        context: AgentContext;
+        callType: string;
+        response: unknown;
+    };
+    [HookEvents.ThinkEnd]: {
+        context: AgentContext;
+        thought: unknown;
+    };
+    [HookEvents.BeforeTool]: {
+        context: AgentContext;
+        tool: Tool<unknown, unknown>;
+        input: unknown;
+    };
+    [HookEvents.AfterTool]: {
+        context: AgentContext;
+        tool: Tool<unknown, unknown>;
+        result: ToolResult<unknown>;
+        record: ToolCallRecord;
+    };
+    [HookEvents.ToolError]: {
+        context: AgentContext;
+        toolName: string;
+        tool?: Tool<unknown, unknown>;
+        error: unknown;
+    };
+    [HookEvents.MemoryRead]: {
+        context: AgentContext;
+        key: string;
+        value: unknown;
+    };
+    [HookEvents.MemoryWrite]: {
+        context: AgentContext;
+        key: string;
+        value: unknown;
+    };
+    [HookEvents.MemoryError]: {
+        context: AgentContext;
+        operation: "read" | "write" | "delete" | "clear";
+        error: unknown;
+    };
+}
+type HookPayload<E extends HookEventName> = HookPayloadMap[E];
+type HookHandler<E extends HookEventName> = (payload: HookPayload<E>) => void | Promise<void>;
+interface HookRegistration<E extends HookEventName> {
+    event: E;
+    handler: HookHandler<E>;
+}
+type UnregisterHook = () => void;
+declare class HookManager {
+    private readonly registry;
+    private readonly logger;
+    constructor(logger?: AgentLogger);
+    on<E extends HookEventName>(event: E, handler: HookHandler<E>): UnregisterHook;
+    once<E extends HookEventName>(event: E, handler: HookHandler<E>): UnregisterHook;
+    off<E extends HookEventName>(event: E, handler: HookHandler<E>): void;
+    clear(): void;
+    listenerCount(event?: HookEventName): number;
+    emit<E extends HookEventName>(event: E, payload: HookPayload<E>): Promise<void>;
+    registerMany<E extends HookEventName>(registrations: HookRegistration<E>[]): UnregisterHook;
+}
+declare const createHookManager: (logger?: AgentLogger) => HookManager;
+
+/**
+ * Schema for memory entry metadata
+ */
+declare const MemoryEntryMetadataSchema: z.ZodObject<{
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    accessCount: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    createdAt: number;
+    updatedAt: number;
+    accessCount: number;
+}, {
+    createdAt: number;
+    updatedAt: number;
+    accessCount?: number | undefined;
+}>;
+type MemoryEntryMetadata = z.infer<typeof MemoryEntryMetadataSchema>;
+/**
+ * Schema for a single memory entry
+ */
+declare const MemoryEntrySchema: z.ZodObject<{
+    key: z.ZodString;
+    description: z.ZodString;
+    value: z.ZodUnknown;
+    metadata: z.ZodObject<{
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+        accessCount: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        createdAt: number;
+        updatedAt: number;
+        accessCount: number;
+    }, {
+        createdAt: number;
+        updatedAt: number;
+        accessCount?: number | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    metadata: {
+        createdAt: number;
+        updatedAt: number;
+        accessCount: number;
+    };
+    key: string;
+    description: string;
+    value?: unknown;
+}, {
+    metadata: {
+        createdAt: number;
+        updatedAt: number;
+        accessCount?: number | undefined;
+    };
+    key: string;
+    description: string;
+    value?: unknown;
+}>;
+type MemoryEntry = z.infer<typeof MemoryEntrySchema>;
+/**
+ * Catalog entry (summary without value) for LLM consumption
+ */
+interface MemoryCatalogEntry {
+    key: string;
+    description: string;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Memory interface for persistent key-value storage across agent invocations.
+ * Implementations must be thread-safe and handle concurrent operations gracefully.
+ */
+interface Memory {
+    /**
+     * Check if memory has any entries
+     *
+     * @returns True if memory contains entries
+     */
+    hasEntries(): Promise<boolean>;
+    /**
+     * List memory catalog (summaries without values) so LLM can decide what to load
+     *
+     * @returns Array of catalog entries with key, description, metadata (no values)
+     */
+    listEntries(): Promise<MemoryCatalogEntry[]>;
+    /**
+     * Read values from memory by keys
+     *
+     * @param keys - Optional array of keys to read (if omitted, reads all)
+     * @returns Object mapping keys to their values
+     */
+    read(keys?: string[]): Promise<Record<string, unknown>>;
+    /**
+     * Write a value to memory with the specified key and description
+     *
+     * @param key - Memory key
+     * @param value - Value to store
+     * @param description - Human-readable description of what this memory contains
+     * @param metadata - Optional metadata
+     * @returns The created or updated memory entry
+     */
+    write(key: string, value: unknown, description?: string, metadata?: Record<string, unknown>): Promise<MemoryEntry>;
+    /**
+     * Delete a memory entry by key
+     *
+     * @param key - Memory key to delete
+     * @returns True if entry was deleted, false if not found
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all memory entries
+     *
+     * @returns Number of entries cleared
+     */
+    clear(): Promise<number>;
+}
+/**
+ * Default in-memory implementation of Memory interface.
+ * Stores data in a Map that persists across agent invocations within the same process.
+ */
+declare class InMemoryStore implements Memory {
+    private readonly store;
+    /**
+     * Check if memory has any entries
+     */
+    hasEntries(): Promise<boolean>;
+    /**
+     * List memory catalog (summaries without values) for LLM consumption
+     */
+    listEntries(): Promise<MemoryCatalogEntry[]>;
+    /**
+     * Read values from memory by keys
+     */
+    read(keys?: string[]): Promise<Record<string, unknown>>;
+    /**
+     * Write a value to memory with description
+     */
+    write(key: string, value: unknown, description?: string, metadata?: Record<string, unknown>): Promise<MemoryEntry>;
+    /**
+     * Delete a memory entry by key
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all memory entries
+     */
+    clear(): Promise<number>;
+    /**
+     * Get the current size of the memory store
+     *
+     * @returns Number of entries in memory
+     */
+    get size(): number;
+}
+/**
+ * Factory function to create a new in-memory store
+ *
+ * @returns New InMemoryStore instance
+ */
+declare const createInMemoryStore: () => InMemoryStore;
+
+declare const DEFAULT_MODEL = "gcp/gemini-flash-latest";
+/**
+ * Configuration options for BaseAgent
+ */
+interface BaseAgentConfig<TInput, TOutput> {
+    /**
+     * Unique name identifying this agent
+     */
+    name: string;
+    /**
+     * Human-readable description of the agent's purpose
+     */
+    description?: string;
+    /**
+     * System instructions guiding agent behavior
+     */
+    instructions?: string;
+    /**
+     * List of tools available to the agent
+     *
+     * We intentionally accept Tool<any, any> here because tool inputs are ultimately validated
+     * at runtime before execution. Using `any` keeps the API ergonomic for tool authors while
+     * allowing the BaseAgent to store mixed tool definitions in a single registry.
+     */
+    tools?: Array<Tool<any, any> | ToolProvider>;
+    /**
+     * Maximum iterations before terminating the agent loop
+     * @default 25
+     */
+    maxIterations?: number;
+    /**
+     * Model identifier(s).
+     * Accepts a single model (e.g., "gpt-4", "claude-3-sonnet") or a list used as fallback.
+     * @default "gcp/gemini-flash-latest"
+     */
+    model?: string | readonly string[];
+    /**
+     * Input schema for validation (Zod schema)
+     */
+    inputSchema?: ZodType<TInput>;
+    /**
+     * Output schema for validation (Zod schema)
+     */
+    outputSchema?: ZodType<TOutput>;
+    /**
+     * Enable memory subsystem
+     * @default false
+     */
+    enableMemory?: boolean;
+    /**
+     * Custom memory implementation (defaults to InMemoryStore if enableMemory is true)
+     */
+    memory?: Memory;
+    /**
+     * Additional metadata for the agent
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Opper API configuration
+     */
+    opperConfig?: OpperClientConfig;
+}
+/**
+ * Opper client configuration
+ */
+interface OpperClientConfig {
+    /**
+     * Opper API key (defaults to process.env.OPPER_API_KEY)
+     */
+    apiKey: string | undefined;
+    /**
+     * Opper API base URL
+     */
+    baseUrl: string | undefined;
+    /**
+     * Additional configuration options
+     */
+    [key: string]: unknown;
+}
+/**
+ * Abstract base class for all Opper agents.
+ * Provides lifecycle management, tool handling, hook system, and Opper integration.
+ *
+ * @template TInput - Type of input the agent accepts
+ * @template TOutput - Type of output the agent produces
+ */
+declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> {
+    /**
+     * Agent name
+     */
+    readonly name: string;
+    /**
+     * Agent description
+     */
+    readonly description: string | undefined;
+    /**
+     * Agent instructions
+     */
+    readonly instructions: string | undefined;
+    /**
+     * Maximum iterations for the agent loop
+     */
+    readonly maxIterations: number;
+    /**
+     * Model identifier
+     */
+    readonly model: string | readonly string[];
+    /**
+     * Input validation schema
+     */
+    readonly inputSchema: ZodType<TInput> | undefined;
+    /**
+     * Output validation schema
+     */
+    readonly outputSchema: ZodType<TOutput> | undefined;
+    /**
+     * Whether memory is enabled
+     */
+    readonly enableMemory: boolean;
+    /**
+     * Memory instance for persistent storage (null if disabled or initialization failed)
+     */
+    readonly memory: Memory | null;
+    /**
+     * Agent metadata
+     */
+    readonly metadata: Record<string, unknown>;
+    /**
+     * Hook manager for lifecycle events
+     */
+    protected readonly hooks: HookManager;
+    /**
+     * Registry of available tools
+     */
+    protected readonly tools: Map<string, Tool<unknown, unknown>>;
+    /**
+     * Baseline tools registered directly on the agent
+     */
+    protected readonly baseTools: Map<string, Tool<unknown, unknown>>;
+    /**
+     * Registered tool providers that can expand into tools at runtime
+     */
+    protected readonly toolProviders: Set<ToolProvider>;
+    /**
+     * Active tools supplied by providers for the current execution
+     */
+    private readonly providerToolRegistry;
+    /**
+     * Opper client configuration
+     */
+    protected readonly opperConfig: OpperClientConfig;
+    constructor(config: BaseAgentConfig<TInput, TOutput>);
+    /**
+     * Initialize memory subsystem with graceful degradation
+     *
+     * @param config - Agent configuration
+     * @returns Memory instance or null
+     */
+    private initializeMemory;
+    /**
+     * Main entry point for agent execution.
+     * Orchestrates lifecycle: context initialization, hook triggering, loop execution, teardown.
+     *
+     * @param input - Input to process
+     * @param parentSpanId - Optional parent span ID for tracing
+     * @returns Processed output
+     */
+    process(input: TInput, parentSpanId?: string): Promise<TOutput>;
+    /**
+     * Abstract method implementing the agent's main loop logic.
+     * Must be implemented by concrete agent classes.
+     *
+     * @param input - Validated input
+     * @param context - Agent execution context
+     * @returns Processed output
+     */
+    protected abstract runLoop(input: TInput, context: AgentContext): Promise<TOutput>;
+    /**
+     * Initialize agent context before execution.
+     * Can be overridden for custom initialization logic.
+     *
+     * @param input - Agent input
+     * @param parentSpanId - Optional parent span ID
+     * @returns Initialized context
+     */
+    protected initializeContext(input: TInput, parentSpanId?: string): Promise<AgentContext>;
+    /**
+     * Teardown agent context after execution.
+     * Can be overridden for custom cleanup logic.
+     *
+     * @param context - Agent context to teardown
+     */
+    protected teardownContext(context: AgentContext): Promise<void>;
+    /**
+     * Add a tool to the agent's tool registry.
+     *
+     * @param tool - Tool to add
+     */
+    addTool<TInput = unknown, TOutput = unknown>(tool: Tool<TInput, TOutput>): void;
+    /**
+     * Remove a tool from the agent's tool registry.
+     *
+     * @param toolName - Name of tool to remove
+     * @returns True if tool was removed, false if not found
+     */
+    removeTool(toolName: string): boolean;
+    /**
+     * Get a tool by name.
+     *
+     * @param toolName - Name of tool to retrieve
+     * @returns Tool instance or undefined
+     */
+    getTool(toolName: string): Tool<unknown, unknown> | undefined;
+    /**
+     * Get all registered tools.
+     *
+     * @returns Array of all tools
+     */
+    getTools(): Array<Tool<unknown, unknown>>;
+    /**
+     * Register a tool provider that expands into tools at runtime.
+     *
+     * @param provider - Tool provider to add
+     */
+    addToolProvider(provider: ToolProvider): void;
+    /**
+     * Convert this agent into a tool that can be used by other agents.
+     *
+     * @param toolName - Optional custom name for the tool (defaults to agent name)
+     * @param toolDescription - Optional custom description (defaults to agent description)
+     * @returns Tool wrapping this agent
+     */
+    asTool(toolName?: string, toolDescription?: string): Tool<TInput, TOutput>;
+    /**
+     * Register a hook handler for a specific event.
+     *
+     * @param event - Hook event name
+     * @param handler - Hook handler function
+     * @returns Cleanup function to unregister the hook
+     */
+    registerHook<E extends HookEventName>(event: E, handler: HookHandler<E>): () => void;
+    /**
+     * Trigger a hook event with a payload.
+     * Swallows errors to prevent hook failures from breaking agent execution.
+     *
+     * @param event - Hook event name
+     * @param payload - Event payload
+     */
+    protected triggerHook<E extends HookEventName>(event: E, payload: Parameters<HookHandler<E>>[0]): Promise<void>;
+    /**
+     * Execute a tool with proper context, hooks, and error handling.
+     *
+     * @param toolName - Name of tool to execute
+     * @param input - Tool input
+     * @param context - Agent context
+     * @param options - Optional execution options (signal, span ID)
+     * @returns Tool execution result
+     */
+    protected executeTool(toolName: string, input: unknown, context: AgentContext, options?: {
+        signal?: AbortSignal;
+        spanId?: string;
+    }): Promise<ToolResult<unknown>>;
+    private registerTools;
+    private activateToolProviders;
+    private deactivateToolProviders;
+}
+
+/**
+ * Opper call response
+ */
+interface OpperCallResponse<TOutput = unknown> {
+    /**
+     * Parsed JSON output (if outputSchema provided)
+     */
+    jsonPayload?: TOutput;
+    /**
+     * Text message response
+     */
+    message?: string | null | undefined;
+    /**
+     * Span ID for this call
+     */
+    spanId: string;
+    /**
+     * Token usage information
+     */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cost: {
+            generation: number;
+            platform: number;
+            total: number;
+        };
+    };
+}
+/**
+ * Options for Opper call
+ */
+interface OpperCallOptions<TInput = unknown, TOutput = unknown> {
+    /**
+     * Unique name for this call/task
+     */
+    name: string;
+    /**
+     * Natural language instructions
+     */
+    instructions: string;
+    /**
+     * Input data for the call
+     */
+    input: TInput;
+    /**
+     * Input schema (Zod or JSON Schema)
+     */
+    inputSchema?: z.ZodType<TInput> | Record<string, unknown>;
+    /**
+     * Output schema (Zod or JSON Schema)
+     */
+    outputSchema?: z.ZodType<TOutput> | Record<string, unknown>;
+    /**
+     * Model to use. Accepts a single model identifier or an ordered list for fallback.
+     * Example: "anthropic/claude-3.7-sonnet" or ["openai/gpt-4o", "anthropic/claude-3.7-sonnet"].
+     */
+    model?: string | readonly string[];
+    /**
+     * Parent span ID for tracing
+     */
+    parentSpanId?: string;
+}
+/**
+ * Span information
+ */
+interface OpperSpan {
+    id: string;
+    name: string;
+    input?: unknown;
+    output?: unknown;
+}
+/**
+ * Options for creating a span
+ */
+interface CreateSpanOptions {
+    name: string;
+    input?: unknown;
+    parentSpanId?: string;
+}
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts
+     */
+    maxRetries: number;
+    /**
+     * Initial delay in milliseconds
+     */
+    initialDelayMs: number;
+    /**
+     * Backoff multiplier
+     */
+    backoffMultiplier: number;
+    /**
+     * Maximum delay in milliseconds
+     */
+    maxDelayMs: number;
+}
+/**
+ * Default retry configuration
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Opper client wrapper with retry logic and usage tracking
+ */
+declare class OpperClient {
+    private readonly client;
+    private readonly logger;
+    private readonly retryConfig;
+    constructor(apiKey?: string, options?: {
+        logger?: AgentLogger;
+        retryConfig?: Partial<RetryConfig>;
+    });
+    /**
+     * Make a call to Opper with retry logic
+     */
+    call<TInput = unknown, TOutput = unknown>(options: OpperCallOptions<TInput, TOutput>): Promise<OpperCallResponse<TOutput>>;
+    /**
+     * Create a span for tracing
+     */
+    createSpan(options: CreateSpanOptions): Promise<OpperSpan>;
+    /**
+     * Update a span with output or error
+     */
+    updateSpan(spanId: string, output: unknown, options?: {
+        error?: string;
+    }): Promise<void>;
+    /**
+     * Get the underlying Opper client
+     */
+    getClient(): Opper;
+    /**
+     * Execute a function with retry logic and exponential backoff
+     */
+    private withRetry;
+    /**
+     * Check if an error is retryable
+     */
+    private isRetryableError;
+    /**
+     * Convert Zod schema to JSON Schema
+     */
+    private toJsonSchema;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+}
+/**
+ * Create an Opper client with optional configuration
+ */
+declare function createOpperClient(apiKey?: string, options?: {
+    logger?: AgentLogger;
+    retryConfig?: Partial<RetryConfig>;
+}): OpperClient;
+
+/**
+ * Configuration for the core Agent
+ */
+interface AgentConfig<TInput, TOutput> extends BaseAgentConfig<TInput, TOutput> {
+    /**
+     * Custom Opper client instance (for testing or custom configuration)
+     */
+    opperClient?: OpperClient;
+    /**
+     * Logger instance
+     */
+    logger?: AgentLogger;
+    /**
+     * Verbose logging
+     */
+    verbose?: boolean;
+}
+/**
+ * Core Agent implementation with "while tools > 0" loop.
+ * Implements think → tool execution → memory handling cycle.
+ */
+declare class Agent<TInput = unknown, TOutput = unknown> extends BaseAgent<TInput, TOutput> {
+    private readonly opperClient;
+    private readonly logger;
+    private readonly verbose;
+    constructor(config: AgentConfig<TInput, TOutput>);
+    /**
+     * Serialize input for passing to LLM or spans
+     */
+    private serializeInput;
+    /**
+     * Main agent loop: think → tool execution → memory handling → repeat until complete
+     */
+    protected runLoop(input: TInput, context: AgentContext): Promise<TOutput>;
+    /**
+     * Think step: Call LLM to decide next action
+     */
+    private think;
+    /**
+     * Build static instructions for the think step
+     */
+    private buildThinkInstructions;
+    /**
+     * Build dynamic context for the think step
+     */
+    private buildThinkContext;
+    /**
+     * Execute all tool calls from a decision
+     */
+    private executeToolCalls;
+    /**
+     * Handle memory operations from a decision
+     * Supports read and write operations with graceful degradation
+     */
+    private handleMemoryActions;
+    /**
+     * Generate final result based on execution history
+     */
+    private generateFinalResult;
+    /**
+     * Log helper
+     */
+    private log;
+}
+
+/**
+ * Schema for agent's internal thought/reasoning
+ */
+declare const ThoughtSchema: z.ZodObject<{
+    /**
+     * The reasoning or internal monologue of the agent
+     */
+    reasoning: z.ZodString;
+    /**
+     * Planned next action(s)
+     */
+    plan: z.ZodOptional<z.ZodString>;
+    /**
+     * Confidence level (0-1)
+     */
+    confidence: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Additional metadata
+     */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    reasoning: string;
+    metadata?: Record<string, unknown> | undefined;
+    plan?: string | undefined;
+    confidence?: number | undefined;
+}, {
+    reasoning: string;
+    metadata?: Record<string, unknown> | undefined;
+    plan?: string | undefined;
+    confidence?: number | undefined;
+}>;
+type Thought = z.infer<typeof ThoughtSchema>;
+/**
+ * Schema for a tool call from the LLM
+ */
+declare const ToolCallSchema: z.ZodObject<{
+    /**
+     * Unique identifier for this tool call
+     */
+    id: z.ZodString;
+    /**
+     * Name of the tool to invoke
+     */
+    toolName: z.ZodString;
+    /**
+     * Arguments to pass to the tool
+     */
+    arguments: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    toolName: string;
+    arguments?: unknown;
+}, {
+    id: string;
+    toolName: string;
+    arguments?: unknown;
+}>;
+type ToolCall = z.infer<typeof ToolCallSchema>;
+/**
+ * Schema for memory updates (write operations)
+ */
+declare const MemoryUpdateSchema: z.ZodObject<{
+    /**
+     * Value to store for this key
+     */
+    value: z.ZodUnknown;
+    /**
+     * Optional description of the memory entry
+     */
+    description: z.ZodOptional<z.ZodString>;
+    /**
+     * Optional metadata for the memory entry
+     */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    value?: unknown;
+    metadata?: Record<string, unknown> | undefined;
+    description?: string | undefined;
+}, {
+    value?: unknown;
+    metadata?: Record<string, unknown> | undefined;
+    description?: string | undefined;
+}>;
+type MemoryUpdate = z.infer<typeof MemoryUpdateSchema>;
+/**
+ * Schema for agent's decision output from the "think" step
+ */
+declare const AgentDecisionSchema: z.ZodObject<{
+    /**
+     * Agent's internal reasoning
+     */
+    reasoning: z.ZodString;
+    /**
+     * Tool calls to execute (if any)
+     * Empty array signals task completion
+     */
+    toolCalls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /**
+         * Unique identifier for this tool call
+         */
+        id: z.ZodString;
+        /**
+         * Name of the tool to invoke
+         */
+        toolName: z.ZodString;
+        /**
+         * Arguments to pass to the tool
+         */
+        arguments: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        toolName: string;
+        arguments?: unknown;
+    }, {
+        id: string;
+        toolName: string;
+        arguments?: unknown;
+    }>, "many">>;
+    /**
+     * Memory keys to read during this iteration
+     */
+    memoryReads: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Memory entries to write/update (key -> payload)
+     */
+    memoryUpdates: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        /**
+         * Value to store for this key
+         */
+        value: z.ZodUnknown;
+        /**
+         * Optional description of the memory entry
+         */
+        description: z.ZodOptional<z.ZodString>;
+        /**
+         * Optional metadata for the memory entry
+         */
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        value?: unknown;
+        metadata?: Record<string, unknown> | undefined;
+        description?: string | undefined;
+    }, {
+        value?: unknown;
+        metadata?: Record<string, unknown> | undefined;
+        description?: string | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    toolCalls: {
+        id: string;
+        toolName: string;
+        arguments?: unknown;
+    }[];
+    reasoning: string;
+    memoryReads: string[];
+    memoryUpdates: Record<string, {
+        value?: unknown;
+        metadata?: Record<string, unknown> | undefined;
+        description?: string | undefined;
+    }>;
+}, {
+    reasoning: string;
+    toolCalls?: {
+        id: string;
+        toolName: string;
+        arguments?: unknown;
+    }[] | undefined;
+    memoryReads?: string[] | undefined;
+    memoryUpdates?: Record<string, {
+        value?: unknown;
+        metadata?: Record<string, unknown> | undefined;
+        description?: string | undefined;
+    }> | undefined;
+}>;
+type AgentDecision = z.infer<typeof AgentDecisionSchema>;
+/**
+ * Schema for tool execution result summary
+ */
+declare const ToolExecutionSummarySchema: z.ZodObject<{
+    /**
+     * Tool name
+     */
+    toolName: z.ZodString;
+    /**
+     * Whether execution succeeded
+     */
+    success: z.ZodBoolean;
+    /**
+     * Output if successful
+     */
+    output: z.ZodOptional<z.ZodUnknown>;
+    /**
+     * Error message if failed
+     */
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    toolName: string;
+    success: boolean;
+    output?: unknown;
+    error?: string | undefined;
+}, {
+    toolName: string;
+    success: boolean;
+    output?: unknown;
+    error?: string | undefined;
+}>;
+type ToolExecutionSummary = z.infer<typeof ToolExecutionSummarySchema>;
+
+declare const MCPConfigVariants: z.ZodDiscriminatedUnion<"transport", [z.ZodObject<{
+    name: z.ZodString;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+} & {
+    transport: z.ZodLiteral<"stdio">;
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    stderr: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"inherit">, z.ZodLiteral<"pipe">, z.ZodLiteral<"ignore">]>>;
+}, "strip", z.ZodTypeAny, {
+    metadata: Record<string, unknown>;
+    name: string;
+    timeout: number;
+    transport: "stdio";
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd?: string | undefined;
+    stderr?: "inherit" | "pipe" | "ignore" | undefined;
+}, {
+    name: string;
+    transport: "stdio";
+    command: string;
+    metadata?: Record<string, unknown> | undefined;
+    timeout?: number | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    cwd?: string | undefined;
+    stderr?: "inherit" | "pipe" | "ignore" | undefined;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+} & {
+    transport: z.ZodLiteral<"http-sse">;
+    url: z.ZodString;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    method: z.ZodDefault<z.ZodEnum<["GET", "POST"]>>;
+}, "strip", z.ZodTypeAny, {
+    metadata: Record<string, unknown>;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    name: string;
+    timeout: number;
+    transport: "http-sse";
+    url: string;
+}, {
+    name: string;
+    transport: "http-sse";
+    url: string;
+    metadata?: Record<string, unknown> | undefined;
+    method?: "GET" | "POST" | undefined;
+    headers?: Record<string, string> | undefined;
+    timeout?: number | undefined;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+} & {
+    transport: z.ZodLiteral<"streamable-http">;
+    url: z.ZodString;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    sessionId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    metadata: Record<string, unknown>;
+    headers: Record<string, string>;
+    name: string;
+    timeout: number;
+    transport: "streamable-http";
+    url: string;
+    sessionId?: string | undefined;
+}, {
+    name: string;
+    transport: "streamable-http";
+    url: string;
+    metadata?: Record<string, unknown> | undefined;
+    headers?: Record<string, string> | undefined;
+    timeout?: number | undefined;
+    sessionId?: string | undefined;
+}>]>;
+type MCPServerConfig = z.output<typeof MCPConfigVariants>;
+type MCPServerConfigInput = z.input<typeof MCPConfigVariants>;
+declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"transport", [z.ZodObject<{
+    name: z.ZodString;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+} & {
+    transport: z.ZodLiteral<"stdio">;
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    stderr: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"inherit">, z.ZodLiteral<"pipe">, z.ZodLiteral<"ignore">]>>;
+}, "strip", z.ZodTypeAny, {
+    metadata: Record<string, unknown>;
+    name: string;
+    timeout: number;
+    transport: "stdio";
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd?: string | undefined;
+    stderr?: "inherit" | "pipe" | "ignore" | undefined;
+}, {
+    name: string;
+    transport: "stdio";
+    command: string;
+    metadata?: Record<string, unknown> | undefined;
+    timeout?: number | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    cwd?: string | undefined;
+    stderr?: "inherit" | "pipe" | "ignore" | undefined;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+} & {
+    transport: z.ZodLiteral<"http-sse">;
+    url: z.ZodString;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    method: z.ZodDefault<z.ZodEnum<["GET", "POST"]>>;
+}, "strip", z.ZodTypeAny, {
+    metadata: Record<string, unknown>;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    name: string;
+    timeout: number;
+    transport: "http-sse";
+    url: string;
+}, {
+    name: string;
+    transport: "http-sse";
+    url: string;
+    metadata?: Record<string, unknown> | undefined;
+    method?: "GET" | "POST" | undefined;
+    headers?: Record<string, string> | undefined;
+    timeout?: number | undefined;
+}>, z.ZodObject<{
+    name: z.ZodString;
+    timeout: z.ZodDefault<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+} & {
+    transport: z.ZodLiteral<"streamable-http">;
+    url: z.ZodString;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    sessionId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    metadata: Record<string, unknown>;
+    headers: Record<string, string>;
+    name: string;
+    timeout: number;
+    transport: "streamable-http";
+    url: string;
+    sessionId?: string | undefined;
+}, {
+    name: string;
+    transport: "streamable-http";
+    url: string;
+    metadata?: Record<string, unknown> | undefined;
+    headers?: Record<string, string> | undefined;
+    timeout?: number | undefined;
+    sessionId?: string | undefined;
+}>]>, {
+    metadata: Record<string, unknown>;
+    name: string;
+    timeout: number;
+    transport: "stdio";
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd?: string | undefined;
+    stderr?: "inherit" | "pipe" | "ignore" | undefined;
+} | {
+    metadata: Record<string, unknown>;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    name: string;
+    timeout: number;
+    transport: "http-sse";
+    url: string;
+} | {
+    metadata: Record<string, unknown>;
+    headers: Record<string, string>;
+    name: string;
+    timeout: number;
+    transport: "streamable-http";
+    url: string;
+    sessionId?: string | undefined;
+}, {
+    name: string;
+    transport: "stdio";
+    command: string;
+    metadata?: Record<string, unknown> | undefined;
+    timeout?: number | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    cwd?: string | undefined;
+    stderr?: "inherit" | "pipe" | "ignore" | undefined;
+} | {
+    name: string;
+    transport: "http-sse";
+    url: string;
+    metadata?: Record<string, unknown> | undefined;
+    method?: "GET" | "POST" | undefined;
+    headers?: Record<string, string> | undefined;
+    timeout?: number | undefined;
+} | {
+    name: string;
+    transport: "streamable-http";
+    url: string;
+    metadata?: Record<string, unknown> | undefined;
+    headers?: Record<string, string> | undefined;
+    timeout?: number | undefined;
+    sessionId?: string | undefined;
+}>;
+declare const MCPconfig: (config: MCPServerConfigInput) => MCPServerConfig;
+declare const createMCPServerConfig: (config: MCPServerConfigInput) => MCPServerConfig;
+
+interface MCPTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+interface MCPClientOptions {
+    clientInfo?: Implementation;
+}
+declare class MCPClient {
+    private readonly config;
+    private readonly client;
+    private transport;
+    private connected;
+    private toolCache;
+    constructor(config: MCPServerConfig, options?: MCPClientOptions);
+    static fromConfig(config: MCPServerConfig, options?: MCPClientOptions): MCPClient;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    listTools(): Promise<MCPTool[]>;
+    callTool(toolName: string, args: Record<string, unknown> | undefined): Promise<unknown>;
+    get isConnected(): boolean;
+    private ensureConnected;
+    private createTransport;
+}
+
+interface MCPToolProviderOptions {
+    namePrefix?: string;
+    clientOptions?: MCPClientOptions;
+    clientFactory?: (config: MCPServerConfig, options?: MCPClientOptions) => MCPClient;
+    logger?: {
+        debug?: (message: string, context?: Record<string, unknown>) => void;
+        info?: (message: string, context?: Record<string, unknown>) => void;
+        warn?: (message: string, context?: Record<string, unknown>) => void;
+        error?: (message: string, context?: Record<string, unknown>) => void;
+    };
+}
+declare class MCPToolProvider implements ToolProvider {
+    private readonly configs;
+    private readonly namePrefix;
+    private readonly clientOptions;
+    private readonly clientFactory;
+    private readonly logger;
+    private readonly clients;
+    constructor(configs: ReadonlyArray<MCPServerConfig>, options?: MCPToolProviderOptions);
+    setup(agent: BaseAgent<unknown, unknown>): Promise<Array<Tool<unknown, unknown>>>;
+    teardown(): Promise<void>;
+    private wrapTool;
+}
+declare const mcp: (...configs: ReadonlyArray<MCPServerConfig | MCPServerConfigInput>) => MCPToolProvider;
+
+declare class SchemaValidationError extends Error {
+    readonly issues: ZodIssue[];
+    constructor(message: string, issues: ZodIssue[]);
+}
+type Schema<T> = ZodType<T>;
+interface SchemaValidationOptions {
+    message?: string;
+}
+declare const validateSchema: <T>(schema: Schema<T>, value: unknown, options?: SchemaValidationOptions) => T;
+declare const isSchemaValid: <T>(schema: Schema<T>, value: unknown) => value is T;
+interface JsonSchemaOptions {
+    name?: string;
+    target?: "jsonSchema7" | "openApi3";
+}
+declare const schemaToJson: (schema: ZodTypeAny, options?: JsonSchemaOptions) => JsonSchema7Type;
+declare const getSchemaDefault: <T>(schema: Schema<T>) => T | undefined;
+declare const mergeSchemaDefaults: <T extends Record<string, unknown>>(schema: Schema<T>, value: Partial<T>) => T;
+
+/**
+ * Options for creating a tool from a function
+ */
+interface ToolOptions<TInput> {
+    /**
+     * Tool name (defaults to function name)
+     */
+    name?: string;
+    /**
+     * Human-readable description
+     */
+    description?: string;
+    /**
+     * Input validation schema
+     */
+    schema?: ZodType<TInput>;
+    /**
+     * Execution timeout in milliseconds
+     */
+    timeoutMs?: number;
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Function that can be converted to a tool
+ */
+type ToolFunction<TInput, TOutput> = (input: TInput, context: ToolExecutionContext) => TOutput | Promise<TOutput>;
+type ToolMethodDecorator<TInput, TOutput> = {
+    <TMethod extends ToolFunction<TInput, TOutput>>(value: TMethod, context: ClassMethodDecoratorContext<unknown, TMethod>): TMethod | void;
+    (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor | undefined): PropertyDescriptor | void;
+};
+/**
+ * Convert a function into a Tool.
+ * Handles both sync and async functions, wraps execution in ToolResult.
+ *
+ * @param fn - Function to wrap
+ * @param options - Tool configuration
+ * @returns Tool definition
+ *
+ * @example
+ * const addTool = createFunctionTool(
+ *   (input: { a: number; b: number }) => input.a + input.b,
+ *   {
+ *     name: "add",
+ *     description: "Add two numbers",
+ *     schema: z.object({ a: z.number(), b: z.number() })
+ *   }
+ * );
+ */
+declare function createFunctionTool<TInput, TOutput>(fn: ToolFunction<TInput, TOutput>, options?: ToolOptions<TInput>): Tool<TInput, TOutput>;
+/**
+ * Decorator factory for creating tools from methods.
+ * Can be used with or without arguments.
+ *
+ * @param options - Tool configuration
+ * @returns Method decorator
+ *
+ * @example
+ * class MyTools {
+ *   @tool({ description: "Add numbers", schema: AddSchema })
+ *   add(input: { a: number; b: number }): number {
+ *     return input.a + input.b;
+ *   }
+ * }
+ */
+declare function tool<TInput = unknown, TOutput = unknown>(options?: ToolOptions<TInput>): ToolMethodDecorator<TInput, TOutput>;
+/**
+ * Extract all tools defined via @tool decorator from a class instance
+ *
+ * @param instance - Class instance with @tool decorated methods
+ * @returns Array of Tool definitions
+ *
+ * @example
+ * class MyTools {
+ *   @tool() greet(input: { name: string }) { return `Hello ${input.name}`; }
+ * }
+ *
+ * const tools = extractTools(new MyTools());
+ */
+declare function extractTools(instance: object): Array<Tool<unknown, unknown>>;
+
+/**
+ * Options for tool execution
+ */
+interface ToolRunOptions {
+    /**
+     * Abort signal for cancellation
+     */
+    signal?: AbortSignal;
+    /**
+     * Additional metadata to pass to the tool
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Override timeout for this execution
+     */
+    timeoutMs?: number;
+}
+/**
+ * Utility class for executing tools with validation and error handling
+ */
+declare class ToolRunner {
+    /**
+     * Execute a tool with the given input and context
+     *
+     * @param tool - Tool to execute
+     * @param input - Input data
+     * @param context - Agent execution context
+     * @param options - Execution options
+     * @returns Tool execution result
+     */
+    static execute<TInput, TOutput>(tool: Tool<TInput, TOutput>, input: TInput, context: AgentContext, options?: ToolRunOptions): Promise<ToolResult<TOutput>>;
+    /**
+     * Execute multiple tools in parallel
+     *
+     * @param executions - Array of tool execution tuples [tool, input, context, options?]
+     * @returns Array of results in same order as input
+     */
+    static executeParallel<TInput, TOutput>(executions: Array<[
+        Tool<TInput, TOutput>,
+        TInput,
+        AgentContext,
+        ToolRunOptions?
+    ]>): Promise<Array<ToolResult<TOutput>>>;
+    /**
+     * Execute multiple tools sequentially, stopping on first failure
+     *
+     * @param executions - Array of tool execution tuples
+     * @returns Array of results up to first failure (inclusive)
+     */
+    static executeSequential<TInput, TOutput>(executions: Array<[
+        Tool<TInput, TOutput>,
+        TInput,
+        AgentContext,
+        ToolRunOptions?
+    ]>): Promise<Array<ToolResult<TOutput>>>;
+    /**
+     * Execute a tool with timeout
+     *
+     * @param promise - Tool execution promise
+     * @param timeoutMs - Timeout in milliseconds
+     * @param toolName - Tool name for error messages
+     * @returns Result or rejects with timeout error
+     */
+    private static executeWithTimeout;
+    /**
+     * Validate tool input without executing
+     *
+     * @param tool - Tool to validate input for
+     * @param input - Input to validate
+     * @returns true if valid, Error if invalid
+     */
+    static validate<TInput>(tool: Tool<TInput, unknown>, input: TInput): true | Error;
+    /**
+     * Check if a result indicates success
+     *
+     * @param result - Tool result to check
+     * @returns true if success, false if failure
+     */
+    static isSuccess<TOutput>(result: ToolResult<TOutput>): result is {
+        success: true;
+        toolName: string;
+        output: TOutput;
+        metadata: Record<string, unknown>;
+        startedAt?: number;
+        finishedAt?: number;
+    };
+    /**
+     * Check if a result indicates failure
+     *
+     * @param result - Tool result to check
+     * @returns true if failure, false if success
+     */
+    static isFailure<TOutput>(result: ToolResult<TOutput>): result is {
+        success: false;
+        toolName: string;
+        error: Error | string;
+        metadata: Record<string, unknown>;
+        startedAt?: number;
+        finishedAt?: number;
+    };
+}
+
+export { Agent, type AgentConfig, AgentContext, type AgentContextOptions, type AgentContextSnapshot, type AgentDecision, AgentDecisionSchema, type AgentLogger, BaseAgent, type BaseAgentConfig, ConsoleLogger, type CreateSpanOptions, DEFAULT_MODEL, DEFAULT_RETRY_CONFIG, type ExecutionCycle, ExecutionCycleSchema, type Failure, type HookEventName, HookEvents, type HookHandler, HookManager, type HookPayload, type HookPayloadMap, type HookRegistration, InMemoryStore, type IterationSummary, type JsonSchemaOptions, LogLevel, MCPClient, type MCPClientOptions, type MCPServerConfig, type MCPServerConfigInput, MCPServerConfigSchema, type MCPTool, MCPToolProvider, type MCPToolProviderOptions, MCPconfig, type MaybePromise, type Memory, type MemoryCatalogEntry, type MemoryEntry, type MemoryEntryMetadata, MemoryEntryMetadataSchema, MemoryEntrySchema, type MemoryUpdate, MemoryUpdateSchema, type OpperCallOptions, type OpperCallResponse, OpperClient, type OpperClientConfig, type OpperSpan, Result, type RetryConfig, type Schema, SchemaValidationError, type SchemaValidationOptions, SilentLogger, type Success, type Thought, ThoughtSchema, type Tool, type ToolCall, type ToolCallRecord, ToolCallRecordSchema, ToolCallSchema, type ToolDefinition, type ToolExecutionContext, type ToolExecutionSummary, ToolExecutionSummarySchema, type ToolFailure, type ToolFunction, ToolMetadataSchema, type ToolOptions, type ToolProvider, type ToolResult, type ToolResultData, ToolResultFactory, ToolResultFailureSchema, type ToolResultInit, ToolResultSchema, ToolResultSuccessSchema, type ToolRunOptions, ToolRunner, type ToolSuccess, type UnregisterHook, type Usage, UsageSchema, coerceToolDefinition, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createToolCallRecord, err, extractTools, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput };