@@ -18,12 +18,12 @@ import {
1818 type ServerProvider ,
1919 ThreadId ,
2020} from "@t3tools/contracts" ;
21- import * as Cause from "effect/Cause" ;
2221import * as Crypto from "effect/Crypto" ;
2322import * as DateTime from "effect/DateTime" ;
2423import * as Effect from "effect/Effect" ;
2524import * as Option from "effect/Option" ;
2625
26+ import type { OrchestrationDispatchError } from "../../../orchestration/Errors.ts" ;
2727import * as OrchestrationEngine from "../../../orchestration/Services/OrchestrationEngine.ts" ;
2828import * as ProjectionSnapshotQuery from "../../../orchestration/Services/ProjectionSnapshotQuery.ts" ;
2929import * 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-
4637function 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+
262276function 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