Route tool defects opaquely; remove legacy envelope shim (#826)

* feat(tool-result): add ToolResult union and dual-shape invoker Adds `ToolResult<T>` / `ToolError` to @executor-js/sdk and a `ToolResult.ok` / `ToolResult.fail` constructor pair. Updates the sandbox tool dispatcher to accept both the new typed union (passes through unchanged) and the legacy `{ data, error }` envelope. The legacy branch now walks known upstream shapes (Microsoft Graph, DealCloud, JSON:API, plain message-bearing bodies) before falling back to a clamped JSON.stringify of the body, so structured 4xx payloads no longer collapse to 'Tool execution failed'. The cause/defect branch keeps its strict .message-only discipline. * feat(plugins): emit ToolResult from openapi, graphql, mcp, google-discovery Migrates each dynamic plugin's invokeTool to wrap its result in the typed ToolResult<T> union. OpenAPI and Google Discovery map non-2xx responses to ToolResult.fail with an extracted upstream message and the raw body in error.details; 2xx responses to ToolResult.ok with { status, headers, data }. GraphQL maps 200-with-errors bodies to ToolResult.fail({ code: 'graphql_errors', ... }) and bare data to ToolResult.ok. MCP maps { isError: true } to ToolResult.fail and content arrays to ToolResult.ok. Static plugin tools (executor.openapi.previewSpec / addSource, executor.graphql.addSource) now also wrap their plain values in ToolResult.ok for shape consistency. Updates plugin tests that asserted on the old { status, headers, data, error } envelope or the bare MCP { content } shape. Tests that consume the OpenAPI plugin's invocation result use the new unwrapInvocation helper from @executor-js/plugin-openapi/testing. * feat(tool-result): make ToolResult mandatory and route defects opaquely Removes the legacy { data, error } envelope shim from the sandbox tool dispatcher. The invoker now passes ToolResult<T> through unchanged and wraps any other plain-value plugin return in ToolResult.ok so the sandbox surface is uniform. Plugin/infra defects no longer pass their message into the sandbox. The dispatcher generates a short hex correlation id, logs the full cause with that id under executor.correlation_id, and rejects with `Internal tool error [<corrId>]`. The QuickJS bridge and the dynamic-worker module template defensively re-stamp the same opaque shape; the MCP host server's top-level execute failure path does the same. ExecutionToolError in-band messages from the execution package's built-in validators (tools.search arg checks, etc.) are still passed through at the QuickJS bridge so model-facing input errors keep their useful diagnostic. Tests: - ToolResult.ok / fail / isToolResult constructor unit tests. - repro tests assert structured upstream payloads now reach the sandbox through ToolResult.error.details (not through .message). - leak tests pin the new invariant: plugin defects only escape as the opaque generic + correlation id; no token / connection string / file path leaks into Error.message. - QuickJS end-to-end defect test confirms the same shape at the sandbox boundary. - Cloud HTTP integration tests, MCP host tests, dynamic-worker invocation tests, and plugin tests updated for the new ToolResult wire shape and the opaque-generic defect contract. * Fix tool result contracts

Rhys Sullivan committed 6 months ago

Commit 278ca7c1 parent 8d986ff35 files · +1322 −340Browse files

Showing the changes to packages/plugins (19 of 35 files). Show all

Unified · Split

19 files

packages/plugins/google-discovery/src/sdk/option-json.test.ts +4 −4
packages/plugins/google-discovery/src/sdk/plugin.test.ts +3 −3
packages/plugins/google-discovery/src/sdk/plugin.ts +85 −5
packages/plugins/graphql/src/sdk/plugin.test.ts +48 −9
packages/plugins/graphql/src/sdk/plugin.ts +37 −2
packages/plugins/mcp/src/react/AddMcpSource.tsx +11 −16
packages/plugins/mcp/src/sdk/elicitation.test.ts +30 −3
packages/plugins/mcp/src/sdk/per-user-auth-isolation.test.ts +6 −3
packages/plugins/mcp/src/sdk/plugin.ts +31 −1
packages/plugins/mcp/src/testing/server.ts +17 −0
packages/plugins/openapi/src/sdk/client-credentials-oauth.test.ts +10 −13
packages/plugins/openapi/src/sdk/multi-scope-bearer.test.ts +49 −60
packages/plugins/openapi/src/sdk/multi-scope-oauth.test.ts +29 −24
packages/plugins/openapi/src/sdk/oauth-refresh.test.ts +9 −12
packages/plugins/openapi/src/sdk/plugin.test.ts +38 −39
packages/plugins/openapi/src/sdk/plugin.ts +88 −3
packages/plugins/openapi/src/sdk/upstream-failures.test.ts +5 −4
packages/plugins/openapi/src/testing/index.ts +54 −2
packages/plugins/workos-vault/src/sdk/secret-store.test.ts +1 −1

packages/plugins/google-discovery/src/sdk/option-json.test.tsrenamed from packages/plugins/google-discovery/src/sdk/option-json-repro.test.ts+4−4

packages/plugins/google-discovery/src/sdk/plugin.test.ts+3−3

@@ -430,10 +430,10 @@ describe("Google Discovery plugin", () => { · 429 unmodified lines
430	"drive.files.get",	430	"drive.files.get",
431	{ fileId: "123", fields: "id,name", prettyPrint: true },	431	{ fileId: "123", fields: "id,name", prettyPrint: true },
432	autoApprove,	432	autoApprove,
433	)) as { data: unknown; error: unknown };	433	)) as { readonly ok: true; readonly data: { status: number; data: unknown } };
434		434
435	expect(invocation.error).toBeNull();	435	expect(invocation.ok).toBe(true);
436	expect(invocation.data).toEqual({ id: "123", name: "Quarterly Plan" });	436	expect(invocation.data.data).toEqual({ id: "123", name: "Quarterly Plan" });
437		437
438	const apiRequest = handle.requests.find((request) =>	438	const apiRequest = handle.requests.find((request) =>
439	request.url.startsWith("/drive/v3/files/123"),	439	request.url.startsWith("/drive/v3/files/123"),

packages/plugins/google-discovery/src/sdk/plugin.ts+85−5

@@ -3,6 +3,7 @@ import { Effect, Option, Predicate, Schema } from "effect"; · 2 unmodified lines
3	import {	3	import {
4	ScopeId,	4	ScopeId,
5	SourceDetectionResult,	5	SourceDetectionResult,
		6	ToolResult,
6	Usage,	7	Usage,
7	definePlugin,	8	definePlugin,
8	resolveSecretBackedMap,	9	resolveSecretBackedMap,
@@ -29,6 +30,69 @@ import type { · 20 unmodified lines
29	} from "./types";	30	} from "./types";
30	import { GoogleDiscoveryStoredSourceData as GoogleDiscoveryStoredSourceDataSchema } from "./types";	31	import { GoogleDiscoveryStoredSourceData as GoogleDiscoveryStoredSourceDataSchema } from "./types";
31		32
		33	// ---------------------------------------------------------------------------
		34	// Upstream-error message extraction
		35	// ---------------------------------------------------------------------------
		36
		37	const GOOGLE_BODY_CAP = 1024;
		38	const UpstreamMessageBody = Schema.Struct({ message: Schema.String });
		39	const UpstreamErrorMessageBody = Schema.Struct({ errorMessage: Schema.String });
		40	const UpstreamNestedErrorBody = Schema.Struct({ error: UpstreamMessageBody });
		41	const UpstreamErrorsArrayBody = Schema.Struct({
		42	errors: Schema.Array(
		43	Schema.Struct({
		44	detail: Schema.optional(Schema.String),
		45	message: Schema.optional(Schema.String),
		46	title: Schema.optional(Schema.String),
		47	}),
		48	),
		49	});
		50
		51	const decodeUpstreamMessageBody = Schema.decodeUnknownOption(UpstreamMessageBody);
		52	const decodeUpstreamErrorMessageBody = Schema.decodeUnknownOption(UpstreamErrorMessageBody);
		53	const decodeUpstreamNestedErrorBody = Schema.decodeUnknownOption(UpstreamNestedErrorBody);
		54	const decodeUpstreamErrorsArrayBody = Schema.decodeUnknownOption(UpstreamErrorsArrayBody);
		55
		56	const googleClampedStringify = (value: unknown): string => {
		57	let s: string;
		58	// oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: JSON.stringify may throw on cycles; fall back to String() so the upstream body can still be surfaced as ToolError.details fallback text
		59	try {
		60	s = JSON.stringify(value);
		61	} catch {
		62	s = String(value);
		63	}
		64	return s.length > GOOGLE_BODY_CAP ? `${s.slice(0, GOOGLE_BODY_CAP)}…` : s;
		65	};
		66
		67	const firstNonEmpty = (...values: readonly (string \| undefined)[]): string \| undefined =>
		68	values.find((value) => value !== undefined && value.length > 0);
		69
		70	const googleExtractUpstreamMessage = (body: unknown, status: number): string => {
		71	if (typeof body === "string") {
		72	return body.length > 0 ? body : `Upstream returned HTTP ${status}`;
		73	}
		74	const nested = Option.getOrUndefined(decodeUpstreamNestedErrorBody(body));
		75	const messageBody = Option.getOrUndefined(decodeUpstreamMessageBody(body));
		76	const errorMessageBody = Option.getOrUndefined(decodeUpstreamErrorMessageBody(body));
		77	const errorsBody = Option.getOrUndefined(decodeUpstreamErrorsArrayBody(body));
		78	const arrayMessage = errorsBody?.errors
		79	.map(({ detail, message: upstreamMessage, title }) =>
		80	firstNonEmpty(detail, upstreamMessage, title),
		81	)
		82	.find((message) => message !== undefined);
		83	const message = firstNonEmpty(
		84	nested?.error.message,
		85	messageBody?.message,
		86	errorMessageBody?.errorMessage,
		87	arrayMessage,
		88	);
		89	if (message !== undefined) return message;
		90	if (body !== null && typeof body === "object") {
		91	return googleClampedStringify(body);
		92	}
		93	return `Upstream returned HTTP ${status}`;
		94	};
		95
32	// ---------------------------------------------------------------------------	96	// ---------------------------------------------------------------------------
33	// Public input / output shapes	97	// Public input / output shapes
34	// ---------------------------------------------------------------------------	98	// ---------------------------------------------------------------------------
@@ -381,11 +445,27 @@ export const googleDiscoveryPlugin = definePlugin(() => ({ · 346 unmodified lines
381	extension: makeGoogleDiscoveryPluginExtension,	445	extension: makeGoogleDiscoveryPluginExtension,
382		446
383	invokeTool: ({ ctx, toolRow, args }) =>	447	invokeTool: ({ ctx, toolRow, args }) =>
384	invokeGoogleDiscoveryTool({	448	Effect.gen(function* () {
385	ctx: ctx as PluginCtx<GoogleDiscoveryStore>,	449	const result = yield* invokeGoogleDiscoveryTool({
386	toolId: toolRow.id,	450	ctx: ctx as PluginCtx<GoogleDiscoveryStore>,
387	toolScope: decodeString(toolRow.scope_id),	451	toolId: toolRow.id,
388	args,	452	toolScope: decodeString(toolRow.scope_id),
		453	args,
		454	});
		455	const ok = result.status >= 200 && result.status < 300;
		456	if (!ok) {
		457	return ToolResult.fail({
		458	code: "upstream_http_error",
		459	status: result.status,
		460	message: googleExtractUpstreamMessage(result.error, result.status),
		461	details: result.error,
		462	});
		463	}
		464	return ToolResult.ok({
		465	status: result.status,
		466	headers: result.headers,
		467	data: result.data,
		468	});
389	}),	469	}),
390		470
391	resolveAnnotations: ({ ctx, sourceId, toolRows }) =>	471	resolveAnnotations: ({ ctx, sourceId, toolRows }) =>

packages/plugins/graphql/src/sdk/plugin.test.ts+48−9

 import { describe, it, expect } from "@effect/vitest";
 import { Effect, Predicate } from "effect";
+import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 import {
   ConnectionId,
   SecretId,
   TokenMaterial,
 } from "@executor-js/sdk";
-import { makeTestConfig } from "@executor-js/sdk/testing";
+import { makeTestConfig, serveTestHttpApp } from "@executor-js/sdk/testing";
 import { memorySecretsPlugin } from "@executor-js/sdk/testing";
 import { graphqlPlugin } from "./plugin";
       });
       expect(result).toEqual({
-        status: 200,
+        ok: true,
         data: { hello: "Hello Ada" },
-        errors: null,
       });
       const requests = yield* server.requests;
     }),
   );
+  it.effect("surfaces non-2xx invocation responses as ToolResult.fail", () =>
+    Effect.gen(function* () {
+      const server = yield* serveTestHttpApp((request) =>
+        Effect.gen(function* () {
+          const webRequest = yield* HttpServerRequest.toWeb(request);
+          const body = yield* Effect.promise(() => webRequest.text());
+          if (body.includes("__schema")) {
+            return HttpServerResponse.jsonUnsafe({ data: introspectionResult });
+          }
+          return HttpServerResponse.text("temporary upstream outage", {
+            status: 503,
+            contentType: "text/plain",
+          });
+        }),
+      );
+      const executor = yield* createExecutor(
+        makeTestConfig({ plugins: [graphqlPlugin()] as const }),
+      );
+      yield* executor.graphql.addSource({
+        endpoint: server.url("/graphql"),
+        scope: TEST_SCOPE,
+        namespace: "http_error_graph",
+      });
+      const result = yield* executor.tools.invoke("http_error_graph.query.hello", {
+        name: "Ada",
+      });
+      expect(result).toMatchObject({
+        ok: false,
+        error: {
+          code: "graphql_http_error",
+          status: 503,
+          message: "GraphQL request failed with HTTP 503",
+        },
+      });
+    }),
+  );
   it.effect("invokes OAuth-backed sources with a bearer token", () =>
     Effect.gen(function* () {
       const server = yield* serveGreetingServer;
       });
       expect(result).toEqual({
-        status: 200,
+        ok: true,
         data: { hello: "Hello Ada" },
-        errors: null,
       });
       const requests = yield* server.requests;
         },
         { onElicitation: "accept-all" },
       );
