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.

20.4 KB
Raw Blame
/**
 * Agent Messages' deliveries to this machine's own agents (docs/design/2026-10-10-agent-messages.md,
 * "Delivery"). Each waits until it is delivered; none expires. Two routes race for it, decided by one rename
 * in the pane's inbox (inbox.ts):
 * 1. the messages hook takes it at the agent's next tool call (engines/kit/messagesHook.ts), while it works;
 * 2. the core types it into an idle agent: a team delivery (`team:` id), written only into an empty composer,
 *    never over a draft, a dialog or a running turn (engines/kit/screen.ts `teamHold`), and never twice.
 * Before handing the core a typed attempt the mailbox takes the file back from the hook; a refusal that proves
 * nothing was typed gives it back, and the next attempt waits a little longer. A refusal that may have left
 * text in the composer ends the delivery there, its hook copy withdrawn: never delivered twice.
 *
 * An inbox file names the conversation it is for, and the hook delivers it to that conversation only: a pane
 * number tmux gives out again (after a reboot, or to a person's own session) never takes another's message.
 * While its harness is stopped a file is withdrawn, and put back when the harness returns.
 */
import { createHash } from 'node:crypto'
import type { TurnDelivery } from '../core/api.js'
import { isMessageHold } from '../lib/messageHolds.js'
import { TERMINAL_LEASE_REFUSED } from '../lib/terminalTypes.js'
import type { PaneInbox } from './inbox.js'
import { paneNotice, type DeliveryStatus, type Message } from './model.js'
import type { LocalDelivery, MessageStore } from './store.js'

export const PUMP_MS = 2_000
/** The longest wait between typed attempts at an agent that keeps working. */
export const MAX_BACKOFF_MS = 30_000
/** How long a typed attempt the core never acknowledged is waited for before it is taken back: the core says
 *  `queued` as it takes any, so one it never mentioned never reached it. */
export const ATTEMPT_MS = 120_000
/**
 * How long the core may hold a typed attempt it said it queued before the mailbox takes it for one held behind a
 * running turn. The core queues a delivery while the agent's turn is open and writes it only once the turn ends
 * (lib/sessionInput.ts `submit`); one it can write now it writes within seconds, a lease wait and a slow paste
 * included. Found end to end: a message for an agent twenty seconds into a turn sat in the core's queue, out of
 * the hook's reach, and was typed at the end. Long enough that a write in progress is never taken for one.
 */
export const PARK_MS = 20_000
/** How long a parked attempt is left with the core before it is forgotten: the core may have lost it. */
export const PARKED_MAX_MS = 10 * 60_000
/**
 * How long a message waits on a working agent's hook before its reason stops promising the next tool call. An
 * engine reads its hooks as it starts: Codex agents running since before Agent Messages never ran the hook, and
 * every message to their lead read "arrives at its next tool call" for an hour while it polled `harness send`
 * (2026-10-12).
 */
export const HOOKLESS_MS = 10 * 60_000
/** Why news (`harness send --fyi`) waits: it is never typed, so it starts no turn of the agent's. */
export const FYI_REASON = 'news: arrives at its next tool call, or when it reads its messages; it starts no turn'
export const HOOKLESS_REASON = 'working, and no tool call has taken it: it may have started before Agent Messages. '
  + 'It reads its messages with `harness send`; restarting it gives it them at once'
/** How long a finished delivery is kept: its outcome lives on in the history. */
export const FINISHED_KEEP_MS = 24 * 3600_000

/** An agent as the mailbox needs it: where its pane is, which conversation is in it, and whether it runs. */
export interface MailboxAgent { pane: string; session: string; available: boolean }

