Interfaces

onDemand: 'supported' | 'unsupported' | 'unverified';
inputTokenCounting: 'provider' | 'unavailable' | 'unverified';

};| - | |reasoningHistory?|reasoningHistory?: 'discard' | 'always' | 'when_tools_configured';| Whether normalized reasoning must be replayed in stateless conversation history. | |promptCaching|promptCaching: { mode: PromptCachingMode; ttlModes: Array<'short' | 'extended'>; reportsCacheUsage: boolean; /** Supports explicit per-content cache breakpoints. / explicitBreakpoints?: boolean; };| - | |batch|batch: { supported: boolean; cancellable: boolean; maxRequests?: number; completionWindow?: string; };| - | |structuredOutput|structuredOutput: { jsonObject: 'native' | 'prompt'; jsonSchema: 'native' | 'prompt'; nativeWithTools: boolean; };| - | |nativeTools|nativeTools: NativeToolCapability[];| - | |nativeToolOptions|nativeToolOptions: { /* Whether the adapter can surface and resume a host-managed MCP approval. */ remoteMcpApproval: boolean; };| - | |responsesExtensions?|responsesExtensions?: { asyncToolCalling: boolean; midTurnSteering: boolean; configurationUpdates: boolean; misalignmentMonitoring: boolean; };| Responses-protocol extensions exposed through this provider/library integration. | |dataHandling|dataHandling: { promptCaching: 'none' | 'provider_managed'; batch: 'none' | 'provider_retained'; remoteMcp: 'none' | 'third_party'; };` | - |

total: number;
processing?: number;
succeeded?: number;
failed?: number;
cancelled?: number;
expired?: number;

};| - | |rawStatus?|rawStatus?: string;| - | |metadata?|metadata?: Record<string, string>;` | - |

code?: string;
message: string;
statusCode?: number;
/** Provider-native item error for diagnostics/recovery. */
details?: unknown;

};| - | |providerRequestId?|providerRequestId?: string;` | - |

promptTokens: number;
totalTokens: number;

};` | Token usage |

