The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 14:30 UTC
fix(server): recover handoffs when target context is exhausted (#25610)
Yash Singh committed
Oct 27, 2026 at 14:44 UTC
07242abff3cf2004a703ae631eae1416574a5f30
10 files changed
+816
-342
apps/server/src/orchestration-v2/Adapters/AcpAdapterV2.test.ts
+111
-1
@@ -909,7 +909,11 @@ describe("AcpAdapterV2", () => {
909
flavor: {
910
driver: ACP_TEST_DRIVER,
911
capabilities: AcpProviderCapabilitiesV2,
912
- makeRuntime: makeMockRuntime({ childProcessSpawner, mockAgentPath, protocolEvents }),
912
+ makeRuntime: makeMockRuntime({
913
+ childProcessSpawner,
914
+ mockAgentPath,
915
+ protocolEvents,
916
+ }),
917
},
918
selfInvocation,
919
});
@@ -2406,6 +2410,99 @@ describe("AcpAdapterV2", () => {
2410
}).pipe(Effect.provide(layerTest), Effect.scoped),
2411
);
2412
2413
+ it.live("creates a fresh ACP identity when recovering an exhausted target", () =>
2414
+ Effect.gen(function* () {
2415
+ const childProcessSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
2416
+ const path = yield* Path.Path;
2417
+ const selfInvocation = yield* resolveSelfInvocation();
2418
+ const mockAgentPath = yield* path.fromFileUrl(
2419
+ new URL("../../../scripts/acp-mock-agent.ts", import.meta.url),
2420
+ );
2421
+ const protocolEvents = yield* Queue.unbounded<EffectAcpProtocol.AcpProtocolLogEvent>();
2422
+ const instanceId = ProviderInstanceId.make("acp-test-exhausted-target");
2423
+ const adapter = yield* makeAcpAdapterV2({
2424
+ instanceId,
2425
+ flavor: {
2426
+ driver: ACP_TEST_DRIVER,
2427
+ capabilities: AcpProviderCapabilitiesV2,
2428
+ makeRuntime: makeMockRuntime({
2429
+ childProcessSpawner,
2430
+ mockAgentPath,
2431
+ protocolEvents,
2432
+ wrapRuntime: (runtime, ordinal) => ({
2433
+ ...runtime,
2434
+ start: () =>
2435
+ runtime.start().pipe(
2436
+ Effect.map((started) => ({
2437
+ ...started,
2438
+ sessionId: `mock-recovery-session-${ordinal}`,
2439
+ })),
2440
+ ),
2441
+ }),
2442
+ }),
2443
+ },
2444
+ selfInvocation,
2445
+ });
2446
+ const threadId = ThreadId.make("thread-acp-exhausted-target");
2447
+ const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
2448
+ runtimeMode: "full-access",
2449
+ interactionMode: "default",
2450
+ cwd: process.cwd(),
2451
+ });
2452
+ const modelSelection = { instanceId, model: "default" } as const;
2453
+ const runtime = yield* adapter.openSession({
2454
+ threadId,
2455
+ providerSessionId: ProviderSessionId.make("provider-session-acp-exhausted-target"),
2456
+ modelSelection,
2457
+ runtimePolicy,
2458
+ });
2459
+ const original = yield* runtime.ensureThread({ threadId, modelSelection, runtimePolicy });
2460
+ yield* runtime.startTurn(
2461
+ makeTurnInput({
2462
+ threadId,
2463
+ providerThread: original,
2464
+ instanceId,
2465
+ runtimePolicy,
2466
+ now: yield* DateTime.now,
2467
+ ordinal: 1,
2468
+ }),
2469
+ );
2470
+ yield* runtime.events.pipe(
2471
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
2472
+ Stream.runDrain,
2473
+ );
2474
+ const replacement = yield* runtime.ensureThread({
2475
+ threadId,
2476
+ modelSelection,
2477
+ runtimePolicy,
2478
+ existingProviderThread: { ...original, nativeThreadRef: null },
2479
+ forceNewNativeThread: true,
2480
+ });
2481
+ assert.notEqual(replacement.nativeThreadRef?.nativeId, original.nativeThreadRef?.nativeId);
2482
+ assert.equal(replacement.id, original.id);
2483
+ assert.equal(replacement.nativeMetadata?.itemIdentityVersion, 2);
2484
+ yield* runtime.startTurn(
2485
+ makeTurnInput({
2486
+ threadId,
2487
+ providerThread: replacement,
2488
+ instanceId,
2489
+ runtimePolicy,
2490
+ now: yield* DateTime.now,
2491
+ ordinal: 2,
2492
+ }),
2493
+ );
2494
+ const events = yield* runtime.events.pipe(
2495
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
2496
+ Stream.runCollect,
2497
+ );
2498
+ assert.isTrue(
2499
+ events.some((event) => event.type === "turn.terminal" && event.status === "completed"),
2500
+ );
2501
+ const methods = yield* pollProtocolMethods(protocolEvents);
2502
+ assert.equal(methods.filter((method) => method === "session/new").length, 2);
2503
+ }).pipe(Effect.provide(layerTest), Effect.scoped),
2504
+ );
2505
+
2506
it.live("preserves new-session fallback when an eager ACP session load is stale", () =>
2507
Effect.gen(function* () {
2508
const childProcessSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -5240,6 +5337,19 @@ describe("AcpAdapterV2", () => {
5337
yield* hasPendingBackgroundWork,
5338
"carryover live subagent must pin hasPendingBackgroundWork after root settle",
5339
);
5340
+ const refusedReplacement = yield* runtime
5341
+ .ensureThread({
5342
+ threadId,
5343
+ modelSelection,
5344
+ runtimePolicy,
5345
+ existingProviderThread: { ...providerThread, nativeThreadRef: null },
5346
+ forceNewNativeThread: true,
5347
+ })
5348
+ .pipe(Effect.flip);
5349
+ assert.equal(refusedReplacement._tag, "ProviderAdapterEnsureThreadError");
5350
+ const preserved = yield* runtime.ensureThread({ threadId, modelSelection, runtimePolicy });
5351
+ assert.equal(preserved.nativeThreadRef?.nativeId, providerThread.nativeThreadRef?.nativeId);
5352
+ assert.isTrue(yield* hasPendingBackgroundWork);
5353
assert.isDefined(sessionUpdateHandler, "session update handler must be wired");
5354
5355
subagentPhase = "complete";
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
+43
-1
@@ -7784,7 +7784,7 @@ describe("ClaudeAdapterV2 background wake turns", () => {
7784
),
7785
);
7786
7787
- it.effect("stops background work after the turn settled", () =>
7787
+ it.effect("preserves settled background work until an explicit stop", () =>
7788
Effect.scoped(
7789
Effect.gen(function* () {
7790
let closes = 0;
@@ -7813,6 +7813,29 @@ describe("ClaudeAdapterV2 background wake turns", () => {
7813
assert.equal(settledThread?.pendingBackgroundTasks?.[0]?.taskId, WAKE_TASK_ID);
7814
assert.isTrue(yield* harness.hasPendingBackgroundWork);
7815
7816
+ const replacementAttempt = yield* harness.runtime
7817
+ .startTurn(
7818
+ makeClaudeTestTurnInput({
7819
+ threadId: harness.threadId,
7820
+ providerThread: {
7821
+ ...harness.providerThread,
7822
+ nativeThreadRef: {
7823
+ ...harness.providerThread.nativeThreadRef!,
7824
+ nativeId: "replacement-session",
7825
+ },
7826
+ },
7827
+ now,
7828
+ attemptId: RunAttemptId.make("attempt-claude-background-replacement"),
7829
+ text: "Continue in a fresh session.",
7830
+ attachments: [],
7831
+ providerTurnOrdinal: 2,
7832
+ }),
7833
+ )
7834
+ .pipe(Effect.result);
7835
+ assert.equal(replacementAttempt._tag, "Failure");
7836
+ assert.equal(closes, 0);
7837
+ assert.isTrue(yield* harness.hasPendingBackgroundWork);
7838
+
7839
yield* harness.runtime.interruptTurn({
7840
providerThread: settledThread ?? harness.providerThread,
7841
providerTurnId: harness.terminalEvents()[0]!.providerTurnId,
@@ -12240,6 +12263,25 @@ describe("ClaudeAdapterV2 background wake turns", () => {
12263
yield* changes.until(() => terminals().length === 1);
12264
const settledTurn = terminals()[0]!;
12265
12266
+ assert.isFalse(yield* runtime.hasPendingBackgroundWorkForThread!(providerThread));
12267
+ assert.isTrue(
12268
+ yield* runtime.hasPendingBackgroundWorkForThread!(providerThread, {
12269
+ includeSubagents: true,
12270
+ }),
12271
+ );
12272
+ assert.isFalse(
12273
+ yield* runtime.hasPendingBackgroundWorkForThread!(
12274
+ {
12275
+ ...providerThread,
12276
+ nativeThreadRef: {
12277
+ ...providerThread.nativeThreadRef!,
12278
+ nativeId: "sibling-native-session",
12279
+ },
12280
+ },
12281
+ { includeSubagents: true },
12282
+ ),
12283
+ );
12284
+
12285
const alternateModel = CLAUDE_TEST_RESTART_MODEL_SELECTION;
12286
const switchTurn = (attempt: string) =>
12287
runtime.startTurn(
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+13
-3
@@ -9692,10 +9692,11 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
9692
return existing;
9693
}
9694
9695
- // Selection changes kill CLI background work; refuse until it finishes or Stop closes the process.
9695
+ // Replacing this thread's process kills its background work, even with a new native identity.
9696
if (
9697
existing !== null &&
9698
- existing.nativeThreadId === nativeThreadId &&
9698
+ (existing.nativeThreadId === nativeThreadId ||
9699
+ existing.lastTurn?.input.threadId === turnInput.threadId) &&
9700
!existing.stopping &&
9701
(yield* liveProcessRunsBackgroundWork(existing))
9702
) {
@@ -10560,11 +10561,20 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
10561
}),
10562
hasPendingBackgroundWorkForThread: Effect.fn(
10563
"ClaudeAdapterV2.hasPendingBackgroundWorkForThread",
10563
- )(function* (providerThread) {
10564
+ )(function* (providerThread, options) {
10565
const nativeThreadId = providerThread.nativeThreadRef?.nativeId;
10566
if (nativeThreadId === undefined || nativeThreadId === null) {
10567
return false;
10568
}
10569
+ if (options?.includeSubagents) {
10570
+ const live = yield* Ref.get(queryContext);
10571
+ if (
10572
+ live?.nativeThreadId === nativeThreadId &&
10573
+ !live.stopping &&
10574
+ (yield* liveProcessRunsBackgroundWork(live))
10575
+ )
10576
+ return true;
10577
+ }
10578
return (
10579
rosterForNativeThread(
10580
yield* Ref.get(pendingBackgroundTasksByNativeThread),
apps/server/src/orchestration-v2/ProviderTurnStartService.ts
+350
-250
@@ -4,6 +4,7 @@ import {
4
CommandId,
5
latestProviderTurnForAttempt,
6
type OrchestrationV2DomainEvent,
7
+ type OrchestrationV2ContextHandoff,
8
type OrchestrationV2ExecutionNode,
9
type OrchestrationV2ProviderThread,
10
type OrchestrationV2Run,
@@ -48,6 +49,7 @@ import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
49
import * as ProjectionStore from "./ProjectionStore.ts";
50
import * as ProviderSessionManager from "./ProviderSessionManager.ts";
51
import {
52
+ ContextHandoffBackgroundWorkError,
53
knownProviderFailureMessage,
54
makeProviderFailure,
55
} from "@t3tools/provider-core/server/failure";
@@ -754,6 +756,279 @@ export const layer: Layer.Layer<
756
});
757
let effectiveHandoffs = handoffs;
758
let resumeFellBack = false;
759
+ const userText = projectComposerContextForProvider({
760
+ text: message.text,
761
+ records: message.context?.records ?? [],
762
+ });
763
+ // Codex and Claude parse /goal from the prompt, so it goes verbatim and history waits a turn.
764
+ const goalDriver = session.driver === "codex" || session.driver === "claudeAgent";
765
+ const goalCommand = goalDriver && parseGoalCommand(message) !== null;
766
+ // The provider turn marks cancellation work delivered; restart continuations use their own text or resume natively.
767
+ const noteContinuation = isRestartNoteContinuation(
768
+ run,
769
+ projection.runs,
770
+ projection.providerTurns,
771
+ projection.attempts,
772
+ );
773
+ const restartCancelledWork = pendingRestartCancelledBackgroundWork({
774
+ runs: projection.runs,
775
+ providerTurns: projection.providerTurns,
776
+ compactionMessageIds: new Set(
777
+ projection.messages
778
+ .filter(
779
+ (candidate) =>
780
+ isCompactionCommandMessage(candidate) ||
781
+ (goalDriver && parseGoalCommand(candidate) !== null),
782
+ )
783
+ .map((candidate) => candidate.id),
784
+ ),
785
+ run,
786
+ attempts: projection.attempts,
787
+ });
788
+ const restartNote =
789
+ restartCancelledWork.length === 0
790
+ ? ""
791
+ : restartCancelledBackgroundWorkNote(restartCancelledWork);
792
+ const tokenCap = yield* handoffTokenCapConfig.pipe(
793
+ Effect.orElseSucceed(() => DEFAULT_HANDOFF_TOKEN_CAP),
794
+ );
795
+ const handoffContextForThread = (loadedProviderThread: OrchestrationV2ProviderThread) => {
796
+ const measuredContext = latestNativeContextUsage(projection, providerThread);
797
+ const previousSelection =
798
+ measuredContext?.modelSelection ??
799
+ projection.runs.findLast(
800
+ (source) =>
801
+ source.ordinal < run.ordinal &&
802
+ source.startedAt !== null &&
803
+ source.providerThreadId === providerThread.id,
804
+ )?.modelSelection;
805
+ const sameSelection =
806
+ previousSelection === undefined ||
807
+ modelSelectionsEqual(previousSelection, run.modelSelection);
808
+ const sameNativeThread =
809
+ loadedProviderThread.nativeThreadRef?.nativeId ===
810
+ providerThread.nativeThreadRef?.nativeId;
811
+ const threadUsage = loadedProviderThread.contextUsage ?? providerThread.contextUsage;
812
+ const previousUsage = measuredContext
813
+ ? { ...threadUsage, ...measuredContext.usage }
814
+ : threadUsage;
815
+ const reuseTelemetry =
816
+ sameSelection ||
817
+ (previousSelection !== undefined &&
818
+ session.canReuseContextUsage?.(previousSelection, run.modelSelection) === true);
819
+ const knownModelWindow = session.getModelContextWindow?.(
820
+ run.modelSelection,
821
+ resolvedRuntimePolicy.cwd,
822
+ );
823
+ const handoffUsage = contextUsageForHandoff({
824
+ sameNativeThread,
825
+ sameSelection,
826
+ reuseTelemetry,
827
+ previousUsage,
828
+ knownModelWindow,
829
+ });
830
+ const settledHandoffs = projection.contextHandoffs.filter(
831
+ (handoff) =>
832
+ handoff.toProviderThreadId === providerThread.id &&
833
+ handoff.delivery?.nativeThreadId === loadedProviderThread.nativeThreadRef?.nativeId &&
834
+ handoff.delivery?.status !== "pending",
835
+ );
836
+ const deliveredItemIds = new Set(
837
+ settledHandoffs.flatMap((handoff) => handoff.delivery?.itemIds ?? []),
838
+ );
839
+ const coveredItemIds = new Set([
840
+ ...deliveredItemIds,
841
+ ...settledHandoffs.flatMap((handoff) => handoff.delivery?.omittedItemIds ?? []),
842
+ ]);
843
+ const deliveredAttemptIds = new Set(
844
+ projection.providerTurns.map((turn) => turn.runAttemptId),
845
+ );
846
+ const acceptedAttempts = projection.attempts.filter(
847
+ (source) =>
848
+ source.providerThreadId === providerThread.id && deliveredAttemptIds.has(source.id),
849
+ );
850
+ const nativeInputRunIds = new Set(
851
+ acceptedAttempts
852
+ .filter(
853
+ (source) =>
854
+ source.nativeThreadId !== undefined &&
855
+ source.nativeThreadId === loadedProviderThread.nativeThreadRef?.nativeId,
856
+ )
857
+ .map((source) => source.runId),
858
+ );
859
+ const legacyInputRunIds = new Set(
860
+ acceptedAttempts
861
+ .filter((source) => source.nativeThreadId === undefined)
862
+ .map((source) => source.runId),
863
+ );
864
+ const legacyRecoveredRunIds = new Set(
865
+ projection.runs
866
+ .filter(
867
+ (source) =>
868
+ source.providerThreadId === providerThread.id &&
869
+ settledHandoffs.some(
870
+ (handoff) =>
871
+ handoff.strategy === "full_thread_summary" &&
872
+ handoff.fromProviderThreadIds.includes(providerThread.id) &&
873
+ source.ordinal >= handoff.coveredRunOrdinals.from &&
874
+ source.ordinal <= handoff.coveredRunOrdinals.to,
875
+ ),
876
+ )
877
+ .map((source) => source.id),
878
+ );
879
+ // Row identity survives recovery; only accepted native input and delivered history occupy the new session.
880
+ const nativeContextEstimate = Effect.gen(function* () {
881
+ return sameNativeThread
882
+ ? (yield* projectionStore.getTurnStartHistory(input.threadId)).reduce((sum, item) => {
883
+ const acceptedNatively =
884
+ item.providerThreadId === providerThread.id &&
885
+ item.runId !== null &&
886
+ (nativeInputRunIds.has(item.runId) ||
887
+ (legacyInputRunIds.has(item.runId) &&
888
+ !coveredItemIds.has(item.id) &&
889
+ !legacyRecoveredRunIds.has(item.runId)));
890
+ if (item.runId === run.id || (!acceptedNatively && !deliveredItemIds.has(item.id)))
891
+ return sum;
892
+ const historical = historicalMessage(item);
893
+ const nativeAttachments =
894
+ item.type === "user_message" && acceptedNatively
895
+ ? attachmentTokenAllowance(item.attachments)
896
+ : 0;
897
+ return (
898
+ sum +
899
+ (historical === null ? 0 : Buffer.byteLength(historical.text)) +
900
+ nativeAttachments
901
+ );
902
+ }, 0)
903
+ : 0;
904
+ });
905
+ const modelContextWindow =
906
+ knownModelWindow ??
907
+ (handoffUsage !== null || reuseTelemetry ? previousUsage?.maxTokens : undefined);
908
+ const budgetProviderThread = {
909
+ ...loadedProviderThread,
910
+ contextUsage: handoffUsage,
911
+ };
912
+ // The resume fallback summary already covers every earlier run in order. A
913
+ // retry copy after it would rank older missed requests as the newest history.
914
+ const missedRuns = projection.runs.filter(
915
+ (source) =>
916
+ !resumeFellBack &&
917
+ source.ordinal < run.ordinal &&
918
+ source.providerThreadId === providerThread.id &&
919
+ (source.status === "failed" || source.status === "interrupted") &&
920
+ !deliveredAttemptIds.has(source.activeAttemptId),
921
+ );
922
+ const missedRunIds = new Set(missedRuns.map((source) => source.id));
923
+ return {
924
+ sameNativeThread,
925
+ handoffUsage,
926
+ deliveredItemIds,
927
+ coveredItemIds,
928
+ acceptedAttempts,
929
+ nativeInputRunIds,
930
+ legacyInputRunIds,
931
+ missedRuns,
932
+ missedRunIds,
933
+ budget: Effect.gen(function* () {
934
+ return handoffBudget({
935
+ tokenCap,
936
+ modelContextWindow,
937
+ userText: restartNote === "" ? userText : `${restartNote}\n\n${userText}`,
938
+ attachments: message.attachments,
939
+ providerThread: budgetProviderThread,
940
+ nativeContextEstimate:
941
+ budgetProviderThread.contextUsage?.usedTokens === undefined
942
+ ? yield* nativeContextEstimate
943
+ : 0,
944
+ });
945
+ }),
946
+ };
947
+ };
948
+ const prepareRetryHandoff = Effect.fn("ProviderTurnStartService.prepareRetryHandoff")(
949
+ function* (context: ReturnType<typeof handoffContextForThread>) {
950
+ const { missedRunIds, coveredItemIds, missedRuns } = context;
951
+ const missedItems =
952
+ missedRunIds.size === 0
953
+ ? []
954
+ : (yield* projectionStore.getTurnStartHistory(input.threadId, [
955
+ ...missedRunIds,
956
+ ])).filter(
957
+ (item) =>
958
+ item.runId !== null &&
959
+ missedRunIds.has(item.runId) &&
960
+ !coveredItemIds.has(item.id) &&
961
+ historicalMessage(item) !== null,
962
+ );
963
+ const retryHandoff =
964
+ missedItems.length === 0
965
+ ? []
966
+ : [
967
+ yield* contextHandoffService.prepareProviderHandoff({
968
+ threadId: projection.thread.id,
969
+ targetRunId: run.id,
970
+ transferId: null,
971
+ fromProviderThreadIds: [providerThread.id],
972
+ toProviderThreadId: providerThread.id,
973
+ fromProviderInstanceId: run.providerInstanceId,
974
+ toProviderInstanceId: run.providerInstanceId,
975
+ coveredRunOrdinals: {
976
+ from: missedRuns[0]!.ordinal,
977
+ to: missedRuns.at(-1)!.ordinal,
978
+ },
979
+ strategy: "delta_since_target_last_seen",
980
+ items: missedItems,
981
+ runs: projection.runs,
982
+ createdAt: yield* DateTime.now,
983
+ }),
984
+ ];
985
+ return retryHandoff;
986
+ },
987
+ );
988
+ const prepareRecoveryHandoff = Effect.fn("ProviderTurnStartService.prepareRecoveryHandoff")(
989
+ function* () {
990
+ const transferId = yield* idAllocator.allocate.contextTransfer({
991
+ sourceThreadId: projection.thread.id,
992
+ targetThreadId: projection.thread.id,
993
+ type: "provider_resume_fallback",
994
+ });
995
+ const createdAt = yield* DateTime.now;
996
+ const handoff = yield* contextHandoffService.prepareProviderHandoff({
997
+ threadId: projection.thread.id,
998
+ targetRunId: run.id,
999
+ transferId,
1000
+ fromProviderThreadIds: [providerThread.id],
1001
+ toProviderThreadId: providerThread.id,
1002
+ fromProviderInstanceId: providerThread.providerInstanceId,
1003
+ toProviderInstanceId: run.providerInstanceId,
1004
+ coveredRunOrdinals: { from: 1, to: Math.max(1, run.ordinal - 1) },
1005
+ strategy: "full_thread_summary",
1006
+ runs: projection.runs,
1007
+ items: (yield* projectionStore.getTurnStartHistory(input.threadId)).filter(
1008
+ (item) =>
1009
+ item.runId === null ||
1010
+ projection.runs.some(
1011
+ (source) => source.id === item.runId && source.ordinal < run.ordinal,
1012
+ ),
1013
+ ),
1014
+ createdAt,
1015
+ });
1016
+ return { handoff, transferId, createdAt };
1017
+ },
1018
+ );
1019
+ const recoveryHandoff = yield* Effect.cached(prepareRecoveryHandoff());
1020
+ const withRecoveryHandoff = (handoff: OrchestrationV2ContextHandoff) => {
1021
+ // Delivery ranks later handoffs as newer history. Pending handoffs from
1022
+ // earlier runs predate this summary; handoffs for this run (provider-switch
1023
+ // delta, merge-back) are newer and must stay last.
1024
+ return [
1025
+ ...effectiveHandoffs.filter((candidate) => candidate.targetRunId !== run.id),
1026
+ handoff,
1027
+ ...effectiveHandoffs.filter((candidate) => candidate.targetRunId === run.id),
1028
+ ];
1029
+ };
1030
+ let resumedRetryHandoff: ReadonlyArray<OrchestrationV2ContextHandoff> | undefined;
1031
+ let resumedHandoffContext: ReturnType<typeof handoffContextForThread> | undefined;
1032
const loadedProviderThread = yield* Effect.gen(function* () {
1033
if (nativeForkTransfer !== undefined) {
1034
const sourceProjection = yield* projectionStore.getThreadRecords(
@@ -831,15 +1106,71 @@ export const layer: Layer.Layer<
1106
}),
1107
);
1108
if (resumed._tag === "Success") {
834
- return resumed.success;
1109
+ const context = handoffContextForThread(resumed.success);
1110
+ context.budget = yield* Effect.cached(context.budget);
1111
+ resumedHandoffContext = context;
1112
+ resumedRetryHandoff = yield* prepareRetryHandoff(context);
1113
+ const fits = yield* deliverContextHandoffs({
1114
+ handoffs: [...handoffs, ...resumedRetryHandoff],
1115
+ providerThread: { ...resumed.success, id: providerThread.id },
1116
+ budget: context.budget,
1117
+ deferInline: isCompactionCommandMessage(message) || goalCommand,
1118
+ alreadyDeliveredItemIds: context.deliveredItemIds,
1119
+ persist: () => Effect.void,
1120
+ }).pipe(
1121
+ Effect.as(true),
1122
+ Effect.catchTags({ ContextHandoffBudgetError: () => Effect.succeed(false) }),
1123
+ );
1124
+ if (fits) return resumed.success;
1125
+ const freshThread = { ...resumed.success, nativeThreadRef: null };
1126
+ const freshContext = handoffContextForThread(freshThread);
1127
+ const { handoff } = yield* recoveryHandoff;
1128
+ const fitsFresh = yield* deliverContextHandoffs({
1129
+ handoffs: withRecoveryHandoff(handoff),
1130
+ providerThread: freshThread,
1131
+ budget: freshContext.budget,
1132
+ alreadyDeliveredItemIds: freshContext.deliveredItemIds,
1133
+ persist: () => Effect.void,
1134
+ }).pipe(
1135
+ Effect.as(true),
1136
+ Effect.catchTags({ ContextHandoffBudgetError: () => Effect.succeed(false) }),
1137
+ );
1138
+ if (!fitsFresh) return resumed.success;
1139
+ const hasPendingWork = yield* (
1140
+ session.hasPendingBackgroundWorkForThread?.(resumed.success, {
1141
+ includeSubagents: true,
1142
+ }) ??
1143
+ session.hasPendingBackgroundWork ??
1144
+ Effect.succeed(false)
1145
+ );
1146
+ if (hasPendingWork) {
1147
+ return yield* loadFromProvider(
1148
+ Effect.fail(
1149
+ new ProviderAdapter.ProviderAdapterTurnStartError({
1150
+ driver: session.driver,
1151
+ threadId: projection.thread.id,
1152
+ providerThreadId: providerThread.id,
1153
+ runId,
1154
+ cause: new ContextHandoffBackgroundWorkError(),
1155
+ }),
1156
+ ),
1157
+ );
1158
+ }
1159
}
1160
+ resumedHandoffContext = undefined;
1161
+ resumedRetryHandoff = [];
1162
+ if (!(yield* isCurrentAttemptInStatus("starting"))) return undefined;
1163
837
- yield* Effect.logWarning("Provider resume failed; attempting a fresh native session", {
1164
+ yield* Effect.logWarning("Recovering provider context in a fresh native session", {
1165
driver: session.driver,
1166
providerThreadId: providerThread.id,
1167
runId,
841
- reason: uncertainDelivery ? "uncertain_history_delivery" : "resume_failed",
842
- errorTag: resumed.failure._tag,
1168
+ reason: uncertainDelivery
1169
+ ? "uncertain_history_delivery"
1170
+ : resumed._tag === "Success"
1171
+ ? "handoff_budget_exhausted"
1172
+ : "resume_failed",
1173
+ errorTag: resumed._tag === "Failure" ? resumed.failure._tag : "ContextHandoffBudgetError",
1174
});
1175
const replacement = yield* loadFromProvider(
1176
session.ensureThread({
@@ -850,43 +1181,12 @@ export const layer: Layer.Layer<
1181
providerSessionId,
1182
// Clear the native ref to force a fresh session while preserving row identity.
1183
existingProviderThread: { ...providerThread, nativeThreadRef: null },
1184
+ forceNewNativeThread: true,
1185
}),
1186
);
1187
if (replacement === undefined) return undefined;
856
- const transferId = yield* idAllocator.allocate.contextTransfer({
857
- sourceThreadId: projection.thread.id,
858
- targetThreadId: projection.thread.id,
859
- type: "provider_resume_fallback",
860
- });
861
- const createdAt = yield* DateTime.now;
862
- const handoff = yield* contextHandoffService.prepareProviderHandoff({
863
- threadId: projection.thread.id,
864
- targetRunId: run.id,
865
- transferId,
866
- fromProviderThreadIds: [providerThread.id],
867
- toProviderThreadId: providerThread.id,
868
- fromProviderInstanceId: providerThread.providerInstanceId,
869
- toProviderInstanceId: run.providerInstanceId,
870
- coveredRunOrdinals: { from: 1, to: Math.max(1, run.ordinal - 1) },
871
- strategy: "full_thread_summary",
872
- runs: projection.runs,
873
- items: (yield* projectionStore.getTurnStartHistory(input.threadId)).filter(
874
- (item) =>
875
- item.runId === null ||
876
- projection.runs.some(
877
- (source) => source.id === item.runId && source.ordinal < run.ordinal,
878
- ),
879
- ),
880
- createdAt,
881
- });
882
- // Delivery ranks later handoffs as newer history. Pending handoffs from
883
- // earlier runs predate this summary; handoffs for this run (provider-switch
884
- // delta, merge-back) are newer and must stay last.
885
- effectiveHandoffs = [
886
- ...effectiveHandoffs.filter((candidate) => candidate.targetRunId !== run.id),
887
- handoff,
888
- ...effectiveHandoffs.filter((candidate) => candidate.targetRunId === run.id),
889
- ];
1188
+ const { handoff, transferId, createdAt } = yield* recoveryHandoff;
1189
+ effectiveHandoffs = withRecoveryHandoff(handoff);
1190
resumeFellBack = true;
1191
yield* eventSink.write({
1192
events: [
@@ -934,39 +1234,17 @@ export const layer: Layer.Layer<
1234
return;
1235
}
1236
const now = yield* DateTime.now;
937
- const measuredContext = latestNativeContextUsage(projection, providerThread);
938
- const previousSelection =
939
- measuredContext?.modelSelection ??
940
- projection.runs.findLast(
941
- (source) =>
942
- source.ordinal < run.ordinal &&
943
- source.startedAt !== null &&
944
- source.providerThreadId === providerThread.id,
945
- )?.modelSelection;
946
- const sameSelection =
947
- previousSelection === undefined ||
948
- modelSelectionsEqual(previousSelection, run.modelSelection);
949
- const sameNativeThread =
950
- loadedProviderThread.nativeThreadRef?.nativeId === providerThread.nativeThreadRef?.nativeId;
951
- const threadUsage = loadedProviderThread.contextUsage ?? providerThread.contextUsage;
952
- const previousUsage = measuredContext
953
- ? { ...threadUsage, ...measuredContext.usage }
954
- : threadUsage;
955
- const reuseTelemetry =
956
- sameSelection ||
957
- (previousSelection !== undefined &&
958
- session.canReuseContextUsage?.(previousSelection, run.modelSelection) === true);
959
- const knownModelWindow = session.getModelContextWindow?.(
960
- run.modelSelection,
961
- resolvedRuntimePolicy.cwd,
962
- );
963
- const handoffUsage = contextUsageForHandoff({
1237
+ const handoffContext = resumedHandoffContext ?? handoffContextForThread(loadedProviderThread);
1238
+ const {
1239
sameNativeThread,
965
- sameSelection,
966
- reuseTelemetry,
967
- previousUsage,
968
- knownModelWindow,
969
- });
1240
+ handoffUsage,
1241
+ deliveredItemIds,
1242
+ acceptedAttempts,
1243
+ nativeInputRunIds,
1244
+ legacyInputRunIds,
1245
+ budget,
1246
+ } = handoffContext;
1247
+ const retryHandoff = resumedRetryHandoff ?? (yield* prepareRetryHandoff(handoffContext));
1248
const runningProviderThread: OrchestrationV2ProviderThread = {
1249
...loadedProviderThread,
1250
contextUsage: handoffUsage,
@@ -1094,191 +1372,13 @@ export const layer: Layer.Layer<
1372
const routableSubagents = projection.subagents.filter((subagent) =>
1373
RunExecutionService.canRouteRelatedSubagent(subagent.status),
1374
);
1097
- const userText = projectComposerContextForProvider({
1098
- text: message.text,
1099
- records: message.context?.records ?? [],
1100
- });
1101
- // Codex and Claude parse /goal from the prompt, so it goes verbatim and history waits a turn.
1102
- const goalDriver = session.driver === "codex" || session.driver === "claudeAgent";
1103
- const goalCommand = goalDriver && parseGoalCommand(message) !== null;
1104
- // The provider turn marks cancellation work delivered; restart continuations use their own text or resume natively.
1105
- const noteContinuation = isRestartNoteContinuation(
1106
- run,
1107
- projection.runs,
1108
- projection.providerTurns,
1109
- projection.attempts,
1110
- );
1111
- const restartCancelledWork = pendingRestartCancelledBackgroundWork({
1112
- runs: projection.runs,
1113
- providerTurns: projection.providerTurns,
1114
- compactionMessageIds: new Set(
1115
- projection.messages
1116
- .filter(
1117
- (candidate) =>
1118
- isCompactionCommandMessage(candidate) ||
1119
- (goalDriver && parseGoalCommand(candidate) !== null),
1120
- )
1121
- .map((candidate) => candidate.id),
1122
- ),
1123
- run,
1124
- attempts: projection.attempts,
1125
- });
1126
- const restartNote =
1127
- restartCancelledWork.length === 0
1128
- ? ""
1129
- : restartCancelledBackgroundWorkNote(restartCancelledWork);
1130
- const tokenCap = yield* handoffTokenCapConfig.pipe(
1131
- Effect.orElseSucceed(() => DEFAULT_HANDOFF_TOKEN_CAP),
1132
- );
1133
- const settledHandoffs = projection.contextHandoffs.filter(
1134
- (handoff) =>
1135
- handoff.toProviderThreadId === providerThread.id &&
1136
- handoff.delivery?.nativeThreadId === runningProviderThread.nativeThreadRef?.nativeId &&
1137
- handoff.delivery?.status !== "pending",
1138
- );
1139
- const deliveredItemIds = new Set(
1140
- settledHandoffs.flatMap((handoff) => handoff.delivery?.itemIds ?? []),
1141
- );
1142
- const coveredItemIds = new Set([
1143
- ...deliveredItemIds,
1144
- ...settledHandoffs.flatMap((handoff) => handoff.delivery?.omittedItemIds ?? []),
1145
- ]);
1146
- const deliveredAttemptIds = new Set(
1147
- projection.providerTurns.map((turn) => turn.runAttemptId),
1148
- );
1149
- const acceptedAttempts = projection.attempts.filter(
1150
- (source) =>
1151
- source.providerThreadId === providerThread.id && deliveredAttemptIds.has(source.id),
1152
- );
1153
- const nativeInputRunIds = new Set(
1154
- acceptedAttempts
1155
- .filter(
1156
- (source) =>
1157
- source.nativeThreadId !== undefined &&
1158
- source.nativeThreadId === runningProviderThread.nativeThreadRef?.nativeId,
1159
- )
1160
- .map((source) => source.runId),
1161
- );
1162
- const legacyInputRunIds = new Set(
1163
- acceptedAttempts
1164
- .filter((source) => source.nativeThreadId === undefined)
1165
- .map((source) => source.runId),
1166
- );
1167
- const legacyRecoveredRunIds = new Set(
1168
- projection.runs
1169
- .filter(
1170
- (source) =>
1171
- source.providerThreadId === providerThread.id &&
1172
- settledHandoffs.some(
1173
- (handoff) =>
1174
- handoff.strategy === "full_thread_summary" &&
1175
- handoff.fromProviderThreadIds.includes(providerThread.id) &&
1176
- source.ordinal >= handoff.coveredRunOrdinals.from &&
1177
- source.ordinal <= handoff.coveredRunOrdinals.to,
1178
- ),
1179
- )
1180
- .map((source) => source.id),
1181
- );
1182
- // Legacy attempts lack native ids; exclude recovered attachments absent from the replacement thread.
1183
- const nativeContextEstimate = Effect.gen(function* () {
1184
- return sameNativeThread
1185
- ? (yield* projectionStore.getTurnStartHistory(input.threadId)).reduce((sum, item) => {
1186
- if (
1187
- item.runId === run.id ||
1188
- (item.runId !== null &&
1189
- missedRunIds.has(item.runId) &&
1190
- !deliveredItemIds.has(item.id)) ||
1191
- (item.providerThreadId !== providerThread.id && !deliveredItemIds.has(item.id))
1192
- )
1193
- return sum;
1194
- const historical = historicalMessage(item);
1195
- const nativeAttachments =
1196
- item.type === "user_message" &&
1197
- item.providerThreadId === providerThread.id &&
1198
- item.runId !== null &&
1199
- (nativeInputRunIds.has(item.runId) ||
1200
- (legacyInputRunIds.has(item.runId) &&
1201
- !coveredItemIds.has(item.id) &&
1202
- !legacyRecoveredRunIds.has(item.runId)))
1203
- ? attachmentTokenAllowance(item.attachments)
1204
- : 0;
1205
- return (
1206
- sum +
1207
- (historical === null ? 0 : Buffer.byteLength(historical.text)) +
1208
- nativeAttachments
1209
- );
1210
- }, 0)
1211
- : 0;
1212
- });
1213
- const modelContextWindow =
1214
- knownModelWindow ??
1215
- (handoffUsage !== null || reuseTelemetry ? previousUsage?.maxTokens : undefined);
1216
- const budgetProviderThread = {
1217
- ...runningProviderThread,
1218
- contextUsage: handoffUsage,
1219
- };
1220
- // The resume fallback summary already covers every earlier run in order. A
1221
- // retry copy after it would rank older missed requests as the newest history.
1222
- const missedRuns = projection.runs.filter(
1223
- (source) =>
1224
- !resumeFellBack &&
1225
- source.ordinal < run.ordinal &&
1226
- source.providerThreadId === providerThread.id &&
1227
- (source.status === "failed" || source.status === "interrupted") &&
1228
- !deliveredAttemptIds.has(source.activeAttemptId),
1229
- );
1230
- const missedRunIds = new Set(missedRuns.map((source) => source.id));
1231
- const missedItems =
1232
- missedRunIds.size === 0
1233
- ? []
1234
- : (yield* projectionStore.getTurnStartHistory(input.threadId, [...missedRunIds])).filter(
1235
- (item) =>
1236
- item.runId !== null &&
1237
- missedRunIds.has(item.runId) &&
1238
- !coveredItemIds.has(item.id) &&
1239
- historicalMessage(item) !== null,
1240
- );
1375
const startWithHandoffs = Effect.fn("ProviderTurnStartService.startWithHandoffs")(
1376
function* (turnInput: Parameters<typeof session.startTurn>[0], compact = false) {
1243
- const retryHandoff =
1244
- missedItems.length === 0
1245
- ? []
1246
- : [
1247
- yield* contextHandoffService.prepareProviderHandoff({
1248
- threadId: projection.thread.id,
1249
- targetRunId: run.id,
1250
- transferId: null,
1251
- fromProviderThreadIds: [providerThread.id],
1252
- toProviderThreadId: providerThread.id,
1253
- fromProviderInstanceId: run.providerInstanceId,
1254
- toProviderInstanceId: run.providerInstanceId,
1255
- coveredRunOrdinals: {
1256
- from: missedRuns[0]!.ordinal,
1257
- to: missedRuns.at(-1)!.ordinal,
1258
- },
1259
- strategy: "delta_since_target_last_seen",
1260
- items: missedItems,
1261
- runs: projection.runs,
1262
- createdAt: yield* DateTime.now,
1263
- }),
1264
- ];
1377
const delivery = yield* deliverContextHandoffs({
1378
handoffs: [...effectiveHandoffs, ...retryHandoff],
1379
deferInline: compact || goalCommand,
1380
providerThread: runningProviderThread,
1269
- budget: Effect.gen(function* () {
1270
- return handoffBudget({
1271
- tokenCap,
1272
- modelContextWindow,
1273
- userText: restartNote === "" ? userText : `${restartNote}\n\n${userText}`,
1274
- attachments: message.attachments,
1275
- providerThread: budgetProviderThread,
1276
- nativeContextEstimate:
1277
- budgetProviderThread.contextUsage?.usedTokens === undefined
1278
- ? yield* nativeContextEstimate
1279
- : 0,
1280
- });
1281
- }),
1381
+ budget,
1382
alreadyDeliveredItemIds: deliveredItemIds,
1383
...(session.injectHistory === undefined
1384
? {}
@@ -1361,7 +1461,7 @@ export const layer: Layer.Layer<
1461
);
1462
const deliverySession =
1463
effectiveHandoffs.length === 0 &&
1364
- missedItems.length === 0 &&
1464
+ retryHandoff.length === 0 &&
1465
restartNote === "" &&
1466
!noteContinuation
1467
? session
apps/server/src/orchestration-v2/testkit/ProviderSwitch.integration.test.ts
+168
-13
@@ -115,6 +115,8 @@ function makeTestAdapter(input: {
115
readonly failedRunOrdinals?: ReadonlySet<number>;
116
readonly interruptedRunOrdinals?: ReadonlySet<number>;
117
readonly holdRunOrdinal?: number;
118
+ readonly pendingBackgroundWork?: Ref.Ref<boolean>;
119
+ readonly subagentOnlyBackgroundWork?: boolean;
120
readonly holdFirstTurn?: Deferred.Deferred<void>;
121
readonly releaseFirstTurn?: Deferred.Deferred<void>;
122
}): ProviderAdapter.ProviderAdapterV2["Service"] {
@@ -146,6 +148,14 @@ function makeTestAdapter(input: {
148
providerSessionId: sessionInput.providerSessionId,
149
providerSession,
150
events: Stream.fromPubSub(events),
151
+ ...(input.pendingBackgroundWork === undefined
152
+ ? {}
153
+ : {
154
+ hasPendingBackgroundWorkForThread: (_thread, options) =>
155
+ input.subagentOnlyBackgroundWork && options?.includeSubagents !== true
156
+ ? Effect.succeed(false)
157
+ : Ref.get(input.pendingBackgroundWork!),
158
+ }),
159
...(input.getModelContextWindow === undefined
160
? {}
161
: { getModelContextWindow: input.getModelContextWindow }),
@@ -419,6 +429,13 @@ describe("orchestration v2 provider switching", () => {
429
"screenshot-fallback",
430
"screenshot-reported-capacity-native",
431
"screenshot-option-change-retry-native",
432
+ "screenshot-exhausted-target-native",
433
+ "screenshot-exhausted-target-fallback",
434
+ "screenshot-exhausted-target-estimate-native",
435
+ "screenshot-exhausted-target-oversized-native",
436
+ "screenshot-exhausted-target-tight-native",
437
+ "screenshot-exhausted-target-background-native",
438
+ "screenshot-exhausted-target-subagent-native",
439
"prior-images-reasoning-change-replacement-small-native",
440
"imported-prior-images-fallback",
441
"prior-images-telemetry-native",
@@ -438,11 +455,16 @@ describe("orchestration v2 provider switching", () => {
455
const failStartOnce = yield* Ref.make(false);
456
const failResumeOnce = yield* Ref.make(false);
457
const generation = yield* Ref.make(0);
458
+ const pendingBackgroundWork = yield* Ref.make(false);
459
const priorImages = scenario.includes("prior-images");
460
+ const exhaustedTarget = scenario.includes("exhausted-target");
461
const replaceNative = scenario.includes("replacement");
462
const capacityScenario = modelScenario || scenario.includes("reported-capacity");
463
const returning =
445
- scenario === "large-current-input" || scenario.includes("-change-") || priorImages;
464
+ scenario === "large-current-input" ||
465
+ scenario.includes("-change-") ||
466
+ priorImages ||
467
+ exhaustedTarget;
468
const targetSelection: ModelSelection = !modelScenario
469
? CLAUDE_MODEL_SELECTION
470
: {
@@ -467,10 +489,19 @@ describe("orchestration v2 provider switching", () => {
489
driver: CLAUDE_DRIVER,
490
capabilities: ClaudeProviderCapabilitiesV2,
491
modelSelection: CLAUDE_MODEL_SELECTION,
470
- responseByRunOrdinal: {},
492
+ responseByRunOrdinal: scenario.includes("target-estimate")
493
+ ? { 2: "x".repeat(10_000) }
494
+ : {},
495
capturedTurns,
496
...(scenario.includes("retry") || scenario.includes("unsent") ? { failStartOnce } : {}),
497
...(replaceNative ? { failResumeOnce, nativeThreadGeneration: generation } : {}),
498
+ ...(exhaustedTarget ? { nativeThreadGeneration: generation } : {}),
499
+ ...(scenario.includes("target-background") || scenario.includes("target-subagent")
500
+ ? {
501
+ pendingBackgroundWork,
502
+ subagentOnlyBackgroundWork: scenario.includes("target-subagent"),
503
+ }
504
+ : {}),
505
...(scenario.includes("reported-capacity")
506
? { initialContextUsage: { usedTokens: 999_999, maxTokens: 1_000_000 } }
507
: {}),
@@ -498,8 +529,11 @@ describe("orchestration v2 provider switching", () => {
529
? 1_000_000
530
: 32_000,
531
}
501
- : scenario === "large-current-input" || priorImages
502
- ? { getModelContextWindow: () => 32_000 }
532
+ : scenario === "large-current-input" || priorImages || exhaustedTarget
533
+ ? {
534
+ getModelContextWindow: () =>
535
+ scenario.includes("target-tight") ? 25_121 : 32_000,
536
+ }
537
: {}),
538
...(scenario.endsWith("-native") || scenario === "large-current-input"
539
? { injectedHistory }
@@ -546,7 +580,9 @@ describe("orchestration v2 provider switching", () => {
580
}))
581
: turnUsageScenario && ordinal >= targetOrdinal
582
? [screenshot, { ...screenshot, id: "current-2" }]
549
- : scenario.startsWith("screenshot") && ordinal >= targetOrdinal
583
+ : scenario.startsWith("screenshot") &&
584
+ ordinal >= targetOrdinal &&
585
+ (!exhaustedTarget || ordinal === targetOrdinal)
586
? screenshots
587
: priorImages && ordinal === (scenario.startsWith("imported") ? 1 : 2)
588
? [screenshot]
@@ -602,19 +638,49 @@ describe("orchestration v2 provider switching", () => {
638
yield* Effect.addFinalizer(() => Effect.sync(() => spy?.mockRestore()));
639
const current = scenario.startsWith("compact")
640
? "/compact"
605
- : capacityScenario && !turnUsageScenario
606
- ? "x".repeat(70_000)
607
- : scenario === "large-current-input"
608
- ? "x".repeat(9_000)
609
- : "Continue work";
641
+ : scenario.includes("target-oversized")
642
+ ? "x".repeat(40_000)
643
+ : capacityScenario && !turnUsageScenario
644
+ ? "x".repeat(70_000)
645
+ : scenario === "large-current-input"
646
+ ? "x".repeat(9_000)
647
+ : "Continue work";
648
if (returning) {
649
if (scenario.includes("unsent")) yield* Ref.set(failStartOnce, true);
650
yield* dispatch(
651
2,
614
- turnUsageScenario ? "x".repeat(27_460) : "Establish target",
652
+ turnUsageScenario
653
+ ? "x".repeat(27_460)
654
+ : scenario.includes("target-estimate")
655
+ ? "x".repeat(12_000)
656
+ : "Establish target",
657
CLAUDE_MODEL_SELECTION,
658
);
659
yield* wait(2);
660
+ if (exhaustedTarget) {
661
+ assert.equal(
662
+ (yield* orchestrator.getThreadProjection(threadId)).runs.at(-1)?.status,
663
+ "completed",
664
+ );
665
+ }
666
+ if (exhaustedTarget && !scenario.includes("target-estimate")) {
667
+ const target = (yield* orchestrator.getThreadProjection(
668
+ threadId,
669
+ )).providerThreads.find(
670
+ (thread) => thread.providerInstanceId === CLAUDE_MODEL_SELECTION.instanceId,
671
+ )!;
672
+ yield* eventSink.write({
673
+ events: [
674
+ {
675
+ id: EventId.make("exhausted-target-usage"),
676
+ type: "provider-thread.updated",
677
+ threadId,
678
+ occurredAt: yield* DateTime.now,
679
+ payload: { ...target, contextUsage: { usedTokens: 30_000, maxTokens: 32_000 } },
680
+ },
681
+ ],
682
+ });
683
+ }
684
if (modelScenario && !turnUsageScenario) {
685
const target = (yield* orchestrator.getThreadProjection(
686
threadId,
@@ -695,6 +761,8 @@ describe("orchestration v2 provider switching", () => {
761
yield* Ref.set(failResumeOnce, true);
762
}
763
if (scenario.includes("retry")) yield* Ref.set(failStartOnce, true);
764
+ if (scenario.includes("target-background") || scenario.includes("target-subagent"))
765
+ yield* Ref.set(pendingBackgroundWork, true);
766
yield* dispatch(targetOrdinal, current, targetSelection);
767
yield* wait(targetOrdinal);
768
if (scenario.includes("retry")) {
@@ -780,7 +848,73 @@ describe("orchestration v2 provider switching", () => {
848
yield* wait(targetOrdinal + 3);
849
}
850
const projection = yield* orchestrator.getThreadProjection(threadId);
851
+ if (
852
+ scenario.includes("target-oversized") ||
853
+ scenario.includes("target-tight") ||
854
+ scenario.includes("target-background") ||
855
+ scenario.includes("target-subagent")
856
+ ) {
857
+ assert.equal(projection.runs.at(-1)?.status, "failed");
858
+ assert.equal(yield* Ref.get(generation), 1);
859
+ assert.equal(projection.messages.at(-1)!.text, current);
860
+ assert.deepEqual(projection.messages.at(-1)!.attachments, screenshots);
861
+ if (scenario.includes("target-background") || scenario.includes("target-subagent")) {
862
+ assert.isTrue(yield* Ref.get(pendingBackgroundWork));
863
+ const failure = projection.turnItems.findLast((item) => item.type === "error");
864
+ assert.equal(
865
+ failure?.type === "error" ? failure.failure.message : null,
866
+ "The target provider still has background work running. Wait for it to finish or stop it before retrying the handoff.",
867
+ );
868
+ }
869
+ return;
870
+ }
871
assert.equal(projection.runs.at(-1)?.status, "completed");
872
+ if (exhaustedTarget) {
873
+ assert.equal(yield* Ref.get(generation), 2);
874
+ const turns = (yield* Ref.get(capturedTurns)).filter(
875
+ (turn) => turn.driver === CLAUDE_DRIVER,
876
+ );
877
+ assert.notEqual(turns[0]!.nativeThreadId, turns[1]!.nativeThreadId);
878
+ const latestRun = projection.runs.at(-1)!;
879
+ assert.equal(
880
+ projection.attempts.find((attempt) => attempt.id === latestRun.activeAttemptId)!
881
+ .nativeThreadId,
882
+ turns[1]!.nativeThreadId,
883
+ );
884
+ const context = scenario.endsWith("-native")
885
+ ? yield* encodeJson(yield* Ref.get(injectedHistory))
886
+ : turns[1]!.text;
887
+ assert.include(context, "Original request with constraints");
888
+ assert.include(context, "Original partial work");
889
+ assert.include(context, "New source constraint");
890
+ assert.include(turns[1]!.text, current);
891
+ assert.deepEqual(turns[1]!.attachments, screenshots);
892
+ const historyBeforeFollowup = yield* Ref.get(injectedHistory);
893
+ yield* dispatch(5, "Continue after automatic recovery", CLAUDE_MODEL_SELECTION);
894
+ yield* wait(5);
895
+ assert.equal(
896
+ (yield* orchestrator.getThreadProjection(threadId)).runs.at(-1)?.status,
897
+ "completed",
898
+ );
899
+ assert.equal(yield* Ref.get(generation), 2);
900
+ assert.equal(
901
+ (yield* Ref.get(capturedTurns)).at(-1)!.text,
902
+ "Continue after automatic recovery",
903
+ );
904
+ assert.deepEqual(yield* Ref.get(injectedHistory), historyBeforeFollowup);
905
+ if (scenario.includes("target-estimate")) {
906
+ yield* dispatch(6, "Another source turn", CODEX_MODEL_SELECTION);
907
+ yield* wait(6);
908
+ yield* dispatch(7, "Return after recovery", CLAUDE_MODEL_SELECTION);
909
+ yield* wait(7);
910
+ assert.equal(
911
+ (yield* orchestrator.getThreadProjection(threadId)).runs.at(-1)?.status,
912
+ "completed",
913
+ );
914
+ assert.equal(yield* Ref.get(generation), 2);
915
+ }
916
+ return;
917
+ }
918
if (priorImages) {
919
const handoff = projection.contextHandoffs.at(-1)!;
920
const context = scenario.endsWith("-native")
@@ -901,7 +1035,12 @@ describe("orchestration v2 provider switching", () => {
1035
}),
1036
),
1037
);
904
- it.live.each(["turn-start", "injection", "large-missed-request"] as const)(
1038
+ it.live.each([
1039
+ "turn-start",
1040
+ "injection",
1041
+ "large-missed-request",
1042
+ "exhausted-target-retry",
1043
+ ] as const)(
1044
"recovers %s failure without duplicating history in the same native thread",
1045
(failure) =>
1046
Effect.scoped(
@@ -999,6 +1138,22 @@ describe("orchestration v2 provider switching", () => {
1138
failure !== "injection" ? "injected" : "pending",
1139
);
1140
const historyBeforeRetry = (yield* Ref.get(injectedHistory)).length;
1141
+ if (failure === "exhausted-target-retry") {
1142
+ const target = failed.providerThreads.find(
1143
+ (thread) => thread.providerInstanceId === CLAUDE_MODEL_SELECTION.instanceId,
1144
+ )!;
1145
+ yield* (yield* EventSink.EventSinkV2).write({
1146
+ events: [
1147
+ {
1148
+ id: EventId.make("exhausted-retry-usage"),
1149
+ type: "provider-thread.updated",
1150
+ threadId,
1151
+ occurredAt: yield* DateTime.now,
1152
+ payload: { ...target, contextUsage: { usedTokens: 30_000, maxTokens: 32_000 } },
1153
+ },
1154
+ ],
1155
+ });
1156
+ }
1157
const retryText =
1158
failure === "large-missed-request" ? "y".repeat(10_000) : "Retry target request";
1159
yield* dispatch(3, retryText, CLAUDE_MODEL_SELECTION);
@@ -1006,7 +1161,7 @@ describe("orchestration v2 provider switching", () => {
1161
const retried = yield* orchestrator.getThreadProjection(threadId);
1162
const lastTurn = (yield* Ref.get(capturedTurns)).at(-1)!;
1163
assert.equal(lastTurn.text, retryText);
1009
- if (failure !== "injection") {
1164
+ if (failure !== "injection" && failure !== "exhausted-target-retry") {
1165
const delta = yield* encodeJson(
1166
(yield* Ref.get(injectedHistory)).slice(historyBeforeRetry),
1167
);
docs/user/portable-handoffs.md
+7
-3
@@ -20,9 +20,13 @@ agent-written summary.
20
## Context limits
21
22
A handoff must leave room for existing provider context, your request and attachments, instructions,
23
-tools, and subsequent work. If even its retrieval references cannot fit, T3 Code reports an error
24
-instead of shortening your request. Compact the target conversation or select a larger-context
25
-model before trying again.
23
+tools, and subsequent work. If the target conversation has no room for the handoff, T3 Code starts
24
+a fresh provider conversation with a bounded selection of saved history and sends your request
25
+automatically. You do not need to compact manually. If the request and attachments leave too little
26
+room even in a fresh conversation, shorten the request or select a larger-context model. T3 Code
27
+never shortens your request to make it fit.
28
+
29
+Recovery leaves running background work intact. Let it finish or stop it before retrying the handoff.
30
31
Server operators can set `T3CODE_CONTEXT_HANDOFF_TOKEN_CAP` to change the initial history allowance
32
(default 16,000; clamped to 1,024–64,000). This is an upper bound, not a provider context-window
packages/provider-acp/src/server/adapter.ts
+95
-58
@@ -6550,6 +6550,46 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
6550
return replacementExit.value.started;
6551
});
6552
6553
+ const commitReplacementSession = Effect.fn("AcpAdapterV2.commitReplacementSession")(
6554
+ function* (
6555
+ threadId: ThreadId | null,
6556
+ candidate: AcpSessionRuntime.AcpSessionRuntimeStartResult,
6557
+ ) {
6558
+ rememberTerminalEnvironment(candidate.sessionId, yield* readMcpContext(threadId));
6559
+ yield* Ref.set(runtimeRestartRequired, false);
6560
+ yield* Ref.set(activeSessionId, candidate.sessionId);
6561
+ yield* setActiveSessionSetup(candidate);
6562
+ yield* Ref.set(activeSelection, null);
6563
+ yield* Ref.set(activeInteractionMode, null);
6564
+ yield* Ref.set(promptInstructionStates, new Map());
6565
+ yield* Ref.set(compactionMarkers, new Map());
6566
+ yield* Ref.set(providerTurns, new Map());
6567
+ yield* Ref.set(snapshot, {
6568
+ order: [],
6569
+ messages: new Map(),
6570
+ loadingRole: null,
6571
+ loadingMessageId: null,
6572
+ loadingIndex: 0,
6573
+ });
6574
+ yield* continuationPermit.withPermit(
6575
+ Effect.gen(function* () {
6576
+ yield* Ref.update(continuationGeneration, (value) => value + 1);
6577
+ yield* Ref.set(stoppedRunQuarantine, false);
6578
+ yield* Ref.set(wakeBuffer, []);
6579
+ yield* Ref.set(wakeReports, noWakeReports);
6580
+ yield* Ref.set(continuationRequested, false);
6581
+ yield* Ref.set(runningBackgroundTaskIds, new Set());
6582
+ yield* Ref.set(endedBackgroundTaskIds, new Set());
6583
+ yield* Ref.set(midTurnUnreportedCompletedTaskIds, new Set());
6584
+ yield* Ref.set(handledBackgroundTaskIdsInActiveTurn, new Set());
6585
+ yield* Ref.set(carryoverSubagents, null);
6586
+ yield* Ref.set(suppressPostSettleMonitorPrompt, false);
6587
+ yield* Ref.set(lastTurnRoute, null);
6588
+ }),
6589
+ );
6590
+ },
6591
+ );
6592
+
6593
const initialStart = yield* Effect.result(
6594
startAcpRuntime(input.threadId, input.initialNativeThreadId),
6595
);
@@ -7784,28 +7824,61 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
7824
: {}),
7825
ensureThread: Effect.fn("AcpAdapterV2.ensureThread")(
7826
function* (threadInput: ProviderAdapter.ProviderAdapterV2EnsureThreadInput) {
7787
- const now = yield* DateTime.now;
7788
- const sessionId = yield* Ref.get(activeSessionId);
7789
- if (sessionId === null) {
7790
- return yield* new ProviderAdapter.ProviderAdapterProtocolError({
7791
- driver,
7792
- detail: "ACP runtime did not produce a session id",
7793
- });
7794
- }
7795
- const providerThread = makeProviderThread({
7796
- driver,
7797
- providerInstanceId: options.instanceId,
7798
- idAllocator,
7799
- appThreadId: threadInput.threadId,
7800
- providerSessionId: input.providerSessionId,
7801
- nativeThreadId: sessionId,
7802
- ...(itemIdentityVersion === undefined ? {} : { itemIdentityVersion }),
7803
- now,
7804
- });
7805
- yield* Ref.update(providerThreadByNativeSessionId, (current) =>
7806
- new Map(current).set(sessionId, providerThread),
7827
+ return yield* runtimeTransitionPermit.withPermit(
7828
+ Effect.gen(function* () {
7829
+ if (threadInput.forceNewNativeThread) {
7830
+ const currentTurn = yield* Ref.get(activeTurn);
7831
+ const pendingWork = yield* (
7832
+ sessionRuntime.hasPendingBackgroundWork ?? Effect.succeed(false)
7833
+ );
7834
+ if (currentTurn !== null || pendingWork)
7835
+ return yield* new ProviderAdapter.ProviderAdapterProtocolError({
7836
+ driver,
7837
+ detail:
7838
+ "Cannot replace ACP session while a turn or background work is active",
7839
+ });
7840
+ yield* awaitRuntimeTeardown();
7841
+ const previousItemIdentityVersion = itemIdentityVersion;
7842
+ itemIdentityVersion = 2;
7843
+ prepareTerminalEnvironment(yield* readMcpContext(threadInput.threadId));
7844
+ yield* startReplacementAcpRuntime(threadInput.threadId, (candidate) =>
7845
+ commitReplacementSession(threadInput.threadId, candidate),
7846
+ ).pipe(
7847
+ Effect.tapError(() =>
7848
+ Effect.sync(() => {
7849
+ itemIdentityVersion = previousItemIdentityVersion;
7850
+ }),
7851
+ ),
7852
+ );
7853
+ }
7854
+ const now = yield* DateTime.now;
7855
+ const sessionId = yield* Ref.get(activeSessionId);
7856
+ if (sessionId === null) {
7857
+ return yield* new ProviderAdapter.ProviderAdapterProtocolError({
7858
+ driver,
7859
+ detail: "ACP runtime did not produce a session id",
7860
+ });
7861
+ }
7862
+ const created = makeProviderThread({
7863
+ driver,
7864
+ providerInstanceId: options.instanceId,
7865
+ idAllocator,
7866
+ appThreadId: threadInput.threadId,
7867
+ providerSessionId: input.providerSessionId,
7868
+ nativeThreadId: sessionId,
7869
+ ...(itemIdentityVersion === undefined ? {} : { itemIdentityVersion }),
7870
+ now,
7871
+ });
7872
+ const providerThread =
7873
+ threadInput.forceNewNativeThread && threadInput.existingProviderThread
7874
+ ? { ...created, id: threadInput.existingProviderThread.id }
7875
+ : created;
7876
+ yield* Ref.update(providerThreadByNativeSessionId, (current) =>
7877
+ new Map(current).set(sessionId, providerThread),
7878
+ );
7879
+ return providerThread;
7880
+ }),
7881
);
7808
- return providerThread;
7882
},
7883
(effect, threadInput) =>
7884
effect.pipe(
@@ -8348,43 +8421,7 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
8421
const replacement = yield* startReplacementAcpRuntime(
8422
rollbackInput.providerThread.appThreadId,
8423
(candidate) =>
8351
- Effect.gen(function* () {
8352
- rememberTerminalEnvironment(
8353
- candidate.sessionId,
8354
- yield* readMcpContext(rollbackInput.providerThread.appThreadId),
8355
- );
8356
- yield* Ref.set(runtimeRestartRequired, false);
8357
- yield* Ref.set(activeSessionId, candidate.sessionId);
8358
- yield* setActiveSessionSetup(candidate);
8359
- yield* Ref.set(activeSelection, null);
8360
- yield* Ref.set(activeInteractionMode, null);
8361
- yield* Ref.set(promptInstructionStates, new Map());
8362
- yield* Ref.set(compactionMarkers, new Map());
8363
- yield* Ref.set(providerTurns, new Map());
8364
- yield* Ref.set(snapshot, {
8365
- order: [],
8366
- messages: new Map(),
8367
- loadingRole: null,
8368
- loadingMessageId: null,
8369
- loadingIndex: 0,
8370
- });
8371
- yield* continuationPermit.withPermit(
8372
- Effect.gen(function* () {
8373
- yield* Ref.update(continuationGeneration, (value) => value + 1);
8374
- yield* Ref.set(stoppedRunQuarantine, false);
8375
- yield* Ref.set(wakeBuffer, []);
8376
- yield* Ref.set(wakeReports, noWakeReports);
8377
- yield* Ref.set(continuationRequested, false);
8378
- yield* Ref.set(runningBackgroundTaskIds, new Set());
8379
- yield* Ref.set(endedBackgroundTaskIds, new Set());
8380
- yield* Ref.set(midTurnUnreportedCompletedTaskIds, new Set());
8381
- yield* Ref.set(handledBackgroundTaskIdsInActiveTurn, new Set());
8382
- yield* Ref.set(carryoverSubagents, null);
8383
- yield* Ref.set(suppressPostSettleMonitorPrompt, false);
8384
- yield* Ref.set(lastTurnRoute, null);
8385
- }),
8386
- );
8387
- }),
8424
+ commitReplacementSession(rollbackInput.providerThread.appThreadId, candidate),
8425
).pipe(Effect.retry({ times: 1 }));
8426
const now = yield* DateTime.now;
8427
return {
packages/provider-core/src/server/ProviderAdapter.ts
+3
-1
@@ -411,6 +411,7 @@ export interface ProviderAdapterV2EnsureThreadInput {
411
readonly runtimePolicy: ProviderAdapterV2RuntimePolicy;
412
readonly providerSessionId?: ProviderSessionId;
413
readonly existingProviderThread?: OrchestrationV2ProviderThread;
414
+ readonly forceNewNativeThread?: boolean;
415
}
416
417
export interface ProviderAdapterV2TurnInput {
@@ -549,9 +550,10 @@ export interface ProviderAdapterV2SessionRuntime {
550
/** Manager runtimes broadcast independent subscriptions; adapters may expose only a single-consumer stream. */
551
readonly subscribeEvents?: Effect.Effect<ProviderAdapterV2EventSubscription>;
552
readonly hasPendingBackgroundWork?: Effect.Effect<boolean>;
552
- /** Overrides the session-wide probe so sibling threads cannot keep this root subscription open. */
553
+ /** Root-subscription probe; replacement checks opt in to subagents owned by the live process. */
554
readonly hasPendingBackgroundWorkForThread?: (
555
providerThread: OrchestrationV2ProviderThread,
556
+ options?: { readonly includeSubagents?: boolean },
557
) => Effect.Effect<boolean>;
558
/** Set only if all session background tasks end with its process; otherwise threads must keep Waiting. */
559
readonly backgroundTasksEndWithProcess?: true;
packages/provider-core/src/server/failure.test.ts
+11
-11
@@ -16,6 +16,7 @@ import {
16
makeProviderFailureTurnItem,
17
MAX_PROVIDER_FAILURE_MESSAGE_LENGTH,
18
ContextHandoffBudgetError,
19
+ ContextHandoffBackgroundWorkError,
20
} from "./failure.ts";
21
import * as IdAllocator from "./IdAllocator.ts";
22
import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
@@ -69,17 +70,16 @@ it("does not expose arbitrary cause messages and preserves explicit messages", (
70
});
71
72
it("preserves actionable handoff errors wrapped by turn startup", () => {
72
- const cause = new ProviderAdapter.ProviderAdapterTurnStartError({
73
- driver: ProviderDriverKind.make("codex"),
74
- threadId: ThreadId.make("thread:handoff-error"),
75
- providerThreadId: ProviderThreadId.make("provider-thread:handoff-error"),
76
- runId: RunId.make("run:handoff-error"),
77
- cause: new ContextHandoffBudgetError(),
78
- });
79
- assert.equal(
80
- makeProviderFailure({ cause: Cause.fail(cause) }).message,
81
- new ContextHandoffBudgetError().message,
82
- );
73
+ for (const error of [new ContextHandoffBudgetError(), new ContextHandoffBackgroundWorkError()]) {
74
+ const cause = new ProviderAdapter.ProviderAdapterTurnStartError({
75
+ driver: ProviderDriverKind.make("codex"),
76
+ threadId: ThreadId.make("thread:handoff-error"),
77
+ providerThreadId: ProviderThreadId.make("provider-thread:handoff-error"),
78
+ runId: RunId.make("run:handoff-error"),
79
+ cause: error,
80
+ });
81
+ assert.equal(makeProviderFailure({ cause: Cause.fail(cause) }).message, error.message);
82
+ }
83
});
84
85
it("keeps unrecognized reasons and provider text out of category messages", () => {
packages/provider-core/src/server/failure.ts
+15
-1
@@ -22,7 +22,16 @@ export class ContextHandoffBudgetError extends Schema.TaggedError<ContextHandoff
22
{},
23
) {
24
override get message() {
25
- return "Insufficient context allowance for the provider handoff. Compact the target conversation or use a larger-context model; the current request has not been truncated.";
25
+ return "The request leaves too little context for a provider handoff. Shorten the request or use a larger-context model; the current request has not been truncated.";
26
+ }
27
+}
28
+
29
+export class ContextHandoffBackgroundWorkError extends Schema.TaggedError<ContextHandoffBackgroundWorkError>()(
30
+ "ContextHandoffBackgroundWorkError",
31
+ {},
32
+) {
33
+ override get message() {
34
+ return "The target provider still has background work running. Wait for it to finish or stop it before retrying the handoff.";
35
}
36
}
37
@@ -87,6 +96,11 @@ function curatedCauseMessages(cause: unknown): {
96
switch (tag) {
97
case "ContextHandoffBudgetError":
98
return { known: new ContextHandoffBudgetError().message, category: categoryMessage() };
99
+ case "ContextHandoffBackgroundWorkError":
100
+ return {
101
+ known: new ContextHandoffBackgroundWorkError().message,
102
+ category: categoryMessage(),
103
+ };
104
case "AcpModelSelectionError":
105
case "ClaudeBackgroundWorkBlocksQueryReplacementError":
106
case "ClaudeAppendSystemPromptFileError":