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.

13.6 KB
Raw Blame
/**
 * The event funnel: the one place a session's live events fan out from, to the app, search, input, the
 * device's input, the device service, the heartbeat, the question watcher and the recaps. The
 * order is exact and it matters: per event, the frame goes to the app before anything acts on it; the
 * recaps hear the whole batch after the loop; the device stream comes last and never on a replay.
 *
 * Until the core has built what the funnel feeds, events wait: a hook can register a session the instant
 * the hook server binds. `arm` installs the funnel and delivers what waited, in order. `emit` is the same
 * function before and after, so whoever holds it keeps a working funnel.
 *
 * Moved verbatim out of `runForeground` (the core boundary, step 8: docs/design/2026-10-03-harnessd.md).
 */
import { withoutOutputTail } from '../../lib/cardUpdate.js'
import { correlateAgentEvent } from '../../lib/agentEvent.js'
import type { AutonomousDeviceInput } from '../deviceInput.js'
import { isDeviceInputBoundary } from '../deviceInput.js'
import type { SubmissionReader } from '../../lib/submissionReader.js'
import type { WifiFeed } from '../wifi.js'
import type { TurnRecaps } from './recaps.js'
import type { ShortTurnGuard } from './shortTurnGuard.js'
import { deviceErrorText } from '../cardText.js'
import { preview, sid } from '../../lib/log.js'
import type { CursorNormalizer } from '../../engines/cursor/normalizer.js'
import type { QuestionWatcher } from '../../lib/questionController.js'
import type { RegisteredSession } from '../../lib/registry.js'
import type { SessionInputController } from '../../lib/sessionInput.js'
import { promptLine } from '../../lib/activitySummary.js'
import { isProgressEvent, type TurnActivity } from '../../lib/turnActivity.js'

type Events = ReturnType<CursorNormalizer['ingest']>
type EmitOptions = { resumed?: boolean; replay?: boolean }
type Frame = { type: string; agentId?: string; dbSessionId?: string; payload: Record<string, unknown> }

export interface FunnelClients {
  /** The app. */
  send(frame: Frame): void
  /** The dial. */
  sendCommander(frame: Frame): void
}

/** What the funnel feeds, built by the time it is armed. */
export interface FunnelDeps {
  bySession: (sessionId: string) => RegisteredSession | undefined
  tokenUsage: { changed(target: RegisteredSession): void }
  agentIdFor: (sessionId: string) => string
  turnActivity: Pick<TurnActivity, 'observe' | 'snapshot'>
  isSubagentSession: (sessionId: string) => boolean
  clients: Pick<FunnelClients, 'send'>
  search: { touch(sessionId: string): void } | null | undefined
  turnStartedAt: Map<string, number>
  /** The prompt of each agent's last turn start, by agent, for the one-line summary of what it does (turns/summaries.ts).
   *  Not cleared when the turn ends: an idle agent with no recap is summarised by its last prompt. */
  prompts?: Map<string, string>
  input: Pick<SessionInputController, 'onTurnStarted' | 'onTurnEnded'>
  deviceInput: Pick<AutonomousDeviceInput, 'onTurnStarted' | 'onTurnEnded'>
  /** Which engines take a message typed mid-turn into their own queue (their declared submission policy). */
  submission: Pick<SubmissionReader, 'policy'>
  device: () => Pick<WifiFeed, 'turnStarted' | 'turnEnded' | 'stream'> | undefined
  startHeartbeat: (sessionId: string) => void
  questionWatcher: Pick<QuestionWatcher, 'start' | 'noteTurnStart' | 'stop'>
  mirror: Pick<TurnRecaps, 'ingest'>
  /** On-demand, bounded native prompt/answer observers. No consumer is awaited. */
  nativeTurns?: { ingest(agentId: string, events: readonly Events[number][], replay: boolean): void }
  /** How a consumer outside the core is called ([outsideConsumers]). */
  outside?: OutsideConsumers
  /** The agent's engine is working now: a live turn start or its progress, never a re-read (the mover's quiet clock,
   *  lib/hostMove/quiet.ts). */
  working?: (agentId: string) => void
  /** Each live turn's start and end, never a re-read: the short-turn guard holds automatic input to an agent that
   *  loops (shortTurnGuard.ts). */
  shortTurns?: Pick<ShortTurnGuard, 'started' | 'ended'>
}

type OutsideConsumers = (consumer: string, call: () => void) => void

/**
 * A consumer outside the core — the device service — answers for itself: one that
 * throws is logged, at most once a minute per consumer and with how many were not, and every consumer
 * after it still gets the event. The heartbeat, the question watcher and the recaps must not miss a
 * turn because a device was unplugged mid-call. The services on the boundary are guarded the same way
 * (core/serviceHost.ts), and so are the dial and the window bridges on the local socket (cli.ts).
 */
