Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

23.9 KB
Raw Blame
/**
 * The core half of @shared/station-outcome: what each station last REPORTED about its task, and the
 * `report-outcome` verb that records it. ONE module for both shells — desktop main and the Server
 * Edition both answer the verb here and both register the read channel — so the two cannot come to
 * accept different reports or keep them differently.
 *
 * DURABLE ACROSS A RESTART (it used to be transient, so after an app restart every
 * `--after-success` dependent read BLOCKED and needed ▶ / `run`). Held in MAIN rather than the
 * renderer so a renderer reload (⌘R, a Server Edition browser tab closing) does not lose it — the
 * station-notice monitor learned that lesson with its DROPPED verdict — and mirrored to
 * `<userData>/orchestration-state/station-outcomes.json` (`OUTCOME_FACT`) so an app restart does not
 * either. What a restart means for a report:
 *   - it comes back as it was, BOUND to the session that made it: `record` stores the station's
 *     agent and session id (`sessionOf`, the status mirror). At load, a report whose recorded
 *     session or agent differs from what the (restored) mirror now says for that node is dropped —
 *     the node id now belongs to another conversation, and its word is not this one's;
 *   - and afterwards: a `SessionStart` from the node naming a DIFFERENT session or agent than the
 *     one a report is bound to withdraws it (`onAgentEvent`). That also holds in-run — a report is
 *     about a task in one conversation, and `/clear`, a respawn or another agent in the pane is a
 *     different one. It errs toward holding, like every rule here. A report with no recorded
 *     session (its station never named one) is kept: there is nothing to compare;
 *   - "work pending" is NOT stored: it is rebuilt from the durable delivery queue, whose restore
 *     replays a `queued` hand-over for every message still waiting (delivery-queue.ts). A message
 *     that lapsed while the app was down is then settled without landing, which withdraws the report
 *     exactly as an in-run expiry does;
 *   - a report whose station was CLOSED keeps counting for the dependents it already had (the
 *     deleted-station rule, `evaluateSuccessDep`) — across a restart now too.
 * A crash inside the save window loses that window; a clean quit flushes synchronously.
 *
 * WHEN A REPORT ENDS (the "new task" rule):
 *   - the station reports again — the later report supersedes;
 *   - the station is handed new work THROUGH CANVAS CONTROL. That is how an orchestrator reuses a
 *     station, and without it "hand the station its next task, then open a dependent
 *     `--after-success` on it" would release that dependent at once on the PREVIOUS task's success —
 *     early, the direction nothing can undo. It is decided by WHEN THE WORK REACHES THE PANE, never
 *     by when a control answer comes back (the answer to a queued message comes back long before):
 *       · a `send` / `reply` that is QUEUED for a busy station marks it WORK PENDING
 *         (`onHandover` 'queued'): every report it makes stops counting — including the one it is
 *         about to make for the task it is still on — until the message lands;
 *       · when the bytes LAND (first attempt or flush), every report made before that delivery
 *         STARTED is withdrawn; a report made after it (about the new work) stands, however late
 *         the answer arrives;
 *       · a queued message that ends WITHOUT landing (expired, refused on flush) withdraws the
 *         report too. The orchestrator handed new work and was told it did not arrive; a dependent it
 *         armed after that hand-over must not start on the older task's word;
 *       · `write` / `run` (typed straight into the pane after its confirm, or a held launch started)
 *         withdraw every report older than their answer, which is when the bytes landed;
 *     Every one of these errs toward holding, which the deadline and ▶ / `run` can always end;
 *   - NOT a new turn. A turn is not a task: a station may report mid-turn and keep summarising, and
 *     a person typing "thanks" into its pane starts a turn without starting a task. nodeterm cannot
 *     tell a new task from a follow-up by looking at a turn, so a turn changes nothing here; the
 *     skill tells every station to report at the end of every task, which supersedes the old one;
 *   - NOT the station being closed. A closed station's success still counts for the dependents it
 *     already had (`evaluateSuccessDep`): closing finished stations is ordinary tidying.
 * The store is bounded, oldest evicted first, so a long session cannot grow it without limit.
 */
