Skip to content

Commit d892d55

Browse files
t3dotggclaude
andcommitted
fix(server): build create_threads failure messages from error tags
Follow the repo's error conventions: construct OrchestratorMcpFailure at each failure site instead of through a forwarding helper, and never copy cause.message into the message the agent sees. The message now names the failed step and tells the agent whether a retry with the same clientRequestId can help. The full error still goes to the log. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 02a3a3d commit d892d55

2 files changed

Lines changed: 94 additions & 66 deletions

File tree

‎apps/server/src/mcp/toolkits/orchestrator/handlers.test.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -402,7 +402,9 @@ describe("orchestrator toolkit: create_threads", () => {
402402
const request = { threads: [{ prompt: "Do it" }], clientRequestId: "req-1" };
403403
const error = yield* harness.createThreadsFailure(request);
404404
expect(error.code).toBe("orchestration_error");
405-
expect(error.message).toContain("Unable to start thread 1");
405+
expect(error.message).toBe(
406+
"Unable to start thread 1: T3 Code could not read or write its database. Retry with the same clientRequestId.",
407+
);
406408

407409
storageDown = false;
408410
const retry = yield* harness.createThreads(request);
@@ -428,8 +430,12 @@ describe("orchestrator toolkit: create_threads", () => {
428430
const request = { threads: [{ prompt: "Do it" }], clientRequestId: "req-1" };
429431
const first = yield* harness.createThreadsFailure(request);
430432
const retry = yield* harness.createThreadsFailure(request);
431-
expect(first.message).toContain("Thread is archived.");
432-
expect(retry.message).toContain("Thread is archived.");
433+
expect(first.message).toBe(
434+
"Unable to start thread 1: T3 Code rejected the thread.turn.start command.",
435+
);
436+
// The engine stored the rejection, so the retry fails with a hint instead
437+
// of reporting a thread without its first turn as started.
438+
expect(retry.message).toContain("Retry with a new clientRequestId.");
433439
}),
434440
);
435441
});

‎apps/server/src/mcp/toolkits/orchestrator/handlers.ts‎

Lines changed: 85 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,12 @@ import {
1818
type ServerProvider,
1919
ThreadId,
2020
} from "@t3tools/contracts";
21-
import * as Cause from "effect/Cause";
2221
import * as Crypto from "effect/Crypto";
2322
import * as DateTime from "effect/DateTime";
2423
import * as Effect from "effect/Effect";
2524
import * as Option from "effect/Option";
2625

26+
import type { OrchestrationDispatchError } from "../../../orchestration/Errors.ts";
2727
import * as OrchestrationEngine from "../../../orchestration/Services/OrchestrationEngine.ts";
2828
import * as ProjectionSnapshotQuery from "../../../orchestration/Services/ProjectionSnapshotQuery.ts";
2929
import * as ProviderRegistry from "../../../provider/Services/ProviderRegistry.ts";
@@ -34,15 +34,6 @@ import { OrchestratorToolkit } from "./tools.ts";
3434
// apps/server/src/mcp/OrchestratorMcpService.ts). Keep them in step until
3535
// V2 replaces this file.
3636

