lael-labs/executor

.oxlintrc.jsonc+2−0

@@ -40,6 +40,8 @@ · 39 unmodified lines
40		40
41	// Monorepo-specific rules.	41	// Monorepo-specific rules.
42	"executor-monorepo/no-cross-workspace-relative-imports": "error",	42	"executor-monorepo/no-cross-workspace-relative-imports": "error",
		43	"executor-monorepo/no-raw-effect-fail-errors": "error",
		44	"executor-monorepo/no-yield-effect-fail": "error",
43	"executor-monorepo/no-workspace-src-imports": "warn"	45	"executor-monorepo/no-workspace-src-imports": "warn"
44	},	46	},
45		47

apps/executor/src/cli/main.ts+37−32

 import { dirname, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { FileSystem } from "@effect/platform";
 import { Args, Command, Options } from "@effect/cli";
 import {
   NodeFileSystem,
   parseInteractionPayload,
 } from "./pending-interaction-output";
 import { decideInteractionHandling } from "./interaction-handling";
+import {
+  executorAppEffectError,
+  type LocalServerReachabilityTimeoutError,
+  localServerReachabilityTimeoutError,
+} from "../effect-errors";
 const toError = (cause: unknown): Error =>
   cause instanceof Error ? cause : new Error(String(cause));
       }
     }
-    return yield* Effect.fail(
+    return yield* executorAppEffectError("cli/main", "Provide code as a positional argument, use --file, or pipe code over stdin.");
-      new Error("Provide code as a positional argument, use --file, or pipe code over stdin."),
-    );
   });
 const getBootstrapClient = (baseUrl: string = DEFAULT_SERVER_BASE_URL) =>
 };
-const readServerLogTail = async (
+const readServerLogTail = (
   logFile: string = DEFAULT_SERVER_LOG_FILE,
   maxLines: number = 40,
   maxChars: number = 6000,
-): Promise<string | null> => {
+): Effect.Effect<string | null, never, FileSystem.FileSystem> =>
-  try {
+  Effect.gen(function* () {
-    const contents = await readFile(logFile, "utf8");
+    const fs = yield* FileSystem.FileSystem;
+    const contents = yield* fs.readFileString(logFile, "utf8").pipe(
+      Effect.catchAll(() => Effect.succeed<string | null>(null)),
+    );
+    if (contents === null) {
+      return null;
+    }
     const lines = contents.split(/\r?\n/u).filter((line) => line.length > 0);
     const tail = lines.slice(-maxLines).join("\n");
     return tail.length > maxChars ? tail.slice(-maxChars) : tail;
-  } catch {
+  });
-    return null;
-  }
-};
-const buildReachabilityTimeoutError = async (
-  baseUrl: string,
-  expected: boolean,
-  logFile: string = DEFAULT_SERVER_LOG_FILE,
-): Promise<Error> => {
-  const action = expected ? "start" : "shutdown";
-  const prefix = `Timed out waiting for local executor server ${action} at ${baseUrl}`;
-  const logTail = await readServerLogTail(logFile);
-  if (!logTail) {
+const failReachabilityTimeout = (input: {
-    return new Error(`${prefix}\n\nDaemon log: ${logFile}`);
+  baseUrl: string;
-  }
+  expected: boolean;
+  logFile?: string;
+}): Effect.Effect<never, LocalServerReachabilityTimeoutError, FileSystem.FileSystem> =>
+  Effect.gen(function* () {
+    const logFile = input.logFile ?? DEFAULT_SERVER_LOG_FILE;
+    const logTail = yield* readServerLogTail(logFile);
-  return new Error(`${prefix}\n\nRecent daemon log (${logFile}):\n${logTail}`);
+    return yield* localServerReachabilityTimeoutError({
-};
+      baseUrl: input.baseUrl,
+      expected: input.expected,
+      logFile,
+      logTail,
+    });
+  });
 const waitForReachability = (baseUrl: string, expected: boolean) =>
   Effect.gen(function* () {
       yield* sleep(SERVER_POLL_INTERVAL_MS);
     }
-    const error = yield* Effect.tryPromise({
+    return yield* failReachabilityTimeout({ baseUrl, expected });
-      try: () => buildReachabilityTimeoutError(baseUrl, expected),
-      catch: toError,
-    });
-    return yield* Effect.fail(error);
   });
 type LocalServerStatus = {
       Effect.catchAll(() =>
         Effect.tryPromise(() => rm(DEFAULT_SERVER_PID_FILE, { force: true })).pipe(
           Effect.ignore,
-          Effect.zipRight(Effect.fail(new Error(`Timed out stopping local executor server pid ${pid}`))),
+          Effect.zipRight(Effect.fail(executorAppEffectError("cli/main", `Timed out stopping local executor server pid ${pid}`))),
         ),
       ),
     );

apps/executor/src/distribution/harness.ts+3−2

 import * as Layer from "effect/Layer";
 import { buildDistributionPackage } from "./artifact";
+import { executorAppEffectError } from "../effect-errors";
 type CommandResult = {
   readonly stdout: string;
         return;
       }
