Abstract Class: AIAgent<TBus, TConnector>

Makaio Framework

Makaio Framework / ai-adapters-core / AIAgent

Abstract Class: AIAgent<TBus, TConnector>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:112

Abstract base class for AI agents.

Bridges adapter/agent bus subjects to connector sessions.

Type Parameters

TBus

TBus extends ScopedBus<string> = ScopedBus<string>

The scoped bus type for this adapter

TConnector

TConnector extends AIAgentConnector<TBus> = AIAgentConnector<TBus>

The connector type this agent wraps

Constructors

Constructor

new AIAgent<TBus, TConnector>(config): AIAgent<TBus, TConnector>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:158

Create an AIAgent instance.

Note: Does NOT create the connector yet - call init() after construction.

Parameters

config

AIAgentConfig<TBus, TConnector>

Agent configuration

Returns

AIAgent<TBus, TConnector>

Properties

availableModels?

protected readonly optional availableModels?: object[]

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:151

Available models for context window lookup

contextWindowSize

contextWindowSize: number

Maximum context window size in tokens.

family?

optional family?: string

Model family name (e.g., ‘opus’, ‘sonnet’, ‘gpt-4o’). Used for alias resolution and UI grouping.

friendlyName?

optional friendlyName?: string

Human-readable display name (e.g., ‘Sonnet 4.5’, ‘GPT-4o’).

labId

labId: string

Lab that created this model (e.g., ‘anthropic’, ‘openai’, ‘google’).

metadata?

optional metadata?: object

Supplementary metadata from rich provider APIs (pricing, capabilities, etc.). Not used for routing or adapter logic — purely informational.

metadata.capabilities?

optional capabilities?: object

Provider-scoped capabilities for this model offering.

metadata.capabilities.parallelToolCalls?

optional parallelToolCalls?: boolean

Whether multiple tool calls can be issued in a single turn.

metadata.capabilities.pdfUpload?

optional pdfUpload?: boolean

Whether the provider accepts PDF file uploads.

metadata.capabilities.speechToText?

optional speechToText?: object

Speech-to-text capability descriptor.

metadata.capabilities.speechToText.modes

modes: (… | …)[]

Supported transcription modes.

metadata.capabilities.speechToText.vocabularyBiasing?

optional vocabularyBiasing?: boolean

Whether the model supports vocabulary/terminology biasing. Optional by design because model metadata can be partial, unlike provider runtime capabilities.

metadata.capabilities.structuredOutput?

optional structuredOutput?: boolean

Whether the provider supports structured (JSON schema) output.

metadata.capabilities.textToSpeech?

optional textToSpeech?: object

Text-to-speech capability descriptor.

metadata.capabilities.textToSpeech.modes

modes: (… | …)[]

Supported synthesis modes.

metadata.capabilities.textToSpeech.outputFormats?

optional outputFormats?: …[]

Supported output audio formats. Optional because metadata may omit it.

metadata.capabilities.textToSpeech.voiceInstructions?

optional voiceInstructions?: boolean

Whether the model supports style/tone instructions (e.g., gpt-4o-mini-tts). Optional because metadata may omit it.

metadata.capabilities.textToSpeech.voiceSelection?

optional voiceSelection?: boolean

Whether the user can select a voice preset. Optional because model metadata may omit it.

metadata.capabilities.toolCalling?

optional toolCalling?: boolean

Whether the provider’s API supports tool/function calling.

metadata.capabilities.vision?

optional vision?: boolean

Whether the model accepts image inputs.

metadata.description?

optional description?: string

Optional description of the model *

metadata.includedInSubscription?

optional includedInSubscription?: boolean

Whether this model is included in the provider’s subscription plan.

metadata.maxOutputTokens?

optional maxOutputTokens?: number

Maximum output tokens the provider allows for this model.

metadata.pricing?

optional pricing?: object

Token pricing for this model offering.

metadata.pricing.request?

optional request?: object

Per-request pricing (GitHub Copilot premium requests, etc.).

metadata.pricing.request.multiplier

multiplier: number

Cost per request in provider billing units (0 = free).

metadata.pricing.token?

optional token?: object

Per-token pricing (Anthropic direct, OpenAI direct, etc.).

metadata.pricing.token.cacheWritePerMillion?

optional cacheWritePerMillion?: number

Cost per million cache-write input tokens (USD).