export interface MailboxDeps {
  store: MessageStore
  inbox: PaneInbox
  agent(agentId: string): MailboxAgent | null
  /** Hand a typed attempt to the core (`core.turns.deliver`). */
  deliver(agentId: string, text: string, deliveryId: string): void
  /** Null while a delivery may still be made; otherwise why it can no longer be (it left the tab, the tab
   *  turned Agent Messages off). */
  refused(delivery: LocalDelivery): string | null
  /** Null while a delivery may be made; otherwise why it waits, given to no one, the hook included: its tab no longer
   *  carries it, for less long than it is held before it is refused. */
  held?(delivery: LocalDelivery): string | null
  /** Whether who may message whom is known yet: until it is, nothing is typed and nothing refused. */
  ready(): boolean
  /** Why a delivery may never be made, whatever the tabs say, or null: asked as the mailbox starts, before the
   *  directory is read and before anything goes back to a hook, which takes what waits in its inbox on its own. */
  forbidden?(delivery: LocalDelivery): string | null
  /** The text an agent reads for a delivery: the message, and the roster note when it is new to the agent. */
  text(delivery: LocalDelivery, message: Message): string
  /** A delivery changed; the store is saved after. */
  changed(status: DeliveryStatus, delivery: LocalDelivery): void
  /** Whether a typed attempt may be written changed: its process tells the core (services/messagesProcess.ts). */
  writable?(): void
  /** Whether Agent Messages sleep here (off, or signed out): then the pump stops once nothing waits. */
  asleep?(): boolean
  now?(): number
}

/** The reasons a refused typed attempt waits, as a person reads them. */
const WAITING: Record<string, string> = {
  team_waiting_idle: 'working: arrives at its next tool call',
  team_waiting_draft: 'someone is typing in its pane',
  team_waiting_user: 'a dialog is open in its pane',
  team_waiting_unavailable: 'its pane is unavailable',
  team_waiting_control: 'waiting to be written',
}

/** Refusals that prove nothing was typed (lib/sessionInput.ts): the attempt goes back to the hook. Any other
 *  (`enter_withheld`: typed, its Enter held back; `paste_failed`: perhaps partly typed) may have left text. */
const NOT_TYPED: ReadonlySet<string> = new Set(['agent_gone', 'runtime_gone_pre_paste', 'queue_full', 'queue_expired', 'cancelled', TERMINAL_LEASE_REFUSED])
const notTyped = (reason: string | undefined): boolean =>
  !!reason && (reason.startsWith('team_waiting_') || NOT_TYPED.has(reason) || isMessageHold(reason))

/** Why a typed message was not sent, for the person: it is in the input box, and Enter in the pane sends it. */
export const WITHHELD = 'typed into its input box but not sent: something opened over it first; press Enter in its pane to send it'

export const deliveryKey = (messageId: string, agentId: string): string =>
  `${messageId}-${createHash('sha256').update(agentId).digest('hex').slice(0, 8)}`

export class Mailbox {
  private timer: ReturnType<typeof setInterval> | null = null
  private started = false
  /** Deliveries held out of the hook's reach while their tab does not carry them ([hold]). */
  private readonly holding = new Set<LocalDelivery>()
  constructor(private readonly deps: MailboxDeps) {}
  private now(): number { return this.deps.now?.() ?? Date.now() }
  private get local(): LocalDelivery[] { return this.deps.store.state.local }

  start(): void {
    if (this.started) return
    this.started = true
    for (const delivery of this.local) {
      const forbidden = delivery.state === 'queued' ? this.deps.forbidden?.(delivery) : null
      if (forbidden) this.fail(delivery, forbidden)
    }
    this.takeBackAttempts()
    // Anything left taken back from a hook goes back to it, unless its delivery is over.
    for (const [pane, key] of this.deps.inbox.reclaimed()) {
      const delivery = this.local.find((d) => d.pane === pane && d.key === key)
      if (delivery?.state === 'queued') this.deps.inbox.restore(pane, key)
      else this.deps.inbox.typed(pane, key)
    }
    // Finished deliveries are only kept a day: their outcome is in the history.
    this.deps.store.state.local = this.local.filter((d) => d.state === 'queued' || this.now() - d.at < FINISHED_KEEP_MS)
    this.save()
    this.resume()
  }

  stop(): void {
    this.pause()
  }