-      resume(Effect.fail(new Error(
+      resume(Effect.fail(executorAppEffectError("distribution/harness",
         [
           `${input.command} ${input.args.join(" ")} exited with code ${exitCode}`,
           stdout.length > 0 ? `stdout:\n${stdout.trim()}` : null,
       if (!tarballName) {
         return Effect.fail(
-          new Error(`Unable to determine tarball name from npm pack output: ${result.stdout}`),
+          executorAppEffectError("distribution/harness", `Unable to determine tarball name from npm pack output: ${result.stdout}`),
         );
       }

apps/executor/src/effect-errors.ts+40−0

@@ -0,0 +1,40 @@
	1	import * as Data from "effect/Data";
	2
	3	export class ExecutorAppEffectError extends Data.TaggedError(
	4	"ExecutorAppEffectError",
	5	)<{
	6	readonly module: string;
	7	readonly message: string;
	8	}> {}
	9
	10	export const executorAppEffectError = (
	11	module: string,
	12	message: string,
	13	) => new ExecutorAppEffectError({ module, message });
	14
	15	export class LocalServerReachabilityTimeoutError extends Data.TaggedError(
	16	"LocalServerReachabilityTimeoutError",
	17	)<{
	18	readonly baseUrl: string;
	19	readonly action: "start" \| "shutdown";
	20	readonly logFile: string;
	21	readonly logTail: string \| null;
	22	readonly message: string;
	23	}> {}
	24
	25	export const localServerReachabilityTimeoutError = (input: {
	26	baseUrl: string;
	27	expected: boolean;
	28	logFile: string;
	29	logTail: string \| null;
	30	}) =>
	31	new LocalServerReachabilityTimeoutError({
	32	baseUrl: input.baseUrl,
	33	action: input.expected ? "start" : "shutdown",
	34	logFile: input.logFile,
	35	logTail: input.logTail,
	36	message:
	37	input.logTail === null
	38	? `Timed out waiting for local executor server ${input.expected ? "start" : "shutdown"} at ${input.baseUrl}\n\nDaemon log: ${input.logFile}`
	39	: `Timed out waiting for local executor server ${input.expected ? "start" : "shutdown"} at ${input.baseUrl}\n\nRecent daemon log (${input.logFile}):\n${input.logTail}`,
	40	});

packages/auth/mcp-oauth/src/effect-errors.ts+13−0

@@ -0,0 +1,13 @@
	1	import * as Data from "effect/Data";
	2
	3	export class McpOAuthEffectError extends Data.TaggedError(
	4	"McpOAuthEffectError",
	5	)<{
	6	readonly module: string;
	7	readonly message: string;
	8	}> {}
	9
	10	export const mcpOAuthEffectError = (
	11	module: string,
	12	message: string,
	13	) => new McpOAuthEffectError({ module, message });

packages/auth/mcp-oauth/src/index.ts+3−6

   OAuthTokens,
 } from "@modelcontextprotocol/sdk/shared/auth.js";
 import * as Effect from "effect/Effect";
+import { mcpOAuthEffectError } from "./effect-errors";
 type JsonValue =
   | string
     });
     if (result !== "REDIRECT" || !captured.authorizationUrl || !captured.codeVerifier) {
-      return yield* Effect.fail(
+      return yield* mcpOAuthEffectError("index", "OAuth flow did not produce an authorization redirect");
-        new Error("OAuth flow did not produce an authorization redirect"),
-      );
     }
     return {
     });
     if (result !== "AUTHORIZED" || !captured.tokens) {
-      return yield* Effect.fail(
+      return yield* mcpOAuthEffectError("index", "OAuth redirect did not complete MCP OAuth setup");
-        new Error("OAuth redirect did not complete MCP OAuth setup"),
-      );
     }
     return {

packages/dev/kitchen-sink/src/effect-errors.ts+13−0

@@ -0,0 +1,13 @@
	1	import * as Data from "effect/Data";
	2
	3	export class KitchenSinkEffectError extends Data.TaggedError(
	4	"KitchenSinkEffectError",
	5	)<{
	6	readonly module: string;
	7	readonly message: string;
	8	}> {}
	9
	10	export const kitchenSinkEffectError = (
	11	module: string,
	12	message: string,
	13	) => new KitchenSinkEffectError({ module, message });

packages/dev/kitchen-sink/src/kitchen-sink.test.ts+2−1

   toExecutorTool,
 } from "@executor/codemode-core";
 import { makeSesExecutor } from "@executor/runtime-ses";
+import { kitchenSinkEffectError } from "./effect-errors";
 const numberPairInputSchema = Schema.standardSchemaV1(
   Schema.Struct({
       }).execute;
       if (!execute) {
-        return yield* Effect.fail(new Error("Code tool execute function is missing"));
+        return yield* kitchenSinkEffectError("kitchen-sink.test", "Code tool execute function is missing");
       }
       const output = yield* Effect.tryPromise({

packages/hosts/ai-sdk/src/effect-errors.ts+13−0

@@ -0,0 +1,13 @@
	1	import * as Data from "effect/Data";
	2
	3	export class AiSdkEffectError extends Data.TaggedError(
	4	"AiSdkEffectError",
	5	)<{
	6	readonly module: string;
	7	readonly message: string;
	8	}> {}
	9
	10	export const aiSdkEffectError = (
	11	module: string,
	12	message: string,
	13	) => new AiSdkEffectError({ module, message });

packages/hosts/ai-sdk/src/index.ts+2−1

   type ToolMap,
   type ToolInvoker,
 } from "@executor/codemode-core";
+import { aiSdkEffectError } from "./effect-errors";
 export type AiSdkToolMap = ToolSet;
         input.executor.execute(code, input.toolInvoker).pipe(
           Effect.flatMap((result: ExecuteResult) =>
             result.error
-              ? Effect.fail(new Error(result.error))
+              ? Effect.fail(aiSdkEffectError("index", result.error))
               : Effect.succeed({
                   code,
                   result: result.result,

packages/kernel/core/src/effect-errors.ts+13−0

@@ -0,0 +1,13 @@
	1	import * as Data from "effect/Data";
	2
	3	export class KernelCoreEffectError extends Data.TaggedError(
	4	"KernelCoreEffectError",
	5	)<{
	6	readonly module: string;
	7	readonly message: string;
	8	}> {}
	9
	10	export const kernelCoreEffectError = (
	11	module: string,
	12	message: string,
	13	) => new KernelCoreEffectError({ module, message });

packages/kernel/core/src/tool-map.ts+5−4

   ToolMetadata,
   ToolPath,
 } from "./types";
+import { kernelCoreEffectError } from "./effect-errors";
 type ResolvedTool = {
   path: ToolPath;
   const validate = getSchemaValidator(input.schema);
   if (!validate) {
     return Effect.fail(
-      new Error(`Tool ${input.path} has no Standard Schema validator on inputSchema`),
+      kernelCoreEffectError("tool-map", `Tool ${input.path} has no Standard Schema validator on inputSchema`),
     );
   }
     Effect.flatMap((result) => {
       if ("issues" in result && result.issues) {
         return Effect.fail(
-          new Error(
+          kernelCoreEffectError("tool-map",
             `Input validation failed for ${input.path}: ${formatIssues(result.issues)}`,
           ),
         );
   if (!isRecord(input.args)) {
     return Effect.fail(
-      new Error(
+      kernelCoreEffectError("tool-map",
         `Tool ${input.path} cannot merge elicitation content into non-object arguments`,
       ),
     );
       Effect.gen(function* () {
         const entry = byPath.get(path);
         if (!entry) {
-          return yield* Effect.fail(new Error(`Unknown tool path: ${path}`));
+          return yield* kernelCoreEffectError("tool-map", `Unknown tool path: ${path}`);
         }
         const parsedInput = yield* parseInput({

packages/platform/control-plane/src/api/local/http.ts+10−18

             : parseSecretStoreProviderId(payload.providerId);
           if (name.length === 0) {
-            return yield* Effect.fail(
+            return yield* new ControlPlaneBadRequestError({
-              new ControlPlaneBadRequestError({
                 operation: "secrets.create",
                 message: "Secret name is required.",
                 details: "Secret name is required.",
-              }),
+              });
-            );
           }
           if (payload.providerId !== undefined && requestedProviderId === null) {
-            return yield* Effect.fail(
+            return yield* new ControlPlaneBadRequestError({
-              new ControlPlaneBadRequestError({
                 operation: "secrets.create",
                 message: `Unsupported secret provider: ${payload.providerId}`,
                 details: `Unsupported secret provider: ${payload.providerId}`,
-              }),
+              });
-            );
           }
           const store = yield* ControlPlaneStore;
           );
           if (Option.isNone(created)) {
-            return yield* Effect.fail(storageError(`Created secret not found: ${ref.handle}`));
+            return yield* storageError(`Created secret not found: ${ref.handle}`);
           }
           return {
           );
           if (Option.isNone(existing)) {
-            return yield* Effect.fail(
+            return yield* new ControlPlaneNotFoundError({
-              new ControlPlaneNotFoundError({
                 operation: "secrets.update",
                 message: `Secret not found: ${path.secretId}`,
                 details: `Secret not found: ${path.secretId}`,
-              }),
+              });
-            );
           }
           const update: { name?: string | null; value?: string } = {};
           );
           if (Option.isNone(existing)) {
-            return yield* Effect.fail(
+            return yield* new ControlPlaneNotFoundError({
-              new ControlPlaneNotFoundError({
                 operation: "secrets.delete",
                 message: `Secret not found: ${path.secretId}`,
                 details: `Secret not found: ${path.secretId}`,
-              }),
+              });
-            );
           }
           const deleteSecretMaterial = createDefaultSecretMaterialDeleter({
           );
           if (!removed) {
-            return yield* Effect.fail(storageError(`Failed removing secret: ${path.secretId}`));
+            return yield* storageError(`Failed removing secret: ${path.secretId}`);
           }
           return { removed: true };

packages/platform/control-plane/src/runtime/auth/auth-artifacts.ts+5−8

   ResolveSecretMaterial,
   SecretMaterialResolveContext,
 } from "../local/secret-material-providers";
+import { runtimeEffectError } from "../effect-errors";
 export type ResolvedSourceAuthMaterial = {
   placements: ReadonlyArray<RequestPlacement>;
     const providerGrantRefConfig = decodeProviderGrantRefAuthArtifactConfig(input.artifact);
     if (providerGrantRefConfig !== null) {
       if (input.lease === null || input.lease === undefined) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("auth/auth-artifacts", `Provider grant auth artifact ${input.artifact.id} requires a lease`);
-          new Error(`Provider grant auth artifact ${input.artifact.id} requires a lease`),
-        );
       }
     }
     }
     if (input.lease === null || input.lease === undefined) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("auth/auth-artifacts", `Unsupported auth artifact kind: ${input.artifact.artifactKind}`);
-        new Error(`Unsupported auth artifact kind: ${input.artifact.artifactKind}`),
-      );
     }
     const templatesEither = decodeRequestPlacementTemplates(
       input.lease.placementsTemplateJson,
     );
     if (templatesEither._tag === "Left") {
-      return yield* Effect.fail(new Error(
+      return yield* runtimeEffectError("auth/auth-artifacts",
         `Invalid auth lease placements for artifact ${input.artifact.id}`,
-      ));
+      );
     }
     const placements = yield* Effect.forEach(templatesEither.right, (placement) =>

packages/platform/control-plane/src/runtime/auth/auth-leases.ts+6−15

 import { refreshOAuth2AccessToken } from "./oauth2-pkce";
 import type { OAuth2TokenResponse } from "./oauth2-pkce";
 import { createPersistedMcpAuthProvider } from "./mcp-auth-provider";
+import { runtimeEffectError } from "../effect-errors";
 const LEASE_REFRESH_SKEW_MS = 60_000;
       decoded === null
       || decoded.artifactKind !== RefreshableOAuth2AuthorizedUserAuthArtifactKind
     ) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("auth/auth-leases", `Unsupported auth artifact kind: ${input.artifact.artifactKind}`);
-        new Error(`Unsupported auth artifact kind: ${input.artifact.artifactKind}`),
-      );
     }
     const refreshToken = yield* input.resolveSecretMaterial({
   Effect.gen(function* () {
     const config = decodeProviderGrantRefAuthArtifactConfig(input.artifact);
     if (config === null) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("auth/auth-leases", `Unsupported auth artifact kind: ${input.artifact.artifactKind}`);
-        new Error(`Unsupported auth artifact kind: ${input.artifact.artifactKind}`),
-      );
     }
     const grantOption = yield* input.rows.providerAuthGrants.getById(config.grantId);
     if (Option.isNone(grantOption)) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("auth/auth-leases", `Provider auth grant not found: ${config.grantId}`);
-        new Error(`Provider auth grant not found: ${config.grantId}`),
-      );
     }
     const grant = grantOption.value;
     const oauthClientOption = yield* input.rows.workspaceOauthClients.getById(grant.oauthClientId);
     if (Option.isNone(oauthClientOption)) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("auth/auth-leases", `Workspace OAuth client not found: ${grant.oauthClientId}`);
-        new Error(`Workspace OAuth client not found: ${grant.oauthClientId}`),
-      );
     }
     const oauthClient = oauthClientOption.value;
       decoded === null
       || decoded.artifactKind !== RefreshableOAuth2AuthorizedUserAuthArtifactKind
     ) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("auth/auth-leases", `Unsupported auth artifact kind: ${input.artifact.artifactKind}`);
-        new Error(`Unsupported auth artifact kind: ${input.artifact.artifactKind}`),
-      );
     }
     const existingLeaseOption = yield* input.rows.authLeases.getByAuthArtifactId(input.artifact.id);

packages/platform/control-plane/src/runtime/auth/source-auth-material.ts+2−3

   SecretMaterialResolveContext,
 } from "../local/secret-material-providers";
 import { SecretMaterialResolverService } from "../local/secret-material-providers";
+import { runtimeEffectError } from "../effect-errors";
 const authForSlot = (input: {
   source: Source;
       || artifact?.artifactKind === "provider_grant_ref"
       || artifact?.artifactKind === "mcp_oauth"
     ) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("auth/source-auth-material", "Dynamic auth artifacts require persistence-backed lease resolution");
-        new Error("Dynamic auth artifacts require persistence-backed lease resolution"),
-      );
     }
     return yield* resolveAuthArtifactMaterial({

packages/platform/control-plane/src/runtime/catalog/source/runtime.ts+4−5

   RuntimeSourceStoreService,
   type RuntimeSourceStore,
 } from "../../sources/source-store";
+import { runtimeEffectError } from "../../effect-errors";
 type CatalogImportMetadata = CatalogSnapshotV1["import"];
 ) => {
   if (deps.runtimeLocalWorkspace.installation.workspaceId !== workspaceId) {
     return Effect.fail(
-      new Error(
+      runtimeEffectError("catalog/source/runtime",
         `Runtime local workspace mismatch: expected ${workspaceId}, got ${deps.runtimeLocalWorkspace.installation.workspaceId}`,
       ),
     );
       sourceId: source.id,
     });
     if (artifact === null) {
-      return yield* Effect.fail(
+      return yield* new LocalSourceArtifactMissingError({
-        new LocalSourceArtifactMissingError({
           message: `Catalog artifact missing for source ${input.sourceId}`,
           sourceId: input.sourceId,
-        }),
+        });
-      );
     }
     const snapshot = buildSnapshotFromArtifact({

packages/platform/control-plane/src/runtime/catalog/source/sync.ts+2−1

 import {
   refreshSourceTypeDeclarationInBackground,
 } from "./type-declarations";
+import { runtimeEffectError } from "../../effect-errors";
 const shouldIndexSource = (source: Source): boolean =>
   source.enabled
 ) => {
   if (deps.runtimeLocalWorkspace.installation.workspaceId !== workspaceId) {
     return Effect.fail(
-      new Error(
+      runtimeEffectError("catalog/source/sync",
         `Runtime local workspace mismatch: expected ${workspaceId}, got ${deps.runtimeLocalWorkspace.installation.workspaceId}`,
       ),
     );

packages/platform/control-plane/src/runtime/control-plane-runtime.test.ts+2−1

 import { decodeSourceCredentialSelectionContent } from "./sources/source-credential-interactions";
 import { persistSource } from "./sources/source-store";
 import { withControlPlaneClient } from "./execution/test-http-client";
+import { runtimeEffectError } from "./effect-errors";
 const makeRuntime = Effect.gen(function* () {
   const fs = yield* FileSystem.FileSystem;
     Effect.flatMap((result) =>
       result._tag === "Left"
         ? Effect.succeed(result.left)
-        : Effect.fail(new Error("Expected effect to fail")),
+        : Effect.fail(runtimeEffectError("control-plane-runtime.test", "Expected effect to fail")),
     ),
   );

packages/platform/control-plane/src/runtime/effect-errors.ts+13−0

@@ -0,0 +1,13 @@
	1	import * as Data from "effect/Data";
	2
	3	export class RuntimeEffectError extends Data.TaggedError(
	4	"RuntimeEffectError",
	5	)<{
	6	readonly module: string;
	7	readonly message: string;
	8	}> {}
	9
	10	export const runtimeEffectError = (
	11	module: string,
	12	message: string,
	13	) => new RuntimeEffectError({ module, message });

packages/platform/control-plane/src/runtime/execution/ir-execution.ts+2−1

 import type { LoadedSourceCatalogToolIndexEntry } from "../catalog/source/runtime";
 import type { ResolvedSourceAuthMaterial } from "../auth/source-auth-material";
 import { getSourceAdapter } from "../sources/source-adapters";
+import { runtimeEffectError } from "../effect-errors";
 export const invocationDescriptorFromTool = (input: {
   tool: LoadedSourceCatalogToolIndexEntry;
   const adapter = getSourceAdapter(input.tool.executable.adapterKey);
   if (adapter.key !== input.tool.source.kind) {
     return Effect.fail(
-      new Error(
+      runtimeEffectError("execution/ir-execution",
         `Executable ${input.tool.executable.id} expects adapter ${adapter.key}, but source ${input.tool.source.id} is ${input.tool.source.kind}`,
       ),
     );

packages/platform/control-plane/src/runtime/execution/service.ts+32−28

   type ExecutionInteraction,
   type WorkspaceId,
 } from "#schema";
+import * as Data from "effect/Data";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
   type ControlPlaneStoreShape,
 } from "../store";
 import { RuntimeExecutionResolverService } from "./workspace/environment";
+import { runtimeEffectError } from "../effect-errors";
 const executionOps = {
   create: operationErrors("executions.create"),
 ): InteractionMode =>
   value === "live" || value === "live_form" ? value : DEFAULT_INTERACTION_MODE;
+class ExecutionSuspendedError extends Data.TaggedError(
+  "ExecutionSuspendedError",
+)<{
+  readonly executionId: Execution["id"];
+  readonly interactionId: string;
+  readonly message: string;
+}> {}
 const createExecutionSuspendedError = (input: {
   executionId: Execution["id"];
   interactionId: string;
-}): Error =>
+}): ExecutionSuspendedError =>
-  new Error(
+  new ExecutionSuspendedError({
-    `${EXECUTION_SUSPENDED_SENTINEL}:${input.executionId}:${input.interactionId}`,
+    executionId: input.executionId,
-  );
+    interactionId: input.interactionId,
+    message: `${EXECUTION_SUSPENDED_SENTINEL}:${input.executionId}:${input.interactionId}`,
+  });
 const isExecutionSuspendedValue = (value: unknown): boolean => {
+  if (value instanceof ExecutionSuspendedError) {
+    return true;
+  }
   if (value instanceof Error) {
     return value.message.includes(EXECUTION_SUSPENDED_SENTINEL);
   }
     );
     if (Option.isNone(existing)) {
-      return yield* Effect.fail(
+      return yield* errors.notFound(
-        errors.notFound(
           "Execution not found",
           `workspaceId=${input.workspaceId} executionId=${input.executionId}`,
-        ),
+        );
-      );
     }
     return existing.value;
       state: "waiting_for_interaction",
     });
-    return yield* Effect.fail(
+    return yield* createExecutionSuspendedError({
-      createExecutionSuspendedError({
         executionId: input.executionId,
         interactionId: input.interactionId,
-      }),
+      });
-    );
   });
 const createHybridOnElicitation = (input: {
         }
         if (existing.value.status === "failed") {
-          return yield* Effect.fail(
+          return yield* runtimeEffectError("execution/service",
-            new Error(
               existing.value.errorText
                 ?? `Stored tool step ${String(stepSequence)} failed`,
-            ),
+            );
-          );
         }
       } else {
         const now = Date.now();
     );
     if (Option.isNone(running)) {
-      return yield* Effect.fail(
+      return yield* executionOps.create.notFound(
-        executionOps.create.notFound(
           "Execution not found after insert",
           `executionId=${execution.id}`,
-        ),
+        );
-      );
     }
     const nextState = yield* liveExecutionManager.registerStateWaiter(execution.id);
         && existing.pendingInteraction !== null
       )
     ) {
-      return yield* Effect.fail(
+      return yield* executionOps.resume.badRequest(
-        executionOps.resume.badRequest(
           "Execution is not waiting for interaction",
           `executionId=${input.executionId} status=${existing.execution.status}`,
-        ),
+        );
-      );
     }
     const responseJson = input.payload.responseJson;
       );
       if (!resumed) {
-        return yield* Effect.fail(
+        return yield* executionOps.resume.badRequest(
-          executionOps.resume.badRequest(
             "Resume is unavailable for this execution",
             `executionId=${input.executionId}`,
-          ),
+          );
-        );
       }
     }

packages/platform/control-plane/src/runtime/execution/workspace/authorization.ts+6−9

 import { invocationDescriptorFromTool } from "../ir-execution";
 import { evaluateInvocationPolicy } from "../../policy/invocation-policy-engine";
 import { loadRuntimeLocalWorkspacePolicies } from "../../policy/policies-operations";
+import { runtimeEffectError } from "../../effect-errors";
 const asToolPath = (value: string): ToolPath => value as ToolPath;
     }
     if (decision.kind === "deny") {
-      return yield* Effect.fail(new Error(decision.reason));
+      return yield* runtimeEffectError("execution/workspace/authorization", decision.reason);
     }
     if (!input.onElicitation) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("execution/workspace/authorization",
-        new Error(
           `Approval required for ${descriptor.toolPath}, but no elicitation-capable host is available`,
-        ),
+        );
-      );
     }
     const interactionId =
       );
     if (response.action !== "accept") {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("execution/workspace/authorization",
-        new Error(
           `Tool invocation not approved for ${descriptor.toolPath}`,
-        ),
+        );
-      );
     }
   });