metadata.pricing.token.inputCachedPerMillion?

optional inputCachedPerMillion?: number

Cost per million cache-read input tokens (USD).

metadata.pricing.token.inputPerMillion

inputPerMillion: number

Cost per million input tokens (USD).

metadata.pricing.token.outputPerMillion

outputPerMillion: number

Cost per million output tokens (USD).

name

name: string

Model identifier used by the provider (e.g., ‘claude-sonnet-4-6’, ‘gpt-4o’, ‘gemini-2.5-pro’).

supportedReasoningLevels?

optional supportedReasoningLevels?: object

Maps supported reasoning levels to provider-native values. When omitted, the model does not support extended thinking / reasoning.

supportedReasoningLevels.extra-high?

optional extra-high?: string | number = reasoningLevelValue

supportedReasoningLevels.high?

optional high?: string | number = reasoningLevelValue

supportedReasoningLevels.low?

optional low?: string | number = reasoningLevelValue

supportedReasoningLevels.medium?

optional medium?: string | number = reasoningLevelValue

supportedReasoningLevels.none?

optional none?: string | number = reasoningLevelValue

config

protected readonly config: object

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:149

Normalized config with defaults applied

adapterBus

adapterBus: TBus

Scoped bus for adapter-specific events

adapterId

adapterId: string

Adapter instance identifier

adapterName

adapterName: string

Adapter type name (e.g., ‘claude-code’, ‘gemini-sdk’)

adapterSessionId?

optional adapterSessionId?: string

Adapter-specific session identifier for multi-turn conversations

agentId

agentId: string

Unique agent identifier

allowedDirectories?

optional allowedDirectories?: string[]

Directory restrictions for file-system tool execution.

allowedTools?

optional allowedTools?: string[]

Allowed tool names (adapter-specific). Empty array = disable all tools.

availableModels?

optional availableModels?: object[]

Available models for this adapter (used for context window lookup)

capabilities

capabilities: string[]

Adapter capabilities (e.g., [‘streaming’, ‘tools’, ‘vision’])

clientId?

optional clientId?: string

Client identifier for the application this adapter belongs to (e.g., ‘claude-code’, ‘gemini’).

configFactory

configFactory: (input) => Promise<BaseAgentConnectorConfig<TBus, object> & object>

Config factory - transforms partial input into full adapter-specific config. This is the seam where adapters inject their defaults (especially model).

Parameters

input

ConfigFactoryInput<TBus>

Returns

Promise<BaseAgentConnectorConfig<TBus, object> & object>

connectorFactory

connectorFactory: (config) => TConnector | Promise<TConnector>

Connector factory - creates connector from full config. Called AFTER configFactory returns the complete configuration. Config includes adapterId (passed through from input by config factory).

Parameters

config

BaseAgentConnectorConfig<TBus, object> & object

Returns

TConnector | Promise<TConnector>

cwd?

optional cwd?: string

Working directory for agent execution (optional - platform provides default)

disallowedTools?

optional disallowedTools?: string[]

Disallowed tool names (adapter-specific). Takes precedence over allowedTools.

env?

optional env?: Record<string, string>

Environment variables to pass to agent execution

ephemeral?

optional ephemeral?: boolean

When true, PreUserMessage hooks are skipped for this agent. Use for ephemeral ping agents where session enrichment and context injection are not needed and would be actively harmful.

globalBus

globalBus: IMakaioBus

Global bus instance (defaults to MakaioBus singleton)

harnessId?

optional harnessId?: string

Resolved harness ID for tool policy lookup.

mcpSessionContext?

optional mcpSessionContext?: LedgerSessionContext

MCP session context resolved by the orchestrator. Passed through to the connector config so adapters can inject direct tools.

model?

optional model?: string

Model to use (optional - adapter provides default)

nativeTools

nativeTools: string[]

Native tools built into the adapter (e.g., [‘shell_command’, ‘apply_patch’])

providerContext?

optional providerContext?: object

Unresolved provider context (credential refs, not plaintext). Set by the orchestrator before forwarding the startAgent request. Connectors resolve credentials locally via resolveConnectorCredentials().

providerContext.credentialEnvVars?

optional credentialEnvVars?: Record<string, string>

Maps credential keys to environment variable names for subprocess adapters. E.g., { apiKey: 'ANTHROPIC_API_KEY' }.

providerContext.credentialRefs

