@effect-agent/platform-cloudflare 0.1.0-beta.88 → 0.1.0-beta.89

package/src/protected-browser/binding.ts

@@ -1,5 +1,5 @@
 /// <reference types="@cloudflare/workers-types" />
-import puppeteer, { type Browser } from "@cloudflare/puppeteer";
+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 InteractiveBrowserPolicy } from "effect-agent/interactive-browser";
 import { ProtectedBrowserError } from "effect-agent/protected-browser";
@@ -12,22 +12,50 @@ import {
   type ProtectedBrowserTransport,
 } from "./policy.ts";
 
+/** Host-private exact page identity; never include it in model-visible results. */
+export const ProtectedProviderIdentity = Schema.Struct({
+  sessionId: Schema.Redacted(Schema.String.check(Schema.isUUID())),
+  contextId: Schema.Redacted(Schema.NonEmptyString.check(Schema.isMaxLength(256))),
+  targetId: Schema.Redacted(Schema.NonEmptyString.check(Schema.isMaxLength(256))),
+});
+
+export type ProtectedProviderIdentity = typeof ProtectedProviderIdentity.Type;
+
+export interface ProtectedProviderSession {
+  readonly identity: ProtectedProviderIdentity;
+  readonly driver: ProtectedBrowserTransport;
+  readonly command: (
+    method: "Cloudflare.getLiveView" | "Cloudflare.handoff" | "Cloudflare.getHandoffState",
+    parameters: Readonly<Record<string, string | number>>,
+  ) => Effect.Effect<unknown, ProtectedBrowserError>;
+  readonly detach: Effect.Effect<void, ProtectedBrowserError>;
+}
+
+export class BrowserRunProtectedBinding extends Context.Service<
+  BrowserRunProtectedBinding,
+  {
+    readonly open: (
+      policy: InteractiveBrowserPolicy,
+      identity?: ProtectedProviderIdentity,
+    ) => Effect.Effect<ProtectedProviderSession, ProtectedBrowserError, Scope.Scope>;
+  }
+>()("@effect-agent/platform-cloudflare/BrowserRunProtectedBinding") {}
+
 /**
  * Acquires through BROWSER with recording=false explicitly on the wire. The trusted provider's
  * documented opt-in semantics are the recording guarantee; no recording-status API exists.
  * Account operators remain trusted, and must not attach external observers to private passes.
  */
