lael-labs/executor

apps/cloud/src/api/protected-layers.ts+17−2

 import { HttpApiBuilder, HttpRouter, HttpServer } from "@effect/platform";
 import { Layer } from "effect";
-import { CoreExecutorApi } from "@executor/api";
+import {
+  CoreExecutorApi,
+  InternalError,
+  observabilityMiddleware,
+} from "@executor/api";
 import { CoreHandlers } from "@executor/api/server";
 import { OpenApiGroup, OpenApiHandlers } from "@executor/plugin-openapi/api";
 import { McpGroup, McpHandlers } from "@executor/plugin-mcp/api";
 import { WorkOSAuth } from "../auth/workos";
 import { AutumnService } from "../services/autumn";
 import { DbService } from "../services/db";
+import { ErrorCaptureLive } from "../observability";
 export const ProtectedCloudApi = CoreExecutorApi.add(OpenApiGroup)
   .add(McpGroup)
   .add(GraphqlGroup)
+  .addError(InternalError)
   .middleware(OrgAuth);
+const ObservabilityLive = observabilityMiddleware(ProtectedCloudApi);
 const DbLive = DbService.Live;
 const UserStoreLive = UserStoreService.Live.pipe(Layer.provide(DbLive));
   GraphqlHandlers,
 );
+// `ErrorCaptureLive` is provided above the handler + middleware layers
+// so the `withCapture` translation path (typed-channel `StorageError →
+// InternalError(traceId)`) AND the observability middleware's defect
+// catchall both see the same Sentry-backed implementation.
 export const ProtectedCloudApiLive = HttpApiBuilder.api(ProtectedCloudApi).pipe(
-  Layer.provide(Layer.merge(ProtectedCloudApiHandlers, OrgAuthLive)),
+  Layer.provide(
+    Layer.mergeAll(ProtectedCloudApiHandlers, OrgAuthLive, ObservabilityLive),
+  ),
+  Layer.provide(ErrorCaptureLive),
 );

apps/cloud/src/api/protected.ts+3−0

   Effect.gen(function* () {
     const { executor, engine } = yield* makeExecutionStack(organizationId, organizationName);
+    // Handlers wrap their own bodies with `capture(...)` — the edge
+    // translation lives per-handler, not at service construction. See
+    // notes/error-handling.md.
     const requestServices = Layer.mergeAll(
       Layer.succeed(ExecutorService, executor),
       Layer.succeed(ExecutionEngineService, engine),

apps/cloud/src/observability.ts+31−0

@@ -0,0 +1,31 @@
	1	// ---------------------------------------------------------------------------
	2	// Cloud-app implementation of the shared `ErrorCapture` service. This is the
	3	// only file in the cloud-app that imports `@sentry/cloudflare` for error
	4	// capture — handlers, plugin SDKs, and storage code all stay
	5	// Sentry-agnostic and request the `ErrorCapture` tag instead.
	6	//
	7	// `withObservability` (in @executor/api) wraps every handler effect; when
	8	// it sees an unmapped cause it asks `ErrorCapture.captureException` for a
	9	// trace id and fails with `InternalError({ traceId })`. The client gets
	10	// the opaque id, we get the full cause + stack in Sentry.
	11	// ---------------------------------------------------------------------------
	12
	13	import * as Sentry from "@sentry/cloudflare";
	14	import { Cause, Effect, Layer } from "effect";
	15
	16	import { ErrorCapture } from "@executor/api";
	17
	18	export const ErrorCaptureLive: Layer.Layer<ErrorCapture> = Layer.succeed(
	19	ErrorCapture,
	20	ErrorCapture.of({
	21	captureException: (cause) =>
	22	Effect.sync(() => {
	23	const squashed = Cause.squash(cause);
	24	const eventId = Sentry.captureException(squashed, (scope) => {
	25	scope.setExtra("cause", Cause.pretty(cause));
	26	return scope;
	27	});
	28	return eventId ?? "";
	29	}),
	30	}),
	31	);

apps/cloud/src/services/executor.ts+4−0

       createdAt: new Date(),
     });
+    // The executor surface returns raw `StorageFailure`; translation to
+    // the opaque `InternalError({ traceId })` happens at the HTTP edge
+    // via `withCapture` (see `api/protected-layers.ts`). That's
+    // where `ErrorCaptureLive` (Sentry) gets wired in.
     return yield* createExecutor({ scope, adapter, blobs, plugins });
   });

apps/local/src/server/main.ts+13−1

 } from "@effect/platform";
 import { Context, Effect, Layer, ManagedRuntime } from "effect";
-import { addGroup } from "@executor/api";
+import { addGroup, observabilityMiddleware } from "@executor/api";
 import { CoreHandlers, ExecutorService, ExecutionEngineService } from "@executor/api/server";
 import { createExecutionEngine } from "@executor/execution";
 import { makeQuickJsExecutor } from "@executor/runtime-quickjs";
 } from "@executor/plugin-graphql/api";
 import { getExecutor } from "./executor";
 import { createMcpRequestHandler, type McpRequestHandler } from "./mcp";
+import { ErrorCaptureLive } from "./observability";
 // ---------------------------------------------------------------------------
 // Local server API — core + all plugin groups
   .add(OnePasswordGroup)
   .add(GraphqlGroup);
+// `ErrorCaptureLive` logs causes to the console and returns a short
+// correlation id. Provided above the handler + middleware layers so
+// both the `withCapture` typed-channel translation AND the
+// `observabilityMiddleware` defect catchall see the same
+// implementation.
+const LocalObservability = observabilityMiddleware(LocalApi);
 const LocalApiBase = HttpApiBuilder.api(LocalApi).pipe(
   Layer.provide(CoreHandlers),
   Layer.provide(
       GraphqlHandlers,
     ),
   ),
+  Layer.provide(LocalObservability),
+  Layer.provide(ErrorCaptureLive),
 );
 // ---------------------------------------------------------------------------
   const executor = await getExecutor();
   const engine = createExecutionEngine({ executor, codeExecutor: makeQuickJsExecutor() });
+  // Handlers wrap their own bodies with `capture(...)` — the edge
+  // translation lives per-handler, not at service construction.
   const pluginExtensions = Layer.mergeAll(
     Layer.succeed(OpenApiExtensionService, executor.openapi),
     Layer.succeed(McpExtensionService, executor.mcp),

apps/local/src/server/observability.ts+32−0

@@ -0,0 +1,32 @@
	1	// ---------------------------------------------------------------------------
	2	// Local-app `ErrorCapture` — console implementation.
	3	//
	4	// Unlike the cloud app (Sentry-backed), the CLI just prints the squashed
	5	// cause + pretty-printed structured cause to stderr and returns a short
	6	// correlation id. Operators can grep for the id in their terminal
	7	// scrollback when a user reports an opaque 500 traceId.
	8	// ---------------------------------------------------------------------------
	9
	10	import { Cause, Effect, Layer } from "effect";
	11
	12	import { ErrorCapture } from "@executor/api";
	13
	14	const nextTraceId = () =>
	15	`local-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
	16
	17	export const ErrorCaptureLive: Layer.Layer<ErrorCapture> = Layer.succeed(
	18	ErrorCapture,
	19	ErrorCapture.of({
	20	captureException: (cause) =>
	21	Effect.sync(() => {
	22	const traceId = nextTraceId();
	23	const squashed = Cause.squash(cause);
	24	console.error(
	25	`[executor ${traceId}]`,
	26	squashed instanceof Error ? squashed.stack ?? squashed : squashed,
	27	);
	28	console.error(`[executor ${traceId}] cause:`, Cause.pretty(cause));
	29	return traceId;
	30	}),
	31	}),
	32	);

bun.lock+4−0

         "@effect/platform": "catalog:",
         "@executor/execution": "workspace:*",
         "@executor/sdk": "workspace:*",
+        "@executor/storage-core": "workspace:*",
         "effect": "catalog:",
       },
       "devDependencies": {
+        "@effect/vitest": "catalog:",
         "@types/node": "catalog:",
         "bun-types": "catalog:",
         "typescript": "catalog:",
+        "vitest": "catalog:",
       },
     },
     "packages/core/cli": {
       "name": "@executor/sdk",
       "version": "0.0.1",
       "dependencies": {
+        "@effect/platform": "catalog:",
         "@executor/storage-core": "workspace:*",
         "effect": "catalog:",
       },

notes/error-handling.md+195−0

@@ -0,0 +1,195 @@
	1	# Error handling — model + plumbing
	2
	3	## Principle
	4
	5	Errors are typed values that propagate through the call graph carrying
	6	their full causal structure. Exactly one layer at the edge consumes
	7	them and maps them to a public response. Plugin code never imports
	8	Sentry, never calls `captureException`, never wraps handlers with
	9	`sanitize*` helpers.
	10
	11	Two error categories:
	12
	13	- Surfaceable: typed Schema errors with a user-actionable message
	14	(`McpOAuthError`, `OpenApiParseError`, …). Carry through to the
	15	response with their own status (4xx) and message body. Not captured
	16	to any external sink — they're normal business outcomes.
	17	- Internal: truly unexpected (storage failure, third-party returned
	18	garbage, sync throw inside a handler). Captured via `ErrorCapture`
	19	at the HTTP edge only, then propagated as the shared
	20	`InternalError({ traceId })` schema — opaque to clients, fully
	21	detailed in Sentry. One shape, one trace id, one place to look up
	22	the cause.
	23
	24	## Layering
	25
	26	```
	27	storage-core ──▶ sdk ──▶ api (HTTP edge) ──▶ host
	28	StorageError StorageError InternalError ErrorCaptureLive
	29	(raw) (raw) (captured) (Sentry)
	30	```
	31
	32	The SDK stays storage-typed. The HTTP edge (`@executor/api`) is the
	33	only layer that translates `StorageError → InternalError` and
	34	captures the cause to telemetry. Non-HTTP consumers (CLI, Promise
	35	SDK, tests) see raw `StorageError` in the typed channel and can react
	36	however they want.
	37
	38	## Plumbing
	39
	40	### Storage layer (`@executor/storage-core`)
	41
	42	Emits two `Data.TaggedError` classes and nothing else observability-related:
	43
	44	- `StorageError({ message, cause })` — the catch-all for non-recoverable
	45	backend failures. The `cause` travels as runtime data so the HTTP
	46	edge can capture it, but it's never serialised to the wire.
	47	- `UniqueViolationError({ model? })` — typed 4xx-shaped failure plugins
	48	want to react to (e.g. "source already exists").
	49
	50	Both are `Data.TaggedError`, not `Schema.TaggedError` — you physically
	51	can't `addError(...)` them on an HttpApi group, which enforces "these
	52	are internal types, not wire shapes".
	53
	54	`DBAdapter` / `CustomAdapter` / `TypedAdapter` declare
	55	`Effect<X, StorageFailure>` where `StorageFailure = StorageError \|
	56	UniqueViolationError`. No `Error`, no telemetry service in R.
	57
	58	Storage-core has zero observability awareness — it just emits typed
	59	values and lets consumers decide what to do with them.
	60
	61	### SDK (`@executor/sdk`)
	62
	63	The SDK is entirely observability-free.
	64
	65	- `createExecutor` requires no observability service. `R = never`.
	66	- `PluginCtx.storage`, `ctx.core.`, `ctx.secrets.`, `ctx.transaction`
	67	all surface raw `StorageFailure` in the typed error channel. Plugins
	68	can `Effect.catchTag("UniqueViolationError", …)` and translate to
	69	their own user-facing errors.
	70	- Executor public methods (`executor.tools.list()`,
	71	`executor.sources.refresh()`, etc.) also surface raw `StorageFailure`.
	72
	73	No `liftStorage`, no `wrapAdapterForPlugin`, no `ErrorCapture` tag
	74	inside the SDK. The value proposition: an SDK consumer can write a CLI,
	75	a script, a promise-based wrapper, whatever — and the typed channel
	76	shows them exactly what can go wrong.
	77
	78	### HTTP edge (`@executor/api/observability`)
	79
	80	Owns the translation, the opaque wire schema, and the capture service.
	81
	82	- `InternalError({ traceId })` — the public opaque 500 schema, with an
	83	`HttpApiSchema.annotations({ status: 500 })` annotation so the
	84	framework encodes it correctly.
	85	- `ErrorCapture` — tagged Effect service for recording unexpected
	86	causes. Shape:
	87
	88	```ts
	89	interface ErrorCaptureShape {
	90	readonly captureException: (cause: Cause<unknown>) => Effect<string>
	91	}
	92	```
	93
	94	Optional — resolved via `Effect.serviceOption`; missing service =
	95	empty trace ids. Nothing breaks if it's not wired.
	96
	97	- `capture(eff)` — the single translator. Catches `StorageError` on
	98	the typed channel, captures the cause via `ErrorCapture`, fails with
	99	`InternalError({ traceId })`. Catches `UniqueViolationError` and
	100	dies (plugins that want to surface it as a typed domain error should
	101	`Effect.catchTag` inside their own method first). Every other typed
	102	failure passes through.
	103
	104	Every handler wraps its generator body with `capture(...)`:
	105
	106	```ts
	107	.handle("probeEndpoint", ({ payload }) =>
	108	capture(Effect.gen(function* () {
	109	const ext = yield* McpExtensionService;
	110	return yield* ext.probeEndpoint(payload.endpoint);
	111	})),
	112	)
	113	```
	114
	115	One line at the top of each handler. No service-level proxy, no
	116	`Captured<T>` type gymnastics — the translation is visible right
	117	where it happens, and TypeScript rejects handlers that forget
	118	(because `StorageError` isn't in the group's `.addError` list).
	119
	120	- `observabilityMiddleware(Api)` — defect safety net. An
	121	`HttpApiBuilder.middleware` layer that wraps the HttpApp once and
	122	catches any cause that escaped the typed channel (defects,
	123	interrupts, framework bugs) via `ErrorCapture`, returning a typed
	124	`InternalError({ traceId })`. Should rarely fire when the rest of
	125	the pipeline is well-typed.
	126
	127	### Plugin SDK
	128
	129	Plugin authors write normal Effect code. Their extension method error
	130	unions look like:
	131
	132	```ts
	133	Effect.Effect<X, MyPluginTypedError \| StorageError, never>
	134	```
	135
	136	Where `MyPluginTypedError` is the union of their own
	137	`Schema.TaggedError` classes (with `HttpApiSchema.annotations({ status: 4xx })`).
	138	`StorageError` is the raw storage tag — it bubbles up, and the HTTP
	139	edge translates it.
	140
	141	Plugins never provide `ErrorCapture`, never import Sentry, never see
	142	`InternalError` in their typed channel.
	143
	144	### API groups
	145
	146	Each group declares its typed errors once at the group level:
	147
	148	```ts
	149	class McpGroup extends HttpApiGroup.make("mcp")
	150	.add(endpoint1)
	151	.add(endpoint2)
	152	// …
	153	.addError(InternalError)
	154	.addError(McpOAuthError)
	155	.addError(McpConnectionError)
	156	// …
	157	{}
	158	```
	159
	160	No per-endpoint `addError`. The framework encodes each tagged error by
	161	its annotated status.
	162
	163	### Hosts
	164
	165	- Cloud Worker (`apps/cloud/src/observability.ts`) — provides
	166	`ErrorCaptureLive`, a Sentry-backed implementation. Wired at the API
	167	layer in `protected-layers.ts` so it's available to both
	168	`observabilityMiddleware` (defect catchall) AND the per-handler
	169	`capture(...)` translation. Service tags (`ExecutorService`,
	170	`McpExtensionService`, etc.) hold the raw SDK shapes; the cloud app
	171	just does `Layer.succeed(McpExtensionService, executor.mcp)` —
	172	handlers do the translation themselves. (Distinct from
	173	`apps/cloud/src/services/telemetry.ts`, which is the OTEL→Axiom span
	174	bridge — "telemetry" in the tracing sense.)
	175	- CLI (`apps/local/src/server/main.ts`) — same pattern. Provides a
	176	console-based `ErrorCaptureLive` (`apps/local/src/server/observability.ts`)
	177	that prints the squashed cause + pretty cause to stderr and returns a
	178	short correlation id.
	179	- Tests / Promise SDK / examples — non-HTTP consumers see raw
	180	`StorageError` / `StorageFailure` in the SDK's typed channel and
	181	can match on it directly.
	182
	183	### Anti-patterns
	184
	185	- `Effect.orDie` at handler boundaries — silently turns recoverable
	186	failures into 500s with no telemetry (defects bypass typed-channel
	187	encoding).
	188	- Per-plugin `*InternalError` types — clients can't tell which plugin
	189	emitted a 500 anyway. Use the shared `InternalError`.
	190	- `sanitize*` helpers in handler files that `catchAllCause` + map to a
	191	generic 500 — same swallowing problem in disguise. Prefer wrapping
	192	the handler's `Effect.gen` body with `capture(...)`.
	193	- SDK code importing `Sentry.captureException` or referencing
	194	`InternalError` / `ErrorCapture` — translation lives strictly in
	195	`@executor/api`. If the SDK imports it, the layering is wrong.

notes/promise-sdk-typed-errors.md+78−0

@@ -0,0 +1,78 @@
	1	# Promise SDK — typed errors revisit
	2
	3	## Today
	4
	5	`@executor/sdk/promise` wraps every Effect-returning method in
	6	`Effect.runPromise(...)`. That works but it's lossy at the Promise
	7	boundary:
	8
	9	- The promise's rejection type is `unknown` (or `any` after
	10	`try/catch`). Consumers have to `instanceof InternalError` /
	11	`err._tag === "..."` to discriminate, even though the underlying
	12	Effect had a fully typed error union.
	13	- Defects (uncaught throws, fiber interrupts) become rejections with
	14	whatever value the Effect ran with — sometimes useful, sometimes a
	15	string, depending on the cause.
	16
	17	In other words: the Effect-side surface knows your method can fail with
	18	`McpOAuthError \| InternalError \| UniqueViolationError`; the promise
	19	consumer sees `Promise<X>` and has to take it on faith.
	20
	21	## What we want (revisit)
	22
	23	Switch the wrapper to `Effect.runPromiseExit(...)`. The promise always
	24	resolves with an `Exit<A, E>`:
	25
	26	```ts
	27	const exit = await executor.openapi.addSpec({ ... })
	28	if (Exit.isSuccess(exit)) {
	29	exit.value // properly typed `A`
	30	} else {
	31	// exit.cause is Cause<McpOAuthError \| InternalError \| ...>
	32	// narrow with Cause.failureOption / Cause.match etc.
	33	}
	34	```
	35
	36	The error union survives the Promise boundary. Defects are visible in
	37	the cause. Consumers can write totality-checked `match` on the typed
	38	union without any runtime guessing.
	39
	40	## Open question for the revisit
	41
	42	Do we expose Effect's `Exit` / `Cause` directly to promise consumers,
	43	or wrap them in a promise-native `Result<A, E>`?
	44
	45	Expose `Exit`/`Cause`:
	46	- Pros: one fewer abstraction, no translation layer to maintain, cause
	47	preserves parallel/sequential composition.
	48	- Cons: consumers depend on `effect`'s API even though they're using a
	49	"Promise" SDK — partly defeats the abstraction.
	50
	51	Wrap in a `Result<A, E>`:
	52	- Pros: `@executor/sdk/promise` consumers don't import `effect` at all,
	53	surface stays small.
	54	- Cons: another type to learn / document; loses some Cause structure
	55	(parallel/interrupt) unless we replicate it.
	56
	57	Lean toward exposing `Exit`/`Cause`, but worth thinking through what
	58	the `runPromiseExit` consumers actually want to do at the call site
	59	before deciding.
	60
	61	## Why punted
	62
	63	Current refactor is about getting Effect-side typed errors right
	64	end-to-end (storage → SDK → API). The Promise façade is downstream of
	65	that — once the typed unions are stable on the Effect side, the
	66	`runPromiseExit` rewrite is a small, well-defined change.
	67
	68	Also: it's a breaking change for promise SDK consumers (return type
	69	goes from `Promise<A>` to `Promise<Exit<A, E>>`). Better as its own
	70	focused PR with a migration note.
	71
	72	## Files affected when we do it
	73
	74	- `packages/core/sdk/src/promise-executor.ts` (`promisifyDeep`,
	75	`createExecutor`)
	76	- `packages/core/sdk/src/promise.ts` if it re-exports surface
	77	- Any Promise-SDK consumer in `examples/` or downstream
	78	- Doc updates in `notes/error-handling.md`

packages/core/api/package.json+6−2

   },
   "scripts": {
     "typecheck": "tsgo --noEmit",
-    "typecheck:slow": "tsc --noEmit"
+    "typecheck:slow": "tsc --noEmit",
+    "test": "vitest run"
   },
   "dependencies": {
     "@effect/platform": "catalog:",
     "@executor/execution": "workspace:*",
     "@executor/sdk": "workspace:*",
+    "@executor/storage-core": "workspace:*",
     "effect": "catalog:"
   },
   "devDependencies": {
+    "@effect/vitest": "catalog:",
     "@types/node": "catalog:",
     "bun-types": "catalog:",
-    "typescript": "catalog:"
+    "typescript": "catalog:",
+    "vitest": "catalog:"
   }
 }

packages/core/api/src/executions/api.ts+4−1

 import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "@effect/platform";
 import { Schema } from "effect";
+import { InternalError } from "../observability";
 // ---------------------------------------------------------------------------
 // Schemas
 // ---------------------------------------------------------------------------
       .setPayload(ResumeRequest)
       .addSuccess(ResumeResponse)
       .addError(ExecutionNotFoundError),
-  ) {}
+  )
+  .addError(InternalError) {}

packages/core/api/src/handlers/executions.ts+5−4

 import { ExecutorApi } from "../api";
 import { formatExecuteResult, formatPausedExecution } from "@executor/execution";
 import { ExecutionEngineService } from "../services";
+import { capture } from "@executor/api";
 export const ExecutionsHandlers = HttpApiBuilder.group(ExecutorApi, "executions", (handlers) =>
   handlers
     .handle("execute", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const engine = yield* ExecutionEngineService;
         const outcome = yield* Effect.promise(() => engine.executeWithPause(payload.code));
           text: formatted.text,
           structured: formatted.structured,
         };
-      }),
+      })),
     )
     .handle("resume", ({ path, payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const engine = yield* ExecutionEngineService;
         const result = yield* Effect.promise(() =>
           engine.resume(path.executionId, {
           structured: formatted.structured,
           isError: false,
         };
-      }),
+      })),
     ),
 );

packages/core/api/src/handlers/scope.ts+3−2

 import { ExecutorApi } from "../api";
 import { ExecutorService } from "../services";
+import { capture } from "@executor/api";
 export const ScopeHandlers = HttpApiBuilder.group(ExecutorApi, "scope", (handlers) =>
   handlers.handle("info", () =>
-    Effect.gen(function* () {
+    capture(Effect.gen(function* () {
       const executor = yield* ExecutorService;
       return {
         id: executor.scope.id,
         name: executor.scope.name,
         dir: executor.scope.name,
       };
-    }),
+    })),
   ),
 );

packages/core/api/src/handlers/secrets.ts+21−22

 import { ExecutorApi } from "../api";
 import { ExecutorService } from "../services";
+import { capture } from "@executor/api";
 const refToResponse = (ref: SecretRef) => ({
   id: ref.id,
 export const SecretsHandlers = HttpApiBuilder.group(ExecutorApi, "secrets", (handlers) =>
   handlers
     .handle("list", () =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        const refs = yield* executor.secrets.list().pipe(Effect.orDie);
+        const refs = yield* executor.secrets.list();
         return refs.map(refToResponse);
-      }),
+      })),
     )
     .handle("status", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        const status = yield* executor.secrets.status(path.secretId).pipe(Effect.orDie);
+        const status = yield* executor.secrets.status(path.secretId);
         return { secretId: path.secretId, status };
-      }),
+      })),
     )
     .handle("set", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        const ref = yield* executor.secrets
+        const ref = yield* executor.secrets.set({
-          .set({
+          id: payload.id,
-            id: payload.id,
+          name: payload.name,
-            name: payload.name,
+          value: payload.value,
-            value: payload.value,
+          provider: payload.provider,
-            provider: payload.provider,
+        });
-          })
-          .pipe(Effect.orDie);
         return refToResponse(ref);
-      }),
+      })),
     )
     .handle("resolve", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        const value = yield* executor.secrets.get(path.secretId).pipe(Effect.orDie);
+        const value = yield* executor.secrets.get(path.secretId);
         if (value === null) {
           return yield* Effect.fail(new SecretNotFoundError({ secretId: path.secretId }));
         }
         return { secretId: path.secretId, value };
-      }),
+      })),
     )
     .handle("remove", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        yield* executor.secrets.remove(path.secretId).pipe(Effect.orDie);
+        yield* executor.secrets.remove(path.secretId);
         return { removed: true };
-      }),
+      })),
     ),
 );

packages/core/api/src/handlers/sources.ts+16−17

 import { ExecutorApi } from "../api";
 import { ExecutorService } from "../services";
+import { capture } from "@executor/api";
 export const SourcesHandlers = HttpApiBuilder.group(ExecutorApi, "sources", (handlers) =>
   handlers
     .handle("list", () =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        const sources = yield* executor.sources.list().pipe(Effect.orDie);
+        const sources = yield* executor.sources.list();
         return sources.map((s) => ({
           id: s.id,
           name: s.name,
           canRefresh: s.canRefresh,
           canEdit: s.canEdit,
         }));
-      }),
+      })),
     )
     .handle("remove", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        yield* executor.sources.remove(path.sourceId).pipe(Effect.orDie);
+        yield* executor.sources.remove(path.sourceId);
         return { removed: true };
-      }),
+      })),
     )
     .handle("refresh", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        yield* executor.sources.refresh(path.sourceId).pipe(Effect.orDie);
+        yield* executor.sources.refresh(path.sourceId);
         return { refreshed: true };
-      }),
+      })),
     )
     .handle("tools", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        const tools = yield* executor.tools
+        const tools = yield* executor.tools.list({ sourceId: path.sourceId });
-          .list({ sourceId: path.sourceId })
-          .pipe(Effect.orDie);
         return tools.map((t) => ({
           id: ToolId.make(t.id),
           pluginId: t.pluginId,
           description: t.description,
           mayElicit: t.annotations?.mayElicit,
         }));
-      }),
+      })),
     )
     .handle("detect", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        const results = yield* executor.sources.detect(payload.url).pipe(Effect.orDie);
+        const results = yield* executor.sources.detect(payload.url);
         return results.map((r) => ({
           kind: r.kind,
           confidence: r.confidence,
           name: r.name,
           namespace: r.namespace,
         }));
-      }),
+      })),
     ),
 );

packages/core/api/src/handlers/tools.ts+7−6

 import { ExecutorApi } from "../api";
 import { ExecutorService } from "../services";
+import { capture } from "@executor/api";
 export const ToolsHandlers = HttpApiBuilder.group(ExecutorApi, "tools", (handlers) =>
   handlers
     .handle("list", () =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        const tools = yield* executor.tools.list().pipe(Effect.orDie);
+        const tools = yield* executor.tools.list();
         return tools.map((t) => ({
           id: ToolId.make(t.id),
           pluginId: t.pluginId,
           description: t.description,
           mayElicit: t.annotations?.mayElicit,
         }));
-      }),
+      })),
     )
     .handle("schema", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const executor = yield* ExecutorService;
-        const schema = yield* executor.tools.schema(path.toolId).pipe(Effect.orDie);
+        const schema = yield* executor.tools.schema(path.toolId);
         if (schema === null) {
           return yield* Effect.fail(new ToolNotFoundError({ toolId: path.toolId }));
         }
         return schema;
-      }),
+      })),
     ),
 );

packages/core/api/src/index.ts+7−0

@@ -4,3 +4,10 @@ export { SourcesApi } from "./sources/api"; · 3 unmodified lines
4	export { SecretsApi } from "./secrets/api";	4	export { SecretsApi } from "./secrets/api";
5	export { ExecutionsApi } from "./executions/api";	5	export { ExecutionsApi } from "./executions/api";
6	export { ScopeApi } from "./scope/api";	6	export { ScopeApi } from "./scope/api";
		7	export {
		8	InternalError,
		9	ErrorCapture,
		10	observabilityMiddleware,
		11	capture,
		12	type ErrorCaptureShape,
		13	} from "./observability";

packages/core/api/src/observability.test.ts+87−0

@@ -0,0 +1,87 @@
	1	// ---------------------------------------------------------------------------
	2	// Edge translation — `StorageError → InternalError(traceId)` behaviour
	3	// via `capture(eff)`. Handlers wrap their generator bodies with
	4	// `capture(...)`; this file exercises the translator in isolation.
	5	// ErrorCapture is optional — absent hosts just get empty trace ids.
	6	// ---------------------------------------------------------------------------
	7
	8	import { describe, expect, it } from "@effect/vitest";
	9	import { Cause, Effect, Layer, Ref } from "effect";
	10	import { StorageError, UniqueViolationError } from "@executor/storage-core";
	11
	12	import { capture, ErrorCapture, InternalError } from "./observability";
	13
	14	// Recording ErrorCapture — returns a fixed trace id and accumulates
	15	// every cause it sees in a Ref.
	16	const makeRecorder = (traceId = "trace-xyz") =>
	17	Effect.gen(function* () {
	18	const seen = yield* Ref.make<ReadonlyArray<Cause.Cause<unknown>>>([]);
	19	const layer = Layer.succeed(
	20	ErrorCapture,
	21	ErrorCapture.of({
	22	captureException: (cause) =>
	23	Ref.update(seen, (prev) => [...prev, cause]).pipe(
	24	Effect.as(traceId),
	25	),
	26	}),
	27	);
	28	return { layer, seen };
	29	});
	30
	31	describe("capture", () => {
	32	it.effect("translates StorageError to InternalError with ErrorCapture trace id", () =>
	33	Effect.gen(function* () {
	34	const { layer, seen } = yield* makeRecorder("trace-abc");
	35	const err = new StorageError({ message: "db down", cause: new Error("x") });
	36
	37	const eff = capture(Effect.fail(err));
	38	const result = yield* Effect.flip(eff).pipe(Effect.provide(layer));
	39
	40	expect(result).toBeInstanceOf(InternalError);
	41	expect(result.traceId).toBe("trace-abc");
	42
	43	// The recorder saw exactly one cause carrying the original StorageError.
	44	const causes = yield* Ref.get(seen);
	45	expect(causes.length).toBe(1);
	46	const squashed = Cause.squash(causes[0]!) as StorageError;
	47	expect(squashed).toBeInstanceOf(StorageError);
	48	expect(squashed.message).toBe("db down");
	49	}),
	50	);
	51
	52	it.effect("empty traceId when no ErrorCapture is wired", () =>
	53	Effect.gen(function* () {
	54	const err = new StorageError({ message: "nope", cause: undefined });
	55	const result = yield* Effect.flip(capture(Effect.fail(err)));
	56	expect(result).toBeInstanceOf(InternalError);
	57	expect(result.traceId).toBe("");
	58	}),
	59	);
	60
	61	it.effect("UniqueViolationError dies (becomes a defect — plugins should catchTag before returning)", () =>
	62	Effect.gen(function* () {
	63	const err = new UniqueViolationError({ model: "thing" });
	64	const exit = yield* Effect.exit(capture(Effect.fail(err)));
	65	expect(exit._tag).toBe("Failure");
	66	if (exit._tag === "Failure") {
	67	const defects = Cause.defects(exit.cause);
	68	expect(Array.from(defects)[0]).toBeInstanceOf(UniqueViolationError);
	69	}
	70	}),
	71	);
	72
	73	it.effect("non-storage typed failures pass through unchanged", () =>
	74	Effect.gen(function* () {
	75	class DomainError {
	76	readonly _tag = "DomainError" as const;
	77	}
	78	const eff = Effect.fail(new DomainError()) as Effect.Effect<
	79	never,
	80	DomainError
	81	>;
	82	const result = yield* Effect.flip(capture(eff));
	83	expect(result._tag).toBe("DomainError");
	84	}),
	85	);
	86	});
	87

packages/core/api/src/observability.ts+155−0

@@ -0,0 +1,155 @@
	1	// ---------------------------------------------------------------------------
	2	// HTTP-edge observability — singular translation + capture layer.
	3	//
	4	// The SDK (`@executor/sdk`) stays storage-typed: plugin code and
	5	// executor surface methods return `StorageError` in their typed error
	6	// channel. Non-HTTP consumers (CLI, Promise SDK, tests) see those raw
	7	// and can decide what to do. Here, at the HTTP edge, we define:
	8	//
	9	// 1. `InternalError` — public opaque 500 schema, narrow by design
	10	// (only `traceId`), so no internal cause/message/stack ever
	11	// crosses the wire.
	12	// 2. `ErrorCapture` — pluggable service the host wires up (Sentry in
	13	// the cloud Worker, console in the CLI, in-memory in tests) to
	14	// record causes and return correlation ids. Optional; absent →
	15	// empty trace ids, nothing breaks.
	16	// 3. `capture(eff)` — the one translator. Catches `StorageError` and
	17	// `UniqueViolationError` in the typed channel: the former is
	18	// captured via `ErrorCapture` and re-failed as `InternalError({
	19	// traceId })`; the latter dies as a defect (plugins that want to
	20	// surface it as a typed domain error should `Effect.catchTag`
	21	// inside their own method first). Every handler wraps its
	22	// generator body with `capture(...)` — one line, explicit,
	23	// self-enforcing (TypeScript rejects the handler if it forgets).
	24	// 4. `observabilityMiddleware` — defect safety net. Wraps the HttpApp
	25	// once; catches any cause that slipped past the typed channel and
	26	// produces the same `InternalError({ traceId })` shape.
	27	//
	28	// Distinct from `apps/cloud/src/services/telemetry.ts` — that's the
	29	// OTEL bridge wiring spans to Axiom; this is exception capture in the
	30	// Sentry sense.
	31	// ---------------------------------------------------------------------------
	32
	33	import { Cause, Context, Effect, Layer, Option, Schema } from "effect";
	34	import {
	35	HttpApiBuilder,
	36	HttpApiSchema,
	37	HttpServerResponse,
	38	type HttpApi,
	39	type HttpApiGroup,
	40	} from "@effect/platform";
	41	import type { StorageFailure } from "@executor/storage-core";
	42
	43	/** Public 500 surface. Opaque by schema. */
	44	export class InternalError extends Schema.TaggedError<InternalError>()(
	45	"InternalError",
	46	{
	47	/** Opaque correlation id for backend lookup (Sentry event id, log line, etc.). */
	48	traceId: Schema.String,
	49	},
	50	HttpApiSchema.annotations({ status: 500 }),
	51	) {}
	52
	53	export interface ErrorCaptureShape {
	54	/**
	55	* Record an unexpected cause and return a correlation id the operator
	56	* can later look up. Implementations (Sentry, console, etc.) decide
	57	* how to persist it.
	58	*/
	59	readonly captureException: (
	60	cause: Cause.Cause<unknown>,
	61	) => Effect.Effect<string>;
	62	}
	63
	64	export class ErrorCapture extends Context.Tag("@executor/api/ErrorCapture")<
	65	ErrorCapture,
	66	ErrorCaptureShape
	67	>() {
	68	/** No-op — used where capture isn't wired. Traces back as empty string. */
	69	static readonly NoOp: Layer.Layer<ErrorCapture> = Layer.succeed(
	70	ErrorCapture,
	71	ErrorCapture.of({ captureException: () => Effect.succeed("") }),
	72	);
	73	}
	74
	75	// Resolve ErrorCapture with a no-op fallback. Keeps the caller's R channel
	76	// unencumbered: no host has to provide ErrorCapture for the wrapper to
	77	// typecheck; if it's there, we use it; if not, trace ids are empty.
	78	const resolveCapture = Effect.serviceOption(ErrorCapture).pipe(
	79	Effect.map((opt) =>
	80	Option.isSome(opt)
	81	? opt.value
	82	: ({ captureException: () => Effect.succeed("") } as const),
	83	),
	84	);
	85
	86	/**
	87	* HTTP-edge translator for `StorageFailure` on a single Effect. Two
	88	* cases:
	89	*
	90	* - `StorageError` — known backend failure. Capture the cause via
	91	* `ErrorCapture`, fail with `InternalError({ traceId })`.
	92	* - `UniqueViolationError` — invariant violation at the HTTP edge:
	93	* if a plugin wanted to surface a unique-conflict as a typed
	94	* domain error (e.g. "source already exists") it should
	95	* `Effect.catchTag` inside its own method and translate. Anything
	96	* that reaches here is unexpected, so we `Effect.die` and let the
	97	* observability middleware capture it as a defect.
	98	*
	99	* Every other typed failure (plugin-domain errors, etc.) passes
	100	* through unchanged.
	101	*/
	102	export const capture = <A, E, R>(
	103	eff: Effect.Effect<A, E, R>,
	104	): Effect.Effect<A, Exclude<E, StorageFailure> \| InternalError, R> =>
	105	(eff as Effect.Effect<A, E \| StorageFailure, R>).pipe(
	106	Effect.catchTag("UniqueViolationError", (err) => Effect.die(err)),
	107	Effect.catchTag("StorageError", (err) =>
	108	resolveCapture.pipe(
	109	Effect.flatMap((c) => c.captureException(Cause.fail(err))),
	110	Effect.flatMap((traceId) =>
	111	Effect.fail(new InternalError({ traceId })),
	112	),
	113	),
	114	),
	115	) as Effect.Effect<A, Exclude<E, StorageFailure> \| InternalError, R>;
	116
	117	/**
	118	* Edge defect catchall. Builds an `HttpApiBuilder.middleware` layer
	119	* that wraps the HttpApp once. Captures any cause (defects, interrupts,
	120	* unmapped failures the framework couldn't encode) via `ErrorCapture`
	121	* and returns a typed `InternalError({ traceId })` body.
	122	*
	123	* `ErrorCapture` is OPTIONAL — if the host hasn't wired one up the
	124	* middleware still fires but the trace id will be empty.
	125	*
	126	* Should rarely fire when the edge is well-wired — storage failures
	127	* are already translated by `withCapture` at service construction;
	128	* plugin-domain errors flow through their schemas. This is the net
	129	* for anything that slipped through.
	130	*/
	131	export const observabilityMiddleware = <
	132	Id extends string,
	133	Groups extends HttpApiGroup.HttpApiGroup.Any,
	134	E,
	135	R,
	136	>(
	137	api: HttpApi.HttpApi<Id, Groups, E, R>,
	138	): Layer.Layer<never> =>
	139	HttpApiBuilder.middleware(
	140	api,
	141	Effect.gen(function* () {
	142	const c = yield* resolveCapture;
	143	return (httpApp) =>
	144	Effect.catchAllCause(httpApp, (cause) =>
	145	Effect.gen(function* () {
	146	const traceId = yield* c.captureException(cause);
	147	return HttpServerResponse.unsafeJson(
	148	new InternalError({ traceId }),
	149	{ status: 500 },
	150	);
	151	}),
	152	);
	153	}),
	154	{ withContext: true },
	155	);

packages/core/api/src/scope/api.ts+5−3

 import { Schema } from "effect";
 import { ScopeId } from "@executor/sdk";
+import { InternalError } from "../observability";
 // ---------------------------------------------------------------------------
 // Response schemas
 // ---------------------------------------------------------------------------
 // Group
 // ---------------------------------------------------------------------------
-export class ScopeApi extends HttpApiGroup.make("scope").add(
+export class ScopeApi extends HttpApiGroup.make("scope")
-  HttpApiEndpoint.get("info")`/scope`.addSuccess(ScopeInfoResponse),
+  .add(HttpApiEndpoint.get("info")`/scope`.addSuccess(ScopeInfoResponse))
-) {}
+  .addError(InternalError) {}

packages/core/api/src/secrets/api.ts+4−1

 import { Schema } from "effect";
 import { ScopeId, SecretId, SecretNotFoundError, SecretResolutionError } from "@executor/sdk";
+import { InternalError } from "../observability";
 // ---------------------------------------------------------------------------
 // Params
 // ---------------------------------------------------------------------------
     HttpApiEndpoint.del("remove")`/scopes/${scopeIdParam}/secrets/${secretIdParam}`
       .addSuccess(Schema.Struct({ removed: Schema.Boolean }))
       .addError(SecretNotFound),
-  ) {}
+  )
+  .addError(InternalError) {}

packages/core/api/src/services.ts+4−1

 import type { Executor } from "@executor/sdk";
 import type { ExecutionEngine } from "@executor/execution";
-export class ExecutorService extends Context.Tag("ExecutorService")<ExecutorService, Executor>() {}
+export class ExecutorService extends Context.Tag("ExecutorService")<
+  ExecutorService,
+  Executor
+>() {}
 export class ExecutionEngineService extends Context.Tag("ExecutionEngineService")<
   ExecutionEngineService,

packages/core/api/src/sources/api.ts+16−5

 import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "@effect/platform";
 import { Schema } from "effect";
-import { ScopeId, ToolId } from "@executor/sdk";
+import { ScopeId, SourceRemovalNotAllowedError, ToolId } from "@executor/sdk";
+import { InternalError } from "../observability";
 // ---------------------------------------------------------------------------
 // Params
   namespace: Schema.String,
 });