credentialRefs: Record<string, string & $brand<"CredentialRef">>

Credential references resolved at the connector layer, not on the bus.

providerContext.definitionId

definitionId: string

Provider definition ID (e.g., 'anthropic', 'alibaba').

providerContext.endpointOverrides?

optional endpointOverrides?: object

Endpoint URL overrides keyed by protocol.

providerContext.endpointOverrides.anthropic?

optional anthropic?: string

providerContext.endpointOverrides.openai?

optional openai?: string

providerContext.providerConfigId

providerConfigId: string

Provider config UUID. Links back to the ProviderConfig that produced this context.

reasoningEffort?

optional reasoningEffort?: "none" | "low" | "medium" | "high" | "extra-high"

Reasoning effort for supporting adapters

resumeAdapterSessionId?

optional resumeAdapterSessionId?: string

Previous adapter session ID for resume attempts (from recovery).

sessionId?

optional sessionId?: string

Makaio session identifier

toolLedger?

optional toolLedger?: ISessionToolLedger

Session-scoped ledger tracking MCP injection/discovery/call history. Created once per agent session and passed through unchanged on connector swaps.

confirmedModel?

protected optional confirmedModel?: string

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:118

connector

protected connector: TConnector

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:117

The underlying connector instance (created in init)

initialModel?

protected optional initialModel?: string

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:119

lifecycleTracker

protected readonly lifecycleTracker: MessageLifecycleTracker

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:131

Tracks message lifecycle and emits turn events.

toolCallTracker

protected readonly toolCallTracker: ToolCallTracker

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:133

Tracks tool.use → tool.output correlation across adapters.

Accessors

adapterId

Get Signature

get adapterId(): string

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:269

Returns

string

Adapter instance identifier

adapterName

Get Signature

get adapterName(): string

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:273

Returns

string

Adapter type name (e.g., ‘claude-code’, ‘gemini-sdk’)

adapterSessionId

Get Signature

get protected adapterSessionId(): string | undefined

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:289

Returns

string | undefined

Initial adapter session ID from config (may differ from connector’s resolved session ID)

agentId

Get Signature

get agentId(): string

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:265

Returns

string

Unique agent identifier

capabilities

Get Signature

get capabilities(): string[]

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:277

Returns

string[]

Adapter capabilities for runtime feature detection

globalBus

Get Signature

get protected globalBus(): IMakaioBus

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:293

Returns

IMakaioBus

Global bus for cross-namespace communication (defaulted in constructor)

nativeTools

Get Signature

get nativeTools(): string[]

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:281

Returns

string[]

Native tools built into the adapter

sessionId

Get Signature

get sessionId(): string | undefined

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:285

Returns

string | undefined

Shared Makaio sessionId

Methods

abort()

abort(): void

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:906

Abort the agent immediately (panic mode). Triggers AbortController which may cause provider errors. Use close() for graceful shutdown instead.

Emits session.closed event (once per session) then delegates to the underlying connector’s abort method.

Returns

void

Throws

Error if connector is not initialized

addBusHandlerCleanup()

protected addBusHandlerCleanup(cleanup): void

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:583

Registers a cleanup function for a global bus subscription. These survive connector swaps and are cleaned up in close().

Parameters

cleanup

() => void

Function to unsubscribe from the bus

Returns

void

addConnectorWiringCleanup()

protected addConnectorWiringCleanup(cleanup): void

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:574

Register a cleanup function for connector wiring. These cleanups are cleared on connector swap but preserved across bus handler changes.

Parameters

cleanup

() => void

Cleanup function to register

Returns

void

close()

close(options?): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:768

Clean up resources and emit session closed event.

Emits session.closed event (once per session) unless explicitly suppressed, then unsubscribes from all bus handlers and aborts the connector if available.

Parameters

options?

Cleanup options; ephemeral agents suppress session-close lifecycle events because they never join a session.

emitSessionClosed?

boolean

Returns

Promise<void>

complete()

complete(): Promise<MessageResult | null>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:929

Complete the agent session by waiting for all messages to finish.

Delegates to the underlying connector’s complete method.

Returns

Promise<MessageResult | null>

Last message result or null if no messages processed

Throws

Error if connector is not initialized

createConnectorEventMapping()

protected createConnectorEventMapping<TSourceSubject, TNestedMessageProp, TMessage, TDiscriminator>(sourceSubject, discriminator, handlers, nestedMessageProp?): () => void

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:941