  /**
   * Look every PUMP_MS from now on, unless it already does: while Agent Messages are on, and while they sleep with a
   * delivery still waiting here, which the pump holds out of the hook's reach and fails once it has waited
   * HELD_OUTSIDE_MS (messages/service.ts). Then it stops by itself.
   */
  resume(): void {
    if (!this.started || this.timer) return
    this.timer = setInterval(() => {
      try { this.pump() } catch { /* the next pump looks again */ }
      // Off costs nothing: once what waited has settled, nothing is looked at until Agent Messages wake.
      if (this.deps.asleep?.() && !this.waiting()) this.pause()
    }, PUMP_MS)
    this.timer.unref?.()
  }

  /** Look no more until resumed: Agent Messages sleep, with nothing here to settle or no account to settle it by. */
  pause(): void {
    if (this.timer) clearInterval(this.timer)
    this.timer = null
  }

  /** Whether any delivery here still waits to be delivered or failed. */
  waiting(): boolean {
    return this.local.some((d) => d.state === 'queued')
  }

  /**
   * Forget every typed attempt in flight, giving its message back to the hook: as the service starts, and when
   * it reaches a new core, which holds none of them (an update restarts the core, not this process). Whatever
   * the old core still holds it may no longer write: none is writable now.
   */
  takeBackAttempts(): void {
    let any = false
    for (const delivery of this.local) {
      if (delivery.state !== 'queued' || !delivery.attempt) continue
      if (!delivery.attempt.parked && delivery.pane) this.deps.inbox.restore(delivery.pane, delivery.key)
      delivery.attempt = undefined
      delivery.nextTryAt = this.now()
      any = true
    }
    if (any) { this.save(); this.deps.writable?.() }
  }

  /** A message for one of this machine's agents: it waits in the agent's inbox from now on. */
  accept(message: Message, agentId: string): LocalDelivery {
    const key = deliveryKey(message.id, agentId)
    const known = this.local.find((d) => d.key === key)
    if (known) return known
    const delivery: LocalDelivery = { key, messageId: message.id, agentId, pane: '', state: 'queued', tries: 0, nextTryAt: this.now(), at: this.now() }
    this.local.push(delivery)
    this.save()
    this.pump()
    return delivery
  }

  /** Whether the core may write a typed attempt now: only the current attempt of a delivery still waiting, and
   *  not one parked behind a turn, which the hook has again. */
  canWrite(deliveryId: string): boolean {
    return this.local.some((d) => d.state === 'queued' && d.attempt?.id === deliveryId && !d.attempt.parked)
  }

  /** What the core says became of a typed attempt. */
  observe(event: TurnDelivery): void {
    const delivery = this.local.find((d) => d.attempt?.id === event.deliveryId)
    if (!delivery || delivery.state !== 'queued') return
    const attempt = delivery.attempt!
    if (event.state === 'queued') {
      attempt.queuedAt ??= this.now()
      return this.save()
    }
    if (event.state === 'delivered' || event.state === 'started') return this.finish(delivery, 'prompt')
    // It may have reached the engine: never typed again.
    if (event.state === 'unknown') return this.finish(delivery, 'prompt', 'unconfirmed: inspect its pane')
    // Typed, its Enter held back: the text waits in the agent's input box, unread, so it is not called delivered.
    // Its sender saw "delivered" while a Codex agent never read it (a fresh Mac, 2026-10-12).
    if (event.reason === 'enter_withheld') return this.fail(delivery, WITHHELD)
    if (!notTyped(event.reason)) return this.finish(delivery, 'prompt', 'unconfirmed: inspect its pane')
    // Refused before anything was written: back to the hook, and the next attempt waits longer. A parked one is
    // the hook's already, and its turn has ended: the next attempt finds the agent idle.
    delivery.attempt = undefined
    delivery.nextTryAt = this.now() + (attempt.parked ? 0 : Math.min(MAX_BACKOFF_MS, PUMP_MS * 2 ** Math.min(delivery.tries, 4)))
    if (!attempt.parked) this.deps.inbox.restore(delivery.pane, delivery.key)
    this.report(delivery, event.reason === 'team_waiting_idle' ? this.idleReason(delivery) : WAITING[event.reason ?? ''] ?? event.reason ?? 'waiting')
    this.save()
  }