export function outsideConsumers(options: {
  log?: (line: string) => void
  now?: () => number
  /** What the lines start with: `[funnel]` by default. */
  prefix?: string
  /** Consumers to fail on every call, for the end-to-end suite only (`HARNESSD_TEST_FAULTS`). */
  faults?: ReadonlySet<string>
} = {}): OutsideConsumers {
  const log = options.log ?? ((line: string) => console.error(line))
  const now = options.now ?? Date.now
  const prefix = options.prefix ?? 'funnel'
  const said = new Map<string, { at: number; quiet: number }>()
  return (consumer, call) => {
    try {
      if (options.faults?.has(consumer)) throw new Error(`injected fault: ${consumer}`)
      call()
    } catch (error) {
      const at = now()
      const last = said.get(consumer)
      if (last && at - last.at < 60_000) { last.quiet++; return }
      log(`[${prefix}] ${consumer} failed · ${error instanceof Error ? error.message : String(error)}${last?.quiet ? ` · ${last.quiet} more since` : ''}`)
      said.set(consumer, { at, quiet: 0 })
    }
  }
}

/** The funnel itself, over what it feeds. */
export function funnelFor({
  bySession, tokenUsage, agentIdFor, turnActivity, isSubagentSession, clients, search, turnStartedAt, prompts, input,
  deviceInput, submission, device, startHeartbeat, questionWatcher, mirror, nativeTurns, outside = outsideConsumers(), working, shortTurns,
}: FunnelDeps) {
  return (sessionId: string, events: Events, opts?: EmitOptions): void => {
    if (!events.length || !bySession(sessionId)?.active) return
    const usageSession = bySession(sessionId)
    if (usageSession?.engine === 'opencode') tokenUsage.changed(usageSession)
    for (const [eventIndex, event] of events.entries()) {
      const agentId = agentIdFor(sessionId)
      const replay = !!(opts?.resumed || opts?.replay)
      turnActivity.observe(sessionId, event.type, replay)
      if (!replay && isProgressEvent(event.type)) working?.(agentId)
      if (!replay && event.type === 'turn_started') shortTurns?.started(sessionId, agentId)
      else if (!replay && event.type === 'turn_ended') shortTurns?.ended(sessionId)
      const frame = correlateAgentEvent({ ...event, payload: { ...event.payload, activity: turnActivity.snapshot(sessionId) } }, sessionId, agentId)
      // A `turn_started` that is not a turn starting NOW — a turn picked back up at attach, or a prompt
      // re-read from a transcript that was already on disk — says so in the clear, beside `agentId`
      // (the payload is E2EE; the backend can only read the envelope). The backend's daily turn count
      // skips these; every other consumer ignores an unknown field. Measured before this existed: one
      // agent credited with 42 turns in a single second, all re-reads.
      if (replay) { frame.replay = true; frame.payload.replay = true }
      // The end of a turn carries the two facts an app needs to decide whether it is NEWS, in the clear
      // beside `agentId` for the same reason `replay` is — the payload is E2EE and the apps read this
      // without opening it:
      //   `replay`   — a turn re-read from disk, not one finishing now;
      //   `subagent` — a specialist's turn nobody asked to hear about, the dial's `silent`. The dial has
      //                always been told and the window never was, so an Orchestrator project of four
      //                specialists put ONE row on the dial and FIVE marks in the window. Same predicate
      //                for every screen now — see isSubagentSession.
      // The phone notifies on neither. Absent = false, so a client that predates these reads every end as
      // it always did.
      if (event.type === 'turn_ended') {
        if (opts?.resumed || opts?.replay) frame.replay = true
        if (isSubagentSession(sessionId)) frame.subagent = true
      }
      clients.send(withoutOutputTail(frame))
      if (event.type === 'turn_started' || event.type === 'turn_ended') search?.touch(sessionId)
      if (event.type === 'turn_started') {
        turnStartedAt.set(sessionId, Date.now())
        const line = promptLine(event.payload.userMessage)
        if (line) prompts?.set(agentId, line)
        else prompts?.delete(agentId)
        console.log(`[turn] ${sid(sessionId)} started · engine=${bySession(sessionId)?.engine ?? 'claude'} · bytes=${Buffer.byteLength(event.payload.userMessage, 'utf8')}`)
        input.onTurnStarted(agentIdFor(sessionId), event.payload.userMessage)
        deviceInput.onTurnStarted(agentId, event.payload.userMessage)
        outside('devices', () => device()?.turnStarted(agentId))
        startHeartbeat(sessionId)
        questionWatcher.start(sessionId)   // Claude opens its dialog INSIDE a turn
        // ...and anything already drawn belongs to the turn BEFORE this one — unless this is a turn the
        // daemon is picking back up at attach: a dialog on the pane then is THIS turn's, still waiting,
        // and marking it pre-turn is how a restarted daemon never announced a question Codex had open.
        if (!opts?.resumed) questionWatcher.noteTurnStart(sessionId)
      } else if (event.type === 'turn_ended') {
        const startedAt = turnStartedAt.get(sessionId)
        turnStartedAt.delete(sessionId)
        // Say when a turn was KILLED. The log previously showed an interrupt as a fresh `[turn] started
        // "[Request interrupted by user]"`, which read like a new prompt and hid the bug for weeks.
        console.log(
          `[turn] ${sid(sessionId)} ended${event.payload.aborted ? ' · aborted (interrupted)' : ''}` +
            `${startedAt ? ` · ${Date.now() - startedAt}ms` : ''}`,
        )
        // Filter only the Device receipt view; shared normalizers, mirror, and local input stay unchanged.
        if (!isDeviceInputBoundary(submission.policy(usageSession?.engine ?? ''), events, eventIndex)) {
          outside('devices', () => device()?.turnEnded(agentId, event.payload.aborted === true))
          deviceInput.onTurnEnded(agentId)
        }
        input.onTurnEnded(agentIdFor(sessionId))
        // Command Code asks AFTER the turn: `ask_user_question` ends the turn (its Stop hook fires), the
        // dialog goes up, and the answer opens a NEW turn. Stopping the watcher here is what left the
        // terminal sitting on a question the device never showed. Its watcher runs off the session, not
        // the turn — see the attach path — so leave it alone.
        if (bySession(sessionId)?.engine !== 'commandcode') questionWatcher.stop(sessionId)
        // Do NOT stop the heartbeat here: the turn is closed but its recap is just being cut (the recaps
        // hear the batch below and say its card is busy). The timer keeps beating for the device's card and
        // stops once mirror.heartbeat() reads it idle, which is at once while the recaps are off.
      }
    }
    if (nativeTurns) outside('native-turns', () => nativeTurns.ingest(agentIdFor(sessionId), events, !!(opts?.resumed || opts?.replay)))
    mirror.ingest(events, sessionId, { replay: !!(opts?.resumed || opts?.replay) })
    // Subscribed devices only (lib/autonomous-device/stream.ts). A transcript re-read is history, not live.
    if (!opts?.replay) outside('devices', () => device()?.stream(agentIdFor(sessionId), events))
  }
}

