effect-cf 0.20.0 → 0.22.0

package/src/Worker.ts

@@ -1,37 +1,48 @@
 import { WorkerEntrypoint as CloudflareWorkerEntrypoint } from "cloudflare:workers";
 import {
   type Cause,
-  ConfigProvider,
   Context,
   Effect,
   Layer,
-  ManagedRuntime,
-  type Schema as S,
+  type ManagedRuntime,
+  Option,
   type Scope,
 } from "effect";
-import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpEffect, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { OtlpExporter } from "effect/unstable/observability";
 
-import type * as Binding from "./Binding";
-import { WorkerConfig, WorkerEnvironment, type WorkerEnv } from "./Environment";
+import { WorkerEnvironment, type WorkerEnv } from "./Environment";
 import { fromMessage, fromMessageBatch, type QueueHandler } from "./Queue";
-import type * as Rpc from "./Rpc";
 import type * as RpcDefinition from "./RpcDefinition";
-import type * as ServiceBinding from "./ServiceBinding";
-import * as WorkerDefinition from "./WorkerDefinition";
-import * as CloudflareClock from "./internal/Clock";
 import * as Entrypoint from "./internal/Entrypoint";
-import { fromExecutionContext, type RunWaitUntilEffect } from "./internal/WorkerContext";
+import * as Runtime from "./internal/Runtime";
+import { fromExecutionContext } from "./internal/WorkerContext";
 
+/**
+ * Access to Cloudflare's native `ExecutionContext`.
+ */
 export class ExecutionContext extends Context.Service<
   ExecutionContext,
   globalThis.ExecutionContext
 >()("effect-cf/ExecutionContext") {}
 
+/**
+ * Options for {@link WorkerContextService.waitUntil}.
+ */
 export interface WorkerContextWaitUntilOptions<E, R> {
+  /**
+   * Failure mode for the background effect: `"observe"` (default) logs or
+   * routes the failure to `onFailure`, while `"propagate"` also rejects the
+   * native `waitUntil` promise.
+   */
   readonly mode?: "observe" | "propagate";
+  /** Custom failure handler for the background effect. */
   readonly onFailure?: (cause: Cause.Cause<E>) => Effect.Effect<void, never, R>;
 }
 
