Skip to content

Commit 27cde70

Browse files
Alb11747claudecodex
committed
fix(server): a handoff too large for the context window no longer wedges the thread
When a context handoff could not fit the target's context budget, turn start failed with "Insufficient context allowance" on every turn, so the thread was unusable until the user compacted it manually. An oversized handoff is now marked deferred and the turn proceeds without it. Later turns on the same provider thread retry it until it fits, and the flag clears once it is sent. The flag is an additive optional field, so no migration is needed. Fixes #16147 Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-Authored-By: GPT-6.1-Sol at high effort, implementation subagent for handoff deferral <[email protected]>
1 parent 2cde3f7 commit 27cde70

7 files changed

Lines changed: 237 additions & 39 deletions

File tree

‎apps/server/src/orchestration-v2/ContextHandoffBudget.test.ts‎

Lines changed: 79 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import {
1010
ThreadId,
1111
TurnItemId,
1212
OrchestrationV2ContextHandoff,
13+
OrchestrationV2ContextHandoffJson,
1314
type OrchestrationV2HistoricalMessage,
1415
type OrchestrationV2ProviderThread,
1516
} from "@t3tools/contracts";
@@ -29,6 +30,9 @@ import { deliverContextHandoffs } from "./ContextHandoffDelivery.ts";
2930

3031
const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown));
3132
const decodeHandoff = Schema.decodeUnknownSync(OrchestrationV2ContextHandoff);
33+
const handoffJson = Schema.fromJsonString(OrchestrationV2ContextHandoffJson);
34+
const encodeHandoff = Schema.encodeSync(handoffJson);
35+
const decodePersistedHandoff = Schema.decodeSync(handoffJson);
3236

3337
const now = DateTime.makeUnsafe("2026-09-17T00:00:00Z");
3438
const threadId = ThreadId.make("thread:handoff");
@@ -669,23 +673,85 @@ describe("handoff delivery", () => {
669673
}),
670674
);
671675

672-
it.effect("fails before delivery when even the coverage marker cannot fit", () =>
676+
it.effect.each([true, false])(
677+
"retries deferred history until it fits, delivering once (native=%s)",
678+
(native) =>
679+
Effect.gen(function* () {
680+
let durable = handoff;
681+
let calls = 0;
682+
const persisted: OrchestrationV2ContextHandoff[] = [];
683+
const input = {
684+
providerThread,
685+
alreadyDeliveredItemIds: new Set<string>(),
686+
inject: () =>
687+
Effect.sync(() => {
688+
calls++;
689+
return native;
690+
}),
691+
persist: (value: OrchestrationV2ContextHandoff) =>
692+
Effect.sync(() => {
693+
durable = decodePersistedHandoff(encodeHandoff(value));
694+
persisted.push(durable);
695+
}),
696+
};
697+
const first = yield* deliverContextHandoffs({ ...input, handoffs: [durable], budget: 0 });
698+
assert.equal(first.context, "");
699+
yield* first.delivered;
700+
yield* first.unsent;
701+
assert.equal(durable.deferred, true);
702+
assert.isUndefined(persisted[0]!.delivery);
703+
assert.equal(calls, 0);
704+
assert.lengthOf(persisted, 1);
705+
706+
const stillTooSmall = yield* deliverContextHandoffs({
707+
...input,
708+
handoffs: [durable],
709+
budget: 0,
710+
});
711+
assert.equal(stillTooSmall.context, "");
712+
assert.equal(durable.deferred, true);
713+
assert.equal(calls, 0);
714+
assert.lengthOf(persisted, 1);
715+
716+
const fits = yield* deliverContextHandoffs({
717+
...input,
718+
handoffs: [durable],
719+
budget: 16_000,
720+
});
721+
assert.isUndefined(durable.deferred);
722+
assert.equal(fits.context === "", native);
723+
if (!native) assert.include(fits.context, messages[0]!.text);
724+
yield* fits.delivered;
725+
assert.equal(durable.delivery?.status, native ? "injected" : "inline");
726+
const writes = persisted.length;
727+
const later = yield* deliverContextHandoffs({
728+
...input,
729+
handoffs: [durable],
730+
budget: 16_000,
731+
});
732+
assert.equal(later.context, "");
733+
yield* later.delivered;
734+
assert.equal(calls, 1);
735+
assert.lengthOf(persisted, writes);
736+
}),
737+
);
738+
739+
it.effect("stops retrying deferred history sent inline before the native thread exists", () =>
673740
Effect.gen(function* () {
674-
let calls = 0;
675-
const result = yield* deliverContextHandoffs({
676-
handoffs: [handoff],
677-
providerThread,
678-
budget: 0,
741+
let durable: OrchestrationV2ContextHandoff = { ...handoff, deferred: true };
742+
const delivery = yield* deliverContextHandoffs({
743+
handoffs: [durable],
744+
providerThread: { ...providerThread, nativeThreadRef: null },
745+
budget: 16_000,
679746
alreadyDeliveredItemIds: new Set(),
680-
inject: () =>
747+
persist: (value) =>
681748
Effect.sync(() => {
682-
calls++;
683-
return true;
749+
durable = decodePersistedHandoff(encodeHandoff(value));
684750
}),
685-
persist: () => Effect.void,
686-
}).pipe(Effect.result);
687-
assert.equal(result._tag, "Failure");
688-
assert.equal(calls, 0);
751+
});
752+
assert.include(delivery.context, messages[0]!.text);
753+
yield* delivery.delivered;
754+
assert.isUndefined(durable.deferred);
689755
}),
690756
);
691757
});

