Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
14.6 KB
Raw Blame
/**
 * Wire protocol between the main thread (`PersistQueue`) and the SQLite
 * worker thread (`dbWorker.ts`). The schemas live here so both sides import
 * the same source of truth.
 *
 * `id` is a UUID correlation id; `op` is the discriminated union the
 * dispatcher switches on. Replies use `ok=true|false` with optional
 * `error`/`result` payloads.
 */
import type { ChatMessage, PendingApproval, ToolResult } from '../../core/types'

// ─── Row shapes (DB-side representation) ───────────────────────────────

export interface SessionRow {
  id: string
  session_key: string
  source: string
  user_id: string | null
  team_id: string | null
  channel_type: string | null
  channel_id: string | null
  thread_id: string | null
  /** Effective model of the FIRST task that created the row (INSERT-time
   *  telemetry, migration 007); NOT updated on a later mid-session swap —
   *  do not read it as "current model". Was always NULL before R2. */
  model: string | null
  /** R2 (migration 007) — JSON map `{ provider → model }` of the user's saved
   *  per-provider model selection. NULL until the first `set-model`. */
  model_selections: string | null
  /** #654 (migration 015) — durable revision of `model_selections`, the
   *  compare-and-swap token for the selection write. Optional on the in-memory
   *  shape because a row built before the first write (or by a fixture) has no
   *  value; readers normalize `undefined` to the column default 0. */
  model_selection_revision?: number
  system_prompt_stable_hash: string | null
  parent_session_id: string | null
  started_at: number
  /** Materialized catalog sort key (migration 010). */
  last_activity_at?: number | null
  /** Materialized count of distinct persisted turn numbers (migration 010). */
  turn_count?: number
  ended_at: number | null
  end_reason: string | null
  /** Visible user/assistant bubble count after migration 010. */
  message_count: number
  tool_call_count: number
  input_tokens: number
  output_tokens: number
  cache_read_tokens: number
  cache_write_tokens: number
  /** 1 once any LLM call in this session reported cache info (Anthropic), 0
   *  otherwise (OpenAI/zai/bailian). Sticky — never flips back to 0. */
  cache_tokens_reported: number
  title: string | null
  state: string
  /** D.1 — task currently in flight for this session, or null when idle. */
  active_task_id: string | null
  /** Trace context for the active task only; null for idle and legacy sessions. */
  active_trace_context: string | null
}

export interface MessageRow {
  id?: number
  session_id: string
  ordinal: number
  role: 'system' | 'user' | 'assistant' | 'tool'
  content: string | null
  content_parts: string | null
  tool_call_id: string | null
  tool_calls: string | null
  tool_name: string | null
  timestamp: number
  token_count: number | null
  finish_reason: string | null
  spillover_ref: string | null
  is_error: 0 | 1
  turn_number: number | null
  /**
   * Per-turn token usage (migration 005). Set only on the final/cancel assistant
   * message of a turn; NULL on every other row. Optional on the in-memory shape
   * so callers that don't stamp usage omit them (the dispatcher binds NULL).
   */
  input_tokens?: number | null
  output_tokens?: number | null
  cache_read_tokens?: number | null
  cache_write_tokens?: number | null
}

export interface PendingApprovalRow {
  /** Nullable for approvals created before migration 014. */
  task_budget?: string | null
  /** Omitted write fields persist as legacy NULL; known scopes are `turn_tools` or `exact_invocation`. */
  authorization_scope?: string | null
  request_id: string
  session_id: string
  task_id: string
  tool_name: string
  tool_call_id: string
  parameters: string
  description: string
  context_snapshot: string
  completed_results: string | null
  intent_summary: string | null
  source_message: string | null
  registered_at: number
  expires_at: number
  trace_context: string | null
  /** U5 (migration 013) — suspension discriminator. NULL / 'approval_required'
   *  is the default HITL gate; 'connect_required' is a reactive OAuth-consent
   *  suspension. Preserved so a cold restart rehydrates the right kind. */
  reason: string | null
  /** U5 (migration 013) — oauth mcp-server to connect (reason='connect_required'). */
  mcp_server_name: string | null
}

export interface SessionCountersUpdate {
  messageCountDelta?: number
  toolCallCountDelta?: number
  inputTokensDelta?: number
  outputTokensDelta?: number
  cacheReadTokensDelta?: number
  cacheWriteTokensDelta?: number
  /** When true, marks `cache_tokens_reported = 1` (sticky OR). Set by
   *  persistSessionUsage when the provider reported cache fields for the call. */
  cacheReported?: boolean
}

export interface PersistedSession {
  session: SessionRow
  messages: MessageRow[]
  pending_approval: PendingApprovalRow | null
}

