The best way to control Claude Code, Codex and more from any computer or phone
| 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 | } |