The best way to control Claude Code, Codex and more from any computer or phone
fix(server): MCP tools say why the orchestrator refused (#36083)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Fuksss committed
Nov 14, 2026 at 08:05 UTC
e1f5b682813fa5c15366513ce1868d6c5b50b655
2 files changed
+271
-8
apps/server/src/mcp/OrchestratorMcpService.test.ts
+264
-1
@@ -54,6 +54,7 @@ import {
54
type DispatchModeRefusal,
55
} from "../orchestration-v2/DispatchModeLimit.ts";
56
import {
57
+ OrchestratorDispatchError,
58
OrchestratorProjectionError,
59
OrchestratorThreadAboveModeLimitError,
60
} from "../orchestration-v2/Orchestrator.ts";
@@ -707,7 +708,15 @@ describe("OrchestratorMcpService", () => {
708
cancelDelegatedTask: ({ command, stopDescendants }) =>
709
stopDescendants(() => Effect.die("No remote descendants in this test")).pipe(
710
Effect.andThen(Ref.update(dispatched, (commands) => [...commands, command])),
710
- Effect.andThen(Effect.fail(new Error("simulated stop failure") as never)),
711
+ Effect.andThen(
712
+ Effect.fail(
713
+ new OrchestratorDispatchError({
714
+ commandId: command.commandId,
715
+ commandType: command.type,
716
+ cause: new Error("simulated stop failure"),
717
+ }) as never,
718
+ ),
719
+ ),
720
),
721
}),
722
ServerSettings.layerTest(),
@@ -739,6 +748,10 @@ describe("OrchestratorMcpService", () => {
748
.cancelTask(scope, { taskId, clientRequestId: "cancel-failed-task" })
749
.pipe(Effect.flip);
750
assert.equal(error.code, "task_not_cancellable");
751
+ assert.equal(
752
+ error.message,
753
+ `Unable to stop delegated task ${taskId}: simulated stop failure`,
754
+ );
755
assert.deepEqual(
756
(yield* Ref.get(dispatched)).map((command) => (command as { type: string }).type),
757
["thread.stop"],
@@ -841,6 +854,98 @@ describe("OrchestratorMcpService", () => {
854
}),
855
);
856
857
+ it.effect(
858
+ "reports the dispatch cause instead of the generic wrapper when disposing a finished task's completion delivery fails",
859
+ () =>
860
+ Effect.gen(function* () {
861
+ const parentThreadId = ThreadId.make("thread:mcp-cancel-dispose-cause-parent");
862
+ const childThreadId = ThreadId.make("thread:mcp-cancel-dispose-cause-child");
863
+ const taskId = NodeId.make("node:mcp-cancel-dispose-cause-task");
864
+ const parentProjection = {
865
+ thread: { id: parentThreadId },
866
+ runs: [],
867
+ contextTransfers: [],
868
+ subagents: [
869
+ {
870
+ id: taskId,
871
+ threadId: parentThreadId,
872
+ origin: "app_owned",
873
+ childThreadId,
874
+ driver: "codex",
875
+ model: "gpt-5.6-terra",
876
+ status: "completed",
877
+ result: "Done.",
878
+ completionDelivery: { state: "pending" },
879
+ },
880
+ ],
881
+ } as unknown as OrchestrationV2ThreadProjection;
882
+ const childProjection = {
883
+ thread: { id: childThreadId, title: "Child" },
884
+ runs: [],
885
+ contextTransfers: [],
886
+ messages: [],
887
+ subagents: [],
888
+ providerThreads: [],
889
+ providerTurns: [],
890
+ runtimeRequests: [],
891
+ } as unknown as OrchestrationV2ThreadProjection;
892
+ const layerDependencies = Layer.mergeAll(
893
+ NodeServices.layer,
894
+ NodeCrypto.layer,
895
+ Layer.mock(ThreadManagementService.ThreadManagementService)({
896
+ getThreadRecords: (threadId) =>
897
+ Effect.succeed(threadId === parentThreadId ? parentProjection : childProjection),
898
+ getThreadShell: (threadId) => Effect.succeed(liveThreadShell(threadId)),
899
+ listAppOwnedChildThreadIds: () => Effect.succeed([]),
900
+ stopDelegatedTasks: () => Effect.void,
901
+ cancelDelegatedTask: () => Effect.void,
902
+ dispatch: (command) =>
903
+ command.type === "delegated_task.completion-delivery.dispose"
904
+ ? Effect.fail(
905
+ new OrchestratorDispatchError({
906
+ commandId: command.commandId,
907
+ commandType: command.type,
908
+ cause: new Error("refused by the orchestrator"),
909
+ }) as never,
910
+ )
911
+ : Effect.succeed({} as never),
912
+ }),
913
+ ServerSettings.layerTest(),
914
+ Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }),
915
+ Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
916
+ list: () => Effect.succeed([]),
917
+ }),
918
+ Layer.mock(ProjectService.ProjectService)({}),
919
+ Layer.mock(SecretRequests.SecretRequests)({}),
920
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
921
+ Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
922
+ );
923
+ const scope: McpInvocationScope = {
924
+ environmentId: EnvironmentId.make("environment:mcp-cancel-dispose-cause"),
925
+ requestNamespace: "provider-session:mcp-cancel-dispose-cause",
926
+ thread: {
927
+ threadId: parentThreadId,
928
+ providerSessionId: "provider-session:mcp-cancel-dispose-cause",
929
+ providerInstanceId: ProviderInstanceId.make("codex"),
930
+ },
931
+ client: undefined,
932
+ capabilities: new Set(["orchestration"]),
933
+ issuedAt: 1,
934
+ };
935
+ const error = yield* Effect.gen(function* () {
936
+ const service = yield* OrchestratorMcpService.OrchestratorMcpService;
937
+ return yield* service
938
+ .cancelTask(scope, { taskId, clientRequestId: "cancel-dispose-dispatch-cause" })
939
+ .pipe(Effect.flip);
940
+ }).pipe(Effect.provide(layerOrchestratorService.pipe(Layer.provide(layerDependencies))));
941
+ assert.equal(error.code, "orchestration_error");
942
+ assert.equal(
943
+ error.message,
944
+ `Unable to dispose delegated task ${taskId} completion delivery: refused by the orchestrator`,
945
+ );
946
+ }),
947
+ );
948
+
949
it.effect("refuses to cancel a task whose child now runs above the parent's modes", () =>
950
Effect.gen(function* () {
951
const parentThreadId = ThreadId.make("thread:mcp-cancel-dispose-failed-parent");
@@ -1976,6 +2081,119 @@ describe("OrchestratorMcpService provider resolution", () => {
2081
}),
2082
);
2083
2084
+ it.effect("reports the dispatch cause instead of the generic wrapper when delegating fails", () =>
2085
+ Effect.gen(function* () {
2086
+ const layerDependencies = Layer.mergeAll(
2087
+ NodeServices.layer,
2088
+ NodeCrypto.layer,
2089
+ Layer.mock(ThreadManagementService.ThreadManagementService)({
2090
+ hasReceipt: () => Effect.succeed(false),
2091
+ getThreadRecords: () => Effect.succeed(parentProjection([])),
2092
+ dispatch: (command) =>
2093
+ Effect.fail(
2094
+ new OrchestratorDispatchError({
2095
+ commandId: command.commandId,
2096
+ commandType: command.type,
2097
+ cause: new Error("refused by the orchestrator"),
2098
+ }) as never,
2099
+ ),
2100
+ }),
2101
+ ServerSettings.layerTest(),
2102
+ providerRegistryLayer([
2103
+ providerSnapshot({
2104
+ instanceId: codexInstanceId,
2105
+ driver: ProviderDriverKind.make("codex"),
2106
+ model: "gpt-5.4",
2107
+ }),
2108
+ ]),
2109
+ adapterRegistryLayer([codexInstanceId]),
2110
+ Layer.mock(ProjectService.ProjectService)({}),
2111
+ Layer.mock(SecretRequests.SecretRequests)({}),
2112
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2113
+ Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
2114
+ );
2115
+ const error = yield* Effect.gen(function* () {
2116
+ const service = yield* OrchestratorMcpService.OrchestratorMcpService;
2117
+ return yield* service
2118
+ .delegateTask(scope, {
2119
+ task: "Summarize the diff.",
2120
+ mode: "async",
2121
+ clientRequestId: "delegate-dispatch-cause",
2122
+ })
2123
+ .pipe(Effect.flip);
2124
+ }).pipe(Effect.provide(layerOrchestratorService.pipe(Layer.provide(layerDependencies))));
2125
+ assert.equal(error.code, "orchestration_error");
2126
+ assert.equal(error.message, "Unable to create delegated task: refused by the orchestrator");
2127
+ }),
2128
+ );
2129
+
2130
+ it.effect.each([
2131
+ { failingType: "thread.create", prefix: "Unable to create thread 1: " },
2132
+ { failingType: "message.dispatch", prefix: "Unable to start thread 1: " },
2133
+ {
2134
+ failingType: "thread.created.record",
2135
+ prefix: "Unable to record thread 1 in the parent timeline: ",
2136
+ },
2137
+ ] as const)(
2138
+ "reports the dispatch cause instead of the generic wrapper when create_threads' $failingType dispatch fails",
2139
+ ({ failingType, prefix }) =>
2140
+ Effect.gen(function* () {
2141
+ const childThreadId = ThreadId.make("thread:mcp-providers-create-child");
2142
+ const childShell = {
2143
+ thread: {
2144
+ id: childThreadId,
2145
+ title: "Child",
2146
+ modelSelection: { instanceId: codexInstanceId, model: "gpt-5.4" },
2147
+ },
2148
+ runs: [],
2149
+ } as unknown as OrchestrationV2ThreadProjection;
2150
+ const layerDependencies = Layer.mergeAll(
2151
+ NodeServices.layer,
2152
+ NodeCrypto.layer,
2153
+ Layer.mock(ThreadManagementService.ThreadManagementService)({
2154
+ hasReceipt: () => Effect.succeed(false),
2155
+ assertProviderInstanceEnabled: () => Effect.void,
2156
+ getThreadRecords: (threadId) =>
2157
+ Effect.succeed(threadId === parentThreadId ? parentProjection([]) : childShell),
2158
+ dispatch: (command) =>
2159
+ command.type === failingType
2160
+ ? Effect.fail(
2161
+ new OrchestratorDispatchError({
2162
+ commandId: command.commandId,
2163
+ commandType: command.type,
2164
+ cause: new Error("refused by the orchestrator"),
2165
+ }) as never,
2166
+ )
2167
+ : Effect.succeed({} as never),
2168
+ }),
2169
+ ServerSettings.layerTest(),
2170
+ providerRegistryLayer([
2171
+ providerSnapshot({
2172
+ instanceId: codexInstanceId,
2173
+ driver: ProviderDriverKind.make("codex"),
2174
+ model: "gpt-5.4",
2175
+ }),
2176
+ ]),
2177
+ adapterRegistryLayer([codexInstanceId]),
2178
+ Layer.mock(ProjectService.ProjectService)({}),
2179
+ Layer.mock(SecretRequests.SecretRequests)({}),
2180
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
2181
+ Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
2182
+ );
2183
+ const error = yield* Effect.gen(function* () {
2184
+ const service = yield* OrchestratorMcpService.OrchestratorMcpService;
2185
+ return yield* service
2186
+ .createThreads(scope, {
2187
+ threads: [{ prompt: "Summarize the diff." }],
2188
+ clientRequestId: `create-threads-dispatch-cause-${failingType}`,
2189
+ })
2190
+ .pipe(Effect.flip);
2191
+ }).pipe(Effect.provide(layerOrchestratorService.pipe(Layer.provide(layerDependencies))));
2192
+ assert.equal(error.code, "orchestration_error");
2193
+ assert.equal(error.message, `${prefix}refused by the orchestrator`);
2194
+ }),
2195
+ );
2196
+
2197
it.effect("driver-only delegation skips an instance the project turned off", () =>
2198
Effect.gen(function* () {
2199
const altInstanceId = ProviderInstanceId.make("codex-alt");
@@ -3719,6 +3937,51 @@ describe("OrchestratorMcpService provider resolution", () => {
3937
}),
3938
);
3939
3940
+ it.effect(
3941
+ "reports the dispatch cause instead of the generic wrapper when interrupting fails",
3942
+ () =>
3943
+ Effect.gen(function* () {
3944
+ const layerDependencies = Layer.mergeAll(
3945
+ NodeServices.layer,
3946
+ NodeCrypto.layer,
3947
+ Layer.mock(ThreadManagementService.ThreadManagementService)({
3948
+ getThreadRecords: () => Effect.succeed(parentProjection([])),
3949
+ interruptThread: (input) =>
3950
+ Effect.fail(
3951
+ new OrchestratorDispatchError({
3952
+ commandId: input.commandId,
3953
+ commandType: "thread.interrupt",
3954
+ cause: new Error("refused by the orchestrator"),
3955
+ }) as never,
3956
+ ),
3957
+ }),
3958
+ ServerSettings.layerTest(),
3959
+ Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }),
3960
+ Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
3961
+ list: () => Effect.succeed([]),
3962
+ }),
3963
+ Layer.mock(ProjectService.ProjectService)({}),
3964
+ Layer.mock(SecretRequests.SecretRequests)({}),
3965
+ Layer.mock(RemoteDelegation.RemoteDelegation)({}),
3966
+ Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
3967
+ );
3968
+ const error = yield* Effect.gen(function* () {
3969
+ const service = yield* OrchestratorMcpService.OrchestratorMcpService;
3970
+ return yield* service
3971
+ .interruptThread(scope, {
3972
+ threadId: parentThreadId,
3973
+ clientRequestId: "interrupt-dispatch-cause",
3974
+ })
3975
+ .pipe(Effect.flip);
3976
+ }).pipe(Effect.provide(layerOrchestratorService.pipe(Layer.provide(layerDependencies))));
3977
+ assert.equal(error.code, "orchestration_error");
3978
+ assert.equal(
3979
+ error.message,
3980
+ `Unable to interrupt thread ${parentThreadId}: refused by the orchestrator`,
3981
+ );
3982
+ }),
3983
+ );
3984
+
3985
describe("resolveRuntimeMode", () => {
3986
const muse = {
3987
modelSelection: { instanceId: ProviderInstanceId.make("muse"), model: "muse-model" },
apps/server/src/mcp/OrchestratorMcpService.ts
+7
-7
@@ -2661,7 +2661,7 @@ const make = Effect.gen(function* () {
2661
? threadManagementFailure(error)
2662
: failure(
2663
"orchestration_error",
2664
- `Unable to create delegated task: ${errorMessage(error)}`,
2664
+ `Unable to create delegated task: ${userFacingDispatchErrorMessage(error) ?? errorMessage(error)}`,
2665
),
2666
),
2667
);
@@ -2769,7 +2769,7 @@ const make = Effect.gen(function* () {
2769
Effect.mapError((error) =>
2770
failure(
2771
"orchestration_error",
2772
- `Unable to dispose delegated task ${input.taskId} completion delivery: ${errorMessage(error)}`,
2772
+ `Unable to dispose delegated task ${input.taskId} completion delivery: ${userFacingDispatchErrorMessage(error) ?? errorMessage(error)}`,
2773
),
2774
),
2775
);
@@ -2800,7 +2800,7 @@ const make = Effect.gen(function* () {
2800
Effect.mapError((error) =>
2801
failure(
2802
"task_not_cancellable",
2803
- `Unable to stop delegated task ${input.taskId}: ${errorMessage(error)}`,
2803
+ `Unable to stop delegated task ${input.taskId}: ${userFacingDispatchErrorMessage(error) ?? errorMessage(error)}`,
2804
),
2805
),
2806
);
@@ -3004,7 +3004,7 @@ const make = Effect.gen(function* () {
3004
Effect.mapError((error) =>
3005
failure(
3006
"orchestration_error",
3007
- `Unable to create thread ${index + 1}: ${errorMessage(error)}`,
3007
+ `Unable to create thread ${index + 1}: ${userFacingDispatchErrorMessage(error) ?? errorMessage(error)}`,
3008
),
3009
),
3010
);
@@ -3042,7 +3042,7 @@ const make = Effect.gen(function* () {
3042
? threadManagementFailure(error)
3043
: failure(
3044
"orchestration_error",
3045
- `Unable to start thread ${index + 1}: ${errorMessage(error)}`,
3045
+ `Unable to start thread ${index + 1}: ${userFacingDispatchErrorMessage(error) ?? errorMessage(error)}`,
3046
),
3047
),
3048
);
@@ -3068,7 +3068,7 @@ const make = Effect.gen(function* () {
3068
Effect.mapError((error) =>
3069
failure(
3070
"orchestration_error",
3071
- `Unable to record thread ${index + 1} in the parent timeline: ${errorMessage(error)}`,
3071
+ `Unable to record thread ${index + 1} in the parent timeline: ${userFacingDispatchErrorMessage(error) ?? errorMessage(error)}`,
3072
),
3073
),
3074
);
@@ -3469,7 +3469,7 @@ const make = Effect.gen(function* () {
3469
? threadManagementFailure(error)
3470
: failure(
3471
"orchestration_error",
3472
- `Unable to interrupt thread ${input.threadId}: ${errorMessage(error)}`,
3472
+ `Unable to interrupt thread ${input.threadId}: ${userFacingDispatchErrorMessage(error) ?? errorMessage(error)}`,
3473
),
3474
),
3475
);