+// ---------------------------------------------------------------------------
+// Error schemas with HTTP status annotations
+// ---------------------------------------------------------------------------
+const SourceRemovalNotAllowed = SourceRemovalNotAllowedError.annotations(
+  HttpApiSchema.annotations({ status: 409 }),
+);
 // ---------------------------------------------------------------------------
 // Group
 // ---------------------------------------------------------------------------
     ),
   )
   .add(
-    HttpApiEndpoint.del("remove")`/scopes/${scopeIdParam}/sources/${sourceIdParam}`.addSuccess(
+    HttpApiEndpoint.del("remove")`/scopes/${scopeIdParam}/sources/${sourceIdParam}`
-      SourceRemoveResponse,
+      .addSuccess(SourceRemoveResponse)
-    ),
+      .addError(SourceRemovalNotAllowed),
   )
   .add(
     HttpApiEndpoint.post(
     HttpApiEndpoint.post("detect")`/scopes/${scopeIdParam}/sources/detect`
       .setPayload(DetectRequest)
       .addSuccess(Schema.Array(DetectResultResponse)),
-  ) {}
+  )
+  .addError(InternalError) {}

packages/core/api/src/tools/api.ts+4−1

 import { Schema } from "effect";
 import { ScopeId, ToolId, ToolNotFoundError } from "@executor/sdk";
+import { InternalError } from "../observability";
 // ---------------------------------------------------------------------------
 // Params
 // ---------------------------------------------------------------------------
     HttpApiEndpoint.get("schema")`/scopes/${scopeIdParam}/tools/${toolIdParam}/schema`
       .addSuccess(ToolSchemaResponse)
       .addError(ToolNotFound),
-  ) {}
+  )
+  .addError(InternalError) {}

packages/core/api/vitest.config.ts+7−0

@@ -0,0 +1,7 @@
	1	import { defineConfig } from "vitest/config";
	2
	3	export default defineConfig({
	4	test: {
	5	include: ["src/*/.test.ts"],
	6	},
	7	});

packages/core/sdk/package.json+1−0

@@ -44,6 +44,7 @@ · 43 unmodified lines
44	"typecheck:slow": "tsc --noEmit"	44	"typecheck:slow": "tsc --noEmit"
45	},	45	},
46	"dependencies": {	46	"dependencies": {
		47	"@effect/platform": "catalog:",
47	"@executor/storage-core": "workspace:*",	48	"@executor/storage-core": "workspace:*",
48	"effect": "catalog:"	49	"effect": "catalog:"
49	},	50	},

packages/core/sdk/src/blob.ts+21−8

 //
 // Plugins see a `ScopedBlobStore` that's already namespaced to the plugin
 // id, so key collisions across plugins are structurally impossible.
+//
+// Error channel is `StorageError` — blobs only do read/write/delete, so
+// they never produce `UniqueViolationError`. The HTTP edge translates
+// `StorageError` to the opaque public `InternalError({ traceId })`.
 // ---------------------------------------------------------------------------
 import { Effect } from "effect";
+import { StorageError } from "@executor/storage-core";
 export interface BlobStore {
   readonly get: (
     namespace: string,
     key: string,
-  ) => Effect.Effect<string | null, Error>;
+  ) => Effect.Effect<string | null, StorageError>;
   readonly put: (
     namespace: string,
     key: string,
     value: string,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageError>;
   readonly delete: (
     namespace: string,
     key: string,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageError>;
   readonly has: (
     namespace: string,
     key: string,
-  ) => Effect.Effect<boolean, Error>;
+  ) => Effect.Effect<boolean, StorageError>;
 }
 export interface ScopedBlobStore {
-  readonly get: (key: string) => Effect.Effect<string | null, Error>;
+  readonly get: (key: string) => Effect.Effect<string | null, StorageError>;
-  readonly put: (key: string, value: string) => Effect.Effect<void, Error>;
+  readonly put: (
-  readonly delete: (key: string) => Effect.Effect<void, Error>;
+    key: string,
-  readonly has: (key: string) => Effect.Effect<boolean, Error>;
+    value: string,
+  ) => Effect.Effect<void, StorageError>;
+  readonly delete: (key: string) => Effect.Effect<void, StorageError>;
+  readonly has: (key: string) => Effect.Effect<boolean, StorageError>;
 }
 export const scopeBlobStore = (
  * Minimal in-memory BlobStore — good for tests and trivial hosts. Real
  * backends (filesystem, S3/R2, SQLite-table-backed) implement the same
  * interface.
+ *
+ * Every method is `Effect<_, never>` — a pure in-memory Map can't fail.
+ * `never` is assignable to `StorageError`, so the result still fits the
+ * `BlobStore` interface.
  */
 export const makeInMemoryBlobStore = (): BlobStore => {
   const store = new Map<string, string>();

packages/core/sdk/src/error-handling.test.ts+179−0

@@ -0,0 +1,179 @@
	1	// ---------------------------------------------------------------------------
	2	// Typed-error model — SDK-level behavioural tests.
	3	//
	4	// The happy-path tests in executor.test.ts don't exercise storage-failure
	5	// propagation because the in-memory adapter never fails. These tests
	6	// inject a deliberately failing adapter and verify the SDK surface:
	7	//
	8	// 1. `StorageError` from a backend surfaces raw in the typed error
	9	// channel — no telemetry, no InternalError translation. The HTTP
	10	// edge (`@executor/api` `withCapture`) is the one layer
	11	// that translates to the opaque InternalError; non-HTTP consumers
	12	// (CLI, Promise SDK, tests, plugins) can react to the raw tag.
	13	// 2. `UniqueViolationError` also passes through raw — plugin code
	14	// can `Effect.catchTag` and translate to its own user-facing
	15	// typed error.
	16	// 3. `createExecutor` has no ErrorCapture requirement at all — no
	17	// service lookup, no R channel leak.
	18	//
	19	// See `notes/error-handling.md` for the architectural overview and
	20	// `@executor/api` `observability.test.ts` for the edge-translation
	21	// tests.
	22	// ---------------------------------------------------------------------------
	23
	24	import { describe, expect, it } from "@effect/vitest";
	25	import { Effect } from "effect";
	26
	27	import {
	28	StorageError,
	29	UniqueViolationError,
	30	type DBAdapter,
	31	type DBTransactionAdapter,
	32	type StorageFailure,
	33	} from "@executor/storage-core";
	34	import { makeInMemoryBlobStore } from "./blob";
	35	import { createExecutor } from "./executor";
	36	import { ScopeId } from "./ids";
	37	import { defineSchema, definePlugin } from "./plugin";
	38	import { Scope } from "./scope";
	39
	40	// ---------------------------------------------------------------------------
	41	// Test helpers — an adapter that deterministically fails every method
	42	// with a chosen StorageFailure, and a scope fixture.
	43	// ---------------------------------------------------------------------------
	44
	45	const makeFailingAdapter = (failure: StorageFailure): DBAdapter => {
	46	const fail = () =>
	47	Effect.fail(failure) as Effect.Effect<never, StorageFailure, never>;
	48	return {
	49	id: "failing",
	50	create: fail as DBAdapter["create"],
	51	createMany: fail as DBAdapter["createMany"],
	52	findOne: fail as DBAdapter["findOne"],
	53	findMany: fail as DBAdapter["findMany"],
	54	count: fail as DBAdapter["count"],
	55	update: fail as DBAdapter["update"],
	56	updateMany: fail as DBAdapter["updateMany"],
	57	delete: fail as DBAdapter["delete"],
	58	deleteMany: fail as DBAdapter["deleteMany"],
	59	transaction: ((callback: (trx: DBTransactionAdapter) => unknown) => {
	60	void callback;
	61	return Effect.fail(failure);
	62	}) as DBAdapter["transaction"],
	63	};
	64	};
	65
	66	const testScope = new Scope({
	67	id: ScopeId.make("test-scope"),
	68	name: "test",
	69	createdAt: new Date(),
	70	});
	71
	72	const baseConfig = (adapter: DBAdapter) => ({
	73	scope: testScope,
	74	adapter,
	75	blobs: makeInMemoryBlobStore(),
	76	});
	77
	78	// ---------------------------------------------------------------------------
	79	// Tests
	80	// ---------------------------------------------------------------------------
	81
	82	describe("typed-error edge model — SDK", () => {
	83	it.effect("StorageError propagates raw through the executor surface", () =>
	84	Effect.gen(function* () {
	85	const failure = new StorageError({
	86	message: "backend lost its mind",
	87	cause: new Error("driver kaboom"),
	88	});
	89	const executor = yield* createExecutor(
	90	baseConfig(makeFailingAdapter(failure)),
	91	);
	92
	93	const result = yield* executor.tools.list().pipe(Effect.flip);
	94	expect(result).toBeInstanceOf(StorageError);
	95	expect(result._tag).toBe("StorageError");
	96	// Original cause preserved end-to-end.
	97	const storageErr = result as StorageError;
	98	expect(storageErr.message).toBe("backend lost its mind");
	99	expect(storageErr.cause).toBeInstanceOf(Error);
	100	expect((storageErr.cause as Error).message).toBe("driver kaboom");
	101	}),
	102	);
	103
	104	// ---------------------------------------------------------------------------
	105	// UniqueViolationError propagates unchanged — plugins can catchTag it.
	106	// Build a tiny plugin whose storage method calls adapter.create and
	107	// whose extension method exposes a method that catches
	108	// UniqueViolationError and resolves with a sentinel. If the catch
	109	// fires, UniqueViolationError reached the plugin code intact.
	110	// ---------------------------------------------------------------------------
	111
	112	const uniqueSchema = defineSchema({
	113	thing: {
	114	fields: {
	115	id: { type: "string", required: true },
	116	},
	117	},
	118	});
	119
	120	const uniqueTestPlugin = definePlugin(() => ({
	121	id: "uniq-test" as const,
	122	schema: uniqueSchema,
	123	storage: ({ adapter }) => ({
	124	tryCreate: (id: string) =>
	125	adapter
	126	.create({
	127	model: "thing",
	128	data: { id },
	129	forceAllowId: true,
	130	})
	131	.pipe(
	132	Effect.catchTag("UniqueViolationError", (err) =>
	133	Effect.succeed({
	134	caught: true as const,
	135	model: err.model ?? null,
	136	}),
	137	),
	138	Effect.map((r) =>
	139	"caught" in r ? r : { caught: false as const, model: null },
	140	),
	141	),
	142	}),
	143	extension: (ctx) => ({
	144	create: (id: string) => ctx.storage.tryCreate(id),
	145	}),
	146	}));
	147
	148	it.effect("UniqueViolationError propagates through plugin code (catchTag works)", () =>
	149	Effect.gen(function* () {
	150	const failure = new UniqueViolationError({ model: "thing" });
	151	const executor = yield* createExecutor({
	152	...baseConfig(makeFailingAdapter(failure)),
	153	plugins: [uniqueTestPlugin()] as const,
	154	});
	155
	156	const result = yield* executor["uniq-test"].create("abc");
	157	expect(result.caught).toBe(true);
	158	expect(result.model).toBe("thing");
	159	}),
	160	);
	161
	162	it.effect("createExecutor has no ErrorCapture requirement (no R leak)", () =>
	163	Effect.gen(function* () {
	164	// No `.pipe(Effect.provide(...))` anywhere; just run. If the SDK
	165	// still required any observability service, this wouldn't
	166	// type-check (R would leak) nor run (would crash at construction).
	167	const executor = yield* createExecutor(
	168	baseConfig(
	169	makeFailingAdapter(
	170	new StorageError({ message: "doesn't matter", cause: undefined }),
	171	),
	172	),
	173	);
	174	// Sanity: the executor surface exists and methods are callable.
	175	expect(typeof executor.tools.list).toBe("function");
	176	expect(typeof executor.sources.list).toBe("function");
	177	}),
	178	);
	179	});

packages/core/sdk/src/executor.test.ts+6−1

         }),
       );
+      // The collision is treated as an internal/programmer error and
+      // surfaces as raw `StorageError` in the typed channel. The HTTP
+      // edge (`@executor/api` `withCapture`) is responsible for
+      // translating it to the opaque `InternalError({ traceId })` when
+      // crossing the wire; here, at the SDK layer, we expect the raw tag.
       const err = yield* executor.collide.tryRegister().pipe(Effect.flip);
-      expect(err.message).toContain("collides with a static source");
+      expect(err._tag).toBe("StorageError");
     }),
   );

packages/core/sdk/src/executor.ts+85−47

 import { Effect, FiberRef } from "effect";
 import {
+  StorageError,
   typedAdapter,
   type DBAdapter,
   type DBSchema,
   type DBTransactionAdapter,
+  type StorageFailure,
   type TypedAdapter,
 } from "@executor/storage-core";
   readonly tools: {
     readonly list: (
       filter?: ToolListFilter,
-    ) => Effect.Effect<readonly Tool[], Error>;
+    ) => Effect.Effect<readonly Tool[], StorageFailure>;
     /** Fetch a tool's full schema view: JSON schemas with `$defs`
      *  attached from the core `definition` table, plus TypeScript
      *  preview strings rendered from them. Returns `null` for unknown
      *  tool ids. */
     readonly schema: (
       toolId: string,
-    ) => Effect.Effect<ToolSchema | null, Error>;
+    ) => Effect.Effect<ToolSchema | null, StorageFailure>;
     /** Every `$defs` entry across every source, grouped by source id.
      *  Used for bulk schema export and downstream TypeScript rendering. */
     readonly definitions: () => Effect.Effect<
       Record<string, Record<string, unknown>>,
-      Error
+      StorageFailure
     >;
     readonly invoke: (
       toolId: string,
       | NoHandlerError
       | ToolInvocationError
       | ElicitationDeclinedError
-      | Error
+      | StorageFailure
     >;
   };
   readonly sources: {
-    readonly list: () => Effect.Effect<readonly Source[], Error>;
+    readonly list: () => Effect.Effect<readonly Source[], StorageFailure>;
     readonly remove: (
       sourceId: string,
-    ) => Effect.Effect<void, SourceRemovalNotAllowedError | Error>;
+    ) => Effect.Effect<void, SourceRemovalNotAllowedError | StorageFailure>;
-    readonly refresh: (sourceId: string) => Effect.Effect<void, Error>;
+    readonly refresh: (sourceId: string) => Effect.Effect<void, StorageFailure>;
     /** URL autodetection — fans out to every plugin's `detect` hook
      *  (if declared), returns every high/medium/low-confidence match.
      *  UI picks a winner from the list. */
     readonly detect: (
       url: string,
-    ) => Effect.Effect<readonly SourceDetectionResult[], Error>;
+    ) => Effect.Effect<readonly SourceDetectionResult[], StorageFailure>;
     /** All `$defs` registered for a single source, keyed by def name. */
     readonly definitions: (
       sourceId: string,
-    ) => Effect.Effect<Record<string, unknown>, Error>;
+    ) => Effect.Effect<Record<string, unknown>, StorageFailure>;
   };
   readonly secrets: {
-    readonly get: (id: string) => Effect.Effect<string | null, Error>;
+    readonly get: (
+      id: string,
+    ) => Effect.Effect<string | null, StorageFailure>;
     /** Fast-path existence check — hits the core `secret` routing table
      *  only, never calls the provider. Use this for UI state ("secret
      *  missing, prompt to add") to avoid keychain permission prompts
      *  or 1password IPC roundtrips on a pre-flight check. */
     readonly status: (
       id: string,
-    ) => Effect.Effect<"resolved" | "missing", Error>;
+    ) => Effect.Effect<"resolved" | "missing", StorageFailure>;
-    readonly set: (input: SetSecretInput) => Effect.Effect<SecretRef, Error>;
+    readonly set: (
-    readonly remove: (id: string) => Effect.Effect<void, Error>;
+      input: SetSecretInput,
-    readonly list: () => Effect.Effect<readonly SecretRef[], Error>;
+    ) => Effect.Effect<SecretRef, StorageFailure>;
+    readonly remove: (id: string) => Effect.Effect<void, StorageFailure>;
+    readonly list: () => Effect.Effect<readonly SecretRef[], StorageFailure>;
     readonly providers: () => Effect.Effect<readonly string[]>;
   };
