@effect-agent/platform-cloudflare 0.1.0-beta.107 → 0.1.0-beta.108

package/src/internal/browser-binding.ts

@@ -0,0 +1,82 @@
+/// <reference types="@cloudflare/workers-types" />
+import puppeteer, { type Browser } from "@cloudflare/puppeteer";
+import { Context, Layer, Schema } from "effect";
+
+import { browserFailure, BrowserRunFailure } from "./browser-failure.ts";
+
+const Acquired = Schema.Struct({ sessionId: Schema.String.check(Schema.isUUID()) });
+
+/** Native transport port shared by both scoped adapters; the Layer owns the foreign binding. */
+export class BrowserRunBinding extends Context.Service<
+  BrowserRunBinding,
+  {
+    readonly acquire: (
+      keepAliveMillis: number,
+      operation: "protected.acquire" | "interactive.acquire",
+    ) => Promise<string>;
+    readonly connect: (sessionId: string, operation: string) => Promise<Browser>;
+  }
+>()("@effect-agent/platform-cloudflare/internal/BrowserRunBinding") {
+  static layer(browser: Pick<BrowserRun, "fetch">) {
+    return Layer.succeed(this)({
+      // One allocation path, with recording explicitly disabled for private sessions.
+      acquire: async (keepAliveMillis, operation) => {
+        const response = await browser.fetch(
+          `https://browser-rendering.cloudflare.com/v1/devtools/browser?keep_alive=${keepAliveMillis}&recording=false`,
+          { method: "POST" },
+        );
+
+        if (response.status !== 200) {
+          const failure = new BrowserRunFailure({
+            operation,
+            reason: "provider",
+            status: response.status,
+          });
+
+          try {
+            await response.body?.cancel();
+          } catch {
+            // Body cancellation cannot replace the acquisition refusal.
+          }
+          throw failure;
+        }
+
+        return Schema.decodeUnknownSync(Acquired)(await response.json()).sessionId;
+      },
+      // The SDK embeds bodies and session IDs in errors; retain status before that loss.
+      connect: async (sessionId, operation) => {
+        let failure: BrowserRunFailure | undefined;
+
+        try {
+          return await puppeteer.connect(
+            {
+              fetch: async (input: RequestInfo | URL, init?: RequestInit) => {
+                try {
+                  const response = await browser.fetch(input, init);
+
+                  if (response.status !== 101) {
+                    failure = new BrowserRunFailure({
+                      operation,
+                      reason: "provider",
+                      status: response.status,
+                    });
+                    await response.body?.cancel();
+                    throw failure;
+                  }
+
+                  return response;
+                } catch (cause) {
+                  failure ??= browserFailure(operation, cause);
+                  throw failure;
+                }
+              },
+            },
+            sessionId,
+          );
+        } catch (cause) {
+          throw failure ?? browserFailure(operation, cause);
+        }
+      },
+    });
+  }
+}

package/src/internal/browser-failure.ts