-      expect(result).toEqual({ toolCount: 2, namespace: "via_static" });
+      expect(result).toEqual({ ok: true, data: { toolCount: 2, namespace: "via_static" } });
       expect(yield* executor.graphql.getSource("via_static", String(userScope))).toBeNull();
       expect((yield* executor.graphql.getSource("via_static", String(orgScope)))?.scope).toBe(
         orgScope,
       });
       expect(result).toMatchObject({
-        status: 200,
+        ok: true,
         data: { hello: "Hello Ada" },
       });
       const requests = yield* server.requests;
       });
       expect(result).toMatchObject({
-        status: 200,
+        ok: true,
         data: { hello: "Hello Ada" },
       });
       const requests = yield* server.requests;
         });
         expect(result).toMatchObject({
-          status: 200,
+          ok: true,
           data: { hello: "Hello Ada" },
         });
         const requests = yield* server.requests;

packages/plugins/graphql/src/sdk/plugin.ts+37−2

@@ -12,6 +12,7 @@ import { · 11 unmodified lines
12	SecretId,	12	SecretId,
13	SourceDetectionResult,	13	SourceDetectionResult,
14	StorageError,	14	StorageError,
		15	ToolResult,
15	type PluginCtx,	16	type PluginCtx,
16	type StorageFailure,	17	type StorageFailure,
17	type ToolAnnotations,	18	type ToolAnnotations,
@@ -65,6 +66,19 @@ import { · 47 unmodified lines
65	// Plugin config	66	// Plugin config
66	// ---------------------------------------------------------------------------	67	// ---------------------------------------------------------------------------
67		68
		69	const GraphqlErrorBody = Schema.Struct({ message: Schema.String });
		70	const GraphqlErrorsBody = Schema.Array(Schema.Unknown);
		71	const decodeGraphqlErrorBody = Schema.decodeUnknownOption(GraphqlErrorBody);
		72	const decodeGraphqlErrorsBody = Schema.decodeUnknownOption(GraphqlErrorsBody);
		73
		74	const decodeGraphqlErrors = (errors: unknown): readonly unknown[] \| undefined =>
		75	Option.getOrUndefined(decodeGraphqlErrorsBody(errors));
		76
		77	const extractGraphqlErrorMessage = (errors: readonly unknown[]): string \| undefined =>
		78	errors
		79	.map((error) => Option.getOrUndefined(decodeGraphqlErrorBody(error))?.message)
		80	.find((message) => message !== undefined && message.length > 0);
		81
68	export type HeaderValue = HeaderValueValue;	82	export type HeaderValue = HeaderValueValue;
69	export type GraphqlCredentialValue = ConfiguredGraphqlCredentialValue;	83	export type GraphqlCredentialValue = ConfiguredGraphqlCredentialValue;
70		84
@@ -994,7 +1008,7 @@ export const graphqlPlugin = definePlugin((options?: GraphqlPluginOptions) => { · 923 unmodified lines
994	},	1008	},
995	inputSchema: StaticAddSourceInputStandardSchema,	1009	inputSchema: StaticAddSourceInputStandardSchema,
996	outputSchema: StaticAddSourceOutputStandardSchema,	1010	outputSchema: StaticAddSourceOutputStandardSchema,
997	execute: (input) => self.addSource(input),	1011	execute: (input) => Effect.map(self.addSource(input), ToolResult.ok),
998	}),	1012	}),
999	],	1013	],
1000	},	1014	},
@@ -1057,7 +1071,28 @@ export const graphqlPlugin = definePlugin((options?: GraphqlPluginOptions) => { · 56 unmodified lines
1057	httpClientLayer,	1071	httpClientLayer,
1058	);	1072	);
1059		1073
1060	return result;	1074	const errors = decodeGraphqlErrors(result.errors);
		1075	if (errors !== undefined && errors.length > 0) {
		1076	const firstMessage = extractGraphqlErrorMessage(errors);
		1077	return ToolResult.fail({
		1078	code: "graphql_errors",
		1079	message: firstMessage !== undefined ? firstMessage : "GraphQL request returned errors",
		1080	details: { errors },
		1081	});
		1082	}
		1083	if (result.status < 200 \|\| result.status >= 300) {
		1084	return ToolResult.fail({
		1085	code: "graphql_http_error",
		1086	status: result.status,
		1087	message: `GraphQL request failed with HTTP ${result.status}`,
		1088	details: {
		1089	status: result.status,
		1090	data: result.data,
		1091	errors: result.errors,
		1092	},
		1093	});
		1094	}
		1095	return ToolResult.ok(result.data);