-  readonly close: () => Effect.Effect<void, Error>;
+  readonly close: () => Effect.Effect<void, StorageFailure>;
 } & PluginExtensions<TPlugins>;
 export interface ExecutorConfig<
   core: TypedAdapter<CoreSchema>,
   pluginId: string,
   input: SourceInput,
-): Effect.Effect<void, Error> =>
+): Effect.Effect<void, StorageFailure> =>
   Effect.gen(function* () {
     yield* deleteSourceById(core, input.id);
 const deleteSourceById = (
   core: TypedAdapter<CoreSchema>,
   sourceId: string,
-): Effect.Effect<void, Error> =>
+): Effect.Effect<void, StorageFailure> =>
   Effect.gen(function* () {
     yield* core.deleteMany({
       model: "tool",
   core: TypedAdapter<CoreSchema>,
   pluginId: string,
   input: DefinitionsInput,
-): Effect.Effect<void, Error> =>
+): Effect.Effect<void, StorageFailure> =>
   Effect.gen(function* () {
     yield* core.deleteMany({
       model: "definition",
     // without a list() implementation (keychain) never hit the fallback
     // walk because their secrets must be registered through set() to
     // be known at all.
-    // ------------------------------------------------------------------
+    const secretsGet = (
-    const secretsGet = (id: string): Effect.Effect<string | null, Error> =>
+      id: string,
+    ): Effect.Effect<string | null, StorageFailure> =>
       Effect.gen(function* () {
         // Fast path: routing table
         const row = yield* core.findOne({
     const secretsSet = (
       input: SetSecretInput,
-    ): Effect.Effect<SecretRef, Error> =>
+    ): Effect.Effect<SecretRef, StorageFailure> =>
       Effect.gen(function* () {
-        // Pick provider: explicit or first-writable.
+        // Pick provider: explicit or first-writable. Misconfiguration
+        // (unknown provider, no writable provider, read-only provider)
+        // is a host setup bug — surface as `StorageError` so it lands
+        // as a captured InternalError(traceId) at the SDK boundary.
         let target: SecretProvider | undefined;
         if (input.provider) {
           target = secretProviders.get(input.provider);
           if (!target) {
             return yield* Effect.fail(
-              new Error(`Unknown secret provider: ${input.provider}`),
+              new StorageError({
+                message: `Unknown secret provider: ${input.provider}`,
+                cause: undefined,
+              }),
             );
           }
         } else {
           }
           if (!target) {
             return yield* Effect.fail(
-              new Error("No writable secret providers registered"),
+              new StorageError({
+                message: "No writable secret providers registered",
+                cause: undefined,
+              }),
             );
           }
         }
         if (!target.writable || !target.set) {
           return yield* Effect.fail(
-            new Error(`Secret provider "${target.key}" is read-only`),
+            new StorageError({
+              message: `Secret provider "${target.key}" is read-only`,
+              cause: undefined,
+            }),
           );
         }
         });
       });
-    const secretsRemove = (id: string): Effect.Effect<void, Error> =>
+    const secretsRemove = (id: string): Effect.Effect<void, StorageFailure> =>
       Effect.gen(function* () {
         // Providers don't coordinate on which of them own the id — they
         // each get asked. Most calls are no-ops; fan them out so one
     // so that routing information in the core table is authoritative.
     // Providers without a list() method (e.g. keychain) contribute
     // only via the core table path.
-    const secretsList = (): Effect.Effect<readonly SecretRef[], Error> =>
+    const secretsList = (): Effect.Effect<readonly SecretRef[], StorageFailure> =>
       Effect.gen(function* () {
         const byId = new Map<string, SecretRef>();
         );
       }
-      // `typedAdapter(adapter)` is a zero-cost cast at the type level —
+      // Plugin-facing typed view. `StorageError` and `UniqueViolationError`
-      // the runtime value IS the adapter, but the type is whatever the
+      // flow through the typed channel unchanged — plugins can
-      // plugin's schema declares. Plugins never import `typedAdapter` or
+      // `catchTag("UniqueViolationError", …)` to translate to their own
-      // `DBAdapter` themselves; they just destructure `{ adapter }` in
+      // user-facing errors; the HTTP edge (see @executor/api
-      // their storage factory and get a store typed to their own schema.
+      // `withCapture`) is responsible for translating any
+      // `StorageError` that still escapes into the opaque InternalError.
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const storageDeps: StorageDeps<any> = {
         scope,
                 // a static source id, or any of whose would-be tool ids
                 // collide with a static tool id. Tool ids are
                 // `${source_id}.${tool.name}` — static and dynamic
-                // share the same string space.
+                // share the same string space. Fails as `StorageError`
+                // so the HTTP edge surfaces it as `InternalError(traceId)`.
                 if (staticSources.has(input.id)) {
                   return yield* Effect.fail(
-                    new Error(
+                    new StorageError({
-                      `Source id "${input.id}" collides with a static source`,
+                      message: `Source id "${input.id}" collides with a static source`,
-                    ),
+                      cause: undefined,
+                    }),
                   );
                 }
                 for (const tool of input.tools) {
                   const fqid = `${input.id}.${tool.name}`;
                   if (staticTools.has(fqid)) {
                     return yield* Effect.fail(
-                      new Error(
+                      new StorageError({
-                        `Tool id "${fqid}" collides with a static tool`,
+                        message: `Tool id "${fqid}" collides with a static tool`,
-                      ),
+                        cause: undefined,
+                      }),
                     );
                   }
                 }
           },
         },
         secrets: {
-          get: secretsGet,
+          get: (id) => secretsGet(id),
-          list: secretsListForCtx,
+          list: () => secretsListForCtx(),
-          set: secretsSet,
+          set: (input) => secretsSet(input),
-          remove: secretsRemove,
+          remove: (id) => secretsRemove(id),
         },
         // Open one real tx boundary and route every nested write inside
         // `effect` through that same handle via the activeAdapterRef —
-        // see buildAdapterRouter above for the dispatch logic.
+        // see buildAdapterRouter above. Caller-typed errors (`E`)
+        // propagate unchanged; storage failures also stay typed
+        // (`StorageFailure`) so the HTTP edge wrapper can translate them.
         transaction: <A, E>(effect: Effect.Effect<A, E>) =>
-          adapter.transaction(() => effect) as Effect.Effect<A, E | Error>,
+          adapter.transaction(() => effect) as Effect.Effect<
+            A,
+            E | StorageFailure
+          >,
       };
       // Build extension FIRST so it's available as `self` when resolving
     // just to ask "does this exist?"
     const secretsStatus = (
       id: string,
-    ): Effect.Effect<"resolved" | "missing", Error> =>
+    ): Effect.Effect<"resolved" | "missing", StorageFailure> =>
       Effect.gen(function* () {
         const row = yield* core.findOne({
           model: "secret",
         }
       });
+    // Public Executor surface — storage-backed methods surface
+    // `StorageFailure` (StorageError | UniqueViolationError) raw. The
+    // HTTP edge wraps this surface with `withCapture` to
+    // translate `StorageError` → `InternalError({ traceId })`; non-HTTP
+    // consumers (CLI, Promise SDK, tests) see the raw typed channel.
     const base = {
       scope,
       tools: {
       close,
     };
-    return Object.assign(base, extensions) as Executor<TPlugins>;
+    // Cast through `unknown` because the impl effects can include
+    // `Error` from plugin-supplied callbacks (resolveAnnotations etc.) —
+    // those leak via the helper functions and won't be cleaned until
+    // every plugin tightens its surface to typed errors. The runtime
+    // shape matches `Executor<TPlugins>`.
+    return Object.assign(base, extensions) as unknown as Executor<TPlugins>;
   });

packages/core/sdk/src/index.ts+5−0

   DBSchema,
   DBFieldAttribute,
   DBFieldType,
+  StorageFailure,
   TypedAdapter,
   Where,
   WhereOperator,
 export { typedAdapter } from "@executor/storage-core";
+// Storage-layer typed errors (re-exported so plugin code can catchTag
+// `UniqueViolationError` without importing storage-core directly).
+export { StorageError, UniqueViolationError } from "@executor/storage-core";
 // IDs (branded)
 export { ScopeId, ToolId, SecretId, PolicyId } from "./ids";

packages/core/sdk/src/plugin.ts+35−16

 import type {
   DBAdapter,
   DBSchema,
+  StorageFailure,
   TypedAdapter,
 } from "@executor/storage-core";
 export interface StorageDeps<TSchema extends DBSchema | undefined = undefined> {
   readonly scope: Scope;
-  readonly adapter: TSchema extends DBSchema ? TypedAdapter<TSchema> : DBAdapter;
+  /**
+   * Plugin-facing typed adapter. Failures surface as raw `StorageFailure`
+   * (`StorageError` | `UniqueViolationError`). Plugins can
+   * `catchTag("UniqueViolationError", …)` to translate to their own
+   * user-facing errors. `StorageError` bubbles up; the HTTP edge (see
+   * `@executor/api` `withCapture`) is the one place that
+   * translates it to the opaque `InternalError({ traceId })`.
+   */
+  readonly adapter: TSchema extends DBSchema
+    ? TypedAdapter<TSchema, StorageFailure>
+    : DBAdapter;
   readonly blobs: ScopedBlobStore;
 }
   readonly core: {
     readonly sources: {
-      readonly register: (input: SourceInput) => Effect.Effect<void, Error>;
+      readonly register: (
-      readonly unregister: (sourceId: string) => Effect.Effect<void, Error>;
+        input: SourceInput,
+      ) => Effect.Effect<void, StorageFailure>;
+      readonly unregister: (
+        sourceId: string,
+      ) => Effect.Effect<void, StorageFailure>;
     };
     /** Register shared JSON-schema `$defs` for a source. Tool
      *  input/output schemas registered via `sources.register` can carry
     readonly definitions: {
       readonly register: (
         input: DefinitionsInput,
-      ) => Effect.Effect<void, Error>;
+      ) => Effect.Effect<void, StorageFailure>;
     };
   };
   readonly secrets: {
-    readonly get: (id: string) => Effect.Effect<string | null, Error>;
+    readonly get: (
+      id: string,
+    ) => Effect.Effect<string | null, StorageFailure>;
     readonly list: () => Effect.Effect<
       readonly { readonly id: string; readonly name: string; readonly provider: string }[],
-      Error
+      StorageFailure
     >;
     /** Write a secret value through a provider. Used by plugins that
      *  mint secrets on behalf of the user (OAuth2 token storage,
      *  `executor.secrets.set` on the host surface, but OAuth2 refresh
      *  and one-shot token capture from plugin-owned flows need it here
      *  too. Same routing rules as the host-level setter. */
-    readonly set: (input: SetSecretInput) => Effect.Effect<SecretRef, Error>;
+    readonly set: (
+      input: SetSecretInput,
+    ) => Effect.Effect<SecretRef, StorageFailure>;
     /** Delete a secret from its pinned provider and the core table. */
-    readonly remove: (id: string) => Effect.Effect<void, Error>;
+    readonly remove: (id: string) => Effect.Effect<void, StorageFailure>;
   };
   /** Run `effect` inside a database transaction. Wraps the underlying
    *  registration. */
   readonly transaction: <A, E>(
     effect: Effect.Effect<A, E>,
-  ) => Effect.Effect<A, E | Error>;
+  ) => Effect.Effect<A, E | StorageFailure>;
 }
 // ---------------------------------------------------------------------------
   readonly annotations?: ToolAnnotations;
   readonly handler: (
     input: StaticToolHandlerInput<TStore>,
-  ) => Effect.Effect<unknown, Error>;
+  ) => Effect.Effect<unknown, unknown>;
 }
 export interface StaticSourceDecl<TStore = unknown> {
    *  only static tools can omit it. */
   readonly invokeTool?: (
     input: InvokeToolInput<TStore>,
-  ) => Effect.Effect<unknown, Error>;
+  ) => Effect.Effect<unknown, unknown>;
   /** Bulk resolve annotations (requiresApproval, approvalDescription,
    *  mayElicit) for a set of tool rows under a single source. Called
     readonly ctx: PluginCtx<TStore>;
     readonly sourceId: string;
     readonly toolRows: readonly ToolRow[];
-  }) => Effect.Effect<Record<string, ToolAnnotations>, Error>;
+  }) => Effect.Effect<Record<string, ToolAnnotations>, unknown>;
   /** Called when `executor.sources.remove(id)` targets a source owned
    *  by this plugin. Plugin-side cleanup only; the executor deletes
    *  the same transaction. */
   readonly removeSource?: (
     input: SourceLifecycleInput<TStore>,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, unknown>;
   readonly refreshSource?: (
     input: SourceLifecycleInput<TStore>,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, unknown>;
   /** URL autodetection hook. When the user pastes a URL in the
    *  onboarding UI, `executor.sources.detect(url)` fans out to every
   readonly detect?: (input: {
     readonly ctx: PluginCtx<TStore>;
     readonly url: string;
-  }) => Effect.Effect<SourceDetectionResult | null, Error>;
+  }) => Effect.Effect<SourceDetectionResult | null, unknown>;
   /** Secret providers contributed by this plugin. Either a static
    *  array or a function of ctx (for providers that need per-instance
     | readonly SecretProvider[]
     | ((ctx: PluginCtx<TStore>) => readonly SecretProvider[]);
-  readonly close?: () => Effect.Effect<void, Error>;
+  readonly close?: () => Effect.Effect<void, unknown>;
 }
 export interface Plugin<

packages/core/sdk/src/promise-executor.ts+6−0

     plugins,
   };
+  // The SDK has no observability requirement; storage failures surface
+  // as raw `StorageError` / `UniqueViolationError` in the typed channel.
+  // `Effect.runPromise` turns them into Promise rejections — consumers
+  // get the tagged error as the rejected value. See
+  // notes/promise-sdk-typed-errors.md for the planned `runPromiseExit`
+  // rewrite that exposes the full error union to consumers.
   const effectExecutor = await Effect.runPromise(
     createEffectExecutor(effectConfig),
   );

packages/core/sdk/src/secrets.ts+14−6

 import { Effect, Schema } from "effect";
+import type { StorageFailure } from "@executor/storage-core";
 import { SecretId, ScopeId } from "./ids";
 // ---------------------------------------------------------------------------
    *  honours this before routing writes — trying to write to a
    *  read-only provider is an error, not a silent drop. */
   readonly writable: boolean;
-  /** Get a secret value by id. Returns null if not found. Errors are
+  /** Get a secret value by id. Returns null if not found. Failures
-   *  real failures (provider unreachable, decryption failed, etc.). */
+   *  (provider unreachable, decryption failed, etc.) surface as
-  readonly get: (id: string) => Effect.Effect<string | null, Error>;
+   *  `StorageFailure` — the executor treats a provider call the same
+   *  as a DB call; `StorageError` is captured at the HTTP edge to
+   *  `InternalError`, `UniqueViolationError` dies. */
+  readonly get: (id: string) => Effect.Effect<string | null, StorageFailure>;
   /** Set a secret value. Only called on writable providers. */
-  readonly set?: (id: string, value: string) => Effect.Effect<void, Error>;
+  readonly set?: (
+    id: string,
+    value: string,
+  ) => Effect.Effect<void, StorageFailure>;
   /** Delete a secret. Only called on writable providers. Returns true
    *  if something was deleted. */
-  readonly delete?: (id: string) => Effect.Effect<boolean, Error>;
+  readonly delete?: (id: string) => Effect.Effect<boolean, StorageFailure>;
   /** Enumerate known secret entries. Optional — not all backends can
    *  enumerate (env-backed providers, for example). */
   readonly list?: () => Effect.Effect<
     readonly { readonly id: string; readonly name: string }[],
-    Error
+    StorageFailure
   >;
 }

packages/core/storage-core/src/adapter.ts+28−24

 import type { Effect } from "effect";
+import type { StorageError, UniqueViolationError } from "./errors";
 import type { DBFieldAttribute, DBSchema } from "./schema";
+/** Error union every backend method may emit. */
+export type StorageFailure = StorageError | UniqueViolationError;
 // ---------------------------------------------------------------------------
 // Where clauses
 // ---------------------------------------------------------------------------
     select?: string[] | undefined;
     /** Preserve an `id` in `data` instead of discarding it. */
     forceAllowId?: boolean | undefined;
-  }) => Effect.Effect<R, Error>;
+  }) => Effect.Effect<R, StorageFailure>;
   /**
    * Insert multiple rows in one call. Backends that don't have native
     model: string;
     data: ReadonlyArray<Omit<T, "id">>;
     forceAllowId?: boolean | undefined;
-  }) => Effect.Effect<readonly R[], Error>;
+  }) => Effect.Effect<readonly R[], StorageFailure>;
   findOne: <T>(data: {
     model: string;
     where: Where[];
     select?: string[] | undefined;
     join?: JoinOption | undefined;
-  }) => Effect.Effect<T | null, Error>;
+  }) => Effect.Effect<T | null, StorageFailure>;
   findMany: <T>(data: {
     model: string;
       | undefined;
     offset?: number | undefined;
     join?: JoinOption | undefined;
-  }) => Effect.Effect<readonly T[], Error>;
+  }) => Effect.Effect<readonly T[], StorageFailure>;
   count: (data: {
     model: string;
     where?: Where[] | undefined;
-  }) => Effect.Effect<number, Error>;
+  }) => Effect.Effect<number, StorageFailure>;
   /**
    * ⚠︎ `update` may return `null` if multiple rows match — prefer `updateMany`
     model: string;
     where: Where[];
     update: Record<string, unknown>;
-  }) => Effect.Effect<T | null, Error>;
+  }) => Effect.Effect<T | null, StorageFailure>;
   updateMany: (data: {
     model: string;
     where: Where[];
     update: Record<string, unknown>;
-  }) => Effect.Effect<number, Error>;
+  }) => Effect.Effect<number, StorageFailure>;
-  delete: (data: { model: string; where: Where[] }) => Effect.Effect<void, Error>;
+  delete: (data: { model: string; where: Where[] }) => Effect.Effect<void, StorageFailure>;
-  deleteMany: (data: { model: string; where: Where[] }) => Effect.Effect<number, Error>;
+  deleteMany: (data: { model: string; where: Where[] }) => Effect.Effect<number, StorageFailure>;
   /**
    * Run operations in a transaction. Backends without transaction support
    */
   transaction: <R, E>(
     callback: (trx: DBTransactionAdapter) => Effect.Effect<R, E>,
-  ) => Effect.Effect<R, E | Error>;
+  ) => Effect.Effect<R, E | StorageFailure>;
   /**
    * Optional migration-source generator. Forwarded verbatim from the
     | ((props: {
         file?: string | undefined;
         tables: DBSchema;
-      }) => Effect.Effect<DBAdapterSchemaCreation, Error>)
+      }) => Effect.Effect<DBAdapterSchemaCreation, StorageFailure>)
     | undefined;
   /**
     model: string;
     data: T;
     select?: string[] | undefined;
-  }) => Effect.Effect<T, Error>;
+  }) => Effect.Effect<T, StorageFailure>;
   /**
    * Native bulk insert. Required because over a real network (e.g.
   createMany: <T extends Record<string, unknown>>(data: {
     model: string;
     data: ReadonlyArray<T>;
-  }) => Effect.Effect<T[], Error>;
+  }) => Effect.Effect<T[], StorageFailure>;
   update: <T>(data: {
     model: string;
     where: CleanedWhere[];
     update: T;
-  }) => Effect.Effect<T | null, Error>;
+  }) => Effect.Effect<T | null, StorageFailure>;
   updateMany: (data: {
     model: string;
     where: CleanedWhere[];
     update: Record<string, unknown>;
-  }) => Effect.Effect<number, Error>;
+  }) => Effect.Effect<number, StorageFailure>;
   findOne: <T>(data: {
     model: string;
     where: CleanedWhere[];
     select?: string[] | undefined;
     join?: JoinConfig | undefined;
-  }) => Effect.Effect<T | null, Error>;
+  }) => Effect.Effect<T | null, StorageFailure>;
   findMany: <T>(data: {
     model: string;
     sortBy?: { field: string; direction: "asc" | "desc" } | undefined;
     offset?: number | undefined;
     join?: JoinConfig | undefined;
-  }) => Effect.Effect<T[], Error>;
+  }) => Effect.Effect<T[], StorageFailure>;
   delete: (data: {
     model: string;
     where: CleanedWhere[];
-  }) => Effect.Effect<void, Error>;
+  }) => Effect.Effect<void, StorageFailure>;
   deleteMany: (data: {
     model: string;
     where: CleanedWhere[];
-  }) => Effect.Effect<number, Error>;
+  }) => Effect.Effect<number, StorageFailure>;
   count: (data: {
     model: string;
     where?: CleanedWhere[] | undefined;
-  }) => Effect.Effect<number, Error>;
+  }) => Effect.Effect<number, StorageFailure>;
   /**
    * Optional migration-source generator — plugin authors use this to
     | ((props: {
         file?: string | undefined;
         tables: DBSchema;
-      }) => Effect.Effect<DBAdapterSchemaCreation, Error>)
+      }) => Effect.Effect<DBAdapterSchemaCreation, StorageFailure>)
     | undefined;
   options?: Record<string, unknown> | undefined;
         | false
         | (<R, E>(
             callback: (trx: DBTransactionAdapter) => Effect.Effect<R, E>,
-          ) => Effect.Effect<R, E | Error>)
+          ) => Effect.Effect<R, E | StorageFailure>)
       )
     | undefined;
   /** Skip id generation on `create`. @default false */
           | "count";
         model: string;
         schema: DBSchema;
-      }) => Effect.Effect<unknown, Error>)
+      }) => Effect.Effect<unknown, StorageFailure>)
     | undefined;
   /**
    * Per-field hook run inside the factory's read-path transform. Called
         select: readonly string[];
         model: string;
         schema: DBSchema;
-      }) => Effect.Effect<unknown, Error>)
+      }) => Effect.Effect<unknown, StorageFailure>)
     | undefined;
   /** Escape hatch — skip write-path transform entirely. @default false */
   disableTransformInput?: boolean | undefined;

packages/core/storage-core/src/errors.ts+42−0

@@ -0,0 +1,42 @@
	1	// ---------------------------------------------------------------------------
	2	// Storage-layer typed errors.
	3	//
	4	// Both are `Data.TaggedError` — runtime values, not wire schemas.
	5	// Storage-core stays out of HTTP / serialisation / telemetry concerns;
	6	// the HTTP edge (`@executor/api` `withCapture`) is the one place
	7	// that translates `StorageError` into the opaque public
	8	// `InternalError({ traceId })`. Plugins `Effect.catchTag("UniqueViolationError")`
	9	// and re-fail with their own schema'd error (e.g. `McpSourceAlreadyExistsError`).
	10	//
	11	// The `Data` choice (vs `Schema.TaggedError`) is enforcement: it's
	12	// physically impossible to `addError(...)` these on an HttpApi group, so
	13	// nobody can accidentally leak storage-layer details to clients by
	14	// letting them serialize through.
	15	// ---------------------------------------------------------------------------
	16
	17	import { Data } from "effect";
	18
	19	/**
	20	* Catch-all for non-recoverable backend failures (driver crash, network
	21	* gone, transaction abort the backend can't classify, etc.). The cause
	22	* travels as runtime data so the HTTP edge can capture it via
	23	* `ErrorCapture` before translating to the public `InternalError`.
	24	*/
	25	export class StorageError extends Data.TaggedError("StorageError")<{
	26	readonly message: string;
	27	readonly cause: unknown;
	28	}> {}
	29
	30	/**
	31	* Typed unique-constraint violation. Plugins are expected to
	32	* `Effect.catchTag` this and translate to their own user-facing error.
	33	* Carries an optional `model` so a plugin doing a batch insert across
	34	* tables can disambiguate; everything else (constraint name, raw
	35	* driver message) stays internal because plugin code rarely needs it
	36	* and surfacing it leaks backend specifics.
	37	*/
	38	export class UniqueViolationError extends Data.TaggedError(
	39	"UniqueViolationError",
	40	)<{
	41	readonly model?: string;
	42	}> {}

packages/core/storage-core/src/factory.ts+25−16

 //
 // Vendored from better-auth (packages/core/src/db/adapter/factory.ts) under
 // MIT. Adapted for executor:
-//   - Promise/async → Effect.Effect<T, Error>
+//   - Promise/async → Effect.Effect<T, StorageFailure>
 //   - Stripped auth-specific concerns (numeric serial ids, joins, telemetry
 //     spans, logger, plural model name resolution, BetterAuthOptions)
 //   - Contract matches our CustomAdapter + DBAdapterFactoryConfig in
   DBTransactionAdapter,
   JoinConfig,
   JoinOption,
+  StorageFailure,
   Where,
 } from "./adapter";
+import { StorageError } from "./errors";
 import type { DBFieldAttribute, DBSchema, DBPrimitive } from "./schema";
 // ---------------------------------------------------------------------------
     return defaultGenerateId();
   };
-  const getModelDef = (model: string): Effect.Effect<DBSchema[string], Error> =>
+  const getModelDef = (
+    model: string,
+  ): Effect.Effect<DBSchema[string], StorageError> =>
     Effect.gen(function* () {
       const def = schema[model];
       if (!def) {
         return yield* Effect.fail(
-          new Error(`[storage-core] unknown model "${model}"`),
+          new StorageError({
+            message: `[storage-core] unknown model "${model}"`,
+            cause: undefined,
+          }),
         );
       }
       return def;
     data: Record<string, unknown>,
     action: "create" | "update",
     forceAllowId: boolean,
-  ): Effect.Effect<Record<string, unknown>, Error> =>
+  ): Effect.Effect<Record<string, unknown>, StorageFailure> =>
     Effect.gen(function* () {
       const def = yield* getModelDef(model);
       const out: Record<string, unknown> = {};
           if (res && typeof (res as { then?: unknown }).then === "function") {
             value = yield* Effect.tryPromise({
               try: () => res as Promise<DBPrimitive>,
-              catch: (e) =>
+              catch: (cause) =>
-                new Error(
+                new StorageError({
-                  `[storage-core] transform.input for "${model}.${logical}" failed: ${String(e)}`,
+                  message: `[storage-core] transform.input for "${model}.${logical}" failed: ${cause instanceof Error ? cause.message : String(cause)}`,
-                ),
+                  cause,
+                }),
             });
           } else {
             value = res;
     model: string,
     row: Record<string, unknown> | null,
     select?: string[],
-  ): Effect.Effect<Record<string, unknown> | null, Error> =>
+  ): Effect.Effect<Record<string, unknown> | null, StorageFailure> =>
     Effect.gen(function* () {
       if (row === null || row === undefined) return null;
       const def = yield* getModelDef(model);
           if (res && typeof (res as { then?: unknown }).then === "function") {
             value = yield* Effect.tryPromise({
               try: () => res as Promise<DBPrimitive>,
-              catch: (e) =>
+              catch: (cause) =>
-                new Error(
+                new StorageError({
-                  `[storage-core] transform.output for "${model}.${logical}" failed: ${String(e)}`,
+                  message: `[storage-core] transform.output for "${model}.${logical}" failed: ${cause instanceof Error ? cause.message : String(cause)}`,
-                ),
+                  cause,
+                }),
             });
           } else {
             value = res;
     data: Record<string, unknown>,
     action: "create" | "update",
     forceAllowId: boolean,
-  ): Effect.Effect<Record<string, unknown>, Error> =>
+  ): Effect.Effect<Record<string, unknown>, StorageFailure> =>
     config.disableTransformInput
       ? Effect.succeed(data)
       : transformInput(model, data, action, forceAllowId);
     base: Record<string, unknown> | null,
     raw: Record<string, unknown> | null,
     join: JoinOption | undefined,
-  ): Effect.Effect<Record<string, unknown> | null, Error> =>
+  ): Effect.Effect<Record<string, unknown> | null, StorageFailure> =>
     Effect.gen(function* () {
       if (!base || !raw || !join) return base;
       const merged: Record<string, unknown> = { ...base };
     model: string,
     row: Record<string, unknown> | null,
     select?: string[],
-  ): Effect.Effect<Record<string, unknown> | null, Error> =>
+  ): Effect.Effect<Record<string, unknown> | null, StorageFailure> =>
     config.disableTransformOutput
       ? Effect.succeed(row)
       : transformOutput(model, row, select);

packages/core/storage-core/src/index.ts+3−0

 export { createAdapter, type CreateAdapterOptions } from "./factory";
+export { StorageError, UniqueViolationError } from "./errors";
 export {
   whereOperators,
   type WhereOperator,
   type DBAdapterDebugLogOption,
   type DBAdapterFactoryConfig,
   type DBAdapterSchemaCreation,
+  type StorageFailure,
 } from "./adapter";

