@swarmclawai/swarmclaw 1.2.0 → 1.2.2

package/src/lib/server/runtime/session-run-manager/drain.ts

@@ -0,0 +1,246 @@
+import { executeSessionChatTurn } from '@/lib/server/chat-execution/chat-execution'
+import { log } from '@/lib/server/logger'
+import { isInternalHeartbeatRun } from '@/lib/server/runtime/heartbeat-source'
+import { notify } from '@/lib/server/ws-hub'
+import { errorMessage } from '@/lib/shared-utils'
+import { handleMainLoopRunResult } from '@/lib/server/agents/main-agent-loop'
+
+import {
+  clearDeferredDrain,
+  decrementNonHeartbeatWork,
+  emitRunMeta,
+  emitToSubscribers,
+  hasActiveNonHeartbeatSessionLease,
+  hasExternalSessionExecutionHold,
+  HEARTBEAT_BUSY_RETRY_MS,
+  MAX_DRAIN_DEPTH,
+  now,
+  queueAutonomyObservation,
+  queueForExecution,
+  reconcileSessionActivityLease,
+  scheduleDeferredDrain,
+  state,
+  syncRunRecord,
+} from './state'
+import type { EnqueueSessionRunInput } from './types'
+
+type EnqueueSessionRunFn = (input: EnqueueSessionRunInput) => unknown
+
+export async function drainExecution(
+  executionKey: string,
+  deps: { enqueueSessionRun: EnqueueSessionRunFn },
+): Promise<void> {
+  const depth = (state.drainDepth.get(executionKey) || 0) + 1
+  state.drainDepth.set(executionKey, depth)
+  if (depth > MAX_DRAIN_DEPTH) {
+    log.error('session-run', 'Drain recursion depth exceeded, deferring', { executionKey, depth, max: MAX_DRAIN_DEPTH })
+    state.drainDepth.delete(executionKey)
+    scheduleDeferredDrain(executionKey, (nextExecutionKey) => { void drainExecution(nextExecutionKey, deps) }, 500)
+    return
+  }
+  try {
+    if (state.runningByExecution.has(executionKey)) return
+    const queue = queueForExecution(executionKey)
+    const userIdx = queue.findIndex((entry) => !entry.run.internal)
+    let next
+    if (userIdx >= 0) {
+      next = queue.splice(userIdx, 1)[0]
+    } else {
+      const internalIdx = queue.findIndex((entry) => !isInternalHeartbeatRun(entry.run.internal, entry.run.source))
+      next = internalIdx >= 0 ? queue.splice(internalIdx, 1)[0] : queue.shift()
+    }
+    if (!next) {
+      clearDeferredDrain(executionKey)
+      return
+    }
+
+    if (isInternalHeartbeatRun(next.run.internal, next.run.source) && hasActiveNonHeartbeatSessionLease(next.run.sessionId)) {
+      queue.unshift(next)
+      scheduleDeferredDrain(executionKey, (nextExecutionKey) => { void drainExecution(nextExecutionKey, deps) }, HEARTBEAT_BUSY_RETRY_MS)
+      log.info('session-run', `Deferred heartbeat run ${next.run.id} for shared busy session`, {
+        sessionId: next.run.sessionId,
+        source: next.run.source,
+      })
+      return
+    }
+
+    if (hasExternalSessionExecutionHold(next.run.sessionId)) {
+      queue.unshift(next)
+      scheduleDeferredDrain(executionKey, (nextExecutionKey) => { void drainExecution(nextExecutionKey, deps) }, HEARTBEAT_BUSY_RETRY_MS)
+      log.info('session-run', `Deferred run ${next.run.id} for external session hold`, {
+        sessionId: next.run.sessionId,
+        source: next.run.source,
+        mode: next.run.mode,
+      })
+      return
+    }
+
+    clearDeferredDrain(executionKey)
+    state.runningByExecution.set(executionKey, next)
+    next.run.status = 'running'
+    next.run.startedAt = now()
+    syncRunRecord(next.run)
+    emitRunMeta(next, 'running')
+    log.info('session-run', `Run started ${next.run.id}`, {
+      sessionId: next.run.sessionId,
+      source: next.run.source,
+      internal: next.run.internal,
+      mode: next.run.mode,
+      timeoutMs: next.maxRuntimeMs || null,
+    })
+
+    let runtimeTimer: ReturnType<typeof setTimeout> | null = null
+    let finishedMissionId: string | null = null
+    if (next.maxRuntimeMs && next.maxRuntimeMs > 0) {
+      runtimeTimer = setTimeout(() => {
+        next.signalController.abort()
+      }, next.maxRuntimeMs)
+    }
+
+    try {
+      const result = await executeSessionChatTurn({
+        sessionId: next.run.sessionId,
+        message: next.message,
+        imagePath: next.imagePath,
+        imageUrl: next.imageUrl,
+        attachedFiles: next.attachedFiles,
+        internal: next.run.internal,
+        source: next.run.source,
+        runId: next.run.id,
+        signal: next.signalController.signal,
+        onEvent: (event) => emitToSubscribers(next, event),
+        modelOverride: next.modelOverride,
+        heartbeatConfig: next.heartbeatConfig,
+        replyToId: next.replyToId,
+      })
+
+      const failed = !!result.error
+      const aborted = next.signalController.signal.aborted
+      next.run.status = aborted ? 'cancelled' : (failed ? 'failed' : 'completed')
+      next.run.endedAt = next.run.endedAt || now()
+      next.run.error = aborted ? (next.run.error || 'Cancelled') : result.error
+      next.run.missionId = result.missionId || next.run.missionId || null
+      finishedMissionId = next.run.missionId || null
+      next.run.resultPreview = result.text?.slice(0, 280)
+      if (typeof result.inputTokens === 'number') next.run.totalInputTokens = result.inputTokens
+      if (typeof result.outputTokens === 'number') next.run.totalOutputTokens = result.outputTokens
+      if (typeof result.estimatedCost === 'number') next.run.estimatedCost = result.estimatedCost
+      syncRunRecord(next.run)
+      emitRunMeta(next, next.run.status, {
+        persisted: result.persisted,
+        hasText: !!result.text,
+        error: next.run.error || null,
+      })
+      log.info('session-run', `Run finished ${next.run.id}`, {
+        sessionId: next.run.sessionId,
+        status: next.run.status,
+        persisted: result.persisted,
+        hasText: !!result.text,
+        error: next.run.error || null,
+        durationMs: (next.run.endedAt || now()) - (next.run.startedAt || now()),
+      })
+      const followup = handleMainLoopRunResult({
+        runId: next.run.id,
+        sessionId: next.run.sessionId,
+        message: next.message,
+        internal: next.run.internal,
+        source: next.run.source,
+        resultText: result.text,
+        error: next.run.error,
+        toolEvents: result.toolEvents,
+        inputTokens: result.inputTokens,
+        outputTokens: result.outputTokens,
+        estimatedCost: result.estimatedCost,
+      })
+      queueAutonomyObservation({
+        runId: next.run.id,
+        sessionId: next.run.sessionId,
+        source: next.run.source,
+        status: next.run.status,
+        resultText: result.text,
+        error: next.run.error || null,
+        toolEvents: result.toolEvents,
+        sourceMessage: next.message,
+      })
+      if (followup) {
+        setTimeout(() => {
+          try {
+            deps.enqueueSessionRun({
+              sessionId: next.run.sessionId,
+              message: followup.message,
+              internal: true,
+              source: 'main-loop-followup',
+              mode: 'followup',
+              dedupeKey: followup.dedupeKey,
+            })
+          } catch (err: unknown) {
+            log.warn('session-run', `Main loop follow-up enqueue failed for ${next.run.sessionId}`, {
+              error: errorMessage(err),
+            })
+          }
+        }, Math.max(0, followup.delayMs || 0))
+      }
+      next.resolve(result)
+    } catch (err: unknown) {
+      const aborted = next.signalController.signal.aborted
+      next.run.status = aborted ? 'cancelled' : 'failed'
+      next.run.endedAt = now()
+      next.run.error = errorMessage(err)
+      finishedMissionId = next.run.missionId || null
+      syncRunRecord(next.run)
+      emitRunMeta(next, next.run.status, { error: next.run.error })
+      log.error('session-run', `Run failed ${next.run.id}`, {
+        sessionId: next.run.sessionId,
+        status: next.run.status,
+        error: next.run.error,
+        durationMs: (next.run.endedAt || now()) - (next.run.startedAt || now()),
+      })
+      if (err instanceof Error && err.stack) {
+        log.error('session-run', `Run failed stack trace ${next.run.id}`, {
+          sessionId: next.run.sessionId,
+          stack: err.stack,
+        })
+      }
+      queueAutonomyObservation({
+        runId: next.run.id,
+        sessionId: next.run.sessionId,
+        source: next.run.source,
+        status: next.run.status,
+        error: next.run.error || null,
+        sourceMessage: next.message,
+      })
+      next.reject(err instanceof Error ? err : new Error(next.run.error))
+    } finally {
+      if (runtimeTimer) clearTimeout(runtimeTimer)
+      state.runningByExecution.delete(executionKey)
+      decrementNonHeartbeatWork(next)
+      reconcileSessionActivityLease(next.run.sessionId)
+      notify(`stream-end:${next.run.sessionId}`)
+      if (finishedMissionId && next.run.source !== 'chat') {
+        const missionId = finishedMissionId
+        queueMicrotask(() => {
+          import('@/lib/server/missions/mission-service')
+            .then(({ loadMissionById, requestMissionTick }) => {
+              const mission = loadMissionById(missionId)
+              if (!mission) return
+              if (mission.status !== 'active') return
+              if (mission.phase === 'dispatching' || mission.phase === 'executing') return
+              requestMissionTick(missionId, 'run_drained', {
+                runId: next.run.id,
+                source: next.run.source,
+                status: next.run.status,
+              })
+            })
+            .catch((err: unknown) => {
+              log.warn('session-run', 'Mission tick failed', { missionId, runId: next.run.id, error: errorMessage(err) })
+            })
+        })
+      }
+      void drainExecution(executionKey, deps)
+    }
+  } finally {
+    const currentDepth = state.drainDepth.get(executionKey)
+    if (currentDepth && currentDepth > 1) state.drainDepth.set(executionKey, currentDepth - 1)
+    else state.drainDepth.delete(executionKey)
+  }
+}