  /** Look at every delivery still waiting: taken by the hook, refused, moved, stopped, or due a typed attempt. */
  pump(): void {
    // Each folder read once per look, however many deliveries wait: hundreds may.
    const taken = this.deps.inbox.claimedNames()
    const panes = new Map<string, Set<string>>()
    const waiting = (pane: string, key: string): boolean => {
      if (!panes.has(pane)) panes.set(pane, this.deps.inbox.keys(pane))
      return panes.get(pane)!.has(key)
    }
    for (const delivery of this.local) {
      if (delivery.state !== 'queued') continue
      if (delivery.reason === WAITING.team_waiting_idle) this.report(delivery, this.idleReason(delivery))
      if (delivery.pane && taken.has(this.deps.inbox.claimName(delivery.pane, delivery.key) ?? '') && this.deps.inbox.claimed(delivery.pane, delivery.key)) { this.finish(delivery, 'hook'); continue }
      if (delivery.attempt) {
        // A parked attempt is back in the hook's inbox: where its tab no longer carries it, the hook must not take it.
        if (!delivery.attempt.parked || !this.outside(delivery)) { this.watch(delivery); continue }
        delivery.attempt = undefined
      }
      if (!this.deps.ready()) continue
      const refused = this.deps.refused(delivery)
      if (refused) { this.fail(delivery, refused); continue }
      const held = this.deps.held?.(delivery)
      if (held) { this.hold(delivery, held); continue }
      const agent = this.deps.agent(delivery.agentId)
      const message = this.deps.store.entry(delivery.messageId)?.message
      if (!message) { this.fail(delivery, 'the message is no longer kept'); continue }
      if (!agent?.available || !agent.pane) {
        // Withdrawn while its harness is stopped: its pane number may be another's by the time it is back.
        if (delivery.pane) { this.deps.inbox.withdraw(delivery.pane, delivery.key); delivery.pane = ''; this.save() }
        this.report(delivery, 'its harness is stopped')
        continue
      }
      // A harness restarted in another pane, or into another conversation: its inbox file follows it.
      if (agent.pane !== delivery.pane || agent.session !== (delivery.session ?? '') || !waiting(delivery.pane, delivery.key)) {
        if (delivery.pane && agent.pane !== delivery.pane) this.deps.inbox.withdraw(delivery.pane, delivery.key)
        delivery.pane = agent.pane
        delivery.session = agent.session
        this.put(delivery, message, agent)
        const wasHeld = this.holding.delete(delivery)
        if (wasHeld || delivery.reason === 'its harness is stopped') this.report(delivery, undefined)
        this.save()
      }
      // News waits for the hook, or for the agent to read it: typed, it would start a turn of its own.
      if (message.fyi) { this.report(delivery, FYI_REASON); continue }
      if (this.now() < delivery.nextTryAt) continue
      if (!this.deps.inbox.reclaim(delivery.pane, delivery.key)) continue
      delivery.tries += 1
      delivery.attempt = { id: `team:msg:${delivery.key}:${delivery.tries}`, at: this.now() }
      this.save()
      this.deps.deliver(delivery.agentId, this.deps.text(delivery, message), delivery.attempt.id)
    }
  }

  /** Withdraw what waits for an agent's messages in a tab that turned off, or that it left: held for a while, then
   *  refused. */
  refuseAll(): void {
    if (!this.deps.ready()) return
    for (const delivery of this.local) {
      if (delivery.state !== 'queued' || (delivery.attempt && !delivery.attempt.parked)) continue
      const refused = this.deps.refused(delivery)
      const held = refused ? null : this.deps.held?.(delivery)
      if (refused || held) delivery.attempt = undefined
      if (refused) this.fail(delivery, refused)
      else if (held) this.hold(delivery, held)
    }
  }

  /** Whether the tabs no longer carry a delivery, for now or for good. */
  private outside(delivery: LocalDelivery): boolean {
    return this.deps.ready() && Boolean(this.deps.refused(delivery) || this.deps.held?.(delivery))
  }

  /** Its tab does not carry it, for now: out of the hook's reach, given to no one, and put back once it is carried
   *  again (the pump puts what is missing from the inbox). */
  private hold(delivery: LocalDelivery, reason: string): void {
    this.holding.add(delivery)
    if (delivery.pane && this.deps.inbox.waiting(delivery.pane, delivery.key)) { this.deps.inbox.withdraw(delivery.pane, delivery.key); this.save() }
    this.report(delivery, reason)
  }

