@effect-agent/platform-cloudflare 0.1.0-beta.13 → 0.1.0-beta.131

package/src/CloudflareAiGateway.ts

@@ -0,0 +1,170 @@
+import { Context, Effect, Layer, Option, Redactable, Redacted, Schema } from "effect";
+import {
+  FetchHttpClient,
+  Headers,
+  HttpClient,
+  HttpClientError,
+  HttpClientRequest,
+} from "effect/unstable/http";
+
+const Segment = Schema.NonEmptyString.check(
+  Schema.isMaxLength(256),
+  Schema.isPattern(/^[a-zA-Z0-9_-]+$/),
+);
+
+const decodeSegment = Schema.decodeUnknownSync(Segment);
+
+/** Options understood by upstream Effect AI clients; no model or provider wrapper is created. */
+export interface ClientOptions {
+  readonly apiUrl: string;
+  readonly transformClient: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
+}
+
+export interface ProviderOptions {
+  readonly accountId: string;
+  readonly gatewayId: string;
+  /** Cloudflare's provider path, such as openai, anthropic, google-ai-studio, or perplexity-ai. */
+  readonly provider: string;
+  /** Omit only for an unauthenticated gateway with a separately supplied provider key. */
+  readonly apiToken?: Redacted.Redacted<string>;
+}
+
+export interface RestOptions {
+  readonly accountId: string;
+  readonly gatewayId: string;
+  /** Cloudflare API token with Workers AI Read permission. */
+  readonly apiToken: Redacted.Redacted<string>;
+  /** Matches the paths appended by the upstream Effect client. */
+  readonly protocol: "responses" | "chat-completions" | "messages";
+}
+
+/** Choose exactly one route: a native provider path or an account REST protocol. */
+export type RouteOptions =
+  | (ProviderOptions & { readonly protocol?: never })
+  | (RestOptions & { readonly provider?: never });
+
+const redactGatewayToken = (headers: Headers.Headers, tokenHeader: string): void => {
+  // HTTP tracing can copy headers after preprocessing. Attach the public redaction
+  // protocol to the final request as well, before a provider builds error details.
+  Object.defineProperty(headers, Redactable.symbolRedactable, {
+    configurable: true,
+    value: (context: Context.Context<never>) =>
+      Headers.redact(headers, [...Context.get(context, Headers.CurrentRedactedNames), tokenHeader]),
+  });
+};
+
+const clientOptions = (
+  apiUrl: string,
+  tokenHeader: "authorization" | "cf-aig-authorization",
+  apiToken: Redacted.Redacted<string> | undefined,
+  gatewayId?: string,
+): ClientOptions =>
+  Object.freeze({
+    apiUrl,
+    transformClient: (client: HttpClient.HttpClient) =>
+      client.pipe(
+        HttpClient.mapRequestEffect((request) => {
+          const url = URL.parse(request.url);
+
+          // Check the normalized URL too: dot segments must not escape this account or gateway.
+          if (
+            url === null ||
+            url.username !== "" ||
+            url.password !== "" ||
+            !(url.href === apiUrl || url.href.startsWith(`${apiUrl}/`))
+          ) {
+            return Effect.fail(
+              new HttpClientError.HttpClientError({
+                reason: new HttpClientError.InvalidUrlError({
+                  request,
+                  description: "Request is outside the configured Cloudflare AI Gateway endpoint",
+                }),
+              }),
+            );
+          }
+          let prepared = request;
+
+          if (apiToken !== undefined) {
+            prepared = HttpClientRequest.setHeader(
+              prepared,
+              tokenHeader,
+              `Bearer ${Redacted.value(apiToken)}`,
+            );
+          }
+          if (gatewayId !== undefined) {
+            prepared = HttpClientRequest.setHeader(prepared, "cf-aig-gateway-id", gatewayId);
+          }
+
+          return Effect.succeed(prepared);
+        }),
+        HttpClient.transformResponse((effect) =>
+          Effect.gen(function* () {
+            const defaults = yield* Effect.serviceOption(FetchHttpClient.RequestInit);
+
+            return yield* effect.pipe(
+              Effect.provideService(FetchHttpClient.RequestInit, {
+                ...Option.getOrElse(defaults, () => ({})),
+                redirect: "error",
+              }),
+            );
+          }),
+        ),
+        HttpClient.transformResponse((effect) =>
+          effect.pipe(
+            Effect.tap((response) =>
+              Effect.sync(() => redactGatewayToken(response.request.headers, tokenHeader)),
+            ),
+            Effect.tapError((error) =>
+              Effect.sync(() => redactGatewayToken(error.reason.request.headers, tokenHeader)),
+            ),
+            Effect.updateService(Headers.CurrentRedactedNames, (names) => [...names, tokenHeader]),
+          ),
+        ),
+      ),
+  });
+
+/**
+ * Provider-native proxy for model calls, streaming, embeddings, and hosted tools supported
+ * by that provider. Pass the result to the upstream client's layer along with its apiKey
+ * for BYOK-in-request, or omit apiKey for Gateway stored keys / Unified Billing.
+ * Provider model names and request bodies pass through unchanged. This module is Node-safe.
+ * Custom transforms and redirect policies must retain this endpoint and credential boundary.
+ */
+export const provider = (options: ProviderOptions): ClientOptions =>
+  clientOptions(
+    `https://gateway.ai.cloudflare.com/v1/${decodeSegment(options.accountId)}/${decodeSegment(options.gatewayId)}/${decodeSegment(options.provider)}`,
+    "cf-aig-authorization",
+    options.apiToken,
+  );
+
+/**
+ * Cloudflare's account REST API (not the deprecated /compat API). Use provider-qualified
+ * model names, e.g. openai/gpt-4.1 or anthropic/claude-haiku-4.5, and omit provider apiKey.
+ * OpenAI clients append /responses or /chat/completions; Anthropic appends /v1/messages.
+ * Compatibility remains the responsibility of the selected upstream client and model.
+ */
+export const rest = (options: RestOptions): ClientOptions =>
+  clientOptions(
+    `https://api.cloudflare.com/client/v4/accounts/${decodeSegment(options.accountId)}/ai${options.protocol === "messages" ? "" : "/v1"}`,
+    "authorization",
+    options.apiToken,
+    decodeSegment(options.gatewayId),
+  );
+
+/**
+ * Provide a Gateway-configured upstream client directly in a Layer pipeline.
+ * Pass the client's `layer` factory, or a callback adding client-specific options.
+ * The factory's errors and remaining services (such as HttpClient) stay visible.
+ * Model selection and resource ownership remain with the supplied upstream Layers.
+ *
+ * @example
+ * ```ts
+ * AnthropicLanguageModel.model("claude-haiku-4-5").pipe(
+ *   Gateway.provide(AnthropicClient.layer, { ...options, provider: "anthropic" }),
+ * )
+ * ```
+ */
+export const provide = <Client, E, R>(
+  clientLayer: (options: ClientOptions) => Layer.Layer<Client, E, R>,
+  options: RouteOptions,
+) => Layer.provide(clientLayer(options.provider !== undefined ? provider(options) : rest(options)));