37-
function failure(code: OrchestratorMcpFailure["code"], message: string): OrchestratorMcpFailure {
38-
return new OrchestratorMcpFailure({ code, message });
39-
}
40-
41-
function errorMessage(cause: Cause.Cause<unknown>): string {
42-
const error = Cause.squash(cause);
43-
return error instanceof Error ? error.message : String(error);
44-
}
45-
4637
function runtimeModeRank(mode: RuntimeMode): number {
4738
switch (mode) {
4839
case "approval-required":
@@ -68,10 +59,10 @@ function resolveRuntimeMode(
6859
const resolved = requested === undefined || requested === "inherit" ? parentMode : requested;
6960
return runtimeModeRank(resolved) > runtimeModeRank(parentMode)
7061
? Effect.fail(
71-
failure(
72-
"runtime_mode_escalation_denied",
73-
`Child runtime mode ${resolved} is broader than parent mode ${parentMode}.`,
74-
),
62+
new OrchestratorMcpFailure({
63+
code: "runtime_mode_escalation_denied",
64+
message: `Child runtime mode ${resolved} is broader than parent mode ${parentMode}.`,
65+
}),
7566
)
7667
: Effect.succeed(resolved);
7768
}
@@ -83,10 +74,10 @@ function resolveInteractionMode(
8374
const resolved = requested === undefined || requested === "inherit" ? parentMode : requested;
8475
return interactionModeRank(resolved) > interactionModeRank(parentMode)
8576
? Effect.fail(
86-
failure(
87-
"interaction_mode_escalation_denied",
88-
`Child interaction mode ${resolved} is broader than parent mode ${parentMode}.`,
89-
),
77+
new OrchestratorMcpFailure({
78+
code: "interaction_mode_escalation_denied",
79+
message: `Child interaction mode ${resolved} is broader than parent mode ${parentMode}.`,
80+
}),
9081
)
9182
: Effect.succeed(resolved);
9283
}
@@ -171,33 +162,33 @@ function resolveTarget(input: {
171162
) ?? candidates[0]
172163
)?.instanceId;
173164
if (instanceId === undefined) {
174-
return yield* failure(
175-
"provider_unavailable",
176-
`No available provider instance for driver ${requestedDriver}.`,
177-
);
165+
return yield* new OrchestratorMcpFailure({
166+
code: "provider_unavailable",
167+
message: `No available provider instance for driver ${requestedDriver}.`,
168+
});
178169
}
179170
}
180171
instanceId ??= input.parent.modelSelection.instanceId;
181172

182173
const provider = input.providers.find((candidate) => candidate.instanceId === instanceId);
183174
if (provider === undefined) {
184-
return yield* failure(
185-
"provider_unavailable",
186-
`Provider instance ${instanceId} is not registered.`,
187-
);
175+
return yield* new OrchestratorMcpFailure({
176+
code: "provider_unavailable",
177+
message: `Provider instance ${instanceId} is not registered.`,
178+
});
188179
}
189180
if (requestedDriver !== undefined && provider.driver !== requestedDriver) {
190-
return yield* failure(
191-
"invalid_request",
192-
`Provider instance ${instanceId} uses driver ${provider.driver}, not ${requestedDriver}.`,
193-
);
181+
return yield* new OrchestratorMcpFailure({
182+
code: "invalid_request",
183+
message: `Provider instance ${instanceId} uses driver ${provider.driver}, not ${requestedDriver}.`,
184+
});
194185
}
195186
const constraints = providerConstraints(provider);
196187
if (constraints.length > 0) {
197-
return yield* failure(
198-
"provider_unavailable",
199-
`Provider ${instanceId} cannot run a new thread: ${constraints.join(" ")}`,
200-
);
188+
return yield* new OrchestratorMcpFailure({
189+
code: "provider_unavailable",
190+
message: `Provider ${instanceId} cannot run a new thread: ${constraints.join(" ")}`,
191+
});
201192
}
202193

203194
const inherited = input.parent.modelSelection;
@@ -206,20 +197,20 @@ function resolveTarget(input: {
206197
requestedModel ??
207198
(instanceId === inherited.instanceId ? inherited.model : provider.models[0]?.slug);
208199
if (model === undefined) {
209-
return yield* failure(
210-
"model_unavailable",
211-
`Provider ${instanceId} has no model available for inheritance.`,
212-
);
200+
return yield* new OrchestratorMcpFailure({
201+
code: "model_unavailable",
202+
message: `Provider ${instanceId} has no model available for inheritance.`,
203+
});
213204
}
214205
if (
215206
requestedModel !== undefined &&
216207
provider.models.length > 0 &&
217208
!provider.models.some((candidate) => candidate.slug === requestedModel)
218209
) {
219-
return yield* failure(
220-
"model_unavailable",
221-
`Model ${requestedModel} is not advertised by provider ${instanceId}.`,
222-
);
210+
return yield* new OrchestratorMcpFailure({
211+
code: "model_unavailable",
212+
message: `Model ${requestedModel} is not advertised by provider ${instanceId}.`,
213+
});
223214
}
224215

225216
const requestedOptions = input.target?.options;
@@ -228,10 +219,10 @@ function resolveTarget(input: {
228219
?.capabilities?.optionDescriptors;
229220
const invalid = invalidOptionSelections(requestedOptions, descriptors);
230221
if (invalid.length > 0) {
231-
return yield* failure(
232-
"invalid_request",
233-
`Model ${model} on provider ${instanceId} rejected options: ${invalid.join(" ")}`,
234-
);
222+
return yield* new OrchestratorMcpFailure({
223+
code: "invalid_request",
224+
message: `Model ${model} on provider ${instanceId} rejected options: ${invalid.join(" ")}`,
225+
});
235226
}
236227
}
237228

@@ -259,6 +250,29 @@ function threadTitle(input: {
259250
return detail.length > 80 ? `${detail.slice(0, 77)}...` : detail;
260251
}
261252

253+
/**
254+
* What the agent can do about a failed dispatch or read, from the error tag
255+
* alone. The engine replays an accepted command id, so a storage failure is
256+
* safe to retry with the same clientRequestId. A rejection is stored too, so
257+
* retrying it needs a new clientRequestId.
258+
*/
259+
function orchestrationErrorReason(error: OrchestrationDispatchError): string {
260+
switch (error._tag) {
261+
case "OrchestrationCommandInvariantError":
262+
return `T3 Code rejected the ${error.commandType} command.`;
263+
case "OrchestrationThreadSettleBlockedError":
264+
return "T3 Code rejected the command.";
265+
case "OrchestrationCommandPreviouslyRejectedError":
266+
return "An earlier call with this clientRequestId was rejected. Retry with a new clientRequestId.";
267+
case "OrchestrationCommandIdConflictError":
268+
return "This clientRequestId was already used for other work. Retry with a new clientRequestId.";
269+
case "PersistenceSqlError":
270+
case "PersistenceDecodeError":
271+
case "OrchestrationProjectorDecodeError":
272+
return "T3 Code could not read or write its database. Retry with the same clientRequestId.";
273+
}
274+
}
275+
262276
function createdThreadStatus(
263277
thread: OrchestrationThreadShell,
264278
started: boolean,
@@ -288,36 +302,44 @@ const make = Effect.gen(function* () {
288302
const encoder = new TextEncoder();
289303

290304
// A returned failure is a normal tool result, so McpServer never logs it.
291-
// Log the cause here. The agent gets the message, the same text V2 returns.
305+
// Log the error here, and give the agent a message built from its tag.
292306
const orchestrationError =
293307
(context: string) =>
294-
<E>(cause: Cause.Cause<E>): Effect.Effect<never, OrchestratorMcpFailure> =>
295-
Cause.hasInterruptsOnly(cause)
296-
? Effect.failCause(cause as Cause.Cause<never>)
297-
: Effect.logWarning(`create_threads: ${context}`, cause).pipe(
298-
Effect.andThen(
299-
Effect.fail(failure("orchestration_error", `${context}: ${errorMessage(cause)}`)),
300-
),
301-
);
308+
(error: OrchestrationDispatchError): Effect.Effect<never, OrchestratorMcpFailure> =>
309+
Effect.logWarning(`create_threads: ${context}`, error).pipe(
310+
Effect.andThen(
311+
Effect.fail(
312+
new OrchestratorMcpFailure({
313+
code: "orchestration_error",
314+
message: `${context}: ${orchestrationErrorReason(error)}`,
315+
}),
316+
),
317+
),
318+
);
302319

303320
const requireScope = Effect.gen(function* () {
304321
const scope = yield* McpInvocationContext.McpInvocationContext;
305322
if (!scope.capabilities.has("orchestration")) {
306-
return yield* failure(
307-
"capability_denied",
308-
"This MCP credential does not grant orchestration capabilities.",
309-
);
323+
return yield* new OrchestratorMcpFailure({
324+
code: "capability_denied",
325+
message: "This MCP credential does not grant orchestration capabilities.",
326+
});
310327
}
311328
return scope;
312329
});
313330

314331
const loadThread = (threadId: ThreadId) =>
315332
snapshots.getThreadShellById(threadId).pipe(
316-
Effect.catchCause(orchestrationError(`Unable to read thread ${threadId}`)),
333+
Effect.catch(orchestrationError(`Unable to read thread ${threadId}`)),
317334
Effect.flatMap(
318335
Option.match({
319336
onNone: () =>
320-
Effect.fail(failure("thread_not_found", `Thread ${threadId} was not found.`)),
337+
Effect.fail(
338+
new OrchestratorMcpFailure({
339+
code: "thread_not_found",
340+
message: `Thread ${threadId} was not found.`,
341+
}),
342+
),
321343
onSome: Effect.succeed,
322344
}),
323345
),
@@ -437,7 +459,7 @@ const make = Effect.gen(function* () {
437459
worktreePath: parent.worktreePath,
438460
createdAt,
439461
})
440-
.pipe(Effect.catchCause(orchestrationError(`Unable to create thread ${index + 1}`)));
462+
.pipe(Effect.catch(orchestrationError(`Unable to create thread ${index + 1}`)));
441463
if (request.prompt !== undefined) {
442464
yield* engine
443465
.dispatch({
@@ -463,7 +485,7 @@ const make = Effect.gen(function* () {
463485
interactionMode: plan.interactionMode,
464486
createdAt,
465487
})
466-
.pipe(Effect.catchCause(orchestrationError(`Unable to start thread ${index + 1}`)));
488+
.pipe(Effect.catch(orchestrationError(`Unable to start thread ${index + 1}`)));
467489
}
468490
// Read back what the engine holds: a retried request reports the
469491
// thread it created the first time, not this call's input.

0 commit comments

Comments
 (0)