packages/core/storage-core/src/testing/memory.ts+2−1

   DBAdapter,
   DBAdapterFactoryConfig,
   JoinConfig,
+  StorageFailure,
 } from "../adapter";
 import type { DBSchema } from "../schema";
 import { createAdapter } from "../factory";
         }),
       );
       return result;
-    }) as Effect.Effect<R, E | Error>;
+    }) as Effect.Effect<R, E | StorageFailure>;
   const adapter: DBAdapter = createAdapter({
     schema: options.schema,

packages/core/storage-core/src/typed.ts+19−11

 import type { Effect } from "effect";
-import type { DBAdapter, Where } from "./adapter";
+import type { DBAdapter, StorageFailure, Where } from "./adapter";
 import type {
   DBSchema,
   InferDBFieldsInput,
 > &
   Record<string, unknown>;
-export interface TypedAdapter<S extends DBSchema> {
+/**
+ * Schema-typed view over a `DBAdapter`. The error parameter `E`
+ * defaults to `StorageFailure` (`StorageError | UniqueViolationError`) —
+ * that's what backends emit and what plugin code sees. Translation
+ * to the opaque public `InternalError({ traceId })` is done only at
+ * the HTTP edge (`@executor/api` `withCapture`); everyone else
+ * works with the raw tag.
+ */
+export interface TypedAdapter<S extends DBSchema, E = StorageFailure> {
   readonly raw: DBAdapter;
   readonly create: <M extends keyof S & string>(data: {
     model: M;
     data: Omit<RowInput<S, M>, "id"> & { id?: string };
     forceAllowId?: boolean;
-  }) => Effect.Effect<RowOutput<S, M>, Error>;
+  }) => Effect.Effect<RowOutput<S, M>, E>;
   readonly createMany: <M extends keyof S & string>(data: {
     model: M;
     data: ReadonlyArray<Omit<RowInput<S, M>, "id"> & { id?: string }>;
     forceAllowId?: boolean;
-  }) => Effect.Effect<readonly RowOutput<S, M>[], Error>;
+  }) => Effect.Effect<readonly RowOutput<S, M>[], E>;
   readonly findOne: <M extends keyof S & string>(data: {
     model: M;
     where: Where[];
-  }) => Effect.Effect<RowOutput<S, M> | null, Error>;
+  }) => Effect.Effect<RowOutput<S, M> | null, E>;
   readonly findMany: <M extends keyof S & string>(data: {
     model: M;
     limit?: number;
     sortBy?: { field: string; direction: "asc" | "desc" };
     offset?: number;
-  }) => Effect.Effect<readonly RowOutput<S, M>[], Error>;
+  }) => Effect.Effect<readonly RowOutput<S, M>[], E>;
   readonly update: <M extends keyof S & string>(data: {
     model: M;
     where: Where[];
     update: Partial<RowInput<S, M>>;
-  }) => Effect.Effect<RowOutput<S, M> | null, Error>;
+  }) => Effect.Effect<RowOutput<S, M> | null, E>;
   readonly updateMany: <M extends keyof S & string>(data: {
     model: M;
     where: Where[];
     update: Partial<RowInput<S, M>>;
-  }) => Effect.Effect<number, Error>;
+  }) => Effect.Effect<number, E>;
   readonly delete: <M extends keyof S & string>(data: {
     model: M;
     where: Where[];
-  }) => Effect.Effect<void, Error>;
+  }) => Effect.Effect<void, E>;
   readonly deleteMany: <M extends keyof S & string>(data: {
     model: M;
     where: Where[];
-  }) => Effect.Effect<number, Error>;
+  }) => Effect.Effect<number, E>;
   readonly count: <M extends keyof S & string>(data: {
     model: M;
     where?: Where[];
-  }) => Effect.Effect<number, Error>;
+  }) => Effect.Effect<number, E>;
 }
 /**

packages/core/storage-drizzle/src/adapter.ts+162−61

 //
 // Vendored from better-auth (packages/drizzle-adapter/src/drizzle-adapter.ts)
 // under MIT. Adapted for executor:
-//   - Promise/async → Effect.Effect<T, Error>
+//   - Promise/async → Effect.Effect<T, StorageFailure>
 //   - Tables read from `db._.fullSchema` (drizzle schema introspection)
 //   - Relational queries via `db.query[model]` for join resolution
 //   - Filter/compile logic matches our CleanedWhere shape directly
   DBSchema,
   JoinConfig,
 } from "@executor/storage-core";
-import { createAdapter } from "@executor/storage-core";
+import {
+  StorageError,
+  UniqueViolationError,
+  createAdapter,
+} from "@executor/storage-core";
+// Mirrors `StorageFailure` from @executor/storage-core/adapter — kept
+// local so we don't force a new named export on the public index. Both
+// constructors are already exported, so the union is reconstructible.
+type StorageFailure = StorageError | UniqueViolationError;
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 // Promise → Effect helper
+//
+// Classifies postgres driver errors: `23505` (unique_violation) maps to
+// `UniqueViolationError`, everything else to `StorageError`. Sqlite
+// raises a `SQLITE_CONSTRAINT_UNIQUE` via a synchronous throw; we detect
+// that via the message since better-sqlite3's error code is on the
+// object too.
 // ---------------------------------------------------------------------------
+const isUniqueViolation = (cause: unknown): boolean => {
+  if (!cause || typeof cause !== "object") return false;
+  const c = cause as { code?: unknown; message?: unknown };
+  if (c.code === "23505") return true;
+  if (typeof c.code === "string" && c.code === "SQLITE_CONSTRAINT_UNIQUE") {
+    return true;
+  }
+  if (
+    typeof c.message === "string" &&
+    /unique constraint|UNIQUE constraint failed/i.test(c.message)
+  ) {
+    return true;
+  }
+  return false;
+};
+const classifyError = (
+  op: string,
+  model: string | undefined,
+  cause: unknown,
+): StorageFailure => {
+  if (isUniqueViolation(cause)) {
+    return model !== undefined
+      ? new UniqueViolationError({ model })
+      : new UniqueViolationError({});
+  }
+  return new StorageError({
+    message: `[storage-drizzle] ${op} failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+    cause,
+  });
+};
 const runPromise = <T>(
   op: string,
   fn: () => Promise<T>,
-): Effect.Effect<T, Error> =>
+  model?: string,
+): Effect.Effect<T, StorageFailure> =>
   Effect.tryPromise({
     try: fn,
-    catch: (e) =>
+    catch: (cause) => classifyError(op, model, cause),
-      new Error(
-        `[storage-drizzle] ${op} failed: ${e instanceof Error ? e.message : String(e)}`,
-      ),
   });
 // ---------------------------------------------------------------------------
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   builder: any,
   data: Record<string, unknown>,
-): Effect.Effect<Record<string, unknown>, Error> =>
+  model: string,
+): Effect.Effect<Record<string, unknown>, StorageFailure> =>
   Effect.gen(function* () {
     if (provider === "mysql") {
-      yield* runPromise("mysql insert execute", () => builder.execute());
+      yield* runPromise("mysql insert execute", () => builder.execute(), model);
       // best-effort: look up by id if present
       if (data.id !== undefined) {
-        const rows = (yield* runPromise("mysql select after insert", () =>
+        const rows = (yield* runPromise(
-          db.select().from(table).where(eq(table.id, data.id)).limit(1),
+          "mysql select after insert",
+          () => db.select().from(table).where(eq(table.id, data.id)).limit(1),
+          model,
         )) as Record<string, unknown>[];
         if (!rows[0])
           return yield* Effect.fail(
-            new Error("[storage-drizzle] mysql insert: no row returned"),
+            new StorageError({
+              message: "[storage-drizzle] mysql insert: no row returned",
+              cause: undefined,
+            }),
           );
         return rows[0];
       }
       return yield* Effect.fail(
-        new Error(
+        new StorageError({
-          "[storage-drizzle] mysql insert: id not provided, cannot recover row",
+          message:
-        ),
+            "[storage-drizzle] mysql insert: id not provided, cannot recover row",
+          cause: undefined,
+        }),
       );
     }
-    const rows = (yield* runPromise("insert returning", () =>
+    const rows = (yield* runPromise(
-      builder.returning(),
+      "insert returning",
+      () => builder.returning(),
+      model,
     )) as Record<string, unknown>[];
     if (!rows[0])
       return yield* Effect.fail(
-        new Error("[storage-drizzle] insert returned no rows"),
+        new StorageError({
+          message: "[storage-drizzle] insert returned no rows",
+          cause: undefined,
+        }),
       );
     return rows[0];
   });
       Effect.gen(function* () {
         const table = getTable(model);
         const builder = db.insert(table).values(data);
-        const row = yield* withReturning(db, provider, table, builder, data);
+        const row = yield* withReturning(
+          db,
+          provider,
+          table,
+          builder,
+          data,
+          model,
+        );
         return row as never;
       }),
         const all: Record<string, unknown>[] = [];
         for (let i = 0; i < data.length; i += CHUNK) {
           const slice = data.slice(i, i + CHUNK) as Record<string, unknown>[];
-          const rows = (yield* runPromise("insert many returning", () =>
+          const rows = (yield* runPromise(
-            db.insert(table).values(slice).returning(),
+            "insert many returning",
+            () => db.insert(table).values(slice).returning(),
+            model,
           )) as Record<string, unknown>[];
           for (const row of rows) all.push(row);
         }
         const clause = compileWhere(table, where, provider);
         if (join && db.query && db.query[model]) {
           const includes = buildIncludes(join);
-          const rows = (yield* runPromise("findOne query.findFirst", () =>
+          const rows = (yield* runPromise(
-            Promise.resolve(
+            "findOne query.findFirst",
-              db.query[model].findFirst({
+            () =>
-                where: clause,
+              Promise.resolve(
-                with: includes,
+                db.query[model].findFirst({
-              }),
+                  where: clause,
-            ),
+                  with: includes,
+                }),
+              ),
+            model,
           )) as Record<string, unknown> | undefined;
           return (rows ?? null) as never;
         }
         let q = db.select().from(table);
         if (clause) q = q.where(clause);
-        const rows = (yield* runPromise("findOne select", () =>
+        const rows = (yield* runPromise(
-          q.limit(1),
+          "findOne select",
+          () => q.limit(1),
+          model,
         )) as Record<string, unknown>[];
         return (rows[0] ?? null) as never;
       }),
             const fn = sortBy.direction === "desc" ? desc : asc;
             opts.orderBy = [fn(col)];
           }
-          const rows = (yield* runPromise("findMany query.findMany", () =>
+          const rows = (yield* runPromise(
-            Promise.resolve(db.query[model].findMany(opts)),
+            "findMany query.findMany",
+            () => Promise.resolve(db.query[model].findMany(opts)),
+            model,
           )) as Record<string, unknown>[];
           return rows as never[];
         }
         else if (offset !== undefined && provider === "sqlite")
           q = q.limit(Number.MAX_SAFE_INTEGER);
         if (offset !== undefined) q = q.offset(offset);
-        const rows = (yield* runPromise("findMany select", () =>
+        const rows = (yield* runPromise(
-          Promise.resolve(q),
+          "findMany select",
+          () => Promise.resolve(q),
+          model,
         )) as Record<string, unknown>[];
         return rows as never[];
       }),
         const clause = compileWhere(table, where, provider);
         let q = db.select({ c: count() }).from(table);
         if (clause) q = q.where(clause);
-        const rows = (yield* runPromise("count select", () =>
+        const rows = (yield* runPromise(
-          Promise.resolve(q),
+          "count select",
+          () => Promise.resolve(q),
+          model,
         )) as { c: number | string | bigint }[];
         const raw = rows[0]?.c ?? 0;
         return typeof raw === "number" ? raw : Number(raw);
         // Find matching rows first — if >1, DBAdapter contract says null
         let findQ = db.select().from(table);
         if (clause) findQ = findQ.where(clause);
-        const matched = (yield* runPromise("update pre-select", () =>
+        const matched = (yield* runPromise(
-          findQ.limit(2),
+          "update pre-select",
+          () => findQ.limit(2),
+          model,
         )) as Record<string, unknown>[];
         if (matched.length === 0) return null;
         if (matched.length > 1) return null;
         const target = matched[0]!;
         let updQ = db.update(table).set(update).where(eq(table.id, target.id));
         if (provider !== "mysql") {
-          const rows = (yield* runPromise("update returning", () =>
+          const rows = (yield* runPromise(
-            updQ.returning(),
+            "update returning",
+            () => updQ.returning(),
+            model,
           )) as Record<string, unknown>[];
           return (rows[0] ?? null) as never;
         }
-        yield* runPromise("mysql update execute", () => updQ.execute());
+        yield* runPromise(
-        const reread = (yield* runPromise("mysql update reread", () =>
+          "mysql update execute",
-          db.select().from(table).where(eq(table.id, target.id)).limit(1),
+          () => updQ.execute(),
+          model,
+        );
+        const reread = (yield* runPromise(
+          "mysql update reread",
+          () => db.select().from(table).where(eq(table.id, target.id)).limit(1),
+          model,
         )) as Record<string, unknown>[];
         return (reread[0] ?? null) as never;
       }),
         // but we don't want to rely on that in the generic path)
         let countQ = db.select({ c: count() }).from(table);
         if (clause) countQ = countQ.where(clause);
-        const rows = (yield* runPromise("updateMany count", () =>
+        const rows = (yield* runPromise(
-          Promise.resolve(countQ),
+          "updateMany count",
+          () => Promise.resolve(countQ),
+          model,
         )) as { c: number | string | bigint }[];
         const n = Number(rows[0]?.c ?? 0);
         if (n === 0) return 0;
         let updQ = db.update(table).set(update);
         if (clause) updQ = updQ.where(clause);
-        yield* runPromise("updateMany execute", () => Promise.resolve(updQ));
+        yield* runPromise(
+          "updateMany execute",
+          () => Promise.resolve(updQ),
+          model,
+        );
         return n;
       }),
         // Mirror in-memory semantics: delete first matching row only
         let findQ = db.select({ id: table.id }).from(table);
         if (clause) findQ = findQ.where(clause);
-        const matched = (yield* runPromise("delete pre-select", () =>
+        const matched = (yield* runPromise(
-          findQ.limit(1),
+          "delete pre-select",
+          () => findQ.limit(1),
+          model,
         )) as { id: unknown }[];
         const first = matched[0];
         if (!first) return;
-        yield* runPromise("delete exec", () =>
+        yield* runPromise(
-          Promise.resolve(db.delete(table).where(eq(table.id, first.id))),
+          "delete exec",
+          () => Promise.resolve(db.delete(table).where(eq(table.id, first.id))),
+          model,
         );
       }),
         const clause = compileWhere(table, where, provider);
         let countQ = db.select({ c: count() }).from(table);
         if (clause) countQ = countQ.where(clause);
-        const rows = (yield* runPromise("deleteMany count", () =>
+        const rows = (yield* runPromise(
-          Promise.resolve(countQ),
+          "deleteMany count",
+          () => Promise.resolve(countQ),
+          model,
         )) as { c: number | string | bigint }[];
         const n = Number(rows[0]?.c ?? 0);
         if (n === 0) return 0;
         let delQ = db.delete(table);
         if (clause) delQ = delQ.where(clause);
-        yield* runPromise("deleteMany exec", () => Promise.resolve(delQ));
+        yield* runPromise(
+          "deleteMany exec",
+          () => Promise.resolve(delQ),
+          model,
+        );
         return n;
       }),
   };
           }).pipe(
             Effect.mapError((e) => {
               if (e instanceof TxFailure) return e.inner;
-              return e instanceof Error ? e : new Error(String(e));
+              return classifyError("pg transaction", undefined, e);
             }),
-          ) as Effect.Effect<R, E | Error>;
+          ) as Effect.Effect<R, E | StorageFailure>;
         }
         return Effect.gen(function* () {
                 }
                 return res;
               },
-              catch: (e) =>
+              catch: (cause) => classifyError(stmt, undefined, cause),
-                new Error(
-                  `[storage-drizzle] ${stmt} failed: ${e instanceof Error ? e.message : String(e)}`,
-                ),
             });
           const maybePromise = yield* runStmt("BEGIN");
           if (maybePromise && typeof (maybePromise as { then?: unknown }).then === "function") {
             yield* Effect.tryPromise({
               try: () => maybePromise as Promise<unknown>,
-              catch: (e) => new Error(String(e)),
+              catch: (cause) => classifyError("BEGIN", undefined, cause),
             });
           }
           const nested = drizzleAdapter({
           if (commitRes && typeof (commitRes as { then?: unknown }).then === "function") {
             yield* Effect.tryPromise({
               try: () => commitRes as Promise<unknown>,
-              catch: (e) => new Error(String(e)),
+              catch: (cause) => classifyError("COMMIT", undefined, cause),
             });
           }
           return result;

packages/core/storage-file/src/blob-store.ts+7−3

 import { primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
 import type { BlobStore } from "@executor/sdk";
+import { StorageError } from "@executor/storage-core";
 export const blobTable = sqliteTable(
   "blob",
 const wrapErr =
   (op: string) =>
-  (e: unknown): Error => {
+  (cause: unknown): StorageError => {
-    const msg = e instanceof Error ? e.message : String(e);
+    const msg = cause instanceof Error ? cause.message : String(cause);
-    return new Error(`[storage-file] blob ${op}: ${msg}`);
+    return new StorageError({
+      message: `[storage-file] blob ${op}: ${msg}`,
+      cause,
+    });
   };
 export const makeSqliteBlobStore = (

packages/core/storage-postgres/src/blob-store.ts+7−3

 import { pgTable, primaryKey, text } from "drizzle-orm/pg-core";
 import type { BlobStore } from "@executor/sdk";
+import { StorageError } from "@executor/storage-core";
 export const blobTable = pgTable(
   "blob",
 const wrapErr =
   (op: string) =>
-  (e: unknown): Error => {
+  (cause: unknown): StorageError => {
-    const msg = e instanceof Error ? e.message : String(e);
+    const msg = cause instanceof Error ? cause.message : String(cause);
-    return new Error(`[storage-postgres] blob ${op}: ${msg}`);
+    return new StorageError({
+      message: `[storage-postgres] blob ${op}: ${msg}`,
+      cause,
+    });
   };
 export const makePostgresBlobStore = (

packages/plugins/file-secrets/src/index.ts+57−22

 import * as fs from "node:fs";
 import * as path from "node:path";
-import { definePlugin, type PluginCtx, type SecretProvider } from "@executor/sdk";
+import {
+  definePlugin,
+  StorageError,
+  type PluginCtx,
+  type SecretProvider,
+} from "@executor/sdk";
 // ---------------------------------------------------------------------------
 // XDG data dir resolution
 // ---------------------------------------------------------------------------
 // File I/O with restricted permissions
+//
+// These helpers throw on real I/O or decode failures — the provider wraps
+// every call in `Effect.try` so those throws surface as typed
+// `StorageError` on the Effect error channel. Previously `readFullFile`
+// used a blanket `try { ... } catch { return {}; }` which masked JSON
+// parse errors, schema decode failures, and permission errors as
+// "empty file", making misconfigured installs silently return null from
+// every `get`.
 // ---------------------------------------------------------------------------
 const readFullFile = (filePath: string): Record<string, Record<string, string>> => {
+  if (!fs.existsSync(filePath)) return {};
+  let raw: string;
   try {
-    if (!fs.existsSync(filePath)) return {};
+    raw = fs.readFileSync(filePath, "utf-8");
-    const raw = fs.readFileSync(filePath, "utf-8");
+  } catch (cause) {
-    return decodeScopedAuthFile(JSON.parse(raw));
+    // Treat "file disappeared between existsSync and readFileSync" as
-  } catch {
+    // absence — anything else (EACCES, EISDIR, …) propagates.
-    return {};
+    if ((cause as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw cause;
   }
+  return decodeScopedAuthFile(JSON.parse(raw));
 };
 const readScopeSecrets = (filePath: string, scopeId: string): Record<string, string> =>
 // Provider factory (internal)
 // ---------------------------------------------------------------------------
+const toStorageError = (cause: unknown) =>
+  new StorageError({
+    message: cause instanceof Error ? cause.message : String(cause),
+    cause,
+  });
 const makeScopedProvider = (filePath: string, scopeId: string): SecretProvider => ({
   key: "file",
   writable: true,
   get: (secretId) =>
-    Effect.sync(() => {
+    Effect.try({
-      const data = readScopeSecrets(filePath, scopeId);
+      try: () => {
-      return data[secretId] ?? null;
+        const data = readScopeSecrets(filePath, scopeId);
+        return data[secretId] ?? null;
+      },
+      catch: toStorageError,
     }),
   set: (secretId, value) =>
-    Effect.sync(() => {
+    Effect.try({
-      const data = readScopeSecrets(filePath, scopeId);
+      try: () => {
-      data[secretId] = value;
+        const data = readScopeSecrets(filePath, scopeId);
-      writeScopeSecrets(filePath, scopeId, data);
+        data[secretId] = value;
+        writeScopeSecrets(filePath, scopeId, data);
+      },
+      catch: toStorageError,
     }),
   delete: (secretId) =>
-    Effect.sync(() => {
+    Effect.try({
-      const data = readScopeSecrets(filePath, scopeId);
+      try: () => {
-      const had = secretId in data;
+        const data = readScopeSecrets(filePath, scopeId);
-      delete data[secretId];
+        const had = secretId in data;
-      if (had) writeScopeSecrets(filePath, scopeId, data);
+        delete data[secretId];
-      return had;
+        if (had) writeScopeSecrets(filePath, scopeId, data);
+        return had;
+      },
+      catch: toStorageError,
     }),
   list: () =>
-    Effect.sync(() => {
+    Effect.try({
-      const data = readScopeSecrets(filePath, scopeId);
+      try: () => {
-      return Object.keys(data).map((k) => ({ id: k, name: k }));
+        const data = readScopeSecrets(filePath, scopeId);
+        return Object.keys(data).map((k) => ({ id: k, name: k }));
+      },
+      catch: toStorageError,
     }),
 });

packages/plugins/google-discovery/src/api/group.ts+38−26

 import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "@effect/platform";
 import { Schema } from "effect";
 import { ScopeId } from "@executor/sdk";
+import { InternalError } from "@executor/api";
+import {
+  GoogleDiscoveryOAuthError,
+  GoogleDiscoveryParseError,
+  GoogleDiscoverySourceError,
+} from "../sdk/errors";
 import { GoogleDiscoveryStoredSourceSchema } from "../sdk/stored-source";
 export { HttpApiSchema };
   HttpApiSchema.annotations({ status: 400 }),
 ) {}
-export class GoogleDiscoveryInternalError extends Schema.TaggedError<GoogleDiscoveryInternalError>()(
+// ---------------------------------------------------------------------------
-  "GoogleDiscoveryInternalError",
+// Group
-  {
+//
-    message: Schema.String,
+// Domain errors + the shared opaque 500 (`InternalError`) are declared
-  },
+// once at the group level via `.addError(...)` — every endpoint
-  HttpApiSchema.annotations({ status: 500 }),
+// inherits them. The domain error carries its HTTP status via
-) {}
+// `HttpApiSchema.annotations`; `InternalError` is the public 5xx
+// surface, translated from `StorageError` at the HTTP edge by
+// `withCapture`. No per-endpoint `.addError(...)`, no per-handler
+// InternalError — handlers just `return yield* ext.foo(...)`.
+// ---------------------------------------------------------------------------
 export class GoogleDiscoveryGroup extends HttpApiGroup.make("googleDiscovery")
   .add(
     HttpApiEndpoint.post("probeDiscovery")`/scopes/${scopeIdParam}/google-discovery/probe`
       .setPayload(ProbePayload)
-      .addSuccess(ProbeResponse)
+      .addSuccess(ProbeResponse),
-      .addError(GoogleDiscoveryApiError)
-      .addError(GoogleDiscoveryInternalError),
   )
   .add(
     HttpApiEndpoint.post("addSource")`/scopes/${scopeIdParam}/google-discovery/sources`
       .setPayload(AddSourcePayload)
-      .addSuccess(AddSourceResponse)
+      .addSuccess(AddSourceResponse),
-      .addError(GoogleDiscoveryApiError)
-      .addError(GoogleDiscoveryInternalError),
   )
   .add(
     HttpApiEndpoint.post("startOAuth")`/scopes/${scopeIdParam}/google-discovery/oauth/start`
       .setPayload(StartOAuthPayload)
-      .addSuccess(StartOAuthResponse)
+      .addSuccess(StartOAuthResponse),
-      .addError(GoogleDiscoveryApiError)
-      .addError(GoogleDiscoveryInternalError),
   )
   .add(
     HttpApiEndpoint.post("completeOAuth")`/scopes/${scopeIdParam}/google-discovery/oauth/complete`
       .setPayload(CompleteOAuthPayload)
-      .addSuccess(CompleteOAuthResponse)
+      .addSuccess(CompleteOAuthResponse),
-      .addError(GoogleDiscoveryApiError)
-      .addError(GoogleDiscoveryInternalError),
   )
   .add(
     HttpApiEndpoint.get("oauthCallback")`/google-discovery/oauth/callback`
       .setUrlParams(OAuthCallbackParams)
-      .addSuccess(HtmlResponse)
+      .addSuccess(HtmlResponse),
-      .addError(GoogleDiscoveryApiError)
-      .addError(GoogleDiscoveryInternalError),
   )
   .add(
     HttpApiEndpoint.get(
       "getSource",
     )`/scopes/${scopeIdParam}/google-discovery/sources/${namespaceParam}`
-      .addSuccess(Schema.NullOr(GoogleDiscoveryStoredSourceSchema))
+      .addSuccess(Schema.NullOr(GoogleDiscoveryStoredSourceSchema)),
-      .addError(GoogleDiscoveryApiError)
+  )
-      .addError(GoogleDiscoveryInternalError),
+  // Errors declared once at the group level — every endpoint inherits.
-  ) {}
+  // `InternalError` is the shared opaque 500 translated at the HTTP edge
+  // by `withCapture`. The others are 4xx domain errors carrying their
+  // status via `HttpApiSchema.annotations`; handlers return them through
+  // the typed channel and HttpApi encodes them directly. We only list
+  // errors a Google Discovery *group* endpoint can surface —
+  // `GoogleDiscoveryInvocationError` is thrown inside `invokeTool` which
+  // is reached via the core `tools.invoke` endpoint, not any Google
+  // Discovery-group endpoint, so it doesn't belong here.
+  .addError(InternalError)
+  .addError(GoogleDiscoveryApiError)
+  .addError(GoogleDiscoveryOAuthError)
+  .addError(GoogleDiscoveryParseError)
+  .addError(GoogleDiscoverySourceError) {}

packages/plugins/google-discovery/src/api/handlers.test.ts+61−42

@@ -1,8 +1,17 @@
		1	// ---------------------------------------------------------------------------
		2	// Handler-level integration test for the Google Discovery group.
		3	//
		4	// Verifies the layer wiring stays coherent end-to-end: the handlers
		5	// pull the wrapped extension from the service, and any un-caught cause
		6	// lands in the observability middleware — producing a 500 whose body is
		7	// the opaque `InternalError` schema (no internal leakage).
		8	// ---------------------------------------------------------------------------
		9
1	import { HttpApiBuilder, HttpServer } from "@effect/platform";	10	import { HttpApiBuilder, HttpServer } from "@effect/platform";
2	import { describe, expect, it } from "vitest";	11	import { describe, expect, it } from "@effect/vitest";
3	import { Effect, Layer } from "effect";	12	import { Effect, Layer } from "effect";
4		13
5	import { addGroup } from "@executor/api";	14	import { addGroup, observabilityMiddleware } from "@executor/api";
6	import { CoreHandlers, ExecutionEngineService, ExecutorService } from "@executor/api/server";	15	import { CoreHandlers, ExecutionEngineService, ExecutorService } from "@executor/api/server";
7	import type { GoogleDiscoveryPluginExtension } from "../sdk/plugin";	16	import type { GoogleDiscoveryPluginExtension } from "../sdk/plugin";
8	import { GoogleDiscoveryExtensionService, GoogleDiscoveryHandlers } from "./handlers";	17	import { GoogleDiscoveryExtensionService, GoogleDiscoveryHandlers } from "./handlers";
@@ -10,57 +19,67 @@ import { GoogleDiscoveryGroup } from "./group"; · 1 unmodified line
10		19
11	const unused = Effect.dieMessage("unused");	20	const unused = Effect.dieMessage("unused");
12		21
13	const createFailingExtension = (): GoogleDiscoveryPluginExtension => ({	22	const failingExtension: GoogleDiscoveryPluginExtension = {
14	probeDiscovery: () => Effect.die(new Error("Not implemented")),	23	probeDiscovery: () => Effect.die(new Error("Not implemented")),
15	addSource: () => unused,	24	addSource: () => unused,
16	removeSource: () => unused,	25	removeSource: () => unused,
17	startOAuth: () => unused,	26	startOAuth: () => unused,
18	completeOAuth: () => Effect.die(new Error("Not implemented")),	27	completeOAuth: () => Effect.die(new Error("Not implemented")),
19	getSource: () => Effect.succeed(null),	28	getSource: () => Effect.succeed(null),
20	});	29	};
21		30
22	const Api = addGroup(GoogleDiscoveryGroup);	31	const Api = addGroup(GoogleDiscoveryGroup);
23		32
24	const fakeExecutor = {} as any;	33	// `acquireRelease` keeps disposal inside the Effect scope — no
25	const fakeExecutionEngine = {} as any;	34	// try/finally, no per-test cleanup plumbing. `it.scoped` closes the
26		35	// scope for us.
27	const createHandler = () =>	36	const WebHandler = Effect.acquireRelease(
28	HttpApiBuilder.toWebHandler(	37	Effect.sync(() =>
29	HttpApiBuilder.api(Api).pipe(	38	HttpApiBuilder.toWebHandler(
30	Layer.provide(CoreHandlers),	39	HttpApiBuilder.api(Api).pipe(
31	Layer.provide(GoogleDiscoveryHandlers),	40	Layer.provide(CoreHandlers),
32	Layer.provide(Layer.succeed(ExecutorService, fakeExecutor)),	41	Layer.provide(GoogleDiscoveryHandlers),
33	Layer.provide(Layer.succeed(ExecutionEngineService, fakeExecutionEngine)),	42	Layer.provide(observabilityMiddleware(Api)),
34	Layer.provide(Layer.succeed(GoogleDiscoveryExtensionService, createFailingExtension())),	43	Layer.provide(Layer.succeed(ExecutorService, {} as never)),
35	Layer.provideMerge(HttpServer.layerContext),	44	Layer.provide(Layer.succeed(ExecutionEngineService, {} as never)),
36	Layer.provideMerge(HttpApiBuilder.Router.Live),	45	Layer.provide(
37	Layer.provideMerge(HttpApiBuilder.Middleware.layer),	46	Layer.succeed(GoogleDiscoveryExtensionService, failingExtension),
		47	),
		48	Layer.provideMerge(HttpServer.layerContext),
		49	Layer.provideMerge(HttpApiBuilder.Router.Live),
		50	Layer.provideMerge(HttpApiBuilder.Middleware.layer),
		51	),
38	),	52	),
39	);	53	),
		54	(web) => Effect.promise(() => web.dispose()),
		55	);
40		56
41	describe("GoogleDiscoveryHandlers", () => {	57	describe("GoogleDiscoveryHandlers", () => {
42	it("sanitizes unknown endpoint failures", async () => {	58	it.scoped(
43	const web = createHandler();	59	"defect-returning methods produce an opaque InternalError, no leakage",
44	try {	60	() =>
45	const response = await web.handler(	61	Effect.gen(function* () {
46	new Request("http://localhost/scopes/scope_1/google-discovery/probe", {	62	const web = yield* WebHandler;
47	method: "POST",	63	const response = yield* Effect.promise(() =>
48	headers: { "content-type": "application/json" },	64	web.handler(
49	body: JSON.stringify({	65	new Request("http://localhost/scopes/scope_1/google-discovery/probe", {
50	discoveryUrl: "https://example.googleapis.com/$discovery/rest?version=v1",	66	method: "POST",
51	}),	67	headers: { "content-type": "application/json" },
52	}),	68	body: JSON.stringify({
53	);	69	discoveryUrl: "https://example.googleapis.com/$discovery/rest?version=v1",
		70	}),
		71	}),
		72	),
		73	);
54		74
55	expect(response.status).toBe(500);	75	expect(response.status).toBe(500);
56	const body = await response.json();	76	const body = (yield* Effect.promise(() => response.json())) as {
57	expect(body).toEqual({	77	_tag?: string;
58	_tag: "GoogleDiscoveryInternalError",	78	traceId?: string;
59	message: "Internal server error",	79	};
60	});	80	expect(body._tag).toBe("InternalError");
61	expect(JSON.stringify(body)).not.toContain("Not implemented");	81	expect(typeof body.traceId).toBe("string");
62	} finally {	82	expect(JSON.stringify(body)).not.toContain("Not implemented");
63	await web.dispose();	83	}),
64	}	84	);
65	});
66	});	85	});

packages/plugins/google-discovery/src/api/handlers.ts+48−55

@@ -1,65 +1,58 @@
1	import { HttpApiBuilder, HttpServerResponse } from "@effect/platform";	1	import { HttpApiBuilder, HttpServerResponse } from "@effect/platform";
2	import { Cause, Context, Effect } from "effect";	2	import { Context, Effect } from "effect";
3		3
4	import { runOAuthCallback } from "@executor/plugin-oauth2/http";	4	import { runOAuthCallback } from "@executor/plugin-oauth2/http";
5		5
6	import { addGroup } from "@executor/api";	6	import { addGroup, capture } from "@executor/api";
7	import type {	7	import type {
8	GoogleDiscoveryAddSourceInput,	8	GoogleDiscoveryAddSourceInput,
9	GoogleDiscoveryOAuthAuthResult,	9	GoogleDiscoveryOAuthAuthResult,
10	GoogleDiscoveryPluginExtension,	10	GoogleDiscoveryPluginExtension,
11	} from "../sdk/plugin";	11	} from "../sdk/plugin";
12	import {	12	import { GoogleDiscoveryOAuthError } from "../sdk/errors";
13	GoogleDiscoveryInvocationError,	13	import { GoogleDiscoveryGroup } from "./group";
14	GoogleDiscoveryOAuthError,	14
15	GoogleDiscoveryParseError,	15	// ---------------------------------------------------------------------------
16	GoogleDiscoverySourceError,	16	// Service tag
17	} from "../sdk/errors";	17	//
18	import {	18	// Holds the `Captured` shape — every method's `StorageFailure` channel
19	GoogleDiscoveryApiError,	19	// has been swapped for `InternalError({ traceId })`. The host app
20	GoogleDiscoveryGroup,	20	// provides an already-wrapped extension via
21	GoogleDiscoveryInternalError,	21	// `Layer.succeed(GoogleDiscoveryExtensionService, withCapture(executor.googleDiscovery))`.
22	} from "./group";	22	// Handlers see `InternalError` in the error union, which matches
		23	// `.addError(InternalError)` on the group — no per-handler translation.
		24	// ---------------------------------------------------------------------------
23		25
24	export class GoogleDiscoveryExtensionService extends Context.Tag("GoogleDiscoveryExtensionService")<	26	export class GoogleDiscoveryExtensionService extends Context.Tag("GoogleDiscoveryExtensionService")<
25	GoogleDiscoveryExtensionService,	27	GoogleDiscoveryExtensionService,
26	GoogleDiscoveryPluginExtension	28	GoogleDiscoveryPluginExtension
27	>() {}	29	>() {}
28		30
		31	// ---------------------------------------------------------------------------
		32	// Composed API
		33	// ---------------------------------------------------------------------------
		34
29	const ExecutorApiWithGoogleDiscovery = addGroup(GoogleDiscoveryGroup);	35	const ExecutorApiWithGoogleDiscovery = addGroup(GoogleDiscoveryGroup);
30		36
31	const GOOGLE_DISCOVERY_OAUTH_CHANNEL = "executor:google-discovery-oauth-result";	37	const GOOGLE_DISCOVERY_OAUTH_CHANNEL = "executor:google-discovery-oauth-result";
32		38
33	const toPopupErrorMessage = (error: unknown): string => {	39	const toPopupErrorMessage = (error: unknown): string =>
34	if (error instanceof GoogleDiscoveryOAuthError) {	40	error instanceof GoogleDiscoveryOAuthError ? error.message : "Authentication failed";
35	return error.message;
36	}
37	return "Authentication failed";
38	};
39
40	const toGoogleDiscoveryApiError = (
41	error: unknown,
42	): GoogleDiscoveryApiError \| GoogleDiscoveryInternalError => {
43	if (error instanceof GoogleDiscoveryApiError \|\| error instanceof GoogleDiscoveryInternalError) {
44	return error;
45	}
46	if (
47	error instanceof GoogleDiscoveryParseError \|\|
48	error instanceof GoogleDiscoverySourceError \|\|
49	error instanceof GoogleDiscoveryOAuthError \|\|
50	error instanceof GoogleDiscoveryInvocationError
51	) {
52	return new GoogleDiscoveryApiError({ message: error.message });
53	}
54	return new GoogleDiscoveryInternalError({ message: "Internal server error" });
55	};
56		41
57	const sanitizeGoogleDiscoveryFailure = <A, R>(	42	// ---------------------------------------------------------------------------
58	effect: Effect.Effect<A, unknown, R>,	43	// Handlers
59	): Effect.Effect<A, GoogleDiscoveryApiError \| GoogleDiscoveryInternalError, R> =>	44	//
60	Effect.catchAllCause(effect, (cause) =>	45	// Each handler is exactly: yield the extension service, call the method,
61	Effect.fail(toGoogleDiscoveryApiError(Cause.squash(cause))),	46	// return. Plugin SDK errors flow through the typed channel and are
62	);	47	// schema-encoded to 4xx by HttpApi (see group.ts `.addError(...)` calls).
		48	// `StorageFailure` has already been translated to `InternalError` by
		49	// `withCapture` on the service instance; defects bubble up and are
		50	// captured + downgraded to `InternalError(traceId)` by the API-level
		51	// observability middleware.
		52	//
		53	// No `sanitize*`, no `liftDomainErrors`, no per-handler error mapping.
		54	// If you find yourself adding error-handling here you're in the wrong layer.
		55	// ---------------------------------------------------------------------------
63		56
64	export const GoogleDiscoveryHandlers = HttpApiBuilder.group(	57	export const GoogleDiscoveryHandlers = HttpApiBuilder.group(
65	ExecutorApiWithGoogleDiscovery,	58	ExecutorApiWithGoogleDiscovery,
@@ -67,19 +60,19 @@ export const GoogleDiscoveryHandlers = HttpApiBuilder.group( · 1 unmodified line
67	(handlers) =>	60	(handlers) =>
68	handlers	61	handlers
69	.handle("probeDiscovery", ({ payload }) =>	62	.handle("probeDiscovery", ({ payload }) =>
70	Effect.gen(function* () {	63	capture(Effect.gen(function* () {
71	const ext = yield* GoogleDiscoveryExtensionService;	64	const ext = yield* GoogleDiscoveryExtensionService;
72	return yield* ext.probeDiscovery(payload.discoveryUrl);	65	return yield* ext.probeDiscovery(payload.discoveryUrl);
73	}).pipe(sanitizeGoogleDiscoveryFailure),	66	})),
74	)	67	)
75	.handle("addSource", ({ payload }) =>	68	.handle("addSource", ({ payload }) =>
76	Effect.gen(function* () {	69	capture(Effect.gen(function* () {
77	const ext = yield* GoogleDiscoveryExtensionService;	70	const ext = yield* GoogleDiscoveryExtensionService;
78	return yield* ext.addSource(payload as GoogleDiscoveryAddSourceInput);	71	return yield* ext.addSource(payload as GoogleDiscoveryAddSourceInput);
79	}).pipe(sanitizeGoogleDiscoveryFailure),	72	})),
80	)	73	)
81	.handle("startOAuth", ({ payload }) =>	74	.handle("startOAuth", ({ payload }) =>
82	Effect.gen(function* () {	75	capture(Effect.gen(function* () {
83	const ext = yield* GoogleDiscoveryExtensionService;	76	const ext = yield* GoogleDiscoveryExtensionService;
84	return yield* ext.startOAuth({	77	return yield* ext.startOAuth({
85	name: payload.name,	78	name: payload.name,
@@ -89,30 +82,30 @@ export const GoogleDiscoveryHandlers = HttpApiBuilder.group( · 3 unmodified lines
89	redirectUrl: payload.redirectUrl,	82	redirectUrl: payload.redirectUrl,
90	scopes: payload.scopes,	83	scopes: payload.scopes,
91	});	84	});
92	}).pipe(sanitizeGoogleDiscoveryFailure),	85	})),
93	)	86	)
94	.handle("completeOAuth", ({ payload }) =>	87	.handle("completeOAuth", ({ payload }) =>
95	Effect.gen(function* () {	88	capture(Effect.gen(function* () {
96	const ext = yield* GoogleDiscoveryExtensionService;	89	const ext = yield* GoogleDiscoveryExtensionService;
97	return yield* ext.completeOAuth({	90	return yield* ext.completeOAuth({
98	state: payload.state,	91	state: payload.state,
99	code: payload.code,	92	code: payload.code,
100	error: payload.error,	93	error: payload.error,
101	});	94	});
102	}).pipe(sanitizeGoogleDiscoveryFailure),	95	})),
103	)	96	)
104	.handle("getSource", ({ path }) =>	97	.handle("getSource", ({ path }) =>
105	Effect.gen(function* () {	98	capture(Effect.gen(function* () {
106	const ext = yield* GoogleDiscoveryExtensionService;	99	const ext = yield* GoogleDiscoveryExtensionService;
107	return yield* ext.getSource(path.namespace);	100	return yield* ext.getSource(path.namespace);
108	}).pipe(sanitizeGoogleDiscoveryFailure),	101	})),
109	)	102	)
110	.handle("oauthCallback", ({ urlParams }) =>	103	.handle("oauthCallback", ({ urlParams }) =>
111	Effect.gen(function* () {	104	capture(Effect.gen(function* () {
112	const ext = yield* GoogleDiscoveryExtensionService;	105	const ext = yield* GoogleDiscoveryExtensionService;
113	const html = yield* runOAuthCallback<	106	const html = yield* runOAuthCallback<
114	GoogleDiscoveryOAuthAuthResult,	107	GoogleDiscoveryOAuthAuthResult,
115	GoogleDiscoveryOAuthError,	108	unknown,
116	never	109	never
117	>({	110	>({
118	complete: ({ state, code, error }) =>	111	complete: ({ state, code, error }) =>
@@ -126,6 +119,6 @@ export const GoogleDiscoveryHandlers = HttpApiBuilder.group( · 7 unmodified lines
126	channelName: GOOGLE_DISCOVERY_OAUTH_CHANNEL,	119	channelName: GOOGLE_DISCOVERY_OAUTH_CHANNEL,
127	});	120	});
128	return yield* HttpServerResponse.html(html);	121	return yield* HttpServerResponse.html(html);
129	}).pipe(sanitizeGoogleDiscoveryFailure),	122	})),
130	),	123	),
131	);	124	);

packages/plugins/google-discovery/src/sdk/binding-store.ts+22−12

 import { Effect, Schema } from "effect";
-import { defineSchema, type StorageDeps } from "@executor/sdk";
+import {
+  defineSchema,
+  type StorageDeps,
+  type StorageFailure,
+} from "@executor/sdk";
 import {
   GoogleDiscoveryMethodBinding,
 // Store interface
 // ---------------------------------------------------------------------------
+// Every method routes through the typed adapter (`ctx.storage.adapter`)
+// so the typed error channel is `StorageFailure`. Schema-decode failures
+// inside `Effect.gen` land as defects, not typed errors, and are caught
+// by the HTTP edge's observability middleware.
 export interface GoogleDiscoveryStore {
   readonly getBinding: (toolId: string) => Effect.Effect<
     { readonly namespace: string; readonly binding: GoogleDiscoveryMethodBinding } | null,
-    Error
+    StorageFailure
   >;
   readonly putBinding: (
     toolId: string,
     sourceId: string,
     binding: GoogleDiscoveryMethodBinding,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageFailure>;
   readonly removeBindingsBySource: (
     sourceId: string,
-  ) => Effect.Effect<readonly string[], Error>;
+  ) => Effect.Effect<readonly string[], StorageFailure>;
   readonly getBindingsForSource: (
     sourceId: string,
   ) => Effect.Effect<
     ReadonlyMap<string, GoogleDiscoveryMethodBinding>,
-    Error
+    StorageFailure
   >;
-  readonly putSource: (source: GoogleDiscoveryStoredSource) => Effect.Effect<void, Error>;
+  readonly putSource: (
-  readonly removeSource: (sourceId: string) => Effect.Effect<void, Error>;
+    source: GoogleDiscoveryStoredSource,
+  ) => Effect.Effect<void, StorageFailure>;
+  readonly removeSource: (sourceId: string) => Effect.Effect<void, StorageFailure>;
   readonly getSource: (
     sourceId: string,
-  ) => Effect.Effect<GoogleDiscoveryStoredSource | null, Error>;
+  ) => Effect.Effect<GoogleDiscoveryStoredSource | null, StorageFailure>;
   readonly getSourceConfig: (
     sourceId: string,
-  ) => Effect.Effect<GoogleDiscoveryStoredSourceData | null, Error>;
+  ) => Effect.Effect<GoogleDiscoveryStoredSourceData | null, StorageFailure>;
   readonly putOAuthSession: (
     sessionId: string,
     session: GoogleDiscoveryOAuthSession,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageFailure>;
   readonly getOAuthSession: (
     sessionId: string,
-  ) => Effect.Effect<GoogleDiscoveryOAuthSession | null, Error>;
+  ) => Effect.Effect<GoogleDiscoveryOAuthSession | null, StorageFailure>;
-  readonly deleteOAuthSession: (sessionId: string) => Effect.Effect<void, Error>;
+  readonly deleteOAuthSession: (sessionId: string) => Effect.Effect<void, StorageFailure>;
 }
 // ---------------------------------------------------------------------------

packages/plugins/google-discovery/src/sdk/document.ts+6−2

 });
 type DiscoveryDocument = typeof DiscoveryDocumentModel.Type;
-const toParseError = (message: string, cause: unknown) =>
+// The Schema.TaggedError version of GoogleDiscoveryParseError no longer
-  new GoogleDiscoveryParseError({ message, cause });
+// carries a `cause` field — it would leak raw decoder internals over the
+// wire. The decoder failure still shows up on the Effect cause chain for
+// server-side logging; the client only sees the user-facing `message`.
+const toParseError = (message: string, _cause: unknown) =>
+  new GoogleDiscoveryParseError({ message });
 const decodeUnknownWith =
   <A>(

packages/plugins/google-discovery/src/sdk/errors.ts+21−4

+// Google Discovery plugin tagged errors. The three errors that cross
+// the HTTP edge carry an `HttpApiSchema` annotation so they can be
+// `.addError(...)` directly on the API group — handlers return them
+// and HttpApi encodes each as a 4xx response with a typed body, no
+// per-handler sanitisation step.
+//
+// `GoogleDiscoveryInvocationError` stays a `Data.TaggedError` because
+// it only surfaces through `invokeTool`, which runs under the core
+// `tools.invoke` endpoint — not any endpoint on the Google Discovery
+// group — so it doesn't need an HTTP annotation.
 import { Data, Schema } from "effect";
+import { HttpApiSchema } from "@effect/platform";
 import type { Option } from "effect";
-export class GoogleDiscoveryParseError extends Data.TaggedError("GoogleDiscoveryParseError")<{
+export class GoogleDiscoveryParseError extends Schema.TaggedError<GoogleDiscoveryParseError>()(
-  readonly message: string;
+  "GoogleDiscoveryParseError",
-  readonly cause?: unknown;
+  {
-}> {}
+    message: Schema.String,
+  },
+  HttpApiSchema.annotations({ status: 400 }),
+) {}
 export class GoogleDiscoveryInvocationError extends Data.TaggedError(
   "GoogleDiscoveryInvocationError",
   {
     message: Schema.String,
   },
+  HttpApiSchema.annotations({ status: 400 }),
 ) {}
 export class GoogleDiscoverySourceError extends Schema.TaggedError<GoogleDiscoverySourceError>()(
   {
     message: Schema.String,
   },
+  HttpApiSchema.annotations({ status: 400 }),
 ) {}

packages/plugins/google-discovery/src/sdk/invoke.ts+37−13

   type OAuth2SecretsIO,
 } from "@executor/plugin-oauth2";
-import type { PluginCtx } from "@executor/sdk";
+import type { PluginCtx, StorageFailure } from "@executor/sdk";
 import { SetSecretInput } from "@executor/sdk";
 import { GOOGLE_TOKEN_URL } from "./oauth";
-import { GoogleDiscoveryInvocationError } from "./errors";
+import {
+  GoogleDiscoveryInvocationError,
+  GoogleDiscoveryOAuthError,
+} from "./errors";
 import type { GoogleDiscoveryStore } from "./binding-store";
 import {
   GoogleDiscoveryInvocationResult,
   ctx: PluginCtx<GoogleDiscoveryStore>;
   sourceId: string;
   source: GoogleDiscoveryStoredSourceData;
-}): Effect.Effect<string, Error> =>
+}): Effect.Effect<string, GoogleDiscoveryOAuthError> =>
   Effect.gen(function* () {
     if (input.source.auth.kind !== "oauth2") return "";
     const auth = input.source.auth;
           });
         }),
     }).pipe(
-      Effect.mapError((error) => new Error(error.message)),
+      Effect.mapError(
+        (error) => new GoogleDiscoveryOAuthError({ message: error.message }),
+      ),
     );
   });
   );
   const contentType = response.headers["content-type"] ?? null;
+  const mapBodyError = Effect.mapError(
+    (err: { readonly message?: string }) =>
+      new GoogleDiscoveryInvocationError({
+        message: `Failed to read response body: ${err.message ?? String(err)}`,
+        statusCode: Option.some(response.status),
+        cause: err,
+      }),
+  );
   const body =
     response.status === 204
       ? null
       : isJsonContentType(contentType)
-        ? yield* response.json.pipe(Effect.catchAll(() => response.text))
+        ? yield* response.json.pipe(
-        : yield* response.text;
+            Effect.catchAll(() => response.text),
+            mapBodyError,
+          )
+        : yield* response.text.pipe(mapBodyError);
   const ok = response.status >= 200 && response.status < 300;
   return new GoogleDiscoveryInvocationResult({
   toolId: string;
   args: unknown;
   httpClientLayer?: Layer.Layer<HttpClient.HttpClient>;
-}): Effect.Effect<GoogleDiscoveryInvocationResult, Error> =>
+}): Effect.Effect<
+  GoogleDiscoveryInvocationResult,
+  | GoogleDiscoveryInvocationError
+  | GoogleDiscoveryOAuthError
+  | StorageFailure
+> =>
   Effect.gen(function* () {
     const entry = yield* input.ctx.storage.getBinding(input.toolId);
     if (!entry) {
       return yield* Effect.fail(
-        new Error(`No Google Discovery operation found for tool "${input.toolId}"`),
+        new GoogleDiscoveryInvocationError({
+          message: `No Google Discovery operation found for tool "${input.toolId}"`,
+          statusCode: Option.none(),
+        }),
       );
     }
     const source = yield* input.ctx.storage.getSourceConfig(entry.namespace);
     if (!source) {
       return yield* Effect.fail(
-        new Error(`No Google Discovery source found for "${entry.namespace}"`),
+        new GoogleDiscoveryInvocationError({
+          message: `No Google Discovery source found for "${entry.namespace}"`,
+          statusCode: Option.none(),
+        }),
       );
     }
       source,
       args: (input.args ?? {}) as Record<string, unknown>,
       authorizationHeader: authHeader,
-    }).pipe(
+    }).pipe(Effect.provide(layer));
-      Effect.provide(layer),
-      Effect.mapError((err) => (err instanceof Error ? err : new Error(String(err)))),
-    );
   });

packages/plugins/google-discovery/src/sdk/plugin.ts+34−16

   SetSecretInput,
   SourceDetectionResult,
   type PluginCtx,
+  type StorageFailure,
   type ToolAnnotations,
 } from "@executor/sdk";
   readonly scopes: readonly string[];
 }
+/**
+ * Errors any Google Discovery extension method may surface. The first
+ * three are plugin-domain tagged errors that flow directly to clients
+ * (4xx, each carrying its own `HttpApiSchema` status once wrapped at the
+ * API edge). `StorageFailure` covers raw backend failures (`StorageError`)
+ * plus `UniqueViolationError`; the HTTP edge (`@executor/api`'s
+ * `withCapture`) translates `StorageError` to the opaque
+ * `InternalError({ traceId })` at Layer composition. `UniqueViolationError`
+ * passes through — plugins can `Effect.catchTag` it if they want a
+ * friendlier user-facing error.
+ */
+export type GoogleDiscoveryExtensionFailure =
+  | GoogleDiscoveryParseError
+  | GoogleDiscoverySourceError
+  | GoogleDiscoveryOAuthError
+  | StorageFailure;
 export interface GoogleDiscoveryPluginExtension {
   readonly probeDiscovery: (
     discoveryUrl: string,
     input: GoogleDiscoveryAddSourceInput,
   ) => Effect.Effect<
     { readonly toolCount: number; readonly namespace: string },
-    GoogleDiscoveryParseError | GoogleDiscoverySourceError | Error
+    GoogleDiscoveryParseError | GoogleDiscoverySourceError | StorageFailure
   >;
-  readonly removeSource: (namespace: string) => Effect.Effect<void, Error>;
+  readonly removeSource: (
+    namespace: string,
+  ) => Effect.Effect<void, StorageFailure>;
   readonly startOAuth: (
     input: GoogleDiscoveryOAuthStartInput,
   ) => Effect.Effect<
     GoogleDiscoveryOAuthStartResponse,
-    GoogleDiscoveryParseError | GoogleDiscoverySourceError | GoogleDiscoveryOAuthError | Error
+    | GoogleDiscoveryParseError
+    | GoogleDiscoverySourceError
+    | GoogleDiscoveryOAuthError
+    | StorageFailure
   >;
   readonly completeOAuth: (
     input: GoogleDiscoveryOAuthCompleteInput,
-  ) => Effect.Effect<GoogleDiscoveryOAuthAuthResult, GoogleDiscoveryOAuthError>;
+  ) => Effect.Effect<
+    GoogleDiscoveryOAuthAuthResult,
+    GoogleDiscoveryOAuthError | StorageFailure
+  >;
   readonly getSource: (
     namespace: string,
-  ) => Effect.Effect<GoogleDiscoveryStoredSource | null, Error>;
+  ) => Effect.Effect<GoogleDiscoveryStoredSource | null, StorageFailure>;
 }
 // ---------------------------------------------------------------------------
   schema: googleDiscoverySchema,
   storage: (deps) => makeGoogleDiscoveryStore(deps),