export function createEventFunnel({ clients, agentIdFor }: { clients: FunnelClients; agentIdFor: (sessionId: string) => string }) {
  const queuedSessionEvents: Array<{ sessionId: string; events: Events; opts?: EmitOptions }> = []
  let funnel: ((sessionId: string, events: Events, opts?: EmitOptions) => void) | null = null
  const emit = (sessionId: string, events: Events, opts?: EmitOptions): void => {
    if (funnel) funnel(sessionId, events, opts)
    else if (events.length) queuedSessionEvents.push({ sessionId, events, opts })
  }
  /** Install the funnel and deliver what waited for it, in order. */
  const arm = (deps: FunnelDeps): void => {
    funnel = funnelFor(deps)
    for (const queued of queuedSessionEvents.splice(0)) funnel(queued.sessionId, queued.events, queued.opts)
  }
  /**
   * A turn died inside the engine instead of finishing. Neither devin nor commandcode has a StopFailure
   * hook, so nothing else would tell the clients: the web would sit on the typing indicator and the
   * device tile would stay "Working…". Surface the failure to both; the CALLER closes the turn (the devin
   * reader and the commandcode normalizer each own their own turn state).
   */
  const announceTurnAborted = (
    sessionId: string,
    engine: string,
    message: string,
    deviceMessage = message,
  ): void => {
    console.log(`[turn] ${sid(sessionId)} aborted by ${engine} error · ${preview(message)}`)
    clients.send({ type: 'error', agentId: agentIdFor(sessionId), dbSessionId: sessionId, payload: { message } })
    clients.sendCommander({
      type: 'commander_event',
      agentId: agentIdFor(sessionId),
      dbSessionId: sessionId,
      payload: { kind: 'error', text: deviceErrorText(deviceMessage, engine) },
    })
  }
  return { emit, arm, announceTurnAborted }
}

export type EventFunnel = ReturnType<typeof createEventFunnel>