Class: Turn

Makaio Framework

---

Makaio Framework / services-core / Turn

Class: Turn

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:84

Represents a single turn in a session.

A turn is a semantic bracket: user message(s) → agent response(s). Turn encapsulates state and logic, while SessionOrchestrator handles bus events and emissions.

Design:

• Immutable identity (turnId, sessionId, agentIds set at creation)
• Mutable state (messages, completion tracking)
• State changes return results for orchestrator to act on
• No bus dependency (testable in isolation)

Example

const turn = new Turn({ sessionId: 'sess1', agentIds: ['agent1', 'agent2'] });
turn.addMessage('msg1');

const change = turn.markAgentCompleted('agent1');
// change.turnComplete === false (agent2 still pending)

const change2 = turn.markAgentCompleted('agent2');
// change2.turnComplete === true, change2.result.success === true

Constructors

Constructor

new Turn(config): Turn

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:112

Parameters

config

TurnConfig

Returns

Turn

Properties

sessionId

readonly sessionId: string

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:89

Session this turn belongs to

---

startedAt

readonly startedAt: number

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:95

Timestamp when turn was created

---

turnId

readonly turnId: string

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:86

Unique turn identifier

---

turnNumber

readonly turnNumber: number

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:92

Monotonic per-session ordinal (1-based).

Accessors

agentIds

Get Signature

get agentIds(): readonly string[]

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:132

Agents participating in this turn.

Returns

readonly string[]

Immutable array of agent IDs

---

completedAgents

Get Signature

get completedAgents(): ReadonlySet<string>

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:157

Agents that have completed successfully.

Returns

ReadonlySet<string>

Read-only set of completed agent IDs

---

erroredAgents

Get Signature

get erroredAgents(): ReadonlyMap<string, string>

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:165

Agents that errored.

Returns

ReadonlyMap<string, string>

Read-only map of agent ID to error message

---

initiator

Get Signature

get initiator(): object

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:141

Origin of this turn for loop prevention and audit. Returned as a defensive copy to avoid external mutation of internal state.

Returns

Defensive copy of turn initiator metadata

source

source: "user" | "extension" | "system"

Origin category

sourceId?

optional sourceId?: string

Identifier for the specific origin.

Examples: 'routine:validation', 'loop', 'subagent:xyz'.

---

messageIds

Get Signature

get messageIds(): readonly string[]

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:149

Messages sent during this turn.

Returns

readonly string[]

Immutable array of message IDs

Methods

addMessage()

addMessage(messageId): void

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:177

Add a message to this turn.

Parameters

messageId

string

The message ID to add

Returns

void

---

getContext()

getContext(): TurnContext

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:241

Get context for agent dispatch. Used when sending messages to agents for context propagation.

Returns

TurnContext

Turn context with turnId and current messageId

Throws

Error if no messages have been added yet

---

getContextForMessage()

getContextForMessage(messageId): TurnContext

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:256

Get context for a specific message (for events emitted per-message).

Parameters

messageId

string

The message ID to get context for

Returns

TurnContext

Turn context with turnId and the specified messageId

---

getResult()

getResult(): TurnResult

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:228

Get the turn result (only meaningful when turn is complete).

Returns

TurnResult

Turn result with success status and any errors

---

hasAgent()

hasAgent(agentId): boolean

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:211

Check if an agent is part of this turn.

Parameters

agentId

string

The agent ID to check

Returns

boolean

True if agent is participating in this turn

---

isComplete()

isComplete(): boolean

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:219

Check if the turn is complete (all agents finished).

Returns

boolean

True if all agents have completed or errored

---

markAgentCompleted()

markAgentCompleted(agentId): TurnStateChange

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:186

Mark an agent as completed successfully.

Parameters

agentId

string

The agent that completed

Returns

TurnStateChange

State change indicating if turn is now complete

---

markAgentErrored()

markAgentErrored(agentId, error): TurnStateChange

Defined in: ../../../packages/services/core/src/session/entities/turn.ts:197

Mark an agent as errored.

Parameters

agentId

string

The agent that errored

error

string

Error message

Returns

TurnStateChange

State change indicating if turn is now complete