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

package/src/InteractiveBrowser.ts

@@ -1,6 +1,6 @@
 /// <reference types="@cloudflare/workers-types" />
 
-import puppeteer, {
+import {
   type Browser,
   type BrowserContext,
   type CDPSession,
@@ -8,6 +8,7 @@ import puppeteer, {
   type Page,
 } from "@cloudflare/puppeteer";
 import {
+  Cause,
   Context,
   Clock,
   Duration,
@@ -21,6 +22,8 @@ import {
 } from "effect";
 import {
   BrowserActionResult,
+  BrowserSelectFileRequest,
+  BrowserFileSelectionResult,
   BrowserScreenshotRequest,
   BrowserScrollRequest,
   BrowserNavigationResult,
@@ -43,6 +46,13 @@ import {
 import { PageScreenshotResult } from "effect-agent/page-screenshot";
 import { SandboxImplementation } from "effect-agent/sandbox";
 
+import { BrowserRunBinding } from "./internal/browser-binding.ts";
+import {
+  BrowserRunFailure,
+  reportBrowserCause,
+  reportedBrowserError,
+} from "./internal/browser-failure.ts";
+import { makeFileSelection } from "./internal/browser-file-selection.ts";
 import {
   BrowserRunSessionLifecycle,
   type BrowserRunLifecycleOptions,
@@ -328,6 +338,11 @@ export interface BrowserRunInteractivePage {
     signal: AbortSignal,
     onDispatch: () => void,
   ) => Promise<unknown>;
+  readonly selectFile: (
+    request: BrowserSelectFileRequest,
+    signal: AbortSignal,
+    onDispatch: () => void,
+  ) => Promise<unknown>;
   readonly screenshot: (fullPage: boolean) => Promise<unknown>;
   readonly scroll: (deltaX: number, deltaY: number) => Promise<void>;
   readonly setViewport: (viewport: BrowserRunViewport) => Promise<void>;
@@ -371,22 +386,26 @@ export class BrowserRunInteractiveBinding extends Context.Service<
     return Layer.effect(BrowserRunInteractiveBinding)(
       Effect.gen(function* () {
         const lifecycle = yield* BrowserRunSessionLifecycle;
+        const binding = yield* BrowserRunBinding;
 
         const viewport =
           options.viewport === undefined ? undefined : yield* decodeViewport(options.viewport);
 
         return {
           acquire: async (keepAliveMillis: number) =>
-            (await puppeteer.acquire(options.browser, { keep_alive: keepAliveMillis })).sessionId,
+            binding.acquire(keepAliveMillis, "interactive.acquire"),
           connect: async (sessionId: string) =>
-            makeProductionBrowser(await puppeteer.connect(options.browser, sessionId), viewport),
+            makeProductionBrowser(
+              await binding.connect(sessionId, "interactive.connect"),
+              viewport,
+            ),
           closeSession: (sessionId: Redacted.Redacted<string>) =>
             lifecycle
               .close(sessionId)
               .pipe(Effect.mapError((cause) => actionError("close", cause))),
         };
       }),
-    );
+    ).pipe(Layer.provide(BrowserRunBinding.layer(options.browser)));
   }
 }
 
@@ -706,6 +725,7 @@ const runObservedPageAction = async (
   signal: AbortSignal,
   onDispatch: () => void,
   action: (element: NonNullable<Awaited<ReturnType<Page["$"]>>>) => Promise<void>,
+  validate?: (element: NonNullable<Awaited<ReturnType<Page["$"]>>>) => Promise<boolean>,
 ): Promise<unknown> => {
   if (signal.aborted) throw new BrowserRunActionUndispatched(0);
 
@@ -737,6 +757,8 @@ const runObservedPageAction = async (
 
   signal.addEventListener("abort", onAbort, { once: true });
   try {
+    if (validate !== undefined && !(await validate(matches[0])))
+      throw new BrowserRunActionUndispatched(1);
     tracker = makeActionRequestTracker(page, signal);
     // No await between the final cancellation fence and SDK dispatch. Once
     // dispatched, interruption is uncertain, even if the SDK later resolves.
@@ -761,10 +783,18 @@ const runObservedPageAction = async (
 };
 
 const makeProductionPage = (page: Page): BrowserRunInteractivePage => {
+  const prepareFileSelection = makeFileSelection(page);
   const listeners = new Map<BrowserRunInteractiveRequestListener, (request: HTTPRequest) => void>();
 
   return {
-    close: () => page.close(),
+    close: async () => {
+      if (!page.browser().isConnected()) return;
+      try {
+        await page.close();
+      } catch (cause) {
+        if (!isRemoteClosure(cause)) throw cause;
+      }
+    },
     setBypassServiceWorker: (enabled) => page.setBypassServiceWorker(enabled),
     setRequestInterception: (enabled) => page.setRequestInterception(enabled),
     onRequest: (listener) => {
@@ -1087,6 +1117,22 @@ const makeProductionPage = (page: Page): BrowserRunInteractivePage => {
       ),
     click: (selector, signal, onDispatch) =>
       runObservedPageAction(page, selector, signal, onDispatch, (element) => element.click()),
+    selectFile: async (request, signal, onDispatch) => {
+      const selection = await prepareFileSelection(request, signal);
+
+      try {
+        return await runObservedPageAction(
+          page,
+          request.selector,
+          signal,
+          onDispatch,
+          selection.select,
+          selection.validate,
+        );
+      } finally {
+        await selection.close();
+      }
+    },
     // Puppeteer materializes the complete image before returning. The adapter
     // validates the 8 MiB Schema ceiling and pass limit immediately afterward.
     screenshot: (fullPage) => page.screenshot({ type: "png", fullPage }),
@@ -1116,7 +1162,14 @@ const makeProductionContext = (
 
     return makeProductionPage(page);
   },
-  close: () => context.close(),
+  close: async () => {
+    if (!context.browser().isConnected()) return;
+    try {
+      await context.close();
+    } catch (cause) {
+      if (!isRemoteClosure(cause)) throw cause;
+    }
+  },
 });
 
 const makeProductionBrowser = (
@@ -1124,7 +1177,15 @@ const makeProductionBrowser = (
   viewport?: BrowserRunViewport,
 ): BrowserRunInteractiveBrowser => ({
   createContext: async () => makeProductionContext(await browser.createBrowserContext(), viewport),
-  close: () => browser.close(),
+  // Exact-session termination may already have closed the provider transport.
+  close: async () => {
+    if (!browser.isConnected()) return;
+    try {
+      await browser.close();
+    } catch (cause) {
+      if (!isRemoteClosure(cause)) throw cause;
+    }
+  },
   sessionId: () => browser.sessionId(),
   isConnected: () => browser.isConnected(),
   onDisconnected: (listener) => {
@@ -1183,7 +1244,7 @@ const causeText = (cause: unknown): string => {
 };
 
 const isCapacityRefusal = (cause: unknown): boolean =>
-  /(^|\D)429(\D|$)|browser time limit|capacity|too many concurrent/i.test(causeText(cause));
+  cause instanceof BrowserRunFailure && cause.status === 429;
 
 const isRemoteClosure = (cause: unknown): boolean =>
   /target closed|browser.*closed|session.*closed|connection.*closed|not connected|websocket.*closed/i.test(
@@ -1242,6 +1303,8 @@ const hostAllowed = (policy: InteractiveBrowserPolicySnapshot, value: string): b
 const keepAliveMillis = (policy: InteractiveBrowserPolicySnapshot): number =>
   Math.max(MIN_KEEP_ALIVE_MILLIS, Math.min(MAX_KEEP_ALIVE_MILLIS, policy.maxElapsedMillis));
 
+class LateBrowserAcquisition extends Error {}
+
 const closeLateAcquisition = async <A>(
   signal: AbortSignal,
   acquire: () => Promise<A>,
@@ -1256,22 +1319,25 @@ const closeLateAcquisition = async <A>(
   try {
     await close(acquired);
   } catch {
-    // No caller remains to observe a late cleanup failure, and provider details
-    // must not escape through an unhandled rejection.
+    // The captured runtime reports cleanup failures before this callback absorbs rejection.
   }
-  throw new Error("The interrupted browser acquisition completed late");
+  throw new LateBrowserAcquisition("The interrupted browser acquisition completed late");
 };
 
 const closeWithWarning = (close: () => Promise<void>, warning: string): Effect.Effect<void> =>
   Effect.tryPromise({
     try: close,
-    catch: () => protocolError(warning),
+    catch: (cause) => protocolError(warning, cause),
   }).pipe(
     Effect.timeoutOrElse({
       duration: Duration.millis(CLEANUP_STEP_TIMEOUT_MILLIS),
       orElse: () => Effect.fail(protocolError(warning)),
     }),
-    Effect.catchCause(() => Effect.logWarning(warning)),
+    Effect.catchCause((cause) =>
+      reportBrowserCause("interactive.cleanup", cause).pipe(
+        Effect.andThen(Effect.logWarning(warning)),
+      ),
+    ),
   );
 
 const deadlineError = Effect.fn("BrowserRunInteractive.deadlineError")(function* (
@@ -1431,15 +1497,21 @@ const makeRequestListener =
 
     try {
       settlement = allowed ? request.continue() : request.abort();
-    } catch {
-      state.violation.value = protocolError("Resolving an intercepted browser request failed");
+    } catch (cause) {
+      state.violation.value = protocolError(
+        "Resolving an intercepted browser request failed",
+        cause,
+      );
 
       return;
     }
 
     const observed = settlement
-      .catch(() => {
-        state.violation.value = protocolError("Resolving an intercepted browser request failed");
+      .catch((cause) => {
+        state.violation.value = protocolError(
+          "Resolving an intercepted browser request failed",
+          cause,
+        );
       })
       .finally(() => {
         state.pendingRequests.delete(observed);
@@ -1490,7 +1562,7 @@ const makeHandle = Effect.fn("BrowserRunInteractive.makeHandle")(function* (
     );
 
   const observedAction = (
-    operation: "fill" | "click",
+    operation: "fill" | "click" | "select-file",
     evaluate: (signal: AbortSignal, onDispatch: () => void) => Promise<unknown>,
   ) =>
     Effect.suspend(() => {
@@ -1537,7 +1609,7 @@ const makeHandle = Effect.fn("BrowserRunInteractive.makeHandle")(function* (
   );
 
   const logActionObservation = (
-    operation: "fill" | "click",
+    operation: "fill" | "click" | "select-file",
     observation: typeof ActionObservation.Type,
   ) =>
     Effect.logInfo("Browser interactive action observed").pipe(
@@ -1764,6 +1836,29 @@ const makeHandle = Effect.fn("BrowserRunInteractive.makeHandle")(function* (
           return yield* decodeActionResult(page, policy);
         }),
       ),
+    selectFile: (request) =>
+      Schema.decodeEffect(BrowserSelectFileRequest)(request).pipe(
+        Effect.mapError(() => policyError("The browser file selection request is malformed")),
+        Effect.flatMap((decoded) =>
+          run(
+            Effect.gen(function* () {
+              const observation = yield* observedAction("select-file", (signal, onDispatch) =>
+                page.selectFile(decoded, signal, onDispatch),
+              ).pipe(Effect.flatMap(decodeActionObservation));
+
+              yield* logActionObservation("select-file", observation);
+              const result = yield* decodeActionResult(page, policy);
+
+              return BrowserFileSelectionResult.make({
+                url: result.url,
+                fileName: decoded.fileName,
+                mediaType: decoded.mediaType,
+                size: decoded.bytes.length,
+              });
+            }),
+          ),
+        ),
+      ),
     screenshot: (request) =>
       Schema.decodeEffect(BrowserScreenshotRequest)(request).pipe(
         Effect.mapError(() => policyError("The browser screenshot request is malformed")),
@@ -1872,10 +1967,31 @@ const cdpCommand = <A>(
 ): Effect.Effect<A, InteractiveBrowserError> =>
   Effect.scoped(
     Effect.gen(function* () {
+      const cleanupContext = yield* Effect.context<never>();
+
       const cdp = yield* Effect.acquireRelease(
         Effect.tryPromise({
-          try: (signal) =>
-            closeLateAcquisition(signal, page.createCdpSession, (acquired) => acquired.detach()),
+          try: (signal) => {
+            const pending = closeLateAcquisition(signal, page.createCdpSession, (acquired) =>
+              Effect.runPromiseWith(cleanupContext)(
+                Effect.tryPromise({
+                  try: () => acquired.detach(),
+                  catch: (cause) => actionError("close", cause),
+                }).pipe(
+                  Effect.tapCause((cause) => reportBrowserCause("interactive.lateDetach", cause)),
+                ),
+              ),
+            );
+
+            void pending.then(undefined, (cause) => {
+              if (signal.aborted && !(cause instanceof LateBrowserAcquisition))
+                return Effect.runPromiseWith(cleanupContext)(
+                  reportBrowserCause("interactive.connect", Cause.fail(cause)),
+                );
+            });
+
+            return pending;
+          },
           catch: (cause) =>
             state.disconnected.value || isRemoteClosure(cause)
               ? expiredError()
@@ -1898,7 +2014,11 @@ const cdpCommand = <A>(
       });
 
       return yield* Schema.decodeUnknownEffect(output)(raw).pipe(
-        Effect.mapError(() => protocolError(malformedMessage)),
+        Effect.catch((error) =>
+          reportBrowserCause("interactive.command.decode", Cause.fail(error)).pipe(
+            Effect.andThen(Effect.fail(reportedBrowserError(protocolError(malformedMessage)))),
+          ),
+        ),
       );
     }),
   );
@@ -1930,14 +2050,25 @@ const makeHostService = (
     // Remote termination is authoritative. Local cleanup must not veto it or extend the deadline.
     yield* runTeardown(entries).pipe(
       Effect.flatMap((failures) =>
-        Effect.forEach(failures, (failure) => Effect.logWarning(failure.warning), {
-          discard: true,
-        }),
+        Effect.forEach(
+          failures,
+          (failure) =>
+            reportBrowserCause("interactive.cleanup", Cause.fail(failure.error)).pipe(
+              Effect.andThen(Effect.logWarning(failure.warning)),
+            ),
+          {
+            discard: true,
+          },
+        ),
       ),
       Effect.interruptible,
       Effect.timeout(`${remaining} millis`),
-      Effect.catchCause(() =>
-        Effect.logWarning("Local browser teardown incomplete after confirmed termination"),
+      Effect.catchCause((cause) =>
+        reportBrowserCause("interactive.cleanup", cause).pipe(
+          Effect.andThen(
+            Effect.logWarning("Local browser teardown incomplete after confirmed termination"),
+          ),
+        ),
       ),
     );
   });
@@ -1947,10 +2078,10 @@ const makeHostService = (
   ) {
     const sessionId = yield* Effect.try({
       try: browser.sessionId,
-      catch: () => actionError("close"),
+      catch: (cause) => actionError("close", cause),
     }).pipe(
       Effect.flatMap(Schema.decodeUnknownEffect(BrowserRunSessionId)),
-      Effect.mapError(() => actionError("close")),
+      Effect.mapError((cause) => actionError("close", cause)),
       Effect.onError(() =>
         closeWithWarning(browser.close, "Closing an unidentified browser failed"),
       ),
@@ -1967,8 +2098,26 @@ const makeHostService = (
     const scope = yield* Scope.Scope;
     const fixedPolicy = yield* snapshotPolicy(policy);
     const startedAt = yield* Effect.clockWith((clock) => clock.currentTimeMillis);
-    // Late SDK replies outlive the opening fiber; cleanup retains this pass's clock.
-    const runCleanup = Effect.runPromiseWith(Context.make(Clock.Clock, yield* Clock.Clock));
+
+    // Late SDK replies retain this pass's clock and private reporting scope.
+    const runCleanup = <A, E>(effect: Effect.Effect<A, E>) =>
+      Effect.runPromiseWith(cleanupContext)(
+        effect.pipe(
+          Effect.tapCause((cause) => reportBrowserCause("interactive.lateCleanup", cause)),
+        ),
+      );
+
+    const cleanupContext = yield* Effect.context<never>();
+
+    const observeLate = <A>(signal: AbortSignal, pending: Promise<A>): Promise<A> => {
+      // Observe the original Promise without creating another rejected continuation.
+      void pending.then(undefined, (cause) => {
+        if (signal.aborted && !(cause instanceof LateBrowserAcquisition))
+          return runCleanup(reportBrowserCause("interactive.acquire", Cause.fail(cause)));
+      });
+
+      return pending;
+    };
 
     const state: HandleState = {
       closed: { value: false },
@@ -1988,22 +2137,31 @@ const makeHostService = (
       Effect.suspend(() =>
         lifecycle.managedTeardownInstalled
           ? Effect.void
-          : entry.close.pipe(Effect.catchCause(() => Effect.logWarning(entry.warning))),
+          : entry.close.pipe(
+              Effect.catchCause((cause) =>
+                reportBrowserCause("interactive.cleanup", cause).pipe(
+                  Effect.andThen(Effect.logWarning(entry.warning)),
+                ),
+              ),
+            ),
       );
 
     const sessionIdValue = yield* Effect.acquireRelease(
       withinDeadline(
         Effect.tryPromise({
           try: (signal) =>
-            closeLateAcquisition(
+            observeLate(
               signal,
-              () => binding.acquire(keepAliveMillis(fixedPolicy)),
-              (id) =>
-                runCleanup(
-                  Schema.decodeUnknownEffect(BrowserRunSessionId)(id).pipe(
-                    Effect.flatMap((value) => terminate(Redacted.make(value), [])),
+              closeLateAcquisition(
+                signal,
+                () => binding.acquire(keepAliveMillis(fixedPolicy)),
+                (id) =>
+                  runCleanup(
+                    Schema.decodeUnknownEffect(BrowserRunSessionId)(id).pipe(
+                      Effect.flatMap((value) => terminate(Redacted.make(value), [])),
+                    ),
                   ),
-                ),
+              ),
             ),
           catch: (cause) =>
             isCapacityRefusal(cause)
@@ -2029,7 +2187,11 @@ const makeHostService = (
           return lifecycle.managedTeardownInstalled
             ? Effect.void
             : terminate(Redacted.make(id), []).pipe(
-                Effect.catch(() => Effect.logWarning("Whole-browser cleanup remains unconfirmed")),
+                Effect.catchCause((cause) =>
+                  reportBrowserCause("interactive.close", cause).pipe(
+                    Effect.andThen(Effect.logWarning("Whole-browser cleanup remains unconfirmed")),
+                  ),
+                ),
               );
         }),
       { interruptible: true },
@@ -2045,10 +2207,13 @@ const makeHostService = (
           withinDeadline(
             Effect.tryPromise({
               try: (signal) =>
-                closeLateAcquisition(
+                observeLate(
                   signal,
-                  () => binding.connect(sessionIdValue),
-                  (acquired) => runCleanup(closeAcquired(acquired)),
+                  closeLateAcquisition(
+                    signal,
+                    () => binding.connect(sessionIdValue),
+                    (acquired) => runCleanup(closeAcquired(acquired)),
+                  ),
                 ),
               catch: (cause) =>
                 protocolError("Connecting to the Browser Run session failed", cause),
@@ -2105,7 +2270,17 @@ const makeHostService = (
           withinDeadline(
             Effect.tryPromise({
               try: (signal) =>
-                closeLateAcquisition(signal, browser.createContext, (acquired) => acquired.close()),
+                observeLate(
+                  signal,
+                  closeLateAcquisition(signal, browser.createContext, (acquired) =>
+                    runCleanup(
+                      Effect.tryPromise({
+                        try: () => acquired.close(),
+                        catch: (cause) => actionError("close", cause),
+                      }),
+                    ),
+                  ),
+                ),
               catch: (cause) =>
                 state.disconnected.value || isRemoteClosure(cause)
                   ? expiredError()
@@ -2127,7 +2302,17 @@ const makeHostService = (
           withinDeadline(
             Effect.tryPromise({
               try: (signal) =>
-                closeLateAcquisition(signal, context.newPage, (acquired) => acquired.close()),
+                observeLate(
+                  signal,
+                  closeLateAcquisition(signal, context.newPage, (acquired) =>
+                    runCleanup(
+                      Effect.tryPromise({
+                        try: () => acquired.close(),
+                        catch: (cause) => actionError("close", cause),
+                      }),
+                    ),
+                  ),
+                ),
               catch: (cause) =>
                 state.disconnected.value || isRemoteClosure(cause)
                   ? expiredError()
@@ -2193,7 +2378,12 @@ const makeHostService = (
 
         const teardown = yield* Effect.uninterruptible(
           Effect.gen(function* () {
-            const cached = yield* Effect.cached(terminate(Redacted.make(sessionIdValue), closers));
+            const cached = yield* Effect.cached(
+              terminate(Redacted.make(sessionIdValue), closers).pipe(
+                Effect.tapCause((cause) => reportBrowserCause("interactive.close", cause)),
+                Effect.mapError(reportedBrowserError),
+              ),
+            );
 
             lifecycle.managedTeardownInstalled = true;
             yield* Effect.addFinalizer(() =>
@@ -2203,8 +2393,12 @@ const makeHostService = (
                   state.disconnected.value = true;
                 }).pipe(
                   Effect.andThen(cached),
-                  Effect.catch(() =>
-                    Effect.logWarning("Whole-browser cleanup remains unconfirmed"),
+                  Effect.catchCause((cause) =>
+                    reportBrowserCause("interactive.close", cause).pipe(
+                      Effect.andThen(
+                        Effect.logWarning("Whole-browser cleanup remains unconfirmed"),
+                      ),
+                    ),
                   ),
                 ),
               ),

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);
+        }
+      },
+    });
+  }
+}