Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

17.8 KB
Raw Blame
/**
 * A conversation's history, for a window that asks for it (`session_get`): the whole thread, or the page
 * before a cursor and the cursor to the page before that; and the conversation an agent holds, with how
 * many lines it has (`sessions_list`). The socket hands each request here and sends back what comes out,
 * so every field of the replies is decided in this file.
 *
 * Claude Code and Codex read only the page asked for (lib/transcriptPages.ts), and the other file engines
 * at most the newest 64 MB of their transcripts (lib/transcriptTail.ts), because the whole history of one
 * long session is more memory than the daemon has (the crash of 2026-10-03). The database engines still
 * read a whole conversation from their stores and cut the page from it: bounding them is engine work
 * still to come (docs/design/2026-10-03-harnessd.md, "Next").
 *
 * Moved verbatim out of the socket's request switch (docs/design/2026-10-03-harnessd.md), but for the
 * four database engines: each had its own copy of the same windowing, and they now share one.
 */
import { withoutOutputTail } from '../../lib/cardUpdate.js'
import { stat } from 'node:fs/promises'
import type { EngineTranscript } from '../../engines/facets/transcript.js'
import { EngineReadError } from '../../engines/worker/protocol.js'
import { transcriptReadIdentity } from './readIdentity.js'
import { isOtherEngine, loadEngine, type InProcessModules, type OtherEngine } from '../../engines/inProcess.js'
import { sid } from '../../lib/log.js'
import { lastActivityAt } from '../../lib/agentFrame.js'
import type { SessionEvent } from '../../engines/kit/events.js'
import { projectDisplayName, type RegisteredSession } from '../../lib/registry.js'
import type { TranscriptPager } from '../../lib/transcriptPages.js'
import { tailFileCapped, WHOLE_READ_CAP_BYTES } from '../../lib/transcriptTail.js'

export interface HistoryDeps {
  /** The registry's lookup, by agent or session id. */
  resolve: (id: string) => RegisteredSession | undefined
  /** The conversations kept as stopped harnesses (lib/stoppedAgents.ts): a stop's, an exited engine's,
   *  and one a restart, a move or a restore had to leave for a new one. */
  stopped: () => readonly RegisteredSession[]
  /** Line counts, and the explicit inline compatibility path's pages. Isolated readers own their indexes. */
  pages: Pick<TranscriptPager, 'page' | 'lineCount'>
  readerFor: (engine: string) => EngineTranscript | undefined
  /** The database engines' stores. */
  dbs: { opencode: string; kilo: string; devin: string }
  /** Hermes keeps a store per profile: the one this session's lives in. */
  hermesDb: (session: RegisteredSession) => Promise<string>
}

/**
 * Amp history comes from AMP's store, not from ours.
 *
 * The plugin's JSONL is a record of what the plugin saw; a thread that ran before the integration existed
 * — or in a pane still holding an older plugin — is simply not in it, and no local file can rebuild those
 * turns. `amp threads export` returns the thread complete, including the tools Amp runs server-side.
 *
 * The local file stays as the FALLBACK, because an export is a network call and a pane with no history at
 * all is worse than a partial one. Which source answered is logged either way: silently serving the lesser
 * record is exactly how the missing tool cards went unnoticed for a day.
 */
async function ampHistory(amp: InProcessModules['amp'], sessionId: string, lines: string[]): Promise<SessionEvent[]> {
  const messages = await amp.readAmpThread(sessionId)
  if (messages) {
    console.log(`[history] ${sessionId.slice(0, 12)} amp · ${messages.length} message(s) from amp's own store`)
    return amp.ampThreadToEvents(messages)
  }
  console.warn(`[history] ${sessionId.slice(0, 12)} amp · export unavailable — falling back to the local transcript`)
  return amp.ampMessagesToEvents(lines)
}

/** Grok, agy and Copilot have no transcript windower yet. Keep BOTH `session_get` shapes on the same real-record
 * replay: web always sends a limit, while legacy callers omit it. Returning the whole small transcript for a
 * page is honest (`hasMore:false`) and cannot fall through to Claude's incompatible line cursor. */
export function wholeHistoryPage(events: SessionEvent[], paginated: boolean):
  { events: SessionEvent[]; hasMore?: false; oldestCursor?: null } {
  return paginated ? { events, hasMore: false, oldestCursor: null } : { events }
}

/** What a window asks for: `limit` records before the `before` cursor. No limit asks for all of them. */
interface PageAsk { limit?: number; before?: string }