import type { BoardLogEntry } from '../shared/types'
import { IPC } from '../shared/ipc'
import { isSafeNodeId } from '../shared/safe-id'
import {
  REPORT_OUTCOME_CONTROL_REFUSAL,
  parseReportOutcome,
  sanitizeOutcomeRecords,
  type StationOutcome,
  type StationOutcomeRecord
} from '../shared/station-outcome'
import type { CorePlatform } from './platform'
import type { MessageHandover } from './agents/agent-messaging'
import type { AgentMessageOutcome } from './agents/agent-message-decide'
import { paneResult } from './agents/station-notice'
import { stationOutcomeNoticeBody, type StationRecipient } from '../shared/station-notice'
import type { DurableFactFile, DurableFactSpec } from './durable-state'

/** Which conversation a report was made in. */
export interface OutcomeBinding {
  sessionId?: string
  agentId?: string
}

/** One report as it is written to disk: the published record plus its binding. */
export interface PersistedOutcome {
  nodeId: string
  outcome: StationOutcome
  note?: string
  at: number
  sessionId?: string
  agentId?: string
}

/** Re-check one report read from disk (hand-editable input). `null` drops it. The note is re-run
 *  through the SAME sanitizer a live report takes (`sanitizeOutcomeRecords`). */
export function sanitizePersistedOutcome(raw: unknown): PersistedOutcome | null {
  const [rec] = sanitizeOutcomeRecords([raw])
  if (!rec) return null
  const r = raw as Record<string, unknown>
  const out: PersistedOutcome = {
    nodeId: rec.nodeId,
    outcome: rec.outcome,
    at: rec.at,
    ...(rec.note ? { note: rec.note } : {})
  }
  for (const k of ['sessionId', 'agentId'] as const) {
    const v = r[k]
    if (v === undefined) continue
    if (typeof v !== 'string' || v.length === 0 || v.length > 200) return null
    out[k] = v
  }
  return out
}

/** Would a report bound to `recorded` still speak for a node now in `current`? Unknown on either
 *  side keeps it — only a VISIBLE difference drops it. */
export function sameConversation(recorded: OutcomeBinding, current: OutcomeBinding | undefined): boolean {
  if (!current) return true
  if (recorded.sessionId && current.sessionId && recorded.sessionId !== current.sessionId) return false
  if (recorded.agentId && current.agentId && recorded.agentId !== current.agentId) return false
  return true
}

export interface StationOutcomeStoreOptions {
  /** Mirror every change to disk and load from it at construction. */
  durable?: Pick<DurableFactFile<PersistedOutcome>, 'load' | 'save'>
  /** The node's current agent and session (the status mirror). Recorded with a report and compared
   *  at load. Absent ⇒ reports carry no binding. */
  sessionOf?(nodeId: string): OutcomeBinding | undefined
}

/** How many stations' reports one process keeps. Far past any canvas; evicts the oldest first. */
export const STATION_OUTCOME_MAX_RECORDS = 1000

/** The author of the board-log line — the app, like every other trace it writes. */
const OUTCOME_AUTHOR = { name: 'nodeterm', color: '#8b8b8b' } as const

export class StationOutcomeStore {
  // Insertion order IS recency: a record is deleted and re-set on every write, so the first key is
  // always the oldest and eviction is one `keys().next()`.
  private readonly byId = new Map<string, StationOutcomeRecord>()
  /** Stations with a `send`/`reply` still QUEUED for them, and how many. While a station is here its
   *  report does not count (`workPending` on the published record). Every entry is removed by the
   *  queue's own `settled` event — the queue guarantees one per `queued`. */
  private readonly pending = new Map<string, number>()
  /** Which conversation each report was made in (persisted beside it, never published). */
  private readonly bindings = new Map<string, OutcomeBinding>()
  /** The outcome the station's OPENER last heard through `--notify-opener` (#1356), kept while the
   *  report it was about stands. Not the report itself: a report made without the flag, or whose
   *  notice could not be sent, told the opener nothing — so "already told" is read from here, never
   *  from `byId`. Process-local like the Server Edition's creator ledger (never persisted). */
  private readonly openerHeard = new Map<string, StationOutcome>()
  private readonly durable: StationOutcomeStoreOptions['durable']
  private readonly sessionOf: StationOutcomeStoreOptions['sessionOf']