package/src/lib/server/runtime/session-run-manager/enqueue.ts

@@ -0,0 +1,287 @@
+import { genId } from '@/lib/id'
+import type { SessionRunRecord } from '@/types'
+import { getSession } from '@/lib/server/sessions/session-repository'
+import { loadRuntimeSettings } from '@/lib/server/runtime/runtime-settings'
+import { log } from '@/lib/server/logger'
+import { isInternalHeartbeatRun } from '@/lib/server/runtime/heartbeat-source'
+import { getEnabledToolIds } from '@/lib/capability-selection'
+import { isAllEstopEngaged, isAutonomyEstopEngaged } from '@/lib/server/runtime/estop'
+import { getActiveSessionProcess } from '@/lib/server/runtime/runtime-state'
+
+import { cancelPendingForSession } from './cancellation'
+import {
+  abortSessionRuntime,
+  chainCallerSignal,
+  COLLECT_COALESCE_WINDOW_MS,
+  emitRunMeta,
+  executionKeyForSession,
+  incrementNonHeartbeatWork,
+  messagePreview,
+  nextQueuedAt,
+  normalizeMode,
+  queueForExecution,
+  reconcileSessionActivityLease,
+  registerRun,
+  state,
+  syncRunRecord,
+} from './state'
+import type {
+  EnqueueSessionRunInput,
+  EnqueueSessionRunResult,
+  SessionQueueMode,
+  SessionRunQueueEntry,
+} from './types'
+
+type RepairSessionRunQueueFn = (
+  sessionId: string,
+  opts?: {
+    executionKey?: string
+    maxQueuedAgeMs?: number
+    reason?: string
+  },
+) => { kickedExecutionKeys: number; recoveredQueuedRuns: number }
+
+type DrainExecutionFn = (executionKey: string) => Promise<void>
+
+const LONG_TOOL_NAMES: ReadonlySet<string> = new Set(['claude_code', 'codex_cli', 'opencode_cli'])
+
+type SessionToolConfig = {
+  tools?: string[] | null
+  extensions?: string[] | null
+}
+
+function computeEffectiveRunTimeoutMs(
+  baseTimeoutMs: number,
+  sessionTools: string[],
+  runtime: { claudeCodeTimeoutMs: number },
+): number {
+  const hasLongTool = sessionTools.some((tool) => LONG_TOOL_NAMES.has(tool))
+  if (!hasLongTool) return baseTimeoutMs
+  const toolTimeout = runtime.claudeCodeTimeoutMs + 120_000
+  return Math.max(baseTimeoutMs, toolTimeout)
+}
+
+function isAutonomyManagedEnqueue(source: string, internal: boolean): boolean {
+  return !(source === 'chat' && !internal)
+}
+
+function buildRecoveryPayload(
+  input: EnqueueSessionRunInput,
+  source: string,
+  mode: SessionQueueMode,
+  maxRuntimeMs: number | undefined,
+  executionKey: string,
+) {
+  return {
+    message: input.message,
+    imagePath: input.imagePath,
+    imageUrl: input.imageUrl,
+    attachedFiles: input.attachedFiles,
+    internal: input.internal === true,
+    source,
+    mode,
+    maxRuntimeMs,
+    modelOverride: input.modelOverride,
+    heartbeatConfig: input.heartbeatConfig,
+    replyToId: input.replyToId,
+    executionGroupKey: executionKey.startsWith('session:') ? undefined : executionKey,
+  }
+}
+
+function findDedupeMatch(sessionId: string, dedupeKey?: string) {
+  if (!dedupeKey) return null
+  const executionKey = executionKeyForSession(sessionId)
+  const running = state.runningByExecution.get(executionKey)
+  if (running?.run.sessionId === sessionId && running.run.dedupeKey === dedupeKey) return running
+  const queue = queueForExecution(executionKey)
+  return queue.find((entry) => entry.run.sessionId === sessionId && entry.run.dedupeKey === dedupeKey) || null
+}
+
+export function enqueueSessionRun(
+  input: EnqueueSessionRunInput,
+  deps: {
+    repairSessionRunQueue: RepairSessionRunQueueFn
+    drainExecution: DrainExecutionFn
+  },
+): EnqueueSessionRunResult {
+  const internal = input.internal === true
+  const mode = normalizeMode(input.mode, internal)
+  const source = input.source || 'chat'
+  if (isAllEstopEngaged()) {
+    throw new Error('Execution is blocked because all estop is engaged.')
+  }
+  if (isAutonomyEstopEngaged() && isAutonomyManagedEnqueue(source, internal)) {
+    throw new Error(`Autonomy estop is engaged. New ${source} runs are paused.`)
+  }
+  const executionKey = typeof input.executionGroupKey === 'string' && input.executionGroupKey.trim()
+    ? input.executionGroupKey.trim()
+    : executionKeyForSession(input.sessionId)
+  deps.repairSessionRunQueue(input.sessionId, {
+    executionKey,
+    reason: 'Recovered stale queued run before enqueue',
+  })
+  const runtime = loadRuntimeSettings()
+  const defaultMaxRuntimeMs = runtime.ongoingLoopMaxRuntimeMs ?? (10 * 60_000)
+  const sessionData = getSession(input.sessionId) as SessionToolConfig | null
+  const sessionTools = getEnabledToolIds(sessionData)
+  const adjustedDefaultMs = computeEffectiveRunTimeoutMs(defaultMaxRuntimeMs, sessionTools, runtime)
+  const effectiveMaxRuntimeMs = typeof input.maxRuntimeMs === 'number'
+    ? input.maxRuntimeMs
+    : adjustedDefaultMs
+
+  const dedupe = findDedupeMatch(input.sessionId, input.dedupeKey)
+  if (dedupe) {
+    const cb = input.onEvent
+    if (cb) dedupe.onEvents.push(cb)
+    if (input.callerSignal) chainCallerSignal(input.callerSignal, dedupe.signalController)
+    return {
+      runId: dedupe.run.id,
+      position: 0,
+      deduped: true,
+      promise: dedupe.promise,
+      abort: () => dedupe.signalController.abort(),
+      unsubscribe: () => {
+        if (!cb) return
+        const idx = dedupe.onEvents.indexOf(cb)
+        if (idx >= 0) dedupe.onEvents.splice(idx, 1)
+      },
+    }
+  }
+
+  if (mode === 'steer') {
+    const running = state.runningByExecution.get(executionKey)
+    if (running && running.run.sessionId === input.sessionId) {
+      running.signalController.abort()
+      try { getActiveSessionProcess(input.sessionId)?.kill?.() } catch { /* noop */ }
+    }
+    cancelPendingForSession(input.sessionId, 'Cancelled by steer mode')
+  }
+
+  if (!internal && source === 'chat') {
+    const running = state.runningByExecution.get(executionKey)
+    if (running && isInternalHeartbeatRun(running.run.internal, running.run.source)) {
+      log.info('session-run', `Preempting heartbeat ${running.run.id} for user chat on ${input.sessionId}`)
+      abortSessionRuntime(running, 'Preempted by user chat')
+      state.runningByExecution.delete(executionKey)
+    }
+  }
+
+  const running = state.runningByExecution.get(executionKey)
+  const queue = queueForExecution(executionKey)
+  if (mode === 'collect' && !input.imagePath && !input.imageUrl && !input.attachedFiles?.length) {
+    const nowMs = nextQueuedAt()
+    const candidate = queue.at(-1)
+    const canCoalesce = !!candidate
+      && candidate.run.mode === 'collect'
+      && candidate.run.internal === internal
+      && candidate.run.source === source
+      && !candidate.imagePath
+      && !candidate.imageUrl
+      && !candidate.attachedFiles?.length
+      && (nowMs - candidate.run.queuedAt) <= COLLECT_COALESCE_WINDOW_MS
+
+    if (candidate && canCoalesce) {
+      const nextChunk = input.message.trim()
+      if (nextChunk) {
+        const current = candidate.message.trim()
+        candidate.message = current
+          ? `${current}\n\n[Collected follow-up]\n${nextChunk}`
+          : nextChunk
+        candidate.run.messagePreview = messagePreview(candidate.message)
+        candidate.run.queuedAt = nowMs
+        syncRunRecord(candidate.run)
+      }
+      const coalesceCb = input.onEvent
+      if (coalesceCb) candidate.onEvents.push(coalesceCb)
+      if (input.callerSignal) chainCallerSignal(input.callerSignal, candidate.signalController)
+      emitRunMeta(candidate, 'queued', { position: 0, coalesced: true, mergedIntoRunId: candidate.run.id })
+      return {
+        runId: candidate.run.id,
+        position: 0,
+        coalesced: true,
+        promise: candidate.promise,
+        abort: () => candidate.signalController.abort(),
+        unsubscribe: () => {
+          if (!coalesceCb) return
+          const idx = candidate.onEvents.indexOf(coalesceCb)
+          if (idx >= 0) candidate.onEvents.splice(idx, 1)
+        },
+      }
+    }
+  }
+
+  const runId = genId(8)
+  const run: SessionRunRecord = {
+    id: runId,
+    sessionId: input.sessionId,
+    missionId: input.missionId ?? getSession(input.sessionId)?.missionId ?? null,
+    source,
+    internal,
+    mode,
+    status: 'queued',
+    messagePreview: messagePreview(input.message),
+    dedupeKey: input.dedupeKey,
+    queuedAt: nextQueuedAt(),
+    recoveredFromRestart: input.recoveredFromRestart === true,
+    recoveredFromRunId: input.recoveredFromRunId,
+    recoveryPayload: buildRecoveryPayload(
+      input,
+      source,
+      mode,
+      effectiveMaxRuntimeMs > 0 ? effectiveMaxRuntimeMs : undefined,
+      executionKey,
+    ),
+  }
+  registerRun(run)
+
+  let resolve!: EnqueueSessionRunResult['promise'] extends Promise<infer T> ? (value: T) => void : never
+  let reject!: (error: Error) => void
+  const promise = new Promise<import('@/lib/server/chat-execution/chat-execution-types').ExecuteChatTurnResult>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  promise.catch(() => {})
+  state.promises.set(runId, promise)
+
+  const entry: SessionRunQueueEntry = {
+    executionKey,
+    run,
+    message: input.message,
+    imagePath: input.imagePath,
+    imageUrl: input.imageUrl,
+    attachedFiles: input.attachedFiles,
+    onEvents: input.onEvent ? [input.onEvent] : [],
+    signalController: new AbortController(),
+    maxRuntimeMs: effectiveMaxRuntimeMs > 0 ? effectiveMaxRuntimeMs : undefined,
+    modelOverride: input.modelOverride,
+    heartbeatConfig: input.heartbeatConfig,
+    replyToId: input.replyToId,
+    resolve,
+    reject,
+    promise,
+  }
+
+  if (input.callerSignal) chainCallerSignal(input.callerSignal, entry.signalController)
+
+  queue.push(entry)
+  incrementNonHeartbeatWork(entry)
+  if (entry.nonHeartbeatCounted) {
+    reconcileSessionActivityLease(input.sessionId)
+  }
+  const position = (running ? 1 : 0) + queue.length - 1
+  emitRunMeta(entry, 'queued', { position })
+  void deps.drainExecution(executionKey)
+
+  const entryCb = input.onEvent
+  return {
+    runId,
+    position,
+    promise,
+    abort: () => entry.signalController.abort(),
+    unsubscribe: () => {
+      if (!entryCb) return
+      const idx = entry.onEvents.indexOf(entryCb)
+      if (idx >= 0) entry.onEvents.splice(idx, 1)
+    },
+  }
+}

