@devries-cameron20 / t3code-1 / commits / 07242abff3
Fork 0

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

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":