-export const browserRunProtectedBindingLayer = (options: {
-  readonly browser: Pick<BrowserRun, "fetch">;
-}) =>
-  Layer.effect(BrowserRunProtectedTransport)(
+const protectedBindingLayer = (options: { readonly browser: Pick<BrowserRun, "fetch"> }) =>
+  Layer.effect(BrowserRunProtectedBinding)(
     Effect.gen(function* () {
       const lifecycle = yield* BrowserRunSessionLifecycle;
       const crypto = yield* Crypto.Crypto;
 
       const open = Effect.fn("BrowserRunProtectedTransport.open")(function* (
         policy: InteractiveBrowserPolicy,
-      ): Effect.fn.Return<ProtectedBrowserTransport, ProtectedBrowserError, Scope.Scope> {
+        identity?: ProtectedProviderIdentity,
+      ): Effect.fn.Return<ProtectedProviderSession, ProtectedBrowserError, Scope.Scope> {
         const failure = () =>
           new ProtectedBrowserError({
             reason: "provider",
@@ -37,7 +65,10 @@ export const browserRunProtectedBindingLayer = (options: {
             cleanup: "unconfirmed",
           });
 
-        let sessionId: Redacted.Redacted<string> | undefined;
+        let sessionId: Redacted.Redacted<string> | undefined = identity?.sessionId;
+        let detached = false;
+        let control: CDPSession | undefined;
+        let providerIdentity: ProtectedProviderIdentity | undefined;
         let browser: Browser | undefined;
         let driver: ProtectedBrowserTransport | undefined;
         let invalid = false;
@@ -76,13 +107,15 @@ export const browserRunProtectedBindingLayer = (options: {
         const close = yield* Effect.cached(terminate);
 
         yield* Effect.addFinalizer(() =>
-          close.pipe(
-            Effect.flatMap((state) =>
-              state === "confirmed"
-                ? Effect.void
-                : Effect.logWarning("Protected browser exact-session closure unconfirmed"),
-            ),
-          ),
+          detached
+            ? Effect.void
+            : close.pipe(
+                Effect.flatMap((state) =>
+                  state === "confirmed"
+                    ? Effect.void
+                    : Effect.logWarning("Protected browser exact-session closure unconfirmed"),
+                ),
+              ),
         );
 
         const acquired = yield* Effect.tryPromise({
@@ -105,27 +138,64 @@ export const browserRunProtectedBindingLayer = (options: {
               },
             };
 
-            const acquired = 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)),
-            });
+            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 (!recordingDisabled || signal.aborted || invalid) {
+            if ((identity === undefined && !recordingDisabled) || signal.aborted || invalid) {
               await runCleanup(terminate);
               throw new ProtectedTransportError({ reason: "stale-reference" });
             }
-            // Initial attachment only. No recovery/reconnection path exists.
+            // 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" });
             }
-            const context = await browser.createBrowserContext();
-            const page = await context.newPage();
+            let page: Page;
+
+            if (identity === undefined) {
+              const context = await browser.createBrowserContext();
+
+              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;
+
+              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;
+              }
+              if (found === undefined || pages.length !== 1)
+                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);
@@ -156,7 +226,12 @@ export const browserRunProtectedBindingLayer = (options: {
               throw new ProtectedTransportError({ reason: "stale-reference" });
             }
 
-            return ProtectedNativeSession.of({ browser, page, close });
+            return ProtectedNativeSession.of({
+              browser,
+              page,
+              close,
+              release: Effect.suspend(() => (detached ? Effect.void : close.pipe(Effect.asVoid))),
+            });
           },
           catch: failure,
         }).pipe(
@@ -179,9 +254,60 @@ export const browserRunProtectedBindingLayer = (options: {
           Effect.provideService(Crypto.Crypto, crypto),
         );
 
-        return driver;
+        const exact = providerIdentity;
+
+        if (exact === undefined) return yield* failure();
+
+        return {
+          identity: exact,
+          driver,
+          command: (method, parameters) =>
+            Effect.tryPromise({
+              try: async () => {
+                if (invalid || detached || control === undefined) throw undefined;
+
+                // Cloudflare extends CDP with host-only methods absent from upstream ProtocolMapping.
+                const send = Reflect.get(control, "send");
+
+                return await Reflect.apply(send, control, [method, parameters]);
+              },
+              catch: failure,
+            }).pipe(
+              Effect.timeoutOrElse({
+                duration: "10 seconds",
+                orElse: () => Effect.fail(failure()),
+              }),
+            ),
+          detach: Effect.tryPromise({
+            try: async () => {
+              if (invalid || detached || browser === undefined) throw undefined;
+              // Stop this attachment before another controller can attach. The browser remains live.
+              await browser.disconnect();
+              detached = true;
+              driver?.invalidate();
+            },
+            catch: failure,
+          }).pipe(
+            Effect.timeoutOrElse({ duration: "10 seconds", orElse: () => Effect.fail(failure()) }),
+          ),
+        };
       }, Effect.withTracerEnabled(false));
 
       return { open };
     }),
   );
+
+/** One binding implementation serves scoped tools and host-managed protected handoffs. */
+export const browserRunProtectedBindingLayer = (options: {
+  readonly browser: Pick<BrowserRun, "fetch">;
+}) =>
+  Layer.effect(BrowserRunProtectedTransport)(
+    Effect.gen(function* () {
+      const binding = yield* BrowserRunProtectedBinding;
+
+      return {
+        open: (policy: InteractiveBrowserPolicy) =>
+          binding.open(policy).pipe(Effect.map((session) => session.driver)),
+      };
+    }),
+  ).pipe(Layer.provideMerge(protectedBindingLayer(options)));

package/src/protected-browser/host.ts

@@ -0,0 +1,328 @@
+import {
+  Clock,
+  Context,
+  Crypto,
+  Effect,
+  Layer,
+  Redacted,
+  Schema,
+  Semaphore,
+  type Scope,
+} from "effect";
+import { InteractiveBrowserPolicy } from "effect-agent/interactive-browser";
+import {
+  type BrowserCredentialAccess,
+  ProtectedBrowserCheckpoint,
+  ProtectedBrowserError,
+  type ProtectedBrowserHandle,
+  type ProtectedCleanup,
+} from "effect-agent/protected-browser";
+
+import {
+  BrowserRunHandoffRequest,
+  BrowserRunHandoffState,
+  BrowserRunLiveViewRequest,
+  BrowserRunLiveViewResult,
+} from "../InteractiveBrowser.ts";
+import { BrowserRunSessionLifecycle } from "../internal/browser-session-lifecycle.ts";
+import { BrowserRunProtectedBinding, ProtectedProviderIdentity } from "./binding.ts";
+import { BrowserRunProtectedTransport, makeProtectedBrowserPolicy } from "./policy.ts";
+
+/** Host-only receipt. Store atomically with the controller lease; never return it to a model. */
+export class BrowserRunProtectedCheckpoint extends Schema.Class<BrowserRunProtectedCheckpoint>(
+  "BrowserRunProtectedCheckpoint",
+)({
+  ...ProtectedProviderIdentity.fields,
+  protected: ProtectedBrowserCheckpoint,
+  handoffId: Schema.optionalKey(
+    Schema.Redacted(Schema.NonEmptyString.check(Schema.isMaxLength(1024))),
+  ),
+}) {}
+
+export interface BrowserRunProtectedSession {
+  readonly handle: ProtectedBrowserHandle;
+  readonly sessionId: Redacted.Redacted<string>;
+  /** Quiesce before publishing a durable human-control request. Persist before detaching. */
+  readonly suspend: Effect.Effect<BrowserRunProtectedCheckpoint, ProtectedBrowserError>;
+  /** Fences agent tools before dispatch. Persist the returned receipt before detaching. */
+  readonly handoff: (
+    request: BrowserRunHandoffRequest,
+  ) => Effect.Effect<BrowserRunProtectedCheckpoint, ProtectedBrowserError>;
+  /** Available only while human control is held; the host must authorize the specific human. */
+  readonly getLiveView: (
+    request: BrowserRunLiveViewRequest,
+  ) => Effect.Effect<BrowserRunLiveViewResult, ProtectedBrowserError>;
+  readonly getHandoffState: Effect.Effect<BrowserRunHandoffState, ProtectedBrowserError>;
+  /** Requires provider completion and a renewed observation grant. Tools must observe before acting. */
+  readonly returnControl: Effect.Effect<void, ProtectedBrowserError>;
+  /** Releases this attachment without terminating the remote browser. Only a committed handoff may detach. */
+  readonly detach: Effect.Effect<void, ProtectedBrowserError>;
+  readonly close: Effect.Effect<typeof ProtectedCleanup.Type>;
+}
+
+/**
+ * Host authority for one protected page. The consumer owns durable generation fencing, authorized
+ * human recipients, checkpoint integrity, vault exposure metadata, and expiry cleanup. Resume only
+ * the latest committed suspended receipt; it never replays browser mutations or creates a page.
+ * Hosted passes require Unrestricted network policy: attachment-local request interception
+ * cannot enforce an ExactHosts policy during detachment. Current credential grants still apply.
+ * Provider inactivity/session deadlines still apply while the host is detached.
+ */
+export class BrowserRunProtectedHost extends Context.Service<
+  BrowserRunProtectedHost,
+  {
+    readonly open: (
+      policy: InteractiveBrowserPolicy,
+    ) => Effect.Effect<
+      BrowserRunProtectedSession,
+      ProtectedBrowserError,
+      Scope.Scope | BrowserCredentialAccess
+    >;
+    readonly resume: (
+      checkpoint: BrowserRunProtectedCheckpoint,
+    ) => Effect.Effect<
+      BrowserRunProtectedSession,
+      ProtectedBrowserError,
+      Scope.Scope | BrowserCredentialAccess
+    >;
+    readonly closeSession: (
+      sessionId: Redacted.Redacted<string>,
+    ) => Effect.Effect<typeof ProtectedCleanup.Type>;
+  }
+>()("@effect-agent/platform-cloudflare/BrowserRunProtectedHost") {}
+
+const failure = (reason: ProtectedBrowserError["reason"]) =>
+  new ProtectedBrowserError({
+    reason,
+    dispatch: "not-dispatched",
+    milestone: "none",
+    observation: "protected",
+    cleanup: "not-requested",
+  });
+
+const Handoff = Schema.Struct({ handoffId: Schema.NonEmptyString.check(Schema.isMaxLength(1024)) });
+
+const HandoffState = Schema.Struct({
+  active: Schema.Boolean,
+  handoffId: Schema.optionalKey(Schema.NonEmptyString.check(Schema.isMaxLength(1024))),
+  durationMs: Schema.optionalKey(Schema.Natural),
+});
+
+const LiveView = Schema.Struct({ devtoolsFrontendUrl: Schema.String });
+
+/** Compose with browserRunProtectedBindingLayer and BrowserRunSessionLifecycle. */
+export const browserRunProtectedHostLayer = () =>
+  Layer.effect(BrowserRunProtectedHost)(
+    Effect.gen(function* () {
+      const binding = yield* BrowserRunProtectedBinding;
+      const lifecycle = yield* BrowserRunSessionLifecycle;
+      const crypto = yield* Crypto.Crypto;
+
+      const open = Effect.fn("BrowserRunProtectedHost.open")(function* (
+        input: InteractiveBrowserPolicy,
+        checkpoint?: BrowserRunProtectedCheckpoint,
+      ): Effect.fn.Return<
+        BrowserRunProtectedSession,
+        ProtectedBrowserError,
+        Scope.Scope | BrowserCredentialAccess
+      > {
+        const policy = yield* Schema.decodeEffect(InteractiveBrowserPolicy)(input).pipe(
+          Effect.mapError(() => failure("denied")),
+        );
+
+        if (policy.network._tag !== "Unrestricted") return yield* failure("unsupported");
+
+        const remaining =
+          policy.maxElapsedMillis -
+          ((yield* Clock.currentTimeMillis) -
+            (checkpoint?.protected.startedAt ?? (yield* Clock.currentTimeMillis)));
+
+        if (
+          remaining <= 0 ||
+          (checkpoint !== undefined &&
+            checkpoint.protected.startedAt > (yield* Clock.currentTimeMillis))
+        )
+          return yield* failure("timeout");
+        if (checkpoint !== undefined && checkpoint.protected.actions > policy.maxActions)
+          return yield* failure("denied");
+        const provider = yield* binding.open(policy, checkpoint);
+
+        const state = yield* makeProtectedBrowserPolicy(policy, checkpoint?.protected).pipe(
+          Effect.provideService(BrowserRunProtectedTransport, {
+            open: () => Effect.succeed({ ...provider.driver, detach: provider.detach }),
+          }),
+          Effect.provideService(Crypto.Crypto, crypto),
+        );
+
+        const lock = yield* Semaphore.make(1);
+        let handoff = checkpoint;
+        let detached = false;
+
+        const control = <A>(effect: Effect.Effect<A, ProtectedBrowserError>) =>
+          lock
+            .withPermitsIfAvailable(1)(
+              Effect.suspend(() => (detached ? Effect.fail(failure("closed")) : effect)),
+            )
+            .pipe(Effect.flatMap(Effect.fromOption(() => failure("busy"))));
+
+        const fits = (millis: number) =>
+          Effect.gen(function* () {
+            const started = handoff?.protected.startedAt ?? startedAt;
+
+            if (millis > policy.maxElapsedMillis - ((yield* Clock.currentTimeMillis) - started))
+              return yield* failure("timeout");
+          });
+
+        const startedAt = checkpoint?.protected.startedAt ?? (yield* Clock.currentTimeMillis);
+
+        const getHandoffState = Effect.gen(function* () {
+          if (handoff?.handoffId === undefined) return yield* failure("denied");
+          yield* fits(0);
+          const raw = yield* provider.command("Cloudflare.getHandoffState", {});
+
+          const result = yield* Schema.decodeUnknownEffect(HandoffState)(raw).pipe(
+            Effect.mapError(() => failure("provider")),
+          );
+
+          if (
+            (result.active && result.handoffId === undefined) ||
+            (result.handoffId !== undefined &&
+              result.handoffId !== Redacted.value(handoff.handoffId))
+          )
+            return yield* failure("denied");
+
+          return BrowserRunHandoffState.make({
+            active: result.active,
+            ...(result.durationMs === undefined ? {} : { durationMs: result.durationMs }),
+            ...(result.handoffId === undefined
+              ? {}
+              : { handoffId: Redacted.make(result.handoffId) }),
+          });
+        });
+
+        return {
+          handle: state.handle,
+          sessionId: provider.identity.sessionId,
+          suspend: control(
+            Effect.gen(function* () {
+              if (handoff !== undefined) {
+                yield* state.suspend();
+
+                return handoff;
+              }
+              const suspended = yield* state.suspend();
+
+              handoff = BrowserRunProtectedCheckpoint.make({
+                ...provider.identity,
+                protected: suspended,
+              });
+
+              return handoff;
+            }),
+          ),
+          handoff: (request) =>
+            control(
+              Effect.gen(function* () {
+                if (handoff?.handoffId !== undefined) return yield* failure("busy");
+
+                const decoded = yield* Schema.decodeEffect(BrowserRunHandoffRequest)(request).pipe(
+                  Effect.mapError(() => failure("denied")),
+                );
+
+                yield* fits(decoded.timeout);
+                const suspended = yield* state.suspend(true);
+
+                // An uncertain handoff is never retried; close exactly this provider session.
+                const result = yield* provider
+                  .command("Cloudflare.handoff", {
+                    instructions: decoded.instructions,
+                    timeout: decoded.timeout,
+                  })
+                  .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.onInterrupt(() => state.handle.close),
+                  );
+
+                handoff = BrowserRunProtectedCheckpoint.make({
+                  ...provider.identity,
+                  protected: suspended,
+                  handoffId: Redacted.make(result.handoffId),
+                });
+
+                return handoff;
+              }),
+            ),
+          getLiveView: (request) =>
+            control(
+              Effect.gen(function* () {
+                if (handoff?.handoffId === undefined) return yield* failure("denied");
+
+                const decoded = yield* Schema.decodeEffect(BrowserRunLiveViewRequest)(request).pipe(
+                  Effect.mapError(() => failure("denied")),
+                );
+
+                yield* fits(decoded.expiresInMs);
+
+                const raw = yield* provider.command("Cloudflare.getLiveView", {
+                  mode: decoded.mode,
+                  expiresInMs: decoded.expiresInMs,
+                });
+
+                const result = yield* Schema.decodeUnknownEffect(LiveView)(raw).pipe(
+                  Effect.mapError(() => failure("provider")),
+                );
+
+                return yield* Schema.decodeEffect(BrowserRunLiveViewResult)({
+                  devtoolsFrontendUrl: Redacted.make(result.devtoolsFrontendUrl),
+                }).pipe(Effect.mapError(() => failure("provider")));
+              }),
+            ),
+          getHandoffState: control(getHandoffState),
+          returnControl: control(
+            Effect.gen(function* () {
+              if ((yield* getHandoffState).active) return yield* failure("busy");
+              yield* state.returnControl;
+              handoff = undefined;
+            }),
+          ),
+          detach: control(
+            Effect.gen(function* () {
+              if (handoff === undefined) return yield* failure("denied");
+              yield* state.detach;
+              detached = true;
+            }),
+          ),
+          close: state.handle.close,
+        };
+      }, Effect.withTracerEnabled(false));
+
+      return {
+        open: (policy: InteractiveBrowserPolicy) => open(policy),
+        resume: (checkpoint: BrowserRunProtectedCheckpoint) =>
+          Schema.decodeEffect(BrowserRunProtectedCheckpoint)(checkpoint).pipe(
+            Effect.mapError(() => failure("denied")),
+            Effect.flatMap((decoded) => open(decoded.protected.policy, decoded)),
+          ),
+        closeSession: (id: Redacted.Redacted<string>) =>
+          lifecycle.close(id).pipe(
+            Effect.as("confirmed" as const),
+            Effect.catchCause(() => Effect.succeed("unconfirmed" as const)),
+          ),
+      };
+    }),
+  );

package/src/protected-browser/native.ts

@@ -56,6 +56,8 @@ export class ProtectedNativeSession extends Context.Service<
     readonly browser: Browser;
     readonly page: Page;
     readonly close: Effect.Effect<"confirmed" | "unconfirmed">;
+    /** Host-owned attachment release may detach a committed suspended session. */
+    readonly release?: Effect.Effect<void>;
   }
 >()("@effect-agent/platform-cloudflare/ProtectedNativeSession") {}
 
@@ -249,7 +251,20 @@ export const makeProtectedNativeTransport = Effect.fn("ProtectedNativeTransport.
       page.on("framedetached", onNavigated);
       browser.on("targetcreated", onTarget);
     }),
-    () => close,
+    () =>
+      session.release === undefined
+        ? close
+        : session.release.pipe(
+            Effect.ensuring(
+              Effect.sync(() => {
+                invalidate();
+                page.off("framenavigated", onNavigated);
+                page.off("framedetached", onNavigated);
+                browser.off("targetcreated", onTarget);
+                frames.clear();
+              }),
+            ),
+          ),
   );
 
   return {
@@ -271,6 +286,7 @@ export const makeProtectedNativeTransport = Effect.fn("ProtectedNativeTransport.
     ),
     context,
     invalidate,
+    resetReferences: clear,
     close,
     navigate: Effect.fn("ProtectedNativeTransport.navigate")(function* (url) {
       yield* check;