Abstract Class: ProceduralAgentConnector<TBus, TConfig>

Makaio Framework

Makaio Framework / ai-adapters-core / ProceduralAgentConnector

Abstract Class: ProceduralAgentConnector<TBus, TConfig>

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

Abstract base class for procedural (non-event-driven) agent connectors.

Procedural adapters (OpenAI, Copilot, Gemini) share common patterns:

wireSessionEvents: subscribe to turn lifecycle events and update processing state
processUserMessages: initialize session, enqueue, transition to active, process queue
complete: poll processing state until idle/paused
start: delegate to sendMessage and return AgentStartResult
acceptsImmediate: delegate to session’s current turn

Subclasses must implement:

getSession() / ensureSession() for session access and lazy initialization
getSessionQueue() for the adapter’s UserMessageQueue instance
getTurnSubjects() for namespace-specific turn subjects
sendMessage(), abort(), close(), interrupt(), getAdapterSessionId()

Subclasses may override:

getWireSessionConfig() for custom turn_finished behavior (e.g., Copilot multi-turn)

Extends

AIAgentConnector<TBus, TConfig>

Type Parameters

TBus

TBus extends ScopedBus<string> = ScopedBus<string>

Scoped bus type for adapter namespace

TConfig

TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>

Configuration type extending BaseAgentConnectorConfig

Constructors

Constructor

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

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

Parameters

config

BaseAgentConnectorConfig<TBus, object> & object

Returns

ProceduralAgentConnector<TBus, TConfig>

Inherited from

AIAgentConnector.constructor

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.

Inherited from

AIAgentConnector.adapterId

adapterName

protected readonly adapterName: string

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

Adapter type name for event identification.

Inherited from

AIAgentConnector.adapterName

adapterSessionId?

optional adapterSessionId?: string

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

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

Inherited from

AIAgentConnector.adapterSessionId

agentId

protected readonly agentId: string

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

Unique identifier for this agent instance.

Inherited from

AIAgentConnector.agentId

config

protected readonly config: TConfig & object

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

Type Declaration

adapterId

adapterId: string

Inherited from

AIAgentConnector.config

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.

Inherited from

AIAgentConnector.currentReasoningEffort

cwd

cwd: string

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

Working directory for agent execution

Inherited from

AIAgentConnector.cwd

deferredInterrupt

protected deferredInterrupt: DeferredPromise<void> | undefined

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

Deferred promise for interrupt coordination.

Inherited from

AIAgentConnector.deferredInterrupt

env

protected readonly env: Record<string, string>

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

Inherited from

AIAgentConnector.env

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

Inherited from

AIAgentConnector.errorHandler

lastResult

protected lastResult: MessageResult | null = null

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

Inherited from

AIAgentConnector.lastResult

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)

Inherited from

AIAgentConnector.model

pendingMessageHandle?

protected optional pendingMessageHandle?: MessageHandle

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

Currently active message handle waiting for completion.

Inherited from

AIAgentConnector.pendingMessageHandle

providerConfigId?

optional providerConfigId?: string

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

ProviderConfig UUID used during agent creation, carried for runtime introspection

Inherited from

AIAgentConnector.providerConfigId

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.

Inherited from

AIAgentConnector.sessionId

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.

Inherited from

AIAgentConnector.supportedReasoningLevels

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.

Inherited from

AIAgentConnector.systemPrompt

timeouts

protected readonly timeouts: TrackedTimeoutConfig

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

Resolved timeout configuration with provenance tracking.

Inherited from

AIAgentConnector.timeouts

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

Inherited from

AIAgentConnector.currentTurnNumber

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

Inherited from

AIAgentConnector.pendingTurnNumber

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

Inherited from

AIAgentConnector.abort

acceptsImmediate()

protected acceptsImmediate(): boolean

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

Returns true if current turn can accept immediate messages.

Returns

boolean

True if turn can accept immediate, false otherwise

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

Inherited from

AIAgentConnector.captureSystemPrompt

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.

Inherited from

AIAgentConnector.changeCwdInPlace

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.

Inherited from

AIAgentConnector.changeModelInPlace

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

Inherited from

AIAgentConnector.changeReasoningInPlace

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>

Inherited from

AIAgentConnector.close

complete()

complete(): Promise<MessageResult | null>

Defined in: ../../../adapters/core/src/connector/procedural-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

Overrides

AIAgentConnector.complete

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

Inherited from

AIAgentConnector.consumeTurnNumber

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

Inherited from

AIAgentConnector.createMessageHandle

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

Inherited from

AIAgentConnector.emit

ensureSession()

abstract protected ensureSession(): Promise<ProceduralConnectorSession>

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

Initialize and return the adapter’s session. Must be idempotent (no-op if already initialized).

Returns

Promise<ProceduralConnectorSession>

The initialized session

getAdapterName()

getAdapterName(): string

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

Returns

string

Inherited from