/** One database engine's answer to `session_get`, about `s`, under the id it was asked by. */
type DatabasePage = (s: RegisteredSession, sessionId: string, ask: PageAsk) => Promise<Record<string, unknown>>

/**
 * An engine that keeps its conversations in a database, not a transcript file: the conversation read
 * from its store, then replayed whole or windowed, in the same shape as every other engine's answer.
 *
 * Both shapes are load-bearing: the web client always sends a `limit`, so answering only the whole
 * conversation opens an empty pane, the half-dispatch the socket was once caught on. Each windower
 * namespaces its cursors by engine (`kilo:<index>`), so a cursor from another engine reads as stale
 * rather than silently indexing into the wrong conversation.
 */
function databasePage<M>(
  read: (s: RegisteredSession) => Promise<M[]>,
  toEvents: (messages: M[]) => SessionEvent[],
  windowOf: (messages: M[], opts: { limit: number; before?: string }) =>
    { window: M[]; hasMore: boolean; oldestCursor: string | null; staleCursor?: boolean },
): DatabasePage {
  return async (s, sessionId, { limit, before }) => {
    const messages = await read(s)
    const timestamp = new Date(s.touchedAt).toISOString()
    if (!limit) {
      return { id: sessionId, title: projectDisplayName(s), events: toEvents(messages), timestamp, engine: s.engine }
    }
    const w = windowOf(messages, { limit, before })
    if (w.staleCursor) {
      return { id: sessionId, title: projectDisplayName(s), events: [], timestamp, engine: s.engine, hasMore: false, oldestCursor: null, staleCursor: true }
    }
    const events = toEvents(w.window)
    if (before && events[events.length - 1]?.type === 'done') events.pop()
    return { id: sessionId, title: projectDisplayName(s), events, timestamp, engine: s.engine, hasMore: w.hasMore, oldestCursor: w.oldestCursor }
  }
}