@@ -0,0 +1,92 @@
+import type { Effect } from "effect";
+import { Cause, Data, ErrorReporter, Predicate, Schema } from "effect";
+
+/** Source-authored stages and classifications only; never retain SDK text or session capabilities. */
+export class BrowserRunFailure extends Data.TaggedError("BrowserRunFailure")<{
+  readonly operation: string;
+  readonly reason:
+    | "provider"
+    | "timeout"
+    | "malformed"
+    | "configuration"
+    | "authorization"
+    | "rate-limited"
+    | "pending";
+  readonly status?: number;
+  readonly cause?: BrowserRunFailure | { readonly name: string };
+}> {
+  readonly [ErrorReporter.severity] = "Error" as const;
+}
+
+/** A public projection of an already reported private failure must not produce another issue. */
+export const reportedBrowserError = <A extends object>(error: A): A =>
+  Object.assign(error, { [ErrorReporter.ignore]: true });
+
+export const inheritBrowserReport = <A extends object>(original: unknown, error: A): A =>
+  ErrorReporter.isIgnored(original) ? reportedBrowserError(error) : error;
+
+const reasonSchema = Schema.Literals([
+  "provider",
+  "timeout",
+  "malformed",
+  "configuration",
+  "authorization",
+  "rate-limited",
+  "pending",
+]);
+
+const statusSchema = Schema.Int.check(Schema.isBetween({ minimum: 100, maximum: 599 }));
+
+const failureNames = new Set([
+  "TypeError",
+  "RangeError",
+  "SyntaxError",
+  "TimeoutError",
+  "SchemaError",
+]);
+
+export const browserFailure = (operation: string, cause?: unknown): BrowserRunFailure =>
+  cause instanceof BrowserRunFailure
+    ? cause
+    : new BrowserRunFailure({
+        operation,
+        reason:
+          Predicate.isObject(cause) && "reason" in cause && Schema.is(reasonSchema)(cause.reason)
+            ? cause.reason
+            : "provider",
+        ...(Predicate.isObject(cause) && "status" in cause && Schema.is(statusSchema)(cause.status)
+          ? { status: cause.status }
+          : {}),
+        ...(Predicate.isObject(cause) &&
+        "cause" in cause &&
+        cause.cause instanceof BrowserRunFailure
+          ? { cause: cause.cause }
+          : Predicate.isObject(cause) &&
+              "name" in cause &&
+              typeof cause.name === "string" &&
+              failureNames.has(cause.name)
+            ? { cause: { name: cause.name } }
+            : {}),
+      });
+
+/** Keep mixed defects and interruptions distinct while discarding all foreign diagnostic content. */
+export const reportBrowserCause = <E>(
+  operation: string,
+  cause: Cause.Cause<E>,
+): Effect.Effect<void> =>
+  ErrorReporter.report(
+    Cause.fromReasons(
+      cause.reasons
+        .filter((reason) => !Cause.isFailReason(reason) || !ErrorReporter.isIgnored(reason.error))
+        .map((reason) => {
+          switch (reason._tag) {
+            case "Fail":
+              return Cause.makeFailReason(browserFailure(operation, reason.error));
+            case "Die":
+              return Cause.makeDieReason(browserFailure(operation, reason.defect));
+            case "Interrupt":
+              return reason;
+          }
+        }),
+    ),
+  );

package/src/internal/browser-session-lifecycle.ts

@@ -1,6 +1,8 @@
 import { Context, Effect, Layer, Option, Redacted, Schema, Stream } from "effect";
 import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
 
+import { browserFailure } from "./browser-failure.ts";
+
 export class BrowserRunCleanupError extends Schema.TaggedError<BrowserRunCleanupError>()(
   "BrowserRunCleanupError",
   {
@@ -14,6 +16,7 @@ export class BrowserRunCleanupError extends Schema.TaggedError<BrowserRunCleanup
       "pending",
     ]),
     status: Schema.optionalKey(Schema.Int),
+    cause: Schema.optionalKey(Schema.Defect()),
   },
 ) {}
 
@@ -65,7 +68,13 @@ export class BrowserRunSessionLifecycle extends Context.Service<
             .pipe(
               // workerd supports manual/follow, not error. Reject every redirect below.
               Effect.provideService(FetchHttpClient.RequestInit, { redirect: "manual" }),
-              Effect.mapError(() => new BrowserRunCleanupError({ reason: "provider" })),
+              Effect.mapError(
+                (cause) =>
+                  new BrowserRunCleanupError({
+                    reason: "provider",
+                    cause: browserFailure("browser.close.request", cause),
+                  }),
+              ),
             );
 
           if (response.status === 401 || response.status === 403)
@@ -99,11 +108,23 @@ export class BrowserRunSessionLifecycle extends Context.Service<
 
               return Effect.succeed(combined);
             },
