@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.
- package/.claude-plugin/plugin.json +2 -2
- package/.omp-plugin/plugin.json +2 -2
- package/AGENTS.md +167 -42
- package/README.md +95 -177
- package/dist/dispatch.js +54 -6
- package/dist/envoy-channel.js +2413 -875
- package/dist/session-hook.js +54 -6
- package/hooks/claude-mod.d.ts +500 -0
- package/hooks/hooks.json +2 -1
- package/hooks/mod-protocol.ts +728 -0
- package/hooks/mod-writer.ts +506 -0
- package/hooks/mod.ts +716 -0
- package/package.json +2 -2
- package/scripts/smoke-clear-rebind.sh +1 -1
- package/scripts/smoke-session-title.sh +1 -1
- package/src/agent-stream-claude.ts +558 -0
- package/src/agent-stream-runner.ts +340 -0
- package/src/bounded-set.ts +54 -0
- package/src/channel-forwarder.ts +1 -1
- package/src/claude-rows.ts +195 -0
- package/src/envoy-channel-server.ts +394 -136
- package/src/envoy-off.ts +6 -1
- package/src/installed-build.ts +26 -0
- package/src/legion-inbox.ts +22 -11
- package/src/mod-link.ts +562 -0
- package/src/mod-session.ts +499 -0
- package/src/replay-state.ts +2 -18
- package/src/state-file.ts +39 -0
- package/src/user-turn-router.ts +496 -0
- package/src/user-turn-state.ts +134 -0
- package/scripts/smoke-channel.sh +0 -178
- package/src/claude-channel.ts +0 -705
|
@@ -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
|
+
}
|