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

main
ts 689 lines 22.4 KB
Raw
1 import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
2 import { assert, describe, it } from "@effect/vitest";
3 import {
4 ContextHandoffId,
5 PROVIDER_SEND_TURN_MAX_ATTACHMENTS,
6 ProviderDriverKind,
7 ProviderInstanceId,
8 ProviderThreadId,
9 RunId,
10 ThreadId,
11 TurnItemId,
12 OrchestrationV2ContextHandoff,
13 type OrchestrationV2HistoricalMessage,
14 type OrchestrationV2ProviderThread,
15 } from "@t3tools/contracts";
16 import * as DateTime from "effect/DateTime";
17 import * as Effect from "effect/Effect";
18 import * as Schema from "effect/Schema";
19 import {
20 contextUsageForHandoff,
21 handoffBudget,
22 handoffCoverage,
23 historyCost,
24 historyResponseItems,
25 selectHistory,
26 historicalMessage,
27 } from "@t3tools/provider-core/server/handoffBudget";
28 import { projectContextHandoffForWire } from "./WireProjection.ts";
29 import { deliverContextHandoffs } from "./ContextHandoffDelivery.ts";
30
31 const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown));
32 const decodeHandoff = Schema.decodeUnknownSync(OrchestrationV2ContextHandoff);
33
34 const now = DateTime.makeUnsafe("2026-09-17T00:00:00Z");
35 const threadId = ThreadId.make("thread:handoff");
36 const providerThread: OrchestrationV2ProviderThread = {
37 id: ProviderThreadId.make("provider-thread:target"),
38 driver: ProviderDriverKind.make("codex"),
39 providerInstanceId: ProviderInstanceId.make("codex"),
40 providerSessionId: null,
41 appThreadId: threadId,
42 ownerNodeId: null,
43 nativeThreadRef: {
44 driver: ProviderDriverKind.make("codex"),
45 strength: "strong",
46 nativeId: "native:target",
47 },
48 nativeConversationHeadRef: null,
49 status: "idle",
50 firstRunOrdinal: null,
51 lastRunOrdinal: null,
52 handoffIds: [],
53 forkedFrom: null,
54 createdAt: now,
55 updatedAt: now,
56 };
57 const message = (
58 id: string,
59 role: "user" | "assistant",
60 text: string,
61 ): OrchestrationV2HistoricalMessage => ({
62 itemId: TurnItemId.make(id),
63 role,
64 text,
65 threadId,
66 runId: RunId.make("run:source"),
67 providerThreadId: ProviderThreadId.make("provider-thread:source"),
68 status: "interrupted",
69 kind: role === "user" ? "user_message" : "assistant_message",
70 });
71 const messages = [
72 message("item:one", "user", "Preserve every line.\n\n And this indentation.\n"),
73 message("item:two", "assistant", "Partial work: 日本語 🧪 مرحبا\n" + "x".repeat(600)),
74 ];
75 const handoff: OrchestrationV2ContextHandoff = {
76 id: ContextHandoffId.make("handoff:one"),
77 threadId,
78 targetRunId: RunId.make("run:target"),
79 fromProviderThreadIds: [],
80 toProviderThreadId: providerThread.id,
81 coveredRunOrdinals: { from: 1, to: 2 },
82 strategy: "full_thread_summary",
83 status: "ready",
84 summaryMessageId: null,
85 summaryText: "",
86 history: {
87 messages,
88 coverage: "Historical context; retrieve thread:handoff with t3_thread_read.",
89 omittedItems: 0,
90 },
91 createdByProviderInstanceId: null,
92 createdAt: now,
93 updatedAt: now,
94 };
95
96 describe("handoff budget", () => {
97 it("keeps old preview handoffs readable and delivery history off the wire", () => {
98 const projected = projectContextHandoffForWire({
99 ...handoff,
100 summaryText: "private transcript and command output",
101 delivery: {
102 nativeThreadId: "native:target",
103 status: "injected",
104 itemIds: [messages[0]!.itemId],
105 },
106 });
107 assert.equal(projected.summaryText, "");
108 assert.isUndefined(projected.history);
109 assert.isUndefined(projected.delivery);
110 assert.equal(decodeHandoff(projected).id, handoff.id);
111 assert.deepEqual(handoff.history?.messages, messages);
112 });
113 it("carries command outcomes as attributed activity and excludes reasoning", () => {
114 const base = {
115 id: TurnItemId.make("item:command"),
116 threadId,
117 runId: RunId.make("run:source"),
118 nodeId: null,
119 providerThreadId: providerThread.id,
120 providerTurnId: null,
121 nativeItemRef: null,
122 parentItemId: null,
123 ordinal: 1,
124 status: "failed" as const,
125 title: null,
126 startedAt: now,
127 completedAt: now,
128 updatedAt: now,
129 };
130 const command = historicalMessage({
131 ...base,
132 type: "command_execution",
133 input: "vp test",
134 output: "Failure near the end: " + "界".repeat(300),
135 exitCode: 1,
136 });
137 assert.equal(command?.role, "assistant");
138 assert.equal(command?.kind, "command_execution");
139 assert.include(command!.text, "Exit code: 1");
140 assert.include(command!.text, "界".repeat(300));
141 assert.equal(
142 historicalMessage({
143 ...base,
144 type: "file_change",
145 fileName: "src/a.ts",
146 changes: [
147 { operation: "update", path: "src/a.ts" },
148 { operation: "add", path: "src/b.ts" },
149 { operation: "update", path: "src/new.ts", oldPath: "src/old.ts" },
150 ],
151 })?.text,
152 "File change: src/a.ts, src/b.ts, src/new.ts",
153 );
154 assert.equal(
155 historicalMessage({ ...base, type: "file_change", fileName: "src/a.ts", changes: [] })?.text,
156 "File change: src/a.ts",
157 );
158 assert.isNull(
159 historicalMessage({
160 ...base,
161 type: "reasoning",
162 text: "private reasoning",
163 streaming: false,
164 }),
165 );
166 assert.equal(historyResponseItems([command!], "Activity")[1]?.type, "message");
167 });
168
169 it("omits oversized multilingual items whole, preserves original constraints and recent work", () => {
170 const candidates = [
171 messages[0]!,
172 message("huge", "assistant", "界🧪".repeat(20_000)),
173 message("old", "assistant", "a".repeat(4_000)),
174 messages[1]!,
175 ];
176 const selected = selectHistory({
177 messages: candidates,
178 coverage: "thread:handoff runs 1-4",
179 budget: 3_000,
180 });
181 assert.deepEqual(selected.messages, messages);
182 assert.equal(selected.omittedItems, 2);
183 assert.isAtMost(historyCost(selected.messages, selected.context), 3_000);
184 });
185
186 it("points history recovery at the omitted items instead of a read from the thread's start", () => {
187 const omitted = message("item:omitted", "assistant", "o".repeat(4_000));
188 const selected = selectHistory({
189 messages: [
190 messages[0]!,
191 omitted,
192 ...Array.from({ length: 3 }, (_, i) => message(`item:recent-${i}`, "assistant", "recent")),
193 ],
194 coverage: handoffCoverage({ threadId, coveredRunOrdinals: { from: 1, to: 46 }, items: [] }),
195 budget: 3_000,
196 });
197 assert.deepEqual(selected.omittedItemIds, [omitted.itemId]);
198 assert.include(selected.context, omitted.itemId);
199 });
200
201 it("counts JSON escaping and UTF-8 bytes across many messages", () => {
202 const candidates = Array.from({ length: 500 }, (_, i) =>
203 message(`item:${i}`, i % 2 ? "assistant" : "user", '\u0000\\"🧪界'.repeat(15)),
204 );
205 for (const budget of [1_024, 4_000, 16_000]) {
206 const selected = selectHistory({
207 messages: candidates,
208 coverage: "Retrieve omitted history",
209 budget,
210 });
211 assert.isAtMost(historyCost(selected.messages, selected.context), budget);
212 assert.isAbove(selected.omittedItems, 0);
213 }
214 });
215
216 it("fits the final envelope at intermediate selected/omitted digit boundaries", () => {
217 const candidates = Array.from({ length: 20 }, (_, index) =>
218 message(`boundary:${index}`, "user", "Short request"),
219 );
220 for (let budget = 4_000; budget <= 9_000; budget++) {
221 const selected = selectHistory({
222 messages: candidates,
223 coverage: "Recover history",
224 omittedItems: 90,
225 budget,
226 });
227 assert.isAtMost(historyCost(selected.messages, selected.context), budget);
228 }
229 });
230
231 it("subtracts native usage, input, attachments, instructions and space for work", () => {
232 const base = {
233 tokenCap: 16_000,
234 userText: "Continue",
235 attachments: [],
236 providerThread,
237 nativeContextEstimate: 0,
238 modelContextWindow: 32_000,
239 };
240 assert.isBelow(handoffBudget(base), 16_000);
241 assert.isBelow(handoffBudget({ ...base, nativeContextEstimate: 8_000 }), handoffBudget(base));
242 assert.equal(handoffBudget({ ...base, userText: "界".repeat(30_000) }), 0);
243 assert.equal(
244 handoffBudget({
245 ...base,
246 providerThread: {
247 ...providerThread,
248 contextUsage: { usedTokens: 23_000, maxTokens: 24_000 },
249 },
250 }),
251 0,
252 );
253 for (const sizeBytes of [100_000, 10 * 1024 * 1024]) {
254 const attachments = [
255 {
256 type: "image",
257 id: "attachment",
258 name: "image.png",
259 mimeType: "image/png",
260 sizeBytes,
261 },
262 ];
263 const withImage = handoffBudget({ ...base, attachments });
264 assert.isAbove(withImage, 4_000);
265 assert.isBelow(withImage, handoffBudget(base));
266 assert.equal(handoffBudget({ ...base, attachments: [...attachments, ...attachments] }), 0);
267 assert.equal(
268 handoffBudget({
269 ...base,
270 tokenCap: 64_000,
271 modelContextWindow: 1_000_000,
272 userText: "x".repeat(70_000),
273 attachments,
274 providerThread: {
275 ...providerThread,
276 contextUsage: { usedTokens: 0, maxTokens: 1_000_000 },
277 },
278 }),
279 64_000,
280 );
281 }
282 assert.equal(handoffBudget({ ...base, tokenCap: 2_000 }), 2_000);
283 // The work reserve never takes more than half of a small local window.
284 for (const [modelContextWindow, nativeContextEstimate, expected] of [
285 [8_192, 0, 4_086],
286 [32_768, 0, 16_758],
287 [131_072, 50_000, 48_294],
288 ] as const) {
289 assert.equal(
290 handoffBudget({ ...base, tokenCap: 64_000, modelContextWindow, nativeContextEstimate }),
291 expected,
292 );
293 }
294 });
295
296 it("keeps measured occupancy across a model change", () => {
297 const previous = {
298 usedTokens: 37_321,
299 maxTokens: 258_400,
300 autoCompactThreshold: 32_000,
301 };
302 assert.isNull(
303 contextUsageForHandoff({
304 sameNativeThread: false,
305 sameSelection: false,
306 reuseTelemetry: false,
307 previousUsage: previous,
308 }),
309 );
310 assert.equal(
311 contextUsageForHandoff({
312 sameNativeThread: true,
313 sameSelection: true,
314 reuseTelemetry: true,
315 previousUsage: previous,
316 }),
317 previous,
318 );
319 assert.deepEqual(
320 contextUsageForHandoff({
321 sameNativeThread: true,
322 sameSelection: false,
323 reuseTelemetry: true,
324 previousUsage: previous,
325 }),
326 { usedTokens: 37_321, maxTokens: 258_400 },
327 );
328 assert.deepEqual(
329 contextUsageForHandoff({
330 sameNativeThread: true,
331 sameSelection: false,
332 reuseTelemetry: false,
333 previousUsage: previous,
334 }),
335 { usedTokens: 37_321, maxTokens: 258_400 },
336 );
337 assert.deepEqual(
338 contextUsageForHandoff({
339 sameNativeThread: true,
340 sameSelection: false,
341 reuseTelemetry: false,
342 previousUsage: { usedTokens: 30_000, maxTokens: 32_000, autoCompactThreshold: 31_000 },
343 knownModelWindow: 1_000_000,
344 }),
345 { usedTokens: 30_000, maxTokens: 1_000_000 },
346 );
347
348 const preserved = contextUsageForHandoff({
349 sameNativeThread: true,
350 sameSelection: false,
351 reuseTelemetry: false,
352 previousUsage: previous,
353 });
354 assert.equal(
355 handoffBudget({
356 tokenCap: 16_000,
357 userText: "Continue work",
358 attachments: [
359 {
360 type: "image",
361 id: "screenshot-a",
362 name: "a.png",
363 mimeType: "image/png",
364 sizeBytes: 100_000,
365 },
366 {
367 type: "image",
368 id: "screenshot-b",
369 name: "b.png",
370 mimeType: "image/png",
371 sizeBytes: 100_000,
372 },
373 ],
374 providerThread: { ...providerThread, contextUsage: preserved },
375 nativeContextEstimate: 0,
376 modelContextWindow: preserved?.maxTokens,
377 }),
378 16_000,
379 );
380 assert.equal(
381 handoffBudget({
382 tokenCap: 16_000,
383 userText: "Continue work",
384 attachments: [],
385 providerThread,
386 nativeContextEstimate: 120_000,
387 }),
388 0,
389 );
390 });
391 it("reserves context for image batches up to the attachment limit, honoring smaller known windows", () => {
392 let previousBudget = 16_000;
393 for (let count = 1; count <= PROVIDER_SEND_TURN_MAX_ATTACHMENTS; count++) {
394 const input = {
395 tokenCap: 16_000,
396 userText: "Compare these screenshots",
397 providerThread,
398 nativeContextEstimate: 0,
399 attachments: Array.from({ length: count }, (_, index) => ({
400 type: "image",
401 id: `image-${index}`,
402 name: "image.png",
403 mimeType: "image/png",
404 sizeBytes: 100_000,
405 })),
406 };
407 const budget = handoffBudget(input);
408 assert.isAtLeast(budget, 0);
409 assert.isAtMost(budget, previousBudget);
410 previousBudget = budget;
411 if (count <= 8) assert.equal(budget, 16_000);
412 if (count === 10) {
413 assert.isAbove(budget, 0);
414 assert.isBelow(budget, 16_000);
415 }
416 if (count === PROVIDER_SEND_TURN_MAX_ATTACHMENTS) assert.equal(budget, 0);
417 if (budget > 0) {
418 const selected = selectHistory({ messages, coverage: "Recover omitted history", budget });
419 assert.isAtMost(historyCost(selected.messages, selected.context), budget);
420 }
421 assert.equal(handoffBudget({ ...input, modelContextWindow: 2_000_000 }), 16_000);
422 // 20k window: half is reserved for work, then 27 prompt bytes and 8,192 per image.
423 const smallWindowBudget = count === 1 ? 1_781 : 0;
424 assert.equal(handoffBudget({ ...input, modelContextWindow: 20_000 }), smallWindowBudget);
425 assert.equal(
426 handoffBudget({
427 ...input,
428 providerThread: { ...providerThread, contextUsage: { usedTokens: 0, maxTokens: 20_000 } },
429 }),
430 smallWindowBudget,
431 );
432 assert.equal(
433 handoffBudget({
434 ...input,
435 modelContextWindow: 1_000_000,
436 providerThread: {
437 ...providerThread,
438 contextUsage: { usedTokens: 0, maxTokens: 1_000_000, autoCompactThreshold: 20_000 },
439 },
440 }),
441 smallWindowBudget,
442 );
443 }
444 });
445 });
446
447 describe("handoff delivery", () => {
448 it.effect.each([
449 { native: true, label: "injected" },
450 { native: false, label: "inline" },
451 ])("records omitted recovery coverage separately from $label text", ({ native }) =>
452 Effect.gen(function* () {
453 const omittedBeforeDelivery = TurnItemId.make("item:omitted-during-preparation");
454 const oversized = message("item:oversized", "user", "x".repeat(20_000));
455 let durable: OrchestrationV2ContextHandoff = {
456 ...handoff,
457 history: {
458 ...handoff.history!,
459 messages: [...messages, oversized],
460 omittedItems: 1,
461 omittedItemIds: [omittedBeforeDelivery],
462 },
463 };
464 const result = yield* deliverContextHandoffs({
465 handoffs: [durable],
466 providerThread,
467 budget: 16_000,
468 alreadyDeliveredItemIds: new Set(),
469 inject: (value) => {
470 assert.include(value.context, "omitted 2 items");
471 assert.notInclude(
472 value.messages.map((item) => item.itemId),
473 oversized.itemId,
474 );
475 return Effect.succeed(native);
476 },
477 persist: (value) =>
478 Effect.sync(() => {
479 durable = value;
480 }),
481 });
482 assert.equal(durable.delivery?.status, native ? "injected" : "pending");
483 yield* result.delivered;
484 assert.equal(durable.delivery?.status, native ? "injected" : "inline");
485 assert.deepEqual(
486 durable.delivery?.itemIds,
487 messages.map((item) => item.itemId),
488 );
489 assert.deepEqual(durable.delivery?.omittedItemIds, [omittedBeforeDelivery, oversized.itemId]);
490 assert.deepEqual(decodeHandoff(durable).delivery, durable.delivery);
491 }),
492 );
493
494 it.effect("persists successful injection before turn start and skips it on retry", () =>
495 Effect.gen(function* () {
496 let durable = handoff;
497 const history: unknown[] = [];
498 const statuses: string[] = [];
499 const input = {
500 providerThread,
501 budget: 16_000,
502 alreadyDeliveredItemIds: new Set<string>(),
503 inject: (value: ProviderAdapter.ProviderAdapterV2HistoricalContext) =>
504 Effect.sync(() => {
505 history.push(...historyResponseItems(value.messages, value.context));
506 return true;
507 }),
508 persist: (value: OrchestrationV2ContextHandoff) =>
509 Effect.sync(() => {
510 durable = value;
511 statuses.push(value.delivery!.status);
512 }),
513 };
514 const first = yield* deliverContextHandoffs({ ...input, handoffs: [durable] });
515 assert.equal(first.context, "");
516 assert.deepEqual(statuses, ["pending", "injected"]);
517 assert.lengthOf(history, 3);
518 const second = yield* deliverContextHandoffs({ ...input, handoffs: [durable] });
519 assert.equal(second.context, "");
520 assert.lengthOf(history, 3);
521 }),
522 );
523
524 it.effect(
525 "uses the same selection on explicit native fallback, marking only accepted input",
526 () =>
527 Effect.gen(function* () {
528 let durable = handoff;
529 const result = yield* deliverContextHandoffs({
530 handoffs: [handoff],
531 providerThread,
532 budget: 16_000,
533 alreadyDeliveredItemIds: new Set(),
534 inject: () => Effect.succeed(false),
535 persist: (value) =>
536 Effect.sync(() => {
537 durable = value;
538 }),
539 });
540 assert.include(result.context, messages[0]!.text);
541 assert.include(result.context, messages[1]!.text);
542 assert.equal(durable.delivery?.status, "pending");
543 yield* result.delivered;
544 assert.equal(durable.delivery?.status, "inline");
545 }),
546 );
547
548 it.effect(
549 "defers unsupported compaction history until a normal turn without marking delivery uncertain",
550 () =>
551 Effect.gen(function* () {
552 let durable = handoff;
553 const persist = (value: OrchestrationV2ContextHandoff) =>
554 Effect.sync(() => {
555 durable = value;
556 });
557 const compact = yield* deliverContextHandoffs({
558 handoffs: [durable],
559 providerThread,
560 budget: 16_000,
561 alreadyDeliveredItemIds: new Set(),
562 deferInline: true,
563 inject: () => Effect.succeed(false),
564 persist,
565 });
566 yield* compact.delivered;
567 assert.equal(compact.context, "");
568 assert.isUndefined((() => durable.delivery)());
569 const next = yield* deliverContextHandoffs({
570 handoffs: [durable],
571 providerThread,
572 budget: 16_000,
573 alreadyDeliveredItemIds: new Set(),
574 inject: () => Effect.succeed(false),
575 persist,
576 });
577 assert.include(next.context, messages[0]!.text);
578 yield* next.delivered;
579 assert.equal(durable.delivery?.status, "inline");
580 }),
581 );
582
583 it.effect("bounds accumulated recovery markers while keeping omitted history discoverable", () =>
584 Effect.gen(function* () {
585 const many = Array.from({ length: 100 }, (_, index) => ({
586 ...handoff,
587 id: ContextHandoffId.make(`handoff:retry:${index}`),
588 }));
589 let captured: ProviderAdapter.ProviderAdapterV2HistoricalContext | undefined;
590 const result = yield* deliverContextHandoffs({
591 handoffs: many,
592 providerThread,
593 budget: 2_500,
594 alreadyDeliveredItemIds: new Set(),
595 inject: (history) =>
596 Effect.sync(() => {
597 captured = history;
598 return true;
599 }),
600 persist: () => Effect.void,
601 });
602 assert.equal(result.context, "");
603 assert.isDefined(captured);
604 assert.include(captured.context, "detailed coverage references omitted");
605 assert.include(captured.context, "t3_thread_read");
606 assert.include(captured.context, threadId);
607 assert.isAtMost(historyCost(captured.messages, captured.context), 2_500);
608 assert.isAbove(captured.messages.length, 0);
609 }),
610 );
611
612 it.effect("does not redeliver after ambiguous injection failure", () =>
613 Effect.gen(function* () {
614 let durable = handoff;
615 let calls = 0;
616 const input = {
617 providerThread,
618 budget: 16_000,
619 alreadyDeliveredItemIds: new Set<string>(),
620 inject: () =>
621 Effect.sync(() => {
622 calls++;
623 }).pipe(Effect.andThen(Effect.fail("connection lost"))),
624 persist: (value: OrchestrationV2ContextHandoff) =>
625 Effect.sync(() => {
626 durable = value;
627 }),
628 };
629 yield* deliverContextHandoffs({ ...input, handoffs: [durable] }).pipe(Effect.result);
630 assert.equal(durable.delivery?.status, "pending");
631 const retry = yield* deliverContextHandoffs({ ...input, handoffs: [durable] }).pipe(
632 Effect.result,
633 );
634 assert.equal(retry._tag, "Failure");
635 assert.equal(calls, 1);
636 }),
637 );
638
639 it.effect("budgets multiple handoffs together and skips previously delivered items", () =>
640 Effect.gen(function* () {
641 const extra = {
642 ...handoff,
643 id: ContextHandoffId.make("handoff:two"),
644 history: {
645 ...handoff.history!,
646 messages: [...messages, message("item:three", "assistant", "Latest result")],
647 },
648 };
649 let delivered: ReadonlyArray<unknown> = [];
650 yield* deliverContextHandoffs({
651 handoffs: [handoff, extra],
652 providerThread,
653 budget: 2_500,
654 alreadyDeliveredItemIds: new Set(["item:one"]),
655 inject: (value) =>
656 Effect.sync(() => {
657 delivered = historyResponseItems(value.messages, value.context);
658 return true;
659 }),
660 persist: () => Effect.void,
661 });
662 const serialized = yield* encodeJson(delivered);
663 assert.isAtMost(Buffer.byteLength(serialized), 2_500);
664 assert.notInclude(serialized, "Preserve every line");
665 assert.equal(serialized.split("Partial work").length - 1, 1);
666 assert.include(serialized, "Latest result");
667 }),
668 );
669
670 it.effect("fails before delivery when even the coverage marker cannot fit", () =>
671 Effect.gen(function* () {
672 let calls = 0;
673 const result = yield* deliverContextHandoffs({
674 handoffs: [handoff],
675 providerThread,
676 budget: 0,
677 alreadyDeliveredItemIds: new Set(),
678 inject: () =>
679 Effect.sync(() => {
680 calls++;
681 return true;
682 }),
683 persist: () => Effect.void,
684 }).pipe(Effect.result);
685 assert.equal(result._tag, "Failure");
686 assert.equal(calls, 0);
687 }),
688 );
689 });