packages/platform/control-plane/src/runtime/execution/workspace/tool-invoker.ts+2−3

   createWorkspaceSourceCatalog,
   loadWorkspaceCatalogToolByPath,
 } from "./source-catalog";
+import { runtimeEffectError } from "../../effect-errors";
 export const createWorkspaceToolInvoker = (input: {
   workspaceId: Source["workspaceId"];
           includeSchemas: false,
         });
         if (!catalogTool) {
-          return yield* Effect.fail(
+          return yield* runtimeEffectError("execution/workspace/tool-invoker", `Unknown tool path: ${invocation.path}`);
-            new Error(`Unknown tool path: ${invocation.path}`),
-          );
         }
         yield* authorizePersistedToolInvocation({

packages/platform/control-plane/src/runtime/local/operations.ts+14−28

     );
     if (Option.isNone(stored)) {
-      return yield* Effect.fail(
+      return yield* input.operation.notFound(
-        input.operation.notFound(
           "Source credential request not found",
           `interactionId=${input.interactionId}`,
-        ),
+        );
-      );
     }
     const decoded = decodeSourceCredentialInteraction(stored.value);
       || decoded.workspaceId !== input.workspaceId
       || decoded.sourceId !== input.sourceId
     ) {
-      return yield* Effect.fail(
+      return yield* input.operation.notFound(
-        input.operation.notFound(
           "Source credential request not found",
           `workspaceId=${input.workspaceId} sourceId=${input.sourceId} interactionId=${input.interactionId}`,
-        ),
+        );
-      );
     }
     const source = yield* sourceAuthService.getSourceById({
     });
     if (interaction.status !== "pending") {
-      return yield* Effect.fail(
+      return yield* localOps.sourceCredentialSubmit.badRequest(
-        localOps.sourceCredentialSubmit.badRequest(
           "Source credential request is no longer active",
           `interactionId=${interaction.interactionId} status=${interaction.status}`,
-        ),
+        );
-      );
     }
     const liveExecutionManager = yield* LiveExecutionManagerService;
         );
         if (!persisted) {
-          return yield* Effect.fail(
+          return yield* localOps.sourceCredentialSubmit.badRequest(
-            localOps.sourceCredentialSubmit.badRequest(
               "Source credential request is no longer resumable",
               `interactionId=${interaction.interactionId}`,
-            ),
+            );
-          );
         }
       }
         );
         if (!persisted) {
-          return yield* Effect.fail(
+          return yield* localOps.sourceCredentialSubmit.badRequest(
-            localOps.sourceCredentialSubmit.badRequest(
               "Source credential request is no longer resumable",
               `interactionId=${interaction.interactionId}`,
-            ),
+            );
-          );
         }
       }
     const token = trimOrNull(input.token);
     if (token === null) {
-      return yield* Effect.fail(
+      return yield* localOps.sourceCredentialSubmit.badRequest(
-        localOps.sourceCredentialSubmit.badRequest(
           "Missing token",
           `interactionId=${interaction.interactionId}`,
-        ),
+        );
-      );
     }
     const sourceAuthService = yield* RuntimeSourceAuthServiceTag;
       );
       if (!persisted) {
-        return yield* Effect.fail(
+        return yield* localOps.sourceCredentialSubmit.badRequest(
-          localOps.sourceCredentialSubmit.badRequest(
             "Source credential request is no longer resumable",
             `interactionId=${interaction.interactionId}`,
-          ),
+          );
-        );
       }
     }

packages/platform/control-plane/src/runtime/local/runtime-context.ts+4−8

   Effect.gen(function* () {
     const runtimeLocalWorkspace = yield* getRuntimeLocalWorkspaceOption();
     if (runtimeLocalWorkspace === null) {
-      return yield* Effect.fail(
+      return yield* new RuntimeLocalWorkspaceUnavailableError({
-        new RuntimeLocalWorkspaceUnavailableError({
           message: "Runtime local workspace is unavailable",
-        }),
+        });
-      );
     }
     if (
       workspaceId !== undefined
       && runtimeLocalWorkspace.installation.workspaceId !== workspaceId
     ) {
-      return yield* Effect.fail(
+      return yield* new RuntimeLocalWorkspaceMismatchError({
-        new RuntimeLocalWorkspaceMismatchError({
           message: `Workspace ${workspaceId} is not the active local workspace ${runtimeLocalWorkspace.installation.workspaceId}`,
           requestedWorkspaceId: workspaceId,
           activeWorkspaceId: runtimeLocalWorkspace.installation.workspaceId,
-        }),
+        });
-      );
     }
     return runtimeLocalWorkspace;

packages/platform/control-plane/src/runtime/local/secret-material-providers.ts+29−44

 import { getRuntimeLocalWorkspaceOption } from "./runtime-context";
 import { ControlPlaneStore } from "../store";
 import type { ControlPlaneStoreShape } from "../store";
+import { runtimeEffectError } from "../effect-errors";
 export const ENV_SECRET_PROVIDER_ID = "env";
 export const PARAMS_SECRET_PROVIDER_ID = "params";
     ?? ensureNonEmptyString(input.result.stdout)
     ?? "command returned non-zero exit code";
-  return Effect.fail(new Error(`${input.operation}: ${input.message}: ${details}`));
+  return Effect.fail(runtimeEffectError("local/secret-material-providers", `${input.operation}: ${input.message}: ${details}`));
 };
 const commandAvailabilityCache = new Map<string, Promise<boolean>>();
     const materialId = SecretMaterialIdSchema.make(input.id);
     const stored = yield* input.runtime.rows.secretMaterials.getById(materialId);
     if (Option.isNone(stored)) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("local/secret-material-providers", `${input.operation}: secret material not found: ${input.id}`);
-        new Error(`${input.operation}: secret material not found: ${input.id}`),
-      );
     }
     return stored.value;
       operation: input.operation,
     });
     if (material.providerId !== KEYCHAIN_SECRET_PROVIDER_ID) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("local/secret-material-providers",
-        new Error(
           `${input.operation}: secret ${material.id} is stored in provider '${material.providerId}', not '${KEYCHAIN_SECRET_PROVIDER_ID}'`,
-        ),
+        );
-      );
     }
     return {
       );
     default:
       return Effect.fail(
-        new Error(`keychain.get: keychain provider is unsupported on platform '${process.platform}'`),
+        runtimeEffectError("local/secret-material-providers", `keychain.get: keychain provider is unsupported on platform '${process.platform}'`),
       );
   }
 };
       );
     default:
       return Effect.fail(
-        new Error(`keychain.put: keychain provider is unsupported on platform '${process.platform}'`),
+        runtimeEffectError("local/secret-material-providers", `keychain.put: keychain provider is unsupported on platform '${process.platform}'`),
       );
   }
 };
       );
     default:
       return Effect.fail(
-        new Error(`keychain.delete: keychain provider is unsupported on platform '${process.platform}'`),
+        runtimeEffectError("local/secret-material-providers", `keychain.delete: keychain provider is unsupported on platform '${process.platform}'`),
       );
   }
 };
   resolve: ({ ref, context }) => {
     const value = ensureNonEmptyString(context.params?.[ref.handle]);
     if (value === null) {
-      return Effect.fail(new Error(`Secret parameter ${ref.handle} is not set`));
+      return Effect.fail(runtimeEffectError("local/secret-material-providers", `Secret parameter ${ref.handle} is not set`));
     }
     return Effect.succeed(value);
   resolve: ({ ref, runtime }) => {
     if (!runtime.dangerouslyAllowEnvSecrets) {
       return Effect.fail(
-        new Error(
+        runtimeEffectError("local/secret-material-providers",
           `Env-backed secrets are disabled. Set ${DANGEROUSLY_ALLOW_ENV_SECRETS_ENV}=true to allow provider '${ENV_SECRET_PROVIDER_ID}'.`,
         ),
       );
     const value = ensureNonEmptyString(runtime.env[ref.handle]);
     if (value === null) {
-      return Effect.fail(new Error(`Environment variable ${ref.handle} is not set`));
+      return Effect.fail(runtimeEffectError("local/secret-material-providers", `Environment variable ${ref.handle} is not set`));
     }
     return Effect.succeed(value);
         operation: "local.get",
       });
       if (stored.providerId !== LOCAL_SECRET_PROVIDER_ID) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("local/secret-material-providers",
-          new Error(
             `local.get: secret ${stored.id} is stored in provider '${stored.providerId}', not '${LOCAL_SECRET_PROVIDER_ID}'`,
-          ),
+          );
-        );
       }
       if (stored.value === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("local/secret-material-providers", `local.get: secret ${stored.id} does not have a local value`);
-          new Error(`local.get: secret ${stored.id} does not have a local value`),
-        );
       }
       return stored.value;
         operation: "local.update",
       });
       if (stored.providerId !== LOCAL_SECRET_PROVIDER_ID) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("local/secret-material-providers",
-          new Error(
             `local.update: secret ${stored.id} is stored in provider '${stored.providerId}', not '${LOCAL_SECRET_PROVIDER_ID}'`,
-          ),
+          );
-        );
       }
       if (name === undefined && value === undefined) {
         },
       );
       if (Option.isNone(updated)) {
-        return yield* Effect.fail(new Error(`local.update: secret material not found: ${stored.id}`));
+        return yield* runtimeEffectError("local/secret-material-providers", `local.update: secret material not found: ${stored.id}`);
       }
       return {
         },
       );
       if (Option.isNone(updated)) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("local/secret-material-providers", `keychain.update: secret material not found: ${loaded.material.id}`);