  /** `publish` gets the FULL list after every change (never a delta), like station notices. */
  constructor(
    private readonly publish: (records: StationOutcomeRecord[]) => void = () => {},
    opts: StationOutcomeStoreOptions = {}
  ) {
    this.durable = opts.durable
    this.sessionOf = opts.sessionOf
  }

  /**
   * Load what an earlier process saved (see the header). A shell calls it ONCE at boot, AFTER the
   * status mirror is restored (the binding check reads it) and BEFORE the delivery queue is
   * restored (whose replayed hand-overs act on these reports). Reports already recorded in this
   * run win. Never throws: the file layer turns a bad file into an empty list.
   */
  loadFromDisk(): void {
    if (!this.durable) return
    let dropped = false
    for (const p of this.durable.load()) {
      const binding: OutcomeBinding = {
        ...(p.sessionId ? { sessionId: p.sessionId } : {}),
        ...(p.agentId ? { agentId: p.agentId } : {})
      }
      if (!sameConversation(binding, this.sessionOf?.(p.nodeId))) {
        dropped = true
        continue
      }
      if (this.byId.has(p.nodeId)) continue
      this.byId.set(p.nodeId, {
        nodeId: p.nodeId,
        outcome: p.outcome,
        at: p.at,
        ...(p.note ? { note: p.note } : {})
      })
      this.bindings.set(p.nodeId, binding)
    }
    this.evict()
    if (dropped) this.persist()
    this.publish(this.list())
  }

  record(rec: StationOutcomeRecord): void {
    this.byId.delete(rec.nodeId)
    this.byId.set(rec.nodeId, rec)
    const b = this.sessionOf?.(rec.nodeId)
    this.bindings.set(rec.nodeId, {
      ...(b?.sessionId ? { sessionId: b.sessionId } : {}),
      ...(b?.agentId ? { agentId: b.agentId } : {})
    })
    this.evict()
    this.changed()
  }

  /** Withdraw a station's report. `true` when there was one. */
  clear(nodeId: string): boolean {
    if (!this.drop(nodeId)) return false
    this.changed()
    return true
  }

  /** Every way a report leaves the store goes through here, so what the opener heard about it
   *  leaves with it: the next report after new work is a new task, and it notifies again. */
  private drop(nodeId: string): boolean {
    this.openerHeard.delete(nodeId)
    this.bindings.delete(nodeId)
    return this.byId.delete(nodeId)
  }

  /** `--notify-opener`: the outcome the opener last heard about this station's standing report, or
   *  `undefined` when it heard nothing (no flag yet, notice not sent, report withdrawn since). */
  openerHeardOutcome(nodeId: string): StationOutcome | undefined {
    return this.openerHeard.get(nodeId)
  }

  /** The opener was told (delivered, or queued for its next idle) this outcome. Only for a station
   *  whose report stands — a notice about a withdrawn report is not knowledge of the next one. */
  markOpenerHeard(nodeId: string, outcome: StationOutcome): void {
    if (this.byId.has(nodeId)) this.openerHeard.set(nodeId, outcome)
  }

  /**
   * One normalized agent event. Only a session START matters: a node that begins a DIFFERENT
   * session (or now runs a different agent) than the one its report was made in no longer speaks
   * with that report's voice — withdraw it. Any other event, and a start naming no session, changes
   * nothing (a subagent's stop can name the child's session; only a start is the node's own).
   */
  onAgentEvent(e: {
    nodeId?: string
    sessionPhase?: string
    sessionId?: string
    agentId?: string
    subagentType?: string
  }): void {
    // A child's own session events (grok) name the CHILD's session, never the node's.
    if (!e?.nodeId || e.sessionPhase !== 'start' || e.subagentType) return
    const binding = this.bindings.get(e.nodeId)
    if (!binding || !this.byId.has(e.nodeId)) return
    const current: OutcomeBinding = {
      ...(e.sessionId ? { sessionId: e.sessionId } : {}),
      ...(e.agentId ? { agentId: e.agentId } : {})
    }
    if (!sameConversation(binding, current)) this.clear(e.nodeId)
  }