export function createHistory({ resolve, stopped, pages, dbs, hermesDb, readerFor }: HistoryDeps) {
  // Devin, OpenCode and Kilo keep one store on this machine. Hermes keeps one per HOME, so its path is
  // the session's own (`hermesDb`) rather than this machine's default.
  // Each store's reader, replay and window are the engine's own code, loaded in this process (engines/inProcess.ts).
  const databases = new Map<string, (s: RegisteredSession) => Promise<DatabasePage | null>>([
    ['devin', async () => { const m = await loadEngine('devin'); return m && databasePage((s) => m.readDevinMessages(dbs.devin, s.sessionId), m.devinMessagesToEvents, m.windowDevinMessages) }],
    ['hermes', async () => { const m = await loadEngine('hermes'); return m && databasePage(async (s) => m.readHermesMessages(await hermesDb(s), s.sessionId), m.hermesMessagesToEvents, m.windowHermesMessages) }],
    ['opencode', async () => { const m = await loadEngine('opencode'); return m && databasePage((s) => m.readOpencodeMessages(dbs.opencode, s.sessionId), m.opencodeMessagesToEvents, m.windowOpencodeMessages) }],
    ['kilo', async () => { const m = await loadEngine('kilo'); return m && databasePage((s) => m.readKiloMessages(dbs.kilo, s.sessionId), m.kiloMessagesToEvents, m.windowKiloMessages) }],
  ])
  /** A conversation with nothing to show: no transcript yet, or its engine's code could not be loaded. */
  const emptyPage = (s: RegisteredSession, sessionId: string): Record<string, unknown> => ({
    id: sessionId,
    title: projectDisplayName(s),
    events: [],
    timestamp: new Date(s.touchedAt).toISOString(),
    engine: s.engine,
    hasMore: false,
    oldestCursor: null,
  })

  const lookup = (id: string) => resolve(id) ?? stopped().find((saved) => saved.sessionId === id)

  /** The reply to a `session_get` request, for the socket to send as it is. */
  const sessionGet = async (payload: Record<string, unknown>): Promise<Record<string, unknown>> => {
    const reply = await readHistory(payload)
    return Array.isArray(reply.events) ? { ...reply, events: reply.events.map(withoutOutputTail) } : reply
  }
  const readHistory = async (payload: Record<string, unknown>): Promise<Record<string, unknown>> => {
    const sessionId = payload.sessionId as string | undefined
    if (!sessionId) return { error: 'MISSING_SESSION_ID' }
    // Only serve transcripts for a session this daemon REGISTERED — live, or kept as a stopped one —
    // read from its own trusted transcriptPath: never resolve an arbitrary request-supplied id to a
    // file (that let a caller read any *.jsonl on the computer, incl. unshared claude history /
    // traversal). A kept conversation used to answer NOT_FOUND, so a conversation the daemon had to
    // leave for a new one could no longer be read at all (round 24).
    const s = lookup(sessionId)
    if (!s) return { error: 'NOT_FOUND' }
    // The registry finds an agent by its agent id too, and the reply names the id it was asked by. What
    // is read is the conversation's own, `s.sessionId`: an engine's store, Amp's export and Cursor's task
    // links know that id alone, and under the agent id they read nothing.
    // Optional pagination: `limit` = window size; `before` = cursor (the oldest record the
    // client already holds). Absent → full transcript (legacy). Clamp limit defensively.
    const rawLimit = payload.limit
    const limit = typeof rawLimit === 'number' && rawLimit > 0 ? Math.min(Math.floor(rawLimit), 500) : undefined
    const before = typeof payload.before === 'string' ? payload.before : undefined
    const database = databases.get(s.engine)
    if (database) {
      const page = await database(s)
      return page ? page(s, sessionId, { limit, before }) : emptyPage(s, sessionId)
    }
    if (!s.transcriptPath) return emptyPage(s, sessionId)
    const reader = readerFor(s.engine)
    if (reader) {
      const identity = transcriptReadIdentity(s)
      try {
        const { events, timestamp, ...page } = await reader.historyPage(s, { limit, before }, pages)
        if (transcriptReadIdentity(lookup(sessionId)) !== identity) throw new EngineReadError('ENGINE_STALE_REPLY')
        return { id: sessionId, title: projectDisplayName(s), events, timestamp, engine: s.engine, ...page }
      } catch (error) {
        const failed = error instanceof EngineReadError ? error : new EngineReadError('ENGINE_UNAVAILABLE')
        return { error: failed.code, retryable: failed.retryable }
      }
    }
    // Read from the end and bounded: these engines have no pages of their own yet, and one huge
    // transcript read whole would take the whole daemon down (lib/transcriptTail.ts). History past
    // the cap is not shown, and the reply says so.
    const { lines, truncated: capped } = await tailFileCapped(s.transcriptPath)
    if (capped) console.warn(`[backend] session_get ${sid(sessionId)}: the transcript is over ${WHOLE_READ_CAP_BYTES / 1024 / 1024} MB · its oldest history is not shown`)
    const truncated = capped ? { truncated: true } : {}
    const st = await stat(s.transcriptPath).catch(() => null)
    const timestamp = new Date(st?.mtimeMs ?? Date.now()).toISOString()
    // The other file engines' replays and windows are their own code, loaded in this process: one that could
    // not load shows an empty conversation, and so does an engine with no reader and no code of its own here.
    // Claude Code and Codex always have a reader (core/engines/readers.ts), and a shell keeps no transcript
    // (registry.engineKeepsTranscriptFile), so none reaches this: their replays are their readers', never core's.
    const other = isOtherEngine(s.engine) ? await loadEngine(s.engine) : null
    if (other === null) return { ...emptyPage(s, sessionId), timestamp }
    const engine = <Name extends OtherEngine>(name: Name): InProcessModules[Name] => other as InProcessModules[Name]

    if (!limit) {
      const fullEvents = s.engine === 'cursor'
          ? engine('cursor').cursorMessagesToEvents(lines, s.sessionId, await engine('cursor').loadCursorReplayTaskLinks(engine('cursor').cursorConfigDir(), s.sessionId, engine('cursor').cursorDataDir()))
          : s.engine === 'muse'
            ? engine('muse').museMessagesToEvents(lines)
            : s.engine === 'amp'
            ? await ampHistory(engine('amp'), s.sessionId, lines)
            : s.engine === 'grok'
              ? wholeHistoryPage(engine('grok').grokMessagesToEvents(lines), false).events
            : s.engine === 'agy'
              ? wholeHistoryPage(engine('agy').agyMessagesToEvents(lines), false).events
            : s.engine === 'copilot'
              ? wholeHistoryPage(engine('copilot').copilotMessagesToEvents(lines), false).events
            : s.engine === 'pi'
            ? engine('pi').piMessagesToEvents(lines)
            : s.engine === 'omp'
            ? engine('omp').ompMessagesToEvents(lines)
            : engine('commandcode').commandcodeMessagesToEvents(lines)
      return {
        id: sessionId,
        title: projectDisplayName(s),
        events: fullEvents,
        timestamp,
        engine: s.engine,
        ...truncated,
      }
    }

    // Muse has no windower, so it must not fall through to the raw one: that pairs claude's
    // line-uuid cursor with claude's normalizer, and a muse transcript comes back EMPTY — the web
    // pane opened blank with no error anywhere. Until a muse window exists, answer the page with
    // the whole transcript (`hasMore: false` ends the scroll honestly, and these sessions are
    // small: a real one measured 271 lines).
    // Amp is in the same position as muse and for the same reason: no windower, so falling
    // through would pair claude's line-uuid cursor with claude's normalizer and return nothing.
    if (s.engine === 'muse' || s.engine === 'amp' || s.engine === 'grok' || s.engine === 'agy' || s.engine === 'copilot') {
      const wholePage = s.engine === 'grok'
        ? wholeHistoryPage(engine('grok').grokMessagesToEvents(lines), true)
        : s.engine === 'agy'
          ? wholeHistoryPage(engine('agy').agyMessagesToEvents(lines), true)
          : s.engine === 'copilot'
            ? wholeHistoryPage(engine('copilot').copilotMessagesToEvents(lines), true)
            : null
      return {
        id: sessionId,
        title: projectDisplayName(s),
        events: s.engine === 'amp'
          ? await ampHistory(engine('amp'), s.sessionId, lines)
          : wholePage
            ? wholePage.events
            : engine('muse').museMessagesToEvents(lines),
        timestamp,
        engine: s.engine,
        hasMore: wholePage?.hasMore ?? false,
        oldestCursor: wholePage?.oldestCursor ?? null,
        ...truncated,
      }
    }
    const w = s.engine === 'cursor'
        ? engine('cursor').windowCursorLines(lines, { limit, before })
        : s.engine === 'pi'
          ? engine('pi').windowPiLines(lines, { limit, before })
          : s.engine === 'omp'
            ? engine('omp').windowOmpLines(lines, { limit, before })
            : engine('commandcode').windowCommandCodeLines(lines, { limit, before })
    if (w.staleCursor) {
      return { id: sessionId, title: projectDisplayName(s), events: [], timestamp, engine: s.engine, hasMore: false, oldestCursor: null, staleCursor: true, ...truncated }
    }
    const events = s.engine === 'cursor'
        ? engine('cursor').cursorMessagesToEvents(
            w.window,
            s.sessionId,
            await engine('cursor').loadCursorReplayTaskLinks(engine('cursor').cursorConfigDir(), s.sessionId, engine('cursor').cursorDataDir()),
            'startIndex' in w && typeof w.startIndex === 'number' ? w.startIndex : 0,
            'initialTodos' in w && Array.isArray(w.initialTodos) ? w.initialTodos : [],
          )
        : s.engine === 'pi'
          ? engine('pi').piMessagesToEvents(w.window)
          : s.engine === 'omp'
            ? engine('omp').ompMessagesToEvents(w.window)
            : engine('commandcode').commandcodeMessagesToEvents(w.window)
    // muse and amp are answered above and never reach here, so both are absent by design.
    // Older pages must not inject a spurious end-of-transcript marker mid-scroll.
    if (before && events[events.length - 1]?.type === 'done') events.pop()
    return {
      id: sessionId,
      title: projectDisplayName(s),
      events,
      timestamp,
      engine: s.engine,
      hasMore: w.hasMore,
      oldestCursor: w.oldestCursor,
      ...truncated,
    }
  }

  /** The reply to a `sessions_list` request: the one conversation an agent holds, for the socket to send. */
  const sessionsList = async (payload: Record<string, unknown>): Promise<Record<string, unknown>> => {
    const projectId = payload.agentId as string | undefined
    if (!projectId) return { error: 'MISSING_AGENT_ID' }
    const s = resolve(projectId)
    // An agent whose engine has not reported a session yet has no transcript to list. Saying so
    // plainly beats inventing one: the web then shows the tab with an empty thread until the bind
    // lands, instead of pinning `currentSessionId` to an id no event will ever carry.
    if (!s || !s.sessionId) return { sessions: [] }
    // Counted from an index kept as the file grows (lib/transcriptPages.ts), not by reading it whole.
    const messageCount = s.transcriptPath ? await pages.lineCount(s.transcriptPath) : 0
    return {
      sessions: [{
        id: s.sessionId,
        title: projectDisplayName(s),
        timestamp: new Date(s.registeredAt).toISOString(),
        messageCount,
        lastActivity: new Date(await lastActivityAt(s)).toISOString(),
        participants: [],
      }],
    }
  }

  return { sessionGet, sessionsList }
}