  /** A typed attempt in flight: parked once the core has held it behind a turn, forgotten when the core never
   *  took it or kept it too long. */
  private watch(delivery: LocalDelivery): void {
    const attempt = delivery.attempt!
    const now = this.now()
    if (!attempt.parked && attempt.queuedAt !== undefined && now - attempt.queuedAt >= PARK_MS) {
      attempt.parked = true
      attempt.parkedAt = now
      this.deps.inbox.restore(delivery.pane, delivery.key)
      this.report(delivery, this.idleReason(delivery))
      this.save()
      this.deps.writable?.()
    } else if ((attempt.parked && now - (attempt.parkedAt ?? now) > PARKED_MAX_MS)
      || (!attempt.parked && attempt.queuedAt === undefined && now - (attempt.at ?? now) > ATTEMPT_MS)) {
      // Never acknowledged, or held too long: the core lost it, or will be refused if it asks. The hook has it.
      if (!attempt.parked) this.deps.inbox.restore(delivery.pane, delivery.key)
      delivery.attempt = undefined
      delivery.nextTryAt = now
      this.save()
      this.deps.writable?.()
    }
  }

  /**
   * The agent read what waits for it (`harness send` alone): each of [messageIds] it was not given yet is
   * delivered, its inbox file withdrawn, so neither its hook nor a typed prompt gives it again. One being typed
   * this moment is left to that attempt. Answers the ids it marked.
   */
  read(agentId: string, messageIds: readonly string[]): string[] {
    const wanted = new Set(messageIds)
    const marked: string[] = []
    for (const delivery of this.local) {
      if (delivery.state !== 'queued' || delivery.agentId !== agentId || !wanted.has(delivery.messageId)) continue
      if (delivery.attempt && !delivery.attempt.parked) continue
      this.finish(delivery, 'read')
      marked.push(delivery.messageId)
    }
    return marked
  }

  /** Why a message waits for a working agent: its next tool call, until that has not come for a long while. */
  private idleReason(delivery: LocalDelivery): string {
    return this.now() - delivery.at >= HOOKLESS_MS ? HOOKLESS_REASON : WAITING.team_waiting_idle
  }

  private put(delivery: LocalDelivery, message: Message, agent: MailboxAgent): void {
    try { this.deps.inbox.put(agent.pane, delivery.key, { session: agent.session, text: this.deps.text(delivery, message), notice: paneNotice(message) }) }
    catch { /* the next pump puts it again */ }
  }

  private finish(delivery: LocalDelivery, via: 'hook' | 'prompt' | 'read', reason?: string): void {
    delivery.state = 'delivered'
    delivery.via = via
    delivery.reason = reason
    delivery.attempt = undefined
    delivery.at = this.now()
    // Delivered one way: whatever copy the other way still holds goes.
    if (delivery.pane) this.deps.inbox.withdraw(delivery.pane, delivery.key)
    this.deps.changed(this.status(delivery), delivery)
    this.save()
  }

  private fail(delivery: LocalDelivery, reason: string): void {
    delivery.state = 'failed'
    delivery.reason = reason
    delivery.at = this.now()
    if (delivery.pane) this.deps.inbox.withdraw(delivery.pane, delivery.key)
    this.deps.changed(this.status(delivery), delivery)
    this.save()
  }

  /** Say why a delivery waits, when that changed. */
  private report(delivery: LocalDelivery, reason?: string): void {
    if (delivery.reason === reason) return
    delivery.reason = reason
    this.deps.changed(this.status(delivery), delivery)
  }

  private status(delivery: LocalDelivery): DeliveryStatus {
    return { messageId: delivery.messageId, machineId: '', agentId: delivery.agentId, state: delivery.state,
      ...(delivery.via ? { via: delivery.via } : {}), ...(delivery.reason ? { reason: delivery.reason } : {}), at: this.now() }
  }

  private save(): void {
    try { this.deps.store.save() } catch { /* kept in memory; the next change saves again */ }
  }
}