1061	}),	1096	}),
1062		1097
1063	resolveAnnotations: ({ ctx, sourceId, toolRows }) =>	1098	resolveAnnotations: ({ ctx, sourceId, toolRows }) =>

packages/plugins/mcp/src/react/AddMcpSource.tsx+11−16

 const ErrorMessage = Schema.Struct({ message: Schema.String });
 const decodeErrorMessage = Schema.decodeUnknownOption(ErrorMessage);
+const STDIO_ENV_ESCAPE_REPLACEMENTS: Readonly<Record<string, string>> = {
+  "\\": "\\",
+  n: "\n",
+  r: "\r",
+  t: "\t",
+  '"': '"',
+};
 const errorMessageFromExit = (exit: Exit.Exit<unknown, unknown>, fallback: string): string =>
   Option.match(Option.flatMap(Exit.findErrorOption(exit), decodeErrorMessage), {
     const inner = value.slice(1, -1);
     if (quote === "'") return inner;
-    return inner.replace(/\\([\\nrt"])/g, (_, escaped: string) => {
+    return inner.replace(
-      switch (escaped) {
+      /\\([\\nrt"])/g,
-        case "\\":
+      (_, escaped: string) => STDIO_ENV_ESCAPE_REPLACEMENTS[escaped] ?? escaped,
-          return "\\";
+    );
-        case "n":
-          return "\n";
-        case "r":
-          return "\r";
-        case "t":
-          return "\t";
-        case '"':
-          return '"';
-        default:
-          return escaped;
-      }
-    });
   };
   const parseStdioEnv = (raw: string): Record<string, string> | undefined => {

packages/plugins/mcp/src/sdk/elicitation.test.ts+30−3

@@ -69,7 +69,8 @@ describe("MCP elicitation (end-to-end)", () => { · 68 unmodified lines
69	const result = yield* executor.tools.invoke(gatedEcho!.id, { value: "hello" }, options);	69	const result = yield* executor.tools.invoke(gatedEcho!.id, { value: "hello" }, options);
70		70
71	expect(result).toMatchObject({	71	expect(result).toMatchObject({
72	content: [{ type: "text", text: "approved:hello" }],	72	ok: true,
		73	data: { content: [{ type: "text", text: "approved:hello" }] },
73	});	74	});
74	// At least one elicitation should be the MCP server's form	75	// At least one elicitation should be the MCP server's form
75	expect(elicitationMessages.length).toBeGreaterThanOrEqual(1);	76	expect(elicitationMessages.length).toBeGreaterThanOrEqual(1);
@@ -95,7 +96,8 @@ describe("MCP elicitation (end-to-end)", () => { · 19 unmodified lines
95	);	96	);
96		97
97	expect(result).toMatchObject({	98	expect(result).toMatchObject({
98	content: [{ type: "text", text: "denied:nope" }],	99	ok: true,
		100	data: { content: [{ type: "text", text: "denied:nope" }] },
99	});	101	});
100	}),	102	}),
101	);	103	);
@@ -114,7 +116,32 @@ describe("MCP elicitation (end-to-end)", () => { · 12 unmodified lines
114	);	116	);
115		117
116	expect(result).toMatchObject({	118	expect(result).toMatchObject({
117	content: [{ type: "text", text: "plain" }],	119	ok: true,
		120	data: { content: [{ type: "text", text: "plain" }] },
		121	});
		122	}),
		123	);
		124
		125	it.effect("successful tool invocation preserves structured MCP result fields", () =>
		126	Effect.gen(function* () {
		127	const server = yield* serveElicitationTestServer;
		128	const executor = yield* makeTestExecutor(server.url);
		129	const tools = yield* executor.tools.list();
		130	const structuredEcho = tools.find((t) => t.name === "structured_echo")!;
		131
		132	const result = yield* executor.tools.invoke(
		133	structuredEcho.id,
		134	{ value: "plain" },
		135	{ onElicitation: "accept-all" },
		136	);
		137
		138	expect(result).toMatchObject({
		139	ok: true,
		140	data: {
		141	content: [{ type: "text", text: "plain" }],
		142	structuredContent: { value: "plain", upper: "PLAIN" },
		143	_meta: { trace: "kept" },
		144	},
118	});	145	});
119	}),	146	}),
120	);	147	);

