@sjawhar/claude-envoy 1.18.0 → 1.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,496 @@
1
+ // Where a person's message from Dispatch's Agents page goes (INFRA-1026).
2
+ //
3
+ // Every inbound frame used to become one rendered card naming its sender. A frame that is a
4
+ // person's own direct message to this session becomes the session's own user turn instead, and a
5
+ // `/` message runs as the command it is, a pick sets what it names, and a BTW is answered off to
6
+ // the side. Everything else still arrives as the card, which is the delivery.
7
+ //
8
+ // The accept step is the security of all of it, and it is one step both Envoy plugins take:
9
+ // `acceptUserTurn` in `@legion/pi-shared/accept-user-turn`, which the Oh My Pi plugin
10
+ // (`acceptedUserTurn`, `packages/pi-envoy/extensions/envoy.ts`) calls too, so a fix to the rule
11
+ // lands in both. The order of its steps - and why the attempt is recorded before Dispatch is
12
+ // asked, a 404 included - is stated there. What this host puts into it: its own record of
13
+ // handled attempts (`./user-turn-state`, a file that outlives the process), the session's
14
+ // Dispatch bounded by `ACCEPT_TIMEOUT_MS`, the session id a `/clear` moves, and these warnings.
15
+ // The listener takes an envelope's source from whoever publishes it and every session on the
16
+ // bus holds that token, so a frame saying a person wrote it proves nothing: what makes a turn
17
+ // is Dispatch recording that this session accepted that very attempt, and what it injects is
18
+ // the body Dispatch answers with, never the frame's own text.
19
+ import { comparableLines } from "@legion/contracts"
20
+ import type { DispatchDelivery, RenderInboundResult } from "@legion/envoy-client/delivery"
21
+ import type { DispatchClient } from "@legion/envoy-client/dispatch-http"
22
+ import { pictureAddresses } from "@legion/envoy-client/dispatch-pictures"
23
+ import { messageFor } from "@legion/envoy-client/errors"
24
+ import { type AcceptedUserTurnDelivery, acceptUserTurn } from "@legion/pi-shared/accept-user-turn"
25
+ import { withDeliveredPictures } from "@legion/pi-shared/delivery-pictures"
26
+ import {
27
+ type AcceptedUserTurn,
28
+ handledAttemptKey,
29
+ typedInputReply,
30
+ } from "@legion/pi-shared/dispatch-user-turn"
31
+ import type { ContentBlock } from "@legion/pi-shared/pi-types"
32
+ import type { ModContentBlock, ModEffort, ModEvent } from "../hooks/mod-protocol"
33
+ import { CLAUDE_EFFORT_LEVELS, CLAUDE_PROVIDER } from "./agent-stream-claude"
34
+ import { rememberBounded } from "./bounded-set"
35
+ import type { ModSession } from "./mod-session"
36
+ import type { UserTurnState } from "./user-turn-state"
37
+
38
+ /**
39
+ * How long a person's direct message waits on Dispatch's acceptance before it arrives as a card
40
+ * instead, as the Oh My Pi plugin bounds the same call: the frames reach this session one at a
41
+ * time, so a hung Dispatch must not hold every message behind this one.
42
+ */
43
+ const ACCEPT_TIMEOUT_MS = 10_000
44
+
45
+ /** How long the pictures a message embeds have to load before it goes in as text alone. */
46
+ const PICTURES_TIMEOUT_MS = 20_000
47
+
48
+ /**
49
+ * How long a command runs before the person is told it is still running. Deliberately below the
50
+ * 30 seconds the Agents page waits for a pick's answer (`SWITCH_ANSWER_DEADLINE_MS` in
51
+ * `packages/dispatch/web/src/features/agent-view/use-session-switch.ts`), so a person learns why
52
+ * the answer is late before the page stops waiting for it.
53
+ */
54
+ const COMMAND_WAITING_MS = 10_000
55
+
56
+ /** The most messages whose row of the conversation has not arrived yet. A person's messages are
57
+ * delivered one at a time and the row follows within a moment; this is the bound that keeps a
58
+ * message whose row never came from being matched against a much later one. */
59
+ const AWAITED_ROWS_MAX = 16
60
+
61
+ /** The most answered deliveries this session remembers, so a second answer to one asks Dispatch
62
+ * to post it. A delivery is answered twice at most, within one command's run, and messages are
63
+ * delivered one at a time; this is the bound that keeps the record from growing for the
64
+ * session's life. */
65
+ const ANSWERED_DELIVERIES_MAX = 64
66
+
67
+ /** What a person is told while a command they sent has not finished. */
68
+ export function commandStillRunning(command: string): string {
69
+ return `${command} is still running: it waits for the turn this session is in, or for an answer at the session's own terminal. Its output follows in another reply.`
70
+ }
71
+
72
+ /**
73
+ * What a person is told when the command they sent printed nothing at all, so a Send is never
74
+ * met with silence.
75
+ *
76
+ * `typedInputReply` answers undefined for an empty output, and that helper is the Oh My Pi
77
+ * plugin's too (`packages/pi-shared/src/dispatch-user-turn.ts`), so the line is written here
78
+ * rather than there.
79
+ */
80
+ export function commandPrintedNothing(command: string): string {
81
+ return `${command} ran in this session and printed nothing.`
82
+ }
83
+
84
+ /** What a person is told once their model pick is in force. */
85
+ export function modelPicked(model: string): string {
86
+ return `The session's model is now ${model}.`
87
+ }
88
+
89
+ /** What a person is told once their thinking pick is in force. */
90
+ export function thinkingPicked(effort: ModEffort): string {
91
+ return `The session's thinking level is now ${effort}.`
92
+ }
93
+
94
+ /** A message whose row of the conversation has not arrived yet: the person's own words, which
95
+ * is what the row will say, and the Dispatch message that row is. A `/` message has no such
96
+ * row - the only row it writes is the one Claude Code echoes the command it ran in, which the
97
+ * live view draws nothing of (`./agent-stream-claude`, `runsCommandRow`). */
98
+ interface AwaitedRow {
99
+ readonly body: string
100
+ readonly messageId: string
101
+ }
102
+
103
+ export interface UserTurnRouterOptions {
104
+ /** This session as Dispatch knows it: the actor the accept names, and the author of its
105
+ * replies. Read at each use, since a `/clear` moves it. */
106
+ readonly sessionId: () => string
107
+ /** What this session has already done with the attempts Dispatch sent it. */
108
+ readonly state: UserTurnState
109
+ /** The Claude Code session itself (`./mod-session`). */
110
+ readonly session: ModSession
111
+ /** The session's Dispatch for one request, with `ms` to answer; undefined when Dispatch is not
112
+ * configured, and a throw when its configuration cannot be read. */
113
+ readonly dispatch: (ms: number) => DispatchClient | undefined
114
+ /** Answers a delivery on Dispatch: the reply the person reads, or the error that stopped it.
115
+ * `followUp` is the ask that Dispatch post this answer although the attempt is already
116
+ * answered, which every answer to a delivery after the first carries (`post`). */
117
+ readonly reply: (
118
+ delivery: DispatchDelivery,
119
+ result: {
120
+ readonly body?: string
121
+ readonly error?: string
122
+ readonly followUp?: boolean
123
+ },
124
+ ) => Promise<void>
125
+ /**
126
+ * Where a person's own message goes in a Legion pane: the bridge's inbox, which makes it a user
127
+ * turn (`./legion-inbox`). Undefined in a terminal session, where it goes to the mod.
128
+ */
129
+ readonly inbox?: (input: {
130
+ readonly content: string
131
+ readonly blocks?: readonly ModContentBlock[]
132
+ readonly eventId?: string
133
+ }) => Promise<void>
134
+ /** Refreshes the live view's settings frame, so the header already shows a pick's new value
135
+ * when the reply naming it arrives. */
136
+ readonly refreshSettings: () => void
137
+ /** Tells the live view the effort a thinking pick put in force. Claude Code reports an effort
138
+ * only on a request's own `turn.step`, so a refresh alone leaves the header on the level the
139
+ * session ran at before the pick until its next turn. */
140
+ readonly effortPicked: (effort: ModEffort) => void
141
+ /** Where a failure that must not stop the session is written. */
142
+ readonly warn: (text: string) => void
143
+ /** How long a command runs before the person is told it is still running; `COMMAND_WAITING_MS`
144
+ * by default, named by the tests that drive it. */
145
+ readonly commandWaitingMs?: number
146
+ }
147
+
148
+ export interface UserTurnRouter {
149
+ /**
150
+ * What one live frame becomes: `true` when the router took it - the person's own message, a
151
+ * command, a pick or a BTW - and `false` when it keeps today's card. It throws when a message
152
+ * Dispatch has accepted could not be put into the session, so the frame is not answered and the
153
+ * listener sends it again.
154
+ */
155
+ route(rendered: RenderInboundResult): Promise<boolean>
156
+ /** Takes one of the mod's events, to recognise the row each delivered message turned out to
157
+ * be, which tags that row on the live view's frames. */
158
+ observe(event: ModEvent): void
159
+ }
160
+
161
+ /** The text a row's content holds, so a row can be recognised by the message it carries: its text
162
+ * blocks alone, since a picture crosses as an image block that carries no text of its own. */
163
+ function rowText(content: readonly ModContentBlock[]): string {
164
+ const pieces: string[] = []
165
+ for (const block of content) {
166
+ const text = block["text"]
167
+ if (block.type === "text" && typeof text === "string") pieces.push(text)
168
+ }
169
+ return pieces.join("\n")
170
+ }
171
+
172
+ /** A delivery's content as Claude Code's own blocks: the text, and one image block per picture,
173
+ * as the Messages API shapes them (`@legion/pi-shared/delivery-pictures` answers an Oh My Pi
174
+ * host's blocks, whose images carry their bytes and type under other names). */
175
+ export function claudeContentBlocks(content: string | readonly ContentBlock[]): ModContentBlock[] {
176
+ if (typeof content === "string") return [{ type: "text", text: content }]
177
+ return content.map((block) =>
178
+ block.type === "text"
179
+ ? { type: "text", text: block.text }
180
+ : {
181
+ type: "image",
182
+ source: { type: "base64", media_type: block.mimeType, data: block.data },
183
+ },
184
+ )
185
+ }
186
+
187
+ /** The effort a `/effort` pick names: one of the levels the view offers, or a number for a model
188
+ * that takes one; undefined for anything else, which runs as the command it is. */
189
+ function pickedEffort(value: string): ModEffort | undefined {
190
+ const named = CLAUDE_EFFORT_LEVELS.find((level) => level === value)
191
+ if (named !== undefined) return named
192
+ const number = Number(value)
193
+ return value !== "" && Number.isFinite(number) ? number : undefined
194
+ }
195
+
196
+ export function createUserTurnRouter(options: UserTurnRouterOptions): UserTurnRouter {
197
+ const { reply, session, state, warn } = options
198
+ /** Whether this session is a Legion pane, which is exactly the session whose person messages
199
+ * go to the bridge's inbox rather than to the mod. */
200
+ const inPane = options.inbox !== undefined
201
+ const waitingMs = options.commandWaitingMs ?? COMMAND_WAITING_MS
202
+ /** The pictures this session has been shown, so one is sent once (`withDeliveredPictures`). */
203
+ const shownPictures = new Set<string>()
204
+ /** The messages whose row of the conversation has not arrived yet, oldest first. */
205
+ const awaited: AwaitedRow[] = []
206
+ /** The deliveries this session has already answered, oldest first: every answer after the
207
+ * first has to ask Dispatch to post it (`post`). */
208
+ const answered = new Set<string>()
209
+
210
+ /** Expects the row a message is about to become, so the row is recorded as that message as soon
211
+ * as the session reports it - which it may do before the call that delivered it answers. */
212
+ const expectRow = (body: string, messageId: string): void => {
213
+ awaited.push({ body, messageId })
214
+ while (awaited.length > AWAITED_ROWS_MAX) awaited.shift()
215
+ }
216
+
217
+ const record = (row: string, messageId: string): void => {
218
+ state.delivered(row, messageId).catch((error: unknown) => {
219
+ warn(
220
+ `could not record which Dispatch message a row of this session is — ${messageFor(error)}`,
221
+ )
222
+ })
223
+ }
224
+
225
+ /**
226
+ * The turn Dispatch says this frame is, or undefined for every frame that keeps its card: the
227
+ * shared accept step (`@legion/pi-shared/accept-user-turn`), which both Envoy plugins take,
228
+ * with this session's record of handled attempts, its Dispatch and its stderr. The order of
229
+ * the steps is the rule itself, and it is stated where the step is written; the comment at
230
+ * the top of this file says what this host puts into it.
231
+ */
232
+ const accepted = (rendered: RenderInboundResult): Promise<AcceptedUserTurnDelivery | undefined> =>
233
+ acceptUserTurn({
234
+ actorId: options.sessionId(),
235
+ dispatch: () => options.dispatch(ACCEPT_TIMEOUT_MS),
236
+ handle: state.handle,
237
+ handled: state.handled,
238
+ rendered,
239
+ warn: (refusal) => {
240
+ const { delivery } = refusal
241
+ if (refusal.reason === "handled") {
242
+ warn(
243
+ `a frame names the Dispatch attempt ${delivery.attempt} of message ${delivery.id}, which this session has already delivered; it arrives as a card`,
244
+ )
245
+ return
246
+ }
247
+ if (refusal.reason === "no-body") {
248
+ warn(
249
+ `Dispatch accepted message ${delivery.id} without the stored body to inject; it arrives as a card`,
250
+ )
251
+ return
252
+ }
253
+ warn(
254
+ `Dispatch did not accept message ${delivery.id} as this session's turn (${messageFor(refusal.error)}); it arrives as a card`,
255
+ )
256
+ },
257
+ })
258
+
259
+ /** The person's message, as the session's own: a row of the turn running, or the prompt of a
260
+ * new one. Throws when the session could not take it, so the frame is sent again - which is
261
+ * why `eventId`, the frame's own Envoy event id, goes with it: the mod writes one event id
262
+ * once, so the copy Envoy sends next, which arrives as a card because this attempt is spent,
263
+ * is answered with the row this write left and the person's words reach the model one time
264
+ * (`./mod-session`, `../hooks/mod-writer.ts`, `writeOnce`). */
265
+ const inject = async (
266
+ delivery: DispatchDelivery,
267
+ turn: AcceptedUserTurn,
268
+ eventId: string | undefined,
269
+ ): Promise<void> => {
270
+ const pictures = await withDeliveredPictures(
271
+ turn.body,
272
+ pictureAddresses(turn.body),
273
+ () => options.dispatch(PICTURES_TIMEOUT_MS),
274
+ false,
275
+ shownPictures,
276
+ )
277
+ const blocks = claudeContentBlocks(pictures.content)
278
+ // Expected before the message is handed over: the session reports the row as an event of its
279
+ // own, which can reach this process before the call that delivered it answers.
280
+ expectRow(turn.body, turn.messageId)
281
+ if (!inPane) {
282
+ const row = await session.deliver({
283
+ content: blocks,
284
+ ...(eventId === undefined ? {} : { eventId }),
285
+ // The prompt at a row the turn never read carries both: the person's own words, and
286
+ // which Dispatch message they are (`unreadRowPrompt`, `./mod-session`).
287
+ messageId: turn.messageId,
288
+ text: turn.body,
289
+ // A prompt the session dropped is the one failure this path answers on Dispatch rather
290
+ // than throwing: the person's own words were refused, and Dispatch is where they wait
291
+ // (`deliver`, `./mod-session`).
292
+ failed: (error) => {
293
+ void answer(delivery, typedInputReply(turn.body, { error: messageFor(error) }))
294
+ },
295
+ })
296
+ if (row !== undefined) record(row, turn.messageId)
297
+ } else {
298
+ await options.inbox({
299
+ content: turn.body,
300
+ eventId: turn.messageId,
301
+ ...(blocks.length > 1 ? { blocks } : {}),
302
+ })
303
+ }
304
+ for (const address of pictures.shown) shownPictures.add(address)
305
+ }
306
+
307
+ /**
308
+ * Posts one answer to a delivery, and asks Dispatch to post it when this session has answered
309
+ * that delivery before. Dispatch settles a delivery attempt with the first reply it takes and
310
+ * answers a later POST to the same attempt by handing the stored reply back, posting nothing
311
+ * unless the request asks for a follow-up (`replyAfterAnswer`,
312
+ * `packages/envoy/internal/dispatch/api/message_delivery.go`) - so without the ask the output
313
+ * a waiting reply promised never reaches the person. The ask is decided before the post is
314
+ * awaited, so a waiting reply and the output racing it cannot both be the first.
315
+ */
316
+ const post = async (
317
+ delivery: DispatchDelivery,
318
+ result: { readonly body?: string; readonly error?: string },
319
+ ): Promise<void> => {
320
+ const key = handledAttemptKey(delivery.id, delivery.attempt)
321
+ const followUp = answered.has(key)
322
+ if (!followUp) {
323
+ // A reply Dispatch refused leaves the attempt unsettled, and a follow-up on an unsettled
324
+ // attempt is inserted as the first reply anyway, so the record is kept either way.
325
+ rememberBounded(answered, key, ANSWERED_DELIVERIES_MAX)
326
+ }
327
+ await reply(delivery, { ...result, followUp })
328
+ }
329
+
330
+ /** Posts one reply to a delivery, naming on stderr a reply that did not reach Dispatch. */
331
+ const answer = async (delivery: DispatchDelivery, body: string | undefined): Promise<void> => {
332
+ if (body === undefined) return
333
+ await post(delivery, { body }).catch((error: unknown) => {
334
+ warn(`a reply to message ${delivery.id} did not reach Dispatch — ${messageFor(error)}`)
335
+ })
336
+ }
337
+
338
+ /**
339
+ * A person's pick of a model, which is their own `/model` message. Nothing of the run is
340
+ * expected back as a row: Claude Code echoes the command it ran - `/model haiku` for the
341
+ * `/model anthropic/haiku` the person sent, measured live on 2.1.310 (INFRA-1026) - and the
342
+ * live view draws no row of a run of this session's at all, so their own line reaches the
343
+ * page as the message Dispatch stored and nothing beside it.
344
+ */
345
+ const pickModel = async (value: string): Promise<string> => {
346
+ const model = value.startsWith(`${CLAUDE_PROVIDER}/`)
347
+ ? value.slice(CLAUDE_PROVIDER.length + 1)
348
+ : value
349
+ // A pane's Claude Code runs in print mode, where the model is the command's to change; a
350
+ // terminal session's is a `/config` row.
351
+ if (inPane) {
352
+ await session.runCommand("model", model)
353
+ return modelPicked(`${CLAUDE_PROVIDER}/${model}`)
354
+ }
355
+ const stored = await session.setModel(model)
356
+ return modelPicked(`${CLAUDE_PROVIDER}/${String(stored)}`)
357
+ }
358
+
359
+ /**
360
+ * A `/` message: a pick of the model or the thinking level, or the command itself. Its output
361
+ * is the reply; a command still running after `waitingMs` is answered twice, the waiting reply
362
+ * first.
363
+ */
364
+ const runTyped = async (delivery: DispatchDelivery, body: string): Promise<void> => {
365
+ const typed = /^\/(\S+)/.exec(body)
366
+ const name = typed?.[1] ?? ""
367
+ const value = body.slice(typed?.[0].length ?? 0).trim()
368
+ const effort = name === "effort" ? pickedEffort(value) : undefined
369
+ if (!session.connected()) {
370
+ await answer(
371
+ delivery,
372
+ typedInputReply(body, { error: "this session has no link to Claude Code" }),
373
+ )
374
+ return
375
+ }
376
+ let running = true
377
+ const waiting = setTimeout(() => {
378
+ if (!running) return
379
+ void answer(
380
+ delivery,
381
+ typedInputReply(body, {
382
+ handled: "command",
383
+ output: commandStillRunning(`/${name}`),
384
+ }),
385
+ )
386
+ }, waitingMs)
387
+ waiting.unref()
388
+ let said: string | undefined
389
+ try {
390
+ if (name === "model" && value !== "") said = await pickModel(value)
391
+ else if (effort !== undefined) {
392
+ const inForce = (await session.setEffort(effort)) ?? effort
393
+ // The mod puts this effort on every later request from here on, so the header can say
394
+ // so now rather than at the session's next turn.
395
+ options.effortPicked(inForce)
396
+ said = thinkingPicked(inForce)
397
+ } else {
398
+ // The person sees this command once, as the message Dispatch stored: the row Claude
399
+ // Code echoes the run in is drawn nowhere (`pickModel`), so no row is expected for it.
400
+ const output = await session.runCommand(name, value)
401
+ // A command that printed nothing is answered all the same: `typedInputReply` has
402
+ // nothing to say for an empty output, and silence is what the person was left with.
403
+ const printed = typedInputReply(body, { handled: "command", output })
404
+ said = printed ?? commandPrintedNothing(`/${name}`)
405
+ }
406
+ } catch (error) {
407
+ said = typedInputReply(body, { error: messageFor(error) })
408
+ } finally {
409
+ running = false
410
+ clearTimeout(waiting)
411
+ }
412
+ // A pick has run by now: the header shows its new value before the reply that names it
413
+ // reaches the page.
414
+ options.refreshSettings()
415
+ await answer(delivery, said)
416
+ }
417
+
418
+ /** A BTW: one question of the model with the conversation as its context, answered on Dispatch.
419
+ * It adds nothing to the conversation, and the frame is answered without waiting for it. Its
420
+ * answer never asks for a follow-up: a BTW is answered one time, and the rule that a frame
421
+ * this session is handed twice posts no second answer is what Dispatch leans on for it
422
+ * (`replyAfterAnswer`, `packages/envoy/internal/dispatch/api/message_delivery.go`), since
423
+ * nothing here guards a redelivered BTW and the fork would answer it afresh. */
424
+ const runBtw = (delivery: DispatchDelivery): void => {
425
+ void (async () => {
426
+ if (!session.connected()) {
427
+ await reply(delivery, { error: "this session has no link to Claude Code" })
428
+ return
429
+ }
430
+ try {
431
+ await reply(delivery, { body: await session.fork(delivery.body) })
432
+ } catch (error) {
433
+ await reply(delivery, { error: messageFor(error) })
434
+ }
435
+ })().catch((error: unknown) => {
436
+ warn(`a BTW answer did not reach Dispatch — ${messageFor(error)}`)
437
+ })
438
+ }
439
+
440
+ return {
441
+ async route(rendered) {
442
+ const btw = rendered.delivery
443
+ if (btw?.mode === "btw") {
444
+ runBtw(btw)
445
+ return true
446
+ }
447
+ const accept = await accepted(rendered)
448
+ if (accept === undefined) return false
449
+ const { delivery, turn } = accept
450
+ if (turn.body.startsWith("/")) {
451
+ // The command runs for as long as it runs: the frame is answered now, and its output
452
+ // reaches the person as a reply when it comes.
453
+ void runTyped(delivery, turn.body).catch((error: unknown) => {
454
+ warn(`a command from Dispatch failed — ${messageFor(error)}`)
455
+ })
456
+ return true
457
+ }
458
+ // The frame's own Envoy event id, which is what makes the person's write and the card
459
+ // its resend becomes one write (`inject`).
460
+ await inject(delivery, turn, rendered.envelope?.event_id)
461
+ return true
462
+ },
463
+ observe(event) {
464
+ // The Claude Code session was handed this event before the router was (`startAgentStream`,
465
+ // `./envoy-channel-server`): its turn tracking must not depend on a router existing.
466
+ if (event.kind !== "append" || awaited.length === 0) return
467
+ const { message } = event
468
+ if (message.type !== "user" && message.role !== "user") return
469
+ // Every row is read as the text it carries. A command a person sent writes no row that
470
+ // is theirs - Claude Code echoes the command it ran, in a row the live view draws
471
+ // nothing of (`./agent-stream-claude`, `runsCommandRow`) - so nothing here waits for one
472
+ // and nothing tags one.
473
+ //
474
+ // A row and a body are compared by the shared line rule (`comparableLines`,
475
+ // `@legion/contracts`), each side joined back into one string to match on. A message
476
+ // carrying a picture reaches the session as its text and one image block per picture
477
+ // (`claudeContentBlocks`), and the row it becomes holds the text alone - either as the
478
+ // person wrote it, markdown and all (measured on 2.1.310:
479
+ // `/legion/scratch/tmp/i3-k5-pane/config/projects/-legion-scratch-tmp-i3-k5-pane-cwd/f376a3a9-6e75-461b-806b-22dea4e83ddf.jsonl:121`),
480
+ // or with the markdown gone, as the live view measured it, since the picture is a block
481
+ // of its own and no longer a word of the text. Taking the markdown off both sides
482
+ // recognises the row either way, so the message is tagged with its Dispatch id and the
483
+ // page shows it once. Both sides here are this session's own, which is why both are read
484
+ // by the rule alone: the page reads a stored body by this same rule and so must not
485
+ // drift from it, but it reads the streamed row - a frame any client of the bus can
486
+ // publish - by a check of its own first (`turnSaysBody` and `rowLines`,
487
+ // `packages/dispatch/web/src/features/agent-view/conversation.ts`).
488
+ const said = comparableLines(rowText(message.content)).join("\n")
489
+ const index = awaited.findIndex((row) => comparableLines(row.body).join("\n") === said)
490
+ const row = awaited[index]
491
+ if (row === undefined) return
492
+ awaited.splice(index, 1)
493
+ record(event.uuid, row.messageId)
494
+ },
495
+ }
496
+ }
@@ -0,0 +1,134 @@
1
+ // What this session did with the direct messages Dispatch sent it, in one file per session id
2
+ // under `CLAUDE_PLUGIN_DATA` (INFRA-1026), beside the `replay-*.json` files and the `roles/`
3
+ // records.
4
+ //
5
+ // The Oh My Pi plugin keeps both of these in its host's transcript
6
+ // (`@legion/pi-shared/dispatch-user-turn`, `HANDLED_ATTEMPT_ENTRY`); Claude Code gives this server
7
+ // no transcript to write, so they live here:
8
+ //
9
+ // - the attempts this session has already handled, as a card or as a turn. The accept route may
10
+ // be asked for an attempt once, so the record goes in before Dispatch is asked, and a frame
11
+ // naming a recorded attempt is a card with no accept call - a replay, or one forged inside the
12
+ // accept's minute. It has to outlive the process, because a restart must not accept an attempt
13
+ // the process before it already spent.
14
+ // - the Dispatch message each delivered row of the conversation is, which is what tags the row
15
+ // on the live view's frames so a person's own message shows once rather than twice
16
+ // (`packages/dispatch/web/src/features/agent-view/conversation.ts`). A row is recorded only
17
+ // once it exists, which is the point of the write order the router keeps.
18
+ //
19
+ // Both are bounded, by the rule the package writes once (`rememberBounded`,
20
+ // `rememberBoundedEntry` in `./bounded-set`): a session that runs for weeks must not grow a file
21
+ // without end, and neither record is worth keeping once it is thousands of messages old.
22
+ import { join } from "node:path"
23
+ import { z } from "zod"
24
+ import { rememberBounded, rememberBoundedEntry } from "./bounded-set"
25
+ import { pruneStateDirectory, writeAtomicStateFile, writtenLongAgo } from "./session-state"
26
+ import { readStateFile } from "./state-file"
27
+
28
+ /** The directory the records live in, named once for the writer, the reader and the sweep. */
29
+ const TURNS_DIRECTORY = "turns"
30
+
31
+ /** The most handled attempts one session's file keeps, oldest dropped first. A person sends far
32
+ * fewer than this to one session, and an attempt this old can no longer be accepted: Dispatch
33
+ * accepts only an attempt a person asked for within the last minute. */
34
+ const HANDLED_ATTEMPTS_MAX = 1_000
35
+
36
+ /** The most delivered rows one session's file keeps. It only has to outlive the live view's own
37
+ * ring, which holds far fewer messages than this. */
38
+ const DELIVERED_ROWS_MAX = 1_000
39
+
40
+ /** One row of the conversation this session delivered a person's message as. */
41
+ const DeliveredRowSchema = z.object({ row: z.string(), message_id: z.string() })
42
+
43
+ /**
44
+ * A session's file. Both lists are oldest first, and a reader of a file written by another
45
+ * release takes what it knows: an unknown key is left alone, and a missing one is empty.
46
+ */
47
+ export const UserTurnStateSchema = z.object({
48
+ handled: z.array(z.string()).default([]),
49
+ rows: z.array(DeliveredRowSchema).default([]),
50
+ })
51
+
52
+ export type UserTurnStateFile = z.infer<typeof UserTurnStateSchema>
53
+
54
+ /** The `.json` suffix is what keeps a session id of `.` or `..` a file of the directory itself,
55
+ * since `encodeURIComponent` leaves a dot alone. */
56
+ export function userTurnStateFile(stateDirectory: string, sessionId: string): string {
57
+ return join(stateDirectory, TURNS_DIRECTORY, `${encodeURIComponent(sessionId)}.json`)
58
+ }
59
+
60
+ /**
61
+ * What a session's file holds; nothing when there is no file, which is a session that has taken
62
+ * no direct message yet. A file that cannot be read, or holds something else, rejects, and the
63
+ * caller then builds no router for the session id (`restoreTurns`): every message arrives as a
64
+ * card, since a record it could not read may hold an attempt already spent.
65
+ */
66
+ export async function readUserTurnState(file: string): Promise<UserTurnStateFile> {
67
+ return await readStateFile(
68
+ file,
69
+ UserTurnStateSchema,
70
+ { handled: [], rows: [] },
71
+ "holds no record of this session's turns",
72
+ )
73
+ }
74
+
75
+ /** One session's record, in memory and on disk. */
76
+ export interface UserTurnState {
77
+ /** Whether this session already handled the attempt `key`
78
+ * (`handledAttemptKey`, `@legion/pi-shared/dispatch-user-turn`), in this process or before it. */
79
+ handled(key: string): boolean
80
+ /**
81
+ * Records the attempt `key` as handled, and resolves once the file holding it is in place. The
82
+ * router awaits this before it asks Dispatch to accept: an attempt whose record did not reach
83
+ * the disk must not be spent.
84
+ */
85
+ handle(key: string): Promise<void>
86
+ /** The Dispatch message a delivered row is, or undefined for a row of the session's own. */
87
+ messageOf(row: string): string | undefined
88
+ /** Records that row `row` of the conversation is the Dispatch message `messageId`. */
89
+ delivered(row: string, messageId: string): Promise<void>
90
+ /** Resolves once every write asked for so far has finished, failed ones included. */
91
+ idle(): Promise<void>
92
+ }
93
+
94
+ /** The record in `file`, starting from what it held (`restored`). Every write replaces the whole
95
+ * file with the record as it stands when it runs, one write at a time. */
96
+ export function userTurnState(file: string, restored: UserTurnStateFile): UserTurnState {
97
+ const handled = new Set(restored.handled)
98
+ const rows = new Map(restored.rows.map(({ row, message_id }) => [row, message_id]))
99
+ let writing: Promise<void> = Promise.resolve()
100
+
101
+ const write = (): Promise<void> => {
102
+ const state: UserTurnStateFile = {
103
+ handled: [...handled].slice(-HANDLED_ATTEMPTS_MAX),
104
+ rows: [...rows].slice(-DELIVERED_ROWS_MAX).map(([row, message_id]) => ({ row, message_id })),
105
+ }
106
+ const run = writing.then(() => writeAtomicStateFile(file, `${JSON.stringify(state)}\n`))
107
+ writing = run.catch(() => undefined)
108
+ return run
109
+ }
110
+
111
+ return {
112
+ handled: (key) => handled.has(key),
113
+ handle(key) {
114
+ rememberBounded(handled, key, HANDLED_ATTEMPTS_MAX)
115
+ return write()
116
+ },
117
+ messageOf: (row) => rows.get(row),
118
+ delivered(row, messageId) {
119
+ // The router records the same pair twice by design - the append event the session reported
120
+ // and the call that delivered it, whichever wins - and the second call has nothing to add.
121
+ // The write already running is the one putting this pair in place, so it is what resolves.
122
+ if (rows.get(row) === messageId) return writing
123
+ rememberBoundedEntry(rows, row, messageId, DELIVERED_ROWS_MAX)
124
+ return write()
125
+ },
126
+ idle: () => writing,
127
+ }
128
+ }
129
+
130
+ /** Drop `turns/` records nothing has touched in `STATE_FILE_MAX_AGE_MS`, as the titles are
131
+ * dropped: a session's id dies with it, so nothing else ever removes one. */
132
+ export async function pruneStaleSessionTurns(stateDirectory: string): Promise<void> {
133
+ await pruneStateDirectory(join(stateDirectory, TURNS_DIRECTORY), writtenLongAgo)
134
+ }