  private evict(): void {
    while (this.byId.size > STATION_OUTCOME_MAX_RECORDS) {
      const oldest = this.byId.keys().next().value
      if (oldest === undefined) break
      this.drop(oldest)
    }
  }

  private changed(): void {
    this.persist()
    this.publish(this.list())
  }

  private persist(): void {
    if (!this.durable) return
    const out: PersistedOutcome[] = []
    for (const rec of this.byId.values()) {
      const b = this.bindings.get(rec.nodeId)
      out.push({
        nodeId: rec.nodeId,
        outcome: rec.outcome,
        at: rec.at,
        ...(rec.note ? { note: rec.note } : {}),
        ...(b?.sessionId ? { sessionId: b.sessionId } : {}),
        ...(b?.agentId ? { agentId: b.agentId } : {})
      })
    }
    this.durable.save(out)
  }

  /** Withdraw a station's report if it was made BEFORE `at` — new work landed at `at`, so only a
   *  report made after it can be about that work. `true` when one was withdrawn. */
  withdrawBefore(nodeId: string, at: number): boolean {
    const rec = this.byId.get(nodeId)
    if (!rec || rec.at >= at) return false
    return this.clear(nodeId)
  }

  /**
   * The messaging layer's hand-over events (`AgentMessagingDeps.onHandover`). Only `send` and
   * `reply` count: a board comment is a person steering (like typing in the pane), and a station
   * notice is the app telling an orchestrator something — neither is a task handed to a station.
   */
  onHandover(ev: MessageHandover): void {
    if (!HANDOVER_VERBS.has(ev.verb) || !isSafeNodeId(ev.targetNodeId)) return
    const id = ev.targetNodeId
    if (ev.phase === 'queued') {
      this.pending.set(id, (this.pending.get(id) ?? 0) + 1)
      this.publish(this.list())
      return
    }
    if (ev.phase === 'landed') {
      this.withdrawBefore(id, ev.at)
      return
    }
    // settled: the queued entry is gone. One that never landed withdraws the report as well (see
    // the header); one that landed already withdrew the older reports on its `landed` event.
    const left = (this.pending.get(id) ?? 1) - 1
    if (left > 0) this.pending.set(id, left)
    else this.pending.delete(id)
    if (!ev.landed && this.drop(id)) this.persist()
    this.publish(this.list())
  }

  get(nodeId: string): StationOutcomeRecord | undefined {
    const rec = this.byId.get(nodeId)
    return rec && this.pending.has(nodeId) ? { ...rec, workPending: true } : rec
  }

  /** Every record, newest first, each flagged `workPending` while new work is still queued for it. */
  list(): StationOutcomeRecord[] {
    return [...this.byId.values()]
      .reverse()
      .map((rec) => (this.pending.has(rec.nodeId) ? { ...rec, workPending: true as const } : rec))
  }
}

/** The messaging verbs whose delivery hands a station new work. */
const HANDOVER_VERBS: ReadonlySet<string> = new Set(['send', 'reply'])

/**
 * The control verbs whose ANSWER marks new work landing in the node they name (`--node`): `write`
 * types into the pane right before it answers (after its confirm), and `run` answers once a held
 * launch was delivered. `send` / `reply` are NOT here — their answer can be `queued`, long before
 * the bytes reach the pane — and are handled by the messaging layer's own hand-over events
 * (`StationOutcomeStore.onHandover`). `notify` types nothing into the pane.
 */
export const OUTCOME_CLEARING_VERBS: ReadonlySet<string> = new Set(['write', 'run'])

