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

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: {

package/src/protected-browser/host.ts

@@ -1,4 +1,5 @@
 import {
+  Cause,
   Clock,
   Context,
   Crypto,
@@ -25,6 +26,11 @@ import {
   BrowserRunLiveViewRequest,
   BrowserRunLiveViewResult,
 } from "../InteractiveBrowser.ts";
+import {
+  inheritBrowserReport,
+  reportBrowserCause,
+  reportedBrowserError,
+} from "../internal/browser-failure.ts";
 import { BrowserRunSessionLifecycle } from "../internal/browser-session-lifecycle.ts";
 import { BrowserRunProtectedBinding, ProtectedProviderIdentity } from "./binding.ts";
 import { BrowserRunProtectedTransport, makeProtectedBrowserPolicy } from "./policy.ts";
@@ -184,7 +190,11 @@ export const browserRunProtectedHostLayer = () =>
           const raw = yield* provider.command("Cloudflare.getHandoffState", {});
 
           const result = yield* Schema.decodeUnknownEffect(HandoffState)(raw).pipe(
-            Effect.mapError(() => failure("provider")),
+            Effect.catch((error) =>
+              reportBrowserCause("protected.host.decode", Cause.fail(error)).pipe(
+                Effect.andThen(Effect.fail(reportedBrowserError(failure("provider")))),
+              ),
+            ),
           );
 
           if (
@@ -243,20 +253,25 @@ export const browserRunProtectedHostLayer = () =>
                   })
                   .pipe(
                     Effect.flatMap(Schema.decodeUnknownEffect(Handoff)),
-                    Effect.catch(() =>
-                      state.handle.close.pipe(
-                        Effect.flatMap((cleanup) =>
-                          Effect.fail(
-                            new ProtectedBrowserError({
-                              reason: "outcome-unknown",
-                              dispatch: "possibly-dispatched",
-                              milestone: suspended.milestone,
-                              observation: "closed",
-                              cleanup,
-                            }),
+                    Effect.catchCause((cause) =>
+                      Cause.hasInterruptsOnly(cause)
+                        ? Effect.interrupt
+                        : reportBrowserCause("protected.handoff", cause).pipe(
+                            Effect.andThen(state.handle.close),
+                            Effect.flatMap((cleanup) =>
+                              Effect.fail(
+                                reportedBrowserError(
+                                  new ProtectedBrowserError({
+                                    reason: "outcome-unknown",
+                                    dispatch: "possibly-dispatched",
+                                    milestone: suspended.milestone,
+                                    observation: "closed",
+                                    cleanup,
+                                  }),
+                                ),
+                              ),
+                            ),
                           ),
-                        ),
-                      ),
                     ),
                     Effect.onInterrupt(() => state.handle.close),
                   );
@@ -287,12 +302,22 @@ export const browserRunProtectedHostLayer = () =>
                 });
 
                 const result = yield* Schema.decodeUnknownEffect(LiveView)(raw).pipe(
-                  Effect.mapError(() => failure("provider")),
+                  Effect.catch((error) =>
+                    reportBrowserCause("protected.host.decode", Cause.fail(error)).pipe(
+                      Effect.andThen(Effect.fail(reportedBrowserError(failure("provider")))),
+                    ),
+                  ),
                 );
 
                 return yield* Schema.decodeEffect(BrowserRunLiveViewResult)({
                   devtoolsFrontendUrl: Redacted.make(result.devtoolsFrontendUrl),
-                }).pipe(Effect.mapError(() => failure("provider")));
+                }).pipe(
+                  Effect.catch((error) =>
+                    reportBrowserCause("protected.host.decode", Cause.fail(error)).pipe(
+                      Effect.andThen(Effect.fail(reportedBrowserError(failure("provider")))),
+                    ),
+                  ),
+                );
               }),
             ),
           getHandoffState: control(getHandoffState),
@@ -301,11 +326,15 @@ export const browserRunProtectedHostLayer = () =>
               if ((yield* getHandoffState).active) return yield* failure("busy");
 
               const context = yield* provider.driver.context.pipe(
-                Effect.mapError((error) => failure(error.reason)),
+                Effect.mapError((error) => inheritBrowserReport(error, failure(error.reason))),
               );
 
               return yield* Schema.decodeEffect(CredentialOrigin)(context.topOrigin).pipe(
-                Effect.mapError(() => failure("provider")),
+                Effect.catch((error) =>
+                  reportBrowserCause("protected.host.decode", Cause.fail(error)).pipe(
+                    Effect.andThen(Effect.fail(reportedBrowserError(failure("provider")))),
+                  ),
+                ),
               );
             }),
           ),
@@ -337,7 +366,11 @@ export const browserRunProtectedHostLayer = () =>
         closeSession: (id: Redacted.Redacted<string>) =>
           lifecycle.close(id).pipe(
             Effect.as("confirmed" as const),
-            Effect.catchCause(() => Effect.succeed("unconfirmed" as const)),
+            Effect.catchCause((cause) =>
+              reportBrowserCause("protected.closeSession", cause).pipe(
+                Effect.as("unconfirmed" as const),
+              ),
+            ),
           ),
       };
     }),