The best way to control Claude Code, Codex and more from any computer or phone

main
ts 428 lines 15.9 KB
Raw
1 import type {
2 CheckpointId,
3 MessageId,
4 NodeId,
5 OrchestrationV2Checkpoint,
6 OrchestrationV2DomainEvent,
7 OrchestrationV2ContextHandoff,
8 OrchestrationV2StoredEvent,
9 OrchestrationV2Subagent,
10 OrchestrationV2ThreadProjection,
11 OrchestrationV2ThreadStreamItem,
12 OrchestrationV2TurnItem,
13 } from "@t3tools/contracts";
14 import {
15 dedupeSubagentBodies,
16 dedupeTurnItemBodies,
17 } from "@t3tools/shared/orchestrationV2DedupedBodies";
18 import { MCP_APP_OUTPUT_KEY, readMcpAppReference } from "@t3tools/shared/mcpApp";
19 import {
20 commandIndicatesFailure,
21 compactDynamicToolOutput,
22 omitToolOutputImageData,
23 toolOutputImages,
24 } from "@t3tools/shared/toolOutput";
25
26 // A checkpoint over vendored or generated trees can list 15k+ files; the card needs a prefix.
27 const MAX_WIRE_CHECKPOINT_FILES = 200;
28 const MAX_DETAIL_STRING_BYTES = 32_768;
29 const MAX_DYNAMIC_VALUE_BYTES = 16_384;
30 const MAX_ON_DEMAND_BYTES = 256 * 1024;
31 const TRUNCATION_MARKER = "\n… output truncated for transport";
32 const TRUNCATION_MARKER_BYTES = Buffer.byteLength(TRUNCATION_MARKER, "utf8");
33
34 function truncateDetail(
35 value: string | undefined,
36 maxBytes = MAX_DETAIL_STRING_BYTES,
37 ): string | undefined {
38 if (
39 value === undefined ||
40 (value.length <= maxBytes && Buffer.byteLength(value, "utf8") <= maxBytes)
41 ) {
42 return value;
43 }
44 // The marker counts toward the cap, so projecting truncated text again leaves it unchanged.
45 const budget = maxBytes - TRUNCATION_MARKER_BYTES;
46 // UTF-8 needs at least one byte per UTF-16 unit; encode only a potentially fitting prefix.
47 const prefix = Buffer.from(value.slice(0, budget), "utf8")
48 .subarray(0, budget)
49 .toString("utf8")
50 .replace(/\uFFFD$/u, "");
51 return `${prefix}${TRUNCATION_MARKER}`;
52 }
53
54 /** Bound stored diffs to the client wire limit to avoid retaining invisible data in SQLite and heap. */
55 export function boundFileChangeForStorage(item: OrchestrationV2TurnItem): OrchestrationV2TurnItem {
56 if (item.type !== "file_change") return item;
57 const { diffStr, oldStr, newStr } = item;
58 const bounded = {
59 ...item,
60 ...(diffStr === undefined ? {} : { diffStr: truncateDetail(diffStr) }),
61 ...(oldStr === undefined ? {} : { oldStr: truncateDetail(oldStr) }),
62 ...(newStr === undefined ? {} : { newStr: truncateDetail(newStr) }),
63 };
64 return bounded.diffStr === diffStr && bounded.oldStr === oldStr && bounded.newStr === newStr
65 ? item
66 : bounded;
67 }
68
69 function summarizeDynamicValue(value: unknown): unknown {
70 let serialized: string;
71 try {
72 if (typeof value === "string" && value.length > MAX_DYNAMIC_VALUE_BYTES) {
73 serialized = value;
74 } else {
75 const json = JSON.stringify(value) ?? String(value);
76 if (Buffer.byteLength(json, "utf8") <= MAX_DYNAMIC_VALUE_BYTES) {
77 return value;
78 }
79 serialized = typeof value === "string" ? value : json;
80 }
81 } catch {
82 serialized = "Unserializable tool output";
83 }
84
85 // Splitting and normalizing every line can allocate far more than the input.
86 const start = /\S/u.exec(serialized)?.index;
87 let firstLine = start === undefined ? "Large tool output" : "";
88 let pendingSpace = false;
89 for (let index = start ?? serialized.length; index < serialized.length; index += 1) {
90 const character = serialized[index]!;
91 if (character === "\n") break;
92 if (/\s/u.test(character)) {
93 pendingSpace = true;
94 continue;
95 }
96 if (pendingSpace) firstLine += " ";
97 firstLine += character;
98 pendingSpace = false;
99 if (firstLine.length > 160) break;
100 }
101 const last = firstLine.charCodeAt(158);
102 const end = last >= 0xd800 && last <= 0xdbff ? 158 : 159;
103 return {
104 summary: firstLine.length <= 160 ? firstLine : `${firstLine.slice(0, end).trimEnd()}…`,
105 truncated: true,
106 };
107 }
108
109 type CheckpointFiles = Pick<OrchestrationV2Checkpoint, "files" | "filesTotal">;
110
111 // Same input, same output object: snapshot compaction relies on shared item identity.
112 const cappedCheckpointFiles = new WeakMap<object, object>();
113
114 function capCheckpointFiles<T extends CheckpointFiles>(value: T): T {
115 if (value.files.length <= MAX_WIRE_CHECKPOINT_FILES || value.filesTotal !== undefined) {
116 return value;
117 }
118 const cached = cappedCheckpointFiles.get(value);
119 if (cached !== undefined) return cached as T;
120 let additions = 0;
121 let deletions = 0;
122 for (const file of value.files) {
123 additions += file.additions;
124 deletions += file.deletions;
125 }
126 const capped = {
127 ...value,
128 files: value.files.slice(0, MAX_WIRE_CHECKPOINT_FILES),
129 filesTotal: { count: value.files.length, additions, deletions },
130 };
131 cappedCheckpointFiles.set(value, capped);
132 return capped;
133 }
134
135 /** Idempotent; bounded snapshots that skip `projectThreadProjectionForWire` still need it. */
136 export function capProjectionCheckpointFilesForWire(
137 projection: OrchestrationV2ThreadProjection,
138 ): OrchestrationV2ThreadProjection {
139 const checkpoints = projection.checkpoints.map(capCheckpointFiles);
140 const turnItems = projection.turnItems.map(capCheckpointItemFiles);
141 const visibleTurnItems = projection.visibleTurnItems.map((row) => {
142 const item = capCheckpointItemFiles(row.item);
143 return item === row.item ? row : { ...row, item };
144 });
145 const unchanged = (next: ReadonlyArray<unknown>, previous: ReadonlyArray<unknown>) =>
146 next.every((value, index) => value === previous[index]);
147 return unchanged(checkpoints, projection.checkpoints) &&
148 unchanged(turnItems, projection.turnItems) &&
149 unchanged(visibleTurnItems, projection.visibleTurnItems)
150 ? projection
151 : { ...projection, checkpoints, turnItems, visibleTurnItems };
152 }
153
154 function capCheckpointItemFiles(item: OrchestrationV2TurnItem): OrchestrationV2TurnItem {
155 return item.type === "checkpoint" ? capCheckpointFiles(item) : item;
156 }
157
158 export function projectTurnItemForWire(item: OrchestrationV2TurnItem): OrchestrationV2TurnItem {
159 switch (item.type) {
160 case "checkpoint":
161 return capCheckpointFiles(item);
162 case "handoff": {
163 const { summary: _summary, ...projected } = item;
164 return projected;
165 }
166 case "command_execution": {
167 const { output, ...projected } = item;
168 // A successful search can print "ENOENT" or "exit code 2", so output text
169 // decides only when the provider reported no exit code.
170 const failed = commandIndicatesFailure(item);
171 return {
172 ...projected,
173 ...(failed ? { outputIndicatesFailure: true } : {}),
174 ...(output?.trim() ? { outputOmitted: true } : {}),
175 };
176 }
177 case "file_change": {
178 const { diffStr, oldStr: _old, newStr: _new, ...projected } = item;
179 return item.status === "failed" && diffStr?.trim()
180 ? { ...projected, diffStr: truncateDetail(diffStr) }
181 : projected;
182 }
183 case "subagent":
184 return {
185 ...item,
186 prompt: truncateDetail(item.prompt) ?? "",
187 progress: truncateDetail(item.progress),
188 result: item.result === null ? null : (truncateDetail(item.result) ?? null),
189 };
190 case "dynamic_tool": {
191 const { output: rawOutput, ...projected } = item;
192 const output = compactDynamicToolOutput(rawOutput);
193 return {
194 ...projected,
195 input: summarizeDynamicValue(item.input),
196 ...(output === undefined ? {} : { output }),
197 ...(hasDynamicValue(rawOutput) ? { outputOmitted: true } : {}),
198 };
199 }
200 default:
201 return item;
202 }
203 }
204
205 function hasDynamicValue(value: unknown): boolean {
206 if (value === undefined || value === null) return false;
207 if (typeof value === "string") return value.trim().length > 0;
208 if (Array.isArray(value)) return value.length > 0;
209 return typeof value !== "object" || Object.keys(value).length > 0;
210 }
211
212 function boundDynamicValue(value: unknown): unknown {
213 if (value === undefined) return value;
214 if (typeof value === "string") return truncateDetail(value, MAX_ON_DEMAND_BYTES);
215 let json: string;
216 try {
217 json = JSON.stringify(value) ?? String(value);
218 } catch {
219 return "Unserializable tool value";
220 }
221 return Buffer.byteLength(json, "utf8") <= MAX_ON_DEMAND_BYTES
222 ? value
223 : truncateDetail(json, MAX_ON_DEMAND_BYTES);
224 }
225
226 /** Preserve ordered image markers in truncated output so clients can load images by index. */
227 function boundToolResult(output: unknown): unknown {
228 const omitted = omitToolOutputImageData(output);
229 const bounded = boundDynamicValue(omitted);
230 if (typeof bounded !== "string" || typeof omitted === "string") return bounded;
231 const images = toolOutputImages(omitted);
232 return images.length === 0
233 ? bounded
234 : [
235 { type: "text", text: bounded },
236 ...images.map((image) => ({ type: "image", mimeType: image.mimeType })),
237 ];
238 }
239
240 function boundToolOutput(output: unknown): unknown {
241 if (typeof output !== "object" || output === null || !("result" in output)) {
242 return boundToolResult(output);
243 }
244 const app =
245 MCP_APP_OUTPUT_KEY in output ? readMcpAppReference(output[MCP_APP_OUTPUT_KEY]) : undefined;
246 if (app === undefined) return boundToolResult(output);
247 // The app receives this result, so its image data stays unless it is too large to send.
248 const fits = boundDynamicValue(output.result) === output.result;
249 return {
250 [MCP_APP_OUTPUT_KEY]: app,
251 result: fits ? output.result : boundToolResult(output.result),
252 };
253 }
254
255 export function projectTurnItemForDetail(item: OrchestrationV2TurnItem): OrchestrationV2TurnItem {
256 switch (item.type) {
257 case "command_execution":
258 return {
259 ...item,
260 input: truncateDetail(item.input, MAX_ON_DEMAND_BYTES) ?? "",
261 output: truncateDetail(item.output, MAX_ON_DEMAND_BYTES),
262 };
263 case "dynamic_tool":
264 return {
265 ...item,
266 input: boundDynamicValue(item.input),
267 output: boundToolOutput(item.output),
268 };
269 case "subagent":
270 return {
271 ...item,
272 prompt: truncateDetail(item.prompt, MAX_ON_DEMAND_BYTES) ?? "",
273 progress: truncateDetail(item.progress, MAX_ON_DEMAND_BYTES),
274 result:
275 item.result === null ? null : (truncateDetail(item.result, MAX_ON_DEMAND_BYTES) ?? null),
276 };
277 case "file_change":
278 return {
279 ...projectTurnItemForWire(item),
280 ...(item.diffStr === undefined
281 ? {}
282 : { diffStr: truncateDetail(item.diffStr, MAX_ON_DEMAND_BYTES) }),
283 ...(!item.diffStr?.trim() && item.oldStr !== undefined
284 ? { oldStr: truncateDetail(item.oldStr, MAX_ON_DEMAND_BYTES) }
285 : {}),
286 ...(!item.diffStr?.trim() && item.newStr !== undefined
287 ? { newStr: truncateDetail(item.newStr, MAX_ON_DEMAND_BYTES) }
288 : {}),
289 };
290 case "handoff":
291 return projectTurnItemForWire(item);
292 default:
293 return item;
294 }
295 }
296
297 export function projectContextHandoffForWire(
298 handoff: OrchestrationV2ContextHandoff,
299 ): OrchestrationV2ContextHandoff {
300 const { history: _history, delivery: _delivery, ...projected } = handoff;
301 return { ...projected, summaryText: "" };
302 }
303
304 export function projectThreadProjectionForWire(
305 projection: OrchestrationV2ThreadProjection,
306 ): OrchestrationV2ThreadProjection {
307 const projectedById = new Map<string, OrchestrationV2TurnItem>();
308 const project = (item: OrchestrationV2TurnItem) => {
309 const key = `${item.threadId}:${item.id}`;
310 const existing = projectedById.get(key);
311 if (existing !== undefined) return existing;
312 const projected = projectTurnItemForWire(item);
313 projectedById.set(key, projected);
314 return projected;
315 };
316 return {
317 ...projection,
318 checkpoints: projection.checkpoints.map(capCheckpointFiles),
319 contextHandoffs: projection.contextHandoffs.map(projectContextHandoffForWire),
320 turnItems: projection.turnItems.map(project),
321 visibleTurnItems: projection.visibleTurnItems.map((row) => ({
322 ...row,
323 item: project(row.item),
324 })),
325 };
326 }
327
328 export function projectDomainEventForWire(
329 event: OrchestrationV2DomainEvent,
330 ): OrchestrationV2DomainEvent {
331 return event.type === "turn-item.updated"
332 ? { ...event, payload: projectTurnItemForWire(event.payload) }
333 : event.type === "context-handoff.updated"
334 ? { ...event, payload: projectContextHandoffForWire(event.payload) }
335 : event.type === "checkpoint.captured"
336 ? { ...event, payload: capCheckpointFiles(event.payload) }
337 : event;
338 }
339
340 // Keyed on the stored event PubSub hands every subscriber, so all of them share one projection
341 // and LiveStreamBudget sizes it once. Consumers must not mutate the shared result.
342 const projectedStoredEvents = new WeakMap<OrchestrationV2StoredEvent, OrchestrationV2StoredEvent>();
343
344 export function projectStoredEventForWire(
345 stored: OrchestrationV2StoredEvent,
346 ): OrchestrationV2StoredEvent {
347 const cached = projectedStoredEvents.get(stored);
348 if (cached !== undefined) return cached;
349 const event = projectDomainEventForWire(stored.event);
350 if (event === stored.event) return stored;
351 const projected = { ...stored, event };
352 projectedStoredEvents.set(stored, projected);
353 return projected;
354 }
355
356 type ThreadStreamEvent = Extract<OrchestrationV2ThreadStreamItem, { readonly kind: "event" }>;
357
358 const threadStreamEvents = new WeakMap<OrchestrationV2StoredEvent, ThreadStreamEvent>();
359
360 /** For an event already projected for the wire; subscribers share the item and its cached size. */
361 export function threadStreamEventItem(stored: OrchestrationV2StoredEvent): ThreadStreamEvent {
362 const cached = threadStreamEvents.get(stored);
363 if (cached !== undefined) return cached;
364 const item = { kind: "event" as const, sequence: stored.sequence, event: stored.event };
365 threadStreamEvents.set(stored, item);
366 return item;
367 }
368
369 const LIVE_DEDUPE_MEMORY = 32;
370
371 function remember<K, V>(memory: Map<K, V>, key: K, value: V): void {
372 memory.delete(key);
373 memory.set(key, value);
374 if (memory.size > LIVE_DEDUPE_MEMORY) memory.delete(memory.keys().next().value as K);
375 }
376
377 /**
378 * One per subscription, after coalescing, so it remembers only records the client received. A
379 * record event comes before the turn item that repeats its body, so the item (or a repeated
380 * subagent record) ships blank and marked. The other order, or a forgotten record, only costs
381 * bytes: the repeat ships whole.
382 */
383 export function makeLiveBodyDeduper(): (
384 item: OrchestrationV2ThreadStreamItem,
385 ) => OrchestrationV2ThreadStreamItem {
386 const messageText = new Map<MessageId, string>();
387 const checkpointFiles = new Map<CheckpointId, OrchestrationV2Checkpoint["files"]>();
388 const subagents = new Map<NodeId, Pick<OrchestrationV2Subagent, "prompt" | "result">>();
389 const source = {
390 messageText: (id: MessageId) => messageText.get(id),
391 checkpointFiles: (id: CheckpointId) => checkpointFiles.get(id),
392 subagent: (id: NodeId) => subagents.get(id),
393 };
394 const rememberSubagent = ({ id, prompt, result }: OrchestrationV2Subagent) =>
395 remember(subagents, id, { prompt, result });
396 return (item) => {
397 if (item.kind === "snapshot") {
398 // The client now holds exactly these records; their bodies are never blanked.
399 const { messages, checkpoints, subagents: records } = item.projection;
400 for (const message of messages) remember(messageText, message.id, message.text);
401 for (const checkpoint of checkpoints)
402 remember(checkpointFiles, checkpoint.id, checkpoint.files);
403 for (const subagent of records) rememberSubagent(subagent);
404 return item;
405 }
406 if (item.kind !== "event") return item;
407 const { event } = item;
408 switch (event.type) {
409 case "message.updated":
410 remember(messageText, event.payload.id, event.payload.text);
411 return item;
412 case "checkpoint.captured":
413 remember(checkpointFiles, event.payload.id, event.payload.files);
414 return item;
415 case "subagent.updated": {
416 const payload = dedupeSubagentBodies(event.payload, subagents.get(event.payload.id));
417 rememberSubagent(event.payload);
418 return payload === event.payload ? item : { ...item, event: { ...event, payload } };
419 }
420 case "turn-item.updated": {
421 const payload = dedupeTurnItemBodies(event.payload, source);
422 return payload === event.payload ? item : { ...item, event: { ...event, payload } };
423 }
424 default:
425 return item;
426 }
427 };
428 }