workflow

1import type { Register } from 'claude-code'
2
3// The session's own waker (FLOW-400). While the session is idle it asks `mailbox check` whether
4// anything should wake it, and starts a turn carrying whatever is new. It only schedules: what is
5// worth waking for is decided by the CLI. It also beats the board while the agent works.
6
7const TICK_MS = 60_000
8// Keep in step with CHECK_INTERVAL_MINUTES in tools/cli/src/pr-monitor/poll.ts, which the
9// pr-monitor command text and the wedge bound's idle-minutes figure derive from; the mod cannot
10// import it.
11const CHECK_INTERVAL_MS = 180_000
12// Keep CHECK_TOTAL_BUDGET_MS in tools/cli/src/mailbox/check.ts below this: a check that runs past it
13// is killed and delivers nothing.
14const CHECK_TIMEOUT_MS = 120_000
15// A beat is sent at most this often, and only after a tool call or turn end since the last one:
16// a beat must mean the agent is doing something (FLOW-321). The board marks a session hung after
17// 60 minutes without one.
18const BEAT_INTERVAL_MS = 300_000
19// `dashboard session heartbeat` invokes the board once per live leaf, 5s each.
20const BEAT_TIMEOUT_MS = 30_000
21// `mailbox check` exits 0 on a complete read and 3 on a partial one: there is no board binary, a board
22// read failed or its output was unparseable, or the registry was unreadable, so the answers listed
23// may be a subset of what is released.
24const PARTIAL_EXIT = 3
25// A check prints one entry per wake reason, each opening with a source tag; it indents an answer's
26// continuation lines, so only an entry's first line can open with a tag. Entries split before a known
27// tag at the start of a line.
28const ENTRY_START = /\n(?=\[(?:dashboard|pr-monitor|renovate-pr-monitor|team)\] )/
29const RELEASED_ITEM = /^\[dashboard\] item (\S+) /
30
31export const register: Register = (on) => {
32  // Module memory, so a reload starts all of these at their initial value: the next turn.start sets
33  // the turn state, and the next tool call re-arms the beat.
34  let isTurnRunning = false
35  let turnStarts = 0
36  let hasActivitySinceBeat = false
37  let lastBeatAt = Number.NEGATIVE_INFINITY
38
39  on('turn.start', ($, e, next) => {
40    isTurnRunning = true
41    turnStarts += 1
42    return next(e)
43  })
44
45  on('tool.call', ($, e, next) => {
46    hasActivitySinceBeat = true
47    return next(e)
48  })
49
50  // A subagent's turn ends carrying its agentId; only the main loop's end leaves the session idle.
51  on('turn.complete', ($, e, next) => {
52    hasActivitySinceBeat = true
53    if (e.agentId === undefined) {
54      isTurnRunning = false
55    }
56    return next(e)
57  })
58
59  on('session.start', async ($, e, next) => {
60    const started = await next(e)
61    // A `-p` run or the SDK has nobody at the prompt to wake.
62    if (!e.isInteractive) {
63      return started
64    }
65
66    let lastCheckAt = 0
67
68    $.clock.every(TICK_MS, async () => {
69      // Read every tick, not once: after a `/clear` or a resume the process goes on under another
70      // session id.
71      const sessionId = await $.session.id()
72      // Released answers stay released until consumed, so without this every check would re-deliver
73      // them. Kept per session in $.store, so a reload or restart does not re-deliver either.
74      const deliveredKey = `delivered-board-items:${sessionId}`
75      const now = await $.clock.now()
76      if (hasActivitySinceBeat && now - lastBeatAt >= BEAT_INTERVAL_MS) {
77        hasActivitySinceBeat = false
78        lastBeatAt = now
79        // A failed or timed-out beat is dropped, not retried: the next activity re-arms one, and a
80        // rejection here must not cost this tick its check.
81        await $.process
82          .run([`${$.plugin.root}/bin/dashboard`, 'session', 'heartbeat', '--session', sessionId], {
83            timeoutMs: BEAT_TIMEOUT_MS,
84          })
85          .catch(() => undefined)
86      }
87
88      if (isTurnRunning || now - lastCheckAt < CHECK_INTERVAL_MS) {
89        return
90      }
91
92      lastCheckAt = now
93      const turnStartsBefore = turnStarts
94      // Residual: a death line or a PR change is recorded when the check prints it (a death as
95      // reported, a PR change as the new baseline), so it is lost if the check then rejects at its
96      // timeout, or if the submit below rejects. An answer is not: it is re-printed until consumed.
97      const { exitCode, stdout } = await $.process.run(
98        [`${$.plugin.root}/bin/mailbox`, 'check', '--session', sessionId],
99        { timeoutMs: CHECK_TIMEOUT_MS }
100      )
101
102      const output = stdout.trim()
103      const entries = output === '' ? [] : output.split(ENTRY_START)
104      // Every entry that is not an answer is delivered whatever the exit code and whatever the
105      // session is doing: `$.prompt.submit` queues behind a running turn. A death line or a PR
106      // change is printed once and recorded as reported; a "could not be polled" line is never
107      // recorded and repeats each check until the PR polls again.
108      // Answer entries are re-printed until consumed, so a stale or unreliable read can wait.
109      const isAnswerReadUsable =
110        (exitCode === 0 || exitCode === PARTIAL_EXIT) &&
111        !isTurnRunning &&
112        turnStarts === turnStartsBefore
113      const delivered = new Set(asStringArray(await $.store.get(deliveredKey)))
114      const reportedIds = entries.flatMap((entry) => releasedItemId(entry) ?? [])
115      const wake = entries.filter((entry) => {
116        const id = releasedItemId(entry)
117        if (id === undefined) {
118          return true
119        }
120
121        return isAnswerReadUsable && !delivered.has(id)
122      })
123
124      if (wake.length > 0) {
125        await $.prompt.submit({ text: wake.join('\n') })
126      }
127
128      if (isAnswerReadUsable) {
129        // Recorded only after the submit, so one that rejects leaves the answer to be delivered by
130        // the next check. Only ids the check still reports are kept on a complete read: a consumed
131        // answer drops out, so the list stays as small as the board's open set. A partial read
132        // cannot tell consumed from unread, so it only adds.
133        await $.store.set(
134          deliveredKey,
135          exitCode === 0 ? reportedIds : [...new Set([...delivered, ...reportedIds])]
136        )
137      }
138    })
139
140    return started
141  })
142}
143
144const releasedItemId = (entry: string): string | undefined => RELEASED_ITEM.exec(entry)?.[1]
145
146const asStringArray = (value: unknown): string[] =>
147  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
148