Class: SessionTurnManager
Makaio Framework / services-core / SessionTurnManager
Class: SessionTurnManager
Section titled “Class: SessionTurnManager”Defined in: ../../../packages/services/core/src/session/session-turn-manager.ts:39
Composable turn lifecycle manager.
Owns all stateful turn tracking: active turns, usage accumulation,
completion guards, and buffered-usage-during-completion. Both the
framework SessionOrchestrator and host-provided orchestrators create their
own instance.
Storage calls use bus.requestOptional so the manager degrades
gracefully in ephemeral mode (no storage handlers registered). When
TurnStorageSubjects.create is unhandled, synthetic IDs are generated
locally. When TurnStorageSubjects.complete is unhandled, the turn is
still cleared from memory and session.turn.completed is emitted.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new SessionTurnManager(
bus):SessionTurnManager
Defined in: ../../../packages/services/core/src/session/session-turn-manager.ts:68
Parameters
Section titled “Parameters”Event bus used for storage RPCs and event emission
Returns
Section titled “Returns”SessionTurnManager
Methods
Section titled “Methods”completeTurn()
Section titled “completeTurn()”completeTurn(
turn,result):Promise<void>
Defined in: ../../../packages/services/core/src/session/session-turn-manager.ts:216
Complete a turn: persist via storage, emit session.turn.completed, clear state.
A concurrent-completion guard prevents duplicate writes when two agent completions race. The second call is a no-op.
Usage is snapshotted before the storage call. Any usage events that arrive
while persistence is in-flight are buffered and merged into a second
TurnStorageSubjects.complete call. State is cleared only after durable
persistence succeeds; if persistence fails, the state remains intact so
completion can be retried.
Parameters
Section titled “Parameters”The turn to complete
result
Section titled “result”Turn result (success status and error messages)
Returns
Section titled “Returns”Promise<void>
createTurn()
Section titled “createTurn()”createTurn(
sessionId,agentIds,initiator?,turnId?):Promise<Turn>
Defined in: ../../../packages/services/core/src/session/session-turn-manager.ts:86
Create a new turn, tracking it as active.
Calls TurnStorageSubjects.create via requestOptional. If no storage
handler is registered (ephemeral mode), generates a synthetic UUID turn ID
and a per-session incrementing turn number.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”string
Session the turn belongs to
agentIds
Section titled “agentIds”string[]
Agents participating in this turn
initiator?
Section titled “initiator?”Turn origin metadata (user, plugin, system)
source
Section titled “source”"user" | "extension" | "system" = ...
Origin category
sourceId?
Section titled “sourceId?”string = ...
Identifier for the specific origin.
Examples: 'routine:validation', 'loop', 'subagent:xyz'.
turnId?
Section titled “turnId?”string
Optional pre-assigned turn ID (passed through to storage)
Returns
Section titled “Returns”Promise<Turn>
The newly created and activated Turn entity
destroy()
Section titled “destroy()”destroy():
void
Defined in: ../../../packages/services/core/src/session/session-turn-manager.ts:325
Cancel all bus subscriptions and clear all in-memory state.
Call when the owning orchestrator is destroyed.
Returns
Section titled “Returns”void
findActiveTurnByTurnId()
Section titled “findActiveTurnByTurnId()”findActiveTurnByTurnId(
turnId):Turn|undefined
Defined in: ../../../packages/services/core/src/session/session-turn-manager.ts:307
Find an active turn by turn ID (scans all sessions).
Used to correlate agent.usage events that carry a turnId rather
than a sessionId.
Parameters
Section titled “Parameters”turnId
Section titled “turnId”string
Turn identifier from an agent event payload
Returns
Section titled “Returns”Turn | undefined
Matching active turn, or undefined if not found
getActiveTurn()
Section titled “getActiveTurn()”getActiveTurn(
sessionId):Turn|undefined
Defined in: ../../../packages/services/core/src/session/session-turn-manager.ts:283
Get the active turn for a session, if any.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”string
Session identifier
Returns
Section titled “Returns”Turn | undefined
Active turn, or undefined if no turn is in progress
getActiveTurnsMap()
Section titled “getActiveTurnsMap()”getActiveTurnsMap():
Map<string,Turn>
Defined in: ../../../packages/services/core/src/session/session-turn-manager.ts:295
Expose the active turns map for handlers that need direct access.
Used by registerAttachHandler which tracks turns started via
session.agent.attach (with an initialMessage) in the shared map so
that the completion handler can detect when the attached turn finishes.
Returns
Section titled “Returns”Map<string, Turn>
Reference to the internal active turns map
registerCompletionHandlers()
Section titled “registerCompletionHandlers()”registerCompletionHandlers(
onTurnComplete):void
Defined in: ../../../packages/services/core/src/session/session-turn-manager.ts:137
Register bus listeners for agent.usage and agent.complete events.
Must be called once during initialisation. The onTurnComplete callback
is invoked when all agents in a turn have finished (success or error);
typically the orchestrator passes its own completeTurn method.
Parameters
Section titled “Parameters”onTurnComplete
Section titled “onTurnComplete”Callback invoked when all agents in a turn finish
Returns
Section titled “Returns”void