Creates a type-safe event mapping from connector events to scoped subjects or handlers.

Type Parameters

TSourceSubject

TSourceSubject extends ScopedSubjectDefinition<TConnector extends AIAgentConnector<TBus, BaseAgentConnectorConfig<TBus, object>> ? TBus["namespace"] : never>

TNestedMessageProp

TNestedMessageProp extends string | number | symbol | undefined = undefined

TMessage

TMessage = TNestedMessageProp extends keyof TSourceSubject["$meta"]["payload"] ? TSourceSubject["$meta"]["payload"][TNestedMessageProp] : TSourceSubject["$meta"]["payload"]

TDiscriminator

TDiscriminator extends string = DiscriminatorKeys<TMessage>

Parameters

sourceSubject

TSourceSubject

The connector subject to subscribe to

discriminator

TDiscriminator

The discriminator key within the message (e.g., ‘type’)

handlers

ConnectorEventHandlers<TMessage, TDiscriminator>

Map of discriminator values to target subjects or handler functions

nestedMessageProp?

TNestedMessageProp

Property containing the discriminated union (e.g., ‘msg’), or undefined for top-level

Returns

Unsubscribe function for the connector event mapping subscription

() => void

emitCompletion()

protected emitCompletion(result): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:389

Parameters

result

Omit<z.infer<typeof AgentSchemas.complete>, keyof AgentContext>

Returns

Promise<void>

emitContextWindowUpdate()

protected emitContextWindowUpdate(input): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:468

Emit context window status for compression trigger decisions.

Calculates fill percentage and warning level from raw metrics. Called by subclasses after usage tracking with provider-specific metrics.

Parameters

input

ContextWindowInput

Raw metrics: currentTokens, maxTokens, optional cachedTokens

Returns

Promise<void>

emitError()

protected emitError(result): void

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:403

Stash error metadata for the next emitCompletion call.

The lifecycle tracker emits agent.complete with outcome: 'error' when the message handle completes. This method runs first (from the connector’s errorHandler) and stashes errorCategory so emitCompletion can include it in the complete payload.

No longer emits agent.error — all terminal events flow through agent.complete.

Parameters

result

Pick<z.infer<typeof AgentSchemas.complete>, "error" | "errorCategory">

Error payload from the connector

Returns

void

emitGlobal()

protected emitGlobal<S>(subject, payload): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:430

Emit to a global subject with automatic payload enrichment.

Type Parameters

S

S extends SubjectDefinition

Parameters

subject

S

The subject to emit to

payload

Omit<ExtractSubjectPayload<S>, keyof AgentIdentity> & object

The payload (without AgentContext fields - they’re added automatically)

Returns

Promise<void>

emitSessionClosed()

protected emitSessionClosed(reason?): void

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:412

Emit agent session closed event. Emits only once per session. AIAdapter listens to cleanup agent and re-emit as AdapterSubjects.session.closed.

Parameters

reason?

string

Reason for session closure (e.g., ‘aborted’, ‘closed’)

Returns

void

emitStart()

protected emitStart(event?): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:378

Parameters

event?

Omit<{ adapterId: string; adapterName: string; adapterSessionId: string; agentId: string; clientId?: string; cwd: string | null; messageId?: string; model: string | null; occurredAt?: number; providerConfigId?: string; sessionId?: string; turnId?: string; }, "model" | "cwd" | "adapterName" | "adapterId" | "agentId" | "adapterSessionId">

Returns

Promise<void>

emitStepFinished()

protected emitStepFinished(stepType, content): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:517

Emit step.finished event with content and increment block index. Call this when a content block completes processing.

Parameters

stepType

"text" | "reasoning" | "tool_use"

The type of step that finished

content

{ content: string; type: "text"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "image"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "document"; } | { attachmentType: "file" | "directory"; displayName?: string; fileName: string; filePath: string; source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "attachment"; } | { content: string; metadata?: Record<string, unknown>; type: "reasoning"; } | { args: Record<string, unknown>; name: string; toolCallId: string; type: "tool_call"; } | { isError?: boolean; output: string; toolCallId: string; type: "tool_output"; }

The complete content of the step (text, reasoning, tool_call, or tool_output)

Type Literal

{ attachmentType: "file" | "directory"; displayName?: string; fileName: string; filePath: string; source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "attachment"; }

