Class: TurnTracker<TRecord>

Makaio Framework

---

Makaio Framework / ai-adapters-core / TurnTracker

Class: TurnTracker<TRecord>

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:185

State machine for tracking turn boundaries during log import.

Purpose

Some external tools (like Claude Code) don’t emit explicit turn start/end events. This tracker synthesizes these events based on adapter-specific detection logic.

State Transitions

idle --[turn start detected]--> active (emit turn.started)
active --[turn complete detected]--> idle (emit turn.completed)

Multi-Session Support

The tracker maintains independent state per session ID, enabling concurrent processing of multiple sessions from the same log file.

Remarks

• Thread-safe for single-threaded async processing (no mutex needed)
• Stateless between sessions (each session tracked independently)
• Idempotent: processing the same record twice produces consistent results

Example

// Create tracker for Claude Code logs
const tracker = new TurnTracker({
  detectTurnStart: (record) => record.type === 'user',
  detectTurnComplete: (record) =>
    record.type === 'assistant' &&
    record.message?.content?.some((b) => b.type === 'text'),
  getSessionId: (record) => record.sessionId,
});

// Process records
for (const record of records) {
  const turnEvents = tracker.processRecord(record);
  for (const event of turnEvents) {
    // Emit turn.started or turn.completed events
    console.log(event.type, event.turnId);
  }
}

See

• TurnTrackerOptions - Configuration options
• TurnEvent - Emitted turn events

Type Parameters

TRecord

TRecord

The adapter’s native log record type

Constructors

Constructor

new TurnTracker<TRecord>(options): TurnTracker<TRecord>

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:194

Create a new turn tracker.

Parameters

options

TurnTrackerOptions<TRecord>

Tracker configuration with detection functions

Returns

TurnTracker<TRecord>

Methods

forceCompleteTurn()

forceCompleteTurn(sessionId): TurnEvent | undefined

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:357

Manually complete the current turn for a session.

Parameters

sessionId

string

Session identifier

Returns

TurnEvent | undefined

Turn completed event or undefined if no active turn

Remarks

Use this for cleanup when processing ends mid-turn (e.g., end of file with an incomplete conversation). Does nothing if no active turn.

---

getCurrentTurnId()

getCurrentTurnId(sessionId): string | undefined

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:271

Get the current turn ID for a session.

Parameters

sessionId

string

Session identifier

Returns

string | undefined

Current turn ID or undefined if no active turn

---

getState()

getState(sessionId): TurnState

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:262

Get the current turn state for a session.

Parameters

sessionId

string

Session identifier

Returns

TurnState

Current turn state (‘idle’ if session not tracked)

---

getTrackedSessions()

getTrackedSessions(): string[]

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:345

Get all currently tracked session IDs.

Returns

string[]

Array of session IDs being tracked

---

hasActiveTurn()

hasActiveTurn(sessionId): boolean

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:280

Check if a session has an active turn.

Parameters

sessionId

string

Session identifier

Returns

boolean

True if the session has an active (non-idle) turn

---

processRecord()

processRecord(record): TurnEvent[]

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:215

Process a log record and return any turn events that should be emitted.

Parameters

record

TRecord

Log record to process

Returns

TurnEvent[]

Array of turn events (may be empty, one, or two if turn completes and new one starts)

Remarks

Transition Rules

1. idle + turn start detected emits turn.started, transitions to active
2. active + turn complete detected emits turn.completed, transitions to idle
3. active + turn start detected emits turn.completed for previous turn, then emits turn.started for new turn (implicit completion)
4. idle + turn complete detected is a no-op (no active turn to complete)

Rule 3 handles cases where a user sends another message before the assistant finishes responding (rare but possible in log replays).

---

resetAll()

resetAll(): void

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:300

Reset all tracked session state.

Returns

void

Remarks

Use this for cleanup or when starting fresh.

---

resetSession()

resetSession(sessionId): boolean

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:291

Reset state for a specific session.

Parameters

sessionId

string

Session identifier

Returns

boolean

True if the session was tracked and removed

Remarks

Use this when a session is known to be complete or when re-processing.

---

restore()

restore(serialized): void

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:331

Restore tracker state from a serialized form.

Parameters

serialized

TurnTrackerSerializedState

State object from serialize

Returns

void

Remarks

Clears all current state before restoring. Use this to resume processing after a restart or between chunks.

See

serialize - Create serialized state

---

serialize()

serialize(): TurnTrackerSerializedState

Defined in: ../../../adapters/core/src/log-importer/turn-tracker.ts:312

Serialize the tracker state for persistence.

Returns

TurnTrackerSerializedState

JSON-serializable state object

Remarks

Use this to save state between chunks or before process shutdown for incremental log imports.

See

restore - Restore state from serialized form