npm - @frockbot/cloudflare - Versions diffs - 0.0.0 → 0.7.291 - Mend

@frockbot/cloudflare 0.0.0 → 0.7.291

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (88) hide show

package/build-artifact.ts +130 -0
package/build-flutter-web.ts +508 -0
package/deployment-config/README.md +414 -0
package/deployment-config/cli.ts +228 -0
package/deployment-config/generate.ts +689 -0
package/deployment-config/jsonc.ts +18 -0
package/deployment-config/profile-schema.generated.ts +391 -0
package/deployment-config/profile.schema.json +358 -0
package/deployment-config/profile.ts +124 -0
package/migrations/0001_better_auth.sql +15 -0
package/migrations/0002_drop_account_issuer.sql +8 -0
package/package.json +61 -5
package/release-version.ts +20 -0
package/src/account-admission.ts +179 -0
package/src/account-deletion.ts +274 -0
package/src/admin-entrypoint.ts +194 -0
package/src/admin-identities.ts +26 -0
package/src/audit.ts +103 -0
package/src/auth-package.access.ts +24 -0
package/src/auth-package.ts +36 -0
package/src/avatar-state-cleanup.ts +107 -0
package/src/billing-computer.ts +267 -0
package/src/billing-readiness.ts +21 -0
package/src/billing.ts +461 -0
package/src/bot-capabilities.ts +480 -0
package/src/bot-recovery.ts +1 -0
package/src/bot-state-channel.ts +702 -0
package/src/bot-state.ts +3995 -0
package/src/bot-template-cleanup.ts +98 -0
package/src/bot-title-cleanup.ts +104 -0
package/src/brand-icon.png +0 -0
package/src/brand-logo.ts +2 -0
package/src/brand.ts +36 -0
package/src/client-compatibility.ts +51 -0
package/src/compaction-announcement-cleanup.ts +113 -0
package/src/computer-egress.ts +110 -0
package/src/computer-host.ts +92 -0
package/src/computer-screenshot-cleanup.ts +78 -0
package/src/contracts.ts +832 -0
package/src/debug.ts +272 -0
package/src/default-packages-marker-cleanup.ts +39 -0
package/src/deployment-policy-admin-host.ts +121 -0
package/src/deployment-policy.ts +426 -0
package/src/directory-profile-cleanup.ts +101 -0
package/src/durable-rpc.ts +753 -0
package/src/durable-session.ts +21 -0
package/src/entry-boundary.ts +103 -0
package/src/frock-ai.ts +338 -0
package/src/gateway.ts +1392 -0
package/src/group-chat.ts +736 -0
package/src/hidden-bot-notifications-cleanup.ts +32 -0
package/src/index.ts +2798 -0
package/src/insights.ts +15 -0
package/src/machine-messages-cleanup.ts +121 -0
package/src/machine-socket.ts +164 -0
package/src/memory-records.ts +181 -0
package/src/memory.ts +145 -0
package/src/model-rates.ts +252 -0
package/src/native-auth.ts +1006 -0
package/src/native-sessions.ts +121 -0
package/src/notification-state-cleanup.ts +18 -0
package/src/ollama-web-search-cleanup.ts +69 -0
package/src/package-page-shapes-cleanup.ts +190 -0
package/src/plugin-egress.ts +31 -0
package/src/plugin-page-route.ts +72 -0
package/src/plugin-panels-cleanup.ts +101 -0
package/src/prepared-input-cleanup.ts +105 -0
package/src/production-secrets.ts +484 -0
package/src/project-cleanup.ts +123 -0
package/src/project-events-cleanup.ts +152 -0
package/src/publication-state-cleanup.ts +92 -0
package/src/push.ts +498 -0
package/src/request-body.ts +165 -0
package/src/routine-state-cleanup.ts +57 -0
package/src/search.ts +88 -0
package/src/sidebar-label-cleanup.ts +165 -0
package/src/skill-index-cleanup.ts +53 -0
package/src/supersede-cleanup.ts +162 -0
package/src/test-chat-cleanup.ts +93 -0
package/src/uploads.ts +486 -0
package/src/user-application.ts +1068 -0
package/src/user-configuration.ts +4491 -0
package/src/voice-assistant.ts +4999 -0
package/src/voice-dictation.ts +743 -0
package/src/working-context-cleanup.ts +96 -0
package/src/workspace.ts +201 -0
package/wrangler.jsonc +385 -0
package/README.md +0 -3

package/src/user-application.ts ADDED Viewed