The complete content of the step (text, reasoning, tool_call, or tool_output)

attachmentType

"file" | "directory" = AttachmentTypeSchema

Whether the attachment is a file or directory

displayName?

string = ...

Optional human-readable display name override

fileName

string = ...

Original filename with extension (e.g. “api-spec.yaml”) — for display and type inference

filePath

string = ...

Server-side file path — always populated before message reaches adapters

source

{ data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; } = ContentSourceSchema

Inline content — base64 for binary, raw string for text

type

"attachment" = ...

Type Literal

{ content: string; metadata?: Record<string, unknown>; type: "reasoning"; }

The complete content of the step (text, reasoning, tool_call, or tool_output)

content

string = ...

metadata?

Record<string, unknown> = ...

Optional provider/runtime metadata for reasoning blocks.

type

"reasoning" = ...

Returns

Promise<void>

emitStepStarted()

protected emitStepStarted(stepType, blockData?, content?): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:503

Emit step.started event with automatic block index management. Call this when a content block begins processing.

Parameters

stepType

"text" | "reasoning" | "tool_use"

The type of step (text, reasoning, tool_use)

blockData?

{ toolCallId: string; toolName: string; type: "tool_use"; } | { type: "reasoning"; } | { type: "text"; }

Optional metadata for the block (e.g., toolName for tool_use)

content?

Optional content for the step (e.g., tool_call block for tool_use)

Type Literal

Optional content for the step (e.g., tool_call block for tool_use)

attachmentType

"file" | "directory" = AttachmentTypeSchema

Whether the attachment is a file or directory

displayName?

string = ...

Optional human-readable display name override

fileName

string = ...

Original filename with extension (e.g. “api-spec.yaml”) — for display and type inference

filePath

string = ...

Server-side file path — always populated before message reaches adapters

source

{ data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; } = ContentSourceSchema

Inline content — base64 for binary, raw string for text

type

"attachment" = ...

Type Literal

{ content: string; metadata?: Record<string, unknown>; type: "reasoning"; }

Optional content for the step (e.g., tool_call block for tool_use)

content

string = ...

metadata?

Record<string, unknown> = ...

Optional provider/runtime metadata for reasoning blocks.

type

"reasoning" = ...

Returns

Promise<void>

emitToolOutput()

protected emitToolOutput(output, hints): Promise<ToolOutputResolution>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:492

Emit tool.output event with automatic correlation resolution. Resolves the correlation ID from ToolCallTracker using provided hints. Use this instead of directly emitting to AgentSubjects.tool.output.

Parameters

output

string

Tool output content

hints

ResolveHints

Hints for correlation (nativeId and/or toolName)

Returns

Promise<ToolOutputResolution>

Resolved toolCallId, toolName (falls back to ‘unknown’), and args from the matched tool.use call

emitToolUse()

protected emitToolUse(toolName, args?, nativeId?): Promise<string>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:481

Emit tool.use event with automatic correlation tracking. Registers the tool call with ToolCallTracker and emits to global bus. Use this instead of directly emitting to AgentSubjects.tool.use.

Parameters

toolName

string

Name of the tool being invoked

args?

Record<string, unknown>

Tool arguments

nativeId?

string

Native provider ID if available (e.g., toolu_, call_)

Returns

Promise<string>

The correlation ID used (nativeId if provided, else generated UUID)

enrichPayload()

protected enrichPayload<T>(payload): Promise<T & Required<AgentIdentity> & object>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:421

Enrich a payload with agent context fields.

Type Parameters

T

T extends object

Parameters

payload

T

The base payload to enrich

Returns

Promise<T & Required<AgentIdentity> & object>

Payload with AgentContext fields and optional messageId added

getAdapterSessionId()

getAdapterSessionId(): Promise<string>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:918

Get session ID, waiting for provider to generate it if not yet available.

Delegates to the underlying connector’s getSessionId method.

Returns

Promise<string>

Session ID from provider

Throws

Error if connector is not initialized

getBlockIndex()

protected getBlockIndex(): number

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:525

Get the current block index (for adapters that need to track it externally).

Returns

number

Current block index within the turn

getContextWindowSize()

protected getContextWindowSize(modelName?): number | undefined

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:453

Get context window size for a model.

Looks up the context window size from availableModels based on model name.

Parameters

modelName?

string

Model name to look up (defaults to confirmedModel or initialModel)

