@effect-agent/platform-cloudflare 0.1.0-beta.41 → 0.1.0-beta.44

package/src/alarm.ts

@@ -98,6 +98,7 @@ export class DurableAlarmService extends Context.Service<
          * on top of the already-committed pre-armed alarm.
          */
         const runningPasses = yield* Ref.make(0);
+
         const scheduled = Effect.tryPromise({
           try: () => ctx.storage.getAlarm(),
           catch: alarmFailure("get alarm"),
@@ -106,11 +107,13 @@ export class DurableAlarmService extends Context.Service<
             deadline === null ? Option.none<number>() : Option.some(deadline),
           ),
         );
+
         const scheduleAt = (epochMillis: number) =>
           Effect.tryPromise({
             try: () => ctx.storage.setAlarm(epochMillis),
             catch: alarmFailure("set alarm"),
           });
+
         const ensureScheduledBy = (epochMillis: number) =>
           scheduled.pipe(
             Effect.flatMap((existing) =>
@@ -119,21 +122,26 @@ export class DurableAlarmService extends Context.Service<
                 : scheduleAt(epochMillis),
             ),
           );
+
         const armNow = Clock.currentTimeMillis.pipe(
           Effect.flatMap((now) => ensureScheduledBy(now)),
         );
+
         const scheduleNow = Ref.get(runningPasses).pipe(
           Effect.flatMap((passes) => (passes > 0 ? Effect.void : armNow)),
         );