packages/plugins/mcp/src/sdk/per-user-auth-isolation.test.ts+6−3

           { onElicitation: "accept-all" },
         );
         expect(userAResult).toMatchObject({
-          content: [{ type: "text", text: "ok:from-user-a" }],
+          ok: true,
+          data: { content: [{ type: "text", text: "ok:from-user-a" }] },
         });
         expect(
           (yield* server.requests)
         { onElicitation: "accept-all" },
       );
       expect(userAResult).toMatchObject({
-        content: [{ type: "text", text: "ok:user-a-header" }],
+        ok: true,
+        data: { content: [{ type: "text", text: "ok:user-a-header" }] },
       });
       expect(
         (yield* server.requests)
       );
       expect(result).toMatchObject({
-        content: [{ type: "text", text: "ok:org-header" }],
+        ok: true,
+        data: { content: [{ type: "text", text: "ok:org-header" }] },
       });
       const invokeRequests = (yield* server.requests).slice(beforeInvoke);
       expect(

packages/plugins/mcp/src/sdk/plugin.ts+31−1

   Predicate,
   Result,
   Scope,
+  Schema,
   ScopedCache,
 } from "effect";
 import type { HttpClient } from "effect/unstable/http";
   ScopeId,
   SecretId,
   SourceDetectionResult,
+  ToolResult,
   definePlugin,
   resolveSecretBackedMap as resolveSharedSecretBackedMap,
   type PluginCtx,
   });
 const MCP_PLUGIN_ID = "mcp";