AIAgentConnector.getAdapterName

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

Inherited from

AIAgentConnector.getAdapterSessionId

getAgentId()

getAgentId(): string

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

Returns

string

Inherited from

AIAgentConnector.getAgentId

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

Inherited from

AIAgentConnector.getProcessingState

getSession()

abstract protected getSession(): ProceduralConnectorSession | undefined

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

Get the adapter’s session instance (may be undefined if not yet initialized).

Returns

ProceduralConnectorSession | undefined

The session or undefined

getSessionQueue()

abstract protected getSessionQueue(): UserMessageQueue

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

Get the adapter’s UserMessageQueue instance.

Returns

UserMessageQueue

The message queue

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

Inherited from

AIAgentConnector.getTimeoutMs

getTurnSubjects()

abstract protected getTurnSubjects(): WireSessionSubjects<TBus["namespace"]>

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

Get the adapter’s namespace-specific turn subjects for wireSessionEvents.

Returns

WireSessionSubjects<TBus["namespace"]>

Turn subject definitions

getWireSessionConfig()

protected getWireSessionConfig(): WireSessionConfig | undefined

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

Get optional wire session configuration for custom turn_finished behavior. Override in subclasses that need non-standard turn_finished handling (e.g., Copilot multi-turn message completion).

Returns

WireSessionConfig | undefined

Wire session configuration, or undefined for default behavior

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

Inherited from

AIAgentConnector.handleError

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

Inherited from

AIAgentConnector.handlePause

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

Inherited from

AIAgentConnector.handleToolApprovalDenied

initialize()

initialize(options?): Promise<void>

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

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)

Returns

Promise<void>

Overrides

AIAgentConnector.initialize

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

Inherited from

AIAgentConnector.interrupt

logLowLevelEvent()

protected logLowLevelEvent(_event): void

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

Parameters

_event

unknown

Returns

void

Inherited from

AIAgentConnector.logLowLevelEvent

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

Inherited from

AIAgentConnector.markToolRefreshPending

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

Inherited from

AIAgentConnector.on

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

Inherited from

AIAgentConnector.once

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 }

Inherited from

AIAgentConnector.onceProcessingStateChanged

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

Inherited from

AIAgentConnector.onProcessingStateChanged

processUserMessages()

protected processUserMessages(messageHandles): Promise<Set<MessageHandle>>

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

Process queued user messages by delegating to Session.

Shared flow:

Initialize session if not yet created
Enqueue the message
Set adapterSessionId on handle
Transition to active if currently idle/paused
Process queue via session

Parameters

messageHandles

MessageHandle[]

Array of message handles to process

Returns

Promise<Set<MessageHandle>>

Set of message handles that were processed

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

Inherited from

AIAgentConnector.requestToolApproval

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.

Type Parameters

TSubject

TSubject extends ScopedSubjectDefinition<TBus["namespace"]>

Parameters

subject

TSubject

Scoped subject definition for the tool approval request

payload

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

Payload that must not include adapter metadata

Returns

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

Tool approval response payload

Inherited from

AIAgentConnector.requestToolApprovalWithHandling

sendMessage()

abstract sendMessage(message, options?): Promise<MessageHandle>

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

Send a message to the agent. For initial message, use start() instead.

Parameters

message

NormalizedMessageInput

Normalized message content

options?

ConnectorSendMessageOptions

Send options (e.g., delivery mode, message ID)

Returns

Promise<MessageHandle>

Message handle for tracking

Inherited from

AIAgentConnector.sendMessage

setCanonicalTurnNumber()

setCanonicalTurnNumber(turnNumber): void

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

Stage the canonical orchestrator-assigned turn number for consumption by the next consumeTurnNumber call. The counter is monotonically increasing.

Parameters

turnNumber

number

Canonical 1-based turn number from SessionOrchestrator

Returns

void

Throws

RangeError when the value is invalid, regresses, or downgrades a staged value

Inherited from

AIAgentConnector.setCanonicalTurnNumber

start()

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

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

Start session with initial message.

Parameters

message

NormalizedMessageInput

The initial message to send

options?

ConnectorSendMessageOptions

Optional send message options

Returns

Promise<AgentStartResult>

The agent start result with session ID and message handle

Overrides

AIAgentConnector.start

updateProcessingState()

protected updateProcessingState(state): Promise<void>

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

Update the agent’s processing state. State transitions trigger events via emittery.

Parameters

state

ProcessingState

New processing state

Returns

Promise<void>

Inherited from

AIAgentConnector.updateProcessingState

wireSessionEvents()

protected wireSessionEvents(): void

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

Wire Session turn events to Connector state updates.

Session emits typed events, Connector subscribes and updates processing state. This maintains separation of concerns - Session does not know about Connector state.

Default turn_finished behavior: transition through processing_finished to idle, or drain the queue if messages are pending. Override via getWireSessionConfig().

Returns

void