Abstract Class: AIAgentConnector<TBus, TConfig>

Makaio Framework / ai-adapters-core / AIAgentConnector

Abstract Class: AIAgentConnector<TBus, TConfig>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:63

Abstract base class for AI agent implementations.

Each adapter provides its own message queue implementation (UserMessageQueue). This base class provides common infrastructure for state management, bus operations, and error handling.

Extended by

ProceduralAgentConnector

Type Parameters

TBus

TBus extends ScopedBus<string> = ScopedBus<string>

Scoped bus type for adapter namespace

TConfig

TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>

Constructors

Constructor

protected new AIAgentConnector<TBus, TConfig>(config): AIAgentConnector<TBus, TConfig>

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

Parameters

config

BaseAgentConnectorConfig<TBus, object> & object

Returns

AIAgentConnector<TBus, TConfig>

Properties

adapterId

readonly adapterId: string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:91

Adapter identifier shared across instances of the same adapter type.

adapterName

protected readonly adapterName: string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:115

Adapter type name for event identification.

adapterSessionId?

optional adapterSessionId?: string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:70

Session ID from the provider (set after connection/start).

agentId

protected readonly agentId: string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:68

Unique identifier for this agent instance.

config

protected readonly config: TConfig & object

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:95

Type Declaration

adapterId

adapterId: string

currentReasoningEffort

currentReasoningEffort: "none" | "low" | "medium" | "high" | "extra-high" | undefined

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:103

Current reasoning effort level, updated by changeReasoningInPlace.

cwd

cwd: string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:101

Working directory for agent execution

deferredInterrupt

protected deferredInterrupt: DeferredPromise<void> | undefined

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:82

Deferred promise for interrupt coordination.

env

protected readonly env: Record<string, string>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:109

errorHandler?

protected readonly optional errorHandler?: (error, terminate) => void

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:80

Optional error handler callback.

Parameters

error

Error

terminate

boolean

Returns

void

lastResult

protected lastResult: MessageResult | null = null

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:94

model

model: string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:97

Model used for this agent (subclasses may update when SDK confirms actual model)

pendingMessageHandle?

protected optional pendingMessageHandle?: MessageHandle

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:74

Currently active message handle waiting for completion.

providerConfigId?

optional providerConfigId?: string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:99

ProviderConfig UUID used during agent creation, carried for runtime introspection

sessionId?

protected readonly optional sessionId?: string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:72

Makaio session ID for cross-session correlation and approval routing.

supportedReasoningLevels

supportedReasoningLevels: { extra-high?: string | number; high?: string | number; low?: string | number; medium?: string | number; none?: string | number; } | undefined

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:108

Reasoning levels supported by the current model, forwarded from the config factory. undefined when the model does not declare reasoning support.

systemPrompt?

protected optional systemPrompt?: string | { content: string; mode: "append"; }

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

Runtime system prompt from start/initialize options.

timeouts

protected readonly timeouts: TrackedTimeoutConfig

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:93

Resolved timeout configuration with provenance tracking.

Accessors

currentTurnNumber

Get Signature

get protected currentTurnNumber(): number

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:344

Current turn number (read-only). Use consumeTurnNumber to advance.

Returns

number

The current turn number

pendingTurnNumber

Get Signature

get protected pendingTurnNumber(): number | undefined

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:352

Staged canonical turn number, or undefined if none was staged.

Returns

number | undefined

The pending canonical turn number

Methods

abort()

abstract abort(): void

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:246

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

Returns

void

captureSystemPrompt()

protected captureSystemPrompt(prompt): void

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:167

Store runtime system prompt for session creation. Subclasses may override to apply SDK-specific side effects (e.g., Gemini’s setSystemInstruction).

Parameters

prompt

string | { content: string; mode: "append"; } | undefined

System prompt from start/initialize options

Returns

void

changeCwdInPlace()

changeCwdInPlace(_newCwd): Promise<boolean>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:385

Attempt to change the working directory without a connector swap. Subclasses override when the adapter supports in-place cwd changes (e.g., stateless APIs). Base implementation returns false (swap required).

Mutation contract: Implementations MUST NOT mutate this.cwd directly. The caller (AIAgent.handleCwdChange) owns the this.cwd field update after a successful in-place change. Implementations only update SDK-internal state.

Parameters

_newCwd

string

The working directory path to switch to

Returns

Promise<boolean>