-  extension: (ctx): GoogleDiscoveryPluginExtension => ({
+  extension: (ctx) => ({
     probeDiscovery: (discoveryUrl) =>
       Effect.gen(function* () {
         const text = yield* fetchDiscoveryDocument(discoveryUrl);
           scope: stored.scope,
           scopes: [...session.scopes],
         };
-      }).pipe(
+      }),
-        Effect.mapError((err) =>
-          err instanceof GoogleDiscoveryOAuthError
-            ? err
-            : new GoogleDiscoveryOAuthError({
-                message: err instanceof Error ? err.message : String(err),
-              }),
-        ),
-      ),
     getSource: (namespace) => ctx.storage.getSource(namespace),
-  }),
+  } satisfies GoogleDiscoveryPluginExtension),
   invokeTool: ({ ctx, toolRow, args }) =>
     invokeGoogleDiscoveryTool({

packages/plugins/graphql/src/api/group.ts+23−17

 import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "@effect/platform";
 import { Schema } from "effect";
 import { ScopeId } from "@executor/sdk";
+import { InternalError } from "@executor/api";
 import { GraphqlIntrospectionError, GraphqlExtractionError } from "../sdk/errors";
 import { HeaderValue } from "../sdk/types";
   HttpApiSchema.annotations({ status: 400 }),
 );
-export class GraphqlInternalError extends Schema.TaggedError<GraphqlInternalError>()(
-  "GraphqlInternalError",
-  {
-    message: Schema.String,
-  },
-  HttpApiSchema.annotations({ status: 500 }),
-) {}
 // ---------------------------------------------------------------------------
 // Group
+//
+// Plugin SDK errors (GraphqlIntrospectionError etc.) are declared once at
+// the group level via `.addError(...)` — every endpoint inherits them. The
+// errors themselves carry their HTTP status via `HttpApiSchema.annotations`
+// above, so handlers just `return yield* ext.foo(...)` and the schema
+// encodes whatever it gets.
+//
+// 5xx is handled at the API level: `.addError(InternalError)` adds a
+// single shared opaque-by-schema 500 surface translated from `StorageError`
+// by `withCapture` at the HTTP edge. No per-handler wrapping, no
+// per-plugin InternalError.
 // ---------------------------------------------------------------------------
 export class GraphqlGroup extends HttpApiGroup.make("graphql")
   .add(
     HttpApiEndpoint.post("addSource")`/scopes/${scopeIdParam}/graphql/sources`
       .setPayload(AddSourcePayload)
-      .addSuccess(AddSourceResponse)
+      .addSuccess(AddSourceResponse),
-      .addError(IntrospectionError)
-      .addError(ExtractionError)
-      .addError(GraphqlInternalError),
   )
   .add(
     HttpApiEndpoint.get("getSource")`/scopes/${scopeIdParam}/graphql/sources/${namespaceParam}`
-      .addSuccess(Schema.NullOr(StoredSourceSchema))
+      .addSuccess(Schema.NullOr(StoredSourceSchema)),
-      .addError(GraphqlInternalError),
   )
   .add(
     HttpApiEndpoint.patch("updateSource")`/scopes/${scopeIdParam}/graphql/sources/${namespaceParam}`
       .setPayload(UpdateSourcePayload)
-      .addSuccess(UpdateSourceResponse)
+      .addSuccess(UpdateSourceResponse),
-      .addError(GraphqlInternalError),
+  )
-  ) {}
+  // Errors declared once at the group level — every endpoint inherits.
+  // Plugin domain errors carry their own HttpApiSchema status (4xx);
+  // `InternalError` is the shared opaque 500 translated at the HTTP
+  // edge by `withCapture`.
+  .addError(InternalError)
+  .addError(IntrospectionError)
+  .addError(ExtractionError) {}