package/src/CloudflareBindings.ts

@@ -0,0 +1,199 @@
+import { Context, Effect, Layer, Predicate, Schema } from "effect";
+import { type ThreadId } from "effect-agent/identifiers";
+import { type ProducerId } from "effect-agent/records";
+import { RpcTargets } from "effect-cf";
+
+/**
+ * Cloudflare platform bindings as Effect services (DEPLOY-010: "Cloudflare platform bindings
+ * are supplied as Effect services/Layers"). Application code never reads `env` or touches a
+ * `DurableObjectState` directly — the Thread Object class constructs these Layers once
+ * per incarnation and everything downstream consumes the services.
+ */
+
+/** A Cloudflare platform binding was missing or carried the wrong shape (DEPLOY-003/010). */
+export class CloudflareBindingError extends Schema.TaggedError<CloudflareBindingError>()(
+  "CloudflareBindingError",
+  {
+    binding: Schema.String,
+    message: Schema.String,
+  },
+) {}
+
+/**
+ * The RPC surface one Thread Durable Object exposes to Workers and to sibling
+ * Thread Objects. `ThreadObject.make` implements it; the Worker-side client
+ * and the cross-Object transport call it through `DurableObjectNamespace` stubs. Every
+ * `encoded` value is a Schema-encoded envelope (`client.ts` wire schemas for host entry
+ * points, `@effect-agent/storage-cloudflare` port envelopes for `portCall`), so the RPC
+ * boundary carries only structured-cloneable JSON. The optional trailing trace context is
+ * transient native RPC metadata, stripped by an opted-in effect-cf receiver before decoding
+ * the host envelope. It never enters durable state.
+ */
+export interface ThreadObjectRpc extends Rpc.DurableObjectBranded {
+  /** Admission-limits gate + `DurableAgentRuntime.submit`; answers a `SubmitResponse`. */
+  submitEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  /** Wake-hinted, poll-guaranteed settlement wait; answers an `AwaitSettlementResponse`. */
+  submissionStatusEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  awaitSettlementEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  /** Event-driven durable progress wait; answers a `ProgressObserved` host response. */
+  awaitProgressEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  /** Best-effort cancellation for one in-flight progress wait. */
+  cancelProgressEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  /** One bounded page of canonical records; answers an `ObservePageResponse`. */
+  observePage(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  /** Durable abort intent; answers an `AbortResponse`. */
+  abortEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  /** Durable approval decision (plan §2.6); answers a `ResolveApprovalResponse`. */
+  resolveApprovalEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  /** Authorized DUR-017 Unknown-Outcome resolution; answers a `ResolveUnknownResponse`. */
+  resolveUnknownEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  /** Owner-side cross-Object port endpoint (WP2 envelopes, executed on LOCAL facets). */
+  portCall(encoded: unknown): Promise<unknown>;
+  /** Droppable liveness hint from another Object: arms an immediate alarm. */
+  wake(): Promise<void>;
+}
+
+/** A logical Thread endpoint may be bound to an application Object without forging its brand. */
+export type ThreadObjectClient = Omit<ThreadObjectRpc, keyof Rpc.DurableObjectBranded>;
+
+/**
+ * Deterministic logical Thread placement. The native adapter uses `idFromName(threadId)`;
+ * a shared application owner can bind that logical identity into its RPC adapter instead.
+ * Lookup performs no I/O and grants no authority. Calls reuse a native target within
+ * one invocation; incoming requests and durable retries acquire their own targets.
+ */
+export class ThreadObjectNamespace extends Context.Service<
+  ThreadObjectNamespace,
+  {
+    readonly get: (threadId: ThreadId) => ThreadObjectClient;
+    /** Stable binding name for opted-in native RPC tracing; absent by default. */
+    readonly rpcTracing?: string;
+  }
+>()("@effect-agent/platform-cloudflare/ThreadObjectNamespace") {
+  static layer(
+    namespace: DurableObjectNamespace<ThreadObjectRpc>,
+    options: { readonly rpcTracing?: string } = {},
+  ): Layer.Layer<ThreadObjectNamespace> {
+    return Layer.succeed(ThreadObjectNamespace)({
+      get: (threadId) => namespace.get(namespace.idFromName(threadId)),
+      ...(options.rpcTracing === undefined ? {} : { rpcTracing: options.rpcTracing }),
+    });
+  }
+}
+
+/** Invoke a placed Thread using the current invocation's native RPC channel. */
+export const callThreadObject = Effect.fn("callThreadObject")(function* <A, E>(
+  threadId: ThreadId,
+  invoke: (target: ThreadObjectClient) => Promise<A>,
+  onError: (cause: unknown) => E,
+): Effect.fn.Return<A, E, ThreadObjectNamespace> {
+  const namespace = yield* ThreadObjectNamespace;
+
+  const target = yield* RpcTargets.get(namespace, threadId, () => namespace.get(threadId)).pipe(
+    Effect.mapError(onError),
+  );
+
+  return yield* Effect.tryPromise({ try: () => invoke(target), catch: onError }).pipe(
+    Effect.tapCause(() => RpcTargets.invalidate(target)),
+  );
+});
+
+/**
+ * Narrow one `env` member to a `DurableObjectNamespace`. `env` is an untyped platform value,
+ * and a namespace binding is a host object no Schema can decode, so this is the documented
+ * narrowest-boundary check (structural probe for the namespace surface the transport uses);
+ * a missing or misshaped binding fails typed before any Layer is built.
+ */
+export const threadNamespaceFromEnv = Effect.fn("threadNamespaceFromEnv")(function* (
+  env: unknown,
+  binding: string,
+): Effect.fn.Return<DurableObjectNamespace<ThreadObjectRpc>, CloudflareBindingError> {
+  if (!Predicate.isObjectKeyword(env)) {
+    return yield* CloudflareBindingError.make({
+      binding,
+      message: "The Worker environment is not an object; no bindings are available.",
+    });
+  }
+
+  const candidate = yield* Effect.try({
+    try: () => {
+      const value: unknown = Reflect.get(env, binding);
+
+      if (!Predicate.isObjectKeyword(value)) return undefined;
+      const idFromName: unknown = Reflect.get(value, "idFromName");
+      const get: unknown = Reflect.get(value, "get");
+
+      return typeof idFromName === "function" && typeof get === "function" ? value : undefined;
+    },
+    catch: () =>
+      CloudflareBindingError.make({
+        binding,
+        message: `env.${binding} could not be inspected as a DurableObjectNamespace binding.`,
+      }),
+  });
+
+  if (candidate !== undefined) {
+    // The structural probe above is the entire runtime contract this package relies on;
+    // the assertion records that `idFromName`/`get` name a DurableObjectNamespace.
+    return candidate as unknown as DurableObjectNamespace<ThreadObjectRpc>;
+  }
+
+  return yield* CloudflareBindingError.make({
+    binding,
+    message:
+      `env.${binding} is not a DurableObjectNamespace binding; declare the Thread ` +
+      "Object class under this binding in the Worker configuration.",
+  });
+});
+
+/**
+ * Build the namespace from Worker `env` (fails typed). Enable `rpcTracing` only when the
+ * receiver also opts into the effect-cf native RPC trace-context contract.
+ */
+export const threadNamespaceLayer = (
+  env: unknown,
+  binding: string,
+  options: { readonly rpcTracing?: boolean } = {},
+): Layer.Layer<ThreadObjectNamespace, CloudflareBindingError> =>
+  Layer.effect(ThreadObjectNamespace)(
+    Effect.map(threadNamespaceFromEnv(env, binding), (namespace) => ({
+      get: (threadId) => namespace.get(namespace.idFromName(threadId)),
+      ...(options.rpcTracing === true ? { rpcTracing: binding } : {}),
+    })),
+  );
+
+/**
+ * The live Durable Object execution context of THIS incarnation. Only Layer construction and
+ * the alarm service consume it; important state never lives on it (`ctx.storage` is truth,
+ * everything in memory is a cache — deployment spec §11).
+ */
+export class DurableObjectContext extends Context.Service<
+  DurableObjectContext,
+  {
+    readonly ctx: DurableObjectState;
+    readonly env: unknown;
+  }
+>()("@effect-agent/platform-cloudflare/DurableObjectContext") {
+  static layer(ctx: DurableObjectState, env: unknown): Layer.Layer<DurableObjectContext> {
+    return Layer.succeed(DurableObjectContext)({ ctx, env });
+  }
+}
+
+/**
+ * The Thread identity this Object serializes and the producer identity its Attempts
+ * write with (`{producerPrefix}:{threadId}`, plan §1.4). Derived once per incarnation
+ * from `ctx.id.name` — the Object identity rule guarantees the name IS the Thread ID.
+ */
+export class ThreadObjectIdentity extends Context.Service<
+  ThreadObjectIdentity,
+  {
+    readonly threadId: ThreadId;
+    readonly producerId: ProducerId;
+  }
+>()("@effect-agent/platform-cloudflare/ThreadObjectIdentity") {}
+
+/** Logical Threads whose canonical stores and admission ledger live in this physical Object. */
+export class ThreadObjectPlacement extends Context.Service<
+  ThreadObjectPlacement,
+  { readonly ownsThread: (threadId: ThreadId) => boolean }
+>()("@effect-agent/platform-cloudflare/ThreadObjectPlacement") {}

package/src/CloudflareBrowser.ts

@@ -0,0 +1,15 @@
+/** Public CloudflareBrowser API. Implementation helpers remain private. */
+export {
+  BrowserQuickActionBrowserBinding,
+  BrowserQuickActionRpcError,
+  BrowserQuickActionWorkersAi,
+  BrowserQuickActionWorkersAiPolicyError,
+  browserQuickActionCaptureLayer,
+  browserQuickActionWorkersAiCaptureLayer,
+  browserQuickActionScreenshotLayer,
+  CloudflareBrowser,
+  type BrowserQuickActionCaptureOptions,
+  type BrowserQuickActionClient,
+  type BrowserQuickActionWorkersAiPolicy,
+  type CloudflareBrowserOptions,
+} from "./internal/browser-quick-action.ts";