+/**
+ * Effect wrapper around `ExecutionContext` background APIs.
+ */
 export interface WorkerContextService {
   readonly raw: globalThis.ExecutionContext;
   waitUntil<A, E, R, R2 = never>(
@@ -45,14 +56,32 @@ export interface WorkerContextService {
   readonly passThroughOnException: Effect.Effect<void>;
 }
 
+/**
+ * Service used inside handlers to schedule background work via `waitUntil`.
+ *
+ * @example
+ * ```ts
+ * const handler = Effect.gen(function* () {
+ *   const ctx = yield* Worker.WorkerContext;
+ *   yield* ctx.waitUntil(Effect.log("flush analytics"));
+ *   return new Response("ok");
+ * });
+ * ```
+ */
 export class WorkerContext extends Context.Service<WorkerContext, WorkerContextService>()(
   "effect-cf/WorkerContext",
 ) {}
 
+/**
+ * Access to the incoming `Request` currently handled by a worker or Durable Object fetch.
+ */
 export class NativeRequest extends Context.Service<NativeRequest, Request>()(
   "effect-cf/NativeRequest",
 ) {}
 
+/**
+ * Returns `true` when the request is a websocket upgrade request.
+ */
 export const isWebSocketUpgrade = (request: Request): boolean =>
   request.headers.get("Upgrade")?.toLowerCase() === "websocket";
 
@@ -102,17 +131,32 @@ type RunOptions = {
 };
 
 const RunSymbol = Symbol.for("effect-cf/Worker/run");
+const FetchSymbol = Symbol.for("effect-cf/Worker/fetch");
 
+/**
+ * Successful result of a worker fetch handler: either a native `Response`
+ * (returned to Cloudflare untouched) or an Effect `HttpServerResponse`
+ * (rendered through the Effect HTTP pipeline).
+ */
 export type WorkerFetchSuccess = Response | HttpServerResponse.HttpServerResponse;
 
+/**
+ * Effect type for `fetch` handlers executed by {@link make}.
+ */
 export type WorkerHandler<ROut, A = WorkerFetchSuccess> = Effect.Effect<
   A,
   unknown,
   WorkerFetchContext<ROut>
 >;
 
+/**
+ * Effect type for worker RPC handlers.
+ */
 export type WorkerRpcHandler<ROut, A = unknown> = Effect.Effect<A, unknown, WorkerRpcContext<ROut>>;
 
+/**
+ * Shape of worker RPC handlers passed to {@link make}.
+ */
 export type WorkerRpc<ROut> = Record<string, (...args: Array<any>) => WorkerRpcHandler<ROut>>;
 
 export type WorkerRpcShape<Rpc extends WorkerRpc<ROut>, ROut> = {
@@ -139,6 +183,9 @@ export type RpcHandlers<ROut, Api> = {
     : never;
 };
 
+/**
+ * Options for creating a worker class with Effect handlers.
+ */
 export interface WorkerOptions<
   RRuntime,
   REvent = never,
@@ -153,12 +200,15 @@ export interface WorkerOptions<
    * trace/log exporters that should flush at event completion.
    */
   readonly eventLayer?: Layer.Layer<REvent, EventLayerError, WorkerBaseContext<RRuntime>>;
+  /** Main request handler. */
   readonly fetch?: Effect.Effect<
     WorkerFetchSuccess,
     unknown,
     WorkerFetchContext<RRuntime | REvent>
   >;
+  /** Queue consumer handler invoked per message batch. */
   readonly queue?: QueueHandler<RRuntime | REvent>;
+  /** Optional RPC methods exposed as class instance methods. */
   readonly rpc?: Rpc;
 }
 
@@ -169,6 +219,9 @@ export type FetchWorkerOptions<RRuntime, REvent = never, EventLayerError = never
   readonly rpc?: never;
 };
 
+/**
+ * Cloudflare `WorkerEntrypoint` constructor produced by {@link make}.
+ */
 export type WorkerClass<Rpc extends WorkerRpc<ROut>, ROut> = new (
   ctx: globalThis.ExecutionContext,
   env: WorkerEnv,
@@ -177,6 +230,9 @@ export type WorkerClass<Rpc extends WorkerRpc<ROut>, ROut> = new (
   queue(batch: globalThis.MessageBatch): Promise<void>;
 } & WorkerRpcShape<Rpc, ROut>;
 
+/**
+ * `ExportedHandler`-compatible fetch object produced by {@link makeFetchHandler}.
+ */
 export interface FetchHandler<Env extends WorkerEnv = WorkerEnv> {
   readonly fetch: (
     request: Request,
@@ -185,33 +241,81 @@ export interface FetchHandler<Env extends WorkerEnv = WorkerEnv> {
   ) => Promise<Response>;
 }
 
-export const renderHttpResponse = <A extends HttpServerResponse.HttpServerResponse, E, R>(
-  effect: Effect.Effect<A, E, R>,
-): Effect.Effect<Response, E, R> =>
-  Effect.flatMap(effect, (response) =>
-    Effect.map(Effect.context<never>(), (context) =>
-      HttpServerResponse.toWeb(response, { context }),
-    ),
-  );
-
 const renderFetchSuccess = <E, R>(
   effect: Effect.Effect<WorkerFetchSuccess, E, R>,
-): Effect.Effect<Response, E, R> =>
-  Effect.flatMap(effect, (response) =>
-    response instanceof Response
-      ? Effect.succeed(response)
-      : Effect.map(Effect.context<never>(), (context) =>
-          HttpServerResponse.toWeb(response, { context }),
-        ),
-  );
+): Effect.Effect<Response, E, Exclude<R, Scope.Scope> | HttpServerRequest.HttpServerRequest> =>
+  Effect.suspend(() => {
+    // Native `Response` values bypass all HTTP response processing: WebSocket
+    // upgrade responses and app-level `HttpEffect.toHandled` results pass
+    // through untouched. Pre-response handlers still run against a placeholder
+    // response, but their output is discarded for native `Response` results.
+    let nativeResponse: Response | undefined;
+    let webResponse: Response | undefined;
+
+    const handled = HttpEffect.toHandled(
+      Effect.flatMap(effect, (response) => {
+        if (response instanceof Response) {
+          nativeResponse = response;
+
+          return Effect.succeed(HttpServerResponse.empty());
+        }
+
+        return Effect.succeed(response);
+      }),
+      (request, response) =>
+        nativeResponse !== undefined
+          ? Effect.void
+          : Effect.map(Effect.context<never>(), (context) => {
+              webResponse = HttpServerResponse.toWeb(HttpEffect.scopeTransferToStream(response), {
+                withoutBody: request.method === "HEAD",
+                context,
+              });
+            }),
+    );
+
+    // `toHandled` re-fails with the original cause after rendering the error
+    // response, so both branches return the response captured above.
+    const captured = () => nativeResponse ?? webResponse ?? new Response(null, { status: 500 });
+
+    return Effect.matchCause(handled, { onFailure: captured, onSuccess: captured });
+  });
 
 const isWorkerOptions = <ROut, REvent, EventLayerError, Rpc extends WorkerRpc<ROut | REvent>>(
   options: WorkerOptions<ROut, REvent, EventLayerError, Rpc> | WorkerHandler<ROut>,
-): options is WorkerOptions<ROut, REvent, EventLayerError, Rpc> =>
-  typeof options === "object" &&
-  options !== null &&
-  ("eventLayer" in options || "fetch" in options || "queue" in options || "rpc" in options);
-
+): options is WorkerOptions<ROut, REvent, EventLayerError, Rpc> => !Effect.isEffect(options);
+
+/**
+ * Drains buffered OTLP telemetry once the fetch handler has produced its
+ * response.
+ *
+ * The flush is handed to `ctx.waitUntil` so it never delays the response
+ * (including streaming bodies still being consumed). It is a no-op when the
+ * context does not contain an `OtlpExporter.Flusher`.
+ */
+const scheduleTelemetryFlush: Effect.Effect<void, never, WorkerContext> = Effect.flatMap(
+  Effect.serviceOption(OtlpExporter.Flusher),
+  Option.match({
+    onNone: () => Effect.void,
+    onSome: (flusher) =>
+      Effect.flatMap(WorkerContext, (workerContext) => workerContext.waitUntil(flusher.flush)),
+  }),
+);
+
+/**
+ * Creates a Cloudflare worker class backed by a single managed Effect runtime.
+ *
+ * The runtime layer is built when Cloudflare constructs the class and reused
+ * for every event the instance handles. Layer finalizers do not run when the
+ * isolate is evicted; Cloudflare provides no shutdown hook. Use `eventLayer`
+ * for resources that must be finalized per event.
+ *
+ * @example
+ * ```ts
+ * export default Worker.make(Layer.empty, {
+ *   fetch: Effect.succeed(new Response("ok")),
+ * });
+ * ```
+ */
 export function make<ROut, LayerError>(
   layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
   fetch: WorkerHandler<ROut>,
@@ -246,69 +350,58 @@ export function make<
     constructor(ctx: globalThis.ExecutionContext, env: WorkerEnv) {
       super(ctx, env);
 
-      let runWaitUntilEffect: RunWaitUntilEffect = () =>
-        Promise.reject(new Error("WorkerContext runtime is not initialized"));
-
-      const services = Layer.mergeAll(
-        CloudflareClock.layer,
-        Layer.succeed(ExecutionContext, ctx),
-        ConfigProvider.layer(Effect.succeed(WorkerConfig.providerFromEnv(env))),
-        Layer.succeed(
-          WorkerContext,
-          fromExecutionContext(ctx, (effect) => runWaitUntilEffect(effect)),
-        ),
-        Layer.succeed(WorkerEnvironment, env),
-      ) as Layer.Layer<ExecutionContext | WorkerContext | WorkerEnvironment, never, never>;
-
-      const runtimeLayer = Entrypoint.provideEntrypointServices<
+      this.runtime = Runtime.makeEntrypointRuntime<
         ROut,
         LayerError,
-        ExecutionContext | WorkerContext | WorkerEnvironment
-      >(layer, services);
-
-      this.runtime = ManagedRuntime.make(runtimeLayer);
-      runWaitUntilEffect = <A, E>(effect: Effect.Effect<A, E, never>) =>
-        this.runtime.runPromiseExit(effect as Effect.Effect<A, E, RuntimeContext<ROut>>);
+        ExecutionContext | WorkerContext
+      >(
+        layer,
+        env,
+        Layer.mergeAll(
+          Layer.succeed(ExecutionContext, ctx),
+          Layer.succeed(WorkerContext, fromExecutionContext(ctx)),
+        ),
+      );
     }
 
     [RunSymbol]<A, E>(
       effect: Effect.Effect<A, E, RuntimeContext<ROut> | REvent | Scope.Scope>,
       runOptions: RunOptions = {},
     ): Promise<A> {
-      const effectWithEventLayer =
-        runOptions.eventLayer === false || options.eventLayer === undefined
-          ? effect
-          : effect.pipe(Effect.provide(options.eventLayer, { local: true }));
-
-      return this.runtime.runPromise(
-        Effect.scoped(
-          effectWithEventLayer as Effect.Effect<
-            A,
-            E | EventLayerError,
-            RuntimeContext<ROut> | Scope.Scope
-          >,
-        ),
+      return Runtime.runEventPromise(
+        this.runtime,
+        effect,
+        runOptions.eventLayer === false ? undefined : options.eventLayer,
       );
     }
 
     fetch(request: Request): Promise<Response> {
+      return this[FetchSymbol](request);
+    }
+
+    [FetchSymbol](
+      request: Request,
+      requestContext?: globalThis.ExecutionContext,
+    ): Promise<Response> {
       const fetchHandler = options.fetch;
 
       if (fetchHandler === undefined) {
         return Promise.resolve(new Response("Not Found", { status: 404 }));
       }
 
+      const ctx = requestContext ?? this.ctx;
       const requestServices = Layer.mergeAll(
         Layer.succeed(NativeRequest, request),
         Layer.succeed(HttpServerRequest.HttpServerRequest, HttpServerRequest.fromWeb(request)),
+        Layer.succeed(ExecutionContext, ctx),
+        Layer.succeed(WorkerContext, fromExecutionContext(ctx)),
       );
 
       return this[RunSymbol](
-        renderFetchSuccess(fetchHandler).pipe(Effect.provide(requestServices)) as Effect.Effect<
-          Response,
-          unknown,
-          RuntimeContext<ROut> | REvent | Scope.Scope
-        >,
+        renderFetchSuccess(fetchHandler).pipe(
+          Effect.tap(() => scheduleTelemetryFlush),
+          Effect.provide(requestServices),
+        ) as Effect.Effect<Response, unknown, RuntimeContext<ROut> | REvent | Scope.Scope>,
       );
     }
 
@@ -336,6 +429,21 @@ export function make<
   return Entrypoint.assumeEntrypointClass<WorkerClass<Rpc, ROut | REvent>>(EffectWorker);
 }
 
+interface FetchCapableInstance {
+  [FetchSymbol](request: Request, requestContext: globalThis.ExecutionContext): Promise<Response>;
+}
+
+/**
+ * Creates an `ExportedHandler`-compatible `{ fetch }` object backed by
+ * {@link make}.
+ *
+ * The Effect runtime is cached per `env` identity, so the user layer builds
+ * once per isolate instead of once per request. `ExecutionContext`-backed
+ * services (`Worker.ExecutionContext`, `Worker.WorkerContext`) are still
+ * provided fresh for every request. Layer finalizers do not run when the
+ * isolate is evicted; Cloudflare provides no shutdown hook. Use `eventLayer`
+ * for resources that must be finalized per event.
+ */
 export const makeFetchHandler = <
   ROut,
   LayerError,
@@ -347,136 +455,35 @@ export const makeFetchHandler = <
   options: FetchWorkerOptions<ROut, REvent, EventLayerError>,
 ): FetchHandler<Env> => {
   const WorkerClass = make(layer, options);
+  const instances = new WeakMap<WorkerEnv, FetchCapableInstance>();
 
   return {
-    fetch: (request, env, ctx) => Promise.resolve(new WorkerClass(ctx, env).fetch(request)),
-  };
-};
-
-export type ServiceFreeSchema = S.Codec<any, any, never, never>;
-
-export interface Method<
-  Args extends ReadonlyArray<ServiceFreeSchema> = ReadonlyArray<ServiceFreeSchema>,
-  Success extends ServiceFreeSchema = ServiceFreeSchema,
-> {
-  readonly args: Args;
-  readonly success: Success;
-}
+    fetch: (request, env, ctx) => {
+      let instance = instances.get(env);
 
-export namespace Method {
-  export type Any = Method<ReadonlyArray<ServiceFreeSchema>, ServiceFreeSchema>;
-
-  type ArgsFromSchemas<Args extends ReadonlyArray<ServiceFreeSchema>> = Args extends readonly []
-    ? []
-    : Args extends readonly [
-          infer Head extends ServiceFreeSchema,
-          ...infer Tail extends ReadonlyArray<ServiceFreeSchema>,
-        ]
-      ? [S.Schema.Type<Head>, ...ArgsFromSchemas<Tail>]
-      : Array<S.Schema.Type<Args[number]>>;
-
-  export type Args<Self extends Any> = ArgsFromSchemas<Self["args"]>;
-
-  export type Success<Self extends Any> = S.Schema.Type<Self["success"]>;
-}
-
-export type Methods = Record<string, Method.Any>;
-
-export type NoReservedMethods<MethodsShape extends Methods> =
-  Extract<keyof MethodsShape, ReservedMethodName> extends never ? MethodsShape : never;
-
-export interface Definition<Id extends string = string, MethodsShape extends Methods = Methods> {
-  readonly id: Id;
-  readonly methods: MethodsShape;
-}
-
-export namespace Definition {
-  export type Any = Definition<string, Methods>;
-}
-
-export type ServerApi<Self extends Definition.Any> = {
-  readonly [Key in keyof Self["methods"]]: (
-    ...args: Method.Args<Self["methods"][Key]>
-  ) => Promise<Method.Success<Self["methods"][Key]>>;
-};
-
-export type Api<Self extends Definition.Any> = Rpc.Provider<ServerApi<Self>, ReservedMethodName>;
-
-export type Handlers<ROut, Self extends Definition.Any> = {
-  readonly [Key in keyof Self["methods"]]: (
-    ...args: Method.Args<Self["methods"][Key]>
-  ) => WorkerRpcHandler<ROut, Method.Success<Self["methods"][Key]>>;
-};
-
-export interface Options<
-  ROut,
-  Self extends Definition.Any,
-  REvent = never,
-  EventLayerError = never,
-> extends Omit<WorkerOptions<ROut, REvent, EventLayerError, Handlers<ROut | REvent, Self>>, "rpc"> {
-  readonly rpc: Handlers<ROut | REvent, Self>;
-}
+      if (instance === undefined) {
+        instance = new WorkerClass(ctx, env) as unknown as FetchCapableInstance;
+        instances.set(env, instance);
+      }
 
-export type LayerOptions = WorkerDefinition.LayerOptions;
-
-export type TagClass<Self, Id extends string, MethodsShape extends Methods> = Context.ServiceClass<
-  Self,
-  Id,
-  ServiceBinding.ServiceBindingEffectClient<
-    Api<Definition<Id, MethodsShape>>,
-    Definition<Id, MethodsShape>
-  >
-> &
-  ServiceBinding.ServiceBindingStaticClient<
-    Self,
-    Api<Definition<Id, MethodsShape>>,
-    Definition<Id, MethodsShape>
-  > & {
-    readonly id: Id;
-    readonly methods: MethodsShape;
-    readonly make: <ROut, LayerError, REvent = never, EventLayerError = never>(
-      layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
-      options: Options<ROut, Definition<Id, MethodsShape>, REvent, EventLayerError>,
-    ) => WorkerClass<Handlers<ROut | REvent, Definition<Id, MethodsShape>>, ROut | REvent>;
-    readonly layer: (
-      options: LayerOptions,
-    ) => Layer.Layer<
-      Self,
-      Binding.BindingNotFoundError | Binding.BindingValidationError,
-      WorkerEnvironment
-    >;
+      return instance[FetchSymbol](request, ctx);
+    },
   };
-
-export type TagFactory = <Self>() => <Id extends string, const MethodsShape extends Methods>(
-  id: Id,
-  methods: MethodsShape & NoReservedMethods<MethodsShape>,
-) => TagClass<Self, Id, MethodsShape>;
-
-export const Tag = WorkerDefinition.Tag as unknown as TagFactory;
-
-export const method = WorkerDefinition.method as {
-  <Success extends ServiceFreeSchema>(definition: {
-    readonly success: Success;
-  }): Method<readonly [], Success>;
-  <
-    const Args extends ReadonlyArray<ServiceFreeSchema>,
-    Success extends ServiceFreeSchema,
-  >(definition: {
-    readonly args: Args;
-    readonly success: Success;
-  }): Method<Args, Success>;
 };
 
-export const implement = WorkerDefinition.implement as unknown as <
-  ROut,
-  const Self extends Definition.Any,
->(
-  _definition: Self,
-  handlers: Handlers<ROut, Self>,
-) => Handlers<ROut, Self>;
-
-export type HandlerEffect<
-  ROut,
-  Self extends Definition.Any,
-  Key extends keyof Self["methods"],
-> = WorkerRpcHandler<ROut, Method.Success<Self["methods"][Key]>>;
+export type {
+  Api,
+  Definition,
+  HandlerEffect,
+  Handlers,
+  LayerOptions,
+  Method,
+  Methods,
+  NoReservedMethods,
+  Options,
+  ServerApi,
+  ServiceFreeSchema,
+  TagClass,
+} from "./WorkerDefinition";
+
+export { implement, method, Tag } from "./WorkerDefinition";

package/src/WorkerDefinition.ts

@@ -37,15 +37,10 @@ export namespace Method {
       ? [S.Schema.Type<Head>, ...ArgsFromSchemas<Tail>]
       : Array<S.Schema.Type<Args[number]>>;
 
-  type EncodedArgsFromSchemas<Args extends ReadonlyArray<ServiceFreeSchema>> =
-    Args extends readonly []
-      ? []
-      : Args extends readonly [
-            infer Head extends ServiceFreeSchema,
-            ...infer Tail extends ReadonlyArray<ServiceFreeSchema>,
-          ]
-        ? [S.Codec.Encoded<Head>, ...EncodedArgsFromSchemas<Tail>]
-        : Array<S.Codec.Encoded<Args[number]>>;
+  /** Method schemas cross the wire through their canonical JSON codec. */
+  type EncodedArgsFromSchemas<Args extends ReadonlyArray<ServiceFreeSchema>> = {
+    [Index in keyof Args]: S.Json;
+  };
 
   export type Args<Self extends Any> = ArgsFromSchemas<Self["args"]>;
 
@@ -53,7 +48,7 @@ export namespace Method {
 
   export type Success<Self extends Any> = S.Schema.Type<Self["success"]>;
 
-  export type EncodedSuccess<Self extends Any> = S.Codec.Encoded<Self["success"]>;
+  export type EncodedSuccess<Self extends Any> = S.Json;
 }
 
 export type Methods = Record<string, Method.Any>;

package/src/WorkersAi.ts

@@ -14,6 +14,7 @@ import type {
 
 import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
+import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedWorkersAiBinding = "Workers AI binding with run(), gateway(), and models()";
 
@@ -22,7 +23,11 @@ export class WorkersAiOperationError extends Data.TaggedError("WorkersAiOperatio
   readonly binding: string;
   readonly operation: string;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Workers AI ${this.operation} failed for binding "${this.binding}": ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 /** Typed Workers AI binding definition. */
 export interface WorkersAiDefinition {
@@ -101,7 +106,7 @@ export interface WorkersAiClient<ModelList extends AiModelListType = AiModels> {
   readonly gateway: (
     gatewayId: string,
   ) => Effect.Effect<CloudflareAiGateway, WorkersAiOperationError>;
-  readonly unsafeRaw: Effect.Effect<WorkersAiBinding<ModelList>>;
+  readonly rawUnsafe: Effect.Effect<WorkersAiBinding<ModelList>>;
   readonly definition: WorkersAiDefinition;
 }
 
@@ -177,10 +182,12 @@ export const embeddingResponse = (value: {
 export const makeClient =
   <ModelList extends AiModelListType = AiModels>(definition: WorkersAiDefinition) =>
   (ai: WorkersAiBinding<ModelList>): WorkersAiClient<ModelList> => {
-    const run = ((model: string, input: Record<string, unknown>, options?: WorkersAiOptions) =>
-      tryWorkersAiPromise(definition.binding, "run", () =>
-        ai.run(model as string & {}, input, options),
-      )) as WorkersAiClient<ModelList>["run"];
+    const run = Effect.fn("WorkersAi.run")(
+      (model: string, input: Record<string, unknown>, options?: WorkersAiOptions) =>
+        tryWorkersAiPromise(definition.binding, "run", () =>
+          ai.run(model as string & {}, input, options),
+        ),
+    ) as WorkersAiClient<ModelList>["run"];
 
     return {
       definition,
@@ -190,22 +197,25 @@ export const makeClient =
         () => ai.aiGatewayLogId,
       ),
       run,
-      runEmbedding: (model, input, options) =>
-        run(model, input, options).pipe(
-          Effect.map((response) =>
-            embeddingResponse(
-              response as {
-                readonly data?: ReadonlyArray<ReadonlyArray<number>>;
-                readonly shape?: ReadonlyArray<number>;
-              },
+      runEmbedding: Effect.fn("WorkersAi.runEmbedding")(
+        (model: string, input: WorkersAiEmbeddingInput, options?: WorkersAiOptions) =>
+          run(model, input as Record<string, unknown>, options).pipe(
+            Effect.map((response) =>
+              embeddingResponse(
+                response as {
+                  readonly data?: ReadonlyArray<ReadonlyArray<number>>;
+                  readonly shape?: ReadonlyArray<number>;
+                },
+              ),
             ),
           ),
-        ),
-      models: (params) =>
+      ),
+      models: Effect.fn("WorkersAi.models")((params?: WorkersAiModelsSearchParams) =>
         tryWorkersAiPromise(definition.binding, "models", () => ai.models(params)),
+      ),
       gateway: (gatewayId) =>
         tryWorkersAiSync(definition.binding, "gateway", () => ai.gateway(gatewayId)),
-      unsafeRaw: Effect.succeed(ai),
+      rawUnsafe: Effect.succeed(ai),
     };
   };