/**
 * Durable outcome of one `update_session_model_selections` attempt (issue #654).
 *
 * - `applied: true` — the row was written and the revision is now `current + 1`.
 * - `applied: false` — the caller's `expectedRevision` no longer matched; the row
 *   is UNCHANGED and the reply carries the revision that won, so the caller can
 *   align its in-RAM mirror and retry from the durable value.
 *
 * A missing session row is neither: the dispatcher throws, because a selection
 * that was not written must never be reported as accepted.
 */
export type ModelSelectionWriteOutcome =
  | { applied: true; modelSelectionRevision: number; modelSelections: Record<string, string> }
  | {
      applied: false
      reason: 'model_selection_conflict'
      modelSelectionRevision: number
      modelSelections: Record<string, string>
    }

export interface PersistedSessionSummary {
  session: SessionRow
  last_activity_at: number
  turn_count: number
  // U5 — carry the connect_required discriminator on the lightweight summary
  // projection too, so the REST rejoin snapshot never degrades a reactive-consent
  // suspension into a generic approval.
  pending_approval: Pick<
    PendingApprovalRow,
    'request_id' | 'tool_name' | 'reason' | 'mcp_server_name'
  > | null
}

export interface PersistedSessionMessagePage {
  session: SessionRow
  messages: MessageRow[]
  pending_approval: Pick<
    PendingApprovalRow,
    'request_id' | 'tool_name' | 'reason' | 'mcp_server_name'
  > | null
  total_turns: number
  first_turn_number: number | null
  last_turn_number: number | null
  last_activity_at: number
}

export interface LoadAllPendingApprovalsRow {
  approval: PendingApprovalRow
  session_key: string
  ownership: Pick<SessionRow, 'user_id' | 'channel_type' | 'channel_id' | 'thread_id'>
}

/**
 * T3.1 — row shape returned by `fts_search_messages`. Mirrors the result shape
 * exposed by both `clerum__session_search` (tool) and `/v1/runtime/sessions/search`
 * (REST). All columns are populated server-side from `sessions` + `messages` so
 * the consumer never gets to choose the `user_id` filter.
 */
export interface SearchMessageRow {
  snippet: string
  session_id: string
  timestamp: number
  channel: string | null
  role: string
}

// ─── In-memory shape returned by reconstruct helpers ──────────────────

export interface RehydratedSnapshot {
  sessionKey: string
  taskId: string
  requestId: string
  approval: PendingApproval
  sourceMessage: Record<string, unknown> | null
}

// ─── Operations ───────────────────────────────────────────────────────