packages/plugins/graphql/src/api/handlers.ts+28−53

 import { HttpApiBuilder } from "@effect/platform";
-import { Cause, Context, Effect } from "effect";
+import { Context, Effect } from "effect";
-import { addGroup } from "@executor/api";
+import { addGroup, capture } from "@executor/api";
-import { GraphqlExtractionError, GraphqlIntrospectionError } from "../sdk/errors";
+import type {
-import type { GraphqlPluginExtension, HeaderValue, GraphqlUpdateSourceInput } from "../sdk/plugin";
+  GraphqlPluginExtension,
-import { GraphqlGroup, GraphqlInternalError } from "./group";
+  HeaderValue,
+  GraphqlUpdateSourceInput,
+} from "../sdk/plugin";
+import { GraphqlGroup } from "./group";
 // ---------------------------------------------------------------------------
-// Service tag — the server provides the GraphQL extension
+// Service tag
+//
+// Holds the `Captured` shape — every method's `StorageError` channel has
+// been swapped for `InternalError({ traceId })`. The host app provides an
+// already-wrapped extension via
+// `Layer.succeed(GraphqlExtensionService, withCapture(executor.graphql))`.
+// Handlers see `InternalError` in the error union, which matches
+// `.addError(InternalError)` on the group — no per-handler translation.
 // ---------------------------------------------------------------------------
 export class GraphqlExtensionService extends Context.Tag("GraphqlExtensionService")<
   GraphqlPluginExtension
 >() {}
-// ---------------------------------------------------------------------------
-// Failure mapping
-// ---------------------------------------------------------------------------
-type GraphqlAddSourceFailure =
-  | GraphqlIntrospectionError
-  | GraphqlExtractionError
-  | GraphqlInternalError;
-const toGraphqlAddSourceFailure = (error: unknown): GraphqlAddSourceFailure => {
-  if (
-    error instanceof GraphqlIntrospectionError ||
-    error instanceof GraphqlExtractionError ||
-    error instanceof GraphqlInternalError
-  ) {
-    return error;
-  }
-  const message = error instanceof Error ? error.message : String(error);
-  return new GraphqlInternalError({ message });
-};
-const sanitizeAddSourceFailure = <A, R>(
-  effect: Effect.Effect<A, unknown, R>,
-): Effect.Effect<A, GraphqlAddSourceFailure, R> =>
-  Effect.catchAllCause(effect, (cause) =>
-    Effect.fail(toGraphqlAddSourceFailure(Cause.squash(cause))),
-  );
-const toGraphqlInternalError = (error: unknown): GraphqlInternalError => {
-  if (error instanceof GraphqlInternalError) return error;
-  const message = error instanceof Error ? error.message : String(error);
-  return new GraphqlInternalError({ message });
-};
-const sanitizeInternalFailure = <A, R>(
-  effect: Effect.Effect<A, unknown, R>,
-): Effect.Effect<A, GraphqlInternalError, R> =>
-  Effect.catchAllCause(effect, (cause) =>
-    Effect.fail(toGraphqlInternalError(Cause.squash(cause))),
-  );
 // ---------------------------------------------------------------------------
 // Composed API — core + graphql group
 // ---------------------------------------------------------------------------
 // ---------------------------------------------------------------------------
 // Handlers
+//
+// Each handler is exactly: yield the extension service, call the method,
+// return. Plugin SDK errors flow through the typed channel and are
+// schema-encoded to 4xx by HttpApi (see group.ts `.addError(...)` calls).
+// Defects bubble up and are captured + downgraded to `InternalError(traceId)`
+// by the API-level observability middleware.
 // ---------------------------------------------------------------------------
 export const GraphqlHandlers = HttpApiBuilder.group(ExecutorApiWithGraphql, "graphql", (handlers) =>
   handlers
     .handle("addSource", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* GraphqlExtensionService;
         const result = yield* ext.addSource({
           endpoint: payload.endpoint,
           toolCount: result.toolCount,
           namespace: payload.namespace ?? "graphql",
         };
-      }).pipe(sanitizeAddSourceFailure),
+      })),
     )
     .handle("getSource", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* GraphqlExtensionService;
         return yield* ext.getSource(path.namespace);
-      }).pipe(sanitizeInternalFailure),
+      })),
     )
     .handle("updateSource", ({ path, payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* GraphqlExtensionService;
         yield* ext.updateSource(path.namespace, {
           name: payload.name,
           headers: payload.headers as Record<string, HeaderValue> | undefined,
         } as GraphqlUpdateSourceInput);
         return { updated: true };
-      }).pipe(sanitizeInternalFailure),
+      })),
     ),
 );

packages/plugins/graphql/src/sdk/invoke.ts+5−5

@@ -14,8 +14,8 @@ import { · 13 unmodified lines
14		14
15	export const resolveHeaders = (	15	export const resolveHeaders = (
16	headers: Record<string, HeaderValue>,	16	headers: Record<string, HeaderValue>,
17	secrets: { readonly get: (id: string) => Effect.Effect<string \| null, Error> },	17	secrets: { readonly get: (id: string) => Effect.Effect<string \| null, unknown> },
18	): Effect.Effect<Record<string, string>, Error> =>	18	): Effect.Effect<Record<string, string>> =>
19	Effect.gen(function* () {	19	Effect.gen(function* () {
20	const entries = Object.entries(headers);	20	const entries = Object.entries(headers);
21	// Resolve secret-backed headers in parallel. Missing / failing	21	// Resolve secret-backed headers in parallel. Missing / failing
@@ -138,14 +138,14 @@ export const invokeWithLayer = ( · 116 unmodified lines
138	endpoint: string,	138	endpoint: string,
139	resolvedHeaders: Record<string, string>,	139	resolvedHeaders: Record<string, string>,
140	httpClientLayer: Layer.Layer<HttpClient.HttpClient>,	140	httpClientLayer: Layer.Layer<HttpClient.HttpClient>,
141	): Effect.Effect<InvocationResult, Error> =>	141	) =>
142	invoke(operation, args, endpoint, resolvedHeaders).pipe(	142	invoke(operation, args, endpoint, resolvedHeaders).pipe(
143	Effect.provide(httpClientLayer),	143	Effect.provide(httpClientLayer),
144	Effect.mapError((err) =>	144	Effect.mapError((err) =>
145	err instanceof Error	145	err instanceof GraphqlInvocationError
146	? err	146	? err
147	: new GraphqlInvocationError({	147	: new GraphqlInvocationError({
148	message: String(err),	148	message: err instanceof Error ? err.message : String(err),
149	statusCode: Option.none(),	149	statusCode: Option.none(),
150	cause: err,	150	cause: err,
151	}),	151	}),

packages/plugins/graphql/src/sdk/plugin.ts+24−14

 import {
   definePlugin,
   SourceDetectionResult,
+  type StorageFailure,
   type ToolAnnotations,
   type ToolRow,
 } from "@executor/sdk";
   type IntrospectionTypeRef,
 } from "./introspect";
 import { extract } from "./extract";
-import { GraphqlExtractionError } from "./errors";
+import { GraphqlExtractionError, GraphqlIntrospectionError } from "./errors";
 import { invokeWithLayer, resolveHeaders } from "./invoke";
 import {
   graphqlSchema,
   readonly headers?: Record<string, HeaderValue>;
 }
+/**
+ * Errors any GraphQL extension method may surface. `GraphqlIntrospectionError`
+ * and `GraphqlExtractionError` are plugin-domain tagged errors that flow
+ * directly to clients (4xx, each carrying its own `HttpApiSchema` status).
+ * `StorageFailure` covers raw backend failures (`StorageError` plus
+ * `UniqueViolationError`); the HTTP edge (`@executor/api`'s `withCapture`)
+ * translates `StorageError` to the opaque `InternalError({ traceId })` at
+ * Layer composition.
+ */
+export type GraphqlExtensionFailure =
+  | GraphqlIntrospectionError
+  | GraphqlExtractionError
+  | StorageFailure;
 export interface GraphqlPluginExtension {
   /** Add a GraphQL endpoint and register its operations as tools */
   readonly addSource: (
     config: GraphqlSourceConfig,
-  ) => Effect.Effect<{ readonly toolCount: number }, Error>;
+  ) => Effect.Effect<{ readonly toolCount: number }, GraphqlExtensionFailure>;
   /** Remove all tools from a previously added GraphQL source by namespace */
-  readonly removeSource: (namespace: string) => Effect.Effect<void, Error>;
+  readonly removeSource: (
+    namespace: string,
+  ) => Effect.Effect<void, StorageFailure>;
   /** Fetch the full stored source by namespace (or null if missing) */
   readonly getSource: (
     namespace: string,
-  ) => Effect.Effect<StoredGraphqlSource | null, Error>;
+  ) => Effect.Effect<StoredGraphqlSource | null, StorageFailure>;
   /** Update config (endpoint, headers) for an existing GraphQL source.
    *  Does NOT re-introspect or re-register tools — just patches the
   readonly updateSource: (
     namespace: string,
     input: GraphqlUpdateSourceInput,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageFailure>;
 }
 // ---------------------------------------------------------------------------
       schema: graphqlSchema,
       storage: (deps): GraphqlStore => makeDefaultGraphqlStore(deps),
-      extension: (ctx): GraphqlPluginExtension => {
+      extension: (ctx) => {
         const resolveConfigHeaders = (
           headers: Record<string, HeaderValue> | undefined,
         ) =>
         return {
           addSource: (config) =>
             addSourceInternal(config).pipe(
-              Effect.mapError((err) =>
-                err instanceof Error
-                  ? err
-                  : new GraphqlExtractionError({
-                      message: String(err),
-                    }),
-              ),
               Effect.tap((result) =>
                 configFile
                   ? configFile.upsertSource(
               endpoint: input.endpoint,
               headers: input.headers,
             }),
-        };
+        } satisfies GraphqlPluginExtension;
       },
       staticSources: (self) => [

packages/plugins/graphql/src/sdk/store.ts+8−8

@@ -1,6 +1,6 @@
1	import { Effect } from "effect";	1	import { Effect } from "effect";
2		2
3	import { defineSchema, type StorageDeps } from "@executor/sdk";	3	import { defineSchema, type StorageDeps, type StorageFailure } from "@executor/sdk";
4		4
5	import { OperationBinding, type HeaderValue } from "./types";	5	import { OperationBinding, type HeaderValue } from "./types";
6		6
@@ -89,28 +89,28 @@ export interface GraphqlStore { · 82 unmodified lines
89	readonly upsertSource: (	89	readonly upsertSource: (
90	input: StoredGraphqlSource,	90	input: StoredGraphqlSource,
91	operations: readonly StoredOperation[],	91	operations: readonly StoredOperation[],
92	) => Effect.Effect<void, Error>;	92	) => Effect.Effect<void, StorageFailure>;
93		93
94	readonly updateSourceMeta: (	94	readonly updateSourceMeta: (
95	namespace: string,	95	namespace: string,
96	patch: { readonly name?: string; readonly endpoint?: string; readonly headers?: Record<string, HeaderValue> },	96	patch: { readonly name?: string; readonly endpoint?: string; readonly headers?: Record<string, HeaderValue> },
97	) => Effect.Effect<void, Error>;	97	) => Effect.Effect<void, StorageFailure>;
98		98
99	readonly getSource: (	99	readonly getSource: (
100	namespace: string,	100	namespace: string,
101	) => Effect.Effect<StoredGraphqlSource \| null, Error>;	101	) => Effect.Effect<StoredGraphqlSource \| null, StorageFailure>;
102		102
103	readonly listSources: () => Effect.Effect<readonly StoredGraphqlSource[], Error>;	103	readonly listSources: () => Effect.Effect<readonly StoredGraphqlSource[], StorageFailure>;
104		104
105	readonly getOperationByToolId: (	105	readonly getOperationByToolId: (
106	toolId: string,	106	toolId: string,
107	) => Effect.Effect<StoredOperation \| null, Error>;	107	) => Effect.Effect<StoredOperation \| null, StorageFailure>;
108		108
109	readonly listOperationsBySource: (	109	readonly listOperationsBySource: (
110	sourceId: string,	110	sourceId: string,
111	) => Effect.Effect<readonly StoredOperation[], Error>;	111	) => Effect.Effect<readonly StoredOperation[], StorageFailure>;
112		112
113	readonly removeSource: (namespace: string) => Effect.Effect<void, Error>;	113	readonly removeSource: (namespace: string) => Effect.Effect<void, StorageFailure>;
114	}	114	}
115		115
116	// ---------------------------------------------------------------------------	116	// ---------------------------------------------------------------------------

packages/plugins/keychain/src/provider.ts+18−4

 import { Effect } from "effect";
-import type { SecretProvider } from "@executor/sdk";
+import { StorageError, type SecretProvider } from "@executor/sdk";
 import { getPassword, setPassword, deletePassword } from "./keyring";
 // ---------------------------------------------------------------------------
 // SecretProvider adapter — bridges keyring into SDK resolution chain
+//
+// The underlying `@napi-rs/keyring` sync API encodes "no entry" as an
+// ordinary return value (`getPassword()` → `null`, `deletePassword()` →
+// `false`), and only throws on real failures (keychain locked, permission
+// denied, platform init failure, etc.). `keyring.ts` wraps those thrown
+// failures as `KeychainError`. We translate `KeychainError` →
+// `StorageError` so the HTTP edge can capture it to telemetry and surface
+// an opaque `InternalError({ traceId })` — previously `orElseSucceed`
+// silently converted every failure into "nothing found", which made it
+// impossible to debug why secrets weren't resolving.
 // ---------------------------------------------------------------------------
+const toStorageError = (cause: { readonly message: string; readonly cause?: unknown }) =>
+  new StorageError({ message: cause.message, cause: cause.cause ?? cause });
 export const makeKeychainProvider = (serviceName: string): SecretProvider => ({
   key: "keychain",
   writable: true,
-  get: (secretId) => getPassword(serviceName, secretId).pipe(Effect.orElseSucceed(() => null)),
+  get: (secretId) =>
+    getPassword(serviceName, secretId).pipe(Effect.mapError(toStorageError)),
   set: (secretId, value) =>
-    setPassword(serviceName, secretId, value).pipe(Effect.orElseSucceed(() => undefined)),
+    setPassword(serviceName, secretId, value).pipe(Effect.mapError(toStorageError)),
   delete: (secretId) =>
-    deletePassword(serviceName, secretId).pipe(Effect.orElseSucceed(() => false)),
+    deletePassword(serviceName, secretId).pipe(Effect.mapError(toStorageError)),
   // Keychain doesn't support enumerating — you need to know the account name
   list: undefined,
 });

packages/plugins/mcp/src/api/group.ts+39−48

 import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "@effect/platform";
 import { Schema } from "effect";
 import { ScopeId } from "@executor/sdk";
+import { InternalError } from "@executor/api";
+import {
+  McpConnectionError,
+  McpOAuthError,
+  McpToolDiscoveryError,
+} from "../sdk/errors";
 import { McpStoredSourceSchema } from "../sdk/stored-source";
 // Re-export for handler use
   scope: Schema.NullOr(Schema.String),
 });
-// ---------------------------------------------------------------------------
-// Error
-// ---------------------------------------------------------------------------
-export class McpApiError extends Schema.TaggedError<McpApiError>()(
-  "McpApiError",
-  {
-    message: Schema.String,
-  },
-  HttpApiSchema.annotations({ status: 400 }),
-) {}
-export class McpInternalError extends Schema.TaggedError<McpInternalError>()(
-  "McpInternalError",
-  {
-    message: Schema.String,
-  },
-  HttpApiSchema.annotations({ status: 500 }),
-) {}
 // ---------------------------------------------------------------------------
 // Group
+//
+// Plugin SDK errors (McpOAuthError etc.) are declared once at the group
+// level via `.addError(...)` — every endpoint inherits them. The errors
+// themselves carry their HTTP status via `HttpApiSchema.annotations`
+// in errors.ts, so handlers just `return yield* ext.foo(...)` and the
+// schema encodes whatever it gets.
+//
+// 5xx is handled at the API level: `CoreExecutorApi.addError(InternalError)`
+// adds a single shared opaque-by-schema 500 surface to every endpoint in
+// the entire API. Defects are captured + downgraded to it by an
+// HttpApiBuilder middleware (see apps/cloud/src/observability.ts).
+// No per-handler wrapping, no per-plugin InternalError.
 // ---------------------------------------------------------------------------
 export class McpGroup extends HttpApiGroup.make("mcp")
   .add(
     HttpApiEndpoint.post("probeEndpoint")`/scopes/${scopeIdParam}/mcp/probe`
       .setPayload(ProbeEndpointPayload)
-      .addSuccess(ProbeEndpointResponse)
+      .addSuccess(ProbeEndpointResponse),
-      .addError(McpApiError)
-      .addError(McpInternalError),
   )
   .add(
     HttpApiEndpoint.post("addSource")`/scopes/${scopeIdParam}/mcp/sources`
       .setPayload(AddSourcePayload)
-      .addSuccess(AddSourceResponse)
+      .addSuccess(AddSourceResponse),
-      .addError(McpApiError)
-      .addError(McpInternalError),
   )
   .add(
     HttpApiEndpoint.post("removeSource")`/scopes/${scopeIdParam}/mcp/sources/remove`
       .setPayload(NamespacePayload)
-      .addSuccess(RemoveSourceResponse)
+      .addSuccess(RemoveSourceResponse),
-      .addError(McpApiError)
-      .addError(McpInternalError),
   )
   .add(
     HttpApiEndpoint.post("refreshSource")`/scopes/${scopeIdParam}/mcp/sources/refresh`
       .setPayload(NamespacePayload)
-      .addSuccess(RefreshSourceResponse)
+      .addSuccess(RefreshSourceResponse),
-      .addError(McpApiError)
-      .addError(McpInternalError),
   )
   .add(
     HttpApiEndpoint.post("startOAuth")`/scopes/${scopeIdParam}/mcp/oauth/start`
       .setPayload(StartOAuthPayload)
-      .addSuccess(StartOAuthResponse)
+      .addSuccess(StartOAuthResponse),
-      .addError(McpApiError)
-      .addError(McpInternalError),
   )
   .add(
     HttpApiEndpoint.post("completeOAuth")`/scopes/${scopeIdParam}/mcp/oauth/complete`
       .setPayload(CompleteOAuthPayload)
-      .addSuccess(CompleteOAuthResponse)
+      .addSuccess(CompleteOAuthResponse),
-      .addError(McpApiError)
-      .addError(McpInternalError),
   )
   .add(
     HttpApiEndpoint.get("oauthCallback")`/mcp/oauth/callback`
       .setUrlParams(OAuthCallbackParams)
-      .addSuccess(HtmlResponse)
+      .addSuccess(HtmlResponse),
-      .addError(McpApiError)
-      .addError(McpInternalError),
   )
   .add(
     HttpApiEndpoint.get("getSource")`/scopes/${scopeIdParam}/mcp/sources/${namespaceParam}`
-      .addSuccess(Schema.NullOr(McpStoredSourceSchema))
+      .addSuccess(Schema.NullOr(McpStoredSourceSchema)),
-      .addError(McpApiError)
-      .addError(McpInternalError),
   )
   .add(
     HttpApiEndpoint.patch("updateSource")`/scopes/${scopeIdParam}/mcp/sources/${namespaceParam}`
       .setPayload(UpdateSourcePayload)
-      .addSuccess(UpdateSourceResponse)
+      .addSuccess(UpdateSourceResponse),
-      .addError(McpApiError)
+  )
-      .addError(McpInternalError),
+  // Errors declared once at the group level — every endpoint inherits.
-  ) {}
+  // Plugin domain errors carry their own HttpApiSchema status (4xx);
+  // `InternalError` is the shared opaque 500 translated at the HTTP
+  // edge by `withCapture`. We only list errors an MCP *group*
+  // endpoint can surface: `McpInvocationError` is thrown inside
+  // `invokeTool` which is reached via the core `tools.invoke`
+  // endpoint, not any MCP-group endpoint, so it doesn't belong here.
+  .addError(InternalError)
+  .addError(McpOAuthError)
+  .addError(McpConnectionError)
+  .addError(McpToolDiscoveryError) {}

packages/plugins/mcp/src/api/handlers.test.ts+59−40

@@ -1,8 +1,17 @@
		1	// ---------------------------------------------------------------------------
		2	// Handler-level integration test for the MCP group.
		3	//
		4	// Verifies the layer wiring stays coherent end-to-end: the handlers
		5	// pull the wrapped extension from the service, and any un-caught cause
		6	// lands in the observability middleware — producing a 500 whose body is
		7	// the opaque `InternalError` schema (no internal leakage).
		8	// ---------------------------------------------------------------------------
		9
1	import { HttpApiBuilder, HttpServer } from "@effect/platform";	10	import { HttpApiBuilder, HttpServer } from "@effect/platform";
2	import { describe, expect, it } from "vitest";	11	import { describe, expect, it } from "@effect/vitest";
3	import { Effect, Layer } from "effect";	12	import { Effect, Layer } from "effect";
4		13
5	import { addGroup } from "@executor/api";	14	import { addGroup, observabilityMiddleware } from "@executor/api";
6	import { CoreHandlers, ExecutionEngineService, ExecutorService } from "@executor/api/server";	15	import { CoreHandlers, ExecutionEngineService, ExecutorService } from "@executor/api/server";
7	import type { McpPluginExtension } from "../sdk/plugin";	16	import type { McpPluginExtension } from "../sdk/plugin";
8	import { McpExtensionService, McpHandlers } from "./handlers";	17	import { McpExtensionService, McpHandlers } from "./handlers";
@@ -10,7 +19,7 @@ import { McpGroup } from "./group"; · 1 unmodified line
10		19
11	const unused = Effect.dieMessage("unused");	20	const unused = Effect.dieMessage("unused");
12		21
13	const createFailingExtension = (): McpPluginExtension => ({	22	const failingExtension: McpPluginExtension = {
14	probeEndpoint: () => Effect.die(new Error("Not implemented")),	23	probeEndpoint: () => Effect.die(new Error("Not implemented")),
15	addSource: () => unused,	24	addSource: () => unused,
16	removeSource: () => unused,	25	removeSource: () => unused,
@@ -19,48 +28,58 @@ const createFailingExtension = (): McpPluginExtension => ({ · 2 unmodified lines
19	completeOAuth: () => Effect.die(new Error("Not implemented")),	28	completeOAuth: () => Effect.die(new Error("Not implemented")),
20	getSource: () => Effect.succeed(null),	29	getSource: () => Effect.succeed(null),
21	updateSource: () => unused,	30	updateSource: () => unused,
22	});	31	};
23		32
24	const Api = addGroup(McpGroup);	33	const Api = addGroup(McpGroup);
25		34
26	const fakeExecutor = {} as any;	35	// `acquireRelease` keeps disposal inside the Effect scope — no
27	const fakeExecutionEngine = {} as any;	36	// try/finally, no per-test cleanup plumbing. `it.scoped` closes the
28		37	// scope for us. Each `Layer.provide` satisfies a piece of the api
29	const createHandler = () =>	38	// builder's dependency graph; `provideMerge` at the bottom keeps
30	HttpApiBuilder.toWebHandler(	39	// framework services available to the router itself.
31	HttpApiBuilder.api(Api).pipe(	40	const WebHandler = Effect.acquireRelease(
32	Layer.provide(CoreHandlers),	41	Effect.sync(() =>
33	Layer.provide(McpHandlers),	42	HttpApiBuilder.toWebHandler(
34	Layer.provide(Layer.succeed(ExecutorService, fakeExecutor)),	43	HttpApiBuilder.api(Api).pipe(
35	Layer.provide(Layer.succeed(ExecutionEngineService, fakeExecutionEngine)),	44	Layer.provide(CoreHandlers),
36	Layer.provide(Layer.succeed(McpExtensionService, createFailingExtension())),	45	Layer.provide(McpHandlers),
37	Layer.provideMerge(HttpServer.layerContext),	46	Layer.provide(observabilityMiddleware(Api)),
38	Layer.provideMerge(HttpApiBuilder.Router.Live),	47	Layer.provide(Layer.succeed(ExecutorService, {} as never)),
39	Layer.provideMerge(HttpApiBuilder.Middleware.layer),	48	Layer.provide(Layer.succeed(ExecutionEngineService, {} as never)),
		49	Layer.provide(Layer.succeed(McpExtensionService, failingExtension)),
		50	Layer.provideMerge(HttpServer.layerContext),
		51	Layer.provideMerge(HttpApiBuilder.Router.Live),
		52	Layer.provideMerge(HttpApiBuilder.Middleware.layer),
		53	),
40	),	54	),
41	);	55	),
		56	(web) => Effect.promise(() => web.dispose()),
		57	);
42		58
43	describe("McpHandlers", () => {	59	describe("McpHandlers", () => {
44	it("sanitizes unknown endpoint failures", async () => {	60	it.scoped(
45	const web = createHandler();	61	"defect-returning methods produce an opaque InternalError, no leakage",
46	try {	62	() =>
47	const response = await web.handler(	63	Effect.gen(function* () {
48	new Request("http://localhost/scopes/scope_1/mcp/probe", {	64	const web = yield* WebHandler;
49	method: "POST",	65	const response = yield* Effect.promise(() =>
50	headers: { "content-type": "application/json" },	66	web.handler(
51	body: JSON.stringify({ endpoint: "https://example.com/mcp" }),	67	new Request("http://localhost/scopes/scope_1/mcp/probe", {
52	}),	68	method: "POST",
53	);	69	headers: { "content-type": "application/json" },
		70	body: JSON.stringify({ endpoint: "https://example.com/mcp" }),
		71	}),
		72	),
		73	);
54		74
55	expect(response.status).toBe(500);	75	expect(response.status).toBe(500);
56	const body = await response.json();	76	const body = (yield* Effect.promise(() => response.json())) as {
57	expect(body).toEqual({	77	_tag?: string;
58	_tag: "McpInternalError",	78	traceId?: string;
59	message: "Internal server error",	79	};
60	});	80	expect(body._tag).toBe("InternalError");
61	expect(JSON.stringify(body)).not.toContain("Not implemented");	81	expect(typeof body.traceId).toBe("string");
62	} finally {	82	expect(JSON.stringify(body)).not.toContain("Not implemented");
63	await web.dispose();	83	}),
64	}	84	);
65	});
66	});	85	});

packages/plugins/mcp/src/api/handlers.ts+51−64

 import { HttpApiBuilder, HttpServerResponse } from "@effect/platform";
 import { Cause, Context, Effect } from "effect";
-import { addGroup } from "@executor/api";
+import { addGroup, capture } from "@executor/api";
 import type { McpPluginExtension, McpSourceConfig, McpUpdateSourceInput } from "../sdk/plugin";
-import {
+import { McpOAuthError } from "../sdk/errors";
-  McpConnectionError,
+import { McpGroup } from "./group";
-  McpInvocationError,
-  McpOAuthError,
-  McpToolDiscoveryError,
-} from "../sdk/errors";
-import { McpApiError, McpGroup, McpInternalError } from "./group";
 // ---------------------------------------------------------------------------
-// Service tag
+// Service tag — holds the raw extension shape the executor produces.
+// Handlers wrap their generator bodies with `capture(...)` from
+// `@executor/api`, which translates `StorageError` to `InternalError`
+// at the edge; that's why the tag type matches the SDK shape directly
+// (no `Captured<>` inversion).
 // ---------------------------------------------------------------------------
 export class McpExtensionService extends Context.Tag("McpExtensionService")<
 </body></html>`;
 };
-const toPopupErrorMessage = (error: unknown): string => {
+const toPopupErrorMessage = (cause: Cause.Cause<unknown>): string => {
-  if (error instanceof McpOAuthError) {
+  const err = Cause.squash(cause);
-    return error.message;
+  return err instanceof McpOAuthError ? err.message : "Authentication failed";
-  }
-  return "Authentication failed";
-};
-const toMcpApiError = (error: unknown): McpApiError | McpInternalError => {
-  if (error instanceof McpApiError || error instanceof McpInternalError) {
-    return error;
-  }
-  if (
-    error instanceof McpConnectionError ||
-    error instanceof McpToolDiscoveryError ||
-    error instanceof McpInvocationError ||
-    error instanceof McpOAuthError
-  ) {
-    return new McpApiError({ message: error.message });
-  }
-  return new McpInternalError({ message: "Internal server error" });
 };
-const sanitizeMcpFailure = <A, R>(
-  effect: Effect.Effect<A, unknown, R>,
-): Effect.Effect<A, McpApiError | McpInternalError, R> =>
-  Effect.catchAllCause(effect, (cause) => Effect.fail(toMcpApiError(Cause.squash(cause))));
 // ---------------------------------------------------------------------------
 // Convert API payload → McpSourceConfig
 // ---------------------------------------------------------------------------
     auth?: { kind: string } & Record<string, unknown>;
   };
-  // Normalize oauth2 tokenType default
   const auth = p.auth
     ? p.auth.kind === "oauth2"
       ? {
 // ---------------------------------------------------------------------------
 // Handlers
+//
+// Each handler is exactly: yield the extension service, call the method,
+// return. Plugin SDK errors flow through the typed channel and are
+// schema-encoded to 4xx by HttpApi (see group.ts `.addError(...)` calls).
+// Defects bubble up and are captured + downgraded to `InternalError(traceId)`
+// by the API-level observability middleware (see apps/cloud/src/observability.ts).
+//
+// No `sanitize*`, no `liftDomainErrors`, no `withObservability` per handler.
+// If you find yourself adding error-handling here you're in the wrong layer.
 // ---------------------------------------------------------------------------
 export const McpHandlers = HttpApiBuilder.group(ExecutorApiWithMcp, "mcp", (handlers) =>
   handlers
     .handle("probeEndpoint", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* McpExtensionService;
         return yield* ext.probeEndpoint(payload.endpoint);
-      }).pipe(sanitizeMcpFailure),
+      })),
     )
     .handle("addSource", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* McpExtensionService;
         return yield* ext.addSource(
           toSourceConfig(payload as Parameters<typeof toSourceConfig>[0]),
         );
-      }).pipe(sanitizeMcpFailure),
+      })),
     )
     .handle("removeSource", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* McpExtensionService;
         yield* ext.removeSource(payload.namespace);
         return { removed: true };
-      }).pipe(sanitizeMcpFailure),
+      })),
     )
     .handle("refreshSource", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* McpExtensionService;
         return yield* ext.refreshSource(payload.namespace);
-      }).pipe(sanitizeMcpFailure),
+      })),
     )
     .handle("startOAuth", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* McpExtensionService;
         return yield* ext.startOAuth({
           endpoint: payload.endpoint,
           redirectUrl: payload.redirectUrl,
           queryParams: payload.queryParams,
         });
-      }).pipe(sanitizeMcpFailure),
+      })),
     )
     .handle("completeOAuth", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* McpExtensionService;
         return yield* ext.completeOAuth({
           state: payload.state,
           code: payload.code,
           error: payload.error,
         });
-      }).pipe(sanitizeMcpFailure),
+      })),
     )
     .handle("getSource", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* McpExtensionService;
         return yield* ext.getSource(path.namespace);
-      }).pipe(sanitizeMcpFailure),
+      })),
     )
     .handle("updateSource", ({ path, payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* McpExtensionService;
         yield* ext.updateSource(path.namespace, {
           name: payload.name,
           auth: payload.auth as McpUpdateSourceInput["auth"],
         });
         return { updated: true };
-      }).pipe(sanitizeMcpFailure),
+      })),
     )
     .handle("oauthCallback", ({ urlParams }) =>
-      Effect.gen(function* () {
+      // OAuth popup is special: it always returns 200 HTML and renders the
+      // failure into the popup body so the parent window's listener gets a
+      // structured result. Catching here is intentional, not a leak.
+      capture(Effect.gen(function* () {
         const ext = yield* McpExtensionService;
-        const result = yield* ext
+        const result = yield* Effect.matchCauseEffect(
-          .completeOAuth({
+          ext.completeOAuth({
             state: urlParams.state,
             code: urlParams.code,
             error: urlParams.error ?? urlParams.error_description,
-          })
+          }),
-          .pipe(
+          {
-            Effect.map(
+            onSuccess: (c) =>
-              (c): OAuthPopupResult => ({
+              Effect.succeed<OAuthPopupResult>({
                 type: "executor:oauth-result",
                 ok: true,
                 sessionId: urlParams.state,
                 expiresAt: c.expiresAt,
                 scope: c.scope,
               }),
-            ),
+            onFailure: (cause) =>
-            Effect.catchAllCause((cause) =>
               Effect.succeed<OAuthPopupResult>({
                 type: "executor:oauth-result",
                 ok: false,
                 sessionId: null,
-                error: toPopupErrorMessage(Cause.squash(cause)),
+                error: toPopupErrorMessage(cause),
               }),
-            ),
+          },
-          );
+        );
         return yield* HttpServerResponse.html(popupDocument(result));
-      }).pipe(sanitizeMcpFailure),
+      })),
     ),
 );

packages/plugins/mcp/src/sdk/binding-store.ts+24−12

 import { Effect, Schema } from "effect";
-import { defineSchema, type StorageDeps } from "@executor/sdk";
+import {
+  defineSchema,
+  type StorageDeps,
+  type StorageFailure,
+} from "@executor/sdk";
 import { McpToolBinding, McpStoredSourceData } from "./types";
 import { McpOAuthSession } from "./oauth";
 // Store interface
 // ---------------------------------------------------------------------------
+// Every method routes through the typed adapter (`ctx.storage.adapter`)
+// so the typed error channel is `StorageFailure`. Schema-decode failures
+// inside `Effect.gen` land as defects, not typed errors, and are caught
+// by the HTTP edge's observability middleware.
 export interface McpBindingStore {
   readonly getBinding: (
     toolId: string,
   ) => Effect.Effect<
     { readonly binding: McpToolBinding; readonly namespace: string } | null,
-    Error
+    StorageFailure
   >;
   readonly putBindings: (
     namespace: string,
     entries: ReadonlyArray<{ readonly toolId: string; readonly binding: McpToolBinding }>,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageFailure>;
-  readonly removeBindingsByNamespace: (namespace: string) => Effect.Effect<void, Error>;
+  readonly removeBindingsByNamespace: (
+    namespace: string,
+  ) => Effect.Effect<void, StorageFailure>;
-  readonly listSources: () => Effect.Effect<readonly McpStoredSource[], Error>;
+  readonly listSources: () => Effect.Effect<readonly McpStoredSource[], StorageFailure>;
-  readonly getSource: (namespace: string) => Effect.Effect<McpStoredSource | null, Error>;
+  readonly getSource: (
+    namespace: string,
+  ) => Effect.Effect<McpStoredSource | null, StorageFailure>;
   readonly getSourceConfig: (
     namespace: string,
-  ) => Effect.Effect<McpStoredSourceData | null, Error>;
+  ) => Effect.Effect<McpStoredSourceData | null, StorageFailure>;
-  readonly putSource: (source: McpStoredSource) => Effect.Effect<void, Error>;
+  readonly putSource: (source: McpStoredSource) => Effect.Effect<void, StorageFailure>;
-  readonly removeSource: (namespace: string) => Effect.Effect<void, Error>;
+  readonly removeSource: (namespace: string) => Effect.Effect<void, StorageFailure>;
   readonly putOAuthSession: (
     sessionId: string,
     session: McpOAuthSession,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageFailure>;
   readonly getOAuthSession: (
     sessionId: string,
-  ) => Effect.Effect<McpOAuthSession | null, Error>;
+  ) => Effect.Effect<McpOAuthSession | null, StorageFailure>;
-  readonly deleteOAuthSession: (sessionId: string) => Effect.Effect<void, Error>;
+  readonly deleteOAuthSession: (sessionId: string) => Effect.Effect<void, StorageFailure>;
 }
 // ---------------------------------------------------------------------------

packages/plugins/mcp/src/sdk/errors.ts+16−3

+// MCP plugin tagged errors. Each carries an `HttpApiSchema` annotation so
+// it can be `.addError(...)` directly on the API group — handlers return
+// these and HttpApi encodes them as 4xx responses with a typed body. No
+// per-handler sanitisation step.
 import { Schema } from "effect";
+import { HttpApiSchema } from "@effect/platform";
 export class McpConnectionError extends Schema.TaggedError<McpConnectionError>()(
   "McpConnectionError",
     transport: Schema.String,
     message: Schema.String,
   },
+  HttpApiSchema.annotations({ status: 400 }),
 ) {}
 export class McpToolDiscoveryError extends Schema.TaggedError<McpToolDiscoveryError>()(
     stage: Schema.Literal("connect", "list_tools"),
     message: Schema.String,
   },
+  HttpApiSchema.annotations({ status: 400 }),
 ) {}
 export class McpInvocationError extends Schema.TaggedError<McpInvocationError>()(
     toolName: Schema.String,
     message: Schema.String,
   },
+  HttpApiSchema.annotations({ status: 400 }),
 ) {}
-export class McpOAuthError extends Schema.TaggedError<McpOAuthError>()("McpOAuthError", {
+export class McpOAuthError extends Schema.TaggedError<McpOAuthError>()(
-  message: Schema.String,
+  "McpOAuthError",
-}) {}
+  {
+    message: Schema.String,
+  },
+  HttpApiSchema.annotations({ status: 400 }),
+) {}

packages/plugins/mcp/src/sdk/invoke.ts+9−26

   type ElicitationRequest,
 } from "@executor/sdk";
-import { McpConnectionError } from "./errors";
+import { McpConnectionError, McpInvocationError } from "./errors";
 import type { McpConnection } from "./connection";
 import type { McpStoredSourceData } from "./types";
   toolName: string,
   args: Record<string, unknown>,
   elicit: Elicit,
-): Effect.Effect<unknown, Error> =>
+): Effect.Effect<unknown, McpInvocationError> =>
   Effect.gen(function* () {
     installElicitationHandler(connection.client, elicit);
     return yield* Effect.tryPromise({
       try: () => connection.client.callTool({ name: toolName, arguments: args }),
       catch: (cause) =>
-        new Error(
+        new McpInvocationError({
-          `MCP tool call failed for ${toolName}: ${
+          toolName,
+          message: `MCP tool call failed for ${toolName}: ${
             cause instanceof Error ? cause.message : String(cause)
           }`,
-        ),
+        }),
     });
   });
 export const invokeMcpTool = (
   input: InvokeMcpToolInput,
-): Effect.Effect<unknown, Error> =>
+): Effect.Effect<unknown, McpConnectionError | McpInvocationError> =>
   Effect.gen(function* () {
     const cacheKey = connectionCacheKey(input.sourceData);
     const args = asRecord(input.args);
     const connector = input.resolveConnector();
     input.pendingConnectors.set(cacheKey, connector);
-    const firstConnection = yield* input.connectionCache.get(cacheKey).pipe(
+    const firstConnection = yield* input.connectionCache.get(cacheKey);
-      Effect.mapError(
-        (err) =>
-          new Error(
-            `Failed connecting to MCP server: ${
-              err instanceof Error ? err.message : String(err)
-            }`,
-          ),
-      ),
-    );
     return yield* useConnection(
       firstConnection,
         Effect.gen(function* () {
           yield* input.connectionCache.invalidate(cacheKey);
           input.pendingConnectors.set(cacheKey, connector);
-          const fresh = yield* input.connectionCache.get(cacheKey).pipe(
+          const fresh = yield* input.connectionCache.get(cacheKey);
-            Effect.mapError(
-              (err) =>
-                new Error(
-                  `Failed reconnecting to MCP server: ${
-                    err instanceof Error ? err.message : String(err)
-                  }`,
-                ),
-            ),
-          );
           return yield* useConnection(
             fresh,
             input.toolName,

packages/plugins/mcp/src/sdk/plugin.ts+34−12

   SetSecretInput,
   SourceDetectionResult,
   type PluginCtx,
+  type StorageFailure,
 } from "@executor/sdk";
 import {
   sd: McpStoredSourceData,
   ctx: PluginCtx<McpBindingStore>,
   allowStdio: boolean,
-): Effect.Effect<ConnectorInput, Error> => {
+): Effect.Effect<ConnectorInput, McpConnectionError | StorageFailure> => {
   if (sd.transport === "stdio") {
     if (!allowStdio) {
       return Effect.fail(
   readonly cacheScope: Scope.CloseableScope;
 }
-const makeRuntime = (): Effect.Effect<McpRuntime, Error> =>
+const makeRuntime = (): Effect.Effect<McpRuntime, never> =>
   Effect.gen(function* () {
     const cacheScope = yield* Scope.make();
     const pendingConnectors = new Map<
     // connection cache across a single createExecutor lifecycle.
     const runtimeRef: { current: McpRuntime | null } = { current: null };
-    const ensureRuntime = (): Effect.Effect<McpRuntime, Error> =>
+    const ensureRuntime = (): Effect.Effect<McpRuntime, never> =>
       runtimeRef.current
         ? Effect.succeed(runtimeRef.current)
         : makeRuntime().pipe(
           completeOAuth,
           getSource,
           updateSource,
-        };
+        } satisfies McpPluginExtension;
       },
       invokeTool: ({ ctx, toolRow, args, elicit }) =>
 // returns above.
 // ---------------------------------------------------------------------------
+/**
+ * Errors any MCP extension method may surface. The first four are
+ * plugin-domain tagged errors that flow directly to clients (4xx, each
+ * carrying its own `HttpApiSchema` status). `StorageFailure` covers
+ * raw backend failures (`StorageError`) plus `UniqueViolationError`;
+ * the HTTP edge (`@executor/api`'s `withCapture`) translates
+ * `StorageError` to the opaque `InternalError({ traceId })` at Layer
+ * composition. `UniqueViolationError` passes through — plugins can
+ * `Effect.catchTag` it if they want a friendlier user-facing error.
+ */
+export type McpExtensionFailure =
+  | McpOAuthError
+  | McpConnectionError
+  | McpToolDiscoveryError
+  | StorageFailure;
 export interface McpPluginExtension {
   readonly probeEndpoint: (
     endpoint: string,
-  ) => Effect.Effect<McpProbeResult, Error>;
+  ) => Effect.Effect<McpProbeResult, McpExtensionFailure>;
   readonly addSource: (
     config: McpSourceConfig,
-  ) => Effect.Effect<{ readonly toolCount: number; readonly namespace: string }, Error>;
+  ) => Effect.Effect<
-  readonly removeSource: (namespace: string) => Effect.Effect<void, Error>;
+    { readonly toolCount: number; readonly namespace: string },
+    McpExtensionFailure
+  >;
+  readonly removeSource: (
+    namespace: string,
+  ) => Effect.Effect<void, McpExtensionFailure>;
   readonly refreshSource: (
     namespace: string,
-  ) => Effect.Effect<{ readonly toolCount: number }, Error>;
+  ) => Effect.Effect<{ readonly toolCount: number }, McpExtensionFailure>;
   readonly startOAuth: (
     input: McpOAuthStartInput,
-  ) => Effect.Effect<McpOAuthStartResponse, Error>;
+  ) => Effect.Effect<McpOAuthStartResponse, McpExtensionFailure>;
   readonly completeOAuth: (
     input: McpOAuthCompleteInput,
-  ) => Effect.Effect<McpOAuthCompleteResponse, Error>;
+  ) => Effect.Effect<McpOAuthCompleteResponse, McpExtensionFailure>;
   readonly getSource: (
     namespace: string,
-  ) => Effect.Effect<McpStoredSource | null, Error>;
+  ) => Effect.Effect<McpStoredSource | null, McpExtensionFailure>;
   readonly updateSource: (
     namespace: string,
     input: McpUpdateSourceInput,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, McpExtensionFailure>;
 }

packages/plugins/onepassword/src/api/group.ts+19−14

 import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "@effect/platform";
 import { Schema } from "effect";
 import { ScopeId } from "@executor/sdk";
+import { InternalError } from "@executor/api";
 import { OnePasswordError } from "../sdk/errors";
 import { OnePasswordConfig, Vault, ConnectionStatus } from "../sdk/types";
 const GetConfigResponse = Schema.NullOr(OnePasswordConfig);
-// ---------------------------------------------------------------------------
-// Errors with HTTP status
-// ---------------------------------------------------------------------------
-const OpError = OnePasswordError.annotations(HttpApiSchema.annotations({ status: 502 }));
 // ---------------------------------------------------------------------------
 // Group
+//
+// Plugin SDK errors (OnePasswordError) are declared once at the group level
+// via `.addError(...)` — every endpoint inherits. The error carries its own
+// 502 status via `HttpApiSchema.annotations` in errors.ts.
+//
+// `InternalError` is the shared opaque 500 schema translated at the HTTP
+// edge by `withCapture` (see observability.ts). Storage failures on
+// `ctx.storage`/`ctx.secrets` flow through as `StorageFailure` in the
+// typed channel and are captured + downgraded to `InternalError({ traceId })`
+// at Layer composition. No per-handler translation.
 // ---------------------------------------------------------------------------
 export class OnePasswordGroup extends HttpApiGroup.make("onepassword")
   .add(
     HttpApiEndpoint.put("configure")`/scopes/${scopeIdParam}/onepassword/config`
       .setPayload(ConfigurePayload)
-      .addSuccess(Schema.Void)
+      .addSuccess(Schema.Void),
-      .addError(OpError),
   )
   .add(
     HttpApiEndpoint.del("removeConfig")`/scopes/${scopeIdParam}/onepassword/config`.addSuccess(
     ),
   )
   .add(
-    HttpApiEndpoint.get("status")`/scopes/${scopeIdParam}/onepassword/status`
+    HttpApiEndpoint.get("status")`/scopes/${scopeIdParam}/onepassword/status`.addSuccess(
-      .addSuccess(ConnectionStatus)
+      ConnectionStatus,
-      .addError(OpError),
+    ),
   )
   .add(
     HttpApiEndpoint.get("listVaults")`/scopes/${scopeIdParam}/onepassword/vaults`
       .setUrlParams(ListVaultsParams)
-      .addSuccess(ListVaultsResponse)
+      .addSuccess(ListVaultsResponse),
-      .addError(OpError),
+  )
-  ) {}
+  .addError(InternalError)
+  .addError(OnePasswordError) {}

