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

main
ts 2,273 lines 95.4 KB
Raw
1 import { modelSelectionsEqual } from "@t3tools/shared/model";
2 import { projectComposerContextForProvider } from "@t3tools/shared/composerContextReferences";
3 import { expandAssistantCitationsForProvider } from "@t3tools/shared/assistantCitations";
4 import {
5 CommandId,
6 PROVIDER_SEND_TURN_MAX_INPUT_CHARS,
7 latestProviderTurnForAttempt,
8 withMessageSenderNote,
9 type OrchestrationV2DomainEvent,
10 type OrchestrationV2ContextHandoff,
11 type OrchestrationV2ExecutionNode,
12 type OrchestrationV2ProviderThread,
13 type OrchestrationV2Run,
14 type OrchestrationV2RunAttempt,
15 type OrchestrationV2ThreadProjection,
16 type OrchestrationV2TurnItem,
17 isCompactionCommandMessage,
18 parseGoalCommand,
19 RunId,
20 RunAttemptId,
21 NodeId,
22 ThreadId,
23 } from "@t3tools/contracts";
24 import * as Cause from "effect/Cause";
25 import * as Context from "effect/Context";
26 import * as DateTime from "effect/DateTime";
27 import * as Effect from "effect/Effect";
28 import * as FileSystem from "effect/FileSystem";
29 import * as Layer from "effect/Layer";
30 import * as Option from "effect/Option";
31 import * as Path from "effect/Path";
32 import * as Predicate from "effect/Predicate";
33 import * as Schema from "effect/Schema";
34
35 import * as ServerConfig from "../config.ts";
36 import {
37 CLAUDE_PROVIDER,
38 CLAUDE_QUERY_ENDED_BEFORE_TURN_DETAIL,
39 } from "./Adapters/ClaudeAdapterV2.ts";
40 import { withTurnStartReservation, withWorkspaceLease } from "../workspace/workspaceLease.ts";
41 import * as GitWorkflowService from "../git/GitWorkflowService.ts";
42 import * as ProjectService from "../project/ProjectService.ts";
43 import * as ProviderAuthService from "../provider/ProviderAuthService.ts";
44 import * as ServerSettings from "../serverSettings.ts";
45 import { makeRestoreMissingWorktree } from "../workspace/restoreMissingWorktree.ts";
46 import * as EventSink from "./EventSink.ts";
47 import * as ProviderUsageAnalytics from "../telemetry/ProviderUsageAnalytics.ts";
48 import * as ContextHandoffService from "./ContextHandoffService.ts";
49 import { canForkBusySourceNatively, isActiveRun } from "./CommandPolicy.ts";
50 import { contextBoundaryOrdinal, isScheduledFreshRun } from "./contextBoundary.ts";
51 import {
52 DEFAULT_HANDOFF_TOKEN_CAP,
53 handoffTokenCapConfig,
54 handoffBudget,
55 attachmentTokenAllowance,
56 estimateTextTokens,
57 contextUsageForHandoff,
58 historicalMessage,
59 latestNativeContextUsage,
60 } from "@t3tools/provider-core/server/handoffBudget";
61 import { deliverContextHandoffs, withInlineContext } from "./ContextHandoffDelivery.ts";
62 import { isProviderCommand, outputInstructions } from "./runOutput.ts";
63 import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
64 import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
65 import * as ProjectionStore from "./ProjectionStore.ts";
66 import { unsentManualContinuationSource } from "@t3tools/shared/orchestrationV2ManualContinuation";
67 import * as ProviderSessionManager from "./ProviderSessionManager.ts";
68 import {
69 ContextHandoffBackgroundWorkError,
70 knownProviderFailureMessage,
71 makeProviderFailure,
72 } from "@t3tools/provider-core/server/failure";
73 import * as RunExecutionService from "./RunExecutionService.ts";
74 import * as RuntimePolicy from "./RuntimePolicy.ts";
75 import * as TurnItemPositionStore from "./TurnItemPositionStore.ts";
76 import {
77 isRestartNoteContinuation,
78 pendingRestartCancelledBackgroundWork,
79 restartCancelledBackgroundWorkNote,
80 } from "./RestartBackgroundNote.ts";
81
82 export class ProviderTurnStartError extends Schema.TaggedError<ProviderTurnStartError>()(
83 "ProviderTurnStartError",
84 {
85 runId: RunId,
86 cause: Schema.optional(Schema.Defect()),
87 attemptId: Schema.optional(RunAttemptId),
88 rootNodeId: Schema.optional(NodeId),
89 },
90 ) {}
91
92 /** Runs that ended without completing: their provider turn may still project as running. */
93 const NON_COMPLETING_TERMINAL_RUN_STATUSES: ReadonlySet<OrchestrationV2Run["status"]> = new Set([
94 "failed",
95 "interrupted",
96 "cancelled",
97 "rolled_back",
98 ]);
99
100 export function abandonedProviderTurns(
101 projection: Pick<OrchestrationV2ThreadProjection, "runs" | "attempts" | "providerTurns">,
102 run: Pick<OrchestrationV2Run, "ordinal">,
103 providerThreadId: OrchestrationV2ProviderThread["id"],
104 ) {
105 const attemptsByRun = Map.groupBy(projection.attempts, (attempt) => attempt.runId);
106 const abandonedRuns = new Map<string | null, OrchestrationV2Run>();
107 for (const previous of projection.runs) {
108 if (
109 previous.ordinal >= run.ordinal ||
110 previous.providerThreadId !== providerThreadId ||
111 !NON_COMPLETING_TERMINAL_RUN_STATUSES.has(previous.status)
112 ) {
113 continue;
114 }
115 if (previous.activeAttemptId !== null) {
116 abandonedRuns.set(previous.activeAttemptId, previous);
117 }
118 for (const attempt of attemptsByRun.get(previous.id) ?? []) {
119 abandonedRuns.set(attempt.id, previous);
120 }
121 }
122 return projection.providerTurns.flatMap((turn) => {
123 const previous = abandonedRuns.get(turn.runAttemptId);
124 return turn.providerThreadId === providerThreadId &&
125 turn.status === "running" &&
126 previous !== undefined
127 ? [{ turn, run: previous }]
128 : [];
129 });
130 }
131
132 export const isProviderTurnStartError = Schema.is(ProviderTurnStartError);
133 const isProviderAdapterProtocolError = Schema.is(ProviderAdapter.ProviderAdapterProtocolError);
134 const isProviderAdapterOpenSessionError = Schema.is(
135 ProviderAdapter.ProviderAdapterOpenSessionError,
136 );
137
138 /**
139 * Claude refuses these before it reads the prompt: replacing a process running background work,
140 * launch arguments whose appended system prompt or settings cannot be read, or MCP registration
141 * that never answers while the query opens. A query that ends before the turn attaches (such as a
142 * rejected resume point) never received the prompt either.
143 */
144 const PROMPT_REFUSAL_TAGS = [
145 "ClaudeBackgroundWorkBlocksQueryReplacementError",
146 "ClaudeAppendSystemPromptFileError",
147 "ClaudeAppendSystemPromptMissingValueError",
148 "ClaudeSettingsLaunchArgError",
149 "ClaudeMcpRegistrationTimeoutError",
150 ] as const;
151
152 const refusedBeforePrompt = (error: unknown): boolean =>
153 PROMPT_REFUSAL_TAGS.some((tag) => Predicate.isTagged(error, tag)) ||
154 (isProviderAdapterProtocolError(error) &&
155 error.driver === CLAUDE_PROVIDER &&
156 error.detail === CLAUDE_QUERY_ENDED_BEFORE_TURN_DETAIL) ||
157 (Predicate.hasProperty(error, "cause") && refusedBeforePrompt(error.cause));
158
159 /**
160 * Whether a non-truncating provider's native session lost the conversation kept before `run`.
161 * Rollback resets it: the newest accepted turn was rolled back (works without legacy-missing
162 * native ids) or ran under another native id (rollback of runs the provider never accepted).
163 */
164 const nativeSessionMissesKeptTurns = (
165 projection: Pick<
166 OrchestrationV2ThreadProjection,
167 "thread" | "runs" | "attempts" | "providerTurns" | "contextHandoffs"
168 >,
169 providerThread: OrchestrationV2ProviderThread,
170 run: OrchestrationV2Run,
171 ): boolean => {
172 const nativeId = providerThread.nativeThreadRef?.nativeId;
173 if (nativeId === undefined) return false;
174 const acceptedAttemptIds = new Set(projection.providerTurns.map((turn) => turn.runAttemptId));
175 const accepted = projection.attempts.filter((attempt) => acceptedAttemptIds.has(attempt.id));
176 const runsById = new Map(projection.runs.map((source) => [source.id, source]));
177 const ordinalOf = (attempt: OrchestrationV2RunAttempt) =>
178 runsById.get(attempt.runId)?.ordinal ?? 0;
179 const newest = accepted
180 .filter((attempt) => attempt.providerThreadId === providerThread.id)
181 .toSorted((a, b) => ordinalOf(a) - ordinalOf(b) || a.attemptOrdinal - b.attemptOrdinal)
182 .at(-1);
183 if (newest === undefined) return false;
184 // Inherited fork history is kept even when every local run was rolled back.
185 const keepsHistory =
186 (projection.thread.forkedFrom?.type === "run" && projection.thread.lineage.sideChat !== true) ||
187 accepted.some((attempt) => {
188 const source = runsById.get(attempt.runId);
189 return (
190 source !== undefined && source.ordinal < run.ordinal && source.status !== "rolled_back"
191 );
192 });
193 return (
194 keepsHistory &&
195 (runsById.get(newest.runId)?.status === "rolled_back" ||
196 (newest.nativeThreadId !== undefined && newest.nativeThreadId !== nativeId)) &&
197 !projection.contextHandoffs.some(
198 (handoff) =>
199 handoff.toProviderThreadId === providerThread.id &&
200 handoff.delivery?.nativeThreadId === nativeId &&
201 handoff.delivery.status !== "pending",
202 )
203 );
204 };
205
206 /** Missing execution records cannot be repaired by retrying a start. */
207 export class ProviderTurnStartRunStateMissingError extends Schema.TaggedError<ProviderTurnStartRunStateMissingError>()(
208 "ProviderTurnStartRunStateMissingError",
209 {
210 runId: RunId,
211 },
212 ) {}
213
214 export const isProviderTurnStartRunStateMissingError = Schema.is(
215 ProviderTurnStartRunStateMissingError,
216 );
217
218 const RESUME_PROMPT = "Continue where you left off.";
219
220 const START_GAVE_UP_MESSAGE =
221 "T3 Code could not start this turn. Send the message again; if it keeps failing, check the server logs.";
222
223 const startFailureMessage = (error: Error): string => {
224 const nestedCause = "cause" in error ? error.cause : undefined;
225 return (
226 knownProviderFailureMessage(error) ??
227 (nestedCause instanceof Error
228 ? nestedCause.message
229 : typeof nestedCause === "string"
230 ? nestedCause
231 : error.message)
232 );
233 };
234
235 export interface ProviderTurnStartServiceV2Shape {
236 readonly start: (input: {
237 readonly threadId: ThreadId;
238 readonly runId: RunId;
239 readonly willRetry?: boolean;
240 }) => Effect.Effect<void, ProviderTurnStartError>;
241 readonly failStartingRun: (input: {
242 readonly threadId: ThreadId;
243 readonly runId: RunId;
244 readonly attemptId: RunAttemptId;
245 readonly rootNodeId: NodeId;
246 }) => Effect.Effect<void, ProviderTurnStartError | ProviderTurnStartRunStateMissingError>;
247 }
248
249 export class ProviderTurnStartServiceV2 extends Context.Service<
250 ProviderTurnStartServiceV2,
251 ProviderTurnStartServiceV2Shape
252 >()("t3/orchestration-v2/ProviderTurnStartService/ProviderTurnStartServiceV2") {}
253
254 export const layer: Layer.Layer<
255 ProviderTurnStartServiceV2,
256 never,
257 | EventSink.EventSinkV2
258 | ContextHandoffService.ContextHandoffServiceV2
259 | IdAllocator.IdAllocatorV2
260 | FileSystem.FileSystem
261 | Path.Path
262 | ServerConfig.ServerConfig
263 | ServerSettings.ServerSettingsService
264 | GitWorkflowService.GitWorkflowService
265 | ProjectService.ProjectService
266 | ProviderAuthService.ProviderAuthService
267 | ProjectionStore.ProjectionStoreV2
268 | ProviderSessionManager.ProviderSessionManagerV2
269 | RunExecutionService.RunExecutionServiceV2
270 | RuntimePolicy.RuntimePolicyV2
271 | TurnItemPositionStore.TurnItemPositionStoreV2
272 > = Layer.effect(
273 ProviderTurnStartServiceV2,
274 Effect.gen(function* () {
275 const eventSink = yield* EventSink.EventSinkV2;
276 const turnAnalytics = yield* ProviderUsageAnalytics.ProviderTurnAnalytics;
277 const contextHandoffService = yield* ContextHandoffService.ContextHandoffServiceV2;
278 const idAllocator = yield* IdAllocator.IdAllocatorV2;
279 const fileSystem = yield* FileSystem.FileSystem;
280 const path = yield* Path.Path;
281 const projects = yield* ProjectService.ProjectService;
282 const providerAuth = yield* ProviderAuthService.ProviderAuthService;
283 const projectionStore = yield* ProjectionStore.ProjectionStoreV2;
284 const providerSessions = yield* ProviderSessionManager.ProviderSessionManagerV2;
285 const runExecution = yield* RunExecutionService.RunExecutionServiceV2;
286 const runtimePolicy = yield* RuntimePolicy.RuntimePolicyV2;
287 const restoreMissingWorktree = yield* makeRestoreMissingWorktree;
288 const turnItemPositions = yield* TurnItemPositionStore.TurnItemPositionStoreV2;
289
290 // Build draining callbacks outside startup scope so they cannot retain full thread history.
291 const makeRunControls = (input: {
292 readonly threadId: ThreadId;
293 readonly runId: RunId;
294 readonly attemptId: OrchestrationV2RunAttempt["id"];
295 readonly providerThreadId: OrchestrationV2ProviderThread["id"];
296 readonly runOrdinal: number;
297 readonly worktreePath: string | null;
298 readonly inheritedBackgroundTurnItems: ReturnType<
299 typeof RunExecutionService.selectInheritedBackgroundTurnItems
300 >;
301 }) => {
302 const isCurrentAttemptIn = (statuses: ReadonlyArray<OrchestrationV2Run["status"]>) =>
303 projectionStore
304 .getRun(input.threadId, input.runId)
305 .pipe(
306 Effect.map(
307 (run) => run?.activeAttemptId === input.attemptId && statuses.includes(run.status),
308 ),
309 );
310 const isCurrentAttemptInStatus = (expectedStatus: OrchestrationV2Run["status"]) =>
311 isCurrentAttemptIn([expectedStatus]);
312 return {
313 isCurrentAttemptInStatus,
314 loadInheritedBackgroundTurnItems: () =>
315 projectionStore.getRuntimeRecoveryProjection(input.threadId).pipe(
316 Effect.map((current) =>
317 RunExecutionService.selectInheritedBackgroundTurnItems({
318 threadId: input.threadId,
319 currentProviderThreadId: input.providerThreadId,
320 currentRunOrdinal: input.runOrdinal,
321 runs: current.runs,
322 turnItems: current.turnItems,
323 }),
324 ),
325 Effect.catchCause(() => Effect.succeed(input.inheritedBackgroundTurnItems)),
326 ),
327 shouldStartProviderTurn: () => isCurrentAttemptInStatus("running"),
328 shouldFinalizeRun: () => isCurrentAttemptIn(["starting", "running"]),
329 hasUnpairedRunInterruptRequest: () =>
330 projectionStore
331 .hasUnpairedRunInterruptRequest(
332 input.threadId,
333 idAllocator.derive.runSignalTurnItem({
334 runId: input.runId,
335 signal: "interrupt-request",
336 }),
337 idAllocator.derive.runSignalTurnItem({
338 runId: input.runId,
339 signal: "interrupt-result",
340 }),
341 )
342 .pipe(Effect.catchCause(() => Effect.succeed(false))),
343 hasWorkspaceMoved: () =>
344 projectionStore.getRuntimeRecoveryProjection(input.threadId).pipe(
345 Effect.map((current) => current.thread.worktreePath !== input.worktreePath),
346 Effect.catchCause(() => Effect.succeed(false)),
347 ),
348 loadUnsettledWork: (threadId: ThreadId, nodeIds: ReadonlyArray<NodeId>) =>
349 projectionStore
350 .getThreadRecords(threadId, ["subagents", "nodes", "turnItems"], {
351 nodeIds,
352 subagentIds: nodeIds,
353 turnItemStatuses: ["pending", "running", "waiting"],
354 })
355 .pipe(
356 Effect.catchTags({
357 ProjectionStoreThreadNotFoundError: () =>
358 Effect.succeed({ subagents: [], nodes: [], turnItems: [] }),
359 }),
360 ),
361 loadRunInterruptReason: () =>
362 projectionStore
363 .getThreadRecords(input.threadId, ["turnItems"], {
364 turnItemTypes: ["run_interrupt_request"],
365 turnItemRunIds: [input.runId],
366 })
367 .pipe(
368 Effect.map(({ turnItems }) => {
369 const request = turnItems.find((item) => item.type === "run_interrupt_request");
370 return request?.type === "run_interrupt_request" ? request.message : undefined;
371 }),
372 Effect.catchCause(() => Effect.undefined),
373 ),
374 };
375 };
376
377 const makeDeliverySession = (
378 session: ProviderAdapter.ProviderAdapterV2SessionRuntime,
379 startWithHandoffs: (
380 input: Parameters<ProviderAdapter.ProviderAdapterV2SessionRuntime["startTurn"]>[0],
381 compact?: boolean,
382 ) => ReturnType<ProviderAdapter.ProviderAdapterV2SessionRuntime["startTurn"]>,
383 ) => {
384 let deliver: typeof startWithHandoffs | undefined = startWithHandoffs;
385 const start = (
386 input: Parameters<ProviderAdapter.ProviderAdapterV2SessionRuntime["startTurn"]>[0],
387 compact = false,
388 ) =>
389 Effect.suspend(() => {
390 if (deliver !== undefined) return deliver(input, compact);
391 return compact && session.compactThread !== undefined
392 ? session.compactThread(input)
393 : session.startTurn(input);
394 }).pipe(
395 Effect.ensuring(
396 Effect.sync(() => {
397 deliver = undefined;
398 }),
399 ),
400 );
401 return {
402 ...session,
403 startTurn: (input: Parameters<typeof session.startTurn>[0]) => start(input),
404 ...(session.resumeTurn === undefined
405 ? {}
406 : {
407 resumeTurn: (input: ProviderAdapter.ProviderAdapterV2ResumeTurnInput) =>
408 start(ProviderAdapter.resumeTurnInput(input)),
409 }),
410 ...(session.compactThread === undefined
411 ? {}
412 : {
413 compactThread: (input: Parameters<typeof session.startTurn>[0]) => start(input, true),
414 }),
415 };
416 };
417
418 const settleRunBeforeStart = Effect.fn("orchestrationV2.providerTurnStart.settleBeforeStart")(
419 function* (input: {
420 readonly run: OrchestrationV2Run;
421 readonly rootNode: OrchestrationV2ExecutionNode;
422 readonly attempt: OrchestrationV2RunAttempt;
423 readonly turnItems: ReadonlyArray<OrchestrationV2TurnItem>;
424 readonly signal: string;
425 readonly status: "completed" | "failed";
426 readonly now: DateTime.Utc;
427 readonly startedAt?: DateTime.Utc;
428 readonly providerInstanceId: OrchestrationV2Run["providerInstanceId"];
429 readonly itemProviderThreadId: OrchestrationV2ProviderThread["id"] | null;
430 readonly item:
431 | Pick<Extract<OrchestrationV2TurnItem, { type: "error" }>, "type" | "title" | "failure">
432 | Pick<
433 Extract<OrchestrationV2TurnItem, { type: "command_execution" }>,
434 "type" | "title" | "input" | "output" | "exitCode"
435 >;
436 readonly providerThreadUpdate?: OrchestrationV2ProviderThread;
437 }) {
438 const { run, rootNode, attempt, turnItems, now, status } = input;
439 const runId = run.id;
440 const started = input.startedAt === undefined ? {} : { startedAt: input.startedAt };
441 const item: OrchestrationV2TurnItem = {
442 id: idAllocator.derive.runSignalTurnItem({ runId, signal: input.signal }),
443 threadId: run.threadId,
444 runId,
445 nodeId: rootNode.id,
446 providerThreadId: input.itemProviderThreadId,
447 providerTurnId: null,
448 nativeItemRef: null,
449 parentItemId: null,
450 ordinal:
451 Math.max(
452 0,
453 ...turnItems.filter((item) => item.runId === runId).map((item) => item.ordinal),
454 ) + 1,
455 status,
456 startedAt: now,
457 completedAt: now,
458 updatedAt: now,
459 ...input.item,
460 };
461 const eventPayloads = [
462 { type: "turn-item.updated", payload: item },
463 { type: "run.updated", payload: { ...run, status, ...started, completedAt: now } },
464 {
465 type: "run-attempt.updated",
466 payload: { ...attempt, status, ...started, completedAt: now },
467 },
468 {
469 type: "node.updated",
470 payload: { ...rootNode, status, ...started, completedAt: now },
471 },
472 ...(input.providerThreadUpdate === undefined
473 ? []
474 : [
475 {
476 type: "provider-thread.updated" as const,
477 payload: input.providerThreadUpdate,
478 },
479 ]),
480 ] as const;
481 const events = yield* Effect.forEach(eventPayloads, (event) =>
482 Effect.gen(function* () {
483 return {
484 ...event,
485 id: yield* idAllocator.allocate.event({ threadId: run.threadId }),
486 threadId: run.threadId,
487 runId,
488 nodeId: rootNode.id,
489 providerInstanceId: input.providerInstanceId,
490 occurredAt: now,
491 } satisfies OrchestrationV2DomainEvent;
492 }),
493 );
494 const written = yield* eventSink.writeIfRunCurrent({
495 threadId: run.threadId,
496 runId,
497 activeAttemptId: attempt.id,
498 expectedStatus: "starting",
499 events,
500 });
501 // A steering restart that cannot start still ends a run whose earlier turns counted.
502 if (written.committed) {
503 yield* turnAnalytics.runSettled({
504 runId,
505 status,
506 completedAt: now,
507 childrenRunning: false,
508 });
509 }
510 },
511 );
512
513 const start = Effect.fn("orchestrationV2.providerTurnStart.start")(function* (
514 input: {
515 readonly threadId: ThreadId;
516 readonly runId: RunId;
517 readonly willRetry?: boolean;
518 },
519 captureStartingRun: (run: OrchestrationV2Run) => void,
520 ) {
521 const { runId } = input;
522 const projection = yield* projectionStore.getTurnStartContext(input.threadId, runId);
523 const run = projection.runs.find((candidate) => candidate.id === runId);
524 if (run === undefined) {
525 return yield* new ProviderTurnStartError({ runId, cause: `Run ${runId} was not found.` });
526 }
527 if (run.status !== "starting") {
528 return;
529 }
530 captureStartingRun(run);
531 const rootNode = projection.nodes.find((candidate) => candidate.id === run.rootNodeId);
532 const attempt = projection.attempts.find((candidate) => candidate.id === run.activeAttemptId);
533 const providerThread = projection.providerThreads.find(
534 (candidate) => candidate.id === run.providerThreadId,
535 );
536 const message = projection.messages.find((candidate) => candidate.id === run.userMessageId);
537 const checkpointScope = projection.checkpointScopes.find(
538 (candidate) => candidate.id === rootNode?.checkpointScopeId,
539 );
540 // Older versions also stored subagent replies as history handoffs. Their
541 // queued completion messages carry the results without a history budget.
542 const subagentResultTransfers = new Set(
543 projection.contextTransfers
544 .filter((transfer) => transfer.type === "subagent_result")
545 .map((transfer) => transfer.id),
546 );
547 const isPendingForRun = (handoff: OrchestrationV2ContextHandoff, anyProviderThread = false) =>
548 handoff.status === "ready" &&
549 (handoff.targetRunId === run.id ||
550 ((anyProviderThread || handoff.toProviderThreadId === run.providerThreadId) &&
551 projection.runs.some(
552 (source) =>
553 source.id === handoff.targetRunId &&
554 // A settled delivery retires history of this thread: the session that took it
555 // holds it, and a fresh session starts from a full summary of the thread. That
556 // summary lacks another thread's history (a fork source, a merge-back).
557 (((source.status === "failed" ||
558 source.status === "interrupted" ||
559 source.status === "cancelled") &&
560 !(
561 (handoff.delivery?.status === "injected" ||
562 handoff.delivery?.status === "inline") &&
563 handoff.fromProviderThreadIds.length > 0 &&
564 handoff.fromProviderThreadIds.every((id) =>
565 projection.providerThreads.some((candidate) => candidate.id === id),
566 )
567 )) ||
568 (source.status === "completed" &&
569 handoff.delivery === undefined &&
570 // Compaction and /goal turns defer history to the next turn.
571 projection.messages.some(
572 (message) =>
573 message.id === source.userMessageId &&
574 (isCompactionCommandMessage(message) || parseGoalCommand(message) !== null),
575 ))),
576 )));
577 const isSideChatHandoff = (handoff: OrchestrationV2ContextHandoff) =>
578 projection.thread.lineage.sideChat === true &&
579 ContextHandoffService.isSideChatContextHandoff(handoff);
580 const handoffs = projection.contextHandoffs.filter(
581 (handoff) =>
582 !isSideChatHandoff(handoff) &&
583 (handoff.transferId == null || !subagentResultTransfers.has(handoff.transferId)) &&
584 isPendingForRun(handoff),
585 );
586 // Carried forward until a provider turn accepts them, also after a provider switch. A fresh
587 // session starts without them, and an unscheduled fresh run retires them. A schedule's fresh
588 // run is a side conversation, so the thread's next turn still gets them.
589 const carriedSideChatHandoffs = projection.contextHandoffs.filter(
590 (handoff) =>
591 isSideChatHandoff(handoff) &&
592 handoff.delivery === undefined &&
593 isPendingForRun(handoff, true),
594 );
595 const sideChatHandoff = run.freshContext === true ? undefined : carriedSideChatHandoffs[0];
596 const nativeForkTransfer = projection.contextTransfers.find(
597 (transfer) =>
598 transfer.type === "fork" &&
599 transfer.targetThreadId === input.threadId &&
600 transfer.targetRunId === run.id &&
601 transfer.status === "pending" &&
602 transfer.resolution === null,
603 );
604 if (
605 rootNode === undefined ||
606 attempt === undefined ||
607 providerThread === undefined ||
608 providerThread.providerSessionId === null ||
609 message === undefined ||
610 checkpointScope === undefined
611 ) {
612 return yield* new ProviderTurnStartError({
613 runId,
614 cause: `Run ${runId} is missing its execution projection state.`,
615 });
616 }
617 if (
618 carriedSideChatHandoffs.length > 0 &&
619 run.freshContext === true &&
620 !isScheduledFreshRun(run, projection.turnItems)
621 ) {
622 const updatedAt = yield* DateTime.now;
623 const retired = yield* eventSink.writeIfRunCurrent({
624 threadId: run.threadId,
625 runId,
626 activeAttemptId: attempt.id,
627 expectedStatus: "starting",
628 events: yield* Effect.forEach(carriedSideChatHandoffs, (handoff) =>
629 Effect.map(idAllocator.allocate.event({ threadId: projection.thread.id }), (id) => ({
630 id,
631 type: "context-handoff.updated" as const,
632 threadId: projection.thread.id,
633 runId: run.id,
634 providerInstanceId: run.providerInstanceId,
635 occurredAt: updatedAt,
636 payload: { ...handoff, status: "superseded" as const, updatedAt },
637 })),
638 ),
639 });
640 if (!retired.committed) return;
641 }
642 const manualResume =
643 run.manualContinuationOfRunId !== undefined && attempt.reason !== "steering_restart";
644 const resumeSource = manualResume
645 ? unsentManualContinuationSource(run, projection)
646 : undefined;
647 const unsentResumeMessage =
648 resumeSource !== undefined
649 ? projection.messages.find((source) => source.id === resumeSource.userMessageId)
650 : undefined;
651 const providerMessage = unsentResumeMessage ?? message;
652 const settleStartFailure = Effect.fn("ProviderTurnStartService.settleStartFailure")(
653 function* (failed: {
654 readonly signal: string;
655 readonly title: string;
656 readonly error: Error;
657 readonly message?: string;
658 }) {
659 yield* settleRunBeforeStart({
660 run,
661 rootNode,
662 attempt,
663 turnItems: projection.turnItems,
664 signal: failed.signal,
665 status: "failed",
666 now: yield* DateTime.now,
667 providerInstanceId: run.providerInstanceId,
668 itemProviderThreadId: providerThread.id,
669 item: {
670 type: "error",
671 title: failed.title,
672 failure: makeProviderFailure({
673 cause: failed.error,
674 message: failed.message ?? startFailureMessage(failed.error),
675 class: "provider_error",
676 }),
677 },
678 });
679 },
680 );
681 if (
682 expandAssistantCitationsForProvider(providerMessage.text).length >
683 PROVIDER_SEND_TURN_MAX_INPUT_CHARS
684 ) {
685 yield* settleRunBeforeStart({
686 run,
687 rootNode,
688 attempt,
689 turnItems: projection.turnItems,
690 signal: "expanded-input-too-long",
691 status: "failed",
692 now: yield* DateTime.now,
693 providerInstanceId: run.providerInstanceId,
694 itemProviderThreadId: providerThread.id,
695 item: {
696 type: "error",
697 title: "Message is too long",
698 failure: makeProviderFailure({
699 class: "validation_error",
700 message: `Message exceeds ${PROVIDER_SEND_TURN_MAX_INPUT_CHARS.toLocaleString("en-US")} characters after expanding quotes. Shorten it and try again.`,
701 }),
702 },
703 });
704 return;
705 }
706 if (
707 providerMessage.attachments.length === 0 &&
708 providerMessage.text.trimStart().startsWith("/")
709 ) {
710 const isEmptyCompaction =
711 providerMessage.text.trim().toLowerCase() === "/compact" && !projection.hasConversation;
712 // Preparation may select a new provider; account commands still target the last native session.
713 const nativeThreads = new Map(
714 projection.providerThreads
715 .filter(
716 (candidate) => candidate.ownerNodeId === null && candidate.nativeThreadRef !== null,
717 )
718 .map((candidate) => [candidate.id, candidate]),
719 );
720 const previousNativeRun = projection.runs.reduce<OrchestrationV2Run | undefined>(
721 (previous, candidate) =>
722 candidate.ordinal < run.ordinal &&
723 candidate.providerThreadId !== null &&
724 nativeThreads.has(candidate.providerThreadId) &&
725 (previous === undefined || candidate.ordinal > previous.ordinal)
726 ? candidate
727 : previous,
728 undefined,
729 );
730 const nativeThread = nativeThreads.get(
731 previousNativeRun?.providerThreadId ??
732 projection.thread.activeProviderThreadId ??
733 providerThread.id,
734 );
735 const authInstanceId = nativeThread?.providerInstanceId ?? run.providerInstanceId;
736 const authResult = isEmptyCompaction
737 ? null
738 : yield* Effect.result(
739 providerAuth.tryHandlePromptCommand({
740 instanceId: authInstanceId,
741 text: projectComposerContextForProvider({
742 text: providerMessage.text,
743 records: providerMessage.context?.records ?? [],
744 }),
745 hasAttachments: false,
746 // A scheduled delivery keeps its task author's createdBy.
747 sentByPerson:
748 providerMessage.createdBy === "user" &&
749 providerMessage.scheduledTaskId === undefined,
750 }),
751 );
752 if (isEmptyCompaction || authResult?._tag === "Failure" || authResult?.success) {
753 const now = yield* DateTime.now;
754 const failure = isEmptyCompaction
755 ? makeProviderFailure({
756 class: "validation_error",
757 message: "Start a conversation before compacting this thread.",
758 })
759 : authResult?._tag === "Failure"
760 ? makeProviderFailure({
761 class: "permission_error",
762 message: authResult.failure.detail,
763 })
764 : undefined;
765 const status = failure === undefined ? "completed" : "failed";
766 yield* settleRunBeforeStart({
767 run,
768 rootNode,
769 attempt,
770 turnItems: projection.turnItems,
771 signal: isEmptyCompaction ? "empty-compaction" : "provider-sign-out",
772 status,
773 now,
774 startedAt: now,
775 providerInstanceId: authInstanceId,
776 itemProviderThreadId: nativeThread?.id ?? providerThread.id,
777 item:
778 failure !== undefined
779 ? {
780 type: "error",
781 title: isEmptyCompaction
782 ? "Cannot compact an empty thread"
783 : "Provider sign-out failed",
784 failure,
785 }
786 : {
787 type: "command_execution",
788 title: "Provider signed out",
789 input: providerMessage.text.trim(),
790 output: "Provider signed out",
791 exitCode: 0,
792 },
793 providerThreadUpdate: {
794 ...providerThread,
795 status:
796 providerThread.status === "error"
797 ? "error"
798 : providerThread.nativeThreadRef === null
799 ? "not_loaded"
800 : "idle",
801 updatedAt: now,
802 },
803 });
804 return;
805 }
806 }
807 const recreateResult = yield* Effect.result(restoreMissingWorktree(projection.thread));
808 if (recreateResult._tag === "Failure") {
809 if (input.willRetry === true) return yield* recreateResult.failure;
810 yield* settleStartFailure({
811 signal: "worktree-recreate-failure",
812 title: "Couldn't recreate thread workspace",
813 error: recreateResult.failure,
814 message: recreateResult.failure.message,
815 });
816 return;
817 }
818 const selectInheritedBackgroundItems = (
819 current: ProjectionStore.ProjectionRuntimeRecoveryState,
820 ): ReturnType<typeof RunExecutionService.selectInheritedBackgroundTurnItems> =>
821 RunExecutionService.selectInheritedBackgroundTurnItems({
822 threadId: current.thread.id,
823 currentProviderThreadId: providerThread.id,
824 currentRunOrdinal: run.ordinal,
825 runs: current.runs,
826 turnItems: current.turnItems,
827 });
828 const recoveryResult = yield* Effect.result(
829 projectionStore.getRuntimeRecoveryProjection(projection.thread.id),
830 );
831 if (recoveryResult._tag === "Failure") {
832 if (input.willRetry === true) return yield* recoveryResult.failure;
833 yield* settleStartFailure({
834 signal: "runtime-recovery-read-failure",
835 title: "Couldn't read thread state",
836 error: recoveryResult.failure,
837 });
838 return;
839 }
840 const inheritedBackgroundTurnItems = selectInheritedBackgroundItems(recoveryResult.success);
841 const providerSessionId = providerThread.providerSessionId;
842 const runControls = makeRunControls({
843 threadId: projection.thread.id,
844 runId: run.id,
845 attemptId: attempt.id,
846 providerThreadId: providerThread.id,
847 runOrdinal: run.ordinal,
848 worktreePath: projection.thread.worktreePath,
849 inheritedBackgroundTurnItems,
850 });
851 const { isCurrentAttemptInStatus } = runControls;
852
853 const resolvedPolicy = yield* runtimePolicy
854 .resolve({
855 thread: projection.thread,
856 modelSelection: run.modelSelection,
857 })
858 .pipe(Effect.result);
859 if (resolvedPolicy._tag === "Failure") {
860 const error = resolvedPolicy.failure;
861 if (error._tag !== "RuntimePolicyAboveCeilingError") return yield* error;
862 yield* settleStartFailure({
863 signal: "runtime-mode-above-ceiling",
864 title: "Thread mode is above the policy limit",
865 error,
866 message: error.message,
867 });
868 return;
869 }
870 const resolvedRuntimePolicy = resolvedPolicy.success;
871 if (!(yield* isCurrentAttemptInStatus("starting"))) return;
872 const existingSessionProjection = projection.providerSessions.find(
873 (candidate) => candidate.id === providerSessionId,
874 );
875 // A run that ended without completing can leave its provider turn projected as
876 // running when the agent ignored Stop or an interrupt timed out. Every attempt
877 // of such a run owns a possible abandoned turn, including attempts a steering
878 // restart superseded, and the session cannot be reused until those turns stop.
879 const abandonedTurns = abandonedProviderTurns(projection, run, providerThread.id);
880 const abandonedTurn = abandonedTurns.at(-1)?.turn;
881 if (abandonedTurn !== undefined) {
882 const liveSession = yield* providerSessions.get(providerSessionId);
883 if (Option.isSome(liveSession)) {
884 // The run already ended without stopping its provider — a failed start, an
885 // ignored Stop, or an interrupt that never confirmed. Recover that exact
886 // turn before reusing its native conversation.
887 const recovered = yield* Effect.result(
888 liveSession.value.interruptTurn({
889 providerThread,
890 providerTurnId: abandonedTurn.id,
891 requestRuntimeRestart: true,
892 }),
893 );
894 if (recovered._tag === "Failure") {
895 if (input.willRetry === true) return yield* recovered.failure;
896 yield* settleStartFailure({
897 signal: "provider-turn-recovery-failure",
898 title: "Provider turn recovery failed",
899 error: recovered.failure,
900 });
901 return;
902 }
903 }
904 const completedAt = yield* DateTime.now;
905 const repaired = yield* eventSink.writeIfRunCurrent({
906 threadId: projection.thread.id,
907 runId: run.id,
908 activeAttemptId: attempt.id,
909 expectedStatus: "starting",
910 events: yield* Effect.forEach(abandonedTurns, ({ turn, run: abandonedRun }) =>
911 Effect.gen(function* () {
912 return {
913 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
914 type: "provider-turn.updated" as const,
915 threadId: projection.thread.id,
916 runId: abandonedRun.id,
917 nodeId: turn.nodeId,
918 providerInstanceId: abandonedRun.providerInstanceId,
919 occurredAt: completedAt,
920 payload: { ...turn, status: "interrupted" as const, completedAt },
921 };
922 }),
923 ),
924 });
925 if (!repaired.committed) return;
926 }
927 // Opening a session does not prompt the provider, so the workspace is still unchanged.
928 const baseline = yield* runExecution.forkBaseline({
929 appThread: projection.thread,
930 run,
931 checkpointScope,
932 });
933 const brokenNativeThread = providerThread.status === "error";
934 // Opened without the broken native id, a session that was not live starts fresh.
935 const opensFreshSession =
936 brokenNativeThread &&
937 providerThread.nativeThreadRef !== null &&
938 !(yield* providerSessions.isLive(providerSessionId));
939 const sessionResult = yield* Effect.result(
940 providerSessions.open({
941 threadId: projection.thread.id,
942 providerSessionId,
943 modelSelection: run.modelSelection,
944 runtimePolicy: resolvedRuntimePolicy,
945 ...(existingSessionProjection === undefined
946 ? {}
947 : { resumeFromSession: existingSessionProjection }),
948 ...(providerThread.nativeThreadRef?.nativeId == null || brokenNativeThread
949 ? {}
950 : { initialNativeThreadId: providerThread.nativeThreadRef.nativeId }),
951 ...(providerThread.nativeMetadata?.itemIdentityVersion === undefined
952 ? {}
953 : {
954 initialProviderItemIdentityVersion:
955 providerThread.nativeMetadata.itemIdentityVersion,
956 }),
957 }),
958 );
959 if (sessionResult._tag === "Failure") {
960 const failure = sessionResult.failure;
961 const requiresSignIn =
962 "cause" in failure &&
963 isProviderAdapterOpenSessionError(failure.cause) &&
964 failure.cause.requiresSignIn === true;
965 if (input.willRetry === true && !requiresSignIn) return yield* failure;
966 yield* settleStartFailure({
967 signal: "provider-session-open-failure",
968 title: "Provider session failed to open",
969 error: sessionResult.failure,
970 });
971 return;
972 }
973 const session = sessionResult.success;
974 if (!(yield* isCurrentAttemptInStatus("starting"))) return;
975 const loadFromProvider = Effect.fn("ProviderTurnStartService.loadFromProvider")(function* (
976 load: Effect.Effect<OrchestrationV2ProviderThread, ProviderAdapter.ProviderAdapterV2Error>,
977 ) {
978 const loaded = yield* Effect.result(load);
979 if (loaded._tag === "Success") return loaded.success;
980 if (input.willRetry === true) return yield* loaded.failure;
981 yield* settleStartFailure({
982 signal: "provider-thread-load-failure",
983 title: "Provider turn failed to start",
984 error: loaded.failure,
985 });
986 return undefined;
987 });
988 let effectiveHandoffs = handoffs;
989 let resumeFellBack = false;
990 const messageText = withMessageSenderNote(
991 providerMessage,
992 projectComposerContextForProvider({
993 text: providerMessage.text,
994 records: providerMessage.context?.records ?? [],
995 }),
996 );
997 // Native goal commands go verbatim; handoff history waits a turn.
998 const goalDriver =
999 session.driver === "codex" ||
1000 session.driver === "claudeAgent" ||
1001 session.providerSession.capabilities.turns.supportsNativeGoals === true;
1002 const goalCommand = goalDriver && parseGoalCommand(providerMessage) !== null;
1003 // Part of the user text, so every way a turn starts carries it, after the user's own words.
1004 const userText =
1005 run.outputSchema === undefined || goalCommand || isProviderCommand(providerMessage)
1006 ? messageText
1007 : `${messageText}\n\n${outputInstructions(run.outputSchema)}`;
1008 // The provider turn marks cancellation work delivered; restart continuations use their own text or resume natively.
1009 const noteContinuation = isRestartNoteContinuation(
1010 run,
1011 projection.runs,
1012 projection.providerTurns,
1013 projection.attempts,
1014 );
1015 const restartCancelledWork = pendingRestartCancelledBackgroundWork({
1016 runs: projection.runs,
1017 providerTurns: projection.providerTurns,
1018 compactionMessageIds: () =>
1019 new Set(
1020 projection.messages
1021 .filter(
1022 (candidate) =>
1023 isCompactionCommandMessage(candidate) ||
1024 (goalDriver && parseGoalCommand(candidate) !== null),
1025 )
1026 .map((candidate) => candidate.id),
1027 ),
1028 run,
1029 attempts: projection.attempts,
1030 });
1031 const restartNote =
1032 restartCancelledWork.length === 0
1033 ? ""
1034 : restartCancelledBackgroundWorkNote(restartCancelledWork);
1035 const tokenCap = yield* handoffTokenCapConfig.pipe(
1036 Effect.orElseSucceed(() => DEFAULT_HANDOFF_TOKEN_CAP),
1037 );
1038 const handoffContextForThread = (loadedProviderThread: OrchestrationV2ProviderThread) => {
1039 const measuredContext = latestNativeContextUsage(projection, providerThread);
1040 const previousSelection =
1041 measuredContext?.modelSelection ??
1042 projection.runs.findLast(
1043 (source) =>
1044 source.ordinal < run.ordinal &&
1045 source.startedAt !== null &&
1046 source.providerThreadId === providerThread.id,
1047 )?.modelSelection;
1048 const sameSelection =
1049 previousSelection === undefined ||
1050 modelSelectionsEqual(previousSelection, run.modelSelection);
1051 const sameNativeThread =
1052 loadedProviderThread.nativeThreadRef?.nativeId ===
1053 providerThread.nativeThreadRef?.nativeId;
1054 const threadUsage = loadedProviderThread.contextUsage ?? providerThread.contextUsage;
1055 const previousUsage = measuredContext
1056 ? { ...threadUsage, ...measuredContext.usage }
1057 : threadUsage;
1058 const reuseTelemetry =
1059 sameSelection ||
1060 (previousSelection !== undefined &&
1061 session.canReuseContextUsage?.(previousSelection, run.modelSelection) === true);
1062 const knownModelWindow = session.getModelContextWindow?.(
1063 run.modelSelection,
1064 resolvedRuntimePolicy.cwd,
1065 );
1066 const handoffUsage = contextUsageForHandoff({
1067 sameNativeThread,
1068 sameSelection,
1069 reuseTelemetry,
1070 previousUsage,
1071 knownModelWindow,
1072 });
1073 const settledHandoffs = projection.contextHandoffs.filter(
1074 (handoff) =>
1075 handoff.toProviderThreadId === providerThread.id &&
1076 handoff.delivery?.nativeThreadId === loadedProviderThread.nativeThreadRef?.nativeId &&
1077 handoff.delivery?.status !== "pending",
1078 );
1079 const deliveredItemIds = new Set(
1080 settledHandoffs.flatMap((handoff) => handoff.delivery?.itemIds ?? []),
1081 );
1082 const coveredItemIds = new Set([
1083 ...deliveredItemIds,
1084 ...settledHandoffs.flatMap((handoff) => handoff.delivery?.omittedItemIds ?? []),
1085 ]);
1086 const deliveredAttemptIds = new Set(
1087 projection.providerTurns.map((turn) => turn.runAttemptId),
1088 );
1089 const acceptedAttempts = projection.attempts.filter(
1090 (source) =>
1091 source.providerThreadId === providerThread.id && deliveredAttemptIds.has(source.id),
1092 );
1093 const nativeInputRunIds = new Set(
1094 acceptedAttempts
1095 .filter(
1096 (source) =>
1097 source.nativeThreadId !== undefined &&
1098 source.nativeThreadId === loadedProviderThread.nativeThreadRef?.nativeId,
1099 )
1100 .map((source) => source.runId),
1101 );
1102 const legacyInputRunIds = new Set(
1103 acceptedAttempts
1104 .filter((source) => source.nativeThreadId === undefined)
1105 .map((source) => source.runId),
1106 );
1107 const legacyRecoveredRunIds = new Set(
1108 projection.runs
1109 .filter(
1110 (source) =>
1111 source.providerThreadId === providerThread.id &&
1112 settledHandoffs.some(
1113 (handoff) =>
1114 handoff.strategy === "full_thread_summary" &&
1115 handoff.fromProviderThreadIds.includes(providerThread.id) &&
1116 source.ordinal >= handoff.coveredRunOrdinals.from &&
1117 source.ordinal <= handoff.coveredRunOrdinals.to,
1118 ),
1119 )
1120 .map((source) => source.id),
1121 );
1122 // Row identity survives recovery; only accepted native input and delivered history occupy the new session.
1123 const nativeContextEstimate = Effect.gen(function* () {
1124 return sameNativeThread
1125 ? (yield* projectionStore.getTurnStartHistory(input.threadId)).reduce((sum, item) => {
1126 const acceptedNatively =
1127 item.providerThreadId === providerThread.id &&
1128 item.runId !== null &&
1129 (nativeInputRunIds.has(item.runId) ||
1130 (legacyInputRunIds.has(item.runId) &&
1131 !coveredItemIds.has(item.id) &&
1132 !legacyRecoveredRunIds.has(item.runId)));
1133 if (item.runId === run.id || (!acceptedNatively && !deliveredItemIds.has(item.id)))
1134 return sum;
1135 const historical = historicalMessage(item);
1136 const nativeAttachments =
1137 item.type === "user_message" && acceptedNatively
1138 ? attachmentTokenAllowance(item.attachments)
1139 : 0;
1140 return (
1141 sum +
1142 (historical === null ? 0 : estimateTextTokens(historical.text)) +
1143 nativeAttachments
1144 );
1145 }, 0)
1146 : 0;
1147 });
1148 const modelContextWindow =
1149 knownModelWindow ??
1150 (handoffUsage !== null || reuseTelemetry ? previousUsage?.maxTokens : undefined);
1151 const budgetProviderThread = {
1152 ...loadedProviderThread,
1153 contextUsage: handoffUsage,
1154 };
1155 const missedRuns = projection.runs.filter(
1156 (source) =>
1157 source.ordinal < run.ordinal &&
1158 source.providerThreadId === providerThread.id &&
1159 (source.status === "failed" || source.status === "interrupted") &&
1160 !deliveredAttemptIds.has(source.activeAttemptId),
1161 );
1162 const missedRunIds = new Set(missedRuns.map((source) => source.id));
1163 return {
1164 sameNativeThread,
1165 handoffUsage,
1166 deliveredItemIds,
1167 coveredItemIds,
1168 acceptedAttempts,
1169 nativeInputRunIds,
1170 legacyInputRunIds,
1171 missedRuns,
1172 missedRunIds,
1173 budget: Effect.gen(function* () {
1174 return handoffBudget({
1175 tokenCap,
1176 modelContextWindow,
1177 userText: restartNote === "" ? userText : `${restartNote}\n\n${userText}`,
1178 attachments: providerMessage.attachments,
1179 providerThread: budgetProviderThread,
1180 nativeContextEstimate:
1181 budgetProviderThread.contextUsage?.usedTokens === undefined
1182 ? yield* nativeContextEstimate
1183 : 0,
1184 });
1185 }),
1186 };
1187 };
1188 const prepareRetryHandoff = Effect.fn("ProviderTurnStartService.prepareRetryHandoff")(
1189 function* (context: ReturnType<typeof handoffContextForThread>) {
1190 const { missedRunIds, coveredItemIds, missedRuns, acceptedAttempts } = context;
1191 const missedHistory =
1192 missedRunIds.size === 0
1193 ? []
1194 : (yield* projectionStore.getTurnStartHistory(input.threadId, [
1195 ...missedRunIds,
1196 ])).filter((item) => item.runId !== null && missedRunIds.has(item.runId));
1197 const missedItems = missedHistory.filter(
1198 (item) => !coveredItemIds.has(item.id) && historicalMessage(item) !== null,
1199 );
1200 // The resume fallback summary already covers every earlier run in order. A
1201 // retry copy after it would rank older missed requests as the newest history.
1202 const handoffs =
1203 missedItems.length === 0 || resumeFellBack
1204 ? []
1205 : [
1206 yield* contextHandoffService.prepareProviderHandoff({
1207 threadId: projection.thread.id,
1208 targetRunId: run.id,
1209 transferId: null,
1210 fromProviderThreadIds: [providerThread.id],
1211 toProviderThreadId: providerThread.id,
1212 fromProviderInstanceId: run.providerInstanceId,
1213 toProviderInstanceId: run.providerInstanceId,
1214 coveredRunOrdinals: {
1215 from: missedRuns[0]!.ordinal,
1216 to: missedRuns.at(-1)!.ordinal,
1217 },
1218 strategy: "delta_since_target_last_seen",
1219 items: missedItems,
1220 runs: projection.runs,
1221 createdAt: yield* DateTime.now,
1222 }),
1223 ];
1224 // History delivery (inline or injected) is text only, so missed images ride on prompts
1225 // until a later run's is accepted. Compaction and /goal starts carry none. A missed run's
1226 // own accepted attempt predates its unsent steering input, so it does not count.
1227 const runsById = new Map(projection.runs.map((source) => [source.id, source]));
1228 const messagesById = new Map(projection.messages.map((message) => [message.id, message]));
1229 let lastPromptOrdinal = 0;
1230 for (const attempt of acceptedAttempts) {
1231 if (missedRunIds.has(attempt.runId)) continue;
1232 const source = runsById.get(attempt.runId);
1233 if (source === undefined) continue;
1234 const message = messagesById.get(source.userMessageId);
1235 if (
1236 message !== undefined &&
1237 (isCompactionCommandMessage(message) ||
1238 (goalDriver && parseGoalCommand(message) !== null))
1239 )
1240 continue;
1241 lastPromptOrdinal = Math.max(lastPromptOrdinal, source.ordinal);
1242 }
1243 const attachments = missedHistory.flatMap((item) =>
1244 item.type === "user_message" &&
1245 item.runId !== null &&
1246 (runsById.get(item.runId)?.ordinal ?? 0) > lastPromptOrdinal
1247 ? item.attachments
1248 : [],
1249 );
1250 return { handoffs, attachments };
1251 },
1252 );
1253 const prepareRecoveryHandoff = Effect.fn("ProviderTurnStartService.prepareRecoveryHandoff")(
1254 function* () {
1255 const transferId = yield* idAllocator.allocate.contextTransfer({
1256 sourceThreadId: projection.thread.id,
1257 targetThreadId: projection.thread.id,
1258 type: "provider_resume_fallback",
1259 });
1260 const createdAt = yield* DateTime.now;
1261 const history = yield* projectionStore.getTurnStartHistory(input.threadId);
1262 const boundary = contextBoundaryOrdinal({ runs: projection.runs, turnItems: history });
1263 const from = Math.max(1, boundary);
1264 const handoff = yield* contextHandoffService.prepareProviderHandoff({
1265 threadId: projection.thread.id,
1266 targetRunId: run.id,
1267 transferId,
1268 fromProviderThreadIds: [providerThread.id],
1269 toProviderThreadId: providerThread.id,
1270 fromProviderInstanceId: providerThread.providerInstanceId,
1271 toProviderInstanceId: run.providerInstanceId,
1272 coveredRunOrdinals: { from, to: Math.max(from, run.ordinal - 1) },
1273 strategy: "full_thread_summary",
1274 runs: projection.runs,
1275 items: [
1276 ...(boundary === 0
1277 ? yield* ContextHandoffService.readInheritedHandoffItems(
1278 projectionStore,
1279 projection.thread,
1280 )
1281 : []),
1282 ...history.filter((item) =>
1283 item.runId === null
1284 ? boundary === 0
1285 : projection.runs.some(
1286 (source) =>
1287 source.id === item.runId &&
1288 source.ordinal >= boundary &&
1289 source.ordinal < run.ordinal &&
1290 source.status !== "rolled_back",
1291 ),
1292 ),
1293 ],
1294 createdAt,
1295 });
1296 return { handoff, transferId, createdAt };
1297 },
1298 );
1299 const recoveryHandoff = yield* Effect.cached(prepareRecoveryHandoff());
1300 const withRecoveryHandoff = (handoff: OrchestrationV2ContextHandoff) => {
1301 // Delivery ranks later handoffs as newer history. Pending handoffs from
1302 // earlier runs predate this summary; handoffs for this run (provider-switch
1303 // delta, merge-back) are newer and must stay last.
1304 return [
1305 ...effectiveHandoffs.filter((candidate) => candidate.targetRunId !== run.id),
1306 handoff,
1307 ...effectiveHandoffs.filter((candidate) => candidate.targetRunId === run.id),
1308 ];
1309 };
1310 let resumedRetryHandoff: Effect.Success<ReturnType<typeof prepareRetryHandoff>> | undefined;
1311 let resumedHandoffContext: ReturnType<typeof handoffContextForThread> | undefined;
1312 let portableForkFallback: OrchestrationV2ContextHandoff | undefined;
1313 let recoveryTurnItem: OrchestrationV2TurnItem | undefined;
1314 const loadedProviderThread = yield* Effect.gen(function* () {
1315 if (nativeForkTransfer !== undefined) {
1316 let sourceProjection = yield* projectionStore.getThreadRecords(
1317 nativeForkTransfer.sourceThreadId,
1318 ["runs", "providerThreads", "attempts", "providerTurns"],
1319 );
1320 const sourceRun = sourceProjection.runs.find(
1321 (candidate) => candidate.id === nativeForkTransfer.sourcePoint.runId,
1322 );
1323 const sourceProviderThread = sourceProjection.providerThreads.find(
1324 (candidate) => candidate.id === sourceRun?.providerThreadId,
1325 );
1326 const sourceAttempt = sourceProjection.attempts.find(
1327 (candidate) => candidate.id === sourceRun?.activeAttemptId,
1328 );
1329 const sourceProviderTurn =
1330 latestProviderTurnForAttempt(sourceProjection.providerTurns, sourceAttempt?.id) ??
1331 sourceProjection.providerTurns.find(
1332 (candidate) => candidate.id === sourceAttempt?.providerTurnId,
1333 );
1334 if (sourceRun === undefined || sourceProviderThread === undefined) {
1335 return yield* new ProviderTurnStartError({
1336 runId,
1337 cause: `Native fork transfer ${nativeForkTransfer.id} has no source provider execution.`,
1338 });
1339 }
1340 // The source may have started a turn after dispatch planned this fork.
1341 const sourceBusy = sourceProjection.runs.some(
1342 (candidate) => candidate.ordinal > sourceRun.ordinal && isActiveRun(candidate),
1343 );
1344 let nativeForkFailure: string | undefined;
1345 if (
1346 (sourceRun.status === "completed" || sourceRun.status === "waiting") &&
1347 (!sourceBusy ||
1348 canForkBusySourceNatively(
1349 session.providerSession.capabilities,
1350 sourceProviderTurn?.nativeTurnRef != null,
1351 ))
1352 ) {
1353 // Rolled-back turns are no longer in the source conversation, so they cannot bound a fork.
1354 const rolledBackAttemptIds = new Set(
1355 sourceProjection.attempts
1356 .filter((attempt) =>
1357 sourceProjection.runs.some(
1358 (candidate) =>
1359 candidate.id === attempt.runId && candidate.status === "rolled_back",
1360 ),
1361 )
1362 .map((attempt) => attempt.id),
1363 );
1364 const forked = yield* Effect.result(
1365 session.forkThread({
1366 sourceProviderThread,
1367 sourceProviderTurns: sourceProjection.providerTurns.filter(
1368 (turn) =>
1369 turn.runAttemptId === null || !rolledBackAttemptIds.has(turn.runAttemptId),
1370 ),
1371 targetThreadId: projection.thread.id,
1372 modelSelection: run.modelSelection,
1373 runtimePolicy: resolvedRuntimePolicy,
1374 ...(sourceProviderTurn === undefined
1375 ? {}
1376 : { providerTurnId: sourceProviderTurn.id }),
1377 }),
1378 );
1379 if (forked._tag === "Success") return forked.success;
1380 if (input.willRetry === true) return yield* forked.failure;
1381 if (!(yield* isCurrentAttemptInStatus("starting"))) return undefined;
1382 // Retries are spent (e.g. the source's native session is gone): start fresh with portable history.
1383 yield* Effect.logWarning("Starting a native fork in a fresh native session", {
1384 driver: session.driver,
1385 providerThreadId: providerThread.id,
1386 sourceProviderThreadId: sourceProviderThread.id,
1387 runId,
1388 errorTag: forked.failure._tag,
1389 });
1390 nativeForkFailure = makeProviderFailure({
1391 cause: forked.failure,
1392 message: startFailureMessage(forked.failure),
1393 class: "provider_error",
1394 }).message;
1395 sourceProjection = {
1396 ...sourceProjection,
1397 ...(yield* projectionStore.getThreadRecords(nativeForkTransfer.sourceThreadId, [
1398 "runs",
1399 "attempts",
1400 ])),
1401 };
1402 }
1403 const nativeForkFailed = nativeForkFailure !== undefined;
1404 const sourceItems = yield* ContextHandoffService.readForkHistoryItems(
1405 projectionStore,
1406 sourceProjection,
1407 sourceRun,
1408 );
1409 const createdAt = yield* DateTime.now;
1410 const handoff = yield* contextHandoffService.prepareProviderHandoff({
1411 threadId: projection.thread.id,
1412 targetRunId: run.id,
1413 transferId: nativeForkTransfer.id,
1414 fromProviderThreadIds: [sourceProviderThread.id],
1415 toProviderThreadId: providerThread.id,
1416 fromProviderInstanceId: sourceRun.providerInstanceId,
1417 toProviderInstanceId: run.providerInstanceId,
1418 coveredRunOrdinals: ContextHandoffService.visibleDeltaRunOrdinals(
1419 sourceProjection,
1420 sourceItems,
1421 ),
1422 strategy: "full_thread_summary",
1423 items: sourceItems,
1424 runs: sourceProjection.runs,
1425 createdAt,
1426 });
1427 const loaded = yield* loadFromProvider(
1428 session.ensureThread({
1429 threadId: projection.thread.id,
1430 title: projection.thread.title,
1431 modelSelection: run.modelSelection,
1432 runtimePolicy: resolvedRuntimePolicy,
1433 providerSessionId,
1434 existingProviderThread: nativeForkFailed
1435 ? { ...providerThread, nativeThreadRef: null, forkedFrom: null }
1436 : { ...providerThread, forkedFrom: null },
1437 // The failed fork may have left the adapter's session half-switched.
1438 ...(nativeForkFailed ? { forceNewNativeThread: true } : {}),
1439 }),
1440 );
1441 if (loaded === undefined) return undefined;
1442 portableForkFallback = handoff;
1443 effectiveHandoffs = [handoff, ...effectiveHandoffs];
1444 yield* eventSink.write({
1445 events: [
1446 {
1447 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1448 type: "context-handoff.updated",
1449 threadId: projection.thread.id,
1450 runId: run.id,
1451 providerInstanceId: run.providerInstanceId,
1452 occurredAt: createdAt,
1453 payload: handoff,
1454 },
1455 {
1456 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1457 type: "context-transfer.updated",
1458 threadId: projection.thread.id,
1459 runId: run.id,
1460 providerInstanceId: run.providerInstanceId,
1461 occurredAt: createdAt,
1462 payload: {
1463 ...nativeForkTransfer,
1464 targetProviderInstanceId: run.providerInstanceId,
1465 status: "resolved_portable",
1466 resolution: { strategy: "portable_context", contextHandoffId: handoff.id },
1467 error: null,
1468 updatedAt: createdAt,
1469 },
1470 },
1471 ...(nativeForkFailure === undefined
1472 ? []
1473 : [
1474 {
1475 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1476 type: "turn-item.updated" as const,
1477 threadId: projection.thread.id,
1478 runId: run.id,
1479 providerInstanceId: run.providerInstanceId,
1480 occurredAt: createdAt,
1481 payload: {
1482 id: idAllocator.derive.runSignalTurnItem({
1483 runId,
1484 signal: "native-fork-fallback",
1485 }),
1486 threadId: projection.thread.id,
1487 runId,
1488 nodeId: rootNode.id,
1489 providerThreadId: providerThread.id,
1490 providerTurnId: null,
1491 nativeItemRef: null,
1492 parentItemId: null,
1493 ordinal:
1494 Math.max(
1495 0,
1496 ...projection.turnItems
1497 .filter((item) => item.runId === runId)
1498 .map((item) => item.ordinal),
1499 ) + 1,
1500 status: "completed" as const,
1501 title: "Native fork failed",
1502 startedAt: createdAt,
1503 completedAt: createdAt,
1504 updatedAt: createdAt,
1505 type: "system_notice" as const,
1506 message: `Could not fork the source conversation natively (${nativeForkFailure}). Started a fresh session with its history.`,
1507 },
1508 },
1509 ]),
1510 ],
1511 });
1512 return loaded;
1513 }
1514 if (providerThread.nativeThreadRef === null) {
1515 // Pass the stored provider row for adoption; adapter-minted duplicates make activeProviderThreadId flap.
1516 return yield* loadFromProvider(
1517 session.ensureThread({
1518 threadId: projection.thread.id,
1519 title: projection.thread.title,
1520 modelSelection: run.modelSelection,
1521 runtimePolicy: resolvedRuntimePolicy,
1522 providerSessionId,
1523 existingProviderThread: providerThread,
1524 }),
1525 );
1526 }
1527 const uncertainDelivery = projection.contextHandoffs.some(
1528 (handoff) =>
1529 handoff.toProviderThreadId === providerThread.id &&
1530 handoff.delivery?.nativeThreadId === providerThread.nativeThreadRef?.nativeId &&
1531 handoff.delivery?.status === "pending",
1532 );
1533 // A provider that cannot truncate rolls back into a fresh native session holding none of the kept turns.
1534 const nativeSessionLacksKeptTurns =
1535 !session.providerSession.capabilities.checkpointing.providerCanRollbackConversation &&
1536 nativeSessionMissesKeptTurns(projection, providerThread, run);
1537 // Dispatch prepares no import handoff for a session import: its history is in the native session.
1538 const importedNativeSession =
1539 projection.thread.historyOrigin === "v1_import" &&
1540 !projection.providerTurns.some((turn) => turn.providerThreadId === providerThread.id) &&
1541 !projection.contextHandoffs.some(
1542 (handoff) =>
1543 handoff.toProviderThreadId === providerThread.id &&
1544 handoff.strategy === "manual_context",
1545 );
1546 const resumed = yield* Effect.result(
1547 uncertainDelivery || nativeSessionLacksKeptTurns
1548 ? Effect.fail(
1549 new ProviderAdapter.ProviderAdapterTurnStartError({
1550 driver: session.driver,
1551 threadId: projection.thread.id,
1552 providerThreadId: providerThread.id,
1553 runId,
1554 cause: uncertainDelivery
1555 ? "Uncertain native history injection"
1556 : "Native session holds none of the kept conversation",
1557 }),
1558 )
1559 : session.resumeThread({
1560 providerThread,
1561 threadId: projection.thread.id,
1562 modelSelection: run.modelSelection,
1563 runtimePolicy: resolvedRuntimePolicy,
1564 importedNativeSession,
1565 }),
1566 );
1567 if (resumed._tag === "Success") {
1568 const context = handoffContextForThread(resumed.success);
1569 context.budget = yield* Effect.cached(context.budget);
1570 resumedHandoffContext = context;
1571 resumedRetryHandoff = yield* prepareRetryHandoff(context);
1572 const fits = yield* deliverContextHandoffs({
1573 handoffs: [...handoffs, ...resumedRetryHandoff.handoffs],
1574 providerThread: { ...resumed.success, id: providerThread.id },
1575 budget: context.budget,
1576 deferInline: isCompactionCommandMessage(providerMessage) || goalCommand,
1577 alreadyDeliveredItemIds: context.deliveredItemIds,
1578 persist: () => Effect.void,
1579 }).pipe(
1580 Effect.as(true),
1581 Effect.catchTags({ ContextHandoffBudgetError: () => Effect.succeed(false) }),
1582 );
1583 if (fits) return resumed.success;
1584 const freshThread = { ...resumed.success, nativeThreadRef: null };
1585 const freshContext = handoffContextForThread(freshThread);
1586 const { handoff } = yield* recoveryHandoff;
1587 const fitsFresh = yield* deliverContextHandoffs({
1588 handoffs: withRecoveryHandoff(handoff),
1589 providerThread: freshThread,
1590 budget: freshContext.budget,
1591 alreadyDeliveredItemIds: freshContext.deliveredItemIds,
1592 persist: () => Effect.void,
1593 }).pipe(
1594 Effect.as(true),
1595 Effect.catchTags({ ContextHandoffBudgetError: () => Effect.succeed(false) }),
1596 );
1597 if (!fitsFresh) return resumed.success;
1598 const hasPendingWork = yield* (
1599 session.hasPendingBackgroundWorkForThread?.(resumed.success, {
1600 includeSubagents: true,
1601 }) ??
1602 session.hasPendingBackgroundWork ??
1603 Effect.succeed(false)
1604 );
1605 if (hasPendingWork) {
1606 return yield* loadFromProvider(
1607 Effect.fail(
1608 new ProviderAdapter.ProviderAdapterTurnStartError({
1609 driver: session.driver,
1610 threadId: projection.thread.id,
1611 providerThreadId: providerThread.id,
1612 runId,
1613 cause: new ContextHandoffBackgroundWorkError(),
1614 }),
1615 ),
1616 );
1617 }
1618 }
1619 resumedHandoffContext = undefined;
1620 resumedRetryHandoff = undefined;
1621 if (!(yield* isCurrentAttemptInStatus("starting"))) return undefined;
1622 // Another client is still writing to the native thread. A fresh
1623 // session here would silently split the conversation from it.
1624 if (
1625 resumed._tag === "Failure" &&
1626 resumed.failure._tag === "ProviderAdapterThreadInUseError"
1627 ) {
1628 return yield* loadFromProvider(Effect.fail(resumed.failure));
1629 }
1630
1631 yield* Effect.logWarning("Recovering provider context in a fresh native session", {
1632 driver: session.driver,
1633 providerThreadId: providerThread.id,
1634 runId,
1635 reason: uncertainDelivery
1636 ? "uncertain_history_delivery"
1637 : nativeSessionLacksKeptTurns
1638 ? "native_session_lacks_kept_turns"
1639 : resumed._tag === "Success"
1640 ? "handoff_budget_exhausted"
1641 : "resume_failed",
1642 errorTag: resumed._tag === "Failure" ? resumed.failure._tag : "ContextHandoffBudgetError",
1643 });
1644 const replacement = yield* loadFromProvider(
1645 session.ensureThread({
1646 threadId: projection.thread.id,
1647 title: projection.thread.title,
1648 modelSelection: run.modelSelection,
1649 runtimePolicy: resolvedRuntimePolicy,
1650 providerSessionId,
1651 // Clear the native ref to force a fresh session while preserving row identity.
1652 existingProviderThread: { ...providerThread, nativeThreadRef: null },
1653 // A fresh session that never loaded the broken history needs no replacement.
1654 ...(opensFreshSession && resumed._tag === "Failure"
1655 ? {}
1656 : { forceNewNativeThread: true }),
1657 }),
1658 );
1659 if (replacement === undefined) return undefined;
1660 if (
1661 replacement.nativeThreadRef?.nativeId != null &&
1662 replacement.nativeThreadRef.driver === providerThread.nativeThreadRef?.driver &&
1663 replacement.nativeThreadRef.nativeId === providerThread.nativeThreadRef.nativeId
1664 ) {
1665 // Never retried. Forget the load first, or the next turn would skip resume and start on
1666 // the reused session without this error or the recovery handoff.
1667 yield* providerSessions.forgetLoadedProviderThread({
1668 providerSessionId: session.providerSessionId,
1669 threadId: projection.thread.id,
1670 providerThread: replacement,
1671 modelSelection: run.modelSelection,
1672 runtimePolicy: resolvedRuntimePolicy,
1673 });
1674 yield* settleStartFailure({
1675 signal: "provider-thread-load-failure",
1676 title: "Provider turn failed to start",
1677 error: new ProviderAdapter.ProviderAdapterProtocolError({
1678 driver: session.driver,
1679 detail:
1680 "the provider returned its existing session when asked for a fresh one, so the conversation context could not be moved to a new session",
1681 }),
1682 });
1683 return undefined;
1684 }
1685 const { handoff, transferId, createdAt } = yield* recoveryHandoff;
1686 const previousRun = projection.runs.findLast(
1687 (candidate) =>
1688 candidate.providerThreadId === providerThread.id &&
1689 candidate.ordinal < run.ordinal &&
1690 candidate.startedAt !== null,
1691 );
1692 // Stable per run so a retried start reuses the reserved run-start position.
1693 const handoffTurnItemId = idAllocator.derive.runSignalTurnItem({
1694 runId,
1695 signal: "resume-fallback-handoff",
1696 });
1697 const handoffTurnItem: OrchestrationV2TurnItem = {
1698 id: handoffTurnItemId,
1699 threadId: projection.thread.id,
1700 runId,
1701 nodeId: rootNode.id,
1702 providerThreadId: providerThread.id,
1703 providerTurnId: null,
1704 nativeItemRef: null,
1705 parentItemId: null,
1706 // The summary is delivered ahead of this run's own handoffs and message.
1707 ordinal: yield* turnItemPositions.allocate({
1708 threadId: projection.thread.id,
1709 turnItemId: handoffTurnItemId,
1710 runId,
1711 runOrdinal: run.ordinal,
1712 placement: "run_start",
1713 }),
1714 status: "completed",
1715 title: "Recovered context",
1716 startedAt: createdAt,
1717 completedAt: createdAt,
1718 updatedAt: createdAt,
1719 type: "handoff",
1720 contextHandoffId: handoff.id,
1721 fromProviderThreadIds: handoff.fromProviderThreadIds,
1722 toProviderThreadId: handoff.toProviderThreadId,
1723 fromProviderInstanceIds: [providerThread.providerInstanceId],
1724 toProviderInstanceId: run.providerInstanceId,
1725 fromModelSelections: previousRun === undefined ? [] : [previousRun.modelSelection],
1726 toModel: run.modelSelection.model,
1727 strategy: handoff.strategy,
1728 summary: handoff.summaryText,
1729 };
1730 const replacementWrite = yield* eventSink.writeIfRunCurrent({
1731 threadId: projection.thread.id,
1732 runId: run.id,
1733 activeAttemptId: attempt.id,
1734 expectedStatus: "starting",
1735 events: [
1736 {
1737 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1738 type: "context-handoff.updated",
1739 threadId: projection.thread.id,
1740 runId: run.id,
1741 providerInstanceId: run.providerInstanceId,
1742 occurredAt: createdAt,
1743 payload: handoff,
1744 },
1745 {
1746 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1747 type: "context-transfer.updated",
1748 threadId: projection.thread.id,
1749 runId: run.id,
1750 providerInstanceId: run.providerInstanceId,
1751 occurredAt: createdAt,
1752 payload: {
1753 id: transferId,
1754 type: "provider_handoff",
1755 sourceThreadId: projection.thread.id,
1756 targetThreadId: projection.thread.id,
1757 sourcePoint: { threadId: projection.thread.id },
1758 basePoint: null,
1759 sourceProviderInstanceId: providerThread.providerInstanceId,
1760 targetProviderInstanceId: run.providerInstanceId,
1761 targetRunId: run.id,
1762 status: "resolved_portable",
1763 resolution: { strategy: "portable_context", contextHandoffId: handoff.id },
1764 createdBy: "system",
1765 error: null,
1766 createdAt,
1767 updatedAt: createdAt,
1768 consumedAt: null,
1769 },
1770 },
1771 ],
1772 });
1773 if (!replacementWrite.committed) return undefined;
1774 effectiveHandoffs = withRecoveryHandoff(handoff);
1775 resumeFellBack = true;
1776 recoveryTurnItem = handoffTurnItem;
1777 return replacement;
1778 });
1779 if (loadedProviderThread === undefined) return;
1780 if (!(yield* isCurrentAttemptInStatus("starting"))) {
1781 return;
1782 }
1783 const now = yield* DateTime.now;
1784 const handoffContext = resumedHandoffContext ?? handoffContextForThread(loadedProviderThread);
1785 const {
1786 sameNativeThread,
1787 handoffUsage,
1788 deliveredItemIds,
1789 acceptedAttempts,
1790 nativeInputRunIds,
1791 legacyInputRunIds,
1792 budget,
1793 } = handoffContext;
1794 if (manualResume && unsentResumeMessage === undefined && session.resumeTurn === undefined) {
1795 yield* settleStartFailure({
1796 signal: "resume-unsupported",
1797 title: "Native resume is unavailable",
1798 error: new ProviderAdapter.ProviderResumeUnsupportedError({
1799 driver: session.driver,
1800 providerThreadId: providerThread.id,
1801 }),
1802 });
1803 return;
1804 }
1805 const retryHandoff = resumedRetryHandoff ?? (yield* prepareRetryHandoff(handoffContext));
1806 const runningProviderThread: OrchestrationV2ProviderThread = {
1807 ...loadedProviderThread,
1808 contextUsage: handoffUsage,
1809 id: providerThread.id,
1810 driver: session.driver,
1811 providerInstanceId: run.providerInstanceId,
1812 providerSessionId,
1813 appThreadId: projection.thread.id,
1814 ownerNodeId: providerThread.ownerNodeId,
1815 firstRunOrdinal: providerThread.firstRunOrdinal ?? run.ordinal,
1816 lastRunOrdinal: run.ordinal,
1817 handoffIds:
1818 portableForkFallback === undefined
1819 ? providerThread.handoffIds
1820 : [...providerThread.handoffIds, portableForkFallback.id],
1821 forkedFrom: portableForkFallback === undefined ? providerThread.forkedFrom : null,
1822 status: "active",
1823 createdAt: providerThread.createdAt,
1824 updatedAt: now,
1825 };
1826 const runningRun: OrchestrationV2Run = {
1827 ...run,
1828 status: "running",
1829 startedAt: run.startedAt ?? now,
1830 };
1831 const runningAttempt: OrchestrationV2RunAttempt = {
1832 ...attempt,
1833 ...(runningProviderThread.nativeThreadRef?.nativeId == null
1834 ? {}
1835 : { nativeThreadId: runningProviderThread.nativeThreadRef.nativeId }),
1836 status: "running",
1837 startedAt: now,
1838 };
1839 const runningRootNode: OrchestrationV2ExecutionNode = {
1840 ...rootNode,
1841 status: "running",
1842 startedAt: now,
1843 };
1844 const events: Array<OrchestrationV2DomainEvent> = [
1845 {
1846 id: yield* idAllocator.allocate.event({
1847 threadId: projection.thread.id,
1848 providerSessionId,
1849 }),
1850 type: "provider-session.updated",
1851 threadId: projection.thread.id,
1852 driver: session.driver,
1853 providerInstanceId: run.providerInstanceId,
1854 occurredAt: now,
1855 payload: session.providerSession,
1856 },
1857 {
1858 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1859 type: "provider-thread.updated",
1860 threadId: projection.thread.id,
1861 driver: session.driver,
1862 providerInstanceId: run.providerInstanceId,
1863 occurredAt: now,
1864 payload: runningProviderThread,
1865 },
1866 ...(nativeForkTransfer === undefined ||
1867 portableForkFallback !== undefined ||
1868 runningProviderThread.nativeThreadRef === null
1869 ? []
1870 : [
1871 {
1872 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1873 type: "context-transfer.updated" as const,
1874 threadId: projection.thread.id,
1875 runId: run.id,
1876 driver: session.driver,
1877 providerInstanceId: run.providerInstanceId,
1878 occurredAt: now,
1879 payload: {
1880 ...nativeForkTransfer,
1881 targetProviderInstanceId: run.providerInstanceId,
1882 targetRunId: run.id,
1883 status: "consumed" as const,
1884 resolution: {
1885 strategy: "native_fork" as const,
1886 providerThreadRef: runningProviderThread.nativeThreadRef,
1887 },
1888 error: null,
1889 updatedAt: now,
1890 consumedAt: now,
1891 },
1892 },
1893 ]),
1894 // Shown only once the replacement session commits with the running transition.
1895 ...(recoveryTurnItem === undefined
1896 ? []
1897 : [
1898 {
1899 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1900 type: "turn-item.updated" as const,
1901 threadId: projection.thread.id,
1902 runId: run.id,
1903 providerInstanceId: run.providerInstanceId,
1904 occurredAt: now,
1905 payload: recoveryTurnItem,
1906 },
1907 ]),
1908 {
1909 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1910 type: "run.updated",
1911 threadId: projection.thread.id,
1912 runId: run.id,
1913 nodeId: rootNode.id,
1914 providerInstanceId: run.providerInstanceId,
1915 occurredAt: now,
1916 payload: runningRun,
1917 },
1918 {
1919 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1920 type: "run-attempt.updated",
1921 threadId: projection.thread.id,
1922 runId: run.id,
1923 nodeId: rootNode.id,
1924 providerInstanceId: run.providerInstanceId,
1925 occurredAt: now,
1926 payload: runningAttempt,
1927 },
1928 {
1929 id: yield* idAllocator.allocate.event({ threadId: projection.thread.id }),
1930 type: "node.updated",
1931 threadId: projection.thread.id,
1932 runId: run.id,
1933 nodeId: rootNode.id,
1934 providerInstanceId: run.providerInstanceId,
1935 occurredAt: now,
1936 payload: runningRootNode,
1937 },
1938 ];
1939 const runningWrite = yield* eventSink.writeIfRunCurrent({
1940 threadId: projection.thread.id,
1941 runId: run.id,
1942 activeAttemptId: attempt.id,
1943 expectedStatus: "starting",
1944 events,
1945 });
1946 if (!runningWrite.committed) {
1947 return;
1948 }
1949 // Delegated (app_owned) children run their own runs; routing them here ingests their items twice.
1950 const routableSubagents = projection.subagents.filter(
1951 (subagent) =>
1952 subagent.origin === "provider_native" &&
1953 RunExecutionService.canRouteRelatedSubagent(subagent.status),
1954 );
1955 const persistHandoff = Effect.fn("ProviderTurnStartService.persist")(function* (
1956 handoff: OrchestrationV2ContextHandoff,
1957 ) {
1958 const updatedAt = yield* DateTime.now;
1959 yield* eventSink.write({
1960 events: [
1961 {
1962 id: yield* idAllocator.allocate.event({
1963 threadId: projection.thread.id,
1964 }),
1965 type: "context-handoff.updated",
1966 threadId: projection.thread.id,
1967 runId: run.id,
1968 providerInstanceId: run.providerInstanceId,
1969 occurredAt: updatedAt,
1970 payload: { ...handoff, updatedAt },
1971 },
1972 ],
1973 });
1974 });
1975 const startWithHandoffs = Effect.fn("ProviderTurnStartService.startWithHandoffs")(
1976 function* (turnInput: Parameters<typeof session.startTurn>[0], compact = false) {
1977 const delivery = yield* deliverContextHandoffs({
1978 handoffs: [...effectiveHandoffs, ...retryHandoff.handoffs],
1979 deferInline: compact || goalCommand,
1980 providerThread: runningProviderThread,
1981 budget,
1982 alreadyDeliveredItemIds: deliveredItemIds,
1983 ...(session.injectHistory === undefined
1984 ? {}
1985 : {
1986 inject: (history: ProviderAdapter.ProviderAdapterV2HistoricalContext) =>
1987 session.injectHistory!({
1988 providerThread: runningProviderThread,
1989 ...history,
1990 }),
1991 }),
1992 persist: persistHandoff,
1993 });
1994 if (!(yield* isCurrentAttemptInStatus("running"))) return;
1995 const start = compact ? session.compactThread! : session.startTurn;
1996 // Like history, the side chat context waits for a turn that sends a prompt.
1997 const sideChatContext =
1998 sideChatHandoff === undefined || compact || goalCommand
1999 ? ""
2000 : sideChatHandoff.summaryText;
2001 const context = [delivery.context, sideChatContext, restartNote]
2002 .filter((part) => part !== "")
2003 .join("\n\n");
2004 const { restartContinuationOfRunId: _resumedRunId, ...promptedInput } = turnInput;
2005 const startInput = noteContinuation ? promptedInput : turnInput;
2006 const { resume: _resume, ...contextInput } = startInput;
2007 const { message: resumeMessage, resume: _resumeIntent, ...resumeInput } = startInput;
2008 const missedAttachments =
2009 compact || goalCommand
2010 ? []
2011 : retryHandoff.attachments.filter(
2012 (missed) =>
2013 !turnInput.message.attachments.some((current) => current.id === missed.id),
2014 );
2015 // Like pending history, pending images need a prompt; native resume carries none.
2016 const prompted = context !== "" || missedAttachments.length > 0;
2017 // A resume that must be prompted still needs a request, or the agent has nothing to do.
2018 const requestText =
2019 turnInput.resume && prompted && userText === "" ? RESUME_PROMPT : userText;
2020 const text = goalCommand ? userText : withInlineContext(context, requestText);
2021 const operation =
2022 turnInput.resume && !prompted && session.resumeTurn !== undefined
2023 ? session.resumeTurn({ ...resumeInput, messageId: resumeMessage.messageId })
2024 : start({
2025 ...(prompted ? contextInput : startInput),
2026 message: {
2027 ...turnInput.message,
2028 text,
2029 ...(missedAttachments.length === 0
2030 ? {}
2031 : { attachments: [...missedAttachments, ...turnInput.message.attachments] }),
2032 },
2033 ...(text === userText
2034 ? {}
2035 : { inlineContextLength: text.length - userText.length }),
2036 });
2037 yield* operation.pipe(
2038 // Clear pending handoff markers for refused prompts so the next turn retains the native session.
2039 Effect.tapError((error) =>
2040 refusedBeforePrompt(error)
2041 ? delivery.unsent.pipe(
2042 Effect.catchCause(() =>
2043 Effect.logWarning("Failed to restore unsent context handoffs", {
2044 runId: run.id,
2045 }),
2046 ),
2047 )
2048 : Effect.void,
2049 ),
2050 );
2051 // After provider acceptance, failed delivery bookkeeping must not stop live ingestion.
2052 const nativeThreadId = runningProviderThread.nativeThreadRef?.nativeId;
2053 yield* Effect.forEach(
2054 [
2055 delivery.delivered,
2056 ...(sideChatContext === "" || sideChatHandoff === undefined || nativeThreadId == null
2057 ? []
2058 : [
2059 persistHandoff({
2060 ...sideChatHandoff,
2061 toProviderThreadId: runningProviderThread.id,
2062 delivery: { nativeThreadId, status: "inline" as const, itemIds: [] },
2063 }),
2064 ]),
2065 ],
2066 (record) =>
2067 record.pipe(
2068 Effect.catchCause(() =>
2069 Effect.logWarning("Failed to record accepted context handoff delivery", {
2070 runId: run.id,
2071 deliveryStatus: "pending",
2072 }),
2073 ),
2074 ),
2075 { discard: true },
2076 );
2077 },
2078 Effect.mapError((cause) =>
2079 cause._tag === "ProviderAdapterTurnStartError"
2080 ? cause
2081 : new ProviderAdapter.ProviderAdapterTurnStartError({
2082 driver: session.driver,
2083 threadId: projection.thread.id,
2084 providerThreadId: providerThread.id,
2085 runId: run.id,
2086 cause,
2087 }),
2088 ),
2089 );
2090 const deliverySession =
2091 effectiveHandoffs.length === 0 &&
2092 retryHandoff.handoffs.length === 0 &&
2093 retryHandoff.attachments.length === 0 &&
2094 sideChatHandoff === undefined &&
2095 restartNote === "" &&
2096 !noteContinuation
2097 ? session
2098 : makeDeliverySession(session, startWithHandoffs);
2099 return runExecution.startRootRun({
2100 commandId: CommandId.make(`command:effect:provider-turn.start:${run.id}`),
2101 appThread: projection.thread,
2102 providerSessionId,
2103 session: deliverySession,
2104 run: runningRun,
2105 rootNode: runningRootNode,
2106 checkpointScope,
2107 providerThread: runningProviderThread,
2108 attempt: runningAttempt,
2109 attemptId: attempt.id,
2110 baseline,
2111 loadInheritedBackgroundTurnItems: runControls.loadInheritedBackgroundTurnItems,
2112 relatedThreadIds: routableSubagents.flatMap((subagent) =>
2113 subagent.childThreadId === null ? [] : [subagent.childThreadId],
2114 ),
2115 relatedProviderThreadIds: routableSubagents.flatMap((subagent) =>
2116 subagent.providerThreadId === null ? [] : [subagent.providerThreadId],
2117 ),
2118 providerTurnOrdinal:
2119 Math.max(
2120 0,
2121 ...projection.providerTurns
2122 .filter((turn) => turn.providerThreadId === providerThread.id)
2123 .map((turn) => turn.ordinal),
2124 ) + 1,
2125 resume: manualResume && unsentResumeMessage === undefined,
2126 nativeThreadHasTurns:
2127 nativeInputRunIds.size > 0 ||
2128 (legacyInputRunIds.size > 0 &&
2129 sameNativeThread &&
2130 !acceptedAttempts.some((source) => source.nativeThreadId !== undefined)),
2131 shouldStartProviderTurn: runControls.shouldStartProviderTurn,
2132 shouldFinalizeRun: runControls.shouldFinalizeRun,
2133 hasUnpairedRunInterruptRequest: runControls.hasUnpairedRunInterruptRequest,
2134 loadRunInterruptReason: runControls.loadRunInterruptReason,
2135 hasWorkspaceMoved: runControls.hasWorkspaceMoved,
2136 loadUnsettledWork: runControls.loadUnsettledWork,
2137 message: {
2138 messageId: message.id,
2139 text: userText,
2140 attachments: providerMessage.attachments,
2141 createdBy: message.createdBy,
2142 creationSource: message.creationSource,
2143 ...(message.scheduledTaskId === undefined
2144 ? {}
2145 : { scheduledTaskId: message.scheduledTaskId }),
2146 ...(message.senderThreadId === undefined
2147 ? {}
2148 : { senderThreadId: message.senderThreadId }),
2149 },
2150 modelSelection: run.modelSelection,
2151 runtimePolicy: resolvedRuntimePolicy,
2152 });
2153 });
2154
2155 return ProviderTurnStartServiceV2.of({
2156 start: Effect.fn("ProviderTurnStartService.start")(
2157 function* (input) {
2158 let startingRun: OrchestrationV2Run | undefined;
2159 const captureStartingRun = (run: OrchestrationV2Run) => {
2160 startingRun = run;
2161 };
2162 return yield* Effect.gen(function* () {
2163 // Storage cleanup removes worktrees under the same lease. Only startup
2164 // holds it; the provider turn runs after it is released.
2165 const { thread } = yield* projectionStore.getThreadRecords(input.threadId, []);
2166 const cwd =
2167 thread.worktreePath ??
2168 (yield* projects
2169 .getById(thread.projectId, { includeDeleted: true })
2170 .pipe(Effect.map((project) => Option.getOrUndefined(project)?.workspaceRoot)));
2171 const providerTurn = yield* cwd === undefined
2172 ? start(input, captureStartingRun)
2173 : withTurnStartReservation(
2174 fileSystem,
2175 path,
2176 path.resolve(cwd),
2177 thread.worktreePath === null
2178 ? start(input, captureStartingRun)
2179 : withWorkspaceLease(
2180 path.resolve(thread.worktreePath),
2181 start(input, captureStartingRun),
2182 ),
2183 );
2184 if (providerTurn !== undefined) {
2185 // Run execution owns finalization after the running write. A later
2186 // failure must not settle a replacement attempt committed by steering.
2187 yield* providerTurn.pipe(
2188 Effect.catchCauseIf(
2189 (cause) => !Cause.hasInterruptsOnly(cause),
2190 (cause) =>
2191 Effect.logWarning(
2192 "Run execution failed after starting",
2193 { runId: input.runId },
2194 cause,
2195 ),
2196 ),
2197 );
2198 }
2199 }).pipe(
2200 Effect.catchCauseIf(
2201 (cause) => !Cause.hasInterruptsOnly(cause),
2202 (cause) =>
2203 Effect.fail(
2204 new ProviderTurnStartError({
2205 runId: input.runId,
2206 cause: Cause.squash(cause),
2207 ...(startingRun?.activeAttemptId == null || startingRun.rootNodeId == null
2208 ? {}
2209 : {
2210 attemptId: startingRun.activeAttemptId,
2211 rootNodeId: startingRun.rootNodeId,
2212 }),
2213 }),
2214 ),
2215 ),
2216 );
2217 },
2218 (effect, input) =>
2219 effect.pipe(
2220 Effect.mapError((cause) =>
2221 isProviderTurnStartError(cause)
2222 ? cause
2223 : new ProviderTurnStartError({ runId: input.runId, cause }),
2224 ),
2225 ),
2226 ),
2227 failStartingRun: Effect.fn("ProviderTurnStartService.failStartingRun")(
2228 function* ({ threadId, runId, attemptId, rootNodeId }) {
2229 const projection = yield* projectionStore.getTurnStartContext(threadId, runId);
2230 const run = projection.runs.find((candidate) => candidate.id === runId);
2231 if (
2232 run === undefined ||
2233 run.status !== "starting" ||
2234 run.activeAttemptId !== attemptId ||
2235 run.rootNodeId !== rootNodeId
2236 )
2237 return;
2238 const rootNode = projection.nodes.find((candidate) => candidate.id === run.rootNodeId);
2239 const attempt = projection.attempts.find(
2240 (candidate) => candidate.id === run.activeAttemptId,
2241 );
2242 if (rootNode === undefined || attempt === undefined) {
2243 return yield* new ProviderTurnStartRunStateMissingError({ runId });
2244 }
2245 yield* settleRunBeforeStart({
2246 run,
2247 rootNode,
2248 attempt,
2249 turnItems: projection.turnItems,
2250 signal: "provider-turn-start-failure",
2251 status: "failed",
2252 now: yield* DateTime.now,
2253 providerInstanceId: run.providerInstanceId,
2254 itemProviderThreadId: run.providerThreadId,
2255 item: {
2256 type: "error",
2257 title: "Turn failed to start",
2258 failure: makeProviderFailure({ message: START_GAVE_UP_MESSAGE }),
2259 },
2260 });
2261 },
2262 (effect, { runId }) =>
2263 effect.pipe(
2264 Effect.mapError((cause) =>
2265 isProviderTurnStartRunStateMissingError(cause)
2266 ? cause
2267 : new ProviderTurnStartError({ runId, cause }),
2268 ),
2269 ),
2270 ),
2271 });
2272 }),
2273 );