@devries-cameron20 / t3code-1 / commits / 04ab2fca4b
Fork 0

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

fix(acp): explain rejected model selections (#19699)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Julius Marminge <julius0216@outlook.com>

Wout Stiens committed Oct 20, 2026 at 08:18 UTC 04ab2fca4bcb07b1af609686ad697a22e5687d8a
4 files changed +276 -23
apps/server/src/orchestration-v2/ProviderTurnStartService.ts
+7 -3
@@ -47,7 +47,10 @@ import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter"
47 import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
48 import * as ProjectionStore from "./ProjectionStore.ts";
49 import * as ProviderSessionManager from "./ProviderSessionManager.ts";
50 -import { makeProviderFailure } from "@t3tools/provider-core/server/failure";
50 +import {
51 + knownProviderFailureMessage,
52 + makeProviderFailure,
53 +} from "@t3tools/provider-core/server/failure";
54 import * as RunExecutionService from "./RunExecutionService.ts";
55 import * as RuntimePolicy from "./RuntimePolicy.ts";
56 import {
@@ -569,11 +572,12 @@ export const layer: Layer.Layer<
572 failure: makeProviderFailure({
573 cause: failed.error,
574 message:
572 - nestedCause instanceof Error
575 + knownProviderFailureMessage(failed.error) ??
576 + (nestedCause instanceof Error
577 ? nestedCause.message
578 : typeof nestedCause === "string"
579 ? nestedCause
576 - : failed.error.message,
580 + : failed.error.message),
581 class: "provider_error",
582 }),
583 },
apps/server/src/orchestration-v2/testkit/OrchestratorReplayFixtures.integration.test.ts
+195 -4
@@ -1,13 +1,23 @@
1 import * as NodeServices from "@effect/platform-node/NodeServices";
2 import { assert, describe, it } from "@effect/vitest";
3 -import type {
4 - OrchestrationV2DomainEvent,
5 - ProviderReplayEntry,
6 - ProviderReplayTranscript,
3 +import {
4 + ProviderDriverKind,
5 + ProviderInstanceId,
6 + type OrchestrationV2DomainEvent,
7 + type ProviderReplayEntry,
8 + type ProviderReplayTranscript,
9 } from "@t3tools/contracts";
10 +import * as DateTime from "effect/DateTime";
11 import * as Effect from "effect/Effect";
12 import * as FileSystem from "effect/FileSystem";
13 +import * as Layer from "effect/Layer";
14 +import * as Option from "effect/Option";
15 import * as Path from "effect/Path";
16 +import * as Stream from "effect/Stream";
17 +import { TestClock } from "effect/testing";
18 +
19 +import * as EffectWorker from "../EffectWorker.ts";
20 +import * as Orchestrator from "../Orchestrator.ts";
21
22 import { ClaudeOrchestratorReplayHarness } from "../Adapters/ClaudeAdapterV2.testkit.ts";
23 import { CodexOrchestratorReplayHarness } from "../Adapters/CodexAdapterV2.testkit.ts";
@@ -31,12 +41,14 @@ import { messageRestartInput } from "./fixtures/message_steering/input.ts";
41 import {
42 assertProviderNativeSubagentRootTurns,
43 materializeFixtureInput,
44 + SIMPLE_PROMPT,
45 projectionFor,
46 type OrchestratorFixtureInput,
47 type ProviderOrchestratorReplayVariant,
48 } from "./fixtures/shared.ts";
49 import {
50 runOrchestratorV2ProviderReplayScenario,
51 + layerProviderReplay,
52 type OrchestratorV2ProviderReplayHarness,
53 } from "./ProviderReplayHarness.ts";
54 import { checkpointWorkspace } from "@t3tools/provider-testing/replayWorkspace";
@@ -232,6 +244,185 @@ function runFixtureProviderWithRegisteredHarness(input: {
244 }
245
246 describe("orchestrator replay fixtures", () => {
247 + it.effect.each([
248 + { name: "open", firstTurn: false, code: -32602 },
249 + { name: "switch", firstTurn: true, code: -32602 },
250 + { name: "authentication", firstTurn: false, code: -32000 },
251 + ])("preserves the ACP model-write $name failure through orchestration", (testCase) =>
252 + Effect.gen(function* () {
253 + const name = `acp_model_write_${testCase.name}`;
254 + const sessionId = "grok-replay-session-1";
255 + const rejectedModel = "replay-model-b";
256 + const modelSelection = {
257 + instanceId: ProviderInstanceId.make("acpRegistry"),
258 + model: rejectedModel,
259 + };
260 + const recorded = yield* readTranscript(
261 + new URL("./fixtures/simple/registry_transcript.ndjson", import.meta.url),
262 + );
263 + const sessionIndex = recorded.entries.findIndex(
264 + (entry) => "label" in entry && entry.label === "session.created",
265 + );
266 + assert.isAtLeast(sessionIndex, 0);
267 + const transcript = {
268 + ...recorded,
269 + scenario: name,
270 + entries: [
271 + ...recorded.entries.slice(0, sessionIndex),
272 + {
273 + type: "emit_inbound",
274 + label: "session.created",
275 + frame: {
276 + kind: "response",
277 + method: "session/new",
278 + result: {
279 + sessionId,
280 + configOptions: [
281 + {
282 + id: "model",
283 + name: "Model",
284 + category: "model",
285 + type: "select",
286 + currentValue: "replay-model-a",
287 + options: [
288 + { value: "replay-model-a", name: "Model A" },
289 + { value: rejectedModel, name: "Model B" },
290 + ],
291 + },
292 + ],
293 + },
294 + },
295 + },
296 + ...(testCase.firstTurn
297 + ? recorded.entries
298 + .slice(sessionIndex + 1)
299 + .filter((entry) => entry.type !== "runtime_exit")
300 + : []),
301 + {
302 + type: "expect_outbound",
303 + label: "session.set_model",
304 + frame: {
305 + kind: "request",
306 + method: "session/set_config_option",
307 + params: { sessionId, configId: "model", value: rejectedModel },
308 + },
309 + },
310 + {
311 + type: "emit_inbound",
312 + label: "session.set_model.rejected",
313 + frame: {
314 + kind: "response",
315 + method: "session/set_config_option",
316 + error: {
317 + code: testCase.code,
318 + message: testCase.code === -32602 ? "Invalid provider" : "Authentication required",
319 + },
320 + },
321 + },
322 + ],
323 + } satisfies ProviderReplayTranscript;
324 + const materialized = yield* materializeFixtureInput({
325 + scenario: name,
326 + fixtureInput: {
327 + steps: Array.from({ length: testCase.firstTurn ? 2 : 1 }, () => ({
328 + type: "message" as const,
329 + text: SIMPLE_PROMPT,
330 + })),
331 + },
332 + driver: ProviderDriverKind.make("acpRegistry"),
333 + modelSelection: {
334 + ...modelSelection,
335 + model: testCase.firstTurn ? "replay-model-a" : rejectedModel,
336 + },
337 + });
338 + const scenario = {
339 + ...materialized,
340 + name,
341 + transcript: yield* AcpRegistryOrchestratorReplayHarness.decodeTranscript(
342 + materializeReplayTranscriptRuntimeInstructions(transcript, {
343 + driver: ProviderDriverKind.make("acpRegistry"),
344 + model: "replay-model-a",
345 + }),
346 + ),
347 + runtimePolicyOverride: { cwd: yield* checkpointWorkspace(name) },
348 + };
349 + yield* Effect.gen(function* () {
350 + const orchestrator = yield* Orchestrator.OrchestratorV2;
351 + const worker = yield* EffectWorker.OrchestrationEffectWorkerV2;
352 + if (testCase.firstTurn) yield* EffectWorker.runDaemon.pipe(Effect.forkScoped);
353 + for (const [index, command] of materialized.commands.entries()) {
354 + const isFirstTurn =
355 + testCase.firstTurn && command.type === "message.dispatch" && index === 1;
356 + yield* orchestrator.dispatch(
357 + command.type === "message.dispatch" && !isFirstTurn
358 + ? { ...command, modelSelection }
359 + : command,
360 + );
361 + if (isFirstTurn) {
362 + // Wait for the committed terminal event before switching models.
363 + yield* orchestrator.streamStoredEvents.pipe(
364 + Stream.filter(
365 + ({ event }) => event.type === "run.updated" && event.payload.status === "completed",
366 + ),
367 + Stream.runHead,
368 + );
369 + }
370 + }
371 + if (testCase.firstTurn) {
372 + yield* orchestrator.streamStoredEvents.pipe(
373 + Stream.filter(
374 + ({ event }) => event.type === "run.updated" && event.payload.status === "failed",
375 + ),
376 + Stream.runHead,
377 + );
378 + } else {
379 + // Failed opens retry on the outbox schedule. Advance to each recorded
380 + // deadline, draining effects instead of polling the projection.
381 + for (let attempt = 0; attempt < 10; attempt++) {
382 + yield* worker.drain();
383 + const next = yield* worker.nextClaimableAt;
384 + if (Option.isNone(next)) break;
385 + const now = yield* DateTime.now;
386 + yield* TestClock.adjust(
387 + Math.max(0, DateTime.toEpochMillis(next.value) - DateTime.toEpochMillis(now)),
388 + );
389 + }
390 + }
391 + const projection = yield* orchestrator.getThreadProjection(
392 + materialized.projectionThreadIds[0]!,
393 + );
394 + assert.deepEqual(
395 + projection.runs.map((run) => run.status),
396 + testCase.firstTurn ? ["completed", "failed"] : ["failed"],
397 + );
398 + const errors = projection.turnItems.filter((item) => item.type === "error");
399 + assert.lengthOf(errors, 1);
400 + assert.equal(errors[0]?.failure.class, "provider_error");
401 + if (testCase.code === -32602) {
402 + assert.equal(
403 + errors[0]?.failure.message,
404 + 'The agent did not accept the model "replay-model-b". Choose another model for this provider, then retry.',
405 + );
406 + } else {
407 + assert.match(
408 + errors[0]?.failure.message ?? "",
409 + /^Failed to open acpRegistry provider session \S+\.$/u,
410 + );
411 + }
412 + }).pipe(
413 + Effect.provide(
414 + layerProviderReplay(scenario, AcpRegistryOrchestratorReplayHarness, {
415 + runEffectWorker: false,
416 + }),
417 + ),
418 + );
419 + }).pipe(
420 + Effect.scoped,
421 + provideDeterministicTestRuntime,
422 + Effect.provide(Layer.merge(IdAllocator.layer, NodeServices.layer)),
423 + ),
424 + );
425 +
426 it.effect.each(
427 ORCHESTRATOR_REPLAY_FIXTURES.flatMap((fixture) =>
428 fixture.providers.map(
packages/provider-acp/src/server/adapter.ts
+38 -7
@@ -51,6 +51,7 @@ import * as Option from "effect/Option";
51 import * as Queue from "effect/Queue";
52 import * as Ref from "effect/Ref";
53 import * as Result from "effect/Result";
54 +import * as Schema from "effect/Schema";
55 import * as Scope from "effect/Scope";
56 import * as Semaphore from "effect/Semaphore";
57 import * as Stream from "effect/Stream";
@@ -204,6 +205,24 @@ export interface AcpAdapterV2ExtensionContext {
205 readonly lastProposedPlanMarkdown: Effect.Effect<string | undefined>;
206 }
207
208 +/**
209 + * Raised when an agent does not accept the session's model selection: the
210 + * session's model option does not offer it, or the agent answers the write
211 + * with invalid params. `makeProviderFailure` shows its message to the user;
212 + * the agent's reply stays on `cause`.
213 + */
214 +class AcpModelSelectionError extends Schema.TaggedError<AcpModelSelectionError>()(
215 + "AcpModelSelectionError",
216 + {
217 + model: Schema.String,
218 + cause: Schema.Defect(),
219 + },
220 +) {
221 + override get message(): string {
222 + return `The agent did not accept the model "${this.model}". Choose another model for this provider, then retry.`;
223 + }
224 +}
225 +
226 export interface AcpAdapterV2Flavor {
227 readonly promptFailure?: (cause: unknown) => OrchestrationV2ProviderFailure;
228 readonly driver: ProviderDriverKind;
@@ -6610,13 +6629,23 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
6629 ) {
6630 yield* Ref.set(activeSelection, null);
6631 const requestedModel = flavor.resolveModelId?.(modelSelection) ?? modelSelection.model;
6632 + // Invalid params is the agent refusing the value, and the runtime
6633 + // raises the same code when the session's model option does not offer
6634 + // it. Other failures, such as sign-in or a lost connection, keep their
6635 + // own error.
6636 + const rejectedModel = (error: EffectAcpErrors.AcpError) =>
6637 + error._tag === "AcpRequestError" && error.code === -32602
6638 + ? new AcpModelSelectionError({ model: modelSelection.model, cause: error })
6639 + : error;
6640 let appliedModel: string | undefined;
6641 if (flavor.applyModelSelection !== undefined) {
6615 - appliedModel = yield* flavor.applyModelSelection({
6616 - runtime,
6617 - startResult,
6618 - modelSelection,
6619 - });
6642 + appliedModel = yield* flavor
6643 + .applyModelSelection({
6644 + runtime,
6645 + startResult,
6646 + modelSelection,
6647 + })
6648 + .pipe(Effect.mapError(rejectedModel));
6649 } else if (requestedModel.length > 0) {
6650 // Stored catalog choices can expire; explicitly configured custom IDs
6651 // are validated by the agent instead.
@@ -6632,7 +6661,9 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
6661 : entry.options.some((choice) => choice.value === requestedModel),
6662 )
6663 ) {
6635 - yield* runtime.setConfigOption(modelOption.id, requestedModel);
6664 + yield* runtime
6665 + .setConfigOption(modelOption.id, requestedModel)
6666 + .pipe(Effect.mapError(rejectedModel));
6667 appliedModel = requestedModel;
6668 }
6669 } else if (
@@ -6641,7 +6672,7 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
6672 modelState.availableModels.some((model) => model.modelId === requestedModel))
6673 ) {
6674 if (modelState.currentModelId !== requestedModel) {
6644 - yield* runtime.setSessionModel(requestedModel);
6675 + yield* runtime.setSessionModel(requestedModel).pipe(Effect.mapError(rejectedModel));
6676 }
6677 appliedModel = requestedModel;
6678 }
packages/provider-core/src/server/failure.ts
+36 -9
@@ -57,10 +57,24 @@ const PROVIDER_FAILURE_REASONS: Record<ProviderAdapterFailureReason, string> = {
57 attachment_unreadable: "an attachment could not be read",
58 };
59
60 -function causeMessage(cause: unknown): string | undefined {
60 +/**
61 + * Walks a cause chain for curated text without reading arbitrary provider
62 + * defect text. `known` is the message of a domain error T3 raised itself;
63 + * `category` is the generic message of the innermost provider wrapper seen.
64 + */
65 +function curatedCauseMessages(cause: unknown): {
66 + readonly known: string | undefined;
67 + readonly category: string | undefined;
68 +} {
69 const seen = new Set<unknown>();
70 let category: (typeof PROVIDER_FAILURE_CATEGORIES)[string];
71 let reason: string | undefined;
72 + const categoryMessage = () => {
73 + if (category === undefined) return undefined;
74 + return reason
75 + ? `${category.summary}: ${reason}. ${category.guidance}`
76 + : `${category.summary}. ${category.guidance}`;
77 + };
78 for (let depth = 0; depth < 16 && cause != null && !seen.has(cause); depth++) {
79 seen.add(cause);
80 try {
@@ -72,14 +86,19 @@ function causeMessage(cause: unknown): string | undefined {
86 const tag = (cause as Record<string, unknown>)._tag;
87 switch (tag) {
88 case "ContextHandoffBudgetError":
75 - return new ContextHandoffBudgetError().message;
89 + return { known: new ContextHandoffBudgetError().message, category: categoryMessage() };
90 + case "AcpModelSelectionError":
91 case "ClaudeBackgroundWorkBlocksQueryReplacementError":
92 case "ClaudeAppendSystemPromptFileError":
93 case "ClaudeAppendSystemPromptMissingValueError":
94 case "CursorModelUnavailableError":
80 - return stringField(cause, "message");
95 + return { known: stringField(cause, "message"), category: categoryMessage() };
96 case "ContextHandoffDeliveryUncertainError":
82 - return "T3 could not confirm whether conversation history reached the provider. Retry the turn to recover the session.";
97 + return {
98 + known:
99 + "T3 could not confirm whether conversation history reached the provider. Retry the turn to recover the session.",
100 + category: categoryMessage(),
101 + };
102 case "ProviderAdapterProtocolError": {
103 const typedReason = (cause as Record<string, unknown>).reason;
104 if (
@@ -101,10 +120,16 @@ function causeMessage(cause: unknown): string | undefined {
120 break;
121 }
122 }
104 - if (category === undefined) return undefined;
105 - return reason
106 - ? `${category.summary}: ${reason}. ${category.guidance}`
107 - : `${category.summary}. ${category.guidance}`;
123 + return { known: undefined, category: categoryMessage() };
124 +}
125 +
126 +/**
127 + * The curated message of a domain error in a failure's cause chain, if any.
128 + * Callers that pass their own `message` to `makeProviderFailure` check it
129 + * first, so a known reason is not hidden behind a wrapper's text.
130 + */
131 +export function knownProviderFailureMessage(cause: unknown): string | undefined {
132 + return curatedCauseMessages(cause).known;
133 }
134
135 function stringField(value: unknown, key: "message" | "code"): string | undefined {
@@ -183,7 +208,9 @@ export function makeProviderFailure(input: {
208 readonly retryable?: boolean | null;
209 readonly resetAt?: string | null;
210 }): OrchestrationV2ProviderFailure {
186 - const rawMessage = input.message ?? causeMessage(input.cause) ?? DEFAULT_PROVIDER_FAILURE_MESSAGE;
211 + const curated = curatedCauseMessages(input.cause);
212 + const rawMessage =
213 + input.message ?? curated.known ?? curated.category ?? DEFAULT_PROVIDER_FAILURE_MESSAGE;
214 const message = boundedText(rawMessage, MAX_PROVIDER_FAILURE_MESSAGE_LENGTH);
215 const rawCode = input.code ?? stringField(input.cause, "code") ?? null;
216 const code =