true if changed in-place, false if swap needed. Exceptions are caught by the caller and treated as false (automatic swap fallback), so implementations need not guard.

changeModelInPlace()

changeModelInPlace(_newModel): Promise<boolean>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:369

Attempt to change the model without a connector swap. Subclasses override when the SDK supports in-place model changes. Base implementation returns false (swap required).

Mutation contract: Implementations MUST NOT mutate this.model directly. The caller (AIAgent.handleModelChange) owns the this.model field update after a successful in-place change. Implementations only configure the SDK-internal model (e.g., query.setModel(), geminiConfig.setModel()).

Parameters

_newModel

string

The model identifier to switch to

Returns

Promise<boolean>

true if changed in-place, false if swap needed. Exceptions are caught by the caller and treated as false (automatic swap fallback), so implementations need not guard.

changeReasoningInPlace()

changeReasoningInPlace(_newLevel): Promise<boolean>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:402

Attempt to change reasoning effort without swapping the connector.

Override in subclasses that support in-place reasoning changes (e.g., adapters that pass reasoning parameters per-request rather than at session-creation time). The base implementation returns false so callers fall back to a connector swap.

Mutation contract: Implementations MUST NOT mutate this.currentReasoningEffort directly. The caller owns the currentReasoningEffort field update after a successful in-place change. Implementations only configure the SDK-internal reasoning parameter.

Parameters

_newLevel

"none" | "low" | "medium" | "high" | "extra-high"

The new reasoning effort level to apply

Returns

Promise<boolean>

true if the change was applied in-place, false if a connector swap is needed

close()

abstract close(): Promise<void>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:253

Gracefully close the agent session. Unlike abort(), this doesn’t trigger AbortController errors. Use this for normal shutdown; use abort() for emergency termination.

Returns

Promise<void>

complete()

abstract complete(): Promise<MessageResult | null>

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

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

Returns

Promise<MessageResult | null>

Last message result or null if no messages processed

consumeTurnNumber()

protected consumeTurnNumber(): number

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:330

Advance to the next turn number, consuming any pending canonical value. Orchestrator-staged values win; otherwise the local counter increments by one.

Returns

number

The current turn number after advancement

createMessageHandle()

protected createMessageHandle(message, options?): MessageHandle

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:279

Create a MessageHandle with standard initialization.

Centralizes the pattern used by all connectors:

Generate messageId (use provided or generate UUID)
Create MessageHandle instance
Set adapterSessionId
Call onMessageSent callback

Parameters

message

NormalizedMessageInput

Normalized user message

options?

MessageHandleOptions

Optional message options (id, delivery mode, history, and turn context)

Returns

MessageHandle

Initialized MessageHandle ready for enqueueing

emit()

protected emit<TSubject>(subject, payload): Promise<void>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:527

Emit an event via the scoped bus with auto-injected metadata.

Wraps scopedBus.emit() to automatically include connector identity (adapterName, agentId, adapterId, adapterSessionId) in the payload.

Type Parameters

TSubject

TSubject extends ScopedSubjectDefinition<TBus["namespace"]>

Parameters

subject

TSubject

Subject definition for the event

payload

Forbid<TSubject["$meta"]["payload"], ForbiddenKeys>

Event payload (metadata fields are forbidden and auto-injected)

Returns

Promise<void>

Promise that resolves when the event is emitted

getAdapterName()

getAdapterName(): string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:456

Returns

string

getAdapterSessionId()

abstract getAdapterSessionId(): Promise<string>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:259

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

Returns

Promise<string>

Session ID from provider

getAgentId()

getAgentId(): string

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:452

Returns

string

getProcessingState()

getProcessingState(): ProcessingState

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

Get the current processing state of the agent.

Returns

ProcessingState

The current processing state

getTimeoutMs()

getTimeoutMs(category): number

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:465

Get timeout value for a specific category.

Parameters

Returns

number

Timeout value in milliseconds

handleError()

handleError(error, terminate?): void

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:418

Internal

Marks pending message as failed, calls error handler, resolves completion promise.

Parameters

error

unknown

Error that occurred

terminate?

boolean = false

Whether to abort the agent after handling error

Returns

void

handlePause()

protected handlePause(_reason): void

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

Handle pause after rejection or error. Subclasses should clear pending messages as appropriate.

Parameters

_reason

"error" | "rejection"

Reason for pause (‘rejection’ | ‘error’); available for subclass overrides