Returns

number | undefined

Context window size in tokens, or undefined if not found

incrementBlockIndex()

protected incrementBlockIndex(): void

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:533

Increment block index (for adapters using SDK-provided indices). Call after emitting step.finished if managing index externally.

Returns

void

init()

init(): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:304

Initialize the agent.

Creates the connector via the abstract createConnector() method and sets up handlers for agent.* subjects with agentId filtering.

Returns

Promise<void>

Throws

Error if already initialized

initialize()

initialize(options?): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:865

Initialize the agent without sending a message (idle creation). Ensures init() is called, then delegates to connector.initialize().

Parameters

options?

AgentSendMessageOptions

Optional initialization options (system prompt, sessionContext)

Returns

Promise<void>

onBeforeEmitCompletion()

protected onBeforeEmitCompletion(): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:880

Returns

Promise<void>

onMessageHandle()

protected onMessageHandle(messageHandle): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:882

Parameters

messageHandle

MessageHandle

Returns

Promise<void>

sendMessage()

protected sendMessage(ctx): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:547

Handle agent.sendMessage request. The filter has already been applied at subscription time - this method only receives messages intended for this agent. Runs PreUserMessage hooks before delegating to the connector’s sendMessage method. Uses sessionContext signals to decide between native resume and fresh with history. HookAbortError propagates to caller (session layer handles lifecycle). Subclasses can override for custom handling.

Parameters

ctx

RequestContext<{ adapterId: string; agentId: string; deliveryMode?: "enqueue" | "immediate"; message: string | { blocks: { content: string; type: "text"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "image"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "document"; } | { attachmentType: "file" | "directory"; displayName?: string; fileName: string; filePath: string; source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "attachment"; } | { content: string; metadata?: Record<string, unknown>; type: "reasoning"; } | { args: Record<string, unknown>; name: string; toolCallId: string; type: "tool_call"; } | { isError?: boolean; output: string; toolCallId: string; type: "tool_output"; } | ({ content: string; type: "text"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: … | …; type: "url"; url: string; }; type: "image"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: … | …; type: "url"; url: string; }; type: "document"; } | { attachmentType: "file" | "directory"; displayName?: string; fileName: string; filePath: string; source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: … | …; type: "url"; url: string; }; type: "attachment"; } | { content: string; metadata?: Record<string, unknown>; type: "reasoning"; } | { args: Record<string, unknown>; name: string; toolCallId: string; type: "tool_call"; } | { isError?: boolean; output: string; toolCallId: string; type: "tool_output"; })[]; role?: "user" | "assistant" | "system"; }; messageId?: string; responseSchema?: Record<string, unknown>; sessionContext?: { extractedContext?: unknown; hasCompression?: boolean; hasConnectorSwap?: boolean; hasNewTransforms?: boolean; isFirstTurn?: boolean; messageHistory?: object[]; turnContext?: Record<string, unknown>; }; sessionId?: string; turnId?: string; }, { messageId: string; }>

Request context with payload and response methods

Returns

Promise<void>

shouldUseNativeResume()

protected shouldUseNativeResume(sessionContext?): boolean

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:809

Determine whether to use native session resume or fresh with history.

Native resume: SDK manages history, don’t inject messageHistory, preserve cache. Fresh with history: Create new session, inject messageHistory.

Override in adapter-specific agents if needed.

Parameters

sessionContext?

Context signals from SessionOrchestrator

extractedContext?

unknown = ...

Structured context from compression (if hasCompression=true).

hasCompression?

boolean = ...

Whether compression is active (extractedContext present). If true, Agent should use fresh mode with compressed context.

hasConnectorSwap?

boolean = ...

Whether a connector swap occurred before this message (e.g., cwd/model change). If true, native resume is infeasible and adapters should use fresh mode.

hasNewTransforms?

boolean = ...

Whether transforms have been applied since last turn. If true, Agent should use fresh mode (history changed).

isFirstTurn?

boolean = ...

Whether this is the first turn in the session. If true, no native history exists yet.

messageHistory?

object[] = ...

Curated message history assembled via getFullConversation(). Only used if Agent decides to inject (fresh mode).

turnContext?

Record<string, JsonValue> = ...

Turn-scoped context assembled by PreUserMessage hooks and the orchestrator. Keys are plugin-defined (e.g., ‘skillCatalog’, ‘skills’, ‘predictedTools’). Adapters consume this to prepend context blocks.