-          ).pipe(Effect.mapError(() => new BrowserRunCleanupError({ reason: "malformed" })));
+          ).pipe(
+            Effect.mapError(
+              (cause) =>
+                new BrowserRunCleanupError({
+                  reason: "malformed",
+                  cause: browserFailure("browser.close.response", cause),
+                }),
+            ),
+          );
 
           const body = yield* Effect.try({
             try: () => new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes),
-            catch: () => new BrowserRunCleanupError({ reason: "malformed" }),
+            catch: (cause) =>
+              new BrowserRunCleanupError({
+                reason: "malformed",
+                cause: browserFailure("browser.close.decode", cause),
+              }),
           });
 
           if (response.status === 404) {
@@ -117,14 +138,26 @@ export class BrowserRunSessionLifecycle extends Context.Service<
           }
           if (method === "DELETE") {
             const result = yield* Schema.decodeEffect(Schema.fromJsonString(Closed))(body).pipe(
-              Effect.mapError(() => new BrowserRunCleanupError({ reason: "malformed" })),
+              Effect.mapError(
+                (cause) =>
+                  new BrowserRunCleanupError({
+                    reason: "malformed",
+                    cause: browserFailure("browser.close.response", cause),
+                  }),
+              ),
             );
 
             return result.status === "closed";
           }
 
           const result = yield* Schema.decodeEffect(Schema.fromJsonString(Metadata))(body).pipe(
-            Effect.mapError(() => new BrowserRunCleanupError({ reason: "malformed" })),
+            Effect.mapError(
+              (cause) =>
+                new BrowserRunCleanupError({
+                  reason: "malformed",
+                  cause: browserFailure("browser.close.response", cause),
+                }),
+            ),
           );
 
           if (result.sessionId !== sessionId)

package/src/protected-browser/binding.ts

@@ -1,9 +1,16 @@
 /// <reference types="@cloudflare/workers-types" />
-import puppeteer, { type Browser, type Page, type CDPSession } from "@cloudflare/puppeteer";
-import { Clock, Context, Crypto, Effect, Layer, Redacted, Schema, type Scope } from "effect";
+import { type Browser, type Page, type CDPSession } from "@cloudflare/puppeteer";
+import { Cause, Context, Crypto, Effect, Layer, Redacted, Schema, type Scope } from "effect";
 import { type InteractiveBrowserPolicy } from "effect-agent/interactive-browser";
 import { ProtectedBrowserError } from "effect-agent/protected-browser";
 