-          new Error(`keychain.update: secret material not found: ${loaded.material.id}`),
-        );
       }
       return {
     return Effect.succeed(provider);
   }
-  return Effect.fail(new Error(`Unsupported secret provider: ${input.providerId}`));
+  return Effect.fail(runtimeEffectError("local/secret-material-providers", `Unsupported secret provider: ${input.providerId}`));
 };
 const createSecretMaterialProviderRuntime = (input: {
 }): Effect.Effect<string, Error, never> => {
   const providerAlias = fromConfigSecretProviderId(input.ref.providerId);
   if (providerAlias === null) {
-    return Effect.fail(new Error(`Unsupported secret provider: ${input.ref.providerId}`));
+    return Effect.fail(runtimeEffectError("local/secret-material-providers", `Unsupported secret provider: ${input.ref.providerId}`));
   }
   const provider = input.runtime.localConfig?.secrets?.providers?.[providerAlias];
   if (!provider) {
     return Effect.fail(
-      new Error(`Config secret provider "${providerAlias}" is not configured`),
+      runtimeEffectError("local/secret-material-providers", `Config secret provider "${providerAlias}" is not configured`),
     );
   }
   if (input.runtime.workspaceRoot === null) {
     return Effect.fail(
-      new Error(`Config secret provider "${providerAlias}" requires a workspace root`),
+      runtimeEffectError("local/secret-material-providers", `Config secret provider "${providerAlias}" requires a workspace root`),
     );
   }
   if (provider.source === "env") {
     const value = ensureNonEmptyString(input.runtime.env[input.ref.handle]);
     return value === null
-      ? Effect.fail(new Error(`Environment variable ${input.ref.handle} is not set`))
+      ? Effect.fail(runtimeEffectError("local/secret-material-providers", `Environment variable ${input.ref.handle} is not set`))
       : Effect.succeed(value);
   }
   const command = provider.command.trim();
   if (!isAbsolute(command)) {
     return Effect.fail(
-      new Error(`Exec secret provider command must be absolute: ${command}`),
+      runtimeEffectError("local/secret-material-providers", `Exec secret provider command must be absolute: ${command}`),
     );
   }
   if (!isRegularFilePath(command, provider.allowSymlinkCommand ?? false)) {
     return Effect.fail(
-      new Error(`Exec secret provider command is not an allowed regular file: ${command}`),
+      runtimeEffectError("local/secret-material-providers", `Exec secret provider command is not an allowed regular file: ${command}`),
     );
   }
   if (!ensureTrustedDir(command, provider.trustedDirs)) {
     return Effect.fail(
-      new Error(`Exec secret provider command is outside trustedDirs: ${command}`),
+      runtimeEffectError("local/secret-material-providers", `Exec secret provider command is outside trustedDirs: ${command}`),
     );
   }
         Effect.catchAll(() =>
           fromConfigSecretProviderId(ref.providerId) !== null
             ? Effect.succeed(null)
-            : Effect.fail(new Error(`Unsupported secret provider: ${ref.providerId}`)),
+            : Effect.fail(runtimeEffectError("local/secret-material-providers", `Unsupported secret provider: ${ref.providerId}`)),
         ),
       );
       });
       if (!provider.store) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("local/secret-material-providers", `Secret provider ${defaultStoreProviderId} does not support storing secret material`);
-          new Error(`Secret provider ${defaultStoreProviderId} does not support storing secret material`),
-        );
       }
       return yield* provider.store({
       });
       if (!provider.update) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("local/secret-material-providers", `Secret provider ${ref.providerId} does not support updating secret material`);
-          new Error(`Secret provider ${ref.providerId} does not support updating secret material`),
-        );
       }
       return yield* provider.update({

packages/platform/control-plane/src/runtime/local/tools.ts+9−17

       rawSegments.at(-1) === "index" ? rawSegments.slice(0, -1) : rawSegments;
     if (segments.length === 0) {
-      return yield* Effect.fail(
+      return yield* new LocalToolDefinitionError({
-        new LocalToolDefinitionError({
           message: `Invalid local tool path ${relativePath}: root index files are not supported`,
           path: relativePath,
           details:
             "Root index files are not supported. Use a named file such as hello.ts or a nested index.ts.",
-        }),
+        });
-      );
     }
     for (const segment of segments) {
       if (!LOCAL_TOOL_SEGMENT_PATTERN.test(segment)) {
-        return yield* Effect.fail(
+        return yield* new LocalToolDefinitionError({
-          new LocalToolDefinitionError({
             message: `Invalid local tool path ${relativePath}: segment ${segment} contains unsupported characters`,
             path: relativePath,
             details: `Tool path segments may only contain letters, numbers, underscores, and hyphens. Invalid segment: ${segment}`,
-          }),
+          });
-        );
       }
     }
       transpiled.diagnostics,
     );
     if (diagnosticError) {
-      return yield* Effect.fail(diagnosticError);
+      return yield* diagnosticError;
     }
     return rewriteRelativeImportSpecifiers(transpiled.outputText);
       const toolPath = yield* toToolPath(relativePath);
       const existing = seenToolPaths.get(toolPath);
       if (existing) {
-        return yield* Effect.fail(
+        return yield* new LocalToolPathConflictError({
-          new LocalToolPathConflictError({
             message: `Local tool path conflict for ${toolPath}`,
             path: sourcePath,
             otherPath: existing,
             toolPath,
-          }),
+          });
-        );
       }
       const artifactPath = artifactPaths.get(sourcePath);
       if (!artifactPath) {
-        return yield* Effect.fail(
+        return yield* new LocalToolImportError({
-          new LocalToolImportError({
             message: `Missing compiled artifact for local tool ${sourcePath}`,
             path: sourcePath,
             details:
               "Expected a compiled local tool artifact, but none was produced.",
-          }),
+          });
-        );
       }
       tools[toolPath] = yield* importLocalToolModule({

packages/platform/control-plane/src/runtime/policy/policies-operations.ts+4−8

     );
     const policy = localWorkspace.policies.find((candidate) => candidate.id === input.policyId) ?? null;
     if (policy === null) {
-      return yield* Effect.fail(
+      return yield* policyOps.get.notFound(
-        policyOps.get.notFound(
           "Policy not found",
           `workspaceId=${input.workspaceId} policyId=${input.policyId}`,
-        ),
+        );
-      );
     }
     return policy;
   });
     );
     const existing = localWorkspace.policies.find((candidate) => candidate.id === input.policyId) ?? null;
     if (existing === null) {
-      return yield* Effect.fail(
+      return yield* policyOps.update.notFound(
-        policyOps.update.notFound(
           "Policy not found",
           `workspaceId=${input.workspaceId} policyId=${input.policyId}`,
-        ),
+        );
-      );
     }
     const projectConfig = cloneJson(localWorkspace.loadedConfig.projectConfig ?? {});

packages/platform/control-plane/src/runtime/sources/executor-tools.ts+4−9

   makeLocalStorageLayer,
 } from "../local/storage";
 import { provideOptionalRuntimeLocalWorkspace } from "../local/runtime-context";
+import { runtimeEffectError } from "../effect-errors";
 /** Run an Effect as a Promise, preserving the original error (not FiberFailure). */
 const runEffect = async <A>(
 }) =>
   Effect.gen(function* () {
     if (!input.onElicitation) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/executor-tools", "executor.sources.add requires an elicitation-capable host");
-        new Error("executor.sources.add requires an elicitation-capable host"),
-      );
     }
     if (input.localServerBaseUrl === null) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/executor-tools", "executor.sources.add requires a local server base URL for credential capture");