package/src/lib/server/runtime/session-run-manager/queries.ts

@@ -0,0 +1,117 @@
+import type {
+  RunEventRecord,
+  SessionQueueSnapshot,
+  SessionQueuedTurn,
+  SessionRunRecord,
+  SessionRunStatus,
+} from '@/types'
+import {
+  listPersistedRunEvents,
+  listPersistedRuns,
+  loadPersistedRun,
+} from '@/lib/server/runtime/run-ledger'
+import { isInternalHeartbeatRun } from '@/lib/server/runtime/heartbeat-source'
+
+import { state } from './state'
+import type { SessionRunQueueEntry } from './types'
+
+export function getSessionRunState(sessionId: string): {
+  runningRunId?: string
+  queueLength: number
+} {
+  const summary = getSessionExecutionState(sessionId)
+  return {
+    runningRunId: summary.runningRunId,
+    queueLength: summary.queueLength,
+  }
+}
+
+function visibleQueuedEntriesForSession(sessionId: string): SessionRunQueueEntry[] {
+  return Array.from(state.queueByExecution.values())
+    .flatMap((queue) => queue)
+    .filter((entry) => entry.run.sessionId === sessionId && entry.run.internal !== true)
+    .sort((left, right) => left.run.queuedAt - right.run.queuedAt)
+}
+
+function toQueuedTurn(entry: SessionRunQueueEntry, index: number): SessionQueuedTurn {
+  return {
+    runId: entry.run.id,
+    sessionId: entry.run.sessionId,
+    missionId: entry.run.missionId || null,
+    text: entry.message,
+    queuedAt: entry.run.queuedAt,
+    position: index + 1,
+    imagePath: entry.imagePath,
+    imageUrl: entry.imageUrl,
+    attachedFiles: entry.attachedFiles,
+    replyToId: entry.replyToId,
+    source: entry.run.source,
+  }
+}
+
+export function getSessionQueueSnapshot(sessionId: string): SessionQueueSnapshot {
+  const execution = getSessionExecutionState(sessionId)
+  const visibleQueued = visibleQueuedEntriesForSession(sessionId)
+  return {
+    sessionId,
+    activeRunId: execution.runningRunId || null,
+    queueLength: visibleQueued.length,
+    items: visibleQueued.map((entry, index) => toQueuedTurn(entry, index)),
+  }
+}
+
+export function getSessionExecutionState(sessionId: string): {
+  runningRunId?: string
+  queueLength: number
+  hasRunning: boolean
+  hasQueued: boolean
+  hasRunningHeartbeat: boolean
+  hasQueuedHeartbeat: boolean
+  hasRunningNonHeartbeat: boolean
+  hasQueuedNonHeartbeat: boolean
+} {
+  const running = Array.from(state.runningByExecution.values())
+    .find((entry) => entry.run.sessionId === sessionId)
+  const runningMatchesSession = Boolean(running)
+  const runningHeartbeat = Boolean(
+    runningMatchesSession
+    && running
+    && isInternalHeartbeatRun(running.run.internal, running.run.source),
+  )
+  const runningNonHeartbeat = Boolean(runningMatchesSession && !runningHeartbeat)
+  const queuedEntries = Array.from(state.queueByExecution.values())
+    .flatMap((queue) => queue)
+    .filter((entry) => entry.run.sessionId === sessionId)
+  const queuedHeartbeat = queuedEntries.filter((entry) =>
+    isInternalHeartbeatRun(entry.run.internal, entry.run.source),
+  ).length
+  const queuedNonHeartbeat = queuedEntries.length - queuedHeartbeat
+  return {
+    runningRunId: (runningMatchesSession && running?.run.status === 'running')
+      ? running.run.id
+      : undefined,
+    queueLength: queuedEntries.length,
+    hasRunning: Boolean(runningMatchesSession),
+    hasQueued: queuedEntries.length > 0,
+    hasRunningHeartbeat: runningHeartbeat,
+    hasQueuedHeartbeat: queuedHeartbeat > 0,
+    hasRunningNonHeartbeat: runningNonHeartbeat,
+    hasQueuedNonHeartbeat: queuedNonHeartbeat > 0,
+  }
+}
+
+export function getRunById(runId: string): SessionRunRecord | null {
+  return state.runs.get(runId) || loadPersistedRun(runId)
+}
+
+export function listRuns(params?: {
+  sessionId?: string
+  status?: SessionRunStatus
+  limit?: number
+}): SessionRunRecord[] {
+  return listPersistedRuns(params)
+}
+
+export function listRunEvents(runId: string, limit?: number): RunEventRecord[] {
+  return listPersistedRunEvents(runId, limit)
+}