packages/plugins/onepassword/src/api/handlers.ts+25−12

 import { HttpApiBuilder } from "@effect/platform";
 import { Context, Effect } from "effect";
-import { addGroup } from "@executor/api";
+import { addGroup, capture } from "@executor/api";
 import type { OnePasswordExtension } from "../sdk/plugin";
 import { OnePasswordGroup } from "./group";
 // ---------------------------------------------------------------------------
-// Service tag — the server provides the 1Password extension
+// Service tag
+//
+// Holds the `Captured` shape — every method's `StorageFailure` channel has
+// been swapped for `InternalError({ traceId })`. The host provides an
+// already-wrapped extension via
+// `Layer.succeed(OnePasswordExtensionService, withCapture(executor).onepassword)`.
+// Handlers see `InternalError` in the error union, which matches
+// `.addError(InternalError)` on the group — no per-handler translation.
 // ---------------------------------------------------------------------------
 export class OnePasswordExtensionService extends Context.Tag("OnePasswordExtensionService")<
 // ---------------------------------------------------------------------------
 // Handlers
+//
+// Each handler is exactly: yield the extension service, call the method,
+// return. Plugin SDK errors flow through the typed channel and are
+// schema-encoded (OnePasswordError -> 502) by HttpApi. Defects bubble up
+// and are captured + downgraded to `InternalError(traceId)` by the
+// observability middleware.
 // ---------------------------------------------------------------------------
 export const OnePasswordHandlers = HttpApiBuilder.group(
   (handlers) =>
     handlers
       .handle("getConfig", () =>
-        Effect.gen(function* () {
+        capture(Effect.gen(function* () {
           const ext = yield* OnePasswordExtensionService;
           return yield* ext.getConfig();
-        }).pipe(Effect.orDie),
+        })),
       )
       .handle("configure", ({ payload }) =>
-        Effect.gen(function* () {
+        capture(Effect.gen(function* () {
           const ext = yield* OnePasswordExtensionService;
           yield* ext.configure(payload);
-        }).pipe(Effect.orDie),
+        })),
       )
       .handle("removeConfig", () =>
-        Effect.gen(function* () {
+        capture(Effect.gen(function* () {
           const ext = yield* OnePasswordExtensionService;
           yield* ext.removeConfig();
-        }).pipe(Effect.orDie),
+        })),
       )
       .handle("status", () =>
-        Effect.gen(function* () {
+        capture(Effect.gen(function* () {
           const ext = yield* OnePasswordExtensionService;
           return yield* ext.status();
-        }).pipe(Effect.orDie),
+        })),
       )
       .handle("listVaults", ({ urlParams }) =>
-        Effect.gen(function* () {
+        capture(Effect.gen(function* () {
           const ext = yield* OnePasswordExtensionService;
           const auth =
             urlParams.authKind === "desktop-app"
               : { kind: "service-account" as const, tokenSecretId: urlParams.account };
           const vaults = yield* ext.listVaults(auth);
           return { vaults: [...vaults] };
-        }).pipe(Effect.orDie),
+        })),
       ),
 );

packages/plugins/onepassword/src/sdk/errors.ts+9−4

@@ -1,6 +1,11 @@
1	import { Schema } from "effect";	1	import { Schema } from "effect";
		2	import { HttpApiSchema } from "@effect/platform";
2		3
3	export class OnePasswordError extends Schema.TaggedError<OnePasswordError>()("OnePasswordError", {	4	export class OnePasswordError extends Schema.TaggedError<OnePasswordError>()(
4	operation: Schema.String,	5	"OnePasswordError",
5	message: Schema.String,	6	{
6	}) {}	7	operation: Schema.String,
		8	message: Schema.String,
		9	},
		10	HttpApiSchema.annotations({ status: 502 }),
		11	) {}

packages/plugins/onepassword/src/sdk/plugin.ts+108−103

@@ -2,9 +2,11 @@ import { Effect, Schema } from "effect"; · 1 unmodified line
2		2
3	import {	3	import {
4	definePlugin,	4	definePlugin,
		5	StorageError,
5	type PluginCtx,	6	type PluginCtx,
6	type ScopedBlobStore,	7	type ScopedBlobStore,
7	type SecretProvider,	8	type SecretProvider,
		9	type StorageFailure,
8	} from "@executor/sdk";	10	} from "@executor/sdk";
9		11
10	import { OnePasswordConfig, Vault, ConnectionStatus } from "./types";	12	import { OnePasswordConfig, Vault, ConnectionStatus } from "./types";
@@ -24,6 +26,20 @@ const CREDENTIAL_FIELD = "credential"; · 13 unmodified lines
24	const DEFAULT_TIMEOUT_MS = 15_000;	26	const DEFAULT_TIMEOUT_MS = 15_000;
25	const CONFIG_KEY = "config";	27	const CONFIG_KEY = "config";
26		28
		29	// ---------------------------------------------------------------------------
		30	// Shared failure alias.
		31	//
		32	// Every extension method either touches storage (`ctx.storage` blobs or
		33	// `ctx.secrets`) or reaches the 1Password backend. Storage I/O surfaces
		34	// as `StorageFailure`; the HTTP edge (`withCapture`) translates
		35	// `StorageError` to `InternalError({ traceId })`. Domain problems (not
		36	// configured, service-account token missing, backend RPC failure) stay
		37	// as `OnePasswordError` and encode to 502 via the schema annotation on
		38	// the class.
		39	// ---------------------------------------------------------------------------
		40
		41	export type OnePasswordExtensionFailure = OnePasswordError \| StorageFailure;
		42
27	// ---------------------------------------------------------------------------	43	// ---------------------------------------------------------------------------
28	// Plugin extension — public API on executor.onepassword	44	// Plugin extension — public API on executor.onepassword
29	// ---------------------------------------------------------------------------	45	// ---------------------------------------------------------------------------
@@ -32,59 +48,69 @@ export interface OnePasswordExtension { · 2 unmodified lines
32	/** Configure the 1Password connection */	48	/** Configure the 1Password connection */
33	readonly configure: (	49	readonly configure: (
34	config: OnePasswordConfig,	50	config: OnePasswordConfig,
35	) => Effect.Effect<void, OnePasswordError>;	51	) => Effect.Effect<void, StorageFailure>;
36		52
37	/** Get current configuration (if any) */	53	/** Get current configuration (if any) */
38	readonly getConfig: () => Effect.Effect<	54	readonly getConfig: () => Effect.Effect<
39	OnePasswordConfig \| null,	55	OnePasswordConfig \| null,
40	OnePasswordError	56	OnePasswordExtensionFailure
41	>;	57	>;
42		58
43	/** Remove the 1Password configuration */	59	/** Remove the 1Password configuration */
44	readonly removeConfig: () => Effect.Effect<void, OnePasswordError>;	60	readonly removeConfig: () => Effect.Effect<void, StorageFailure>;
45		61
46	/** Check connection status */	62	/** Check connection status */
47	readonly status: () => Effect.Effect<ConnectionStatus, OnePasswordError>;	63	readonly status: () => Effect.Effect<
		64	ConnectionStatus,
		65	OnePasswordExtensionFailure
		66	>;
48		67
49	/** List accessible vaults (requires auth) */	68	/** List accessible vaults (requires auth) */
50	readonly listVaults: (	69	readonly listVaults: (
51	auth: OnePasswordAuth,	70	auth: OnePasswordAuth,
52	) => Effect.Effect<ReadonlyArray<Vault>, OnePasswordError>;	71	) => Effect.Effect<ReadonlyArray<Vault>, OnePasswordExtensionFailure>;
53		72
54	/** Resolve a secret directly by op:// URI */	73	/** Resolve a secret directly by op:// URI */
55	readonly resolve: (uri: string) => Effect.Effect<string, OnePasswordError>;	74	readonly resolve: (
		75	uri: string,
		76	) => Effect.Effect<string, OnePasswordExtensionFailure>;
56	}	77	}
57		78
58	// ---------------------------------------------------------------------------	79	// ---------------------------------------------------------------------------
59	// Typed config store — single blob, JSON encoded. Declared inline because	80	// Typed config store — single blob, JSON encoded. Blob I/O failures surface
60	// there's only one key and one document; a schema table would be overkill.	81	// as `StorageError` (HTTP edge translates to `InternalError`); decode
		82	// failures stay `OnePasswordError` — the blob's contents are a plugin
		83	// concern, not an infrastructure one.
61	// ---------------------------------------------------------------------------	84	// ---------------------------------------------------------------------------
62		85
63	export interface OnePasswordStore {	86	export interface OnePasswordStore {
64	readonly getConfig: () => Effect.Effect<	87	readonly getConfig: () => Effect.Effect<
65	OnePasswordConfig \| null,	88	OnePasswordConfig \| null,
66	OnePasswordError	89	StorageError \| OnePasswordError
67	>;	90	>;
68	readonly saveConfig: (	91	readonly saveConfig: (
69	config: OnePasswordConfig,	92	config: OnePasswordConfig,
70	) => Effect.Effect<void, OnePasswordError>;	93	) => Effect.Effect<void, StorageError>;
71	readonly deleteConfig: () => Effect.Effect<void, OnePasswordError>;	94	readonly deleteConfig: () => Effect.Effect<void, StorageError>;
72	}	95	}
73		96
74	const decodeConfig = Schema.decodeUnknownSync(OnePasswordConfig);	97	const decodeConfig = Schema.decodeUnknownSync(OnePasswordConfig);
75		98
		99	const blobStorageError = (operation: string) =>
		100	(cause: unknown): StorageError =>
		101	new StorageError({
		102	message: `onepassword blob ${operation}: ${
		103	cause instanceof Error ? cause.message : String(cause)
		104	}`,
		105	cause,
		106	});
		107