@@ -0,0 +1,1068 @@
+import {
+  foundationPackageCatalogV1,
+  FOUNDATION_PACKAGE_VERSION_V1,
+} from "@frockbot/app/runtime";
+import { BRAND_V1 } from "#brand";
+import { COMPUTER_HOST_CAPABILITIES_V1 } from "./computer-host.js";
+import {
+  decodeBotIdV1,
+  isApplicationDeploymentHash,
+  isRpcIdentifier,
+} from "@frockbot/core/configuration";
+import {
+  decodeClientNotificationAcknowledgementCommandV1,
+  type ClientNotificationAcknowledgementV1,
+  type ClientNotificationListV1,
+  decodeClientRunAdmissionFenceCommandV1,
+  decodeClientRunLookupQueryV1,
+  decodeClientRunListQueryV1,
+  parseExchangeCounterpartParamV1,
+  clientProtocolOfV1,
+  decodeClientRunStopCommandV1,
+  decodeClientTurnCommandV1,
+  RUN_ATTACHMENTS_PROTOCOL_V1,
+  withoutRunAttachmentsV1,
+  type ClientRunLookupQueryV1,
+  type ClientRunStopCommandV1,
+  type ClientTurnCommandV1,
+  type ClientTurnRefusalReasonV1,
+  type ClientTurnRefusalV1,
+} from "@frockbot/app/shell/run-protocol";
+import { decodeApprovalDecisionCommandV1 } from "@frockbot/app/shell/approvals";
+import {
+  decodeSecretSubmitCommandV1,
+  isSecretRequestIdV1,
+  SecretDecodeError,
+} from "@frockbot/app/secrets/shared";
+import {
+  decodeCardActionCommandV1,
+  decodeCardSurfaceIdV1,
+} from "@frockbot/app/shell/cards";
+import { botTurnRefusalCodeV1 } from "@frockbot/core/durable";
+import type { UserApplicationEnv } from "./contracts.js";
+import { answeredEntryV1, entryFailureStatusV1 } from "./entry-boundary.js";
+import { INSIGHTS_REPORT_ORIGIN, INSIGHTS_SCRIPT_ORIGIN } from "./insights.js";
+import {
+  drainedAnswerV1,
+  isRequestTooLargeV1,
+  RequestTooLargeError,
+  TURN_BODY_MAX_BYTES_V1,
+  TURN_TOO_LONG_MESSAGE_V1,
+  turnBodyIsOversizedV1,
+} from "./request-body.js";
+import { whatsNewImageResponseV1 } from "@frockbot/app/whats-new";
+declare const __FROCKBOT_FLUTTER_BUILD__: string;
+declare const __FROCKBOT_CLIENT_ICON__: string;
+/**
+ * The content-addressed prefix the Flutter client is served from.
+ *
+ * The payload is the Worker's own static assets, uploaded with the deploy and
+ * served straight from the edge; the artifact only names it. Every URL under
+ * the prefix carries the build hash, so the document is the one thing that
+ * changes when the client does.
+ */
+const FLUTTER_BASE =
+  typeof __FROCKBOT_FLUTTER_BUILD__ === "string"
+    ? `/_flutter/${__FROCKBOT_FLUTTER_BUILD__}/`
+    : "/_flutter/development/";
+// The site icon is a PNG, so it rides the artifact as base64 and is decoded
+// once at module scope rather than on every request.
+const APP_ICON = Uint8Array.from(
+  atob(
+    typeof __FROCKBOT_CLIENT_ICON__ === "string"
+      ? __FROCKBOT_CLIENT_ICON__
+      : "",
+  ),
+  (character) => character.charCodeAt(0),
+);
+/** The product's name as the document title carries it. */
+const DOCUMENT_TITLE = BRAND_V1.productName
+  .replaceAll("&", "&amp;")
+  .replaceAll("<", "&lt;");
+type HostedAuthModeV1 = "anonymous" | "better-auth" | "development";
+function hostedAuthMode(request: Request): HostedAuthModeV1 {
+  const mode = request.headers.get("x-frockbot-auth-session-v1");
+  if (
+    mode !== "anonymous" &&
+    mode !== "better-auth" &&
+    mode !== "development"
+  ) {
+    throw new Error("hosted auth session projection is invalid");
+  }
+  return mode;
+}
+function hostedIsAdmin(request: Request): boolean {
+  const value = request.headers.get("x-frockbot-is-admin-v1");
+  if (value !== "true" && value !== "false") {
+    throw new Error("hosted admin projection is invalid");
+  }
+  return value === "true";
+}
+/**
+ * The `<body>` attributes the client reads before it has asked anything.
+ *
+ * A browser's session is a cookie it cannot see, so the account is stamped
+ * onto the document the Worker renders and the Flutter app adopts it on its
+ * first frame (`apps/native/packages/frockbot_client/lib/client/identity_web.dart`) rather than
+ * flashing the sign-in door at someone who is already signed in. The identity
+ * read still happens; this is what it confirms.
+ */
+export const HOSTED_EMBEDDED_BODY_ATTRIBUTES_V1 = [
+  "data-frockbot-user-id",
+  "data-frockbot-auth-mode",
+  "data-frockbot-is-admin",
+] as const;
+function appHtml(
+  userId: string,
+  applicationHash: string,
+  authMode: HostedAuthModeV1,
+  isAdmin: boolean,
+): string {
+  if (!isRpcIdentifier(userId)) throw new Error("invalid user id");
+  if (!isApplicationDeploymentHash(applicationHash)) {
+    throw new Error("invalid application hash");
+  }
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+  <meta name="frockbot-application" content="${applicationHash}">
+  <base href="${FLUTTER_BASE}">
+  <title>${DOCUMENT_TITLE}</title>
+  <link rel="icon" type="image/png" href="/favicon.ico">
+  <link rel="apple-touch-icon" href="/favicon.ico">
+  <meta name="color-scheme" content="dark">
+  <meta name="theme-color" content="#15151e">
+  <style>html,body{margin:0;height:100%;background:#15151e}</style>
+</head>
+<body data-frockbot-user-id="${userId}" data-frockbot-user-application="${applicationHash}" data-frockbot-auth-mode="${authMode}" data-frockbot-is-admin="${String(isAdmin)}">
+  <script src="${FLUTTER_BASE}flutter_bootstrap.js" async></script>
+</body>
+</html>`;
+}
+/**
+ * What the app frames: a Plugin's pages, which are served from this origin
+ * but only under `/plugin-pages/` and each sandboxed by its own policy, and
+ * the Computer host's viewer origins.
+ */
+function frameSources(applicationUrl: URL): string {
+  return [
+    `${applicationUrl.origin}/plugin-pages/`,
+    ...COMPUTER_HOST_CAPABILITIES_V1.viewerFrameOrigins,
+  ].join(" ");
+}
+function withSecurityHeaders(
+  response: Response,
+  applicationUrl: URL,
+): Response {
+  const secured = new Response(response.body, response);
+  secured.headers.set("x-content-type-options", "nosniff");
+  secured.headers.set("referrer-policy", "no-referrer");
+  secured.headers.set(
+    "content-security-policy",
+    // The app frames a Plugin's pages and the expanded Computer viewer.
+    //
+    // Cloudflare Insights is injected into every response by the zone itself,
+    // above this Worker, so the page loads it whether or not the policy allows
+    // it — and under `script-src 'self'` it was refused on every page load and
+    // logged a red console error for every User. Naming the beacon's origin is
+    // the honest fix: it is the deployment's own analytics, its script is
+    // fetched from one Cloudflare host and it reports to another. Removing it
+    // instead would mean turning the feature off in the zone, which the code
+    // cannot state or keep true.
+    //
+    // `script-src 'wasm-unsafe-eval'` and `style-src 'unsafe-inline'` are what
+    // the Flutter engine needs and neither is optional: CanvasKit instantiates
+    // WebAssembly, and the engine injects a `<style>` element to measure text.
+    // `base-uri 'self'` rather than `'none'` because the document sets a
+    // `<base href>` of its own to the content-addressed directory every engine
+    // URL is relative to.
+    `default-src 'self'; script-src 'self' 'wasm-unsafe-eval' ${INSIGHTS_SCRIPT_ORIGIN}; style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' data: blob:; connect-src 'self' ${INSIGHTS_REPORT_ORIGIN} ${applicationUrl.protocol === "https:" ? "wss:" : "ws:"}//${applicationUrl.host}; frame-src ${frameSources(applicationUrl)}; frame-ancestors 'none'; base-uri 'self'`,
+  );
+  return secured;
+}
+function jsonError(
+  status: number,
+  message: string,
+  options?: { definitive?: boolean },
+): Response {
+  return Response.json(
+    {
+      error: message,
+      ...(options?.definitive ? { definitive: true } : {}),
+    },
+    { status },
+  );
+}
+/**
+ * A Bot-scoped call that failed, answered with the status the failure is owed.
+ *
+ * These routes check the registration once, at the top, and then talk to the
+ * Bot Durable Object — and a Bot can stop existing in between. Deleting a Bot
+ * makes that window real and routine: the panels of the Bot being looked at
+ * poll it, so a read is almost always in flight when the delete lands. Such a
+ * read is a 404 or a 410, not a server fault, and answering 500 made the
+ * client log an error for the correct answer to its own question.
+ *
+ * Only a failure the entry boundary names gets a status of its own; anything
+ * unrecognised is still this Worker's 500.
+ */
+function botFailure(error: unknown, fallback: string): Response {
+  return jsonError(
+    entryFailureStatusV1(error),
+    error instanceof Error ? error.message : fallback,
+  );
+}
+/**
+ * A Turn the Bot Durable Object declined to admit, told apart from one that
+ * broke.
+ *
+ * Admission refusals are ordinary, expected answers — the object is busy with
+ * a Turn this command did not ask to replace, or is holding an uncertain
+ * effect that has to be retrieved first, or the run was fenced. None of them
+ * is a server fault, and answering 500 made the client log a console error for
+ * something it should simply show the person. They are 409: the request was
+ * well formed and the Bot's current state refuses it.
+ */
+const TURN_ADMISSION_REFUSALS_V1: readonly {
+  match: RegExp;
+  reason: ClientTurnRefusalReasonV1;
+}[] = [
+  { match: /bot already has an active run/i, reason: "busy" },
+  { match: /admission was fenced/i, reason: "fenced" },
+  { match: /already (exists|completed)/i, reason: "duplicate" },
+];
+export type { ClientTurnRefusalReasonV1, ClientTurnRefusalV1 };
+function turnRefusal(error: unknown): ClientTurnRefusalV1 | undefined {
+  const message = error instanceof Error ? error.message : "";
+  // The typed refusal first: the authority names its own reason, and the name
+  // is what survives the Durable Object RPC. The prose match stays as a
+  // fallback for refusals a Package still raises as plain errors.
+  const reason =
+    botTurnRefusalCodeV1(error) ??
+    TURN_ADMISSION_REFUSALS_V1.find((candidate) =>
+      candidate.match.test(message),
+    )?.reason;
+  if (!reason) return undefined;
+  return {
+    schemaVersion: 1,
+    status: "refused",
+    reason,
+    error: message,
+  };
+}
+async function requireRegisteredBot(
+  env: UserApplicationEnv,
+  botId: string,
+  allowArchived = false,
+): Promise<Response | undefined> {
+  try {
+    await env.BOT_STATE.assertRegistered({ schemaVersion: 1, botId });
+    return undefined;
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "name" in error) {
+      if (error.name === "BotNotFoundError")
+        return jsonError(
+          404,
+          error instanceof Error ? error.message : "Bot not found",
+        );
+      if (error.name === "BotArchivedError") {
+        if (allowArchived) return undefined;
+        return jsonError(
+          409,
+          error instanceof Error ? error.message : "Bot is archived",
+        );
+      }
+      if (error.name === "BotDeletedError")
+        return jsonError(
+          410,
+          error instanceof Error ? error.message : "Bot is deleted",
+        );
+    }
+    return jsonError(
+      503,
+      error instanceof Error
+        ? error.message
+        : "Bot registration is temporarily unavailable",
+    );
+  }
+}
+/**
+ * Read a send, refusing an oversized one before the body is touched.
+ *
+ * The refusal is typed rather than prose so the route can answer 413 with the
+ * sentence the composer shows, and so it is told apart from a body that simply
+ * would not parse. The gateway checks the same length one isolate earlier;
+ * this check is the one that holds however else a request reaches this Worker.
+ */
+async function readTurnCommand(request: Request): Promise<ClientTurnCommandV1> {
+  const contentLength = Number(request.headers.get("content-length") ?? "0");
+  if (contentLength > TURN_BODY_MAX_BYTES_V1) {
+    throw new RequestTooLargeError();
+  }
+  try {
+    return decodeClientTurnCommandV1(await request.json());
+  } catch (error) {
+    // The decoder's own bound on `text`. Same refusal, said the same way: a
+    // body under the wire limit can still carry a message over the text one.
+    if (
+      error instanceof Error &&
+      /turn command\.text\b.*\b(exceeds|too long|too large)/i.test(
+        error.message,
+      )
+    ) {
+      throw new RequestTooLargeError();
+    }
+    throw error;
+  }
+}
+export function createUserApplication() {
+  const route = createUserApplicationRoute();
+  /*
+   * The User application's own outermost wrapper.
+   *
+   * This Worker is loaded into its own isolate and receives its own `Request`,
+   * so the gateway's drain does nothing for it: an early return here — a 404
+   * on a POST, a body refused for its size — is exactly the shape that makes
+   * workerd tear the isolate down with "Can't read from request stream after
+   * response has been sent". Every answer passes through the drain, and the
+   * size refusal is given before any route runs so an oversized send is never
+   * parsed.
+   */
+  return async (
+    request: Request,
+    env: UserApplicationEnv,
+  ): Promise<Response> => {
+    let oversized = false;
+    try {
+      oversized = turnBodyIsOversizedV1(request, new URL(request.url));
+    } catch {
+      // An unparseable URL is the route's 400 to give, not this guard's.
+    }
+    if (oversized) {
+      return drainedAnswerV1(request, jsonError(413, TURN_TOO_LONG_MESSAGE_V1));
+    }
+    // This Worker's `fetch` is an entry point of its own: a route that throws
+    // has no caller left inside the isolate, and the log showed exactly that —
+    // `BotNotFoundError` five times in one window, then a refused Turn, then
+    // the process exiting. A Bot that is not there is a 404 the client can act
+    // on; anything else is a 500 that still carries a readable reason, and the
+    // isolate survives to answer the next request.
+    return drainedAnswerV1(
+      request,
+      await answeredEntryV1("request failed", () => route(request, env)),
+    );
+  };
+}
+function createUserApplicationRoute() {
+  return async (
+    request: Request,
+    env: UserApplicationEnv,
+  ): Promise<Response> => {
+    let url: URL;
+    try {
+      url = new URL(request.url);
+    } catch {
+      return jsonError(400, "invalid request URL");
+    }
+    if (request.method === "GET" && url.pathname === "/") {
+      return withSecurityHeaders(
+        new Response(
+          appHtml(
+            env.DEPLOYMENT.userId,
+            env.DEPLOYMENT.applicationHash,
+            hostedAuthMode(request),
+            hostedIsAdmin(request),
+          ),
+          {
+            headers: { "content-type": "text/html; charset=utf-8" },
+          },
+        ),
+        url,
+      );
+    }
+    if (request.method === "GET" && url.pathname === "/favicon.ico") {
+      // Browsers request `/favicon.ico` by convention even when a link element
+      // names it, so the site icon answers on that one path in its real type.
+      return withSecurityHeaders(
+        new Response(APP_ICON, {
+          headers: {
+            "content-type": "image/png",
+            "cache-control": "no-cache",
+          },
+        }),
+        url,
+      );
+    }
+    if (request.method === "GET" && BRAND_V1.whatsNew) {
+      const picture = whatsNewImageResponseV1(url.pathname);
+      if (picture) {
+        return withSecurityHeaders(picture, url);
+      }
+    }
+    if (request.method === "GET" && url.pathname === "/app-manifest") {
+      return Response.json({
+        schemaVersion: 1,
+        deployment: env.DEPLOYMENT,
+        // The client needs model-provider facts even when a Package is
+        // platform-owned, so every Package is projected and each carries the
+        // ownership its definition declares; enablement surfaces omit those
+        // rows while model resolution still sees them.
+        packages: foundationPackageCatalogV1(BRAND_V1).entries.map((pkg) => ({
+          id: pkg.id,
+          displayName: pkg.displayName,
+          version: FOUNDATION_PACKAGE_VERSION_V1,
+          ...(pkg.platformOwned ? { platformOwned: true } : {}),
+          ...(pkg.settings ? { settings: pkg.settings } : {}),
+          ...(pkg.capabilities ? { capabilities: pkg.capabilities } : {}),
+          ...(pkg.connectionTypes
+            ? { connectionTypes: pkg.connectionTypes }
+            : {}),
+        })),
+      });
+    }
+    const notificationMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/notifications$/,
+    );
+    if (notificationMatch) {
+      let notificationBotId: string;
+      try {
+        notificationBotId = decodeURIComponent(notificationMatch[1]);
+      } catch {
+        return jsonError(400, "invalid bot id");
+      }
+      try {
+        notificationBotId = decodeBotIdV1(notificationBotId);
+      } catch {
+        return jsonError(400, "invalid bot id");
+      }
+      const missingBot = await requireRegisteredBot(env, notificationBotId);
+      if (missingBot) return missingBot;
+      if (request.method === "GET") {
+        return Response.json({
+          schemaVersion: 1,
+          notifications: await env.BOT_STATE.listNotifications({
+            schemaVersion: 1,
+            botId: notificationBotId,
+          }),
+        } satisfies ClientNotificationListV1);
+      }
+      if (request.method !== "POST") {
+        return jsonError(405, "method not allowed");
+      }
+      let command;
+      try {
+        command = decodeClientNotificationAcknowledgementCommandV1(
+          await request.json(),
+        );
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error
+            ? error.message
+            : "invalid notification acknowledgement",
+        );
+      }
+      await env.BOT_STATE.acknowledgeNotification({
+        schemaVersion: 1,
+        botId: notificationBotId,
+        notificationId: command.notificationId,
+      });
+      return Response.json({
+        schemaVersion: 1,
+        status: "acknowledged",
+      } satisfies ClientNotificationAcknowledgementV1);
+    }
+    // Approval cards (row 53). Bot-scoped and beside the notifications route,
+    // because a pending decision is Bot state the User answers, not a Package
+    // surface of its own.
+    const approvalsMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/approvals$/,
+    );
+    const approvalMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/approvals\/([^/]+)$/,
+    );
+    if (approvalsMatch || approvalMatch) {
+      let approvalBotId: string;
+      try {
+        approvalBotId = decodeBotIdV1(
+          decodeURIComponent((approvalsMatch ?? approvalMatch)![1]),
+        );
+      } catch {
+        return jsonError(400, "invalid bot id");
+      }
+      const missing = await requireRegisteredBot(env, approvalBotId);
+      if (missing) return missing;
+      if (approvalsMatch) {
+        if (request.method !== "GET") {
+          return jsonError(405, "method not allowed");
+        }
+        try {
+          return Response.json(
+            await env.BOT_STATE.listApprovals({
+              schemaVersion: 1,
+              botId: approvalBotId,
+            }),
+          );
+        } catch (error) {
+          return botFailure(error, "approvals failed");
+        }
+      }
+      if (request.method !== "POST") {
+        return jsonError(405, "method not allowed");
+      }
+      let approvalId: string;
+      let command;
+      try {
+        approvalId = decodeURIComponent(approvalMatch![2]);
+        if (!isRpcIdentifier(approvalId)) {
+          throw new Error("approval id is invalid");
+        }
+        command = decodeApprovalDecisionCommandV1(await request.json());
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "invalid approval decision",
+        );
+      }
+      try {
+        // The decision is durable before this answers: "admit input durably
+        // before acknowledging" applies to a person's answer as much as to a
+        // Turn's, and a replay reads back the one decision that was recorded.
+        return Response.json(
+          await env.BOT_STATE.decideApproval({
+            schemaVersion: 1,
+            botId: approvalBotId,
+            approvalId,
+            command,
+          }),
+        );
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "approval decision failed";
+        const name = error instanceof Error ? error.name : "";
+        if (name === "ApprovalNotFoundError") return jsonError(404, message);
+        return jsonError(500, message);
+      }
+    }
+    // Cards (ADR 0030). Beside the approvals it can carry: a GET is the Bot's
+    // surfaces as they stand, a GET of one id is that surface whatever the
+    // listing's byte budget cut, and a POST is one action on one of them,
+    // which the kernel — never the Card — decides the meaning of.
+    const cardsMatch = url.pathname.match(/^\/api\/bots\/([^/]+)\/cards$/);
+    const cardMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/cards\/([^/]+)$/,
+    );
+    if (cardsMatch || cardMatch) {
+      let cardBotId: string;
+      try {
+        cardBotId = decodeBotIdV1(
+          decodeURIComponent((cardsMatch ?? cardMatch)![1]!),
+        );
+      } catch {
+        return jsonError(400, "invalid bot id");
+      }
+      const missing = await requireRegisteredBot(env, cardBotId);
+      if (missing) return missing;
+      if (cardMatch) {
+        if (request.method !== "GET") {
+          return jsonError(405, "method not allowed");
+        }
+        let surfaceId: string;
+        try {
+          surfaceId = decodeCardSurfaceIdV1(decodeURIComponent(cardMatch[2]!));
+        } catch (error) {
+          return jsonError(
+            400,
+            error instanceof Error ? error.message : "invalid surface id",
+          );
+        }
+        try {
+          return Response.json(
+            await env.BOT_STATE.readCard({
+              schemaVersion: 1,
+              botId: cardBotId,
+              surfaceId,
+            }),
+          );
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : "card read failed";
+          const name = error instanceof Error ? error.name : "";
+          if (name === "CardNotFoundError") return jsonError(404, message);
+          if (name === "CardDecodeError") return jsonError(400, message);
+          return jsonError(500, message);
+        }
+      }
+      if (request.method === "GET") {
+        try {
+          return Response.json(
+            await env.BOT_STATE.listCards({
+              schemaVersion: 1,
+              botId: cardBotId,
+            }),
+          );
+        } catch (error) {
+          return botFailure(error, "cards failed");
+        }
+      }
+      if (request.method !== "POST") {
+        return jsonError(405, "method not allowed");
+      }
+      let command;
+      try {
+        command = decodeCardActionCommandV1(await request.json());
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "invalid card action",
+        );
+      }
+      try {
+        return Response.json(
+          await env.BOT_STATE.cardAction({
+            schemaVersion: 1,
+            botId: cardBotId,
+            command,
+          }),
+        );
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "card action failed";
+        const name = error instanceof Error ? error.name : "";
+        // A surface that has moved is not a fault: the person answered the
+        // card they were shown, and the client redraws and asks again. A
+        // refused action is the client's, not the kernel's.
+        if (name === "CardStaleError") return jsonError(409, message);
+        if (name === "CardNotFoundError") return jsonError(404, message);
+        if (name === "CardDecodeError") return jsonError(400, message);
+        // An approval a Card named but the kernel does not hold is the same
+        // answer the approvals route gives for it, and for the same reason.
+        if (name === "ApprovalNotFoundError") return jsonError(404, message);
+        if (name === "ApprovalDecodeError") return jsonError(400, message);
+        return jsonError(500, message);
+      }
+    }
+    // A secret a person typed on a Bot's secret-request card. The body is
+    // decoded without ever being echoed, handed to the Bot that asked, and
+    // sealed by the User object before this answers; nothing here keeps,
+    // logs or repeats it, and a failure answers in fixed words.
+    const secretMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/secret-requests\/([^/]+)$/,
+    );
+    if (secretMatch) {
+      if (request.method !== "POST") {
+        return jsonError(405, "method not allowed");
+      }
+      let secretBotId: string;
+      let requestId: string;
+      let command;
+      try {
+        secretBotId = decodeBotIdV1(decodeURIComponent(secretMatch[1]!));
+        requestId = decodeURIComponent(secretMatch[2]!);
+        if (!isSecretRequestIdV1(requestId)) {
+          return jsonError(404, "That secret request was not found.");
+        }
+      } catch {
+        return jsonError(400, "invalid bot id");
+      }
+      const missing = await requireRegisteredBot(env, secretBotId);
+      if (missing) return missing;
+      try {
+        command = decodeSecretSubmitCommandV1(await request.json());
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof SecretDecodeError
+            ? error.message
+            : "That secret couldn't be read.",
+        );
+      }
+      try {
+        return Response.json(
+          await env.BOT_STATE.submitSecret({
+            schemaVersion: 1,
+            botId: secretBotId,
+            requestId,
+            command,
+          }),
+          { headers: { "cache-control": "no-store" } },
+        );
+      } catch (error) {
+        const name = error instanceof Error ? error.name : "";
+        if (name === "SecretRequestNotFoundError") {
+          return jsonError(404, "That secret request was not found.");
+        }
+        if (name === "SecretLimitError" && error instanceof Error) {
+          return jsonError(409, error.message);
+        }
+        return jsonError(500, "The secret couldn't be saved. Try again.");
+      }
+    }
+    const skillsMatch = url.pathname.match(/^\/api\/bots\/([^/]+)\/skills$/);
+    const workspaceFileMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/workspace\/file$/,
+    );
+    const turnMatch = url.pathname.match(/^\/api\/bots\/([^/]+)\/turns$/);
+    const lookupMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/turns\/([^/]+)$/,
+    );
+    const fenceMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/turns\/([^/]+)\/fence$/,
+    );
+    const questionsMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/turns\/([^/]+)\/questions$/,
+    );
+    const stopMatch = url.pathname.match(
+      /^\/api\/bots\/([^/]+)\/turns\/([^/]+)\/stop$/,
+    );
+    if (
+      !skillsMatch &&
+      !workspaceFileMatch &&
+      !turnMatch &&
+      !lookupMatch &&
+      !questionsMatch &&
+      !fenceMatch &&
+      !stopMatch
+    ) {
+      return jsonError(404, "not found");
+    }
+    let botId: string;
+    try {
+      const matched =
+        skillsMatch ??
+        workspaceFileMatch ??
+        turnMatch ??
+        lookupMatch ??
+        questionsMatch ??
+        fenceMatch ??
+        stopMatch;
+      botId = decodeURIComponent(matched![1]);
+    } catch {
+      return jsonError(400, "invalid bot id");
+    }
+    try {
+      botId = decodeBotIdV1(botId);
+    } catch {
+      return jsonError(400, "invalid bot id");
+    }
+    const missingBot = await requireRegisteredBot(
+      env,
+      botId,
+      request.method === "GET" &&
+        Boolean(turnMatch || lookupMatch || questionsMatch),
+    );
+    if (missingBot) return missingBot;
+    // An installed client older than protocol 3 refuses a Run it does not
+    // know every field of, so the files are left off what it is sent.
+    const forClient = <T>(value: T): T =>
+      clientProtocolOfV1(request.headers.get("x-frockbot-client")) >=
+      RUN_ATTACHMENTS_PROTOCOL_V1
+        ? value
+        : withoutRunAttachmentsV1(value);
+    if (skillsMatch) {
+      // Read-only, and named refs only: the popover learns which Skills exist
+      // and never receives a body.
+      if (request.method !== "GET") return jsonError(405, "method not allowed");
+      try {
+        return Response.json(
+          await env.BOT_STATE.listSkills({ schemaVersion: 1, botId }),
+        );
+      } catch (error) {
+        return botFailure(error, "skill catalog failed");
+      }
+    }
+    if (workspaceFileMatch) {
+      // Read-only, and the durable root and path arrive as one encoded
+      // `WorkspacePathV1` so the route cannot assemble a root the decoder
+      // would not accept. The bytes come from object storage; no Computer
+      // wakes to serve this.
+      if (request.method !== "GET") return jsonError(405, "method not allowed");
+      const encoded = url.searchParams.get("path");
+      if (!encoded) return jsonError(400, "a workspace path is required");
+      let path: unknown;
+      try {
+        path = JSON.parse(encoded);
+      } catch {
+        return jsonError(400, "invalid workspace path");
+      }
+      try {
+        const answer = await env.BOT_STATE.readWorkspaceFileV1({
+          schemaVersion: 1,
+          botId,
+          path,
+        });
+        if (answer.status !== "ok") {
+          return jsonError(
+            answer.status === "not-found" ? 404 : 409,
+            "reason" in answer ? answer.reason : "workspace read failed",
+          );
+        }
+        const binary = atob(answer.bytesBase64);
+        const bytes = new Uint8Array(binary.length);
+        for (let index = 0; index < binary.length; index += 1) {
+          bytes[index] = binary.charCodeAt(index);
+        }
+        return new Response(bytes, {
+          headers: {
+            "content-type": "application/octet-stream",
+            "cache-control": "private, max-age=60",
+            etag: `"${answer.contentHash}"`,
+          },
+        });
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "workspace read failed",
+        );
+      }
+    }
+    if (fenceMatch) {
+      if (request.method !== "POST") {
+        return jsonError(405, "method not allowed");
+      }
+      let query: ClientRunLookupQueryV1;
+      try {
+        decodeClientRunAdmissionFenceCommandV1(await request.json());
+        query = decodeClientRunLookupQueryV1({
+          schemaVersion: 1,
+          runId: decodeURIComponent(fenceMatch[2]),
+        });
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "invalid admission fence",
+        );
+      }
+      try {
+        return Response.json(
+          forClient(
+            await env.BOT_STATE.fenceRunAdmission({
+              schemaVersion: 1,
+              botId,
+              query,
+            }),
+          ),
+        );
+      } catch (error) {
+        return botFailure(error, "admission fence failed");
+      }
+    }
+    if (stopMatch) {
+      if (request.method !== "POST") {
+        return jsonError(405, "method not allowed");
+      }
+      let command: ClientRunStopCommandV1;
+      try {
+        const body: unknown = await request.json();
+        command = decodeClientRunStopCommandV1(body);
+        if (command.runId !== decodeURIComponent(stopMatch[2])) {
+          throw new Error("run stop command does not match the request path");
+        }
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "invalid stop command",
+        );
+      }
+      try {
+        return Response.json(
+          forClient(
+            await env.BOT_STATE.stopRun({ schemaVersion: 1, botId, command }),
+          ),
+        );
+      } catch (error) {
+        return jsonError(
+          409,
+          error instanceof Error ? error.message : "Stop failed",
+        );
+      }
+    }
+    if (questionsMatch) {
+      if (request.method !== "GET") {
+        return jsonError(405, "method not allowed");
+      }
+      let query: ClientRunLookupQueryV1;
+      try {
+        if ([...url.searchParams.keys()].length > 0) {
+          throw new Error("run questions do not accept URL parameters");
+        }
+        query = decodeClientRunLookupQueryV1({
+          schemaVersion: 1,
+          runId: decodeURIComponent(questionsMatch[2]),
+        });
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "invalid run questions",
+        );
+      }
+      try {
+        return Response.json(
+          await env.BOT_STATE.runQuestions({ schemaVersion: 1, botId, query }),
+        );
+      } catch (error) {
+        return botFailure(error, "run questions failed");
+      }
+    }
+    if (lookupMatch) {
+      if (request.method !== "GET") {
+        return jsonError(405, "method not allowed");
+      }
+      let query: ClientRunLookupQueryV1;
+      try {
+        if ([...url.searchParams.keys()].length > 0) {
+          throw new Error("run lookup query does not accept URL parameters");
+        }
+        query = decodeClientRunLookupQueryV1({
+          schemaVersion: 1,
+          runId: decodeURIComponent(lookupMatch[2]),
+        });
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "invalid run lookup",
+        );
+      }
+      try {
+        return Response.json(
+          forClient(
+            await env.BOT_STATE.lookupRun({ schemaVersion: 1, botId, query }),
+          ),
+        );
+      } catch (error) {
+        return botFailure(error, "run lookup failed");
+      }
+    }
+    if (request.method === "GET") {
+      let query;
+      try {
+        const queryKeys = [...url.searchParams.keys()];
+        if (
+          queryKeys.some((key) => key !== "before" && key !== "with") ||
+          url.searchParams.getAll("before").length > 1 ||
+          url.searchParams.getAll("with").length > 1
+        ) {
+          throw new Error("run list query is invalid");
+        }
+        const before = url.searchParams.get("before");
+        const counterpart = url.searchParams.get("with");
+        query = decodeClientRunListQueryV1({
+          schemaVersion: 1,
+          ...(before === null ? {} : { before }),
+          ...(counterpart === null
+            ? {}
+            : { counterpart: parseExchangeCounterpartParamV1(counterpart) }),
+        });
+      } catch (error) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "invalid run page",
+        );
+      }
+      try {
+        return Response.json(
+          forClient(
+            await env.BOT_STATE.listRuns({ schemaVersion: 1, botId, query }),
+          ),
+        );
+      } catch (error) {
+        // A stored run the current codec refuses is a visible failure with
+        // its reason, never a crash of the whole application Worker.
+        return botFailure(error, "run list failed");
+      }
+    }
+    if (request.method !== "POST") return jsonError(405, "method not allowed");
+    let turnCommand: ClientTurnCommandV1;
+    try {
+      turnCommand = await readTurnCommand(request);
+    } catch (error) {
+      if (isRequestTooLargeV1(error)) {
+        return jsonError(413, TURN_TOO_LONG_MESSAGE_V1);
+      }
+      return jsonError(
+        400,
+        error instanceof Error ? error.message : "invalid prompt",
+      );
+    }
+    try {
+      return Response.json(
+        // Every Turn a client asks for is admitted as `chat`. The turn type is
+        // never carried here: `decodeClientTurnCommandV1` accepts exact keys,
+        // and the Bot Durable Object's run RPC accepts exact keys too, so a
+        // client cannot name one, and an absent turn type means `chat`. Only an
+        // in-Durable-Object producer may admit another type.
+        //
+        // The answer is the admission receipt. Execution continues on the Bot
+        // object's drive and recovery alarm; this response does not wait for
+        // either.
+        await env.BOT_STATE.admitRun({
+          schemaVersion: 1,
+          botId,
+          command: {
+            runId: turnCommand.commandId,
+            sessionId: `${env.DEPLOYMENT.userId}:${botId}`,
+            acceptedAt: new Date().toISOString(),
+            text: turnCommand.text,
+            ...(turnCommand.retryOf ? { retryOf: turnCommand.retryOf } : {}),
+            // Refs only: the client names a Skill and never carries its text,
+            // so what a Turn runs on is still whatever the instruction root
+            // holds at the generation the Turn resolves.
+            ...(turnCommand.skills ? { skills: turnCommand.skills } : {}),
+            // Refs again: the bytes were admitted by the upload route, and
+            // the Bot resolves each name against its own uploads.
+            ...(turnCommand.attachments
+              ? { attachments: turnCommand.attachments }
+              : {}),
+          },
+        }),
+        { status: 202 },
+      );
+    } catch (error) {
+      const refusal = turnRefusal(error);
+      if (refusal) return Response.json(refusal, { status: 409 });
+      return botFailure(error, "Bot turn failed");
+    }
+  };
+}
+const fetchUserApplication = createUserApplication();
+export default {
+  fetch: fetchUserApplication,
+} satisfies ExportedHandler<UserApplicationEnv>;