-        new Error("executor.sources.add requires a local server base URL for credential capture"),
-      );
     }
     const response: ElicitationResponse = yield* input.onElicitation({
     }).pipe(Effect.mapError((cause) => cause instanceof Error ? cause : new Error(String(cause))));
     if (response.action !== "accept") {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/executor-tools", `Source credential setup was not completed for ${input.source.name}`);
-        new Error(`Source credential setup was not completed for ${input.source.name}`),
-      );
     }
     const content = yield* Effect.try({

packages/platform/control-plane/src/runtime/sources/source-adapters/google-discovery.test.ts+2−1

 import { googleDiscoverySourceAdapter } from "./google-discovery";
 import { snapshotFromSourceCatalogSyncResult } from "../catalog-sync-result";
 import { createSourceFromPayload } from "../source-definitions";
+import { runtimeEffectError } from "../../effect-errors";
 const fetchLiveDiscoveryDocument = async (): Promise<string> => {
   const response = await fetch("https://www.googleapis.com/discovery/v1/apis/sheets/v4/rest", {
           const syncResult = await Effect.runPromise(
             googleDiscoverySourceAdapter.syncCatalog({
               source,
-              resolveSecretMaterial: () => Effect.fail(new Error("unexpected secret lookup")),
+              resolveSecretMaterial: () => Effect.fail(runtimeEffectError("sources/source-adapters/google-discovery.test", "unexpected secret lookup")),
               resolveAuthMaterialForSlot: () =>
                 Effect.succeed({
                   placements: [],

packages/platform/control-plane/src/runtime/sources/source-adapters/graphql.test.ts+2−1

 import { createSourceFromPayload } from "../source-definitions";
 import { graphqlSourceAdapter } from "./graphql";
+import { runtimeEffectError } from "../../effect-errors";
 describe("graphql source adapter", () => {
   it("fails sync when introspection never responds", async () => {
         Effect.runPromise(
           graphqlSourceAdapter.syncCatalog({
             source,
-            resolveSecretMaterial: () => Effect.fail(new Error("unexpected secret lookup")),
+            resolveSecretMaterial: () => Effect.fail(runtimeEffectError("sources/source-adapters/graphql.test", "unexpected secret lookup")),
             resolveAuthMaterialForSlot: () =>
               Effect.succeed({
                 placements: [],

packages/platform/control-plane/src/runtime/sources/source-adapters/internal.ts+3−4

   type Source,
   type SourceAdapter,
 } from "@executor/source-core";
+import { runtimeEffectError } from "../../effect-errors";
 const InternalBindingConfigSchema = Schema.Struct({});
         "headers",
       ])
     ) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/source-adapters/internal", "internal sources cannot define HTTP source settings");
-        new Error("internal sources cannot define HTTP source settings"),
-      );
     }
     return yield* decodeSourceBindingPayload({
     ),
   invoke: () =>
     Effect.fail(
-      new Error("Internal sources do not support persisted adapter invocation"),
+      runtimeEffectError("sources/source-adapters/internal", "Internal sources do not support persisted adapter invocation"),
     ),
 };

packages/platform/control-plane/src/runtime/sources/source-adapters/mcp.test.ts+4−3

 import { snapshotFromSourceCatalogSyncResult } from "../catalog-sync-result";
 import { createSourceFromPayload } from "../source-definitions";
 import { mcpSourceAdapter } from "./mcp";
+import { runtimeEffectError } from "../../effect-errors";
 type RealMcpServer = {
   endpoint: string;
       const syncResult = yield* mcpSourceAdapter.syncCatalog({
         source,
         resolveSecretMaterial: () =>
-          Effect.fail(new Error("unexpected secret lookup")),
+          Effect.fail(runtimeEffectError("sources/source-adapters/mcp.test", "unexpected secret lookup")),
         resolveAuthMaterialForSlot: () =>
           Effect.succeed({
             placements: [],
       const syncResult = yield* mcpSourceAdapter.syncCatalog({
         source,
         resolveSecretMaterial: () =>
-          Effect.fail(new Error("unexpected secret lookup")),
+          Effect.fail(runtimeEffectError("sources/source-adapters/mcp.test", "unexpected secret lookup")),
         resolveAuthMaterialForSlot: () =>
           Effect.succeed({
             placements: [],
       const syncResult = yield* mcpSourceAdapter.syncCatalog({
         source,
         resolveSecretMaterial: () =>
-          Effect.fail(new Error("unexpected secret lookup")),
+          Effect.fail(runtimeEffectError("sources/source-adapters/mcp.test", "unexpected secret lookup")),
         resolveAuthMaterialForSlot: () => Effect.succeed(resolvedAuth),
       });
       const snapshot = snapshotFromSourceCatalogSyncResult(syncResult);

packages/platform/control-plane/src/runtime/sources/source-auth-service.ts+46−91

 } from "./source-store";
 import type { WorkspaceStorageServices } from "../local/storage";
 import { ControlPlaneStore, type ControlPlaneStoreShape } from "../store";
+import { runtimeEffectError } from "../effect-errors";
 const trimOrNull = (value: string | null | undefined): string | null => {
   if (value === null || value === undefined) {
 ) =>
   Effect.gen(function* () {
     if (!sourceAdapterRequiresInteractiveConnect(source.kind)) {
-      return yield* Effect.fail(new Error(`Expected MCP source, received ${source.kind}`));
+      return yield* runtimeEffectError("sources/source-auth-service", `Expected MCP source, received ${source.kind}`);
     }
     const bindingState = yield* sourceBindingStateFromSource(source);
         storeSecretMaterial: input.storeSecretMaterial,
       });
       if (tokenRef === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", "Bearer auth requires token or tokenRef");
-          new Error("Bearer auth requires token or tokenRef"),
-        );
       }
       return {
       storeSecretMaterial: input.storeSecretMaterial,
     });
     if (accessTokenRef === null) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/source-auth-service", "OAuth2 auth requires accessToken or accessTokenRef");
-        new Error("OAuth2 auth requires accessToken or accessTokenRef"),
-      );
     }
     const refreshTokenRef = yield* materializeSecretRefInput({
         })
       : null;
     if (setupConfig === null) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/source-auth-service", `Source ${input.source.id} does not support OAuth client configuration`);
-        new Error(`Source ${input.source.id} does not support OAuth client configuration`),
-      );
     }
     const existing = yield* input.rows.sourceOauthClients.getByWorkspaceSourceAndProvider({
       existing.value.workspaceId !== input.workspaceId
       || existing.value.providerKey !== input.providerKey
     ) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/source-auth-service", `Workspace OAuth client ${input.oauthClientId} is not valid for ${input.providerKey}`);
-        new Error(`Workspace OAuth client ${input.oauthClientId} is not valid for ${input.providerKey}`),
-      );
     }
     return {
     }
     if (refreshTokenRef === null) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/source-auth-service", `Provider auth grant for ${input.providerKey} is missing a refresh token`);
-        new Error(`Provider auth grant for ${input.providerKey} is missing a refresh token`),
-      );
     }
     const now = Date.now();
 }, Error, WorkspaceStorageServices> =>
   Effect.gen(function* () {
     if (input.targetSources.length === 0) {
-      return yield* Effect.fail(new Error("Provider OAuth setup requires at least one target source"));
+      return yield* runtimeEffectError("sources/source-auth-service", "Provider OAuth setup requires at least one target source");
     }
     const sessionId = SourceAuthSessionIdSchema.make(`src_auth_${crypto.randomUUID()}`);
             Effect.flatMap((source) =>
               sourceAdapterRequiresInteractiveConnect(source.kind)
                 ? Effect.succeed(source)
-                : Effect.fail(new Error(`Expected MCP source, received ${source.kind}`)),
+                : Effect.fail(runtimeEffectError("sources/source-auth-service", `Expected MCP source, received ${source.kind}`)),
             ),
           )
         : input.sourceStore.loadSourcesInWorkspace(input.workspaceId, {
     const localServerBaseUrl = trimOrNull(input.baseUrl) ?? input.getLocalServerBaseUrl?.() ?? null;
     if (!localServerBaseUrl) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/source-auth-service", "Local executor server base URL is unavailable for source credential setup");
-        new Error("Local executor server base URL is unavailable for source credential setup"),
-      );
     }
     const sessionId = SourceAuthSessionIdSchema.make(`src_auth_${crypto.randomUUID()}`);
       }
       if (workspaceOauthClient === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", "Google shared auth requires a workspace OAuth client");
-          new Error("Google shared auth requires a workspace OAuth client"),
-        );
       }
       const requiredScopes = normalizeScopes(googleSetupConfig.scopes);
       const requestBaseUrl = trimOrNull(input.baseUrl);
       const baseUrl = requestBaseUrl ?? input.getLocalServerBaseUrl?.() ?? null;
       if (baseUrl === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", "Local executor server base URL is unavailable for Google OAuth setup");
-          new Error("Local executor server base URL is unavailable for Google OAuth setup"),
-        );
       }
       const oauthRequired = yield* startProviderOauthBatchCredentialSetup({
 }): Effect.Effect<ConnectGoogleDiscoveryBatchResult, Error, WorkspaceStorageServices> =>
   Effect.gen(function* () {
     if (input.sourceInput.sources.length === 0) {
-      return yield* Effect.fail(new Error("Google batch connect requires at least one source"));
+      return yield* runtimeEffectError("sources/source-auth-service", "Google batch connect requires at least one source");
     }
     const existingSources = yield* input.sourceStore.loadSourcesInWorkspace(
               })
             : null;
           if (setupConfig === null) {
-            return yield* Effect.fail(
+            return yield* runtimeEffectError("sources/source-auth-service", `Source ${persistedDraft.id} does not support Google shared auth`);
-              new Error(`Source ${persistedDraft.id} does not support Google shared auth`),
-            );
           }
           return {
       providerKey: baseSetupConfig.providerKey,
     });
     if (workspaceOauthClient === null) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/source-auth-service", `Workspace OAuth client not found: ${input.sourceInput.workspaceOauthClientId}`);
-        new Error(`Workspace OAuth client not found: ${input.sourceInput.workspaceOauthClientId}`),
-      );
     }
     const reusableGrant = yield* findReusableProviderGrant({
     const baseUrl = trimOrNull(input.sourceInput.baseUrl) ?? input.getLocalServerBaseUrl?.() ?? null;
     if (baseUrl === null) {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/source-auth-service", "Local executor server base URL is unavailable for Google OAuth setup");
-        new Error("Local executor server base URL is unavailable for Google OAuth setup"),
-      );
     }
     const oauthRequired = yield* startProviderOauthBatchCredentialSetup({
               baseUrl: options?.baseUrl,
               resolveSecretMaterial: input.resolveSecretMaterial,
             })
-          : Effect.fail(new Error(`Unsupported executor source input: ${JSON.stringify(sourceInput)}`))).pipe(
+          : Effect.fail(runtimeEffectError("sources/source-auth-service", `Unsupported executor source input: ${JSON.stringify(sourceInput)}`))).pipe(
               Effect.flatMap(mirrorLocalSourceResult),
             ),
       ),
           });
           const stored = yield* input.rows.workspaceOauthClients.getById(created.id);
           if (Option.isNone(stored)) {
-            return yield* Effect.fail(
+            return yield* runtimeEffectError("sources/source-auth-service", `Workspace OAuth client ${created.id} was not persisted`);
-              new Error(`Workspace OAuth client ${created.id} was not persisted`),
-            );
           }
           return stored.value;
           const grants = yield* input.rows.providerAuthGrants.listByWorkspaceId(workspaceId);
           const dependentGrant = grants.find((grant) => grant.oauthClientId === oauthClientId);
           if (dependentGrant) {
-            return yield* Effect.fail(
+            return yield* runtimeEffectError("sources/source-auth-service",
-              new Error(
                 `Workspace OAuth client ${oauthClientId} is still referenced by provider grant ${dependentGrant.id}`,
-              ),
+              );
-            );
           }
           const secretRef = sourceOauthClientSecretRef(oauthClient.value);
     Effect.gen(function* () {
       const resolvedBaseUrl = trimOrNull(oauthInput.baseUrl) ?? input.getLocalServerBaseUrl?.() ?? null;
       if (!resolvedBaseUrl) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", "Local executor server base URL is unavailable for OAuth setup");
-          new Error("Local executor server base URL is unavailable for OAuth setup"),
-        );
       }
       const sessionId = SourceAuthSessionIdSchema.make(`src_auth_${crypto.randomUUID()}`);
     provideLocalWorkspace(Effect.gen(function* () {
       const sessionOption = yield* input.rows.sourceAuthSessions.getByState(state);
       if (Option.isNone(sessionOption)) {
-        return yield* Effect.fail(new Error(`Source auth session not found for state ${state}`));
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session not found for state ${state}`);
       }
       const session = sessionOption.value;
       const sessionData = decodeMcpSourceAuthSessionData(session);
       if (session.status === "completed") {
-        return yield* Effect.fail(new Error(`Source auth session ${session.id} is already completed`));
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session ${session.id} is already completed`);
       }
       if (session.status !== "pending") {
-        return yield* Effect.fail(new Error(`Source auth session ${session.id} is not pending`));
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session ${session.id} is not pending`);
       }
       if (trimOrNull(error) !== null) {
           }),
         );
-        return yield* Effect.fail(new Error(reason));
+        return yield* runtimeEffectError("sources/source-auth-service", reason);
       }
       const authorizationCode = trimOrNull(code);
       if (authorizationCode === null) {
-        return yield* Effect.fail(new Error("Missing OAuth authorization code"));
+        return yield* runtimeEffectError("sources/source-auth-service", "Missing OAuth authorization code");
       }
       if (sessionData.codeVerifier === null) {
-        return yield* Effect.fail(new Error("OAuth session is missing the PKCE code verifier"));
+        return yield* runtimeEffectError("sources/source-auth-service", "OAuth session is missing the PKCE code verifier");
       }
       if (sessionData.scope !== null && sessionData.scope !== "mcp") {
-        return yield* Effect.fail(new Error(`Unsupported OAuth provider: ${sessionData.scope}`));
+        return yield* runtimeEffectError("sources/source-auth-service", `Unsupported OAuth provider: ${sessionData.scope}`);
       }
       const exchanged = yield* exchangeMcpOAuthAuthorizationCode({
     provideLocalWorkspace(Effect.gen(function* () {
       const sessionOption = yield* input.rows.sourceAuthSessions.getByState(state);
       if (Option.isNone(sessionOption)) {
-        return yield* Effect.fail(new Error(`Source auth session not found for state ${state}`));
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session not found for state ${state}`);
       }
       const session = sessionOption.value;
       if (session.workspaceId !== workspaceId) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session ${session.id} does not match workspaceId=${workspaceId}`);
-          new Error(`Source auth session ${session.id} does not match workspaceId=${workspaceId}`),
-        );
       }
       if ((session.actorAccountId ?? null) !== (actorAccountId ?? null)) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session ${session.id} does not match the active account`);
-          new Error(`Source auth session ${session.id} does not match the active account`),
-        );
       }
       if (session.providerKind !== "oauth2_provider_batch") {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session ${session.id} is not a provider batch OAuth session`);
-          new Error(`Source auth session ${session.id} is not a provider batch OAuth session`),
-        );
       }
       if (session.status === "completed") {
         const sessionData = decodeProviderOauthBatchSourceAuthSessionData(session);
         } satisfies CompleteProviderOauthCallbackResult;
       }
       if (session.status !== "pending") {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session ${session.id} is not pending`);
-          new Error(`Source auth session ${session.id} is not pending`),
-        );
       }
       const sessionData = decodeProviderOauthBatchSourceAuthSessionData(session);
             errorText: reason,
           }),
         );