/**
 * Apply the "new task" rule to one finished `write` / `run`. Run by each shell's control handler on
 * the answer, and only on success: a refused write handed nothing. Withdraws only reports made
 * BEFORE `now` — the answer is when the bytes landed. A caller naming ITSELF is not handed work by
 * anyone (a station `write`-ing into its own pane is still doing its own task).
 */
export function clearOutcomesAfterControl(
  store: Pick<StationOutcomeStore, 'withdrawBefore'>,
  verb: string,
  args: Record<string, string | undefined>,
  result: { ok: boolean },
  callerNodeId: string,
  now: number = Date.now()
): void {
  if (!result.ok || !OUTCOME_CLEARING_VERBS.has(verb) || typeof args.node !== 'string') return
  for (const id of args.node.split(',').map((s) => s.trim())) {
    if (id && id !== callerNodeId && isSafeNodeId(id)) store.withdrawBefore(id, now)
  }
}

export interface ReportOutcomeDeps {
  store: StationOutcomeStore
  now(): number
  /** The station's project, for the board-log line. `undefined` = not in a saved project yet: the
   *  report is still recorded (it is what the wait reads); only the durable line is skipped. */
  projectIdOfNode(nodeId: string): string | undefined
  appendBoardLog(projectId: string, entry: BoardLogEntry): Promise<boolean>
  newId?(): string
  /** After a record lands. The Server Edition re-evaluates its armed launches here; the desktop's
   *  renderer hears the store's push instead. */
  onRecorded?(record: StationOutcomeRecord): void
  /** `--notify-opener` (#1356): the pair the shell's station-failure monitor already uses, so a
   *  completion notice goes to the same recipient through the same gates. Absent ⇒ the flag is
   *  refused, never ignored. */
  opener?: {
    recipientFor(stationNodeId: string): StationRecipient | undefined
    deliver(notice: {
      stationNodeId: string
      recipientNodeId: string
      body: string
    }): Promise<AgentMessageOutcome>
  }
}

export interface ReportOutcomeReply {
  ok: boolean
  message?: string
  error?: string
  result?: unknown
}

const RELEASE_TEXT: Record<StationOutcome, string> = {
  succeeded:
    'Nodes opened with --after-success on you start once your turn ends (and their other waits are met).',
  failed:
    'Nodes opened with --after-success on you stay held — they will not start on this. If the task is ' +
    'retried, report again when it ends.'
}

/**
 * `report-outcome`, answered in the shell's control handler (main on the desktop, never forwarded to
 * the renderer). The caller is the VERIFIED node the request came from — the hook server refuses an
 * unverified one before any handler runs, and this is the belt — and it may report only about
 * itself (`parseReportOutcome`).
 */