+const McpTextContent = Schema.Struct({ type: Schema.Literal("text"), text: Schema.String });
+const McpToolCallEnvelope = Schema.Struct({
+  isError: Schema.optional(Schema.Boolean),
+  content: Schema.optional(Schema.Array(Schema.Unknown)),
+});
+const decodeMcpTextContent = Schema.decodeUnknownOption(McpTextContent);
+const decodeMcpToolCallEnvelope = Schema.decodeUnknownOption(McpToolCallEnvelope);
+const extractMcpErrorMessage = (content: unknown): string => {
+  if (Array.isArray(content)) {
+    for (const item of content) {
+      const decoded = Option.getOrUndefined(decodeMcpTextContent(item));
+      if (decoded !== undefined && decoded.text.length > 0) return decoded.text;
+    }
+  }
+  return "MCP tool returned an error";
+};
 /** Match `token` as a separator-bounded run inside a URL hostname or path,
  *  used as a low-confidence detection hint when wire-shape detection fails.
           });
         }
-        return yield* invokeMcpTool({
+        const raw = yield* invokeMcpTool({
           toolId: toolRow.id,
           toolName: entry.binding.toolName,
           args,
           pendingConnectors: runtime.pendingConnectors,
           elicit,
         });
+        const envelope = Option.getOrUndefined(decodeMcpToolCallEnvelope(raw));
+        if (envelope?.isError === true) {
+          return ToolResult.fail({
+            code: "mcp_tool_error",
+            message: extractMcpErrorMessage(envelope.content),
+            details: { content: envelope.content },
+          });
+        }
+        return ToolResult.ok(raw);
       }).pipe(
         Effect.withSpan("mcp.plugin.invoke_tool", {
           attributes: {

packages/plugins/mcp/src/testing/server.ts+17−0

@@ -375,6 +375,23 @@ export const makeElicitationMcpServer = () => { · 374 unmodified lines
375	}),	375	}),
376	);	376	);
377		377
		378	server.registerTool(
		379	"structured_echo",
		380	{
		381	description: "Returns text plus structured data",
		382	inputSchema: { value: z.string() },
		383	outputSchema: {
		384	value: z.string(),
		385	upper: z.string(),
		386	},
		387	},
		388	async ({ value }: { value: string }) => ({
		389	content: [{ type: "text" as const, text: value }],
		390	structuredContent: { value, upper: value.toUpperCase() },
		391	_meta: { trace: "kept" },
		392	}),
		393	);
		394
378	return server;	395	return server;
379	};	396	};
380		397

packages/plugins/openapi/src/sdk/client-credentials-oauth.test.ts+10−13

 import {
   addOpenApiTestSource,
   serveOpenApiHttpApiTestServer,
+  unwrapInvocation,
 } from "@executor-js/plugin-openapi/testing";
 import { openApiPlugin } from "./plugin";
       );
       // Invoking the tool injects the freshly-minted bearer via
       // ctx.connections.accessToken.
-      const result = (yield* userExec.tools.invoke(
+      const result = unwrapInvocation(
-        "petstore.items.echoHeaders",
+        yield* userExec.tools.invoke("petstore.items.echoHeaders", {}, autoApprove),
-        {},
+      );
-        autoApprove,
-      )) as {
-        data: { authorization?: string } | null;
-        error: unknown;
-      };
       expect(result.error).toBeNull();
-      const bearer = result.data?.authorization?.replace(/^Bearer\s+/i, "");
+      const data = result.data as EchoHeaders | null;
+      const bearer = data?.authorization?.replace(/^Bearer\s+/i, "");
       expect(bearer).toBeDefined();
       expect(yield* oauth.acceptsAccessToken(bearer!)).toBe(true);
       // The connection lives at the innermost (user) scope, which
       // preserves per-user credential resolution: if each user has
-      // their own `dealcloud_client_id`/`dealcloud_client_secret`
+      // their own OAuth client credentials shadowed at their user
-      // shadowed at their user scope, each user mints their own
+      // scope, each user mints their own token. A single shared
-      // token. A single shared connection slot still lets every caller
+      // connection slot still lets every caller reach the right
-      // reach the right physical row through scoped credential bindings.
+      // physical row through scoped credential bindings.
       const userConnections = yield* userExec.connections.list();
       const connection = userConnections.find((c) => c.id === completedConnection.connectionId);
       expect(connection).toBeDefined();

packages/plugins/openapi/src/sdk/multi-scope-bearer.test.ts+49−60

   addOpenApiTestSource,
   makeOpenApiTestSourceConfig,
   serveOpenApiHttpApiTestServer,
+  unwrapInvocation,
 } from "@executor-js/plugin-openapi/testing";
 import { openApiPlugin } from "./plugin";
       //    yields her token; bob's scope yields his. Same source, same
       //    tool, different injected bearer.
       // -------------------------------------------------------------
-      const aliceResult = (yield* aliceExec.tools.invoke(
+      const aliceResult = unwrapInvocation(
-        "vercel.projects.list",
+        yield* aliceExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-        {},
+      );
-        autoApprove,
-      )) as {
-        data: { authorization?: string; token?: string } | null;
-        error: unknown;
-      };
       expect(aliceResult.error).toBeNull();
-      expect(aliceResult.data?.authorization).toBe("Bearer alice-vercel-token");
+      const aliceData = aliceResult.data as EchoHeaders | null;
-      expect(aliceResult.data?.token).toBe("alice-team");
+      expect(aliceData?.authorization).toBe("Bearer alice-vercel-token");
+      expect(aliceData?.token).toBe("alice-team");
-      const bobResult = (yield* bobExec.tools.invoke("vercel.projects.list", {}, autoApprove)) as {
+      const bobResult = unwrapInvocation(
-        data: { authorization?: string; token?: string } | null;
+        yield* bobExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-        error: unknown;
+      );
-      };
       expect(bobResult.error).toBeNull();
-      expect(bobResult.data?.authorization).toBe("Bearer bob-vercel-token");
+      const bobData = bobResult.data as EchoHeaders | null;
-      expect(bobResult.data?.token).toBe("bob-team");
+      expect(bobData?.authorization).toBe("Bearer bob-vercel-token");
+      expect(bobData?.token).toBe("bob-team");
       // -------------------------------------------------------------
       // 5. Scope attribution: each user's token is pinned to their
         }),
       );
-      const aliceResult = (yield* aliceExec.tools.invoke(
+      const aliceResult = unwrapInvocation(
-        "vercel.projects.list",
+        yield* aliceExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-        {},
+      );
-        autoApprove,
-      )) as { data: { authorization?: string } | null; error: unknown };
       expect(aliceResult.error).toBeNull();
-      expect(aliceResult.data?.authorization).toBe("Bearer alice-vercel-token");
+      expect((aliceResult.data as EchoHeaders | null)?.authorization).toBe(
+        "Bearer alice-vercel-token",
+      );
-      const bobResult = (yield* bobExec.tools.invoke("vercel.projects.list", {}, autoApprove)) as {
+      const bobResult = unwrapInvocation(
-        data: { authorization?: string } | null;
+        yield* bobExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-        error: unknown;
+      );
-      };
       expect(bobResult.error).toBeNull();
-      expect(bobResult.data?.authorization).toBe("Bearer bob-vercel-token");
+      expect((bobResult.data as EchoHeaders | null)?.authorization).toBe("Bearer bob-vercel-token");
     }),
   );
           }),
         );
-        const sharedResult = (yield* aliceExec.tools.invoke(
+        const sharedResult = unwrapInvocation(
-          "vercel.projects.list",
+          yield* aliceExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-          {},
+        );
-          autoApprove,
-        )) as { data: { authorization?: string } | null; error: unknown };
         expect(sharedResult.error).toBeNull();
-        expect(sharedResult.data?.authorization).toBe("Bearer org-token");
+        expect((sharedResult.data as EchoHeaders | null)?.authorization).toBe("Bearer org-token");
         yield* aliceExec.secrets.set(
           SetSecretInput.make({
           }),
         );
-        const overrideResult = (yield* aliceExec.tools.invoke(
+        const overrideResult = unwrapInvocation(
-          "vercel.projects.list",
+          yield* aliceExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-          {},
+        );
-          autoApprove,
-        )) as { data: { authorization?: string } | null; error: unknown };
         expect(overrideResult.error).toBeNull();
-        expect(overrideResult.data?.authorization).toBe("Bearer alice-token");
+        expect((overrideResult.data as EchoHeaders | null)?.authorization).toBe(
+          "Bearer alice-token",
+        );
         yield* aliceExec.openapi.removeSourceBinding(
           "vercel",
           String(aliceScope.id),
         );
-        const fallbackResult = (yield* aliceExec.tools.invoke(
+        const fallbackResult = unwrapInvocation(
-          "vercel.projects.list",
+          yield* aliceExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-          {},
+        );
-          autoApprove,
-        )) as { data: { authorization?: string } | null; error: unknown };
         expect(fallbackResult.error).toBeNull();
-        expect(fallbackResult.data?.authorization).toBe("Bearer org-token");
+        expect((fallbackResult.data as EchoHeaders | null)?.authorization).toBe("Bearer org-token");
         yield* aliceExec.openapi.setSourceBinding(
           OpenApiSourceBindingInput.make({
           }),
         );
-        const result = (yield* aliceExec.tools.invoke("vercel.projects.list", {}, autoApprove)) as {
+        const result = unwrapInvocation(
-          data: { authorization?: string } | null;
+          yield* aliceExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-          error: unknown;
+        );
-        };
         expect(result.error).toBeNull();
-        expect(result.data?.authorization).toBe("Bearer alice-token");
+        expect((result.data as EchoHeaders | null)?.authorization).toBe("Bearer alice-token");
       }),
   );
         }),
       );
-      const result = (yield* userExec.tools.invoke("vercel.projects.list", {}, autoApprove)) as {
+      const result = unwrapInvocation(
-        data: { authorization?: string } | null;
+        yield* userExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-        error: unknown;
+      );
-      };
       expect(result.error).toBeNull();
-      expect(result.data?.authorization).toBe("Bearer org-token");
+      expect((result.data as EchoHeaders | null)?.authorization).toBe("Bearer org-token");
     }),
   );
         }),
       );
-      const result = (yield* userExec.tools.invoke("vercel.projects.list", {}, autoApprove)) as {
+      const result = unwrapInvocation(
-        data: { authorization?: string } | null;
+        yield* userExec.tools.invoke("vercel.projects.list", {}, autoApprove),
-        error: unknown;
+      );
-      };
       expect(result.error).toBeNull();
-      expect(result.data?.authorization).toBe("Bearer org-choice");
+      expect((result.data as EchoHeaders | null)?.authorization).toBe("Bearer org-choice");
     }),
   );
 });

packages/plugins/openapi/src/sdk/multi-scope-oauth.test.ts+29−24

 import {
   addOpenApiTestSource,
   serveOpenApiHttpApiTestServer,
+  unwrapInvocation,
 } from "@executor-js/plugin-openapi/testing";
 import { openApiPlugin } from "./plugin";
       // 4. Invoke through each exec — Authorization must carry that
       //    user's token.
       // -------------------------------------------------------------
-      const aliceResult = (yield* aliceExec.tools.invoke(
+      const aliceResult = unwrapInvocation(
-        "petstore.items.echoHeaders",
+        yield* aliceExec.tools.invoke("petstore.items.echoHeaders", {}, autoApprove),
-        {},
+      );
-        autoApprove,
-      )) as { data: { authorization?: string } | null; error: unknown };
       expect(aliceResult.error).toBeNull();
-      const aliceBearer = aliceResult.data?.authorization?.replace(/^Bearer\s+/i, "");
+      const aliceBearer = (aliceResult.data as EchoHeaders | null)?.authorization?.replace(
+        /^Bearer\s+/i,
+        "",
+      );
       expect(aliceBearer).toBeDefined();
       expect(yield* oauth.acceptsAccessToken(aliceBearer!)).toBe(true);
-      const bobResult = (yield* bobExec.tools.invoke(
+      const bobResult = unwrapInvocation(
-        "petstore.items.echoHeaders",
+        yield* bobExec.tools.invoke("petstore.items.echoHeaders", {}, autoApprove),
-        {},
+      );
-        autoApprove,
-      )) as { data: { authorization?: string } | null; error: unknown };
       expect(bobResult.error).toBeNull();
-      const bobBearer = bobResult.data?.authorization?.replace(/^Bearer\s+/i, "");
+      const bobBearer = (bobResult.data as EchoHeaders | null)?.authorization?.replace(
+        /^Bearer\s+/i,
+        "",
+      );
       expect(bobBearer).toBeDefined();
       expect(yield* oauth.acceptsAccessToken(bobBearer!)).toBe(true);
       expect(bobBearer).not.toBe(aliceBearer);
       // (4) Each user's invocation resolves their OWN row and gets
       // their OWN token — not whatever the last signer happened to
       // mint. This is the core multi-user regression.
-      const aliceResult = (yield* aliceExec.tools.invoke(
+      const aliceResult = unwrapInvocation(
-        "petstore.items.echoHeaders",
+        yield* aliceExec.tools.invoke("petstore.items.echoHeaders", {}, autoApprove),
-        {},
+      );
-        autoApprove,
-      )) as { data: { authorization?: string } | null; error: unknown };
       expect(aliceResult.error).toBeNull();
-      const aliceBearer = aliceResult.data?.authorization?.replace(/^Bearer\s+/i, "");
+      const aliceBearer = (aliceResult.data as EchoHeaders | null)?.authorization?.replace(
+        /^Bearer\s+/i,
+        "",
+      );
       expect(aliceBearer).toBeDefined();
       expect(yield* oauth.acceptsAccessToken(aliceBearer!)).toBe(true);
-      const bobResult = (yield* bobExec.tools.invoke(
+      const bobResult = unwrapInvocation(
-        "petstore.items.echoHeaders",
+        yield* bobExec.tools.invoke("petstore.items.echoHeaders", {}, autoApprove),
-        {},
+      );
-        autoApprove,
-      )) as { data: { authorization?: string } | null; error: unknown };
       expect(bobResult.error).toBeNull();
-      const bobBearer = bobResult.data?.authorization?.replace(/^Bearer\s+/i, "");
+      const bobBearer = (bobResult.data as EchoHeaders | null)?.authorization?.replace(
+        /^Bearer\s+/i,
+        "",
+      );
       expect(bobBearer).toBeDefined();
       expect(yield* oauth.acceptsAccessToken(bobBearer!)).toBe(true);
       expect(bobBearer).not.toBe(aliceBearer);

packages/plugins/openapi/src/sdk/oauth-refresh.test.ts+9−12

 import {
   addOpenApiTestSource,
   serveOpenApiHttpApiTestServer,
+  unwrapInvocation,
 } from "@executor-js/plugin-openapi/testing";
 import { openApiPlugin } from "./plugin";
       });
       yield* bindOAuthConnection(executor, scopeId, "conn-refresh-ok", auth);
-      const result = (yield* executor.tools.invoke(
+      const result = unwrapInvocation(
-        "petstore.items.echoHeaders",
+        yield* executor.tools.invoke("petstore.items.echoHeaders", {}, autoApprove),
-        {},
+      );
-        autoApprove,
-      )) as { data: { authorization?: string } | null; error: unknown };
       expect(result.error).toBeNull();
+      const data = result.data as EchoHeaders | null;
       // Proves the refresh landed: invoke carried the fresh token,
       // not the expired one we seeded.
-      expect(result.data?.authorization).not.toBe("Bearer expired-access-v1");
+      expect(data?.authorization).not.toBe("Bearer expired-access-v1");
-      const bearer = result.data?.authorization?.replace(/^Bearer\s+/i, "");
+      const bearer = data?.authorization?.replace(/^Bearer\s+/i, "");
       expect(bearer).toBeDefined();
       expect(yield* oauth.acceptsAccessToken(bearer!)).toBe(true);
       const calls = refreshTokenRequests(yield* oauth.requests);
       );
       for (const r of invokes) {
-        const res = r as {
+        const res = unwrapInvocation(r);
-          data: { authorization?: string } | null;
-          error: unknown;
-        };
         expect(res.error).toBeNull();
-        const bearer = res.data?.authorization?.replace(/^Bearer\s+/i, "");
+        const bearer = (res.data as EchoHeaders | null)?.authorization?.replace(/^Bearer\s+/i, "");
         expect(bearer).toBeDefined();
         expect(yield* oauth.acceptsAccessToken(bearer!)).toBe(true);
       }

packages/plugins/openapi/src/sdk/plugin.test.ts+38−39

   addOpenApiTestSource,
   makeOpenApiHttpApiTestSourceConfig,
   serveOpenApiHttpApiTestServer,
+  unwrapInvocation,
 } from "../testing";
 const autoApprove: InvokeOptions = { onElicitation: "accept-all" };
         }),
       );
-      const result = (yield* executor.tools.invoke(
+      const preview = unwrapInvocation(
-        "executor.openapi.previewSpec",
+        yield* executor.tools.invoke(
-        { spec: testApiSpec() },
+          "executor.openapi.previewSpec",
-        autoApprove,
+          { spec: testApiSpec() },
-      )) as { operationCount: number };
+          autoApprove,
+        ),
+      ).data as { operationCount: number };
-      expect(result.operationCount).toBeGreaterThanOrEqual(2);
+      expect(preview.operationCount).toBeGreaterThanOrEqual(2);
     }),
   );
         }),
       );
-      const result = (yield* executor.tools.invoke(
+      const result = unwrapInvocation(
-        "executor.openapi.addSource",
+        yield* executor.tools.invoke(
-        testApiSourceConfig({ scope: String(orgScope), namespace: "runtime" }),
+          "executor.openapi.addSource",
-        autoApprove,
+          testApiSourceConfig({ scope: String(orgScope), namespace: "runtime" }),
-      )) as { sourceId: string; toolCount: number };
+          autoApprove,
+        ),
+      ).data as { sourceId: string; toolCount: number };
       expect(result).toEqual({ sourceId: "runtime", toolCount: 4 });
       expect(yield* executor.openapi.getSource("runtime", String(userScope))).toBeNull();
           },
         });
-        const result = (yield* executor.tools.invoke(
+        const result = unwrapInvocation(
-          "authed.items.echoHeaders",
+          yield* executor.tools.invoke("authed.items.echoHeaders", {}, autoApprove),
-          {},
+        );
-          autoApprove,
-        )) as {
-          data: { authorization?: string; "x-static"?: string } | null;
-          error: unknown;
-        };
         expect(result.error).toBeNull();
-        const data = result.data!;
+        const data = result.data as { authorization?: string; "x-static"?: string };
         expect(data.authorization).toBe("Bearer secret-value-123");
         expect(data["x-static"]).toBe("hello");
       }),
           namespace: "test",
         });
-        const result = (yield* executor.tools.invoke("test.items.listItems", {}, autoApprove)) as {
+        const result = unwrapInvocation(
-          data: unknown;
+          yield* executor.tools.invoke("test.items.listItems", {}, autoApprove),
-          error: unknown;
+        );
-        };
         expect(result.error).toBeNull();
         expect(result.data).toEqual(ITEMS);
       }),
           namespace: "test",
         });
-        const result = (yield* executor.tools.invoke(
+        const result = unwrapInvocation(
-          "test.items.getItem",
+          yield* executor.tools.invoke("test.items.getItem", { itemId: "2" }, autoApprove),
-          { itemId: "2" },
+        );
-          autoApprove,
-        )) as { data: unknown; error: unknown };
         expect(result.error).toBeNull();
         expect(result.data).toEqual({ id: 2, name: "Gadget" });
       }),
           namespace: "records",
         });
-        const result = (yield* executor.tools.invoke(
+        const result = unwrapInvocation(
-          "records.items.queryRows",
+          yield* executor.tools.invoke(
-          {
+            "records.items.queryRows",
-            entryTypeId: "18538",
+            {
-            query: JSON.stringify([{ DisplayName: "Example" }]),
+              entryTypeId: "18538",
-            limit: 10,
+              query: JSON.stringify([{ DisplayName: "Example" }]),
-            skip: 0,
+              limit: 10,
-          },
+              skip: 0,
-          autoApprove,
+            },
-        )) as { data: unknown; error: unknown };
+            autoApprove,
+          ),
+        );
         expect(result.data).toBeNull();
         expect(result.error).toEqual(

packages/plugins/openapi/src/sdk/plugin.ts+88−3

@@ -7,6 +7,7 @@ import { · 6 unmodified lines
7	SecretId,	7	SecretId,
8	SourceDetectionResult,	8	SourceDetectionResult,
9	StorageError,	9	StorageError,
		10	ToolResult,
10	definePlugin,	11	definePlugin,
11	tool,	12	tool,
12	resolveSecretBackedMap,	13	resolveSecretBackedMap,
@@ -57,6 +58,77 @@ import { · 44 unmodified lines
57	// Plugin config	58	// Plugin config
58	// ---------------------------------------------------------------------------	59	// ---------------------------------------------------------------------------
59		60
		61	const STRINGIFIED_BODY_CAP = 1024;
		62	const UpstreamMessageBody = Schema.Struct({ message: Schema.String });
		63	const UpstreamErrorMessageBody = Schema.Struct({ errorMessage: Schema.String });
		64	const UpstreamNestedErrorBody = Schema.Struct({ error: UpstreamMessageBody });
		65	const UpstreamErrorsArrayBody = Schema.Struct({
		66	errors: Schema.Array(
		67	Schema.Struct({
		68	detail: Schema.optional(Schema.String),
		69	message: Schema.optional(Schema.String),
		70	title: Schema.optional(Schema.String),
		71	}),
		72	),
		73	});
		74	const UpstreamDescriptionBody = Schema.Struct({
		75	detail: Schema.optional(Schema.String),
		76	title: Schema.optional(Schema.String),
		77	description: Schema.optional(Schema.String),
		78	});
		79
		80	const decodeUpstreamMessageBody = Schema.decodeUnknownOption(UpstreamMessageBody);
		81	const decodeUpstreamErrorMessageBody = Schema.decodeUnknownOption(UpstreamErrorMessageBody);
		82	const decodeUpstreamNestedErrorBody = Schema.decodeUnknownOption(UpstreamNestedErrorBody);
		83	const decodeUpstreamErrorsArrayBody = Schema.decodeUnknownOption(UpstreamErrorsArrayBody);
		84	const decodeUpstreamDescriptionBody = Schema.decodeUnknownOption(UpstreamDescriptionBody);
		85
		86	const clampedStringify = (value: unknown): string => {
		87	let s: string;
		88	// oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: JSON.stringify may throw on cycles; fall back to String() so the upstream body can still be surfaced as ToolError.details fallback text
		89	try {
		90	s = JSON.stringify(value);
		91	} catch {
		92	s = String(value);
		93	}
		94	return s.length > STRINGIFIED_BODY_CAP ? `${s.slice(0, STRINGIFIED_BODY_CAP)}…` : s;
		95	};
		96
		97	const firstNonEmpty = (...values: readonly (string \| undefined)[]): string \| undefined =>
		98	values.find((value) => value !== undefined && value.length > 0);
		99
		100	// Walk known upstream error-body shapes so ToolError.message stays concise
		101	// while ToolError.details preserves the original body.
		102	const extractUpstreamMessage = (body: unknown, status: number): string => {
		103	if (typeof body === "string") {
		104	return body.length > 0 ? body : `Upstream returned HTTP ${status}`;
		105	}
		106	const nested = Option.getOrUndefined(decodeUpstreamNestedErrorBody(body));
		107	const messageBody = Option.getOrUndefined(decodeUpstreamMessageBody(body));
		108	const errorMessageBody = Option.getOrUndefined(decodeUpstreamErrorMessageBody(body));
		109	const errorsBody = Option.getOrUndefined(decodeUpstreamErrorsArrayBody(body));
		110	const descriptionBody = Option.getOrUndefined(decodeUpstreamDescriptionBody(body));
		111	const arrayMessage = errorsBody?.errors
		112	.map(({ detail, message: upstreamMessage, title }) =>
		113	firstNonEmpty(detail, upstreamMessage, title),
		114	)
		115	.find((message) => message !== undefined);
		116	const message = firstNonEmpty(
		117	nested?.error.message,
		118	messageBody?.message,
		119	errorMessageBody?.errorMessage,
		120	arrayMessage,
		121	descriptionBody?.detail,
		122	descriptionBody?.title,
		123	descriptionBody?.description,
		124	);
		125	if (message !== undefined) return message;
		126	if (body !== null && typeof body === "object") {
		127	return clampedStringify(body);
		128	}
		129	return `Upstream returned HTTP ${status}`;
		130	};
		131
60	export type HeaderValue = HeaderValueValue;	132	export type HeaderValue = HeaderValueValue;
61	export type ConfiguredHeaderValue = ConfiguredHeaderValueValue;	133	export type ConfiguredHeaderValue = ConfiguredHeaderValueValue;
62	export type OpenApiHeaderInput = HeaderValue \| ConfiguredHeaderValue;	134	export type OpenApiHeaderInput = HeaderValue \| ConfiguredHeaderValue;
@@ -1193,7 +1265,7 @@ export const openApiPlugin = definePlugin((options?: OpenApiPluginOptions) => { · 1130 unmodified lines
1193	name: "previewSpec",	1265	name: "previewSpec",
1194	description: "Preview an OpenAPI document before adding it as a source",	1266	description: "Preview an OpenAPI document before adding it as a source",
1195	inputSchema: PreviewSpecInputStandardSchema,	1267	inputSchema: PreviewSpecInputStandardSchema,
1196	execute: (input) => self.previewSpec(input),	1268	execute: (input) => Effect.map(self.previewSpec(input), ToolResult.ok),
1197	}),	1269	}),
1198	tool({	1270	tool({
1199	name: "addSource",	1271	name: "addSource",
@@ -1204,7 +1276,7 @@ export const openApiPlugin = definePlugin((options?: OpenApiPluginOptions) => { · 4 unmodified lines
1204	},	1276	},
1205	inputSchema: AddSourceInputStandardSchema,	1277	inputSchema: AddSourceInputStandardSchema,
1206	outputSchema: AddSourceOutputStandardSchema,	1278	outputSchema: AddSourceOutputStandardSchema,
1207	execute: (input) => self.addSpec(input),	1279	execute: (input) => Effect.map(self.addSpec(input), ToolResult.ok),
1208	}),	1280	}),
1209	],	1281	],
1210	},	1282	},
@@ -1283,7 +1355,20 @@ export const openApiPlugin = definePlugin((options?: OpenApiPluginOptions) => { · 72 unmodified lines
1283	httpClientLayer,	1355	httpClientLayer,
1284	);	1356	);
1285		1357
1286	return result;	1358	const ok = result.status >= 200 && result.status < 300;
		1359	if (!ok) {
		1360	return ToolResult.fail({
		1361	code: "upstream_http_error",
		1362	status: result.status,
		1363	message: extractUpstreamMessage(result.error, result.status),
		1364	details: result.error,
		1365	});
		1366	}
		1367	return ToolResult.ok({
		1368	status: result.status,
		1369	headers: result.headers,
		1370	data: result.data,
		1371	});
1287	}),	1372	}),
1288		1373
1289	resolveAnnotations: ({ ctx, sourceId, toolRows }) =>	1374	resolveAnnotations: ({ ctx, sourceId, toolRows }) =>

packages/plugins/openapi/src/sdk/upstream-failures.test.ts+5−4

   makeOpenApiTestSourceConfig,
   type OpenApiTestServerShape,
   serveOpenApiHttpApiTestServer,
+  unwrapInvocation,
 } from "../testing";
 import { openApiPlugin } from "./plugin";
       const { baseUrl } = yield* slowServer;
       const executor = yield* buildExecutor(baseUrl);
-      const result = yield* executor.tools.invoke("f.things.listThings", {}, autoApprove);
+      const result = unwrapInvocation(
-      // Empty array via .data envelope or directly — accept either shape.
+        yield* executor.tools.invoke("f.things.listThings", {}, autoApprove),
-      const data = (result as { data?: unknown }).data ?? result;
+      );
-      expect(data).toEqual([]);
+      expect(result.data).toEqual([]);
     }),
   );
 });

packages/plugins/openapi/src/testing/index.ts+54−2

@@ -1,4 +1,4 @@
1	import { Context, Data, Effect, Layer, Predicate, Ref, Schema, Scope } from "effect";	1	import { Context, Data, Effect, Layer, Option, Predicate, Ref, Schema, Scope } from "effect";
2	import {	2	import {
3	HttpClient,	3	HttpClient,
4	HttpRouter,	4	HttpRouter,
@@ -13,7 +13,7 @@ import { · 8 unmodified lines
13	OpenApi,	13	OpenApi,
14	} from "effect/unstable/httpapi";	14	} from "effect/unstable/httpapi";
15	import { OAuthTestServer, serveTestHttpServerLayer } from "@executor-js/sdk/testing";	15	import { OAuthTestServer, serveTestHttpServerLayer } from "@executor-js/sdk/testing";
16	import type { ScopeId } from "@executor-js/sdk/core";	16	import { isToolResult, type ScopeId } from "@executor-js/sdk/core";
17	import type { OpenApiPluginExtension, OpenApiSpecConfig } from "../sdk/plugin";	17	import type { OpenApiPluginExtension, OpenApiSpecConfig } from "../sdk/plugin";
18		18
19	export class OpenApiTestServerAddressError extends Data.TaggedError(	19	export class OpenApiTestServerAddressError extends Data.TaggedError(
@@ -618,3 +618,55 @@ export const TestLayers = { · 598 unmodified lines
618	echo: OpenApiEchoTestServer.layer,	618	echo: OpenApiEchoTestServer.layer,
619	echoWithOAuth: OpenApiEchoTestServer.layerWithOAuth,	619	echoWithOAuth: OpenApiEchoTestServer.layerWithOAuth,
620	};	620	};
		621
		622	const OpenApiTransportEnvelope = Schema.Struct({
		623	status: Schema.Number,
		624	headers: Schema.Record(Schema.String, Schema.String),
		625	data: Schema.Unknown,
		626	});
		627
		628	const decodeOpenApiTransportEnvelope = Schema.decodeUnknownOption(OpenApiTransportEnvelope);
		629
		630	export interface OpenApiInvocationResult<TData = Record<string, unknown> \| unknown[] \| null> {
		631	readonly status: number \| null;
		632	readonly headers: Record<string, string> \| null;
		633	readonly data: TData;
		634	readonly error: unknown;
		635	}
		636
		637	export const unwrapInvocation = <TData = Record<string, unknown> \| null>(
		638	raw: unknown,
		639	): OpenApiInvocationResult<TData> => {
		640	if (!isToolResult(raw)) {
		641	return {
		642	status: null,
		643	headers: null,
		644	data: raw as TData,
		645	error: null,
		646	};
		647	}
		648	if (raw.ok) {
		649	const inner = raw.data;
		650	const wrapped = Option.getOrUndefined(decodeOpenApiTransportEnvelope(inner));
		651	if (wrapped !== undefined) {
		652	return {
		653	status: wrapped.status,
		654	headers: wrapped.headers,
		655	data: wrapped.data as TData,
		656	error: null,
		657	};
		658	}
		659	return {
		660	status: null,
		661	headers: null,
		662	data: inner as TData,
		663	error: null,
		664	};
		665	}
		666	return {
		667	status: raw.error.status ?? null,
		668	headers: null,
		669	data: null as TData,
		670	error: raw.error.details ?? raw.error,
		671	};
		672	};

packages/plugins/workos-vault/src/sdk/secret-store.test.ts+1−1

@@ -256,7 +256,7 @@ describe("WorkOS Vault secret provider", () => { · 255 unmodified lines
256	const client = makeFakeClient({ rejectReadNamesLongerThan: 80 });	256	const client = makeFakeClient({ rejectReadNamesLongerThan: 80 });
257	const executor = yield* makeExecutor(client);	257	const executor = yield* makeExecutor(client);
258	const longSecretId = SecretId.make(	258	const longSecretId = SecretId.make(
259	"openapi-oauth-dealcloud-api-oauth2-user-org-user-01kp6xm1zpvqvtpj77f0yv4eax.access_token",	259	"openapi-oauth-example-api-oauth2-user-org-user-01kp6xm1zpvqvtpj77f0yv4eax.access_token",
260	);	260	);
261		261
262	yield* executor.secrets.set(	262	yield* executor.secrets.set(

Route tool defects opaquely; remove legacy envelope shim (#826)

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code

@@ -1,6 +1,6 @@
1	// Reproduces the PR 706 bug class using Effect-native primitives only —	1	// Covers the Option JSON boundary using Effect-native primitives only:
2	// no JSON.parse, no JSON.stringify, no node:fs on our side. We split the	2	// no JSON.parse, no JSON.stringify, no node:fs on our side. We split the
3	// JSON boundary into two Effect schema steps:	3	// boundary into two Effect schema steps:
4	//	4	//
5	// 1. Schema.encodeEffect(Inner)(value) → encoded JS shape	5	// 1. Schema.encodeEffect(Inner)(value) → encoded JS shape
6	// 2. Schema.encodeEffect(UnknownFromJsonString) → JSON string	6	// 2. Schema.encodeEffect(UnknownFromJsonString) → JSON string
@@ -13,7 +13,7 @@ · 6 unmodified lines
13	// step 2's JSON-stringify (driven by Effect, not us) flattens the Option	13	// step 2's JSON-stringify (driven by Effect, not us) flattens the Option
14	// to {_id,_tag,value}, and step 5 rejects the shape.	14	// to {_id,_tag,value}, and step 5 rejects the shape.
15	//	15	//
16	// Run: vitest run packages/plugins/google-discovery/src/sdk/option-json-repro.test.ts	16	// Run: vitest run packages/plugins/google-discovery/src/sdk/option-json.test.ts
17		17
18	import { describe, expect, it } from "@effect/vitest";	18	import { describe, expect, it } from "@effect/vitest";
19	import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";	19	import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
@@ -28,7 +28,7 @@ const fixed = { description: Option.some("hello") }; · 8 unmodified lines
28	const withTmpFile = <A, E>(fn: (path: string) => Effect.Effect<A, E, FileSystem.FileSystem>) =>	28	const withTmpFile = <A, E>(fn: (path: string) => Effect.Effect<A, E, FileSystem.FileSystem>) =>
29	Effect.gen(function* () {	29	Effect.gen(function* () {
30	const fs = yield* FileSystem.FileSystem;	30	const fs = yield* FileSystem.FileSystem;
31	const dir = yield* fs.makeTempDirectoryScoped({ prefix: "option-repro-" });	31	const dir = yield* fs.makeTempDirectoryScoped({ prefix: "option-json-" });
32	return yield* fn(`${dir}/binding.json`);	32	return yield* fn(`${dir}/binding.json`);
33	}).pipe(Effect.scoped, Effect.provide(NodeFileSystem.layer));	33	}).pipe(Effect.scoped, Effect.provide(NodeFileSystem.layer));
34		34