toolName: string;
executionId: string;
connectorName?: string;
callId?: string;
runId?: string;
arguments: unknown;
principal: { userId?: string; accountId?: string; agentId?: string };
effect: 'read' | 'write' | 'unknown';
status: 'succeeded' | 'failed' | 'denied' | 'cancelled' | 'timed_out';
completion: 'settled' | 'unknown' | 'not_started';
startedAt: number;
durationMs: number;
executionStarted?: boolean;
cancellation?: 'none' | 'requested' | 'acknowledged';
timeoutMs?: number;
late?: boolean;

};| - | |result?|result?: unknown;` | Absent for unresolved/error receipts. Exact JSON result after host redaction. |

save()

Save an agent definition

save(definition: StoredAgentDefinition): Promise<void>;

Parameters:

• definition: StoredAgentDefinition

Returns: Promise<void>

load()

Load an agent definition

load(agentId: string): Promise<StoredAgentDefinition | null>;

Parameters:

• agentId: string

Returns: Promise<StoredAgentDefinition | null>

delete()

Delete an agent definition

delete(agentId: string): Promise<void>;

Parameters:

• agentId: string

Returns: Promise<void>

exists()

Check if an agent definition exists

exists(agentId: string): Promise<boolean>;

Parameters:

• agentId: string

Returns: Promise<boolean>

list()

List all agent definitions (summaries only)

list(options?: AgentDefinitionListOptions): Promise<AgentDefinitionSummary[]>;

Parameters:

• options: AgentDefinitionListOptions | undefined (optional)

Returns: Promise<AgentDefinitionSummary[]>

updateMetadata()?

Update agent definition metadata without loading full definition

updateMetadata?(
    agentId: string,
    metadata: Partial<AgentDefinitionMetadata>
  ): Promise<void>;

Parameters:

• agentId: string
• metadata: Partial<AgentDefinitionMetadata>

Returns: Promise<void>

getPath()

Get the storage path/location (for display/debugging)

getPath(): string;

Returns: string

save()

Save agent state

save(state: AgentState): Promise<void>;

Parameters:

• state: AgentState

Returns: Promise<void>

load()

Load agent state

load(agentId: string): Promise<AgentState | undefined>;

Parameters:

• agentId: string

Returns: Promise<AgentState | undefined>

delete()

Delete agent state

delete(agentId: string): Promise<void>;

Parameters:

• agentId: string

Returns: Promise<void>

list()

List agents by status

list(filter?: { status?: AgentStatus[] }): Promise<AgentState[]>;

Parameters:

• filter: { status?: AgentStatus[] | undefined; } | undefined (optional)

Returns: Promise<AgentState[]>

patch()

Update specific fields (partial update for efficiency)

patch(agentId: string, updates: Partial<AgentState>): Promise<void>;

Parameters:

• agentId: string
• updates: Partial<AgentState>

Returns: Promise<void>

destroy()

Asynchronously releases all resources held by this instance.

destroy(): Promise<void>;

Returns: Promise<void>

submitBatch()

submitBatch(
    requests: Array<BatchTextRequest<TOptions>>,
    options?: BatchSubmitOptions,
  ): Promise<BatchHandle>;

Parameters:

• requests: BatchTextRequest<TOptions>[]
• options: BatchSubmitOptions | undefined (optional)

Returns: Promise<BatchHandle>

getBatch()

getBatch(id: string): Promise<BatchHandle>;

Parameters:

• id: string

Returns: Promise<BatchHandle>

cancelBatch()

cancelBatch(id: string): Promise<BatchHandle>;

Parameters:

• id: string

Returns: Promise<BatchHandle>

getBatchResults()

getBatchResults(id: string): AsyncIterable<BatchTextResult<TResponse>>;

Parameters:

• id: string

Returns: AsyncIterable<BatchTextResult<TResponse>>

canAccess()

Check if a connector is accessible in the given context. Receives the full Connector instance so it can inspect config.tags, vendor, serviceType, etc.

canAccess(connector: Connector, context: ConnectorAccessContext): boolean;

Parameters:

• connector: Connector
• context: ConnectorAccessContext

Returns: boolean

save()

Save a connector configuration

save(name: string, stored: StoredConnectorConfig): Promise<void>;

Parameters:

• name: string
• stored: StoredConnectorConfig

Returns: Promise<void>

get()

Retrieve a connector configuration by name

get(name: string): Promise<StoredConnectorConfig | null>;

Parameters:

• name: string

Returns: Promise<StoredConnectorConfig | null>

delete()

Delete a connector configuration

delete(name: string): Promise<boolean>;

Parameters:

• name: string

Returns: Promise<boolean>

has()

Check if a connector configuration exists

has(name: string): Promise<boolean>;

Parameters:

• name: string

Returns: Promise<boolean>

list()

List all connector names

list(): Promise<string[]>;

Returns: Promise<string[]>

listAll()

Get all stored connector configurations

listAll(): Promise<StoredConnectorConfig[]>;

Returns: Promise<StoredConnectorConfig[]>

get()

Get a connector by name. Throw ConnectorNotFoundError when missing or hidden in this scope, with no disclosure of inaccessible connectors. Propagate authentication, configuration and storage failures without reclassifying them as absence. Connector.get() preserves custom-registry errors unchanged.

get(name: string): Connector;

Parameters:

• name: string

Returns: Connector

has()

Check if a connector exists (and is accessible)

has(name: string): boolean;

Parameters:

• name: string

Returns: boolean

list()

List all accessible connector names

list(): string[];

Returns: string[]

listAll()

List all accessible connector instances

listAll(): Connector[];

Returns: Connector[]

size()

Get number of accessible connectors

size(): number;

Returns: number

getDescriptionsForTools()

Get connector descriptions formatted for tool parameters

getDescriptionsForTools(): string;

Returns: string

getInfo()

Get connector info map

getInfo(): Record<string, { displayName: string; description: string; baseURL: string }>;

Returns: Record<string, { displayName: string; description: string; baseURL: string; }>

getById()?

Get a connector by ID. Optional — not all registries support ID-based lookup. Uses the same ConnectorNotFoundError contract as get().

getById?(id: string): Connector;

Parameters:

• id: string

Returns: Connector

warmup()?

Optional async warmup — called before sync reads to ensure connectors are loaded.

Multi-tenant registries can implement this to lazily load connectors for the current request context (e.g., tenant/group). Entry points call Connector.warmup() which delegates here. After warmup completes, all sync read methods (get, has, list, listAll) must return correct results without further async work.

warmup?(): Promise<void>;

Returns: Promise<void>

save()

Save context state to a session

save(
    sessionId: string,
    state: SerializedContextState,
    metadata?: ContextSessionMetadata
  ): Promise<void>;

Parameters:

• sessionId: string
• state: SerializedContextState
• metadata: ContextSessionMetadata | undefined (optional)

Returns: Promise<void>

load()

Load context state from a session

load(sessionId: string): Promise<StoredContextSession | null>;

Parameters:

• sessionId: string

Returns: Promise<StoredContextSession | null>

delete()

Delete a session

delete(sessionId: string): Promise<void>;

Parameters:

• sessionId: string

Returns: Promise<void>

exists()

Check if a session exists

exists(sessionId: string): Promise<boolean>;

Parameters:

• sessionId: string

Returns: Promise<boolean>

list()

List all sessions (summaries only, not full state)

list(options?: ContextStorageListOptions): Promise<ContextSessionSummary[]>;

Parameters:

• options: ContextStorageListOptions | undefined (optional)

Returns: Promise<ContextSessionSummary[]>

updateMetadata()?

Update session metadata without loading full state

updateMetadata?(
    sessionId: string,
    metadata: Partial<ContextSessionMetadata>
  ): Promise<void>;

Parameters:

• sessionId: string
• metadata: Partial<ContextSessionMetadata>

Returns: Promise<void>

getPath()

Get the storage path (for display/debugging)

getPath(): string;

Returns: string

getLocation()?

Get a human-readable storage location string (for display/debugging). Examples: file path, MongoDB URI, Redis key prefix, S3 bucket, etc. Falls back to getPath() if not implemented.

getLocation?(): string;

Returns: string

When present, AgentContextNextGen automatically appends every message to the journal (append-oriented, fire-and-forget). The journal is never affected by compaction, preserving full conversation history.

Storage implementations create the appropriate journal for their backend:

• FileContextStorage → FileHistoryJournal (JSONL files)
• MongoContextStorage → MongoHistoryJournal (collection)

Consumers never configure the journal separately — it comes for free with the storage backend. |

save()

Save a correlation mapping. If a correlation with the same ID already exists, it is overwritten.

save(correlationId: string, ref: SessionRef): Promise<void>;

Parameters:

• correlationId: string
• ref: SessionRef

Returns: Promise<void>

resolve()

Resolve a correlation ID to a session reference. Returns null if not found or expired.

resolve(correlationId: string): Promise<SessionRef | null>;

Parameters:

• correlationId: string

Returns: Promise<SessionRef | null>

delete()

Delete a correlation mapping.

delete(correlationId: string): Promise<void>;

Parameters:

• correlationId: string

Returns: Promise<void>

exists()

Check if a correlation exists and is not expired.

exists(correlationId: string): Promise<boolean>;

Parameters:

• correlationId: string

Returns: Promise<boolean>

listBySession()

List all correlations for a given session. Useful for cleanup when a session is resumed or deleted.

listBySession(sessionId: string): Promise<string[]>;

Parameters:

• sessionId: string

Returns: Promise<string[]>

listByAgent()

List all correlations for a given agent.

listByAgent(agentId: string): Promise<CorrelationSummary[]>;

Parameters:

• agentId: string

Returns: Promise<CorrelationSummary[]>

pruneExpired()

Remove all expired correlations.

pruneExpired(): Promise<number>;

Returns: Promise<number>

getPath()

Get the storage path (for debugging/logging).

getPath(): string;

Returns: string

destroy()

Releases all resources held by this instance.

After calling destroy():

• All event listeners should be removed
• All timers/intervals should be cleared
• All internal state should be cleaned up
• The instance should not be reused

Multiple calls to destroy() should be safe (idempotent).

destroy(): void;

Returns: void

embed()

Generate embeddings for one or more inputs

embed(options: EmbeddingOptions): Promise<EmbeddingResponse>;

Parameters:

• options: EmbeddingOptions

Returns: Promise<EmbeddingResponse>

listModels()?

List available embedding models (optional)

listModels?(): Promise<string[]>;

Returns: Promise<string[]>

put()

put(record: EvidenceRecord): Promise<EvidenceReference>;

Parameters:

• record: EvidenceRecord

Returns: Promise<EvidenceReference>

getReference()?

Optional efficient scoped ID lookup; implementations verify stored integrity before returning metadata.

getReference?(id: string, signal?: AbortSignal): Promise<EvidenceReference | null>;

Parameters:

• id: string
• signal: AbortSignal | undefined (optional)

Returns: Promise<EvidenceReference | null>

read()

Integrity checks cover the entire bounded blob even when reading a chunk.

read(reference: EvidenceReference, options?: EvidenceReadOptions): Promise<EvidenceChunk | null>;

Parameters:

• reference: EvidenceReference
• options: EvidenceReadOptions | undefined (optional)

Returns: Promise<EvidenceChunk | null>

readRecord()

Host-only full read, still bounded by maxRecordBytes (default 4 MiB).

readRecord(reference: EvidenceReference): Promise<EvidenceRecord | null>;

Parameters:

• reference: EvidenceReference

Returns: Promise<EvidenceRecord | null>

list()

list(options?: { after?: string; limit?: number; signal?: AbortSignal }): Promise<{ entries: EvidenceEntry[]; next?: string }>;

Parameters:

• options: { after?: string | undefined; limit?: number | undefined; signal?: AbortSignal | undefined; } | undefined (optional)

Returns: Promise<{ entries: EvidenceEntry[]; next?: string | undefined; }>

delete()

delete(reference: EvidenceReference): Promise<boolean>;

Parameters:

• reference: EvidenceReference

Returns: Promise<boolean>

pruneExpired()

Explicit host maintenance; no scratch eviction or compaction deletes evidence.

pruneExpired(now?: number): Promise<number>;

Parameters:

• now: number | undefined (optional)

Returns: Promise<number>

append()

Append entries to the journal.

This is the primary write operation, called on every addUserMessage(), addAssistantResponse(), and addToolResults(). Should be fast and append-oriented.

append(sessionId: string, entries: HistoryEntry[]): Promise<void>;

Parameters:

• sessionId: string
• entries: HistoryEntry[]

Returns: Promise<void>

replaceLast()?

Replace the most recent entry matching type + turnIndex.

Normal history writes remain append-oriented, but post-processing may need to correct the assistant message that was just committed (for example, structured-output reformatting). Returning false lets callers fall back to append() if they still want to preserve the corrected entry.

replaceLast?(
    sessionId: string,
    type: HistoryEntryType,
    turnIndex: number,
    entry: HistoryEntry,
  ): Promise<boolean>;

Parameters:

• sessionId: string
• type: HistoryEntryType
• turnIndex: number
• entry: HistoryEntry

Returns: Promise<boolean>

read()

Read history entries with optional filtering and pagination.

Entries are returned in chronological order (oldest first).

read(sessionId: string, options?: HistoryReadOptions): Promise<HistoryEntry[]>;

Parameters:

• sessionId: string
• options: HistoryReadOptions | undefined (optional)

Returns: Promise<HistoryEntry[]>

count()

Get the total number of entries in the journal.

count(sessionId: string): Promise<number>;

Parameters:

• sessionId: string

Returns: Promise<number>

clear()

Delete all history for a session.

Called when a session is deleted via IContextStorage.delete().

clear(sessionId: string): Promise<void>;

Parameters:

• sessionId: string

Returns: Promise<void>

stream()?

Stream history entries for large histories.

Optional — implementations may omit this if streaming isn't practical (e.g., in-memory storage). Callers should fall back to read() with pagination if stream() is not available.

stream?(sessionId: string, options?: HistoryReadOptions): AsyncIterable<HistoryEntry>;

Parameters:

• sessionId: string
• options: HistoryReadOptions | undefined (optional)

Returns: AsyncIterable<HistoryEntry>

getLocation()?

Get a human-readable location string for debugging/display.

getLocation?(sessionId: string): string;

Parameters:

• sessionId: string

Returns: string

addMessage()

Add a message to history

addMessage(role: 'user' | 'assistant' | 'system', content: string, metadata?: Record<string, unknown>): Promise<HistoryMessage>;

Parameters:

• role: "user" | "assistant" | "system"
• content: string
• metadata: Record<string, unknown> | undefined (optional)

Returns: Promise<HistoryMessage>

getMessages()

Get all messages (may include summaries as system messages)

getMessages(): Promise<HistoryMessage[]>;

Returns: Promise<HistoryMessage[]>

getRecentMessages()

Get recent messages only

getRecentMessages(count?: number): Promise<HistoryMessage[]>;

Parameters:

• count: number | undefined (optional)

Returns: Promise<HistoryMessage[]>

formatForContext()

Get formatted history for LLM context

formatForContext(options?: { maxTokens?: number; includeMetadata?: boolean }): Promise<string>;

Parameters:

• options: { maxTokens?: number | undefined; includeMetadata?: boolean | undefined; } | undefined (optional)

Returns: Promise<string>

compact()

Compact history (apply compaction strategy)

compact(): Promise<void>;

Returns: Promise<void>

clear()

Clear all history

clear(): Promise<void>;

Returns: Promise<void>

getMessageCount()

Get message count

getMessageCount(): Promise<number>;

Returns: Promise<number>

getState()

Get state for session persistence

getState(): Promise<SerializedHistoryState>;

Returns: Promise<SerializedHistoryState>

restoreState()

Restore from saved state

restoreState(state: SerializedHistoryState): Promise<void>;

Parameters:

• state: SerializedHistoryState

Returns: Promise<void>

getConfig()

Get current configuration

getConfig(): IHistoryManagerConfig;

Returns: IHistoryManagerConfig

addMessage()

Store a message

addMessage(message: HistoryMessage): Promise<void>;

Parameters:

• message: HistoryMessage

Returns: Promise<void>

getMessages()

Get all messages

getMessages(): Promise<HistoryMessage[]>;

Returns: Promise<HistoryMessage[]>

getRecentMessages()

Get recent N messages

getRecentMessages(count: number): Promise<HistoryMessage[]>;

Parameters:

• count: number

Returns: Promise<HistoryMessage[]>

removeMessage()

Remove a message by ID

removeMessage(id: string): Promise<void>;

Parameters:

• id: string

Returns: Promise<void>

removeOlderThan()

Remove messages older than timestamp

removeOlderThan(timestamp: number): Promise<number>;

Parameters:

• timestamp: number

Returns: Promise<number>

clear()

Clear all messages

clear(): Promise<void>;

Returns: Promise<void>

getCount()

Get message count

getCount(): Promise<number>;

Returns: Promise<number>

getState()

Get serialized state for session persistence

getState(): Promise<SerializedHistoryState>;

Returns: Promise<SerializedHistoryState>

restoreState()

Restore from serialized state

restoreState(state: SerializedHistoryState): Promise<void>;

Parameters:

• state: SerializedHistoryState

Returns: Promise<void>

connect()

Connect to the MCP server

connect(): Promise<void>;

Returns: Promise<void>

disconnect()

Disconnect from the MCP server

disconnect(): Promise<void>;

Returns: Promise<void>

reconnect()

Reconnect to the MCP server

reconnect(): Promise<void>;

Returns: Promise<void>

isConnected()

Check if connected

isConnected(): boolean;

Returns: boolean

ping()

Ping the server to check health

ping(): Promise<boolean>;

Returns: Promise<boolean>

listTools()

List available tools from the server

listTools(): Promise<MCPTool[]>;

Returns: Promise<MCPTool[]>

callTool()

Call a tool on the server

callTool(name: string, args: Record<string, unknown>): Promise<MCPToolResult>;

Parameters:

• name: string
• args: Record<string, unknown>

Returns: Promise<MCPToolResult>

registerTools()

Register all tools with a ToolManager

registerTools(toolManager: ToolManager): void;

Parameters:

• toolManager: ToolManager

Returns: void

registerToolsSelective()

Register specific tools with a ToolManager (selective registration)

registerToolsSelective(toolManager: ToolManager, toolNames?: string[]): void;

Parameters:

• toolManager: ToolManager
• toolNames: string[] | undefined (optional)

Returns: void

unregisterTools()

Unregister all tools from a ToolManager

unregisterTools(toolManager: ToolManager): void;

Parameters:

• toolManager: ToolManager

Returns: void

listResources()

List available resources from the server

listResources(): Promise<MCPResource[]>;

Returns: Promise<MCPResource[]>

readResource()

Read a resource from the server

readResource(uri: string): Promise<MCPResourceContent>;

Parameters:

• uri: string

Returns: Promise<MCPResourceContent>

subscribeResource()

Subscribe to resource updates

subscribeResource(uri: string): Promise<void>;

Parameters:

• uri: string

Returns: Promise<void>

unsubscribeResource()

Unsubscribe from resource updates

unsubscribeResource(uri: string): Promise<void>;

Parameters:

• uri: string

Returns: Promise<void>

listPrompts()

List available prompts from the server

listPrompts(): Promise<MCPPrompt[]>;

Returns: Promise<MCPPrompt[]>

getPrompt()

Get a prompt from the server

getPrompt(name: string, args?: Record<string, unknown>): Promise<MCPPromptResult>;

Parameters:

• name: string
• args: Record<string, unknown> | undefined (optional)

Returns: Promise<MCPPromptResult>

getState()

Get current state for serialization

getState(): MCPClientState;

Returns: MCPClientState

loadState()

Load state from serialization

loadState(state: MCPClientState): void;

Parameters:

• state: MCPClientState

Returns: void

destroy()

Destroy the client and clean up resources

destroy(): void;

Returns: void

save()

Save media data to storage

save(data: Buffer, metadata: MediaStorageMetadata): Promise<MediaStorageResult>;

Parameters:

• data: Buffer<ArrayBufferLike>
• metadata: MediaStorageMetadata

Returns: Promise<MediaStorageResult>

read()

Read media data from storage

read(location: string): Promise<Buffer | null>;

Parameters:

• location: string

Returns: Promise<Buffer<ArrayBufferLike> | null>

delete()

Delete media from storage

delete(location: string): Promise<void>;

Parameters:

• location: string

Returns: Promise<void>

exists()

Check if media exists in storage

exists(location: string): Promise<boolean>;

Parameters:

• location: string

Returns: Promise<boolean>

list()?

List media files in storage (optional)

list?(options?: MediaStorageListOptions): Promise<MediaStorageEntry[]>;

Parameters:

• options: MediaStorageListOptions | undefined (optional)

Returns: Promise<MediaStorageEntry[]>

getPath()

Get the storage path/location (for display/debugging)

getPath(): string;

Returns: string

load()

Load instruction entries from storage

load(): Promise<InstructionEntry[] | null>;

Returns: Promise<InstructionEntry[] | null>

save()

Save instruction entries to storage

save(entries: InstructionEntry[]): Promise<void>;

Parameters:

• entries: InstructionEntry[]

Returns: Promise<void>

delete()

Delete instructions from storage

delete(): Promise<void>;

Returns: Promise<void>

exists()

Check if instructions exist in storage

exists(): Promise<boolean>;

Returns: Promise<boolean>

getPath()

Get the storage path (for display/debugging)

getPath(): string;

Returns: string

validateConfig()

Validate that the provider configuration is correct

validateConfig(): Promise<boolean>;

Returns: Promise<boolean>

save()

save(context: StorageUserContextInput, definition: RoutineDefinition): Promise<void>;

Parameters:

• context: StorageUserContextInput
• definition: RoutineDefinition

Returns: Promise<void>

load()

load(context: StorageUserContextInput, id: string): Promise<RoutineDefinition | null>;

Parameters:

• context: StorageUserContextInput
• id: string

Returns: Promise<RoutineDefinition | null>

delete()

delete(context: StorageUserContextInput, id: string): Promise<void>;

Parameters:

• context: StorageUserContextInput
• id: string

Returns: Promise<void>

exists()

exists(context: StorageUserContextInput, id: string): Promise<boolean>;

Parameters:

• context: StorageUserContextInput
• id: string

Returns: Promise<boolean>

list()

List routine summaries (slim projection). Use load(id) to fetch the full definition for any returned entry.

list(context: StorageUserContextInput, options?: {
    tags?: string[];
    search?: string;
    limit?: number;
    offset?: number;
  }): Promise<RoutineSummary[]>;

Parameters:

• context: StorageUserContextInput
• options: { tags?: string[] | undefined; search?: string | undefined; limit?: number | undefined; offset?: number | undefined; } | undefined (optional)

Returns: Promise<RoutineSummary[]>

getPath()

getPath(context: StorageUserContextInput): string;

Parameters:

• context: StorageUserContextInput

Returns: string

insert()

Insert a new execution record. Returns the record ID.

insert(context: StorageUserContextInput, record: RoutineExecutionRecord): Promise<string>;

Parameters:

• context: StorageUserContextInput
• record: RoutineExecutionRecord

Returns: Promise<string>

update()

Update top-level fields on an execution record.

update(
    id: string,
    updates: Partial<
      Pick<RoutineExecutionRecord, 'status' | 'progress' | 'error' | 'completedAt' | 'lastActivityAt'>
    >,
  ): Promise<void>;

Parameters:

• id: string
• updates: Partial<Pick<RoutineExecutionRecord, "error" | "status" | "progress" | "completedAt" | "lastActivityAt">>

Returns: Promise<void>

pushStep()

Append a step to the execution's steps array.

pushStep(id: string, step: RoutineExecutionStep): Promise<void>;

Parameters:

• id: string
• step: RoutineExecutionStep

Returns: Promise<void>

updateTask()

Update a specific task snapshot within the execution record.

updateTask(id: string, taskName: string, updates: Partial<RoutineTaskSnapshot>): Promise<void>;

Parameters:

• id: string
• taskName: string
• updates: Partial<RoutineTaskSnapshot>

Returns: Promise<void>

load()

Load a single execution record by ID.

load(id: string): Promise<RoutineExecutionRecord | null>;

Parameters:

• id: string

Returns: Promise<RoutineExecutionRecord | null>

list()

List execution records with optional filters.

list(
    context: StorageUserContextInput,
    options?: {
      routineId?: string;
      status?: RoutineExecutionStatus;
      limit?: number;
      offset?: number;
    },
  ): Promise<RoutineExecutionRecord[]>;

Parameters:

• context: StorageUserContextInput
• options: { routineId?: string | undefined; status?: RoutineExecutionStatus | undefined; limit?: number | undefined; offset?: number | undefined; } | undefined (optional)

Returns: Promise<RoutineExecutionRecord[]>

hasRunning()

Check if a routine has a currently running execution.

hasRunning(context: StorageUserContextInput, routineId: string): Promise<boolean>;

Parameters:

• context: StorageUserContextInput
• routineId: string

Returns: Promise<boolean>

schedule()

Schedule a callback. Returns a handle to cancel it.

schedule(id: string, spec: ScheduleSpec, callback: () => void | Promise<void>): ScheduleHandle;

Parameters:

• id: string
• spec: ScheduleSpec
• callback: () => void | Promise<void>

Returns: ScheduleHandle

cancel()

Cancel a scheduled callback by ID.

cancel(id: string): void;

Parameters:

• id: string

Returns: void

cancelAll()

Cancel all scheduled callbacks.

cancelAll(): void;

Returns: void

has()

Check if a schedule exists by ID.

has(id: string): boolean;

Parameters:

• id: string

Returns: boolean

transcribe()

Transcribe audio to text

transcribe(options: STTOptions): Promise<STTResponse>;

Parameters:

• options: STTOptions

Returns: Promise<STTResponse>

translate()?

Translate audio to English text (optional, Whisper-specific)

translate?(options: STTOptions): Promise<STTResponse>;

Parameters:

• options: STTOptions

Returns: Promise<STTResponse>

compact()

compact(options: TextGenerateOptions): Promise<TextCompactionResponse>;

Parameters:

• options: TextGenerateOptions

Returns: Promise<TextCompactionResponse>

countInput()

countInput(options: TextGenerateOptions): Promise<number | null>;

Parameters:

• options: TextGenerateOptions

Returns: Promise<number | null>

generate()

Generate text response

generate(options: TextGenerateOptions): Promise<LLMResponse>;

Parameters:

• options: TextGenerateOptions

Returns: Promise<LLMResponse>

streamGenerate()

Stream text response with real-time events Returns an async iterator of streaming events

streamGenerate(options: TextGenerateOptions): AsyncIterableIterator<StreamEvent>;

Parameters:

• options: TextGenerateOptions

Returns: AsyncIterableIterator<StreamEvent>

getModelCapabilities()

Get model capabilities

getModelCapabilities(model: string): ModelCapabilities;

Parameters:

• model: string

Returns: ModelCapabilities

getAdvancedCapabilities()?

Executable advanced capabilities for a concrete model/provider pair.

getAdvancedCapabilities?(model: string): AdvancedTextCapabilities;

Parameters:

• model: string

Returns: AdvancedTextCapabilities

listModels()

List available models from the provider's API

listModels(): Promise<string[]>;

Returns: Promise<string[]>

synthesize()

Synthesize speech from text

synthesize(options: TTSOptions): Promise<TTSResponse>;

Parameters:

• options: TTSOptions

Returns: Promise<TTSResponse>

listVoices()?

List available voices (optional - some providers return static list)

listVoices?(): Promise<IVoiceInfo[]>;

Returns: Promise<IVoiceInfo[]>

load()

Load user info entries from storage for a specific user

load(userId: string | undefined): Promise<UserInfoEntry[] | null>;

Parameters:

• userId: string | undefined

Returns: Promise<UserInfoEntry[] | null>

save()

Save user info entries to storage for a specific user

save(userId: string | undefined, entries: UserInfoEntry[]): Promise<void>;

Parameters:

• userId: string | undefined
• entries: UserInfoEntry[]

Returns: Promise<void>

delete()

Delete user info from storage for a specific user

delete(userId: string | undefined): Promise<void>;

Parameters:

• userId: string | undefined

Returns: Promise<void>

exists()

Check if user info exists in storage for a specific user

exists(userId: string | undefined): Promise<boolean>;

Parameters:

• userId: string | undefined

Returns: Promise<boolean>

getPath()

Get the storage path for a specific user (for display/debugging)

getPath(userId: string | undefined): string;

Parameters:

• userId: string | undefined

Returns: string

load()

Load all rules for a user. Returns null if no rules exist.

load(userId: string | undefined): Promise<UserPermissionRule[] | null>;

Parameters:

• userId: string | undefined

Returns: Promise<UserPermissionRule[] | null>

save()

Save all rules for a user (full replacement).

save(userId: string | undefined, rules: UserPermissionRule[]): Promise<void>;

Parameters:

• userId: string | undefined
• rules: UserPermissionRule[]

Returns: Promise<void>

delete()

Delete all rules for a user.

delete(userId: string | undefined): Promise<void>;

Parameters:

• userId: string | undefined

Returns: Promise<void>

exists()

Check if rules exist for a user.

exists(userId: string | undefined): Promise<boolean>;

Parameters:

• userId: string | undefined

Returns: Promise<boolean>

getPath()

Get storage path (for debugging/display).

getPath(userId: string | undefined): string;

Parameters:

• userId: string | undefined

Returns: string

cancel()

cancel(): void;

Returns: void

savedAt: number;
agentId?: string;
userId?: string;
model: string;

};| Metadata | |agentState?|agentState?: Record<string, unknown>;` | Agent-specific state (for TaskAgent, UniversalAgent, etc.) |