+import { BrowserRunBinding } from "../internal/browser-binding.ts";
+import {
+  browserFailure,
+  BrowserRunFailure,
+  reportBrowserCause,
+  reportedBrowserError,
+} from "../internal/browser-failure.ts";
 import { BrowserRunSessionLifecycle } from "../internal/browser-session-lifecycle.ts";
 import { makeProtectedNativeTransport, ProtectedNativeSession } from "./native.ts";
 import {
@@ -50,6 +57,7 @@ const protectedBindingLayer = (options: { readonly browser: Pick<BrowserRun, "fe
   Layer.effect(BrowserRunProtectedBinding)(
     Effect.gen(function* () {
       const lifecycle = yield* BrowserRunSessionLifecycle;
+      const binding = yield* BrowserRunBinding;
       const crypto = yield* Crypto.Crypto;
 
       const open = Effect.fn("BrowserRunProtectedTransport.open")(function* (
@@ -73,8 +81,8 @@ const protectedBindingLayer = (options: { readonly browser: Pick<BrowserRun, "fe
         let driver: ProtectedBrowserTransport | undefined;
         let invalid = false;
         // SDK acquisition may finish after interruption. Its late-reply callback must await cleanup,
-        // using this pass's clock rather than starting an Effect runtime with default services.
-        const runCleanup = Effect.runPromiseWith(Context.make(Clock.Clock, yield* Clock.Clock));
+        // retaining this pass's clock and private reporting scope.
+        const runCleanup = Effect.runPromiseWith(yield* Effect.context<never>());
 
         const terminate = Effect.gen(function* () {
           invalid = true;
@@ -83,11 +91,19 @@ const protectedBindingLayer = (options: { readonly browser: Pick<BrowserRun, "fe
 
           const cleanup = yield* lifecycle.close(sessionId).pipe(
             Effect.as("confirmed" as const),
-            Effect.catchCause(() => Effect.succeed("unconfirmed" as const)),
+            Effect.catchCause((cause) =>
+              reportBrowserCause("protected.close", cause).pipe(Effect.as("unconfirmed" as const)),
+            ),
             Effect.interruptible,
             Effect.timeoutOrElse({
               duration: "10 seconds",
-              orElse: () => Effect.succeed("unconfirmed" as const),
+              orElse: () =>
+                reportBrowserCause(
+                  "protected.close",
+                  Cause.fail(
+                    new BrowserRunFailure({ operation: "protected.close", reason: "timeout" }),
+                  ),
+                ).pipe(Effect.as("unconfirmed" as const)),
             }),
           );
 
@@ -96,9 +112,21 @@ const protectedBindingLayer = (options: { readonly browser: Pick<BrowserRun, "fe
 
           if (connected !== undefined)
             yield* Effect.promise(() => connected.disconnect()).pipe(
-              Effect.catchCause(() => Effect.void),
+              Effect.catchCause((cause) => reportBrowserCause("protected.disconnect", cause)),
               Effect.interruptible,
-              Effect.timeoutOrElse({ duration: "1 second", orElse: () => Effect.void }),
+              Effect.timeoutOrElse({
+                duration: "1 second",
+                orElse: () =>
+                  reportBrowserCause(
+                    "protected.disconnect",
+                    Cause.fail(
+                      new BrowserRunFailure({
+                        operation: "protected.disconnect",
+                        reason: "timeout",
+                      }),
+                    ),
+                  ),
+              }),
             );
 
           return cleanup;
@@ -106,144 +134,138 @@ const protectedBindingLayer = (options: { readonly browser: Pick<BrowserRun, "fe
 
         const close = yield* Effect.cached(terminate);
 
-        yield* Effect.addFinalizer(() =>
-          detached
-            ? Effect.void
-            : close.pipe(
-                Effect.flatMap((state) =>
-                  state === "confirmed"
-                    ? Effect.void
-                    : Effect.logWarning("Protected browser exact-session closure unconfirmed"),
-                ),
-              ),
-        );
+        yield* Effect.addFinalizer(() => (detached ? Effect.void : close));
+        let stage = identity === undefined ? "protected.acquire" : "protected.connect";
 
         const acquired = yield* Effect.tryPromise({
           try: async (signal) => {
-            let recordingDisabled = false;
-
-            const binding = {
-              fetch: async (input: RequestInfo | URL, init?: RequestInit) => {
-                const request = new Request(input, init);
-                const url = new URL(request.url);
-
-                if (url.pathname === "/v1/devtools/browser" && request.method === "POST") {
-                  url.searchParams.set("recording", "false");
-                  recordingDisabled = url.searchParams.get("recording") === "false";
+            try {
+              sessionId =
+                identity === undefined
+                  ? Redacted.make(
+                      await binding.acquire(
+                        Math.min(600_000, Math.max(10_000, policy.maxElapsedMillis)),
+                        "protected.acquire",
+                      ),
+                    )
+                  : identity.sessionId;
+              if (signal.aborted || invalid) {
+                await runCleanup(terminate);
+                throw new ProtectedTransportError({ reason: "stale-reference" });
+              }
+              // Resume only a host-persisted exact page. Never open a replacement page or context.
+              stage = "protected.connect";
+              browser = await binding.connect(Redacted.value(sessionId), stage);
+              if (signal.aborted || invalid) {
+                await runCleanup(terminate);
+                throw new ProtectedTransportError({ reason: "stale-reference" });
+              }
+              let page: Page;
 
-                  return options.browser.fetch(new Request(url, request));
-                }
+              if (identity === undefined) {
+                stage = "protected.context";
+                const context = await browser.createBrowserContext();
 
-                return options.browser.fetch(request);
-              },
-            };
-
-            const acquired =
-              identity === undefined
-                ? await puppeteer.acquire(binding, {
-                    recording: false,
-                    // Provider inactivity timeout, independent of the finite total pass deadline.
-                    keep_alive: Math.min(600_000, Math.max(10_000, policy.maxElapsedMillis)),
-                  })
-                : { sessionId: Redacted.value(identity.sessionId) };
-
-            sessionId = Redacted.make(
-              Schema.decodeSync(Schema.String.check(Schema.isUUID()))(acquired.sessionId),
-            );
-            if ((identity === undefined && !recordingDisabled) || signal.aborted || invalid) {
-              await runCleanup(terminate);
-              throw new ProtectedTransportError({ reason: "stale-reference" });
-            }
-            // Resume only a host-persisted exact page. Never open a replacement page or context.
-            browser = await puppeteer.connect(options.browser, acquired.sessionId);
-            if (signal.aborted || invalid) {
-              await runCleanup(terminate);
-              throw new ProtectedTransportError({ reason: "stale-reference" });
-            }
-            let page: Page;
+                stage = "protected.page";
+                page = await context.newPage();
+              } else {
+                stage = "protected.resume";
 
-            if (identity === undefined) {
-              const context = await browser.createBrowserContext();
+                const context = browser
+                  .browserContexts()
+                  .find((candidate) => candidate.id === Redacted.value(identity.contextId));
 
-              page = await context.newPage();
-            } else {
-              const context = browser
-                .browserContexts()
-                .find((candidate) => candidate.id === Redacted.value(identity.contextId));
+                if (context === undefined)
+                  throw new ProtectedTransportError({ reason: "stale-reference" });
+                const pages = await context.pages();
+                let found: Page | undefined;
 
-              if (context === undefined)
-                throw new ProtectedTransportError({ reason: "stale-reference" });
-              const pages = await context.pages();
-              let found: Page | undefined;
+                for (const candidate of pages) {
+                  const client = await candidate.createCDPSession();
+                  const info = await client.send("Target.getTargetInfo");
 
-              for (const candidate of pages) {
-                const client = await candidate.createCDPSession();
-                const info = await client.send("Target.getTargetInfo");
-
-                await client.detach();
-                if (info.targetInfo.targetId === Redacted.value(identity.targetId))
-                  found = candidate;
+                  await client.detach();
+                  if (info.targetInfo.targetId === Redacted.value(identity.targetId))
+                    found = candidate;
+                }
+                if (found === undefined || pages.length !== 1)
+                  throw new ProtectedTransportError({ reason: "stale-reference" });
+                page = found;
               }
-              if (found === undefined || pages.length !== 1)
+              stage = "protected.control";
+              control = await page.createCDPSession();
+              const info = await control.send("Target.getTargetInfo");
+
+              stage = "protected.identity";
+              providerIdentity = Schema.decodeSync(ProtectedProviderIdentity)({
+                sessionId,
+                contextId: Redacted.make(page.browserContext().id ?? ""),
+                targetId: Redacted.make(info.targetInfo.targetId),
+              });
+
+              stage = "protected.interception";
+              await page.setBypassServiceWorker(true);
+              await page.setRequestInterception(true);
+              page.on("request", (request) => {
+                let allowed = policy.network._tag === "Unrestricted";
+
+                try {
+                  const url = new URL(request.url());
+
+                  allowed ||=
+                    policy.network._tag === "ExactHosts" &&
+                    url.protocol === "https:" &&
+                    !url.username &&
+                    !url.password &&
+                    policy.network.allowedHosts.includes(url.host);
+                } catch {
+                  /* Refuse malformed destinations. */
+                }
+                void (
+                  allowed && !invalid ? request.continue() : request.abort("blockedbyclient")
+                ).catch(async (cause) => {
+                  invalid = true;
+                  driver?.invalidate();
+                  await runCleanup(reportBrowserCause("protected.interception", Cause.fail(cause)));
+                });
+              });
+              if (signal.aborted || invalid) {
+                await runCleanup(terminate);
                 throw new ProtectedTransportError({ reason: "stale-reference" });
-              page = found;
-            }
-            control = await page.createCDPSession();
-            const info = await control.send("Target.getTargetInfo");
-
-            providerIdentity = Schema.decodeSync(ProtectedProviderIdentity)({
-              sessionId,
-              contextId: Redacted.make(page.browserContext().id ?? ""),
-              targetId: Redacted.make(info.targetInfo.targetId),
-            });
-
-            await page.setBypassServiceWorker(true);
-            await page.setRequestInterception(true);
-            page.on("request", (request) => {
-              let allowed = policy.network._tag === "Unrestricted";
-
-              try {
-                const url = new URL(request.url());
-
-                allowed ||=
-                  policy.network._tag === "ExactHosts" &&
-                  url.protocol === "https:" &&
-                  !url.username &&
-                  !url.password &&
-                  policy.network.allowedHosts.includes(url.host);
-              } catch {
-                /* Refuse malformed destinations. */
               }
-              void (
-                allowed && !invalid ? request.continue() : request.abort("blockedbyclient")
-              ).catch(() => {
-                invalid = true;
-                driver?.invalidate();
+
+              return ProtectedNativeSession.of({
+                browser,
+                page,
+                close,
+                release: Effect.suspend(() => (detached ? Effect.void : close.pipe(Effect.asVoid))),
               });
-            });
-            if (signal.aborted || invalid) {
-              await runCleanup(terminate);
-              throw new ProtectedTransportError({ reason: "stale-reference" });
+            } catch (cause) {
+              if (signal.aborted && !(cause instanceof ProtectedTransportError))
+                await runCleanup(reportBrowserCause(stage, Cause.fail(cause)));
+              throw cause;
             }
-
-            return ProtectedNativeSession.of({
-              browser,
-              page,
-              close,
-              release: Effect.suspend(() => (detached ? Effect.void : close.pipe(Effect.asVoid))),
-            });
           },
-          catch: failure,
+          catch: (cause) => browserFailure(stage, cause),
         }).pipe(
           Effect.timeoutOrElse({
             duration: Math.min(policy.maxElapsedMillis, 30_000),
             orElse: () =>
-              Effect.fail(new ProtectedBrowserError({ ...failure(), reason: "timeout" })),
+              Effect.fail(new BrowserRunFailure({ operation: stage, reason: "timeout" })),
           }),
           Effect.catch((error) =>
-            close.pipe(
+            reportBrowserCause(stage, Cause.fail(error)).pipe(
+              Effect.andThen(close),
               Effect.flatMap((cleanup) =>
-                Effect.fail(new ProtectedBrowserError({ ...error, cleanup })),
+                Effect.fail(
+                  reportedBrowserError(
+                    new ProtectedBrowserError({
+                      ...failure(),
+                      reason: error.reason === "timeout" ? "timeout" : "provider",
+                      cleanup,
+                    }),
+                  ),
+                ),
               ),
             ),
           ),
@@ -271,12 +293,20 @@ const protectedBindingLayer = (options: { readonly browser: Pick<BrowserRun, "fe
 
                 return await Reflect.apply(send, control, [method, parameters]);
               },
-              catch: failure,
+              catch: (cause) => browserFailure("protected.command", cause),
             }).pipe(
               Effect.timeoutOrElse({
                 duration: "10 seconds",
-                orElse: () => Effect.fail(failure()),
+                orElse: () =>
+                  Effect.fail(
+                    new BrowserRunFailure({ operation: "protected.command", reason: "timeout" }),
+                  ),
               }),
+              Effect.catch((error) =>
+                reportBrowserCause("protected.command", Cause.fail(error)).pipe(
+                  Effect.andThen(Effect.fail(reportedBrowserError(failure()))),
+                ),
+              ),
             ),
           detach: Effect.tryPromise({
             try: async () => {
@@ -286,16 +316,27 @@ const protectedBindingLayer = (options: { readonly browser: Pick<BrowserRun, "fe
               detached = true;
               driver?.invalidate();
             },
-            catch: failure,
+            catch: (cause) => browserFailure("protected.detach", cause),
           }).pipe(
-            Effect.timeoutOrElse({ duration: "10 seconds", orElse: () => Effect.fail(failure()) }),
+            Effect.timeoutOrElse({
+              duration: "10 seconds",
+              orElse: () =>
+                Effect.fail(
+                  new BrowserRunFailure({ operation: "protected.detach", reason: "timeout" }),
+                ),
+            }),
+            Effect.catch((error) =>
+              reportBrowserCause("protected.detach", Cause.fail(error)).pipe(
+                Effect.andThen(Effect.fail(reportedBrowserError(failure()))),
+              ),
+            ),
           ),
         };
       }, Effect.withTracerEnabled(false));
 
       return { open };
     }),
-  );
+  ).pipe(Layer.provide(BrowserRunBinding.layer(options.browser)));
 
 /** One binding implementation serves scoped tools and host-managed protected handoffs. */
 export const browserRunProtectedBindingLayer = (options: {