76	export const makeOnePasswordStore = (	108	export const makeOnePasswordStore = (
77	blobs: ScopedBlobStore,	109	blobs: ScopedBlobStore,
78	): OnePasswordStore => ({	110	): OnePasswordStore => ({
79	getConfig: () =>	111	getConfig: () =>
80	blobs.get(CONFIG_KEY).pipe(	112	blobs.get(CONFIG_KEY).pipe(
81	Effect.mapError(	113	Effect.mapError(blobStorageError("read")),
82	(cause) =>
83	new OnePasswordError({
84	operation: "config load",
85	message: cause instanceof Error ? cause.message : String(cause),
86	}),
87	),
88	Effect.flatMap((raw) => {	114	Effect.flatMap((raw) => {
89	if (raw === null) return Effect.succeed(null);	115	if (raw === null) return Effect.succeed(null);
90	return Effect.try({	116	return Effect.try({
@@ -108,26 +134,10 @@ export const makeOnePasswordStore = ( · 17 unmodified lines
108	name: config.name,	134	name: config.name,
109	}),	135	}),
110	)	136	)
111	.pipe(	137	.pipe(Effect.mapError(blobStorageError("write"))),
112	Effect.mapError(
113	(cause) =>
114	new OnePasswordError({
115	operation: "config save",
116	message: cause instanceof Error ? cause.message : String(cause),
117	}),
118	),
119	),
120		138
121	deleteConfig: () =>	139	deleteConfig: () =>
122	blobs.delete(CONFIG_KEY).pipe(	140	blobs.delete(CONFIG_KEY).pipe(Effect.mapError(blobStorageError("delete"))),
123	Effect.mapError(
124	(cause) =>
125	new OnePasswordError({
126	operation: "config delete",
127	message: cause instanceof Error ? cause.message : String(cause),
128	}),
129	),
130	),
131	});	141	});
132		142
133	// ---------------------------------------------------------------------------	143	// ---------------------------------------------------------------------------
@@ -137,7 +147,7 @@ export const makeOnePasswordStore = ( · 3 unmodified lines
137	const resolveAuth = (	147	const resolveAuth = (
138	auth: OnePasswordAuth,	148	auth: OnePasswordAuth,
139	ctx: PluginCtx<OnePasswordStore>,	149	ctx: PluginCtx<OnePasswordStore>,
140	): Effect.Effect<ResolvedAuth, OnePasswordError> => {	150	): Effect.Effect<ResolvedAuth, OnePasswordError \| StorageFailure> => {
141	if (auth.kind === "desktop-app") {	151	if (auth.kind === "desktop-app") {
142	return Effect.succeed({	152	return Effect.succeed({
143	kind: "desktop-app" as const,	153	kind: "desktop-app" as const,
@@ -145,13 +155,6 @@ const resolveAuth = ( · 1 unmodified line
145	});	155	});
146	}	156	}
147	return ctx.secrets.get(auth.tokenSecretId).pipe(	157	return ctx.secrets.get(auth.tokenSecretId).pipe(
148	Effect.mapError(
149	(cause) =>
150	new OnePasswordError({
151	operation: "auth resolution",
152	message: `Failed to resolve service account token secret "${auth.tokenSecretId}": ${cause instanceof Error ? cause.message : String(cause)}`,
153	}),
154	),
155	Effect.flatMap((token) => {	158	Effect.flatMap((token) => {
156	if (token === null) {	159	if (token === null) {
157	return Effect.fail(	160	return Effect.fail(
@@ -174,7 +177,7 @@ const getServiceFromConfig = ( · 16 unmodified lines
174	ctx: PluginCtx<OnePasswordStore>,	177	ctx: PluginCtx<OnePasswordStore>,
175	timeoutMs: number,	178	timeoutMs: number,
176	preferSdk: boolean \| undefined,	179	preferSdk: boolean \| undefined,
177	): Effect.Effect<OnePasswordService, OnePasswordError> =>	180	): Effect.Effect<OnePasswordService, OnePasswordError \| StorageFailure> =>
178	resolveAuth(config.auth, ctx).pipe(	181	resolveAuth(config.auth, ctx).pipe(
179	Effect.flatMap((resolved) =>	182	Effect.flatMap((resolved) =>
180	makeOnePasswordService(resolved, { timeoutMs, preferSdk }),	183	makeOnePasswordService(resolved, { timeoutMs, preferSdk }),
@@ -252,69 +255,71 @@ export const onepasswordPlugin = definePlugin( · 71 unmodified lines
252	id: "onepassword" as const,	255	id: "onepassword" as const,
253	storage: ({ blobs }) => makeOnePasswordStore(blobs),	256	storage: ({ blobs }) => makeOnePasswordStore(blobs),
254		257
255	extension: (ctx): OnePasswordExtension => ({	258	extension: (ctx) => {
256	configure: (config) => ctx.storage.saveConfig(config),	259	return {
257		260	configure: (config) => ctx.storage.saveConfig(config),
258	getConfig: () => ctx.storage.getConfig(),	261
259		262	getConfig: () => ctx.storage.getConfig(),
260	removeConfig: () => ctx.storage.deleteConfig(),	263
261		264	removeConfig: () => ctx.storage.deleteConfig(),
262	status: () =>	265
263	Effect.gen(function* () {	266	status: () =>
264	const config = yield* ctx.storage.getConfig();	267	Effect.gen(function* () {
265	if (!config) {	268	const config = yield* ctx.storage.getConfig();
		269	if (!config) {
		270	return new ConnectionStatus({
		271	connected: false,
		272	error: "Not configured",
		273	});
		274	}
		275	const svc = yield* getServiceFromConfig(
		276	config,
		277	ctx,
		278	timeoutMs,
		279	preferSdk,
		280	);
		281	const vaults = yield* svc.listVaults();
		282	const vault = vaults.find((v) => v.id === config.vaultId);
266	return new ConnectionStatus({	283	return new ConnectionStatus({
267	connected: false,	284	connected: true,
268	error: "Not configured",	285	vaultName: vault?.title,
269	});	286	});
270	}	287	}),
271	const svc = yield* getServiceFromConfig(
272	config,
273	ctx,
274	timeoutMs,
275	preferSdk,
276	);
277	const vaults = yield* svc.listVaults();
278	const vault = vaults.find((v) => v.id === config.vaultId);
279	return new ConnectionStatus({
280	connected: true,
281	vaultName: vault?.title,
282	});
283	}),
284		288
285	listVaults: (auth) =>	289	listVaults: (auth) =>
286	Effect.gen(function* () {	290	Effect.gen(function* () {
287	const resolved = yield* resolveAuth(auth, ctx);	291	const resolved = yield* resolveAuth(auth, ctx);
288	const svc = yield* makeOnePasswordService(resolved, {	292	const svc = yield* makeOnePasswordService(resolved, {
289	timeoutMs,	293	timeoutMs,
290	preferSdk,	294	preferSdk,
291	});	295	});
292	const vaults = yield* svc.listVaults();	296	const vaults = yield* svc.listVaults();
293	return vaults	297	return vaults
294	.map((v) => new Vault({ id: v.id, name: v.title }))	298	.map((v) => new Vault({ id: v.id, name: v.title }))
295	.sort((a, b) => a.name.localeCompare(b.name));	299	.sort((a, b) => a.name.localeCompare(b.name));
296	}),	300	}),
297		301
298	resolve: (uri) =>	302	resolve: (uri) =>
299	Effect.gen(function* () {	303	Effect.gen(function* () {
300	const config = yield* ctx.storage.getConfig();	304	const config = yield* ctx.storage.getConfig();
301	if (!config) {	305	if (!config) {
302	return yield* Effect.fail(	306	return yield* Effect.fail(
303	new OnePasswordError({	307	new OnePasswordError({
304	operation: "resolve",	308	operation: "resolve",
305	message: "1Password is not configured",	309	message: "1Password is not configured",
306	}),	310	}),
		311	);
		312	}
		313	const svc = yield* getServiceFromConfig(
		314	config,
		315	ctx,
		316	timeoutMs,
		317	preferSdk,
307	);	318	);
308	}	319	return yield* svc.resolveSecret(uri);
309	const svc = yield* getServiceFromConfig(	320	}),
310	config,	321	} satisfies OnePasswordExtension;
311	ctx,	322	},
312	timeoutMs,
313	preferSdk,
314	);
315	return yield* svc.resolveSecret(uri);
316	}),
317	}),
318		323
319	secretProviders: (ctx) => [makeProvider(ctx, timeoutMs, preferSdk)],	324	secretProviders: (ctx) => [makeProvider(ctx, timeoutMs, preferSdk)],
320	};	325	};

packages/plugins/openapi/src/api/group.ts+30−28

 import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "@effect/platform";
 import { Schema } from "effect";
 import { ScopeId } from "@executor/sdk";
+import { InternalError } from "@executor/api";
 import {
   OpenApiParseError,
 );
 const OAuthError = OpenApiOAuthError.annotations(HttpApiSchema.annotations({ status: 400 }));
-export class OpenApiInternalError extends Schema.TaggedError<OpenApiInternalError>()(
-  "OpenApiInternalError",
-  {
-    message: Schema.String,
-  },
-  HttpApiSchema.annotations({ status: 500 }),
-) {}
 // ---------------------------------------------------------------------------
 // Group
+//
+// Plugin SDK errors (OpenApiParseError, OpenApiExtractionError,
+// OpenApiOAuthError) are declared once at the group level via
+// `.addError(...)` — every endpoint inherits them. The errors themselves
+// carry their HTTP status via `HttpApiSchema.annotations` above, so
+// handlers just `return yield* ext.foo(...)` and the schema encodes
+// whatever comes out.
+//
+// 5xx is handled at the API level: `.addError(InternalError)` adds the
+// shared opaque 500 surface. Defects are captured + downgraded to it by
+// an HttpApiBuilder middleware (see apps/cloud/src/observability.ts).
+// StorageError → InternalError translation happens at service wiring
+// time via `withCapture(executor)`.
 // ---------------------------------------------------------------------------
 export class OpenApiGroup extends HttpApiGroup.make("openapi")
   .add(
     HttpApiEndpoint.post("previewSpec")`/scopes/${scopeIdParam}/openapi/preview`
       .setPayload(PreviewSpecPayload)
-      .addSuccess(SpecPreview)
+      .addSuccess(SpecPreview),
-      .addError(ParseError)
-      .addError(ExtractionError)
-      .addError(OpenApiInternalError),
   )
   .add(
     HttpApiEndpoint.post("addSpec")`/scopes/${scopeIdParam}/openapi/specs`
       .setPayload(AddSpecPayload)
-      .addSuccess(AddSpecResponse)
+      .addSuccess(AddSpecResponse),
-      .addError(ParseError)
-      .addError(ExtractionError)
-      .addError(OpenApiInternalError),
   )
   .add(
     HttpApiEndpoint.get("getSource")`/scopes/${scopeIdParam}/openapi/sources/${namespaceParam}`
-      .addSuccess(Schema.NullOr(StoredSourceSchema))
+      .addSuccess(Schema.NullOr(StoredSourceSchema)),
-      .addError(OpenApiInternalError),
   )
   .add(
     HttpApiEndpoint.patch("updateSource")`/scopes/${scopeIdParam}/openapi/sources/${namespaceParam}`
       .setPayload(UpdateSourcePayload)
-      .addSuccess(UpdateSourceResponse)
+      .addSuccess(UpdateSourceResponse),
-      .addError(OpenApiInternalError),
   )
   .add(
     HttpApiEndpoint.post("startOAuth")`/scopes/${scopeIdParam}/openapi/oauth/start`
       .setPayload(StartOAuthPayload)
-      .addSuccess(StartOAuthResponse)
+      .addSuccess(StartOAuthResponse),
-      .addError(OAuthError),
   )
   .add(
     HttpApiEndpoint.post("completeOAuth")`/scopes/${scopeIdParam}/openapi/oauth/complete`
       .setPayload(CompleteOAuthPayload)
-      .addSuccess(OAuth2Auth)
+      .addSuccess(OAuth2Auth),
-      .addError(OAuthError),
   )
   .add(
     HttpApiEndpoint.get("oauthCallback", "/openapi/oauth/callback")
         Schema.Unknown.annotations(
           HttpApiSchema.annotations({ contentType: "text/html" }),
         ),
-      )
+      ),
-      .addError(OAuthError)
+  )
-      .addError(OpenApiInternalError),
+  // Errors declared once at the group level — every endpoint inherits.
-  ) {}
+  // Plugin domain errors carry their own HttpApiSchema status (4xx);
+  // `InternalError` is the shared opaque 500 translated at the HTTP
+  // edge by `withCapture`.
+  .addError(InternalError)
+  .addError(ParseError)
+  .addError(ExtractionError)
+  .addError(OAuthError) {}

packages/plugins/openapi/src/api/handlers.ts+36−60

 import { HttpApiBuilder, HttpServerResponse } from "@effect/platform";
-import { Cause, Context, Effect } from "effect";
+import { Context, Effect } from "effect";
 import { runOAuthCallback } from "@executor/plugin-oauth2/http";
-import { addGroup } from "@executor/api";
+import { addGroup, capture, InternalError } from "@executor/api";
-import {
+import { OpenApiOAuthError } from "../sdk/errors";
-  OpenApiExtractionError,
-  OpenApiOAuthError,
-  OpenApiParseError,
-} from "../sdk/errors";
 import type {
   OpenApiPluginExtension,
   HeaderValue,
   OpenApiUpdateSourceInput,
 } from "../sdk/plugin";
 import { OAuth2Auth } from "../sdk/types";
-import { OpenApiGroup, OpenApiInternalError } from "./group";
+import { OpenApiGroup } from "./group";
 const OPENAPI_OAUTH_CHANNEL = "executor:openapi-oauth-result";
 };
 // ---------------------------------------------------------------------------
-// Service tag — the server provides the OpenAPI extension
+// Service tag
+//
+// Holds the `Captured` shape — every method's `StorageFailure`
+// channel has been swapped for `InternalError({ traceId })`. The cloud
+// app provides an already-wrapped extension via
+// `Layer.succeed(OpenApiExtensionService, withCapture(executor.openapi))`.
+// Handlers see `InternalError` in the error union, which matches
+// `.addError(InternalError)` on the group — no per-handler translation.
 // ---------------------------------------------------------------------------
 export class OpenApiExtensionService extends Context.Tag("OpenApiExtensionService")<
   OpenApiPluginExtension
 >() {}
-// ---------------------------------------------------------------------------
-// Failure mapping
-// ---------------------------------------------------------------------------
-type OpenApiSpecFailure = OpenApiParseError | OpenApiExtractionError | OpenApiInternalError;
-const toOpenApiSpecFailure = (error: unknown): OpenApiSpecFailure => {
-  if (
-    error instanceof OpenApiParseError ||
-    error instanceof OpenApiExtractionError ||
-    error instanceof OpenApiInternalError
-  ) {
-    return error;
-  }
-  const message = error instanceof Error ? error.message : String(error);
-  return new OpenApiInternalError({ message });
-};
-const sanitizeSpecFailure = <A, R>(
-  effect: Effect.Effect<A, unknown, R>,
-): Effect.Effect<A, OpenApiSpecFailure, R> =>
-  Effect.catchAllCause(effect, (cause) => Effect.fail(toOpenApiSpecFailure(Cause.squash(cause))));
-const toOpenApiInternalError = (error: unknown): OpenApiInternalError => {
-  if (error instanceof OpenApiInternalError) return error;
-  const message = error instanceof Error ? error.message : String(error);
-  return new OpenApiInternalError({ message });
-};
-const sanitizeInternalFailure = <A, R>(
-  effect: Effect.Effect<A, unknown, R>,
-): Effect.Effect<A, OpenApiInternalError, R> =>
-  Effect.catchAllCause(effect, (cause) =>
-    Effect.fail(toOpenApiInternalError(Cause.squash(cause))),
-  );
 // ---------------------------------------------------------------------------
 // Composed API — core + openapi group
 // ---------------------------------------------------------------------------
 // ---------------------------------------------------------------------------
 // Handlers
+//
+// Each handler is exactly: yield the extension service, call the method,
+// return. Plugin SDK errors flow through the typed channel and are
+// schema-encoded to 4xx by HttpApi (see group.ts `.addError(...)` calls).
+// Defects bubble up and are captured + downgraded to `InternalError(traceId)`
+// by the API-level observability middleware.
 // ---------------------------------------------------------------------------
 export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "openapi", (handlers) =>
   handlers
     .handle("previewSpec", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* OpenApiExtensionService;
         return yield* ext.previewSpec(payload.spec);
-      }).pipe(sanitizeSpecFailure),
+      })),
     )
     .handle("addSpec", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* OpenApiExtensionService;
         const result = yield* ext.addSpec({
           spec: payload.spec,
           toolCount: result.toolCount,
           namespace: result.sourceId,
         };
-      }).pipe(sanitizeSpecFailure),
+      })),
     )
     .handle("getSource", ({ path }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* OpenApiExtensionService;
         return yield* ext.getSource(path.namespace);
-      }).pipe(sanitizeInternalFailure),
+      })),
     )
     .handle("updateSource", ({ path, payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* OpenApiExtensionService;
         yield* ext.updateSource(path.namespace, {
           name: payload.name,
           headers: payload.headers as Record<string, HeaderValue> | undefined,
         } as OpenApiUpdateSourceInput);
         return { updated: true };
-      }).pipe(sanitizeInternalFailure),
+      })),
     )
     .handle("startOAuth", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* OpenApiExtensionService;
         return yield* ext.startOAuth({
           displayName: payload.displayName,
           clientSecretSecretId: payload.clientSecretSecretId ?? null,
           scopes: [...payload.scopes],
         });
-      }),
+      })),
     )
     .handle("completeOAuth", ({ payload }) =>
-      Effect.gen(function* () {
+      capture(Effect.gen(function* () {
         const ext = yield* OpenApiExtensionService;
         return yield* ext.completeOAuth({
           state: payload.state,
           code: payload.code,
           error: payload.error,
         });
-      }),
+      })),
     )
     .handle("oauthCallback", ({ urlParams }) =>
-      Effect.gen(function* () {
+      // OAuth popup is special: it always returns 200 HTML and renders the
+      // failure into the popup body so the parent window's listener gets a
+      // structured result.
+      capture(Effect.gen(function* () {
         const ext = yield* OpenApiExtensionService;
-        const html = yield* runOAuthCallback<OAuth2Auth, OpenApiOAuthError, never>({
+        const html = yield* runOAuthCallback<OAuth2Auth, OpenApiOAuthError | InternalError, never>({
           complete: ({ state, code, error }) =>
             ext.completeOAuth({
               state,
           channelName: OPENAPI_OAUTH_CHANNEL,
         });
         return yield* HttpServerResponse.html(html);
-      }).pipe(sanitizeInternalFailure),
+      })),
     ),
 );

packages/plugins/openapi/src/sdk/invoke.ts+29−8

 import { Effect, Layer, Option } from "effect";
 import { HttpClient, HttpClientRequest } from "@effect/platform";
+import type { StorageFailure } from "@executor/sdk";
 import { OpenApiInvocationError } from "./errors";
 import {
   type HeaderValue,
 export const resolveHeaders = (
   headers: Record<string, HeaderValue>,
-  secrets: { readonly get: (id: string) => Effect.Effect<string | null, Error> },
+  secrets: {
-): Effect.Effect<Record<string, string>, Error> =>
+    readonly get: (
+      id: string,
+    ) => Effect.Effect<string | null, StorageFailure>;
+  },
+): Effect.Effect<
+  Record<string, string>,
+  OpenApiInvocationError | StorageFailure
+> =>
   Effect.gen(function* () {
     const entries = Object.entries(headers);
     // Fan out secret lookups: on every invocation, one or two headers
               Effect.flatMap((secret) =>
                 secret === null
                   ? Effect.fail(
-                      new Error(
+                      new OpenApiInvocationError({
-                        `Failed to resolve secret "${value.secretId}" for header "${name}"`,
+                        message: `Failed to resolve secret "${value.secretId}" for header "${name}"`,
-                      ),
+                        statusCode: Option.none(),
+                      }),
                     )
                   : Effect.succeed({
                       name,
   const responseHeaders: Record<string, string> = { ...response.headers };
   const contentType = response.headers["content-type"] ?? null;
+  const mapBodyError = Effect.mapError(
+    (err: { readonly message?: string }) =>
+      new OpenApiInvocationError({
+        message: `Failed to read response body: ${err.message ?? String(err)}`,
+        statusCode: Option.some(status),
+        cause: err,
+      }),
+  );
   const responseBody: unknown =
     status === 204
       ? null
       : isJsonContentType(contentType)
-        ? yield* response.json.pipe(Effect.catchAll(() => response.text))
+        ? yield* response.json.pipe(
-        : yield* response.text;
+            Effect.catchAll(() => response.text),
+            mapBodyError,
+          )
+        : yield* response.text.pipe(mapBodyError);
   const ok = status >= 200 && status < 300;
   baseUrl: string,
   resolvedHeaders: Record<string, string>,
   httpClientLayer: Layer.Layer<HttpClient.HttpClient>,
-): Effect.Effect<InvocationResult, Error> => {
+) => {
   const clientWithBaseUrl = baseUrl
     ? Layer.effect(
         HttpClient.HttpClient,

packages/plugins/openapi/src/sdk/plugin.ts+36−8

   SetSecretInput,
   SourceDetectionResult,
   definePlugin,
+  type StorageFailure,
   type ToolAnnotations,
   type ToolRow,
 } from "@executor/sdk";
   type OpenApiSourceConfig,
 } from "@executor/config";
-import { OpenApiOAuthError } from "./errors";
+import {
+  OpenApiExtractionError,
+  OpenApiOAuthError,
+  OpenApiParseError,
+} from "./errors";
 import { parse, resolveSpecText } from "./parse";
 import { extract } from "./extract";
 import { compileToolDefinitions, type ToolDefinition } from "./definitions";
   readonly error?: string;
 }
+/**
+ * Errors any OpenAPI extension method may surface. The first three are
+ * plugin-domain tagged errors that flow directly to clients (4xx, each
+ * carrying its own `HttpApiSchema` status). `StorageFailure` covers
+ * raw backend failures (`StorageError`) plus `UniqueViolationError`;
+ * the HTTP edge (`@executor/api`'s `withCapture`) translates
+ * `StorageError` to the opaque `InternalError({ traceId })` at Layer
+ * composition. `UniqueViolationError` passes through — plugins can
+ * `Effect.catchTag` it if they want a friendlier user-facing error.
+ */
+export type OpenApiExtensionFailure =
+  | OpenApiParseError
+  | OpenApiExtractionError
+  | OpenApiOAuthError
+  | StorageFailure;
 export interface OpenApiPluginExtension {
-  readonly previewSpec: (specText: string) => Effect.Effect<SpecPreview, Error>;
+  readonly previewSpec: (
+    specText: string,
+  ) => Effect.Effect<SpecPreview, OpenApiParseError | OpenApiExtractionError>;
   readonly addSpec: (
     config: OpenApiSpecConfig,
-  ) => Effect.Effect<{ readonly sourceId: string; readonly toolCount: number }, Error>;
+  ) => Effect.Effect<
-  readonly removeSpec: (namespace: string) => Effect.Effect<void, Error>;
+    { readonly sourceId: string; readonly toolCount: number },
-  readonly getSource: (namespace: string) => Effect.Effect<StoredSource | null, Error>;
+    OpenApiParseError | OpenApiExtractionError | StorageFailure
+  >;
+  readonly removeSpec: (namespace: string) => Effect.Effect<void, StorageFailure>;
+  readonly getSource: (
+    namespace: string,
+  ) => Effect.Effect<StoredSource | null, StorageFailure>;
   readonly updateSource: (
     namespace: string,
     input: OpenApiUpdateSourceInput,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageFailure>;
   readonly startOAuth: (
     input: OpenApiStartOAuthInput,
   ) => Effect.Effect<OpenApiStartOAuthResponse, OpenApiOAuthError>;
       schema: openapiSchema,
       storage: (deps): OpenapiStore => makeDefaultOpenapiStore(deps),
-      extension: (ctx): OpenApiPluginExtension => {
+      extension: (ctx) => {
         // Wraps ctx.secrets.set for the oauth2 helper so createSecret
         // returns the freshly-minted id.
         const createOAuthSecret = (args: {
                   : new OpenApiOAuthError({ message: err.message }),
               ),
             ),
-        };
+        } satisfies OpenApiPluginExtension;
       },
       staticSources: (self) => [

packages/plugins/openapi/src/sdk/store.ts+19−11

 import { Effect, Option, Schema } from "effect";
-import { defineSchema, type StorageDeps } from "@executor/sdk";
+import {
+  defineSchema,
+  type StorageDeps,
+  type StorageFailure,
+} from "@executor/sdk";
 import {
   HeaderValue,
 // Store interface
 // ---------------------------------------------------------------------------
+// Every method routes through the typed adapter (`ctx.storage.adapter`)
+// so the typed error channel is `StorageFailure`. Schema-decode failures
+// inside `Effect.gen` land as defects, not typed errors, and are caught
+// by the HTTP edge's observability middleware.
 export interface OpenapiStore {
   readonly upsertSource: (
     input: StoredSource,
     operations: readonly StoredOperation[],
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageFailure>;
   readonly updateSourceMeta: (
     namespace: string,
       readonly headers?: Record<string, HeaderValue>;
       readonly oauth2?: OAuth2Auth;
     },
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageFailure>;
   readonly getSource: (
     namespace: string,
-  ) => Effect.Effect<StoredSource | null, Error>;
+  ) => Effect.Effect<StoredSource | null, StorageFailure>;
-  readonly listSources: () => Effect.Effect<readonly StoredSource[], Error>;
+  readonly listSources: () => Effect.Effect<readonly StoredSource[], StorageFailure>;
   readonly getOperationByToolId: (
     toolId: string,
-  ) => Effect.Effect<StoredOperation | null, Error>;
+  ) => Effect.Effect<StoredOperation | null, StorageFailure>;
   readonly listOperationsBySource: (
     sourceId: string,
-  ) => Effect.Effect<readonly StoredOperation[], Error>;
+  ) => Effect.Effect<readonly StoredOperation[], StorageFailure>;
-  readonly removeSource: (namespace: string) => Effect.Effect<void, Error>;
+  readonly removeSource: (namespace: string) => Effect.Effect<void, StorageFailure>;
   readonly putOAuthSession: (
     sessionId: string,
     session: OpenApiOAuthSession,
-  ) => Effect.Effect<void, Error>;
+  ) => Effect.Effect<void, StorageFailure>;
   readonly getOAuthSession: (
     sessionId: string,
-  ) => Effect.Effect<OpenApiOAuthSession | null, Error>;
+  ) => Effect.Effect<OpenApiOAuthSession | null, StorageFailure>;
-  readonly deleteOAuthSession: (sessionId: string) => Effect.Effect<void, Error>;
+  readonly deleteOAuthSession: (sessionId: string) => Effect.Effect<void, StorageFailure>;
 }
 // ---------------------------------------------------------------------------

packages/plugins/workos-vault/src/sdk/secret-store.ts+9−6

 import {
   defineSchema,
+  StorageError,
   type SecretProvider,
   type StorageDeps,
+  type StorageFailure,
 } from "@executor/sdk";
 import {
 // ---------------------------------------------------------------------------
 export interface WorkosVaultStore {
-  readonly get: (id: string) => Effect.Effect<MetadataRow | null, Error>;
+  readonly get: (id: string) => Effect.Effect<MetadataRow | null, StorageFailure>;
-  readonly upsert: (row: MetadataRow) => Effect.Effect<void, Error>;
+  readonly upsert: (row: MetadataRow) => Effect.Effect<void, StorageFailure>;
-  readonly remove: (id: string) => Effect.Effect<boolean, Error>;
+  readonly remove: (id: string) => Effect.Effect<boolean, StorageFailure>;
-  readonly list: () => Effect.Effect<readonly MetadataRow[], Error>;
+  readonly list: () => Effect.Effect<readonly MetadataRow[], StorageFailure>;
 }
 export const makeWorkosVaultStore = (
     return true;
   });
-const formatVaultError = (error: unknown): Error => {
+const formatVaultError = (error: unknown): StorageError => {
   const cause = unwrapVaultError(error);
-  return cause instanceof Error ? cause : new Error(String(cause));
+  const message = cause instanceof Error ? cause.message : String(cause);
+  return new StorageError({ message, cause });
 };
 // ---------------------------------------------------------------------------