-        return yield* Effect.fail(new Error(reason));
+        return yield* runtimeEffectError("sources/source-auth-service", reason);
       }
       const authorizationCode = trimOrNull(code);
       if (authorizationCode === null) {
-        return yield* Effect.fail(new Error("Missing OAuth authorization code"));
+        return yield* runtimeEffectError("sources/source-auth-service", "Missing OAuth authorization code");
       }
       if (sessionData.codeVerifier === null) {
-        return yield* Effect.fail(new Error("OAuth session is missing the PKCE code verifier"));
+        return yield* runtimeEffectError("sources/source-auth-service", "OAuth session is missing the PKCE code verifier");
       }
       const oauthClient = yield* resolveWorkspaceOauthClientById({
         providerKey: sessionData.providerKey,
       });
       if (oauthClient === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", `Workspace OAuth client not found: ${sessionData.oauthClientId}`);
-          new Error(`Workspace OAuth client not found: ${sessionData.oauthClientId}`),
-        );
       }
       let clientSecret: string | null = null;
     provideLocalWorkspace(Effect.gen(function* () {
       const sessionOption = yield* input.rows.sourceAuthSessions.getByState(state);
       if (Option.isNone(sessionOption)) {
-        return yield* Effect.fail(new Error(`Source auth session not found for state ${state}`));
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session not found for state ${state}`);
       }
       const session = sessionOption.value;
       if (session.workspaceId !== workspaceId || session.sourceId !== sourceId) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service",
-          new Error(
             `Source auth session ${session.id} does not match workspaceId=${workspaceId} sourceId=${sourceId}`,
-          ),
+          );
-        );
       }
       if (
         actorAccountId !== undefined
         && (session.actorAccountId ?? null) !== (actorAccountId ?? null)
       ) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session ${session.id} does not match the active account`);
-          new Error(`Source auth session ${session.id} does not match the active account`),
-        );
       }
       const source = yield* input.sourceStore.loadSourceById({
       }
       if (session.status !== "pending") {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-auth-service", `Source auth session ${session.id} is not pending`);
-          new Error(`Source auth session ${session.id} is not pending`),
-        );
       }
       const sessionData = session.providerKind === "oauth2_pkce"
           },
         });