Returns

void

handleToolApprovalDenied()

protected handleToolApprovalDenied(abort, details?): void

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:444

Parameters

abort

"handled" | "not_requested" | "not_supported"

details?

string

Returns

void

initialize()

abstract initialize(options?): Promise<void>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:219

Initialize the connector’s SDK session without sending a message. Must set adapterSessionId before returning. Called by createAgent for idle agent setup. Implementations MUST be idempotent (no-op if already initialized).

Parameters

options?

ConnectorSendMessageOptions

Optional start options (e.g., systemPrompt for Claude)

Returns

Promise<void>

interrupt()

abstract interrupt(): Promise<void>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:410

Interrupt the current message processing.

Returns

Promise<void>

Promise that resolves when interrupt is handled

logLowLevelEvent()

protected logLowLevelEvent(_event): void

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:572

Parameters

_event

unknown

Returns

void

markToolRefreshPending()

markToolRefreshPending(): void

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:302

Signal that MCP tools have changed and should be refreshed at the next turn boundary.

Called by the AIAgent layer when receiving MCP bus events (mcp.tools.updated, mcp.tools.enabled). Connectors that support direct-inject tool refresh (e.g., BaseStreamConnector) override this to set an internal pending-refresh flag. The default implementation is a no-op so connectors that do not manage MCP tools directly are unaffected.

Returns

void

on()

on<Subject>(subject, handler, options?): () => void

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:549

Subscribe to events on the filtered bus (pre-filtered by agentId).

Uses filteredBus which only delivers events matching this connector’s agentId.

Type Parameters

Subject

Subject extends ScopedSubjectDefinition<TBus["namespace"]>

Parameters

subject

Subject

Subject definition to subscribe to

handler

HandlerForSubjectDefinition<Subject>

Event handler receiving the event context

options?

OnOptions

Optional subscription options (e.g., priority)

Returns

Unsubscribe function

() => void

once()

once<Subject>(subject, options?): Promise<never>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:565

Wait for a single event on the filtered bus (pre-filtered by agentId).

Uses filteredBus which only delivers events matching this connector’s agentId.

Type Parameters

Subject

Subject extends ScopedSubjectDefinition<TBus["namespace"]>

Parameters

subject

Subject

Subject definition to wait for

options?

OnceOptions<ScopedSubjectDefinition<TBus["namespace"]>>

Optional options (e.g., predicate filter, timeout)

Returns

Promise<never>

Promise resolving to the event context

onceProcessingStateChanged()

onceProcessingStateChanged(predicate?): Promise<ProcessingState>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:206

Wait for a single processing state change matching an optional predicate.

Parameters

predicate?

(eventData) => boolean

Optional filter, e.g., (e) => !e.isProcessing for idle

Returns

Promise<ProcessingState>

Promise resolving to { isProcessing: boolean }

onProcessingStateChanged()

onProcessingStateChanged(handler): UnsubscribeFunction

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:195

Subscribe to processing state changes (idle ↔ processing transitions).

Parameters

handler

(payload) => void | Promise<void>

Called with { isProcessing: boolean } on each state change

Returns

UnsubscribeFunction

Unsubscribe function

requestToolApproval()

protected requestToolApproval<TSubject>(subject, payload): Promise<TSubject["$meta"]["payload"]["response"]>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:478

Request tool approval via the scoped bus with auto-injected metadata.

Wraps scopedBus.request() to automatically include connector identity (adapterName, agentId, adapterId, adapterSessionId) in the payload.

Type Parameters

TSubject

TSubject extends ScopedSubjectDefinition<TBus["namespace"]>

Parameters

subject

TSubject

Subject definition for the tool approval request

payload

Forbid<TSubject["$meta"]["payload"]["request"], ForbiddenKeys>

Request payload (metadata fields are forbidden and auto-injected)

Returns

Promise<TSubject["$meta"]["payload"]["response"]>

Promise resolving to the approval response

requestToolApprovalWithHandling()

protected requestToolApprovalWithHandling<TSubject>(subject, payload): Promise<TSubject["$meta"]["payload"]["response"]>

Defined in: ../../../adapters/core/src/connector/agent-connector.ts:502

Execute a tool approval request with the shared diagnostics wrapper.

Handles the common RequestError/NoHandlerError path by logging a helpful message via handleError and re-throwing so callers can decide whether to surface the failure or fall back to a denial.