Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import type { ModelSelectionWriteOutcome } from '../../db/worker/protocol'
import { parseSessionKey } from '../../session/types'
import { projectGfsApproval } from '../../visualInput/suspension'
import { ConversationError, ConversationErrorCode } from '../errors'
import { SESSION_SCOPED_APPROVAL_TOOLS } from '../extensions/approvalController'
import { isMcpToolName } from '../extensions/mcpApprovalGateController'
import {
ChatMessage,
ContextBreakdown,
Conversation,
ConversationState,
PendingApproval,
TraceContextV1,
Turn,
TurnToolCall,
} from '../types'
import type { SessionTokenUsage } from './conversationStore'
import {
ConversationSessionSummary,
ConversationStore,
GetOrCreateOptions,
InMemoryConversationStore,
SessionListQuery,
SessionMessagesQuery,
} from './conversationStore'
import { userIdFromRpcPrefix } from './sessionKeyParts'
/**
* Manages conversation state and turn tracking.
*
* State transitions:
* Idle → Processing (start_turn)
* Processing → Idle (complete/fail)
* Processing → AwaitingApproval (tool needs approval)
* AwaitingApproval → Processing (approve)
* AwaitingApproval → Idle (deny)
*
* The store is injected. The default is `InMemoryConversationStore` so unit
* tests and dev mode keep their previous behavior; production wires the
* SQLite-backed store in `main.ts`. State-mutating methods call the matching
* `persist*` hook on the store; for in-memory stores those are no-ops.
*
* IronClaw-critical methods (`suspendForApproval`, `approve`, `deny`,
* `clearPendingApproval`) are async because the SQLite store uses sync
* write-through (the durable state must land before the user-facing
* notification fires). Other lifecycle methods stay sync — the store
* absorbs them into its `enqueueAsync` queue, preserving per-sessionKey
* ordering without blocking the caller.
*/
export class ConversationManager {
private store: ConversationStore
/**
* Load-or-create in flight per session key. Concurrent callers on a new
* chat share one creation; two would insert two rows with the same
* `session_key`, and the second insert fails on its unique index.
*/
private readonly pendingCreates = new Map<string, Promise<Conversation>>()
constructor(store: ConversationStore = new InMemoryConversationStore()) {
this.store = store
}
/**
* Expose the underlying store so wiring code (cold-start loader,
* onEvict hook, shutdown drain) can reach into it without crossing
* ConversationManager.
*/
getStore(): ConversationStore {
return this.store
}
/**
* Swap the underlying store. Used by `main.ts` to inject the SQLite store
* after the worker thread is ready. Safe to call before any conversation
* has been touched; calling after sessions live in the old store would
* orphan them.
*/
setStore(store: ConversationStore): void {
this.store = store
}
/**
* Get or create a conversation for a session key.
*
* **Now async** (T2.1): on a cache miss we consult the durable store
* (`getOrLoad`) before creating a brand-new conversation. Production
* callsites already live in async paths (taskExecutor.run,
* RPC handlers); tests must `await`.
*/
async getOrCreate(sessionKey: string, opts?: GetOrCreateOptions): Promise<Conversation> {
const cached = this.store.get(sessionKey)
if (cached) {
this.assertSessionOwner(cached, opts?.userId)
return cached
}
let pending = this.pendingCreates.get(sessionKey)
if (!pending) {
pending = this.loadOrCreate(sessionKey, opts).finally(() => {
this.pendingCreates.delete(sessionKey)
})
this.pendingCreates.set(sessionKey, pending)
}
const conv = await pending
this.assertSessionOwner(conv, opts?.userId)
return conv
}
private async loadOrCreate(sessionKey: string, opts?: GetOrCreateOptions): Promise<Conversation> {
const loaded = await this.store.getOrLoad(sessionKey)
if (loaded) return loaded
const parsed = parseSessionKey(sessionKey)
const conv: Conversation = {
id: `conv-${sessionKey}-${Date.now()}`,
session_key: sessionKey,
user_id: opts?.userId ?? parsed?.userId ?? sessionKey,
state: ConversationState.Idle,
turns: [],
auto_approved_tools: new Set(),
created_at: new Date(),
updated_at: new Date(),
// #654 — a freshly inserted row carries the column default, so the RAM
// base revision matches disk from the first write onward. Without it the
// projection would omit the revision and the first selection of a new chat
// would fall back to the legacy unconditional (no-CAS) write.
modelSelectionRevision: 0,
}
this.store.set(sessionKey, conv)
await Promise.resolve(this.store.persistSessionCreate(conv, opts ?? {}))
return conv
}
/**
* List conversations whose session key begins with the given prefix.
* Used by the sessions read endpoints; filter logic lives here so routes
* don't reach into the underlying store directly.
*
* The prefix must include the trailing ":" that separates the userId+channelType
* segments from the agent. E.g. "<userId>:rpc:" — the method extracts agent
* and chatId from the single remaining ":" after the prefix.
*/
listSessionsForUser(keyPrefix: string): Array<{
key: string
conversation: Conversation
agent: string
chatId: string
}> {
const userId = userIdFromRpcPrefix(keyPrefix)
if (!userId) return []
const out = [] as Array<{
key: string
conversation: Conversation
agent: string
chatId: string
}>
for (const { key, conversation } of this.store.listByPrefix(keyPrefix)) {
if (conversation.user_id !== userId) continue
const rest = key.slice(keyPrefix.length)
const colonIdx = rest.indexOf(':')
if (colonIdx < 0) continue
const agent = rest.slice(0, colonIdx)
const chatId = rest.slice(colonIdx + 1)
out.push({ key, conversation, agent, chatId })
}
return out
}
/**
* Async variant of `listSessionsForUser` that warms the cache with any
* matching durable rows before returning the in-memory view. Used by
* the RPC `sessions` listing endpoint after the SQLite store ships.
*/
async listSessionsForUserAsync(keyPrefix: string): Promise<
Array<{
key: string
conversation: Conversation
agent: string
chatId: string
}>
> {
await this.store.prefetchUserSessions(keyPrefix)
return this.listSessionsForUser(keyPrefix)
}
/**
* Summary-only listing for `/v1/runtime/sessions`. Durable stores implement
* this without loading transcript rows; full turn hydration stays on
* `getSessionByKeyAsync` and the messages endpoint.
*/
async listSessionSummariesForUserAsync(
keyPrefix: string,
query: SessionListQuery = {}
): Promise<ConversationSessionSummary[]> {
return this.store.listSessionSummariesByPrefix(keyPrefix, query)
}
/**
* Summary-preserving, bounded transcript window for `/messages`.
* Durable stores can fetch only the requested turns instead of hydrating
* the whole persisted conversation before slicing.
*/
async getSessionMessagesByKeyAsync(
key: string,
keyPrefix: string,
query: SessionMessagesQuery = {}
) {
return this.store.getSessionMessagesByKey(key, keyPrefix, query)
}
/**
* Look up a single conversation by its exact session key.
* Used by the transcript endpoint: the full key can be reconstructed from
* auth.sub + agent + chatId, so iterating the whole map is wasteful.
* Returns undefined when no conversation exists for that key (cache miss).
*/
getSessionByKey(key: string): Conversation | undefined {
return this.store.get(key)
}
/**
* Async variant of `getSessionByKey` that consults the durable store on
* cache miss. Used by RPC handlers that need to surface historical
* conversations after they've fallen out of the RAM cache.
*/
async getSessionByKeyAsync(key: string): Promise<Conversation | undefined> {
return this.store.getOrLoad(key)
}
/** Authenticated exact-key lookup that treats persisted ownership as authoritative. */
async getSessionByKeyForUserAsync(
key: string,
userId: string
): Promise<Conversation | undefined> {
const conversation = await this.store.getOrLoad(key)
return conversation?.user_id === userId ? conversation : undefined
}
private assertSessionOwner(conversation: Conversation, expectedUserId?: string): void {
if (expectedUserId !== undefined && conversation.user_id !== expectedUserId) {
throw new ConversationError('Session access denied', ConversationErrorCode.OwnershipMismatch)
}
}
/**
* Start a new turn in the conversation.
* Transitions: Idle → Processing
*
* **D3 durability barrier**: awaits the store's `persistTurnStart` — under
* the SQLite store the user message + state flip commit as ONE transaction
* before the turn proceeds (retry semantics replay from the last persisted
* user message). On a rejected write the in-RAM mutation is rolled back
* (same rationale as `suspendForApproval`) and the error propagates so the
* caller fails the task loudly.
*/
async startTurn(
conversation: Conversation,
userInput: string,
taskId: string,
traceContext: TraceContextV1 | null = null,
/**
* Server-authoritative auto-title (spec 15), already redacted + truncated by
* the caller (TaskExecutor, which owns the secret list). Only supplied on
* turn 1. Applied with `??=` so it never clobbers a title already set (a
* future rename); `persistTurnStart` gates the durable COALESCE write on the
* durable `turnNumber === 1`, so an out-of-turn value is harmless.
*/
autoTitle?: string
): Promise<Turn> {
if (conversation.state !== ConversationState.Idle) {
throw new ConversationError(
`Cannot start turn: conversation is ${conversation.state}`,
ConversationErrorCode.InvalidTransition
)
}
const previousTraceContext = conversation.traceContext
const previousTitle = conversation.title
conversation.state = ConversationState.Processing
// D.1 — record the in-flight task so it can be exposed via /sessions and
// mirrored to sessions.active_task_id by persistTurnStart.
conversation.activeTaskId = taskId
conversation.traceContext = traceContext
conversation.updated_at = new Date()
// Clear per-turn wildcard approval — each new message requires fresh approval
conversation.auto_approved_tools.delete('*')
// A new user message starts a new task: plain session-scoped approvals end here.
conversation.task_approved_tools?.clear()
// Materialize the auto-title (spec 15) in RAM before persisting so the
// dual-store projection and the durable COALESCE write agree. `??=` keeps
// any title already set.
if (autoTitle !== undefined) conversation.title ??= autoTitle
const turn: Turn = {
number: conversation.turns.length + 1,
user_input: userInput,
tool_calls: [],
started_at: new Date(),
}
conversation.turns.push(turn)
try {
await Promise.resolve(this.store.persistTurnStart(conversation, userInput))
} catch (err) {
// Roll back the in-RAM mutation so the cached conversation is not left
// poisoned in Processing — the next startTurn would otherwise throw
// InvalidTransition forever. The ordinal consumed by the failed write
// stays consumed (holes are legal; UNIQUE collisions are not).
conversation.turns.pop()
conversation.state = ConversationState.Idle
conversation.activeTaskId = undefined
conversation.traceContext = previousTraceContext
// Roll back the auto-title too, so a failed turn-1 write leaves no RAM
// title that SQLite never persisted (would break dual-store parity).
conversation.title = previousTitle
conversation.updated_at = new Date()
throw err
}
return turn
}
/**
* Complete the current turn with a response.
* Transitions: Processing → Idle
*
* **D3 durability barrier**: awaits the store's `persistTurnComplete` —
* under the SQLite store the assistant message + state flip +
* `active_task_id` clear commit as ONE transaction. Callers MUST await this
* BEFORE ACKing the client (`responseCallback`) so an acknowledged turn is
* always durable. A rejected write propagates — never swallowed — and the
* caller fails the turn (see TaskExecutor.handleLoopResult).
*/
async completeTurn(conversation: Conversation, response: string): Promise<void> {
if (conversation.state !== ConversationState.Processing) {
throw new ConversationError(
`Cannot complete turn: conversation is ${conversation.state}`,
ConversationErrorCode.InvalidTransition
)
}
const currentTurn = conversation.turns[conversation.turns.length - 1]
if (currentTurn) {
currentTurn.response = response
currentTurn.completed_at = new Date()
}
conversation.state = ConversationState.Idle
conversation.pending_approval = undefined
conversation.activeTaskId = undefined // D.1 — turn done, no task in flight
conversation.traceContext = null
conversation.updated_at = new Date()
await Promise.resolve(this.store.persistTurnComplete(conversation, response))
}
/**
* Accumulate the token usage of one LLM call into this session's lifetime
* totals. Mirrors the numbers onto the in-RAM `Conversation` (so the hot
* `/sessions` and `/messages` paths serve a live count) AND enqueues the
* durable SQLite update (so cold-loaded sessions converge). Both start from
* the same `usage`, so they stay consistent; the durable write is
* fire-and-forget (`enqueueAsync`), lagging RAM by microseconds — irrelevant
* for a display counter.
*
* `cacheTokensReported` is OR-accumulated: a single call that reported cache
* info (defined `cache_*`) flips it true for the session, which is what the
* desktop uses to decide whether to show the cache breakdown.
*/
recordSessionUsage(conversation: Conversation, usage: SessionTokenUsage): void {
// Defensive: a malformed/buggy provider response must not poison the
// counter. A negative value would decrement the running total and a
// NaN/non-finite would corrupt it (and could bind NaN into the NOT NULL
// SQLite column). Coerce each figure to a non-negative integer; preserve
// `undefined` for cache fields (the "provider doesn't report cache" signal).
const clamp = (n: number | undefined): number | undefined =>
n === undefined ? undefined : Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0
const safe: SessionTokenUsage = {
input_tokens: clamp(usage.input_tokens) ?? 0,
output_tokens: clamp(usage.output_tokens) ?? 0,
cache_read_tokens: clamp(usage.cache_read_tokens),
cache_write_tokens: clamp(usage.cache_write_tokens),
}
conversation.input_tokens = (conversation.input_tokens ?? 0) + safe.input_tokens
conversation.output_tokens = (conversation.output_tokens ?? 0) + safe.output_tokens
conversation.cache_read_tokens =
(conversation.cache_read_tokens ?? 0) + (safe.cache_read_tokens ?? 0)
conversation.cache_write_tokens =
(conversation.cache_write_tokens ?? 0) + (safe.cache_write_tokens ?? 0)
// The flag reflects whether the provider REPORTED cache info (defined field),
// independent of the value — Anthropic with a defined 0 still flips it true.
if (safe.cache_read_tokens !== undefined || safe.cache_write_tokens !== undefined) {
conversation.cacheTokensReported = true
}
// Per-turn attribution: add to the in-flight turn ONLY while a user turn is
// being served (Processing). This counts in-loop compaction toward the turn
// (it's spent serving it) while excluding operator /compact, which runs with
// no in-flight turn (it still counts at the session level above). The turn's
// total is persisted onto its final assistant message by persistTurnComplete.
if (conversation.state === ConversationState.Processing && conversation.turns.length > 0) {
const turn = conversation.turns[conversation.turns.length - 1]
turn.input_tokens = (turn.input_tokens ?? 0) + safe.input_tokens
turn.output_tokens = (turn.output_tokens ?? 0) + safe.output_tokens
// Preserve "unreported" (undefined) faithfully: only accumulate cache when
// the provider reported it (Anthropic's defined 0 still counts). A provider
// that omits cache (OpenAI/zai/bailian) leaves the turn's cache undefined,
// mirroring the session-level treatment.
if (safe.cache_read_tokens !== undefined) {
turn.cache_read_tokens = (turn.cache_read_tokens ?? 0) + safe.cache_read_tokens
}
if (safe.cache_write_tokens !== undefined) {
turn.cache_write_tokens = (turn.cache_write_tokens ?? 0) + safe.cache_write_tokens
}
}
// NOTE: intentionally does NOT bump `updated_at` — token accounting is not
// user activity. The turn lifecycle (start/complete/cancel) owns that, so an
// operator-triggered /compact does not advance `lastActivityAt`.
void this.store.persistSessionUsage?.(conversation, safe)
}
/**
* Record the send-time context-window breakdown snapshot for this session.
*
* Captured by `DefaultReasoningPort.buildMessages` from the raw per-bucket
* `countSync` counts (local, cheap). The `totalInputTokens` left here is
* PROVISIONAL (= Σbuckets); the usage sink (`onUsageRecorded`, runs in the
* same call's `recordUsage`) overwrites it with the provider's authoritative
* `input_tokens` so the displayed total matches the `N/M` exactly (#8).
*
* RAM-only by design (decision LOCKED #4): the snapshot is ephemeral and
* recomputed every turn, so it is NOT persisted to SQLite. A cold-load has
* no "current prompt" until the next turn (null is acceptable).
*/
recordContextBreakdown(
conversation: Conversation,
raw: { buckets: ContextBreakdown['buckets']; maxTokens: number }
): void {
const sum = Object.values(raw.buckets).reduce((a, b) => a + b, 0)
conversation.contextBreakdown = {
buckets: raw.buckets,
totalInputTokens: sum, // provisional; the usage sink finalizes it (#8)
maxTokens: raw.maxTokens,
capturedAtTurn: conversation.turns?.length ?? 0,
}
// NOTE: intentionally does NOT bump `updated_at` — the breakdown is token
// accounting recomputed every turn, not user activity (same invariant as
// `recordSessionUsage`). The turn lifecycle owns `updated_at`.
}
/**
* Fail the current turn.
* Transitions: Processing → Idle
*
* Awaited durability barrier (parity with completeTurn): the failure ACK
* sent after this resolves must describe a state that is already durable —
* under the SQLite store the state flip + `active_task_id` clear commit as
* one awaited worker op. A rejected write propagates — never swallowed.
*/
async failTurn(conversation: Conversation): Promise<void> {
conversation.state = ConversationState.Idle
conversation.pending_approval = undefined
conversation.activeTaskId = undefined // D.1 — turn done, no task in flight
conversation.traceContext = null
conversation.updated_at = new Date()
const currentTurn = conversation.turns[conversation.turns.length - 1]
if (currentTurn) {
currentTurn.completed_at = new Date()
}
await Promise.resolve(this.store.persistTurnFail(conversation))
}
/**
* Mark the current turn as cancelled by the user.
*
* Unlike failTurn, this sets a synthetic assistant response on the turn
* so that buildMessageHistory emits a clean user↔assistant alternation —
* preventing the cancelled user_input from leaking into the next LLM call
* (see BUG-9).
*
* Distinct from deny (which is a user decision on a specific tool and
* appends explicit denial messages to history). Cancel ≠ deny per
* spec §5.3.
*
* Transitions: Processing | AwaitingApproval → Idle
*/
cancelTurn(conversation: Conversation): void {
conversation.state = ConversationState.Idle
conversation.pending_approval = undefined
conversation.activeTaskId = undefined // D.1 — turn done, no task in flight
conversation.traceContext = null
conversation.updated_at = new Date()
const currentTurn = conversation.turns[conversation.turns.length - 1]
if (currentTurn) {
currentTurn.response = '[Task cancelled by user before completion]'
currentTurn.completed_at = new Date()
}
void this.store.persistTurnCancel(conversation)
}
/**
* Session-key variant of cancelTurn, used by the AgentStateMachine cancel
* subscriber which only holds sessionKey (not Conversation).
* No-op for unknown session keys.
*
* Stays sync: the cancel subscriber is invoked synchronously by the
* lifecycle EventEmitter and must not introduce async hops (see I11).
*/
cancelTurnBySessionKey(sessionKey: string): void {
const conv = this.store.get(sessionKey)
if (!conv) return
this.cancelTurn(conv)
}
/**
* Suspend for approval.
* Transitions: Processing → AwaitingApproval
*
* **IronClaw write-through (T2.1)**: the durable pending_approval row
* MUST land before the channel notification fires. The store handles
* that via `enqueueSync`; this method awaits the ACK before returning.
*/
async suspendForApproval(conversation: Conversation, approval: PendingApproval): Promise<void> {
const renewing =
conversation.state === ConversationState.AwaitingApproval &&
conversation.pending_approval?.legacy_budget === true &&
approval.replaces_request_id === conversation.pending_approval.request_id
if (conversation.state !== ConversationState.Processing && !renewing) {
throw new ConversationError(
`Cannot suspend: conversation is ${conversation.state}`,
ConversationErrorCode.InvalidTransition
)
}
const prevState = conversation.state
const prevApproval = conversation.pending_approval
const prevApprovalTraceContext = approval.traceContext
approval.traceContext = conversation.traceContext ?? null
const projected = projectGfsApproval(approval)
conversation.state = ConversationState.AwaitingApproval
conversation.pending_approval = projected
conversation.updated_at = new Date()
try {
await this.store.persistSuspend(conversation, projected)
} catch (err) {
// Under the sqlite/dual store the durable write can reject (worker
// timeout, SQLITE_BUSY, worker exit). Roll back the in-RAM mutation so
// the cached conversation is not left poisoned in AwaitingApproval — the
// next `startTurn` would otherwise throw InvalidTransition. The caller
// (TaskExecutor.handleLoopResult) surfaces the failure as a failed turn.
conversation.state = prevState
conversation.pending_approval = prevApproval
approval.traceContext = prevApprovalTraceContext
conversation.updated_at = new Date()
throw err
}
}
/**
* Resume after approval.
* Transitions: AwaitingApproval → Processing
*
* Proven turn-wide consent keeps the legacy expansion: all tools in this turn,
* plus the MCP server prefix for future turns. Exact-call and legacy unknown
* scopes authorize only the frozen invocation being resumed.
*
* SESSION_SCOPED_APPROVAL_TOOLS are the exception: turn-wide consent for one
* of them stores only that tool name, never '*' — in `task_approved_tools`
* for the current task, or in `auto_approved_tools` with alwaysApprove.
*
* When alwaysApprove=true, also stores the individual tool name (backwards compat).
*
* **IronClaw write-through**: awaits durable approval-state mutation.
*/
async approve(conversation: Conversation, alwaysApprove: boolean): Promise<void> {
if (conversation.state !== ConversationState.AwaitingApproval) {
throw new ConversationError(
`Cannot approve: conversation is ${conversation.state}`,
ConversationErrorCode.InvalidTransition
)
}
const requestId = conversation.pending_approval?.request_id
if (conversation.pending_approval) {
const toolName = conversation.pending_approval.tool_name
const turnWide = conversation.pending_approval.authorization_scope === 'turn_tools'
if (turnWide && SESSION_SCOPED_APPROVAL_TOOLS.has(toolName)) {
// Session-scoped consent covers this tool alone and neither grants nor
// revokes '*'. A plain approval lasts for the current task; "always"
// lasts for later tasks while the conversation is in memory.
if (alwaysApprove) conversation.auto_approved_tools.add(toolName)
else (conversation.task_approved_tools ??= new Set()).add(toolName)
} else {
// Only proven turn-wide consent expands. Exact-call and legacy unknown
// scopes authorize just the frozen invocation being resumed.
if (turnWide) conversation.auto_approved_tools.add('*')
else conversation.auto_approved_tools.delete('*')
// MCP tools: also auto-approve the entire server for future turns
if (turnWide && isMcpToolName(toolName)) {
const serverPrefix = toolName.split('__')[0]
conversation.auto_approved_tools.add(serverPrefix)
}
// alwaysApprove also stores the individual tool name (for future turns)
if (turnWide && alwaysApprove) {
conversation.auto_approved_tools.add(toolName)
}
}
}
conversation.state = ConversationState.Processing
conversation.updated_at = new Date()
if (requestId) {
await this.store.persistApprovalResolved(conversation, requestId, 'approve')
}
}
/**
* Deny approval.
* Transitions: AwaitingApproval → Idle
*
* **IronClaw write-through**: durable mutation lands before returning.
*/
async deny(conversation: Conversation): Promise<void> {
if (conversation.state !== ConversationState.AwaitingApproval) {
throw new ConversationError(
`Cannot deny: conversation is ${conversation.state}`,
ConversationErrorCode.InvalidTransition
)
}
const requestId = conversation.pending_approval?.request_id
conversation.state = ConversationState.Idle
conversation.pending_approval = undefined
conversation.activeTaskId = undefined // D.1 — deny is terminal (→ Idle), no task in flight
conversation.traceContext = null
conversation.updated_at = new Date()
if (requestId) {
await this.store.persistApprovalResolved(conversation, requestId, 'deny')
}
}
/**
* Clear pending approval on cancel-during-waiting_approval path (spec §4.4, §5.3).
* Distinct from deny() — does NOT append assistant/user messages to history and
* does NOT require the conversation to be in AwaitingApproval state.
* The task is being cancelled, not denied; conversation state should reflect a
* cancelled interruption, not a user decision on the tool.
*
* Also resets conversation.state to Idle so the next startTurn can proceed
* without throwing "Cannot start turn: conversation is awaiting_approval". (BUG-8)
*
* Safe on unknown sessionKey (no-op).
*
* **IronClaw write-through**: durable mutation lands before returning.
*/
async clearPendingApproval(sessionKey: string): Promise<void> {
const conv = this.store.get(sessionKey)
if (!conv) return
const requestId = conv.pending_approval?.request_id
conv.pending_approval = undefined
conv.state = ConversationState.Idle // release the turn lock (BUG-8)
conv.activeTaskId = undefined
conv.traceContext = null
conv.updated_at = new Date()
if (requestId) {
await this.store.persistApprovalResolved(conv, requestId, 'cancel')
}
}
/**
* Record a tool call in the current turn.
*/
recordToolCall(conversation: Conversation, toolCall: TurnToolCall): void {
const currentTurn = conversation.turns[conversation.turns.length - 1]
if (currentTurn) {
currentTurn.tool_calls.push(toolCall)
}
void this.store.persistToolCall(conversation, toolCall)
}
/**
* T2.2 — Persist the system-prompt stable hash for auditability. Called by
* the prompt-cache wiring whenever a new `SystemPromptParts.stableHash` is
* computed for a session. The store-level method enqueues the update onto
* the worker thread (async write-through).
*/
recordSystemPromptStableHash(conversation: Conversation, stableHash: string): void {
void Promise.resolve(this.store.persistSystemPromptStableHash(conversation, stableHash))
}
/**
* Apply a per-provider selection atomically and await its durable outcome.
* Conflicts return the winning map as well as its revision so the RAM mirror
* and the next /models response cannot pair stale data with a fresh revision.
*/
async setModelSelection(
conversation: Conversation,
provider: string,
model: string,
expectedRevision?: number
): Promise<ModelSelectionWriteOutcome> {
const outcome = await this.store.applyModelSelection(
conversation,
provider,
model,
expectedRevision
)
// Another accepted write may have completed while this reply was queued.
// Never move the mirror backwards; conflicts also carry the winning map.
if (outcome.modelSelectionRevision >= (conversation.modelSelectionRevision ?? 0)) {
conversation.modelSelections = outcome.modelSelections
conversation.modelSelectionRevision = outcome.modelSelectionRevision
}
return outcome
}
/**
* Spec 15 Fase B — overwrite the session title from an explicit user rename
* and write it through to the durable `sessions.title` column. Unlike the
* auto-title (`??=` on turn 1), a rename always wins. Caller
* (`applySessionTitle`) has already sanitized + validated `title`. Does NOT
* bump `updated_at`: a rename must not reorder the catalog (mirrors
* `setModelSelection`).
*/
setTitle(conversation: Conversation, title: string): void {
conversation.title = title
void Promise.resolve(this.store.persistTitle?.(conversation))
}
/**
* Build the ChatMessage[] history from conversation turns.
* Used to reconstruct messages for the ReasoningPort.
*
* Risk 5.1: Must produce messages compatible with the new format
* (including tool role and tool_calls).
*/
buildMessageHistory(conversation: Conversation): ChatMessage[] {
const messages: ChatMessage[] = []
for (const turn of conversation.turns) {
// User message
messages.push({ role: 'user', content: turn.user_input })
// Tool calls are tracked for analytics, but the actual
// wire-protocol messages are maintained by the loop, not here.
// Response
if (turn.response) {
messages.push({ role: 'assistant', content: turn.response })
}
}
return messages
}
}