-        return yield* Effect.fail(new Error(reason));
+        return yield* runtimeEffectError("sources/source-auth-service", reason);
       }
       const authorizationCode = trimOrNull(code);
       if (authorizationCode === null) {
-        return yield* Effect.fail(new Error("Missing OAuth authorization code"));
+        return yield* runtimeEffectError("sources/source-auth-service", "Missing OAuth authorization code");
       }
       if (sessionData.codeVerifier === null) {
-        return yield* Effect.fail(new Error("OAuth session is missing the PKCE code verifier"));
+        return yield* runtimeEffectError("sources/source-auth-service", "OAuth session is missing the PKCE code verifier");
       }
       const now = Date.now();
         });
         const refreshToken = trimOrNull(exchanged.refresh_token);
         if (refreshToken === null) {
-          return yield* Effect.fail(
+          return yield* runtimeEffectError("sources/source-auth-service", "OAuth authorization did not return a refresh token");
-            new Error("OAuth authorization did not return a refresh token"),
-          );
         }
         const refreshTokenRef = yield* input.storeSecretMaterial({

packages/platform/control-plane/src/runtime/sources/source-definitions.ts+11−26

   authArtifactFromSourceAuth,
   sourceAuthFromAuthArtifact,
 } from "../auth/auth-artifacts";
+import { runtimeEffectError } from "../effect-errors";
 const trimOrNull = (value: string | null | undefined): string | null => {
   if (value === null || value === undefined) {
       const providerId = trimOrNull(auth.token.providerId);
       const handle = trimOrNull(auth.token.handle);
       if (providerId === null || handle === null) {
-        return yield* Effect.fail(new Error("Bearer auth requires a token secret ref"));
+        return yield* runtimeEffectError("sources/source-definitions", "Bearer auth requires a token secret ref");
       }
       return {
       const refreshProviderId = trimOrNull(auth.refreshToken.providerId);
       const refreshHandle = trimOrNull(auth.refreshToken.handle);
       if (refreshProviderId === null || refreshHandle === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-definitions", "OAuth2 authorized-user auth requires a refresh token secret ref");
-          new Error("OAuth2 authorized-user auth requires a refresh token secret ref"),
-        );
       }
       let clientSecret: { providerId: string; handle: string } | null = null;
         const clientSecretProviderId = trimOrNull(auth.clientSecret.providerId);
         const clientSecretHandle = trimOrNull(auth.clientSecret.handle);
         if (clientSecretProviderId === null || clientSecretHandle === null) {
-          return yield* Effect.fail(
+          return yield* runtimeEffectError("sources/source-definitions", "OAuth2 authorized-user client secret ref must include providerId and handle");
-            new Error("OAuth2 authorized-user client secret ref must include providerId and handle"),
-          );
         }
         clientSecret = {
           providerId: clientSecretProviderId,
       const tokenEndpoint = trimOrNull(auth.tokenEndpoint);
       const clientId = trimOrNull(auth.clientId);
       if (tokenEndpoint === null || clientId === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-definitions", "OAuth2 authorized-user auth requires tokenEndpoint and clientId");
-          new Error("OAuth2 authorized-user auth requires tokenEndpoint and clientId"),
-        );
       }
       return {
       const prefix = auth.prefix ?? "Bearer ";
       const grantId = trimOrNull(auth.grantId);
       if (grantId === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-definitions", "Provider grant auth requires a grantId");
-          new Error("Provider grant auth requires a grantId"),
-        );
       }
       return {
       const accessProviderId = trimOrNull(auth.accessToken.providerId);
       const accessHandle = trimOrNull(auth.accessToken.handle);
       if (redirectUri === null || accessProviderId === null || accessHandle === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-definitions", "MCP OAuth auth requires redirectUri and access token secret ref");
-          new Error("MCP OAuth auth requires redirectUri and access token secret ref"),
-        );
       }
       let refreshToken: { providerId: string; handle: string } | null = null;
         const refreshProviderId = trimOrNull(auth.refreshToken.providerId);
         const refreshHandle = trimOrNull(auth.refreshToken.handle);
         if (refreshProviderId === null || refreshHandle === null) {
-          return yield* Effect.fail(
+          return yield* runtimeEffectError("sources/source-definitions", "MCP OAuth refresh token ref must include providerId and handle");
-            new Error("MCP OAuth refresh token ref must include providerId and handle"),
-          );
         }
         refreshToken = {
     const accessProviderId = trimOrNull(auth.accessToken.providerId);
     const accessHandle = trimOrNull(auth.accessToken.handle);
     if (accessProviderId === null || accessHandle === null) {
-      return yield* Effect.fail(new Error("OAuth2 auth requires an access token secret ref"));
+      return yield* runtimeEffectError("sources/source-definitions", "OAuth2 auth requires an access token secret ref");
     }
     let refreshToken: { providerId: string; handle: string } | null = null;
       const refreshProviderId = trimOrNull(auth.refreshToken.providerId);
       const refreshHandle = trimOrNull(auth.refreshToken.handle);
       if (refreshProviderId === null || refreshHandle === null) {
-        return yield* Effect.fail(
+        return yield* runtimeEffectError("sources/source-definitions", "OAuth2 refresh token ref must include providerId and handle");
-          new Error("OAuth2 refresh token ref must include providerId and handle"),
-        );
       }
       refreshToken = {
 const validateSourceImportAuth = (source: Source): Effect.Effect<Source, Error, never> =>
   Effect.gen(function* () {
     if (source.importAuthPolicy !== "separate" && source.importAuth.kind !== "none") {
-      return yield* Effect.fail(
+      return yield* runtimeEffectError("sources/source-definitions", "importAuth must be none unless importAuthPolicy is separate");
-        new Error("importAuth must be none unless importAuthPolicy is separate"),
-      );
     }
     return source;

packages/platform/control-plane/src/runtime/sources/source-inspection.ts+3−5

     });
     if (!canInspectSourceWithoutCatalog(source)) {
-      return yield* Effect.fail(input.cause);
+      return yield* input.cause;
     }
     return source;
     const tool = inspection.tool;
     if (!tool) {
-      return yield* Effect.fail(
+      return yield* sourceInspectOps.tool.notFound(
-        sourceInspectOps.tool.notFound(
           "Tool not found",
           `workspaceId=${input.workspaceId} sourceId=${input.sourceId} path=${input.toolPath}`,
-        ),
+        );
-      );
     }
     return inspectionToolDetailFromTool(tool);

packages/platform/control-plane/src/runtime/sources/source-store/deps.ts+2−4

 > =>
   Effect.gen(function* () {
     if (deps.runtimeLocalWorkspace.installation.workspaceId !== workspaceId) {
-      return yield* Effect.fail(
+      return yield* new RuntimeLocalWorkspaceMismatchError({
-        new RuntimeLocalWorkspaceMismatchError({
           message: `Runtime local workspace mismatch: expected ${workspaceId}, got ${deps.runtimeLocalWorkspace.installation.workspaceId}`,
           requestedWorkspaceId: workspaceId,
           activeWorkspaceId: deps.runtimeLocalWorkspace.installation.workspaceId,
-        }),
+        });
-      );
     }
     const loadedConfig = yield* deps.workspaceConfigStore.load(

packages/platform/control-plane/src/runtime/sources/source-store/records.ts+4−8

   Effect.gen(function* () {
     const sourceConfig = input.loadedConfig.config?.sources?.[input.sourceId];
     if (!sourceConfig) {
-      return yield* Effect.fail(
+      return yield* new LocalConfiguredSourceNotFoundError({
-        new LocalConfiguredSourceNotFoundError({
           message: `Configured source not found for id ${input.sourceId}`,
           sourceId: input.sourceId,
-        }),
+        });
-      );
     }
     const existingState = input.workspaceState.sources[input.sourceId];
       input.workspaceId,
     );
     if (!localWorkspace.loadedConfig.config?.sources?.[input.sourceId]) {
-      return yield* Effect.fail(
+      return yield* new LocalConfiguredSourceNotFoundError({
-        new LocalConfiguredSourceNotFoundError({
           message: `Source not found: workspaceId=${input.workspaceId} sourceId=${input.sourceId}`,
           sourceId: input.sourceId,
-        }),
+        });
-      );
     }
     const localSource = yield* buildLocalSourceRecord({

packages/platform/control-plane/src/runtime/sources/sources-operations.ts+1−3

             );
           }
-          return yield* Effect.fail(
+          return yield* input.operation.unknownStorage(error, "Failed syncing source tools");
-            input.operation.unknownStorage(error, "Failed syncing source tools"),
-          );
         }),
     });
   });

packages/platform/server/src/effect-errors.ts+13−0

@@ -0,0 +1,13 @@
	1	import * as Data from "effect/Data";
	2
	3	export class PlatformServerEffectError extends Data.TaggedError(
	4	"PlatformServerEffectError",
	5	)<{
	6	readonly module: string;
	7	readonly message: string;
	8	}> {}
	9
	10	export const platformServerEffectError = (
	11	module: string,
	12	message: string,
	13	) => new PlatformServerEffectError({ module, message });

packages/platform/server/src/index.ts+2−1

   createLocalTracingRuntimeFromEnv,
   tracingSearchUrl,
 } from "./tracing";
+import { platformServerEffectError } from "./effect-errors";
 export {
   DEFAULT_EXECUTOR_DATA_DIR,
     const address = server.address();
     if (!address || typeof address === "string") {
-      return yield* Effect.fail(new Error("Failed to resolve local executor server address"));
+      return yield* platformServerEffectError("index", "Failed to resolve local executor server address");
     }
     const resolvedAddress = address as AddressInfo;

packages/sources/core/src/effect-errors.ts+13−0

@@ -0,0 +1,13 @@
	1	import * as Data from "effect/Data";
	2
	3	export class SourceCoreEffectError extends Data.TaggedError(
	4	"SourceCoreEffectError",
	5	)<{
	6	readonly module: string;
	7	readonly message: string;
	8	}> {}
	9
	10	export const sourceCoreEffectError = (
	11	module: string,
	12	message: string,
	13	) => new SourceCoreEffectError({ module, message });

packages/sources/core/src/index.ts+1−0

@@ -2,6 +2,7 @@ export * from "./catalog"; · 1 unmodified line
2	export * from "./catalog-sync-result";	2	export * from "./catalog-sync-result";
3	export * from "./discovery";	3	export * from "./discovery";
4	export * from "./discovery-models";	4	export * from "./discovery-models";
		5	export * from "./effect-errors";
5	export * from "./registry";	6	export * from "./registry";
6	export * from "./shared";	7	export * from "./shared";
7	export * from "./source-models";	8	export * from "./source-models";

packages/sources/core/src/shared.ts+13−8

@@ -1,6 +1,8 @@
		1	import * as Data from "effect/Data";
1	import * as Effect from "effect/Effect";	2	import * as Effect from "effect/Effect";
2	import * as Schema from "effect/Schema";	3	import * as Schema from "effect/Schema";
3		4
		5	import { sourceCoreEffectError } from "./effect-errors";
4	import {	6	import {
5	SecretRefSchema,	7	SecretRefSchema,
6	SourceBindingVersionSchema,	8	SourceBindingVersionSchema,
@@ -86,14 +88,17 @@ export const parseJsonValue = <T>(input: { · 79 unmodified lines
86	: new Error(`Invalid ${input.label}: ${String(cause)}`),	88	: new Error(`Invalid ${input.label}: ${String(cause)}`),
87	});	89	});
88		90
89	export class SourceCredentialRequiredError extends Error {	91	export class SourceCredentialRequiredError extends Data.TaggedError(
90	readonly _tag = "SourceCredentialRequiredError";	92	"SourceCredentialRequiredError",
91		93	)<{
		94	readonly slot: CredentialSlot;
		95	readonly message: string;
		96	}> {
92	constructor(	97	constructor(
93	readonly slot: CredentialSlot,	98	slot: CredentialSlot,
94	message: string,	99	message: string,
95	) {	100	) {
96	super(message);	101	super({ slot, message });
97	}	102	}
98	}	103	}
99		104
@@ -150,7 +155,7 @@ export const decodeBindingConfig = <A>(input: { · 50 unmodified lines
150	}): Effect.Effect<SourceBinding & { payload: A }, Error, never> => {	155	}): Effect.Effect<SourceBinding & { payload: A }, Error, never> => {
151	if (input.value === null) {	156	if (input.value === null) {
152	return Effect.fail(	157	return Effect.fail(
153	new Error(`Missing ${input.label} binding config for ${input.sourceId}`),	158	sourceCoreEffectError("core/shared", `Missing ${input.label} binding config for ${input.sourceId}`),
154	);	159	);
155	}	160	}
156		161
@@ -173,7 +178,7 @@ export const decodeBindingConfig = <A>(input: { · 16 unmodified lines
173	payload: decoded.payload,	178	payload: decoded.payload,
174	} as SourceBinding & { payload: A })	179	} as SourceBinding & { payload: A })
175	: Effect.fail(	180	: Effect.fail(
176	new Error(	181	sourceCoreEffectError("core/shared",
177	`Unsupported ${input.label} binding config version ${decoded.version} for ${input.sourceId}; expected ${input.version}`,	182	`Unsupported ${input.label} binding config version ${decoded.version} for ${input.sourceId}; expected ${input.version}`,
178	),	183	),
179	),	184	),
@@ -192,7 +197,7 @@ export const decodeSourceBindingPayload = <A>(input: { · 12 unmodified lines
192	}): Effect.Effect<A, Error, never> =>	197	}): Effect.Effect<A, Error, never> =>
193	input.version !== input.expectedVersion	198	input.version !== input.expectedVersion
194	? Effect.fail(	199	? Effect.fail(
195	new Error(	200	sourceCoreEffectError("core/shared",
196	`Unsupported ${input.label} binding version ${input.version} for ${input.sourceId}; expected ${input.expectedVersion}`,	201	`Unsupported ${input.label} binding version ${input.version} for ${input.sourceId}; expected ${input.expectedVersion}`,
197	),	202	),
198	)	203	)

packages/sources/google-discovery/src/adapter.ts+8−15

   WorkspaceOauthClientIdSchema,
   createCatalogImportMetadata,
   EXECUTABLE_BINDING_VERSION,
+  sourceCoreEffectError,
   type Source,
   type SourceAdapter,
 } from "@executor/source-core";
         "specUrl",
       ])
     ) {
-      return yield* Effect.fail(
+      return yield* sourceCoreEffectError("google-discovery/adapter",
-        new Error(
           "Google Discovery sources cannot define MCP or OpenAPI binding fields",
-        ),
+        );
-      );
     }
     const bindingConfig = yield* decodeSourceBindingPayload({
     const service = bindingConfig.service.trim();
     const version = bindingConfig.version.trim();
     if (service.length === 0 || version.length === 0) {
-      return yield* Effect.fail(
+      return yield* sourceCoreEffectError("google-discovery/adapter", "Google Discovery sources require service and version");
-        new Error("Google Discovery sources require service and version"),
-      );
     }
     const explicitDiscoveryUrl =
       );
     if (response.status === 401 || response.status === 403) {
-      return yield* Effect.fail(
+      return yield* new SourceCredentialRequiredError(
-        new SourceCredentialRequiredError(
           "import",
           `Google Discovery fetch requires credentials (status ${response.status})`,
-        ),
+        );
-      );
     }
     if (response.status < 200 || response.status >= 300) {
-      return yield* Effect.fail(
+      return yield* sourceCoreEffectError("google-discovery/adapter",
-        new Error(
           `Google Discovery fetch failed with status ${response.status}`,
-        ),
+        );
-      );
     }
     return yield* response.text.pipe(

packages/sources/google-discovery/src/tools.ts+3−4

   type HttpRequestPlacements,
   type ToolMetadata,
 } from "@executor/codemode-core";
+import { sourceCoreEffectError } from "@executor/source-core";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
             const body = yield* decodeResponseBody(response);
             if (response.status < 200 || response.status >= 300) {
-              return yield* Effect.fail(
+              return yield* sourceCoreEffectError("google-discovery/tools",
-                new Error(
                   `Google Discovery request failed with HTTP ${response.status}: ${typeof body === "string" ? body : JSON.stringify(body)}`,
-                ),
+                );
-              );
             }
             return body;

packages/sources/graphql/src/adapter.ts+3−6

   StringMapSchema,
   createCatalogImportMetadata,
   EXECUTABLE_BINDING_VERSION,
+  sourceCoreEffectError,
   type Source,
   type SourceAdapter,
 } from "@executor/source-core";
         "headers",
       ])
     ) {
-      return yield* Effect.fail(
+      return yield* sourceCoreEffectError("graphql/adapter", "GraphQL sources cannot define MCP transport settings");
-        new Error("GraphQL sources cannot define MCP transport settings"),
-      );
     }
     if (bindingHasAnyField(source.binding, ["specUrl"])) {
-      return yield* Effect.fail(
+      return yield* sourceCoreEffectError("graphql/adapter", "GraphQL sources cannot define specUrl");
-        new Error("GraphQL sources cannot define specUrl"),
-      );
     }
     const bindingConfig = yield* decodeSourceBindingPayload({

packages/sources/graphql/src/graphql-tools.ts+2−3

   type ToolPath,
   typeSignatureFromSchema,
 } from "@executor/codemode-core";
+import { sourceCoreEffectError } from "@executor/source-core";
 import {
   GraphqlToolProviderDataSchema,
   type GraphqlToolProviderData,
     const record = asRecord(input.args);
     const query = asString(record.query);
     if (query === null) {
-      return yield* Effect.fail(
+      return yield* sourceCoreEffectError("graphql/graphql-tools", `GraphQL query must be a non-empty string for ${input.path}`);
-        new Error(`GraphQL query must be a non-empty string for ${input.path}`),
-      );
     }
     return yield* invokeGraphqlHttpRequest({

packages/sources/mcp/src/adapter.ts+3−4

   StringMapSchema,
   createCatalogImportMetadata,
   EXECUTABLE_BINDING_VERSION,
+  sourceCoreEffectError,
   type Source,
   type SourceAdapter,
   type SourceCatalogSyncResult,
 ): Effect.Effect<McpBindingConfig, Error, never> =>
   Effect.gen(function* () {
     if (bindingHasAnyField(source.binding, ["specUrl"])) {
-      return yield* Effect.fail(new Error("MCP sources cannot define specUrl"));
+      return yield* sourceCoreEffectError("mcp/adapter", "MCP sources cannot define specUrl");
     }
     if (bindingHasAnyField(source.binding, ["defaultHeaders"])) {
-      return yield* Effect.fail(
+      return yield* sourceCoreEffectError("mcp/adapter", "MCP sources cannot define HTTP source settings");
-        new Error("MCP sources cannot define HTTP source settings"),
-      );
     }
     const bindingConfig = yield* decodeSourceBindingPayload({

packages/sources/mcp/src/tools.ts+6−10

       }
       if (isExecutionSuspendedCause(attempt.left)) {
-        return yield* Effect.fail(attempt.left as McpToolsError);
+        return yield* (attempt.left as McpToolsError);
       }
       if (
         continue;
       }
-      return yield* Effect.fail(
+      return yield* new McpToolsError({
-        new McpToolsError({
           stage: "list_tools",
           message: "Failed listing MCP tools",
           details: toDetails(attempt.left),
-        }),
+        });
-      );
     }
   });
       }
       if (isExecutionSuspendedCause(attempt.left)) {
-        return yield* Effect.fail(attempt.left as McpToolsError);
+        return yield* (attempt.left as McpToolsError);
       }
       if (
         continue;
       }
-      return yield* Effect.fail(
+      return yield* new McpToolsError({
-        new McpToolsError({
           stage: "call_tool",
           message: `Failed invoking MCP tool: ${input.toolName}`,
           details: toDetails(attempt.left),
-        }),
+        });
-      );
     }
   });

