The best way to control Claude Code, Codex and more from any computer or phone
feat(server): sends can start a fresh provider session (#30323)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 5, 2026 at 11:29 UTC
e139768a7e7f53fd36c2ff88b63bc03c71f3fad7
6 files changed
+504
-40
apps/server/src/environment/ServerEnvironment.ts
+1
@@ -268,6 +268,7 @@ export const make = Effect.gen(function* () {
268
ignoredFileListing: true,
269
triage: true,
270
oneTimeSchedules: true,
271
+ freshContext: true,
272
npmReleaseLookup: true,
273
...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
274
...(serverInstallation === null ? {} : { serverInstallation }),
apps/server/src/orchestration-v2/Orchestrator.ts
+200
-37
@@ -45,6 +45,7 @@ import {
45
type OrchestrationV2DelegatedCompletionDelivery,
46
type OrchestrationV2DomainEvent,
47
type OrchestrationV2ExecutionNode,
48
+ type OrchestrationV2ProviderSession,
49
type OrchestrationV2ProviderThread,
50
type OrchestrationV2ProviderTurn,
51
type OrchestrationV2RemoteTaskChild,
@@ -998,16 +999,75 @@ function appendContextHandoffId(
999
return handoffId === null ? handoffIds : Array.from(new Set([...handoffIds, handoffId]));
1000
}
1001
1002
+/** Ordinal of the latest started fresh-context run. Runs before it never reach a provider again. */
1003
+function contextBoundaryOrdinal(
1004
+ runs: ReadonlyArray<
1005
+ Pick<
1006
+ OrchestrationV2Run,
1007
+ "ordinal" | "freshContext" | "status" | "startedAt" | "restartContinuationOfRunId"
1008
+ >
1009
+ >,
1010
+): number {
1011
+ let boundary = 0;
1012
+ for (const run of runs) {
1013
+ if (
1014
+ run.freshContext === true &&
1015
+ run.status !== "queued" &&
1016
+ !cancelledBeforeStart(run) &&
1017
+ run.ordinal > boundary
1018
+ ) {
1019
+ boundary = run.ordinal;
1020
+ }
1021
+ }
1022
+ return boundary;
1023
+}
1024
+
1025
+/** Threads with no started run (imported, or reserved by another queued run) never cross it. */
1026
+function providerThreadPredatesBoundary(
1027
+ providerThread: Pick<OrchestrationV2ProviderThread, "firstRunOrdinal">,
1028
+ boundary: number,
1029
+): boolean {
1030
+ return (
1031
+ boundary > 0 &&
1032
+ (providerThread.firstRunOrdinal === null || providerThread.firstRunOrdinal < boundary)
1033
+ );
1034
+}
1035
+
1036
+/** A provider that hosts one native thread per session keeps the old conversation alive otherwise. */
1037
+function sessionsReleasedByFreshContext(
1038
+ projection: Pick<OrchestrationV2ThreadProjection, "providerSessions">,
1039
+ activeProviderThread: OrchestrationV2ProviderThread | undefined,
1040
+): ReadonlyArray<OrchestrationV2ProviderSession> {
1041
+ const sessionId = activeProviderThread?.providerSessionId ?? null;
1042
+ return projection.providerSessions.filter(
1043
+ (session) =>
1044
+ session.id === sessionId &&
1045
+ session.status !== "stopped" &&
1046
+ session.status !== "error" &&
1047
+ !session.capabilities.sessions.supportsMultipleProviderThreadsPerSession,
1048
+ );
1049
+}
1050
+
1051
+const FRESH_CONTEXT_DETACH_REASON = "Started a fresh session.";
1052
+
1053
+function uniqueSessions(
1054
+ sessions: ReadonlyArray<OrchestrationV2ProviderSession>,
1055
+): ReadonlyArray<OrchestrationV2ProviderSession> {
1056
+ return Array.from(new Map(sessions.map((session) => [session.id, session])).values());
1057
+}
1058
+
1059
function rootProviderThreadsForProvider(
1002
- projection: Pick<OrchestrationV2ThreadProjection, "providerThreads" | "thread">,
1060
+ projection: Pick<OrchestrationV2ThreadProjection, "providerThreads" | "thread" | "runs">,
1061
providerInstanceId: ModelSelection["instanceId"],
1062
): ReadonlyArray<OrchestrationV2ProviderThread> {
1063
+ const boundary = contextBoundaryOrdinal(projection.runs);
1064
return projection.providerThreads
1065
.filter(
1066
(providerThread) =>
1067
providerThread.providerInstanceId === providerInstanceId &&
1068
providerThread.appThreadId === projection.thread.id &&
1010
- providerThread.ownerNodeId === null,
1069
+ providerThread.ownerNodeId === null &&
1070
+ !providerThreadPredatesBoundary(providerThread, boundary),
1071
)
1072
.toSorted(
1073
(left, right) =>
@@ -1807,15 +1867,29 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
1867
(candidate) => candidate.id === projection.thread.activeProviderThreadId,
1868
);
1869
const followsCurrent = followsCurrentConversation(queuedMessage);
1810
- const targetProviderThread = followsCurrent
1811
- ? activeProviderThread?.providerInstanceId === queuedRun.providerInstanceId
1870
+ const freshContext = queuedRun.freshContext === true;
1871
+ const contextBoundary = freshContext ? ordinal : contextBoundaryOrdinal(projection.runs);
1872
+ // A run queued before a fresh run started is bound to the conversation that run left behind.
1873
+ const followsLatestContext =
1874
+ !freshContext &&
1875
+ (followsCurrent || providerThreadPredatesBoundary(storedProviderThread, contextBoundary));
1876
+ const targetProviderThread = followsLatestContext
1877
+ ? activeProviderThread?.providerInstanceId === queuedRun.providerInstanceId &&
1878
+ !providerThreadPredatesBoundary(activeProviderThread, contextBoundary)
1879
? activeProviderThread
1880
: rootProviderThreadsForProvider(projection, queuedRun.providerInstanceId)[0]
1814
- : storedProviderThread;
1881
+ : freshContext &&
1882
+ (storedProviderThread.firstRunOrdinal !== null ||
1883
+ storedProviderThread.nativeThreadRef !== null)
1884
+ ? undefined
1885
+ : storedProviderThread;
1886
const queuedProviderThread: OrchestrationV2ProviderThread = targetProviderThread ?? {
1887
id: idAllocator.derive.providerThread({
1888
driver: targetAdapter.driver,
1818
- nativeThreadId: `pending:${queuedRun.id}`,
1889
+ // The queue reserved `pending:<run>` for this run; another run may have taken it.
1890
+ nativeThreadId: freshContext
1891
+ ? `pending:${queuedRun.id}:fresh`
1892
+ : `pending:${queuedRun.id}`,
1893
}),
1894
driver: targetAdapter.driver,
1895
providerInstanceId: queuedRun.providerInstanceId,
@@ -1870,12 +1944,15 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
1944
),
1945
)
1946
: null;
1873
- const releasableSessions = projection.providerSessions.filter(
1874
- (session) =>
1875
- switchPlan?.releaseProviderSessionIds.includes(session.id) &&
1876
- session.status !== "stopped" &&
1877
- session.status !== "error",
1878
- );
1947
+ const releasableSessions = uniqueSessions([
1948
+ ...projection.providerSessions.filter(
1949
+ (session) =>
1950
+ switchPlan?.releaseProviderSessionIds.includes(session.id) &&
1951
+ session.status !== "stopped" &&
1952
+ session.status !== "error",
1953
+ ),
1954
+ ...(freshContext ? sessionsReleasedByFreshContext(projection, activeProviderThread) : []),
1955
+ ]);
1956
const busySessionIds = new Set<ProviderSessionId>();
1957
for (const session of releasableSessions) {
1958
if (yield* sessionHasBackgroundWork(session, projection.providerThreads)) {
@@ -1884,7 +1961,12 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
1961
}
1962
// Nobody waits on a queued start to refuse it. A handoff runs in its own session, so a
1963
// busy one stays up; a restart resumes the busy session's native thread, so wait instead.
1887
- if (busySessionIds.size > 0 && switchPlan?.transition.type === "restart_and_resume") {
1964
+ // A fresh run resumes nothing, so it never waits.
1965
+ if (
1966
+ busySessionIds.size > 0 &&
1967
+ !freshContext &&
1968
+ switchPlan?.transition.type === "restart_and_resume"
1969
+ ) {
1970
yield* Effect.logInfo(
1971
"Holding the queue: the replaced provider session still runs background work",
1972
{ threadId, runId: queuedRun.id, providerSessionIds: Array.from(busySessionIds) },
@@ -1907,6 +1989,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
1989
(session) => !busySessionIds.has(session.id),
1990
);
1991
const canResumeAcrossInstances =
1992
+ !freshContext &&
1993
switchPlan?.instanceChanged === true &&
1994
switchPlan.transition.type === "restart_and_resume" &&
1995
activeProviderThread !== undefined &&
@@ -1936,6 +2019,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
2019
queuedProviderThread.id,
2020
);
2021
const coveredRuns =
2022
+ freshContext ||
2023
canResumeAcrossInstances ||
2024
latestHandoffRun === undefined ||
2025
latestHandoffRun.providerInstanceId === queuedRun.providerInstanceId
@@ -1943,12 +2027,13 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
2027
: projection.runs.filter(
2028
(run) =>
2029
isHandoffSourceRun(run) &&
2030
+ run.ordinal >= contextBoundary &&
2031
run.ordinal > (targetLastCompletedRun?.ordinal ?? 0) &&
2032
run.ordinal <= latestHandoffRun.ordinal,
2033
);
2034
const needsFullContext = deliveryProviderThread.nativeThreadRef === null;
2035
const legacyImportItems =
1951
- projection.thread.historyOrigin === "v1_import"
2036
+ projection.thread.historyOrigin === "v1_import" && contextBoundary === 0
2037
? yield* readHandoffItems(threadId, [null])
2038
: [];
2039
const handoffStrategy = needsFullContext
@@ -2153,6 +2238,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
2238
? {}
2239
: { idleCompaction: queuedMessage.idleCompaction }),
2240
}),
2241
+ ...(freshContext ? { freshContext: true } : {}),
2242
providerThreadId: queuedProviderThread.id,
2243
inputIntent: "queued_turn",
2244
status: "completed",
@@ -2244,6 +2330,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
2330
},
2331
]
2332
: [];
2333
+ const detachReason = freshContext
2334
+ ? FRESH_CONTEXT_DETACH_REASON
2335
+ : "Provider or model selection changed.";
2336
yield* writeSystemEvents(
2337
[
2338
...(selectionChanged
@@ -2344,7 +2433,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
2433
payload: {
2434
providerSessionId: session.id,
2435
detachedAt: now,
2347
- reason: "Provider or model selection changed.",
2436
+ reason: detachReason,
2437
},
2438
})),
2439
...executionIdentityEvents,
@@ -2386,7 +2475,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
2475
request: {
2476
type: "provider-session.detach" as const,
2477
providerSessionId: session.id,
2389
- detail: "Provider or model selection changed.",
2478
+ detail: detachReason,
2479
},
2480
})),
2481
{
@@ -5219,6 +5308,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
5308
type: "provider_handoff",
5309
}),
5310
);
5311
+ const contextBoundary = contextBoundaryOrdinal(input.projection.runs);
5312
restartHandoff = yield* contextHandoffService
5313
.prepareProviderHandoff({
5314
threadId: input.command.threadId,
@@ -5228,9 +5318,16 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
5318
toProviderThreadId: targetProviderThreadBase.id,
5319
fromProviderInstanceId: targetRun.providerInstanceId,
5320
toProviderInstanceId: input.modelSelection.instanceId,
5231
- coveredRunOrdinals: { from: 1, to: targetRun.ordinal },
5321
+ coveredRunOrdinals: { from: Math.max(1, contextBoundary), to: targetRun.ordinal },
5322
strategy: "full_thread_summary",
5233
- items: yield* readHandoffItems(input.command.threadId),
5323
+ items: yield* readHandoffItems(
5324
+ input.command.threadId,
5325
+ contextBoundary === 0
5326
+ ? undefined
5327
+ : input.projection.runs
5328
+ .filter((run) => run.ordinal >= contextBoundary)
5329
+ .map((run) => run.id),
5330
+ ),
5331
runs: input.projection.runs,
5332
createdAt: now,
5333
})
@@ -5750,6 +5847,13 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
5847
) {
5848
dispatchMode = { type: "queue_after_active" };
5849
}
5850
+ const freshContext = command.freshContext === true;
5851
+ if (
5852
+ freshContext &&
5853
+ (dispatchMode.type === "steer_active" || dispatchMode.type === "restart_active")
5854
+ ) {
5855
+ dispatchMode = { type: "queue_after_active" };
5856
+ }
5857
// Codex and Claude own /goal; elsewhere it is ordinary text that cannot steer.
5858
const parsedGoalCommand = parseGoalCommand(command);
5859
const goalCommand =
@@ -5849,12 +5953,13 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
5953
// behind a long parent turn is never seen. Never interrupt/restart a turn
5954
// for a notification.
5955
if (
5852
- delegatedCompletion !== undefined
5956
+ !freshContext &&
5957
+ (delegatedCompletion !== undefined
5958
? delegatedCompletion.taskIds.every(
5959
(id) =>
5960
projection.subagents.find((task) => task.id === id)?.completionWake === "always",
5961
)
5857
- : command.notification?.source.kind === "delegated_task"
5962
+ : command.notification?.source.kind === "delegated_task")
5963
) {
5964
const active = projection.runs.find((run) => run.status === "running");
5965
const providerThread = projection.providerThreads.find(
@@ -6040,8 +6145,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6145
const now = yield* DateTime.now;
6146
const ordinal = nextRunOrdinal(projection);
6147
const runId = idAllocator.derive.run({ threadId: command.threadId, ordinal });
6043
- const targetProviderThread =
6044
- modelSelection.instanceId === queueProviderThread.providerInstanceId
6148
+ const targetProviderThread = freshContext
6149
+ ? undefined
6150
+ : modelSelection.instanceId === queueProviderThread.providerInstanceId
6151
? queueProviderThread
6152
: rootProviderThreadsForProvider(projection, modelSelection.instanceId)[0];
6153
const queuedAdapter = yield* providerAdapters
@@ -6160,6 +6266,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6266
? {}
6267
: { restartContinuationOfRunId: command.restartContinuationOfRunId }),
6268
...(continuedTaskId === undefined ? {} : { delegatedTaskId: continuedTaskId }),
6269
+ ...(freshContext ? { freshContext: true } : {}),
6270
};
6271
const attempt: OrchestrationV2RunAttempt = {
6272
id: attemptId,
@@ -6349,12 +6456,23 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6456
},
6457
});
6458
}
6459
+ if (
6460
+ freshContext &&
6461
+ (pendingForkTransfer !== undefined || pendingMergeBackTransfer !== undefined)
6462
+ ) {
6463
+ return yield* new OrchestratorDispatchError({
6464
+ commandId: command.commandId,
6465
+ commandType: command.type,
6466
+ cause: "A fresh session can't start while a fork or merge is still being applied.",
6467
+ });
6468
+ }
6469
const ordinal = nextRunOrdinal(projection);
6470
const runId = idAllocator.derive.run({ threadId: command.threadId, ordinal });
6471
+ const contextBoundary = freshContext ? ordinal : contextBoundaryOrdinal(projection.runs);
6472
const latestCompletedRun = projection.runs.findLast((run) => run.status === "completed");
6473
const latestHandoffRun = projection.runs.findLast(isHandoffSourceRun);
6474
const legacyImportItems =
6357
- projection.thread.historyOrigin === "v1_import"
6475
+ projection.thread.historyOrigin === "v1_import" && contextBoundary === 0
6476
? yield* readHandoffItems(command.threadId, [null])
6477
: [];
6478
const isProviderSwitch =
@@ -6380,22 +6498,27 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6498
.pipe(mapDispatchError(command))
6499
: null;
6500
const canResumeAcrossInstances =
6501
+ !freshContext &&
6502
isProviderSwitch &&
6503
activeProviderThread.nativeThreadRef !== null &&
6504
providerSwitchPlan?.transition.type === "restart_and_resume";
6386
- const sessionsToDetach = projection.providerSessions.filter(
6387
- (session) =>
6388
- providerSwitchPlan?.releaseProviderSessionIds.includes(session.id) &&
6389
- session.status !== "stopped" &&
6390
- session.status !== "error",
6391
- );
6505
+ const sessionsToDetach = uniqueSessions([
6506
+ ...projection.providerSessions.filter(
6507
+ (session) =>
6508
+ providerSwitchPlan?.releaseProviderSessionIds.includes(session.id) &&
6509
+ session.status !== "stopped" &&
6510
+ session.status !== "error",
6511
+ ),
6512
+ ...(freshContext ? sessionsReleasedByFreshContext(projection, activeProviderThread) : []),
6513
+ ]);
6514
for (const detaching of sessionsToDetach) {
6515
if (yield* sessionHasBackgroundWork(detaching, projection.providerThreads)) {
6516
return yield* new OrchestratorDispatchError({
6517
commandId: command.commandId,
6518
commandType: command.type,
6397
- cause:
6398
- "The previous provider is still running background agents or commands, and switching would end them. Wait for them to finish, or press Stop, then send the message again.",
6519
+ cause: freshContext
6520
+ ? "The current session is still running background agents or commands, and a fresh session would end them. Wait for them to finish, or press Stop, then send the message again."
6521
+ : "The previous provider is still running background agents or commands, and switching would end them. Wait for them to finish, or press Stop, then send the message again.",
6522
});
6523
}
6524
}
@@ -6403,8 +6526,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6526
if (
6527
pendingForkTransfer === undefined &&
6528
pendingMergeBackTransfer === undefined &&
6406
- !isProviderSwitch
6529
+ (!isProviderSwitch || freshContext)
6530
) {
6531
+ const reusableProviderThread = freshContext ? undefined : activeProviderThread;
6532
const adapter = yield* providerAdapters.get(modelSelection.instanceId).pipe(
6533
Effect.mapError(
6534
(cause) =>
@@ -6416,7 +6540,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6540
),
6541
);
6542
const providerSessionId =
6419
- activeProviderThread?.providerSessionId ??
6543
+ reusableProviderThread?.providerSessionId ??
6544
(yield* mapDispatchError(command)(
6545
providerSessionIdFor({
6546
adapter,
@@ -6425,7 +6549,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6549
}),
6550
));
6551
const providerThreadId =
6428
- activeProviderThread?.id ??
6552
+ reusableProviderThread?.id ??
6553
idAllocator.derive.providerThread({
6554
driver: adapter.driver,
6555
nativeThreadId: `pending:${runId}`,
@@ -6447,7 +6571,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6571
.pipe(mapDispatchError(command))
6572
: null;
6573
const providerThread: OrchestrationV2ProviderThread =
6450
- activeProviderThread === undefined
6574
+ reusableProviderThread === undefined
6575
? {
6576
id: providerThreadId,
6577
driver: adapter.driver,
@@ -6466,11 +6590,11 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6590
updatedAt: now,
6591
}
6592
: {
6469
- ...activeProviderThread,
6593
+ ...reusableProviderThread,
6594
providerSessionId,
6595
lastRunOrdinal: ordinal,
6596
handoffIds: appendContextHandoffId(
6473
- activeProviderThread.handoffIds,
6597
+ reusableProviderThread.handoffIds,
6598
legacyImportHandoff?.id ?? null,
6599
),
6600
updatedAt: now,
@@ -6526,6 +6650,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6650
: {}),
6651
...(continuedTaskId === undefined ? {} : { delegatedTaskId: continuedTaskId }),
6652
...wakeWorkStartedAt(projection.runs, command),
6653
+ ...(freshContext ? { freshContext: true } : {}),
6654
};
6655
const attempt: OrchestrationV2RunAttempt = {
6656
id: attemptId,
@@ -6607,6 +6732,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6732
text: dispatchText,
6733
...(command.context ? { context: command.context } : {}),
6734
attachments: command.attachments,
6735
+ ...(freshContext ? { freshContext: true } : {}),
6736
...(run.contextHandoffId === null ? modelSwitchSince(projection, modelSelection) : {}),
6737
};
6738
const preparationTurnItem: OrchestrationV2TurnItem | null =
@@ -6724,6 +6850,34 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6850
payload: preparationTurnItem,
6851
});
6852
}
6853
+ for (const session of sessionsToDetach) {
6854
+ if (session.id === providerSessionId) continue;
6855
+ yield* emitEvent({
6856
+ type: "provider-session.detached",
6857
+ threadId: command.threadId,
6858
+ driver: session.driver,
6859
+ providerInstanceId: session.providerInstanceId,
6860
+ occurredAt: now,
6861
+ payload: {
6862
+ providerSessionId: session.id,
6863
+ detachedAt: now,
6864
+ reason: FRESH_CONTEXT_DETACH_REASON,
6865
+ },
6866
+ });
6867
+ yield* Ref.update(effects, (existing) => [
6868
+ ...existing,
6869
+ {
6870
+ id: `effect:${command.commandId}:provider-session.detach:${session.id}`,
6871
+ commandId: command.commandId,
6872
+ threadId: command.threadId,
6873
+ request: {
6874
+ type: "provider-session.detach",
6875
+ providerSessionId: session.id,
6876
+ detail: FRESH_CONTEXT_DETACH_REASON,
6877
+ },
6878
+ } satisfies PendingOrchestrationEffectV2,
6879
+ ]);
6880
+ }
6881
const pendingEffect = {
6882
id: `effect:${command.commandId}:provider-turn.start:${runId}`,
6883
commandId: command.commandId,
@@ -7010,6 +7164,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
7164
: projection.runs.filter(
7165
(run) =>
7166
isHandoffSourceRun(run) &&
7167
+ run.ordinal >= contextBoundary &&
7168
run.ordinal >
7169
(requiresFullProviderSwitchContext ? 0 : (targetLastCompletedRun?.ordinal ?? 0)) &&
7170
run.ordinal <= latestHandoffRun.ordinal,
@@ -9681,6 +9836,14 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
9836
now,
9837
});
9838
}
9839
+ // Skipping compaction starts the message as its own turn; steering would join the current one.
9840
+ if (queuedRun.freshContext === true) {
9841
+ return yield* new OrchestratorDispatchError({
9842
+ commandId: command.commandId,
9843
+ commandType: command.type,
9844
+ cause: "A message that starts a fresh session can't steer the current turn.",
9845
+ });
9846
+ }
9847
if (goalCommand !== null) {
9848
yield* ensureGoalCommandSupported(command, queuedMessage, queuedRun.providerInstanceId);
9849
const goal = projection.providerThreads.find(
apps/server/src/orchestration-v2/SteeringCompletion.integration.test.ts
+5
-3
@@ -1511,7 +1511,7 @@ it.effect("queues a plain send behind the stopped queue and releases its hold",
1511
1512
const goalHarness = Effect.fn("goalHarness")(function* (name: string) {
1513
const harness = yield* nextTurnSelectionHarness(name);
1514
- const send = (id: string, text: string, delivery: "queue" | "auto") =>
1514
+ const send = (id: string, text: string, delivery: "queue" | "auto", freshContext = false) =>
1515
Effect.gen(function* () {
1516
const orchestrator = yield* Orchestrator.OrchestratorV2;
1517
yield* orchestrator.dispatch({
@@ -1522,6 +1522,7 @@ const goalHarness = Effect.fn("goalHarness")(function* (name: string) {
1522
text,
1523
attachments: [],
1524
modelSelection: runSelection,
1525
+ ...(freshContext ? { freshContext } : {}),
1526
...(delivery === "queue"
1527
? { dispatchMode: { type: "queue_after_active" } }
1528
: { dispatchMode: { type: "start_immediately" }, deliveryIntent: "auto" }),
@@ -1627,7 +1628,8 @@ it.effect("promotes a queued goal by stopping the running turn", () =>
1628
),
1629
);
1630
1630
-it.effect.each(["next", "/goal ship it"])(
1631
+// A fresh message skips compaction as its own turn, which steering a running turn would not.
1632
+it.effect.each(["next", "/goal ship it", "fresh next"])(
1633
"promoting %s into a compaction stops it and sends it next",
1634
(promoted) =>
1635
Effect.scoped(
@@ -1641,7 +1643,7 @@ it.effect.each(["next", "/goal ship it"])(
1643
const threadId = yield* startFirstTurn;
1644
yield* send("compact", "/compact", "queue");
1645
yield* send("queued", "queued", "queue");
1644
- yield* send("next", promoted, "queue");
1646
+ yield* send("next", promoted, "queue", promoted.startsWith("fresh"));
1647
const settled = yield* orchestrator.streamDomainEvents.pipe(
1648
Stream.filter(
1649
(event) =>
apps/server/src/orchestration-v2/testkit/ProviderSwitch.integration.test.ts
+290
@@ -2767,6 +2767,296 @@ describe("orchestration v2 provider switching", () => {
2767
),
2768
);
2769
2770
+ it.live.each(["immediately", "behind a running turn"] as const)(
2771
+ "starts a fresh provider session %s and never hands earlier runs to a later provider",
2772
+ (variant) =>
2773
+ Effect.scoped(
2774
+ Effect.gen(function* () {
2775
+ const queued = variant !== "immediately";
2776
+ const key = queued ? "queued" : "immediate";
2777
+ const cwd = yield* checkpointWorkspace(`fresh-context-${key}`);
2778
+ const capturedTurns = yield* Ref.make<ReadonlyArray<CapturedTurn>>([]);
2779
+ const closedSessions = yield* Ref.make<ReadonlyArray<string>>([]);
2780
+ // A queued start has nobody to refuse, so a busy session must stay up.
2781
+ const backgroundWork = yield* Ref.make(queued);
2782
+ const started = yield* Deferred.make<void>();
2783
+ const release = yield* Deferred.make<void>();
2784
+ const layerRegistry = ProviderAdapterRegistry.layerFromAdapters([
2785
+ makeTestAdapter({
2786
+ instanceId: CLAUDE_MODEL_SELECTION.instanceId,
2787
+ driver: CLAUDE_DRIVER,
2788
+ capabilities: ClaudeProviderCapabilitiesV2,
2789
+ modelSelection: CLAUDE_MODEL_SELECTION,
2790
+ responseByRunOrdinal: {},
2791
+ capturedTurns,
2792
+ closedSessions,
2793
+ backgroundWork,
2794
+ nativeThreadGeneration: yield* Ref.make(0),
2795
+ ...(queued
2796
+ ? { holdFirstTurn: started, releaseFirstTurn: release, holdRunOrdinal: 2 }
2797
+ : {}),
2798
+ }),
2799
+ makeTestAdapter({
2800
+ instanceId: CODEX_MODEL_SELECTION.instanceId,
2801
+ driver: CODEX_DRIVER,
2802
+ capabilities: CodexProviderCapabilitiesV2,
2803
+ modelSelection: CODEX_MODEL_SELECTION,
2804
+ responseByRunOrdinal: {},
2805
+ capturedTurns,
2806
+ }),
2807
+ ]);
2808
+ const freshThreadId = ThreadId.make(`thread:fresh-context:${key}`);
2809
+ yield* Effect.gen(function* () {
2810
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
2811
+ const worker = yield* EffectWorker.OrchestrationEffectWorkerV2;
2812
+ const send = (
2813
+ name: string,
2814
+ modelSelection: ModelSelection,
2815
+ options: { readonly freshContext?: boolean } = {},
2816
+ ) =>
2817
+ orchestrator.dispatch({
2818
+ type: "message.dispatch",
2819
+ createdBy: "user",
2820
+ creationSource: "web",
2821
+ commandId: CommandId.make(`command:fresh-context:${key}:${name}`),
2822
+ threadId: freshThreadId,
2823
+ messageId: MessageId.make(`message:fresh-context:${key}:${name}`),
2824
+ text: `Prompt ${name}`,
2825
+ attachments: [],
2826
+ modelSelection,
2827
+ ...options,
2828
+ // A fresh send must never steer the running turn.
2829
+ deliveryIntent: "auto",
2830
+ dispatchMode: { type: "start_immediately" },
2831
+ });
2832
+ yield* orchestrator.dispatch({
2833
+ type: "thread.create",
2834
+ createdBy: "user",
2835
+ creationSource: "web",
2836
+ commandId: CommandId.make(`command:fresh-context:${key}:create`),
2837
+ threadId: freshThreadId,
2838
+ projectId: ProjectId.make(`project:fresh-context:${key}`),
2839
+ title: "Fresh context",
2840
+ modelSelection: CLAUDE_MODEL_SELECTION,
2841
+ runtimeMode: "full-access",
2842
+ interactionMode: "default",
2843
+ branch: null,
2844
+ worktreePath: cwd,
2845
+ });
2846
+ // Codex keeps a native thread from before the fresh run that must not resume.
2847
+ yield* send("zero", CODEX_MODEL_SELECTION);
2848
+ yield* worker.drain();
2849
+ yield* waitForIdle(freshThreadId);
2850
+ yield* send("alpha", CLAUDE_MODEL_SELECTION);
2851
+ if (queued) {
2852
+ yield* Deferred.await(started);
2853
+ yield* worker.drain();
2854
+ } else {
2855
+ yield* worker.drain();
2856
+ yield* waitForIdle(freshThreadId);
2857
+ }
2858
+ const firstSession = (yield* orchestrator.getThreadProjection(
2859
+ freshThreadId,
2860
+ )).providerSessions.find(
2861
+ (session) => session.providerInstanceId === CLAUDE_MODEL_SELECTION.instanceId,
2862
+ )!;
2863
+ yield* send("beta", CLAUDE_MODEL_SELECTION, { freshContext: true });
2864
+ if (queued) {
2865
+ // Queued before the fresh run started, so it is bound to the old conversation.
2866
+ yield* send("gamma", CLAUDE_MODEL_SELECTION);
2867
+ const waiting = yield* orchestrator.getThreadProjection(freshThreadId);
2868
+ assert.deepEqual(
2869
+ waiting.runs.map((run) => run.status),
2870
+ ["completed", "running", "queued", "queued"],
2871
+ );
2872
+ // Steering would send it into the conversation it is meant to leave.
2873
+ const promoted = yield* orchestrator
2874
+ .dispatch({
2875
+ type: "queued-message.promote-to-steer",
2876
+ commandId: CommandId.make(`command:fresh-context:${key}:promote`),
2877
+ threadId: freshThreadId,
2878
+ queuedRunId: waiting.runs.find((run) => run.freshContext === true)!.id,
2879
+ targetRunId: waiting.runs.find((run) => run.status === "running")!.id,
2880
+ })
2881
+ .pipe(Effect.flip);
2882
+ assert.instanceOf(promoted, Orchestrator.OrchestratorDispatchError);
2883
+ assert.include(String(promoted.cause), "fresh session");
2884
+ yield* Deferred.succeed(release, undefined);
2885
+ }
2886
+ yield* worker.drain();
2887
+ yield* waitForIdle(freshThreadId);
2888
+ // Claude hosts one native thread per session, so an idle old one is closed.
2889
+ assert.deepEqual(yield* Ref.get(closedSessions), queued ? [] : [firstSession.id]);
2890
+ yield* Ref.set(backgroundWork, false);
2891
+ yield* send("delta", CODEX_MODEL_SELECTION);
2892
+ yield* worker.drain();
2893
+ yield* waitForIdle(freshThreadId);
2894
+ yield* worker.drain();
2895
+ const projection = yield* orchestrator.getThreadProjection(freshThreadId);
2896
+ const turns = yield* Ref.get(capturedTurns);
2897
+ const turnFor = (name: string) =>
2898
+ turns.find((turn) => turn.text.endsWith(`Prompt ${name}`))!;
2899
+
2900
+ const freshRun = projection.runs.find(
2901
+ (run) => run.userMessageId === `message:fresh-context:${key}:beta`,
2902
+ )!;
2903
+ assert.isTrue(freshRun.freshContext);
2904
+ assert.equal(freshRun.contextHandoffId, null);
2905
+ assert.isTrue(
2906
+ projection.turnItems.some(
2907
+ (item) =>
2908
+ item.type === "user_message" &&
2909
+ item.messageId === freshRun.userMessageId &&
2910
+ item.freshContext === true,
2911
+ ),
2912
+ );
2913
+ assert.notEqual(turnFor("beta").providerThreadId, turnFor("alpha").providerThreadId);
2914
+ assert.notEqual(turnFor("beta").nativeThreadId, turnFor("alpha").nativeThreadId);
2915
+ assert.equal(turnFor("beta").text, "Prompt beta");
2916
+ if (queued) {
2917
+ assert.equal(turnFor("gamma").providerThreadId, turnFor("beta").providerThreadId);
2918
+ }
2919
+ const codexTurn = turnFor("delta");
2920
+ assert.notEqual(codexTurn.providerThreadId, turnFor("zero").providerThreadId);
2921
+ assert.include(codexTurn.text, "Prompt beta");
2922
+ assert.notInclude(codexTurn.text, "Prompt alpha");
2923
+ assert.notInclude(codexTurn.text, "Prompt zero");
2924
+ assert.equal(projection.contextHandoffs.at(-1)!.coveredRunOrdinals.from, 3);
2925
+ }).pipe(
2926
+ Effect.provide(
2927
+ ProviderReplayHarness.layerWithRegistry(
2928
+ {
2929
+ name: `fresh-context-${key}`,
2930
+ runtimePolicyOverride: {
2931
+ cwd,
2932
+ approvalPolicy: "never",
2933
+ sandboxPolicy: {
2934
+ type: "readOnly",
2935
+ access: { type: "fullAccess" },
2936
+ networkAccess: false,
2937
+ },
2938
+ },
2939
+ },
2940
+ layerRegistry,
2941
+ ),
2942
+ ),
2943
+ );
2944
+ }),
2945
+ ),
2946
+ );
2947
+
2948
+ it.live("keeps the thread a queued fresh run reserved for that run", () =>
2949
+ Effect.scoped(
2950
+ Effect.gen(function* () {
2951
+ const cwd = yield* checkpointWorkspace("fresh-context-reserved");
2952
+ const capturedTurns = yield* Ref.make<ReadonlyArray<CapturedTurn>>([]);
2953
+ const started = yield* Deferred.make<void>();
2954
+ const release = yield* Deferred.make<void>();
2955
+ const layerRegistry = ProviderAdapterRegistry.layerFromAdapters([
2956
+ makeTestAdapter({
2957
+ instanceId: CLAUDE_MODEL_SELECTION.instanceId,
2958
+ driver: CLAUDE_DRIVER,
2959
+ capabilities: ClaudeProviderCapabilitiesV2,
2960
+ modelSelection: CLAUDE_MODEL_SELECTION,
2961
+ responseByRunOrdinal: {},
2962
+ capturedTurns,
2963
+ nativeThreadGeneration: yield* Ref.make(0),
2964
+ holdFirstTurn: started,
2965
+ releaseFirstTurn: release,
2966
+ holdRunOrdinal: 2,
2967
+ }),
2968
+ makeTestAdapter({
2969
+ instanceId: CODEX_MODEL_SELECTION.instanceId,
2970
+ driver: CODEX_DRIVER,
2971
+ capabilities: CodexProviderCapabilitiesV2,
2972
+ modelSelection: CODEX_MODEL_SELECTION,
2973
+ responseByRunOrdinal: {},
2974
+ capturedTurns,
2975
+ nativeThreadGeneration: yield* Ref.make(0),
2976
+ }),
2977
+ ]);
2978
+ const reservedThreadId = ThreadId.make("thread:fresh-context-reserved");
2979
+ yield* Effect.gen(function* () {
2980
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
2981
+ const worker = yield* EffectWorker.OrchestrationEffectWorkerV2;
2982
+ const send = (
2983
+ name: string,
2984
+ modelSelection: ModelSelection,
2985
+ options: { readonly freshContext?: boolean } = {},
2986
+ ) =>
2987
+ orchestrator.dispatch({
2988
+ type: "message.dispatch",
2989
+ createdBy: "user",
2990
+ creationSource: "web",
2991
+ commandId: CommandId.make(`command:fresh-context-reserved:${name}`),
2992
+ threadId: reservedThreadId,
2993
+ messageId: MessageId.make(`message:fresh-context-reserved:${name}`),
2994
+ text: `Prompt ${name}`,
2995
+ attachments: [],
2996
+ modelSelection,
2997
+ ...options,
2998
+ dispatchMode: { type: "queue_after_active" },
2999
+ });
3000
+ yield* orchestrator.dispatch({
3001
+ type: "thread.create",
3002
+ createdBy: "user",
3003
+ creationSource: "web",
3004
+ commandId: CommandId.make("command:fresh-context-reserved:create"),
3005
+ threadId: reservedThreadId,
3006
+ projectId: ProjectId.make("project:fresh-context-reserved"),
3007
+ title: "Fresh context reserved",
3008
+ modelSelection: CODEX_MODEL_SELECTION,
3009
+ runtimeMode: "full-access",
3010
+ interactionMode: "default",
3011
+ branch: null,
3012
+ worktreePath: cwd,
3013
+ });
3014
+ yield* send("zero", CODEX_MODEL_SELECTION);
3015
+ yield* worker.drain();
3016
+ yield* waitForIdle(reservedThreadId);
3017
+ yield* send("alpha", CLAUDE_MODEL_SELECTION);
3018
+ yield* Deferred.await(started);
3019
+ yield* worker.drain();
3020
+ // Queued while no fresh run has started: gamma binds to zero's Codex thread, and
3021
+ // delta reserves its own. Once beta starts, gamma must not take delta's thread.
3022
+ yield* send("beta", CLAUDE_MODEL_SELECTION, { freshContext: true });
3023
+ yield* send("gamma", CODEX_MODEL_SELECTION);
3024
+ yield* send("delta", CODEX_MODEL_SELECTION, { freshContext: true });
3025
+ yield* Deferred.succeed(release, undefined);
3026
+ yield* worker.drain();
3027
+ yield* waitForIdle(reservedThreadId);
3028
+ yield* worker.drain();
3029
+ const turns = yield* Ref.get(capturedTurns);
3030
+ const turnFor = (name: string) =>
3031
+ turns.find((turn) => turn.text.endsWith(`Prompt ${name}`))!;
3032
+
3033
+ assert.notEqual(turnFor("gamma").providerThreadId, turnFor("zero").providerThreadId);
3034
+ assert.notEqual(turnFor("delta").providerThreadId, turnFor("gamma").providerThreadId);
3035
+ assert.notEqual(turnFor("delta").nativeThreadId, turnFor("gamma").nativeThreadId);
3036
+ assert.equal(turnFor("delta").text, "Prompt delta");
3037
+ }).pipe(
3038
+ Effect.provide(
3039
+ ProviderReplayHarness.layerWithRegistry(
3040
+ {
3041
+ name: "fresh-context-reserved",
3042
+ runtimePolicyOverride: {
3043
+ cwd,
3044
+ approvalPolicy: "never",
3045
+ sandboxPolicy: {
3046
+ type: "readOnly",
3047
+ access: { type: "fullAccess" },
3048
+ networkAccess: false,
3049
+ },
3050
+ },
3051
+ },
3052
+ layerRegistry,
3053
+ ),
3054
+ ),
3055
+ );
3056
+ }),
3057
+ ),
3058
+ );
3059
+
3060
// regression: #21314 a queued PR update must follow the provider that took over the thread
3061
it.live.each([
3062
["automatic", "Claude"],
packages/contracts/src/environment.ts
+2
@@ -168,6 +168,8 @@ export const ExecutionEnvironmentCapabilities = Schema.Struct({
168
triage: Schema.optionalKey(Schema.Boolean),
169
/** Server accepts `{ type: "once" }` scheduled tasks; older servers reject them on save. */
170
oneTimeSchedules: Schema.optionalKey(Schema.Boolean),
171
+ /** Server honors `freshContext` on sends; older servers ignore it and keep the old context. */
172
+ freshContext: Schema.optionalKey(Schema.Boolean),
173
});
174
export type ExecutionEnvironmentCapabilities = typeof ExecutionEnvironmentCapabilities.Type;
175
packages/contracts/src/orchestrationV2.ts
+6
@@ -705,6 +705,8 @@ export const OrchestrationV2Run = Schema.Struct({
705
),
706
delegatedCompletion: Schema.optional(OrchestrationV2DelegatedCompletionCohort),
707
workspacePreparation: Schema.optional(OrchestrationV2ThreadLaunchWorkspaceStrategy),
708
+ /** Starts a new provider conversation; earlier runs stay visible but never reach the provider. */
709
+ freshContext: Schema.optional(Schema.Boolean),
710
});
711
export type OrchestrationV2Run = typeof OrchestrationV2Run.Type;
712
@@ -1607,6 +1609,7 @@ export const OrchestrationV2TurnItem = Schema.Union([
1609
senderThreadId: Schema.optional(ThreadId),
1610
idleCompaction: Schema.optional(OrchestrationV2IdleCompaction),
1611
workflowScript: OrchestrationV2ConversationMessage.fields.workflowScript,
1612
+ freshContext: OrchestrationV2Run.fields.freshContext,
1613
inputIntent: OrchestrationV2UserMessageInputIntent,
1614
text: Schema.String,
1615
/** Same as the text of message `messageId`. */
@@ -2443,6 +2446,7 @@ export const OrchestrationV2TurnItemJson = Schema.Union([
2446
senderThreadId: Schema.optional(ThreadId),
2447
idleCompaction: Schema.optional(OrchestrationV2IdleCompaction),
2448
workflowScript: OrchestrationV2ConversationMessage.fields.workflowScript,
2449
+ freshContext: OrchestrationV2Run.fields.freshContext,
2450
inputIntent: OrchestrationV2UserMessageInputIntent,
2451
text: Schema.String,
2452
context: Schema.optional(OrchestrationMessageContext),
@@ -3152,6 +3156,8 @@ export const OrchestrationV2Command = Schema.Union([
3156
scheduledTaskId: Schema.optional(ScheduledTaskId),
3157
senderThreadId: Schema.optional(ThreadId),
3158
idleCompaction: Schema.optional(OrchestrationV2IdleCompaction),
3159
+ /** Start a new provider session without the thread's earlier context. Never steers. */
3160
+ freshContext: Schema.optional(Schema.Boolean),
3161
commandId: CommandId,
3162
threadId: ThreadId,
3163
messageId: MessageId,