Classify transport failures without hiding invocation defects

Author: RhysSullivan

packages/plugins/openapi/src/sdk/backing.ts

@@ -727,7 +727,7 @@ export const invokeOpenApiBackedTool = (input: {
                   details: error.cause ?? error,
                 }),
               })
-            : error.cause !== undefined && Option.isNone(error.statusCode)
+            : error.reason === "transport_error"
               ? Effect.succeed({
                   ok: false as const,
                   failure: ToolResult.fail({

packages/plugins/openapi/src/sdk/errors.ts

@@ -39,7 +39,11 @@ export class OpenApiSpecOverrideError extends Schema.TaggedErrorClass<OpenApiSpe
 export class OpenApiInvocationError extends Data.TaggedError("OpenApiInvocationError")<{
   readonly message: string;
   readonly statusCode: Option.Option<number>;
-  readonly reason?: "response_headers_timeout" | "response_body_timeout" | "unknown_arguments";
+  readonly reason?:
+    | "response_headers_timeout"
+    | "response_body_timeout"
+    | "unknown_arguments"
+    | "transport_error";
   readonly cause?: unknown;
 }> {}
 

packages/plugins/openapi/src/sdk/invoke.ts

@@ -1,4 +1,4 @@
-import { Effect, Exit, Fiber, Layer, Option, Schema, Stream } from "effect";
+import { Effect, Exit, Fiber, Layer, Option, Predicate, Schema, Stream } from "effect";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
 import { isToolFile, type ToolFileValue } from "@executor-js/sdk/core";
 
@@ -1183,6 +1183,9 @@ export const invoke = Effect.fn("OpenApi.invoke")(function* (
         (err) =>
           new OpenApiInvocationError({
             message: "HTTP request failed",
+            ...(Predicate.isTagged(err.reason, "TransportError")
+              ? { reason: "transport_error" as const }
+              : {}),
             statusCode: Option.none(),
             cause: err,
           }),
@@ -1197,7 +1200,6 @@ export const invoke = Effect.fn("OpenApi.invoke")(function* (
         }),
       ),
     );
-    const fiber = runFork(responseEffect);
     const interrupt = () => {
       runFork(Fiber.interrupt(fiber));
     };
@@ -1207,6 +1209,7 @@ export const invoke = Effect.fn("OpenApi.invoke")(function* (
       interrupt();
       resume(Effect.succeed(Option.none()));
     }, responseHeadersTimeoutMs);
+    const fiber = runFork(responseEffect);
     signal.addEventListener("abort", interrupt, { once: true });
     return Effect.sync(() => {
       clearTimeout(timer);
@@ -1257,7 +1260,6 @@ export const invoke = Effect.fn("OpenApi.invoke")(function* (
             }),
           ),
         );
-        const fiber = runFork(bodyEffect);
         const interrupt = () => {
           runFork(Fiber.interrupt(fiber));
         };
@@ -1267,6 +1269,7 @@ export const invoke = Effect.fn("OpenApi.invoke")(function* (
           interrupt();
           resume(Effect.succeed(Option.none()));
         }, responseBodyTimeoutMs);
+        const fiber = runFork(bodyEffect);
         signal.addEventListener("abort", interrupt, { once: true });
         return Effect.sync(() => {
           clearTimeout(timer);

packages/plugins/openapi/src/sdk/upstream-failures.test.ts

@@ -11,8 +11,14 @@
 // ---------------------------------------------------------------------------
 
 import { describe, expect, it } from "@effect/vitest";
-import { Effect, Exit, Schema } from "effect";
-import { FetchHttpClient, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { Cause, Data, Effect, Exit, Layer, Schema } from "effect";
+import {
+  FetchHttpClient,
+  HttpClient,
+  HttpClientError,
+  HttpServerRequest,
+  HttpServerResponse,
+} from "effect/unstable/http";
 import {
   HttpApi,
   HttpApiBuilder,
@@ -43,8 +49,10 @@ import {
 
 import { openApiPlugin } from "./plugin";
 
-const testPlugins = () =>
-  [openApiPlugin({ httpClientLayer: FetchHttpClient.layer }), memoryCredentialsPlugin()] as const;
+class AdapterDefect extends Data.TaggedError("AdapterDefect") {}
+
+const testPlugins = (httpClientLayer = FetchHttpClient.layer) =>
+  [openApiPlugin({ httpClientLayer }), memoryCredentialsPlugin()] as const;
 
 // `/things` GET op `listThings` under group "things" → tool path
 // `things.listThings`, used verbatim (dots and all) as the address tool segment.
@@ -114,9 +122,11 @@ const FailureApi = HttpApi.make("failuresTest")
 
 // Build an executor + connection from the FailureApi HttpApi against an
 // arbitrary baseUrl (used for the Node-transport socket-drop / slow cases).
-const buildExecutor = (baseUrl: string) =>
+const buildExecutor = (baseUrl: string, httpClientLayer = FetchHttpClient.layer) =>
   Effect.gen(function* () {
-    const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
+    const executor = yield* createExecutor(
+      makeTestConfig({ plugins: testPlugins(httpClientLayer) }),
+    );
     yield* executor.openapi.addSpec(
       makeOpenApiHttpApiTestIntegrationConfig(FailureApi, { slug: "f", baseUrl }),
     );
@@ -450,6 +460,62 @@ describe("OpenAPI upstream failure modes", () => {
     }),
   );
 
+  it.effect("request encoding failures remain invocation failures", () =>
+    Effect.gen(function* () {
+      const httpClientLayer = Layer.succeed(
+        HttpClient.HttpClient,
+        HttpClient.make((request) =>
+          Effect.fail(
+            new HttpClientError.HttpClientError({
+              reason: new HttpClientError.EncodeError({ request, cause: new AdapterDefect() }),
+            }),
+          ),
+        ),
+      );
+      const { executor, address } = yield* buildExecutor(
+        "https://upstream.example",
+        httpClientLayer,
+      );
+      const exit = yield* executor.execute(address, {}).pipe(Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+    }),
+  );
+
+  it.effect("transport defects remain defects", () =>
+    Effect.gen(function* () {
+      const defect = new AdapterDefect();
+      const httpClientLayer = Layer.succeed(
+        HttpClient.HttpClient,
+        HttpClient.make(() => Effect.die(defect)),
+      );
+      const { executor, address } = yield* buildExecutor(
+        "https://upstream.example",
+        httpClientLayer,
+      );
+      const exit = yield* executor.execute(address, {}).pipe(Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(Exit.match(exit, { onFailure: Cause.hasDies, onSuccess: () => false })).toBe(true);
+    }),
+  );
+
+  it.effect("interrupted transport remains interrupted", () =>
+    Effect.gen(function* () {
+      const httpClientLayer = Layer.succeed(
+        HttpClient.HttpClient,
+        HttpClient.make(() => Effect.interrupt),
+      );
+      const { executor, address } = yield* buildExecutor(
+        "https://upstream.example",
+        httpClientLayer,
+      );
+      const exit = yield* executor.execute(address, {}).pipe(Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(Exit.match(exit, { onFailure: Cause.hasInterrupts, onSuccess: () => false })).toBe(
+        true,
+      );
+    }),
+  );
+
   // Port 1 refuses immediately. The same path used to throw `Internal tool
   // error [hex]` because the raw HttpClientError carries the request URL.
   it.effect("connection refused returns upstream_unreachable without leaking the path", () =>