packages/sources/openapi/src/adapter.ts+6−11

   StringMapSchema,
   createCatalogImportMetadata,
   EXECUTABLE_BINDING_VERSION,
+  sourceCoreEffectError,
   type Source,
   type SourceAdapter,
 } from "@executor/source-core";
         "headers",
       ])
     ) {
-      return yield* Effect.fail(
+      return yield* sourceCoreEffectError("openapi/adapter", "OpenAPI sources cannot define MCP transport settings");
-        new Error("OpenAPI sources cannot define MCP transport settings"),
-      );
     }
     const bindingConfig = yield* decodeSourceBindingPayload({
         ? bindingConfig.specUrl.trim()
         : "";
     if (specUrl.length === 0) {
-      return yield* Effect.fail(new Error("OpenAPI sources require specUrl"));
+      return yield* sourceCoreEffectError("openapi/adapter", "OpenAPI sources require specUrl");
     }
     return {
       );
     if (response.status === 401 || response.status === 403) {
-      return yield* Effect.fail(
+      return yield* new SourceCredentialRequiredError(
-        new SourceCredentialRequiredError(
           "import",
           `OpenAPI spec fetch requires credentials (status ${response.status})`,
-        ),
+        );
-      );
     }
     if (response.status < 200 || response.status >= 300) {
-      return yield* Effect.fail(
+      return yield* sourceCoreEffectError("openapi/adapter", `OpenAPI spec fetch failed with status ${response.status}`);
-        new Error(`OpenAPI spec fetch failed with status ${response.status}`),
-      );
     }
     return yield* response.text.pipe(

tools/oxlint/README.md+2−0

@@ -11,6 +11,8 @@ Why it lives here: · 10 unmodified lines
11	Current rules:	11	Current rules:
12		12
13	- `executor-monorepo/no-cross-workspace-relative-imports`	13	- `executor-monorepo/no-cross-workspace-relative-imports`
		14	- `executor-monorepo/no-raw-effect-fail-errors`
		15	- `executor-monorepo/no-yield-effect-fail`
14	- `executor-monorepo/no-workspace-src-imports`	16	- `executor-monorepo/no-workspace-src-imports`
15		17
16	To add another rule:	18	To add another rule:

tools/oxlint/plugin.mjs+4−0

 import { definePlugin } from "@oxlint/plugins";
 import noCrossWorkspaceRelativeImports from "./rules/no-cross-workspace-relative-imports.mjs";
+import noRawEffectFailErrors from "./rules/no-raw-effect-fail-errors.mjs";
+import noYieldEffectFail from "./rules/no-yield-effect-fail.mjs";
 import noWorkspaceSrcImports from "./rules/no-workspace-src-imports.mjs";
 export default definePlugin({
   },
   rules: {
     "no-cross-workspace-relative-imports": noCrossWorkspaceRelativeImports,
+    "no-raw-effect-fail-errors": noRawEffectFailErrors,
+    "no-yield-effect-fail": noYieldEffectFail,
     "no-workspace-src-imports": noWorkspaceSrcImports,
   },
 });

tools/oxlint/rules/no-raw-effect-fail-errors.mjs+109−0

@@ -0,0 +1,109 @@
	1	import { defineRule } from "@oxlint/plugins";
	2
	3	const BUILTIN_ERROR_NAMES = new Set([
	4	"AggregateError",
	5	"Error",
	6	"EvalError",
	7	"RangeError",
	8	"ReferenceError",
	9	"SyntaxError",
	10	"TypeError",
	11	"URIError",
	12	]);
	13
	14	const isIdentifierNamed = (node, name) =>
	15	node?.type === "Identifier" && node.name === name;
	16
	17	const isEffectFailCall = (node) =>
	18	node?.type === "CallExpression"
	19	&& node.callee?.type === "MemberExpression"
	20	&& node.callee.computed === false
	21	&& isIdentifierNamed(node.callee.object, "Effect")
	22	&& isIdentifierNamed(node.callee.property, "fail");
	23
	24	const readBuiltinErrorName = (node) => {
	25	if (
	26	node?.type === "NewExpression"
	27	&& node.callee?.type === "Identifier"
	28	&& BUILTIN_ERROR_NAMES.has(node.callee.name)
	29	) {
	30	return node.callee.name;
	31	}
	32
	33	if (
	34	node?.type === "CallExpression"
	35	&& node.callee?.type === "Identifier"
	36	&& BUILTIN_ERROR_NAMES.has(node.callee.name)
	37	) {
	38	return node.callee.name;
	39	}
	40
	41	return null;
	42	};
	43
	44	const readBuiltinFailedErrorName = (node) => {
	45	if (!isEffectFailCall(node) \|\| node.arguments.length === 0) {
	46	return null;
	47	}
	48
	49	return readBuiltinErrorName(node.arguments[0]);
	50	};
	51
	52	export default defineRule({
	53	meta: {
	54	type: "problem",
	55	docs: {
	56	description:
	57	"Disallow failing Effects with builtin Error constructors instead of tagged Effect errors.",
	58	recommended: true,
	59	},
	60	messages: {
	61	noRawEffectFailErrors:
	62	"Do not pass builtin {{errorName}} to Effect.fail. Use a Data.TaggedError or Schema.TaggedError instead. If no suitable tagged error exists, define one near this module with structured fields and fail with that tagged error rather than interpolating context into a message string.",
	63	noRawYieldedEffectFailErrors:
	64	"Do not `yield* Effect.fail` with builtin {{errorName}}. In Effect.gen, prefer yielding the tagged error directly, for example `yield* new MyTaggedError({ ... })`. If no suitable Data.TaggedError or Schema.TaggedError exists, define one near this module with structured fields instead of interpolating context into a message string.",
	65	},
	66	},
	67	create(context) {
	68	return {
	69	CallExpression(node) {
	70	const errorName = readBuiltinFailedErrorName(node);
	71
	72	if (!errorName) {
	73	return;
	74	}
	75
	76	if (
	77	node.parent?.type === "YieldExpression"
	78	&& node.parent.argument === node
	79	) {
	80	return;
	81	}
	82
	83	context.report({
	84	node: node.arguments[0],
	85	messageId: "noRawEffectFailErrors",
	86	data: {
	87	errorName,
	88	},
	89	});
	90	},
	91	YieldExpression(node) {
	92	const failedCall = node.argument;
	93	const errorName = readBuiltinFailedErrorName(failedCall);
	94
	95	if (!errorName) {
	96	return;
	97	}
	98
	99	context.report({
	100	node: failedCall.arguments[0],
	101	messageId: "noRawYieldedEffectFailErrors",
	102	data: {
	103	errorName,
	104	},
	105	});
	106	},
	107	};
	108	},
	109	});

tools/oxlint/rules/no-yield-effect-fail.mjs+64−0

@@ -0,0 +1,64 @@
	1	import { defineRule } from "@oxlint/plugins";
	2
	3	const isIdentifierNamed = (node, name) =>
	4	node?.type === "Identifier" && node.name === name;
	5
	6	const isEffectFailCall = (node) =>
	7	node?.type === "CallExpression"
	8	&& node.callee?.type === "MemberExpression"
	9	&& node.callee.computed === false
	10	&& isIdentifierNamed(node.callee.object, "Effect")
	11	&& isIdentifierNamed(node.callee.property, "fail");
	12
	13	const isDirectYieldCandidate = (node) => {
	14	if (!node) {
	15	return false;
	16	}
	17
	18	if (node.type === "CallExpression" \|\| node.type === "NewExpression") {
	19	return true;
	20	}
	21
	22	if (node.type === "ParenthesizedExpression") {
	23	return isDirectYieldCandidate(node.expression);
	24	}
	25
	26	return node.type === "TSAsExpression" \|\| node.type === "TSTypeAssertion";
	27	};
	28
	29	export default defineRule({
	30	meta: {
	31	type: "suggestion",
	32	docs: {
	33	description:
	34	"Disallow `yield* Effect.fail(...)` when the yielded failure value can be yielded directly in Effect.gen.",
	35	recommended: true,
	36	},
	37	messages: {
	38	noYieldEffectFail:
	39	"Avoid `yield* Effect.fail(...)` here. In Effect.gen, yield the tagged or yieldable error expression directly instead, for example `yield* new MyTaggedError({ ... })` or `yield* myTaggedError(...)`.",
	40	},
	41	},
	42	create(context) {
	43	return {
	44	YieldExpression(node) {
	45	if (!node.delegate) {
	46	return;
	47	}
	48
	49	if (!isEffectFailCall(node.argument) \|\| node.argument.arguments.length === 0) {
	50	return;
	51	}
	52
	53	if (!isDirectYieldCandidate(node.argument.arguments[0])) {
	54	return;
	55	}
	56
	57	context.report({
	58	node,
	59	messageId: "noYieldEffectFail",
	60	});
	61	},
	62	};
	63	},
	64	});