Default: false (normal user-scoped behavior) |

/** Connector name (must be registered at runtime) */
name: string;
/** Model to use */
model: string;

};| Connector configuration | |systemPrompt?|systemPrompt?: string;| System prompt | |instructions?|instructions?: string;| Instructions | |features?|features?: ContextFeatures;| Feature configuration | |metadata?|metadata?: AgentDefinitionMetadata;| Agent metadata | |typeConfig?|typeConfig?: Record<string, unknown>;` | Agent-type-specific configuration |

type: 'text' | 'json_object' | 'json_schema';
json_schema?: any;

};| - | |parallel_tool_calls?|parallel_tool_calls?: boolean;| - | |previous_response_id?|previous_response_id?: string;| - | |continuation_token?|continuation_token?: string;| Opaque provider token used to resume an incomplete long decode. | |metadata?|metadata?: Record<string, string>;| - | |prompt_cache?|prompt_cache?: PromptCachePolicy;| Provider-neutral prompt-cache policy. Unsupported strict requests fail before execution.mode: 'off'suppresses library-requested cache controls but cannot disable provider-implicit caching. | |native_tools?|native_tools?: NativeToolRequest[];| Provider-hosted tools. These are not executed by ToolManager. | |data_handling?|data_handling?: DataHandlingPolicy;| Host policy for retention-sensitive provider features. | |credential_context?|credential_context?: { userId?: string; connectorRegistry?: IConnectorRegistry };| - | |thinking?|thinking?: ThinkingConfig;| Vendor-agnostic thinking/reasoning configuration | |vendorOptions?|vendorOptions?: Record<string, any>;| Vendor-specific options (e.g., Google's thinkingLevel, OpenAI's reasoning_effort) | |skipContextLimitCheck?|skipContextLimitCheck?: boolean;` | Skip pre-flight context limit check. Default: false (check is ON) |