export async function handleReportOutcome(
  req: { nodeId: string; args: Record<string, string>; verified: boolean },
  deps: ReportOutcomeDeps
): Promise<ReportOutcomeReply> {
  const refuse = (error: string): ReportOutcomeReply => ({ ok: false, error, message: error })
  if (!req.verified) return refuse(REPORT_OUTCOME_CONTROL_REFUSAL)
  if (!isSafeNodeId(req.nodeId)) return refuse(REPORT_OUTCOME_CONTROL_REFUSAL)
  const parsed = parseReportOutcome(req.args, req.nodeId)
  if (!parsed.ok) return refuse(parsed.error)
  if (parsed.notifyOpener && !deps.opener) {
    return refuse('report-outcome: --notify-opener is not available in this edition')
  }
  const at = deps.now()
  const record: StationOutcomeRecord = {
    nodeId: req.nodeId,
    outcome: parsed.outcome,
    at,
    ...(parsed.note ? { note: parsed.note } : {})
  }
  // `--notify-opener` speaks only when the outcome the opener HEARD changes: repeating the same
  // report cannot keep waking it. Read before the record lands, and from what was actually told —
  // not from the previous record: a report made without the flag, or whose notice was not sent, told
  // the opener nothing, and a flagged repeat of it must still speak. New work reaching the station
  // withdraws its report (and what was heard about it), so the next task notifies again.
  const heard = deps.store.openerHeardOutcome(req.nodeId)
  deps.store.record(record)
  const projectId = deps.projectIdOfNode(req.nodeId)
  let logged = false
  if (projectId) {
    const entry: BoardLogEntry = {
      id: deps.newId?.() ?? `station-reported-${req.nodeId}-${at}`,
      ts: at,
      author: OUTCOME_AUTHOR,
      nodeId: req.nodeId,
      kind: 'event',
      event: {
        type: 'station-reported',
        from: req.nodeId,
        to: parsed.outcome,
        ...(parsed.note ? { title: parsed.note } : {})
      }
    }
    logged = await deps.appendBoardLog(projectId, entry).catch(() => false)
  }
  deps.onRecorded?.(record)
  // shortcut: sent when the report lands, not when the station's turn ends; hold it for the turn's
  // `done` if openers start reading half-finished transcripts.
  const told = !parsed.notifyOpener || !deps.opener
    ? undefined
    : heard === parsed.outcome
      ? 'Your opener was already told this outcome; it is not told again.'
      : await tellOpener(record, deps.store, deps.opener)
  const message = [
    `recorded: your task ${parsed.outcome}${parsed.note ? ` — "${parsed.note}"` : ''}.`,
    RELEASE_TEXT[parsed.outcome],
    'It stands until you report again, or until new work handed to you through canvas control (a ' +
      'send, reply, write or run aimed at you) reaches your session. A new turn does not change it.',
    ...(told ? [told] : [])
  ].join(' ')
  return {
    ok: true,
    message,
    result: { nodeId: req.nodeId, outcome: parsed.outcome, at, boardLog: logged }
  }
}

/** `--notify-opener`: one notice to the node that opened the station. Returns the line the station
 *  is told, so it knows whether its opener heard — and records in the store what it heard, which
 *  is what silences a flagged repeat of the same outcome. A notice that was not sent records
 *  nothing, so the next flagged report tries again (the switch may have been turned on since). */
async function tellOpener(
  record: StationOutcomeRecord,
  store: Pick<StationOutcomeStore, 'markOpenerHeard'>,
  opener: NonNullable<ReportOutcomeDeps['opener']>
): Promise<string> {
  const recipient = opener.recipientFor(record.nodeId)
  if (!recipient) return 'No opener to tell: no agent opened you through canvas control.'
  const body = stationOutcomeNoticeBody({ id: record.nodeId, title: recipient.stationTitle }, record.outcome)
  const outcome = await opener
    .deliver({ stationNodeId: record.nodeId, recipientNodeId: recipient.recipientNodeId, body })
    .catch(() => null)
  const { pane, paneDetail } = outcome ? paneResult(outcome) : { pane: 'not-sent', paneDetail: 'error' }
  // Queued counts as heard: the queue delivers it on the opener's next idle. A queued notice that
  // then expires is the one case this cannot see — the opener reads `list` as it always could.
  if (pane === 'told' || pane === 'queued') store.markOpenerHeard(record.nodeId, record.outcome)
  if (pane === 'told') return `Your opener ${recipient.recipientNodeId} was told.`
  if (pane === 'queued') return `Your opener ${recipient.recipientNodeId} is told when it next goes idle.`
  return `Your opener could not be told (${paneDetail ?? 'not sent'}).`
}

/** The read channel, registered by BOTH shells. `store` is a thunk for the same reason as the
 *  station-notice channels': a shell may build its store after the platform handlers. */
export function registerStationOutcomeIpc(
  platform: Pick<CorePlatform, 'handle'>,
  store: () => StationOutcomeStore | null
): void {
  platform.handle(IPC.stationOutcomeList, () => store()?.list() ?? [])
}

/** The store's durable file (core/durable-state.ts). */
export const OUTCOME_FACT: DurableFactSpec<PersistedOutcome> = {
  kind: 'station-outcomes',
  version: 1,
  maxRecords: STATION_OUTCOME_MAX_RECORDS,
  sanitize: sanitizePersistedOutcome
}