export type WorkerOp =
  | { kind: 'ping' }
  | { kind: 'insert_session'; payload: SessionRow }
  | {
      kind: 'update_session_state'
      sessionId: string
      state: string
      endedAt?: number | null
      endReason?: string | null
      /**
       * D.1 — undefined = keep current active_task_id (COALESCE),
       * a string = set it, null = clear it (dedicated statement).
       */
      activeTaskId?: string | null
      /** undefined = keep, string = set, null = clear. */
      activeTraceContext?: string | null
    }
  | { kind: 'reap_processing_sessions'; nowEpoch: number; chunkSize?: number }
  | {
      kind: 'reap_awaiting_approval_sessions'
      nowEpoch: number
      chunkSize?: number
      /**
       * S1 — when true, reap EVERY 'awaiting_approval' session (live or expired),
       * not just those whose approval has expired/orphaned. Used by the boot
       * reaper because no awaiting_approval session is resumable after a restart.
       * The synthetic message + error_code differ between the two modes. Default
       * (false/undefined) keeps the expired-only behaviour.
       */
      includeLive?: boolean
    }
  | { kind: 'update_session_counters'; sessionId: string; counters: SessionCountersUpdate }
  | { kind: 'update_session_prompt_stable_hash'; sessionId: string; stableHash: string }
  | {
      /** Update one provider in the durable per-session selection map.
       *
       *  #654 — compare-and-swap. With `expectedRevision` the write lands only
       *  while `model_selection_revision` still equals it; `undefined` is the
       *  legacy unconditional write. BOTH paths increment the revision, so a
       *  straggler carrying an already-superseded value is rejected instead of
       *  overwriting the winner. The reply carries the durable outcome
       *  (`ModelSelectionWriteOutcome`), not just an ack. */
      kind: 'update_session_model_selections'
      sessionId: string
      provider: string
      model: string
      expectedRevision?: number
    }
  | {
      /** Spec 15 Fase B — overwrite the user-set session title (rename). Unlike
       *  the Fase A auto-title (COALESCE, turn 1 only), this UNCONDITIONALLY
       *  overwrites: an explicit rename always wins. */
      kind: 'update_session_title'
      sessionId: string
      title: string
    }
  | { kind: 'insert_message'; payload: MessageRow }
  | {
      /**
       * D3 (stateless-agents) — a turn boundary: the boundary message (user
       * message at turn start / assistant message at turn complete) and the
       * session-state flip commit in ONE SQLite transaction. A crash between
       * the two writes can therefore never leave `active_task_id` pointing at
       * a task whose boundary message is absent (or vice versa) — the pair is
       * all-or-nothing on disk.
       */
      kind: 'persist_turn_boundary'
      message: MessageRow
      sessionId: string
      state: string
      /**
       * Same semantics as `update_session_state.activeTaskId`:
       * undefined = keep current, a string = set it, null = clear it.
       */
      activeTaskId?: string | null
      /** Same keep/set/clear semantics as update_session_state. */
      activeTraceContext?: string | null
      /**
       * Server-authoritative auto-title (spec 15). Present only on turn 1; the
       * dispatcher runs `setSessionTitleIfAbsent` (COALESCE) so a retried turn 1
       * never overwrites, and a rename set earlier wins.
       */
      title?: string
    }
  | { kind: 'replace_messages'; sessionId: string; messages: MessageRow[] }
  | {
      kind: 'insert_pending_approval'
      payload: PendingApprovalRow
      replaceRequestId?: string
      markAwaitingApproval?: boolean
    }
  | { kind: 'delete_pending_approval'; requestId: string }
  | { kind: 'load_active_session'; sessionKey: string }
  | {
      kind: 'load_session_message_page'
      sessionKey: string
      limit?: number
      beforeTurn?: number
      afterTurn?: number
    }
  | { kind: 'list_sessions_by_prefix'; sessionKeyPrefix: string }
  | {
      kind: 'list_session_summaries_by_prefix'
      sessionKeyPrefix: string
      userId: string
      limit?: number
      cursorUpdatedAt?: number
      cursorKey?: string
      agentScoped?: boolean
    }
  | { kind: 'load_all_pending_approvals' }
  | { kind: 'sweep_expired'; nowEpoch: number; ttlSeconds: number }
  | { kind: 'fts_search'; query: string; limit: number; userId?: string }
  | {
      kind: 'fts_search_messages'
      query: string
      userId: string
      channelType?: string
      since?: string
      limit: number
    }
  /** Deletes at most `limit` rows; the caller repeats until a batch deletes nothing. */
  | { kind: 'sweep_closed_sessions'; cutoffEpoch: number; limit: number }
  | { kind: 'integrity_check' }
  | { kind: 'checkpoint' }
  | { kind: 'shutdown' }

export interface WorkerMessage {
  id: string
  op: WorkerOp
}

/**
 * D.2 — one entry per session the processing reaper transitioned from
 * 'processing' to 'idle' at boot (its task's reporter died with the previous
 * pod). Uses the columns that actually exist on `sessions` (NOT agent/chatId,
 * which aren't part of the session_key — cross-ref D.2 P1).
 */
export interface ReapedSession {
  sessionId: string
  sessionKey: string
  userId: string | null
  channelType: string | null
  channelId: string | null
  threadId: string | null
  activeTaskId: string | null
  reapedAt: number
}

export interface WorkerReply<T = unknown> {
  id: string
  ok: boolean
  error?: { code: string; message: string; stack?: string }
  result?: T
}

/** Internal heartbeat payload — uses a sentinel id. */
export const HEARTBEAT_ID = '__heartbeat__'

export interface HeartbeatPayload {
  kind: 'heartbeat'
  writesSinceCheckpoint: number
  dbBytes: number
  walBytes: number
}

export function isWriteOp(op: WorkerOp): boolean {
  switch (op.kind) {
    case 'insert_session':
    case 'update_session_state':
    case 'update_session_counters':
    case 'update_session_prompt_stable_hash':
    case 'update_session_model_selections':
    case 'update_session_title':
    case 'insert_message':
    case 'persist_turn_boundary':
    case 'replace_messages':
    case 'insert_pending_approval':
    case 'delete_pending_approval':
    case 'reap_processing_sessions':
    case 'reap_awaiting_approval_sessions':
    case 'sweep_expired':
    case 'sweep_closed_sessions':
      return true
    default:
      return false
  }
}

// ─── Helpers for ChatMessage / ToolResult serialization ────────────────

export function serializeContextSnapshot(snapshot: ChatMessage[]): string {
  return JSON.stringify(snapshot)
}

export function deserializeContextSnapshot(raw: string): ChatMessage[] {
  return JSON.parse(raw) as ChatMessage[]
}

export function serializeCompletedResults(results: ToolResult[] | undefined): string | null {
  if (!results || results.length === 0) return null
  return JSON.stringify(results)
}

export function deserializeCompletedResults(raw: string | null): ToolResult[] | undefined {
  if (!raw) return undefined
  return JSON.parse(raw) as ToolResult[]
}