Constrained to JSON-safe types to ensure serialization succeeds.

ADAPTER CONTRACT: Every adapter MUST materialize turnContext into the LLM-facing message using serializeTurnContext().

Returns

boolean

true if native resume should be used

start()

start(message, options?): Promise<AgentStartResult>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:841

Start the agent with an initial message.

Ensures the agent is initialized (idempotent) before delegating to the connector. Runs PreUserMessage hooks before sending the message. Uses sessionContext signals to decide between native resume and fresh with history. HookAbortError propagates to caller.

Parameters

message

string | { blocks: { content: string; type: "text"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "image"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "document"; } | { attachmentType: "file" | "directory"; displayName?: string; fileName: string; filePath: string; source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "attachment"; } | { content: string; metadata?: Record<string, unknown>; type: "reasoning"; } | { args: Record<string, unknown>; name: string; toolCallId: string; type: "tool_call"; } | { isError?: boolean; output: string; toolCallId: string; type: "tool_output"; } | ({ content: string; type: "text"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "image"; } | { source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "document"; } | { attachmentType: "file" | "directory"; displayName?: string; fileName: string; filePath: string; source: { data: string; mimeType: string; type: "base64"; } | { mimeType?: string; type: "url"; url: string; }; type: "attachment"; } | { content: string; metadata?: Record<string, unknown>; type: "reasoning"; } | { args: Record<string, unknown>; name: string; toolCallId: string; type: "tool_call"; } | { isError?: boolean; output: string; toolCallId: string; type: "tool_output"; })[]; role?: "user" | "assistant" | "system"; } | NormalizedMessageInput

User message (normalized or unnormalized)

options?

AgentSendMessageOptions

Optional start options (e.g., delivery mode, sessionContext)

Returns

Promise<AgentStartResult>

Session ID, agent ID, and message handle for tracking

subscribeConnector()

protected subscribeConnector<Subject>(connector, subject, handler, options?): void

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:752

Subscribe to a connector subject and register its cleanup as connector wiring.

Use this in adapter wireEvents() implementations so connector swaps can remove old listeners before rewiring the new connector.

Type Parameters

Subject

Subject extends ScopedSubjectDefinition<TConnector extends AIAgentConnector<TBus, BaseAgentConnectorConfig<TBus, object>> ? TBus["namespace"] : never>

Parameters

connector

TConnector

Connector instance to subscribe on

subject

Subject

Subject definition to subscribe to

handler

HandlerForSubjectDefinition<Subject>

Subject handler

options?

OnOptions

Optional bus subscription options

Returns

void

supportsNativeResume()

protected supportsNativeResume(): boolean

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:826

Whether this adapter supports native session resume. Override in adapter-specific agents that can resume SDK sessions.

Returns

boolean

true if native resume is supported

swapConnector()

swapConnector(configOverrides?): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:603

Replace the current connector with a fresh one.

Uses create-before-close pattern with rollback for safety:

Create new connector first (old connector still alive)
Wire events to new connector (accumulate cleanups separately)
If successful: close old connector, assign new one
If failed: close new connector, restore old wiring, throw

This ensures the agent always has a working connector, even if factory or wiring fails.

Preserves runtime overrides across sequential swaps by using current connector values as baseline for non-overridden fields.

Parameters

configOverrides?

Partial<{ cwd: string; model: string; providerContext: { credentialEnvVars?: Record<string, string>; credentialRefs: Record<string, string & $brand<"CredentialRef">>; definitionId: string; endpointOverrides?: { anthropic?: string; openai?: string; }; providerConfigId: string; }; }>

Optional config overrides (e.g., new cwd, model)

Returns

Promise<void>

Throws

Error if connector is currently processing a turn

trackUsage()

protected trackUsage(normalized): Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:442

Track usage and emit to global bus. AIAdapter aggregates session totals from per-call usage events.

Parameters

normalized

NormalizedCallUsage

Normalized usage metrics from adapter-specific normalizer

Returns

Promise<void>

wireEvents()

abstract protected wireEvents(connector): void | Promise<void>

Defined in: ../../../adapters/core/src/agent/ai-agent.ts:740

Wire adapter-specific connector events. Called automatically during init() and connector swap. Subclasses implement this to set up their event mappings.

Parameters

connector

TConnector

Connector instance to wire

Returns

void | Promise<void>