+
         const withWakesDeferred = <A, E, R>(body: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
           Ref.update(runningPasses, (passes) => passes + 1).pipe(
             Effect.andThen(body),
             Effect.ensuring(Ref.update(runningPasses, (passes) => passes - 1)),
           );
+
         const cancel = Effect.tryPromise({
           try: () => ctx.storage.deleteAlarm(),
           catch: alarmFailure("delete alarm"),
         });
+
         return DurableAlarmService.of({
           scheduled,
           scheduleAt,
@@ -221,6 +229,7 @@ const readMaintenanceState = async (
   transaction: DurableObjectTransaction,
 ): Promise<{ readonly state: ThreadMaintenanceState; readonly initialized: boolean }> => {
   const encoded = await transaction.get(MAINTENANCE_STATE_KEY);
+
   return encoded === undefined
     ? { state: initialMaintenanceState(), initialized: false }
     : { state: decodeMaintenanceState(encoded), initialized: true };
@@ -231,6 +240,7 @@ const ensureTransactionAlarmBy = async (
   deadline: number,
 ): Promise<void> => {
   const scheduled = await transaction.getAlarm();
+
   if (scheduled === null || scheduled > deadline) {
     await transaction.setAlarm(deadline);
   }
@@ -241,6 +251,7 @@ const stableExternalWait = (
   reports: ReadonlyMap<string, RecoveryReport>,
 ): boolean => {
   const decision = reports.get(snapshot.submissionId)?.decision._tag;
+
   // An accepted abort still owes cleanup/settlement even if its claim was deferred this pass.
   if (decision === "SettleAborted") return false;
   switch (snapshot.state) {
@@ -353,13 +364,16 @@ export class ThreadMaintenance extends Context.Service<
         const beginMutation = Effect.fn("ThreadMaintenance.beginMutation")(function* () {
           yield* failpoint.hit("maintenance:dirty:before");
           const now = yield* Clock.currentTimeMillis;
+
           yield* runTransaction("advance maintenance generation", () =>
             ctx.storage.transaction(async (transaction) => {
               const { state } = await readMaintenanceState(transaction);
+
               const next = ThreadMaintenanceState.make({
                 ...state,
                 dirty: state.dirty + 1n,
               });
+
               await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(next));
               // The earliest configured retry bounds a newly actionable mutation without relying
               // on its best-effort immediate wake hint.
@@ -390,9 +404,11 @@ export class ThreadMaintenance extends Context.Service<
         const ensureAlarm = Effect.fn("ThreadMaintenance.ensureAlarm")(function* () {
           yield* failpoint.hit("maintenance:ensure:before");
           const now = yield* Clock.currentTimeMillis;
+
           yield* runTransaction("ensure maintenance alarm", () =>
             ctx.storage.transaction(async (transaction) => {
               const { state, initialized } = await readMaintenanceState(transaction);
+
               if (!initialized) {
                 await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(state));
               }
@@ -407,23 +423,29 @@ export class ThreadMaintenance extends Context.Service<
         const beginPass = Effect.fn("ThreadMaintenance.beginPass")(function* () {
           yield* failpoint.hit("maintenance:begin:before");
           const now = yield* Clock.currentTimeMillis;
+
           const result = yield* runTransaction("begin maintenance pass", () =>
             ctx.storage.transaction(async (transaction) => {
               const { state, initialized } = await readMaintenanceState(transaction);
+
               if (!initialized) {
                 await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(state));
               }
               if (state.processed >= state.dirty) {
                 await transaction.deleteAlarm();
+
                 return { _tag: "CaughtUp" as const, nonterminal: state.nonterminal };
               }
               // Pre-arm the earliest retry before recovery. A successful finish may move this slot
               // LATER to its bounded backoff, which does not cancel the running handler.
               await ensureTransactionAlarmBy(transaction, now + minimumAlarmDelay);
+
               return { _tag: "Actionable" as const, generation: state.dirty };
             }),
           );
+
           yield* failpoint.hit("maintenance:begin:after");
+
           return result;
         });
 
@@ -433,6 +455,7 @@ export class ThreadMaintenance extends Context.Service<
           const priorStalls = yield* Ref.getAndUpdate(stalls, (count) =>
             progressed ? 0 : count + 1,
           );
+
           if (progressed) return config.alarmBackoffBase;
           const exponent = Math.min(priorStalls, 30);
           const backoff = Math.min(config.alarmBackoffCap, config.alarmBackoffBase * 2 ** exponent);
@@ -440,6 +463,7 @@ export class ThreadMaintenance extends Context.Service<
           // Full jitter over [backoff/2, backoff]: desynchronizes retry storms without ever
           // waiting longer than the deterministic bound.
           const jittered = Math.ceil(backoff / 2 + (backoff / 2) * jitter);
+
           return Math.min(jittered, config.wakeScanInterval);
         });
 
@@ -460,9 +484,11 @@ export class ThreadMaintenance extends Context.Service<
             Effect.gen(function* () {
               const activeAtStart = yield* Ref.get(activeMutations);
               const generation = yield* beginPass();
+
               return { ...generation, activeAtStart };
             }),
           );
+
           if (started._tag === "CaughtUp") {
             return yield* annotate(
               MaintenancePassReport.make({
@@ -483,6 +509,7 @@ export class ThreadMaintenance extends Context.Service<
           const reports = new Map(recovered.map((report) => [report.submissionId, report]));
           const head = remaining[0];
           const headWaiting = head !== undefined && stableExternalWait(head, reports);
+
           const autonomous = remaining.some((snapshot, index) => {
             // FIFO followers cannot execute through a stable external wait. Only plain queued
             // input is dormant here; admission repairs and accepted aborts still need a pass.
@@ -493,19 +520,26 @@ export class ThreadMaintenance extends Context.Service<
               reports.get(snapshot.submissionId)?.decision._tag === "ApplyInput"
             )
               return false;
+
             return !stableExternalWait(snapshot, reports);
           });
+
           const progressed =
             settlements.length > 0 || recovered.some((report) => report.disposition === "repaired");
+
           const delay = autonomous ? yield* rearmDelay(progressed) : 0;
           const now = yield* Clock.currentTimeMillis;
+
           yield* failpoint.hit("maintenance:finish:before");
+
           const alarmDisposition = yield* generationGate.withPermit(
             Effect.gen(function* () {
               const active = yield* Ref.get(activeMutations);
+
               return yield* runTransaction("finish maintenance pass", () =>
                 ctx.storage.transaction(async (transaction) => {
                   const { state } = await readMaintenanceState(transaction);
+
                   // Autonomous work and in-flight mutations intentionally leave the observed
                   // generation dirty. Otherwise acknowledge only the pass-start generation.
                   const processed =
@@ -514,17 +548,20 @@ export class ThreadMaintenance extends Context.Service<
                       : state.processed > started.generation
                         ? state.processed
                         : started.generation;
+
                   const next = ThreadMaintenanceState.make({
                     ...state,
                     processed,
                     nonterminal: remaining.length,
                   });
+
                   await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(next));
                   if (autonomous) {
                     // Replace the crash-fallback slot with this pass's bounded backoff. The target
                     // is never earlier than the begin-pass fallback, so workerd does not cancel
                     // this running alarm handler before its report/span can complete.
                     await transaction.setAlarm(now + delay);
+
                     return "rearmed" as const;
                   }
                   if (started.activeAtStart > 0 || active > 0 || next.dirty > next.processed) {
@@ -534,18 +571,22 @@ export class ThreadMaintenance extends Context.Service<
                     // from inside the current handler: workerd cancels a running handler when it
                     // writes an earlier slot.
                     await ensureTransactionAlarmBy(transaction, now + config.wakeScanInterval);
+
                     return "rearmed" as const;
                   }
                   await transaction.deleteAlarm();
+
                   return "cleared" as const;
                 }),
               );
             }),
           );
+
           yield* failpoint.hit("maintenance:finish:after");
           if (alarmDisposition === "cleared") {
             yield* Ref.set(stalls, 0);
           }
+
           return yield* annotate(
             MaintenancePassReport.make({
               phase: "actionable",

package/src/bindings.ts

@@ -91,12 +91,15 @@ export const threadNamespaceFromEnv = Effect.fn("threadNamespaceFromEnv")(functi
       message: "The Worker environment is not an object; no bindings are available.",
     });
   }
+
   const candidate = yield* Effect.try({
     try: () => {
       const value: unknown = Reflect.get(env, binding);
+
       if (!Predicate.isObjectKeyword(value)) return undefined;
       const idFromName: unknown = Reflect.get(value, "idFromName");
       const get: unknown = Reflect.get(value, "get");
+
       return typeof idFromName === "function" && typeof get === "function" ? value : undefined;
     },
     catch: () =>
@@ -105,11 +108,13 @@ export const threadNamespaceFromEnv = Effect.fn("threadNamespaceFromEnv")(functi
         message: `env.${binding} could not be inspected as a DurableObjectNamespace binding.`,
       }),
   });
+
   if (candidate !== undefined) {
     // The structural probe above is the entire runtime contract this package relies on;
     // the assertion records that `idFromName`/`get` name a DurableObjectNamespace.
     return candidate as unknown as DurableObjectNamespace<ThreadObjectRpc>;
   }
+
   return yield* CloudflareBindingError.make({
     binding,
     message:

package/src/boundary.ts

@@ -9,6 +9,7 @@ const boundForeignDiagnostic = (message: string): string =>
 export const safeCauseMessage = (cause: unknown, fallback: string): string => {
   try {
     const message = cause instanceof Error ? cause.message : cause;
+
     return boundForeignDiagnostic(typeof message === "string" ? message : String(message));
   } catch {
     return boundForeignDiagnostic(fallback);
@@ -38,9 +39,12 @@ export const cloudflareFailureSignals = (cause: unknown): CloudflareFailureSigna
     const retryableValue = Reflect.get(cause, "retryable");
     const overloadedValue = Reflect.get(cause, "overloaded");
     const resetValue = Reflect.get(cause, "durableObjectReset");
+
     const retryable =
       typeof retryableValue === "boolean" ? retryableValue : resetValue === true ? true : undefined;
+
     const overloaded = typeof overloadedValue === "boolean" ? overloadedValue : undefined;
+
     return {
       ...(retryable === undefined ? {} : { retryable }),
       ...(overloaded === undefined ? {} : { overloaded }),

package/src/browser-quick-action.ts

@@ -97,6 +97,7 @@ export class BrowserQuickActionBrowserBinding extends Context.Service<
     options: BrowserQuickActionCaptureOptions,
   ): Layer.Layer<BrowserQuickActionBrowserBinding> {
     const browser = options.browser;
+
     const invoke = Effect.fn("BrowserQuickActionBrowserBinding.invoke")(function* (
       action: "screenshot" | "content" | "markdown" | "links" | "scrape" | "json",
       evaluate: () => Promise<Response>,
@@ -106,6 +107,7 @@ export class BrowserQuickActionBrowserBinding extends Context.Service<
         catch: (cause) => BrowserQuickActionRpcError.make({ action, cause }),
       });
     });
+
     return Layer.succeed(BrowserQuickActionBrowserBinding)({
       screenshot: (request) =>
         invoke("screenshot", () => browser.quickAction("screenshot", request)),
@@ -175,8 +177,10 @@ const decodeEnvelope = Schema.decodeUnknownOption(Schema.fromJsonString(QuickAct
 const quickActionCommonOptions = (request: PageCaptureRequest): BrowserRunCommonOptions => {
   const options: BrowserRunBaseOptions = {};
   const navigation = request.navigation;
+
   if (navigation !== undefined) {
     const goto: NonNullable<BrowserRunBaseOptions["gotoOptions"]> = {};
+
     if (navigation.waitUntil !== undefined) goto.waitUntil = navigation.waitUntil;
     if (navigation.timeoutMillis !== undefined) goto.timeout = navigation.timeoutMillis;
     if (Object.keys(goto).length > 0) options.gotoOptions = goto;
@@ -200,6 +204,7 @@ const quickActionCommonOptions = (request: PageCaptureRequest): BrowserRunCommon
       options.allowRequestPattern = [...request.resourcePolicy.allowRequestPatterns];
     }
   }
+
   return request.target._tag === "PageUrlTarget"
     ? { ...options, url: request.target.url }
     : { ...options, html: request.target.html };
@@ -211,6 +216,7 @@ const executeQuickAction = (
   request: PageCaptureRequest,
 ): Effect.Effect<Response, BrowserQuickActionRpcError> => {
   const options = quickActionCommonOptions(request);
+
   switch (request.action._tag) {
     case "CapturePageContent": {
       return browser.content(options);
@@ -284,6 +290,7 @@ const readBoundedResponse = Effect.fn("BrowserQuickActionCapture.readResponse")(
   request: PageCaptureRequest,
 ) {
   const body = response.body;
+
   if (body === null) return "";
 
   const reader = yield* Effect.acquireRelease(
@@ -293,6 +300,7 @@ const readBoundedResponse = Effect.fn("BrowserQuickActionCapture.readResponse")(
     }),
     releaseResponseReader,
   );
+
   const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
   let observedBytes = 0;
   let bodyText = "";
@@ -302,6 +310,7 @@ const readBoundedResponse = Effect.fn("BrowserQuickActionCapture.readResponse")(
       try: () => reader.read(),
       catch: (cause) => protocolError("Reading the Quick Action response failed", cause),
     });
+
     if (chunk.done) break;
 
     observedBytes += chunk.value.byteLength;
@@ -334,25 +343,32 @@ const readBoundedResponse = Effect.fn("BrowserQuickActionCapture.readResponse")(
  */
 const retryAfterMillis = (response: Response): number | undefined => {
   const header = response.headers.get("Retry-After");
+
   if (header === null) return undefined;
   const seconds = Number(header);
+
   if (!Number.isSafeInteger(seconds) || seconds < 0) return undefined;
   const millis = seconds * 1_000;
+
   return Number.isSafeInteger(millis) ? millis : undefined;
 };
 
 const browserMillis = (response: Response): number | undefined => {
   const header = response.headers.get("X-Browser-Ms-Used");
+
   if (header === null) return undefined;
   const millis = Number(header);
+
   return Number.isSafeInteger(millis) && millis >= 0 ? millis : undefined;
 };
 
 /** Only trusted response metadata chooses transport framing; page text never does. */
 const isJsonResponse = (response: Response): boolean => {
   const contentType = response.headers.get("Content-Type");
+
   if (contentType === null) return false;
   const mediaType = contentType.split(";", 1)[0]?.trim().toLowerCase();
+
   return mediaType === "application/json" || mediaType?.endsWith("+json") === true;
 };
 
@@ -368,6 +384,7 @@ const parseOutput = (
     );
   }
   const envelope = decodeEnvelope(bodyText);
+
   if (Option.isNone(envelope)) {
     return protocolError(
       "The JSON Quick Action response did not carry a valid response envelope",
@@ -386,6 +403,7 @@ const parseOutput = (
       if (typeof envelope.value.result !== "string") {
         return protocolError("The Quick Action envelope carried a non-text result");
       }
+
       return action._tag === "CapturePageContent"
         ? PageContentCaptured.make({ html: envelope.value.result })
         : PageMarkdownCaptured.make({ markdown: envelope.value.result });
@@ -395,9 +413,11 @@ const parseOutput = (
         _tag: "PageLinksCaptured",
         links: envelope.value.result,
       });
+
       if (Option.isNone(decoded)) {
         return protocolError("The links Quick Action did not return a bounded array of valid URLs");
       }
+
       return decoded.value;
     }
     case "CapturePageScrape": {
@@ -405,11 +425,13 @@ const parseOutput = (
         _tag: "PageScrapeCaptured",
         groups: envelope.value.result,
       });
+
       if (Option.isNone(decoded)) {
         return protocolError(
           "The scrape Quick Action did not return bounded grouped element records",
         );
       }
+
       return decoded.value;
     }
     case "CapturePageStructured": {
@@ -437,6 +459,7 @@ const makeCapture = (
     }
 
     const usesWorkersAi = request.action._tag === "CapturePageStructured";
+
     if (usesWorkersAi) {
       if (workersAi === undefined) {
         return yield* PageCaptureUnsupportedError.make({
@@ -467,11 +490,14 @@ const makeCapture = (
         protocolError("The browser binding rejected the Quick Action", error.cause),
       ),
     );
+
     const bodyText = yield* readBoundedResponse(response, request);
+
     if (response.status === 429) {
       const retryAfter = retryAfterMillis(response);
       const reason = isQuotaMessage(bodyText) ? "quota" : "rate";
       const cause = privateResponseCause(bodyText);
+
       return yield* PageCaptureRateLimitedError.make({
         implementation: browserQuickActionImplementation,
         reason,
@@ -486,12 +512,15 @@ const makeCapture = (
     if (!response.ok) {
       const message = `The Quick Action answered HTTP ${response.status}`;
       const cause = privateResponseCause(bodyText);
+
       if (response.status >= 500) {
         return yield* protocolError(message, cause);
       }
+
       return yield* navigationError(message, cause);
     }
     const output = parseOutput(request.action, bodyText, response);
+
     if (
       output._tag === "PageCaptureNavigationError" ||
       output._tag === "PageCaptureProtocolError"
@@ -499,6 +528,7 @@ const makeCapture = (
       return yield* output;
     }
     const millis = browserMillis(response);
+
     return PageCaptureResult.make({
       implementation: browserQuickActionImplementation,
       output,
@@ -543,6 +573,7 @@ export const browserQuickActionWorkersAiCaptureLayer = (): Layer.Layer<
     Effect.gen(function* () {
       const browser = yield* BrowserQuickActionBrowserBinding;
       const workersAi = yield* BrowserQuickActionWorkersAi;
+
       return PageCapture.of({ capture: makeCapture(browser, workersAi) });
     }),
   );
@@ -580,6 +611,7 @@ export const CloudflareBrowser = {
 
 const screenshotOptions = (request: PageScreenshotRequest): BrowserRunScreenshotOptions => {
   const options: BrowserRunBaseOptions = {};
+
   if (
     request.navigation?.waitUntil !== undefined ||
     request.navigation?.timeoutMillis !== undefined
@@ -610,6 +642,7 @@ const screenshotOptions = (request: PageScreenshotRequest): BrowserRunScreenshot
   if (request.resourcePolicy?.allowRequestPatterns !== undefined) {
     options.allowRequestPattern = [...request.resourcePolicy.allowRequestPatterns];
   }
+
   return {
     ...options,
     ...(request.target._tag === "PageUrlTarget"
@@ -643,8 +676,10 @@ const pngResponse = (response: Response): boolean =>
 
 const declaredLength = (response: Response): number | undefined => {
   const raw = response.headers.get("Content-Length");
+
   if (raw === null || !/^(0|[1-9][0-9]*)$/.test(raw)) return undefined;
   const length = Number(raw);
+
   return Number.isSafeInteger(length) ? length : undefined;
 };
 
@@ -653,22 +688,27 @@ const readScreenshot = Effect.fn("BrowserQuickActionScreenshot.read")(function*
   request: PageScreenshotRequest,
 ) {
   const body = response.body;
+
   if (body === null) {
     return yield* protocolError("The screenshot response had no body");
   }
   if (!pngResponse(response)) {
     yield* cancelBody(body);
+
     return yield* protocolError("The screenshot response was not image/png");
   }
   const length = declaredLength(response);
+
   if (length !== undefined && length > request.limits.maxOutputBytes) {
     yield* cancelBody(body);
+
     return yield* PageScreenshotOutputLimitError.make({
       implementation: browserQuickActionImplementation,
       limit: request.limits.maxOutputBytes,
       observed: length,
     });
   }
+
   const reader = yield* Effect.acquireRelease(
     Effect.try({
       try: () => body.getReader(),
@@ -676,13 +716,16 @@ const readScreenshot = Effect.fn("BrowserQuickActionScreenshot.read")(function*
     }),
     releaseScreenshotReader,
   );
+
   const chunks: Array<Uint8Array> = [];
   let observed = 0;
+
   while (true) {
     const next = yield* Effect.tryPromise({
       try: () => reader.read(),
       catch: (cause) => protocolError("Reading the screenshot response failed", cause),
     });
+
     if (next.done) break;
     observed += next.value.byteLength;
     if (observed > request.limits.maxOutputBytes) {
@@ -696,10 +739,12 @@ const readScreenshot = Effect.fn("BrowserQuickActionScreenshot.read")(function*
   }
   const bytes = new Uint8Array(observed);
   let offset = 0;
+
   for (const chunk of chunks) {
     bytes.set(chunk, offset);
     offset += chunk.byteLength;
   }
+
   return bytes;
 }, Effect.scoped);
 
@@ -714,6 +759,7 @@ const makeScreenshot = (browser: BrowserQuickActionClient): PageScreenshotCaptur
         message: "The browser binding's screenshot action exposes no engine selector",
       });
     }
+
     const response = yield* browser
       .screenshot(screenshotOptions(request))
       .pipe(
@@ -721,9 +767,12 @@ const makeScreenshot = (browser: BrowserQuickActionClient): PageScreenshotCaptur
           protocolError("The browser binding rejected the screenshot", error.cause),
         ),
       );
+
     if (response.status === 429) {
       const body = response.body;
+
       if (body !== null) yield* cancelBody(body);
+
       return yield* PageCaptureRateLimitedError.make({
         implementation: browserQuickActionImplementation,
         reason: "rate",
@@ -735,11 +784,14 @@ const makeScreenshot = (browser: BrowserQuickActionClient): PageScreenshotCaptur
     }
     if (!response.ok) {
       const body = response.body;
+
       if (body !== null) yield* cancelBody(body);
       const message = `The screenshot Quick Action answered HTTP ${response.status}`;
+
       return yield* response.status >= 500 ? protocolError(message) : navigationError(message);
     }
     const bytes = yield* readScreenshot(response, request);
+
     return PageScreenshotResult.make({
       implementation: browserQuickActionImplementation,
       mediaType: "image/png",