‎apps/server/src/orchestration-v2/ContextHandoffDelivery.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@ import type {
33
OrchestrationV2ProviderThread,
44
} from "@t3tools/contracts";
55
import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
6-
import { ContextHandoffBudgetError } from "@t3tools/provider-core/server/failure";
76
import * as Effect from "effect/Effect";
87
import * as Schema from "effect/Schema";
98
import {
@@ -81,7 +80,17 @@ export const deliverContextHandoffs = Effect.fn("orchestrationV2.deliverContextH
8180
});
8281
if (historyCost(selected.messages, selected.context) > budget) {
8382
if (input.deferInline) return { context: "", delivered: Effect.void, unsent: Effect.void };
84-
return yield* new ContextHandoffBudgetError();
83+
yield* Effect.forEach(
84+
pending.filter((handoff) => handoff.deferred !== true),
85+
(handoff) => input.persist({ ...handoff, deferred: true }),
86+
{ discard: true },
87+
);
88+
yield* Effect.logDebug("Deferring context handoffs that exceed the delivery budget", {
89+
providerThreadId: input.providerThread.id,
90+
handoffCount: pending.length,
91+
budget,
92+
});
93+
return { context: "", delivered: Effect.void, unsent: Effect.void };
8594
}
8695
const omittedItemIds = new Set(selected.omittedItemIds);
8796
const persist = (status: "pending" | "injected" | "inline") =>
@@ -90,6 +99,8 @@ export const deliverContextHandoffs = Effect.fn("orchestrationV2.deliverContextH
9099
(handoff) =>
91100
input.persist({
92101
...handoff,
102+
// Sent (or possibly sent) now, so later turns must not retry it.
103+
deferred: undefined,
93104
...(nativeThreadId === undefined
94105
? {}
95106
: {

‎apps/server/src/orchestration-v2/ProviderTurnStartService.test.ts‎

Lines changed: 140 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { expect, it, vi } from "vite-plus/test";
22
import { it as effectIt } from "@effect/vitest";
33
import {
44
CheckpointScopeId,
5+
ContextHandoffId,
56
MessageId,
67
NodeId,
78
ProviderSessionId,
@@ -171,6 +172,7 @@ function makeLocalCommandHarness(input: {
171172
readonly writeFailure?: unknown;
172173
/** Loads the thread and starts the run, then fails every later state read. */
173174
readonly failReadsAfterRunning?: boolean;
175+
readonly nativeTurn?: boolean;
174176
}) {
175177
const now = DateTime.makeUnsafe("2026-09-04T12:00:00Z");
176178
const threadId = ThreadId.make("thread-native-account-command");
@@ -393,6 +395,7 @@ function makeLocalCommandHarness(input: {
393395
),
394396
ensureThread: () => Effect.succeed(providerThread),
395397
};
398+
const startTurn = vi.fn((_input: ProviderAdapter.ProviderAdapterV2TurnInput) => Effect.void);
396399
const open = vi.fn(() =>
397400
input.interruptOpen === true
398401
? Effect.interrupt
@@ -414,7 +417,7 @@ function makeLocalCommandHarness(input: {
414417
),
415418
),
416419
)
417-
: input.failReadsAfterRunning === true
420+
: input.failReadsAfterRunning === true || input.nativeTurn === true
418421
? Effect.succeed({
419422
driver: providerThread.driver,
420423
providerSession: {
@@ -430,15 +433,50 @@ function makeLocalCommandHarness(input: {
430433
lastError: null,
431434
},
432435
ensureThread: () => Effect.succeed(providerThread),
436+
resumeThread: () => Effect.succeed(projection.providerThreads.at(-1)!),
437+
startTurn,
433438
} as never)
434439
: Effect.die("A local command must not open a native session."),
435440
);
436-
const startRootRun = vi.fn<
437-
(input: RunExecutionService.RunExecutionServiceV2StartRootRunInput) => Effect.Effect<void>
438-
>(() =>
439-
input.failReadsAfterRunning === true
440-
? Effect.void
441-
: Effect.die("A local command must not start a native turn."),
441+
const startRootRun = vi.fn((turn: RunExecutionService.RunExecutionServiceV2StartRootRunInput) =>
442+
input.nativeTurn === true
443+
? turn.session
444+
.startTurn({
445+
appThread: turn.appThread,
446+
threadId,
447+
runId: turn.run.id,
448+
runOrdinal: turn.run.ordinal,
449+
providerTurnOrdinal: turn.run.ordinal,
450+
attemptId: turn.attemptId,
451+
rootNodeId: turn.rootNode.id,
452+
providerThread: turn.providerThread,
453+
message: {
454+
messageId,
455+
text: input.text,
456+
attachments: [],
457+
createdBy: "user",
458+
creationSource: "web",
459+
},
460+
modelSelection: turn.run.modelSelection,
461+
runtimePolicy: {
462+
cwd: "/tmp/native-account-command",
463+
runtimeMode: "full-access",
464+
interactionMode: "default",
465+
},
466+
})
467+
.pipe(
468+
Effect.mapError(
469+
(cause) =>
470+
new RunExecutionService.RunExecutionStartError({
471+
commandId: turn.commandId,
472+
runId: turn.run.id,
473+
cause,
474+
}),
475+
),
476+
)
477+
: input.failReadsAfterRunning === true
478+
? Effect.void
479+
: Effect.die("A local command must not start a native turn."),
442480
);
443481
const failReadIfRunning = Effect.suspend(() =>
444482
input.failReadsAfterRunning === true &&
@@ -489,7 +527,18 @@ function makeLocalCommandHarness(input: {
489527
Layer.mock(ContextHandoffService.ContextHandoffServiceV2)({
490528
prepareProviderHandoff: () => Effect.die("history read must fail first"),
491529
}),
492-
Layer.mock(EventSink.EventSinkV2)({ writeIfRunCurrent }),
530+
Layer.mock(EventSink.EventSinkV2)({
531+
writeIfRunCurrent,
532+
write: ({ events: incoming }) =>
533+
Effect.sync(() => {
534+
for (const event of incoming) {
535+
expect(isDomainEvent(event)).toBe(true);
536+
events.push(event);
537+
projection = ProjectionStore.applyToProjection(projection, event);
538+
}
539+
return [];
540+
}),
541+
}),
493542
IdAllocator.layer,
494543
FileSystem.layerNoop({}),
495544
Layer.mock(GitWorkflow.GitWorkflowService)({}),
@@ -540,6 +589,12 @@ function makeLocalCommandHarness(input: {
540589
newInstanceId,
541590
attemptId,
542591
projection: () => projection,
592+
updateProjection: (
593+
update: (current: OrchestrationV2ThreadProjection) => OrchestrationV2ThreadProjection,
594+
) => {
595+
projection = update(projection);
596+
},
597+
startTurn,
543598
start: Effect.gen(function* () {
544599
yield* (yield* ProviderTurnStart.ProviderTurnStartServiceV2).start({ threadId, runId });
545600
}).pipe(Effect.provide(layer)),
@@ -553,6 +608,83 @@ function makeLocalCommandHarness(input: {
553608
};
554609
}
555610

611+
effectIt.effect.each([
612+
{ deferred: true, sameThread: true, usedTokens: 0, delivers: true },
613+
{ deferred: true, sameThread: true, usedTokens: 32_000, delivers: false },
614+
{ deferred: true, sameThread: false, usedTokens: 0, delivers: false },
615+
{ deferred: undefined, sameThread: true, usedTokens: 0, delivers: false },
616+
] as const)(
617+
"retries completed ordinary-turn handoffs only when deferred on this provider thread: %j",
618+
(scenario) =>
619+
Effect.gen(function* () {
620+
const harness = makeLocalCommandHarness({ text: "Continue", nativeTurn: true });
621+
harness.updateProjection((projection) => {
622+
const run = projection.runs[0]!;
623+
const providerThread = projection.providerThreads[0]!;
624+
const previousRunId = RunId.make("completed-ordinary-handoff-run");
625+
return {
626+
...projection,
627+
runs: [
628+
{
629+
...run,
630+
id: previousRunId,
631+
ordinal: 1,
632+
status: "completed",
633+
startedAt: run.requestedAt,
634+
completedAt: run.requestedAt,
635+
},
636+
run,
637+
],
638+
providerThreads: [
639+
{
640+
...providerThread,
641+
nativeThreadRef: {
642+
driver: providerThread.driver,
643+
nativeId: "native-handoff-target",
644+
strength: "strong",
645+
},
646+
contextUsage: { usedTokens: scenario.usedTokens, maxTokens: 32_000 },
647+
},
648+
],
649+
contextHandoffs: [
650+
{
651+
id: ContextHandoffId.make("completed-ordinary-handoff"),
652+
threadId: run.threadId,
653+
targetRunId: previousRunId,
654+
fromProviderThreadIds: [],
655+
toProviderThreadId: scenario.sameThread
656+
? providerThread.id
657+
: ProviderThreadId.make("another-provider-thread"),
658+
coveredRunOrdinals: { from: 1, to: 1 },
659+
strategy: "full_thread_summary",
660+
status: "ready",
661+
deferred: scenario.deferred,
662+
summaryMessageId: null,
663+
summaryText: "Remember the original constraints.",
664+
createdByProviderInstanceId: null,
665+
createdAt: run.requestedAt,
666+
updatedAt: run.requestedAt,
667+
},
668+
],
669+
};
670+
});
671+
672+
yield* harness.start;
673+
674+
expect(harness.startTurn).toHaveBeenCalledOnce();
675+
const text = harness.startTurn.mock.calls[0]![0].message.text;
676+
expect(text.includes("Remember the original constraints.")).toBe(scenario.delivers);
677+
expect(text.endsWith("Continue")).toBe(true);
678+
const handoff = harness.projection().contextHandoffs[0]!;
679+
expect(handoff.delivery?.status).toBe(scenario.delivers ? "inline" : undefined);
680+
expect(handoff.deferred).toBe(scenario.delivers ? undefined : scenario.deferred);
681+
expect(harness.projection().runs.at(-1)?.status).toBe("running");
682+
expect(
683+
harness.events.filter((event) => event.type === "context-handoff.updated"),
684+
).toHaveLength(scenario.delivers ? 2 : 0);
685+
}),
686+
);
687+
556688
effectIt.effect("terminalizes a starting run when its provider session cannot open", () =>
557689
Effect.gen(function* () {
558690
const harness = makeLocalCommandHarness({

‎apps/server/src/orchestration-v2/ProviderTurnStartService.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,7 @@ export const layer: Layer.Layer<
243243
(handoff) =>
244244
handoff.status === "ready" &&
245245
(handoff.targetRunId === run.id ||
246+
(handoff.deferred === true && handoff.toProviderThreadId === run.providerThreadId) ||
246247
(handoff.toProviderThreadId === run.providerThreadId &&
247248
projection.runs.some(
248249
(source) =>

‎packages/contracts/src/orchestrationV2.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1025,6 +1025,8 @@ export const OrchestrationV2ContextHandoff = Schema.Struct({
10251025
"manual_context",
10261026
]),
10271027
status: Schema.Literals(["pending", "ready", "failed", "superseded"]),
1028+
// Known unsent because it did not fit; retry on later turns.
1029+
deferred: Schema.optional(Schema.Literal(true)),
10281030
summaryMessageId: Schema.NullOr(MessageId),
10291031
summaryText: Schema.String,
10301032
// Optional fields keep existing preview events and projections readable without a migration.

‎packages/provider-core/src/server/failure.test.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ import {
1616
makeProviderFailureTurnItem,
1717
MAX_PROVIDER_FAILURE_CODE_LENGTH,
1818
MAX_PROVIDER_FAILURE_MESSAGE_LENGTH,
19-
ContextHandoffBudgetError,
2019
} from "./failure.ts";
2120
import * as IdAllocator from "./IdAllocator.ts";
2221
import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
@@ -93,11 +92,11 @@ it("preserves actionable handoff errors wrapped by turn startup", () => {
9392
threadId: ThreadId.make("thread:handoff-error"),
9493
providerThreadId: ProviderThreadId.make("provider-thread:handoff-error"),
9594
runId: RunId.make("run:handoff-error"),
96-
cause: new ContextHandoffBudgetError(),
95+
cause: { _tag: "ContextHandoffDeliveryUncertainError" },
9796
});
9897
assert.equal(
9998
makeProviderFailure({ cause: Cause.fail(cause) }).message,
100-
new ContextHandoffBudgetError().message,
99+
"T3 could not confirm whether conversation history reached the provider. Retry the turn to recover the session.",
101100
);
102101
});
103102

0 commit comments

Comments
 (0)