@frockbot/cloudflare 0.0.0 → 0.7.291

package/src/insights.ts

@@ -0,0 +1,15 @@
+/**
+ * Cloudflare Insights, the zone's own analytics.
+ *
+ * The beacon is injected into every HTML response by the zone, above this
+ * Worker, so a page loads it whether or not that page's policy allows it. A
+ * policy that does not name these origins does not remove the beacon; it turns
+ * every page load into a refused request and a red console error. The
+ * application's policy therefore names them, and does not pretend the feature
+ * is off.
+ */
+
+/** Where the zone's injected beacon script is served from. */
+export const INSIGHTS_SCRIPT_ORIGIN = "https://static.cloudflareinsights.com";
+/** Where that beacon posts its measurements — a different host from the script. */
+export const INSIGHTS_REPORT_ORIGIN = "https://cloudflareinsights.com";

package/src/machine-messages-cleanup.ts

@@ -0,0 +1,121 @@
+// Disposable pre-user cleanup for first-party Messages (ADR 0037).
+//
+// Messages left three shapes no decoder accepts any more: a machine record
+// that reports the `messages` capability or carries its permission report, a
+// queued command whose op is `messages`, and a Bot's intent for one. The User
+// object rewrites the records and drops the commands with their requeue
+// counters; the Bot drops its intents. A result carries no op, so results stay.
+// Each walk runs once per object, in pages.
+
+const USER_RECEIPT = "maintenance:machine-messages:2026-09-25";
+const BOT_RECEIPT = "maintenance:machine-messages-intents:2026-09-25";
+const MACHINE_PREFIX = "machine:";
+const MACHINE_QUEUE_PREFIX = "machine-queue:";
+const MACHINE_REQUEUE_PREFIX = "machine-requeue:";
+const MACHINE_INTENT_PREFIX = "machine-command:";
+const PAGE = 128;
+
+export interface MachineMessagesCleanupStorageV1 {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  put(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list<T = unknown>(options: {
+    prefix: string;
+    limit: number;
+    startAfter?: string;
+  }): Promise<Map<string, T>>;
+}
+
+type Stored = Record<string, unknown>;
+
+function record(value: unknown): Stored | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return undefined;
+  return value as Stored;
+}
+
+function isMessagesOp(value: unknown): boolean {
+  return record(record(value)?.op)?.kind === "messages";
+}
+
+/** The machine record without Messages, or `undefined` to keep it. */
+export function withoutMessagesCapabilityV1(
+  value: unknown,
+): Stored | undefined {
+  const machine = record(value);
+  if (!machine) return undefined;
+  const capabilities = Array.isArray(machine.capabilities)
+    ? machine.capabilities
+    : undefined;
+  const reportsMessages = capabilities?.includes("messages") === true;
+  if (!reportsMessages && !Object.hasOwn(machine, "messagesPermissions"))
+    return undefined;
+  const { messagesPermissions: _retired, ...kept } = machine;
+  return reportsMessages
+    ? {
+        ...kept,
+        capabilities: capabilities!.filter((entry) => entry !== "messages"),
+      }
+    : kept;
+}
+
+async function walk(
+  storage: MachineMessagesCleanupStorageV1,
+  prefix: string,
+  visit: (key: string, value: unknown) => Promise<void>,
+): Promise<void> {
+  let startAfter: string | undefined;
+  for (;;) {
+    const page = await storage.list({
+      prefix,
+      limit: PAGE,
+      ...(startAfter ? { startAfter } : {}),
+    });
+    for (const [key, value] of page) await visit(key, value);
+    if (page.size < PAGE) return;
+    startAfter = [...page.keys()].at(-1);
+  }
+}
+
+export async function cleanUserMachineMessagesV1(
+  storage: MachineMessagesCleanupStorageV1,
+  now: Date = new Date(),
+): Promise<void> {
+  if (await storage.get(USER_RECEIPT)) return;
+  let machines = 0;
+  let commands = 0;
+  await walk(storage, MACHINE_PREFIX, async (key, value) => {
+    const cleaned = withoutMessagesCapabilityV1(value);
+    if (!cleaned) return;
+    await storage.put(key, cleaned);
+    machines += 1;
+  });
+  await walk(storage, MACHINE_QUEUE_PREFIX, async (key, value) => {
+    if (!isMessagesOp(value)) return;
+    await storage.delete(key);
+    const commandId = record(value)?.commandId;
+    if (typeof commandId === "string") {
+      await storage.delete(`${MACHINE_REQUEUE_PREFIX}${commandId}`);
+    }
+    commands += 1;
+  });
+  await storage.put(USER_RECEIPT, {
+    at: now.toISOString(),
+    machines,
+    commands,
+  });
+}
+
+export async function cleanBotMachineMessagesV1(
+  storage: MachineMessagesCleanupStorageV1,
+  now: Date = new Date(),
+): Promise<void> {
+  if (await storage.get(BOT_RECEIPT)) return;
+  let intents = 0;
+  await walk(storage, MACHINE_INTENT_PREFIX, async (key, value) => {
+    if (!isMessagesOp(value)) return;
+    await storage.delete(key);
+    intents += 1;
+  });
+  await storage.put(BOT_RECEIPT, { at: now.toISOString(), intents });
+}

package/src/machine-socket.ts

@@ -0,0 +1,164 @@
+// A registered machine's socket, as the User Durable Object holds it.
+//
+// The gateway verifies the machine token at the edge and forwards the upgrade
+// here with what it proved in internal headers, the way the Bot-state channel
+// carries identity. The token itself stops at the gateway: what crosses is its
+// claims and its digest, and the Durable Object checks the digest against the
+// machine record before it accepts anything.
+//
+// The sockets are hibernating and tagged by machine, so an idle desktop costs
+// nothing and presence is simply whether a socket with that tag is open.
+
+import {
+  MachineTokenError,
+  machineTokenClaimsV1,
+  type MachinePlatformV1,
+  type MachineSocketFrameV1,
+} from "@frockbot/core/machine-protocol";
+import type { MachineCallV1 } from "@frockbot/app/machine/backend";
+import type { MachineSocketsV1 } from "@frockbot/app/machine/user";
+
+export const MACHINE_SOCKET_INTERNAL_PATH_V1 = "/internal/machine-socket/v1";
+
+const USER_HEADER = "x-frockbot-user-id";
+const MACHINE_HEADER = "x-frockbot-machine-id";
+const CLAIMS_HEADER = "x-frockbot-machine-claims";
+const DIGEST_HEADER = "x-frockbot-machine-token-digest";
+const DIGEST = /^[0-9a-f]{64}$/;
+const OPEN = 1;
+
+export function machineSocketTagV1(machineId: string): string {
+  return `machine:${machineId}`;
+}
+
+/** What each accepted socket carries through hibernation. */
+export interface MachineSocketAttachmentV1 {
+  machineId: string;
+  tokenDigest: string;
+  keyVersion: number;
+  /** Which device modules the machine is sent. */
+  platform: MachinePlatformV1;
+}
+
+/** The upgrade, as the gateway hands it to the User Durable Object. */
+export function internalMachineSocketRequestV1(
+  userId: string,
+  call: MachineCallV1,
+  request: Request,
+): Request {
+  const headers = new Headers(request.headers);
+  headers.delete("authorization");
+  headers.set(USER_HEADER, userId);
+  headers.set(MACHINE_HEADER, call.machineId);
+  headers.set(CLAIMS_HEADER, JSON.stringify(call.claims));
+  headers.set(DIGEST_HEADER, call.tokenDigest);
+  return new Request(
+    new URL(
+      MACHINE_SOCKET_INTERNAL_PATH_V1,
+      "https://user-configuration.internal",
+    ),
+    { method: "GET", headers },
+  );
+}
+
+/** The forwarded call, or a refusal. */
+export function readMachineSocketCallV1(request: Request): {
+  userId: string;
+  call: MachineCallV1;
+} {
+  const userId = request.headers.get(USER_HEADER);
+  const machineId = request.headers.get(MACHINE_HEADER);
+  const claims = request.headers.get(CLAIMS_HEADER);
+  const tokenDigest = request.headers.get(DIGEST_HEADER);
+  if (!userId || !machineId || !claims || !tokenDigest) {
+    throw new MachineTokenError(401, "machine token is required");
+  }
+  if (!DIGEST.test(tokenDigest)) {
+    throw new MachineTokenError(401, "machine token is invalid");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(claims);
+  } catch {
+    throw new MachineTokenError(401, "machine token is invalid");
+  }
+  return {
+    userId,
+    call: { machineId, claims: machineTokenClaimsV1(parsed), tokenDigest },
+  };
+}
+
+/** The Contribution's view of the sockets, over the Durable Object's own list. */
+export function durableObjectMachineSocketsV1(
+  ctx: DurableObjectState,
+): MachineSocketsV1 {
+  const open = (machineId: string): WebSocket[] =>
+    ctx
+      .getWebSockets(machineSocketTagV1(machineId))
+      .filter((socket) => socket.readyState === OPEN);
+  return {
+    push(machineId: string, frame: MachineSocketFrameV1): void {
+      if (frame.type === "commands" && frame.commands.length === 0) return;
+      const encoded = JSON.stringify(frame);
+      for (const socket of open(machineId)) {
+        try {
+          socket.send(encoded);
+        } catch {
+          // A socket that cannot take a frame is closing; the queue is durable
+          // and the machine is sent the command again when it reconnects.
+        }
+      }
+    },
+    connected: (machineId) => open(machineId).length > 0,
+    close(machineId: string, code: number, reason: string): void {
+      for (const socket of ctx.getWebSockets(machineSocketTagV1(machineId))) {
+        try {
+          socket.close(code, reason);
+        } catch {
+          // Already closed.
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Send every open machine socket its platform's frame. The frame is built once
+ * per platform, however many machines share it.
+ */
+export function broadcastMachineFrameV1(
+  ctx: DurableObjectState,
+  frameFor: (platform: MachinePlatformV1) => MachineSocketFrameV1,
+): void {
+  const encoded = new Map<MachinePlatformV1, string>();
+  for (const socket of ctx.getWebSockets()) {
+    if (socket.readyState !== OPEN) continue;
+    const attachment =
+      socket.deserializeAttachment() as MachineSocketAttachmentV1 | null;
+    if (!attachment) continue;
+    let frame = encoded.get(attachment.platform);
+    if (frame === undefined) {
+      frame = JSON.stringify(frameFor(attachment.platform));
+      encoded.set(attachment.platform, frame);
+    }
+    try {
+      socket.send(frame);
+    } catch {
+      // A closing socket is sent the whole list again when it reconnects.
+    }
+  }
+}
+
+/** Every machine with an open socket, and the platform it is sent modules for. */
+export function connectedMachinePlatformsV1(
+  ctx: DurableObjectState,
+): Map<string, MachinePlatformV1> {
+  const connected = new Map<string, MachinePlatformV1>();
+  for (const socket of ctx.getWebSockets()) {
+    if (socket.readyState !== OPEN) continue;
+    const attachment =
+      socket.deserializeAttachment() as MachineSocketAttachmentV1 | null;
+    if (attachment) connected.set(attachment.machineId, attachment.platform);
+  }
+  return connected;
+}

package/src/memory-records.ts

@@ -0,0 +1,181 @@
+// Cloudflare Durable Object SQL adapter for canonical Memory.
+//
+// Alarm arming stays on the object's existing async alarm owner: SQLite
+// `transactionSync` cannot enclose `setAlarm`. Jobs still carry `next_attempt_at`
+// so eviction re-arms from the due index.
+
+import { MemoryEngineV1 } from "@frockbot/app/memory/engine";
+import { createMemoryEmbedder } from "@frockbot/app/memory/embeddings";
+import {
+  drainMemoryProcessingV1,
+  type MemoryDrainResultV1,
+  type MemoryProcessingAdaptersV1,
+} from "@frockbot/app/memory/processing";
+import {
+  MemoryRecordsV1,
+  type MemoryRemoteOwnerV1,
+} from "@frockbot/app/memory/owner";
+import type {
+  MemoryBrowseRequestV1,
+  MemoryBrowseResultV1,
+  MemoryExpandRequestV1,
+  MemoryExpandResultV1,
+  MemoryForgetRequestV1,
+  MemoryForgetResultV1,
+  MemoryPreparedCoreRequestV1,
+  MemoryPreparedCoreResultV1,
+  MemoryRecallRequestV1,
+  MemoryRecallResultV1,
+  MemoryWriteRequestV1,
+  MemoryWriteResultV1,
+} from "@frockbot/app/memory/records";
+import type { MemorySqlStorageV1 } from "@frockbot/app/memory/sql";
+import type {
+  MemoryAiBinding,
+  MemoryVectorIndex,
+} from "@frockbot/app/memory/types";
+import { remoteCallV1 } from "@frockbot/core/contracts";
+
+export interface DurableMemoryStorageV1 {
+  sql: MemorySqlStorageV1["sql"];
+  transactionSync<T>(callback: () => T): T;
+}
+
+export function durableObjectHasSqlV1(
+  storage: object,
+): storage is DurableMemoryStorageV1 {
+  return (
+    "sql" in storage &&
+    typeof (storage as { transactionSync?: unknown }).transactionSync ===
+      "function"
+  );
+}
+
+export function createDurableMemoryStorageV1(
+  storage: DurableMemoryStorageV1,
+): MemorySqlStorageV1 {
+  return {
+    sql: storage.sql,
+    transactionSync: (callback) => storage.transactionSync(callback),
+  };
+}
+
+export function createBotMemoryEngineV1(
+  storage: DurableMemoryStorageV1,
+): MemoryEngineV1 {
+  const engine = new MemoryEngineV1({
+    storage: createDurableMemoryStorageV1(storage),
+    ownedKinds: ["bot"],
+  });
+  engine.open();
+  return engine;
+}
+
+export function createUserMemoryEngineV1(
+  storage: DurableMemoryStorageV1,
+): MemoryEngineV1 {
+  const engine = new MemoryEngineV1({
+    storage: createDurableMemoryStorageV1(storage),
+    ownedKinds: ["user", "groupChat"],
+  });
+  engine.open();
+  return engine;
+}
+
+export type MemoryOperateActionV1 =
+  "write" | "forget" | "recall" | "expand" | "browse" | "preparedCore";
+
+export interface UserMemoryRecordsRpc {
+  operateMemory(input: unknown): Promise<unknown>;
+}
+
+export function createUserMemoryRecordsRemoteV1(
+  rpc: UserMemoryRecordsRpc,
+  identity: { userId: string; botId: string },
+): MemoryRemoteOwnerV1 {
+  const call = async <T>(
+    action: MemoryOperateActionV1,
+    request: unknown,
+  ): Promise<T> =>
+    remoteCallV1("shared Memory", () =>
+      rpc.operateMemory({
+        schemaVersion: 1,
+        userId: identity.userId,
+        botId: identity.botId,
+        action,
+        request,
+      }),
+    ) as Promise<T>;
+  return {
+    write: (request) => call<MemoryWriteResultV1>("write", request),
+    forget: (request) => call<MemoryForgetResultV1>("forget", request),
+    recall: (request) => call<MemoryRecallResultV1>("recall", request),
+    expand: (request) => call<MemoryExpandResultV1>("expand", request),
+    browse: (request) => call<MemoryBrowseResultV1>("browse", request),
+    preparedCore: (request) =>
+      call<MemoryPreparedCoreResultV1>("preparedCore", request),
+  };
+}
+
+export function createBotMemoryRecordsV1(
+  storage: DurableMemoryStorageV1,
+  remote: MemoryRemoteOwnerV1,
+): MemoryRecordsV1 {
+  return new MemoryRecordsV1({
+    owner: "bot",
+    engine: createBotMemoryEngineV1(storage),
+    remote,
+  });
+}
+
+export function dispatchMemoryOperateV1(
+  engine: MemoryEngineV1,
+  action: MemoryOperateActionV1,
+  request: unknown,
+):
+  | MemoryWriteResultV1
+  | MemoryForgetResultV1
+  | MemoryRecallResultV1
+  | MemoryExpandResultV1
+  | MemoryBrowseResultV1
+  | MemoryPreparedCoreResultV1 {
+  switch (action) {
+    case "write":
+      return engine.write(request as MemoryWriteRequestV1);
+    case "forget":
+      return engine.forget(request as MemoryForgetRequestV1);
+    case "recall":
+      return engine.recall(request as MemoryRecallRequestV1);
+    case "expand":
+      return engine.expand(request as MemoryExpandRequestV1);
+    case "browse":
+      return engine.browse(request as MemoryBrowseRequestV1);
+    case "preparedCore": {
+      const coreRequest = request as MemoryPreparedCoreRequestV1;
+      engine.refreshPreparedCores(coreRequest);
+      return engine.preparedCore(coreRequest);
+    }
+    default: {
+      const exhausted: never = action;
+      throw new Error(`unknown Memory action ${String(exhausted)}`);
+    }
+  }
+}
+
+export interface DurableMemoryIndexBindingsV1 {
+  vectors?: MemoryVectorIndex;
+  ai?: MemoryAiBinding;
+  /** What a Turn's words hold worth remembering; absent, extraction waits. */
+  extract?: MemoryProcessingAdaptersV1["extract"];
+}
+
+export async function drainDurableMemoryV1(
+  engine: MemoryEngineV1,
+  bindings: DurableMemoryIndexBindingsV1 = {},
+): Promise<MemoryDrainResultV1> {
+  const adapters: MemoryProcessingAdaptersV1 = {};
+  if (bindings.vectors) adapters.vectors = bindings.vectors;
+  if (bindings.ai) adapters.embed = createMemoryEmbedder(bindings.ai);
+  if (bindings.extract) adapters.extract = bindings.extract;
+  return drainMemoryProcessingV1(engine, adapters);
+}

package/src/memory.ts

@@ -0,0 +1,145 @@
+// The Memory seam, bound in production.
+//
+// Two things live here, and both exist because the User's Durable Object is
+// the authority for everything User-scoped:
+//
+//  1. `createRoutedWorkspaceGenerationsV1` sends the *shared* Memory root's
+//     generations — `user-memory` — to the User Durable Object over RPC, and
+//     everything else to the Bot's own ledger. Two Bots writing one shared
+//     root therefore record into one ledger, which is what makes "newest fact
+//     wins on conflict" answerable at all: the minted generation ids come
+//     from a single authority, so they order.
+//  2. `createUserMemoryGroupsV1` reads which Group Chats the Bot is in, whose
+//     Memory it may use, from the User object's list of groups.
+//
+// Both are decoded at the seam. "Cross-runtime communication uses narrow,
+// versioned DTOs, and every inbound value is decoded at its seam" — an answer
+// from another Durable Object is inbound, so it is decoded here rather than
+// trusted because of where it came from.
+import {
+  decodeWorkspaceGenerationRecordV1,
+  isWorkspaceSharedMemoryRootV1,
+  remoteCallV1,
+  type WorkspaceGenerationRecordV1,
+  type WorkspaceGenerationsV1,
+  type WorkspaceRootV1,
+} from "@frockbot/core/contracts";
+import { isGroupIdV1 } from "@frockbot/app/groups/shared";
+import type { MemoryGroupsV1 } from "@frockbot/app/memory/groups";
+
+/** The User Durable Object's Memory RPC surface, as the Bot object calls it. */
+export interface UserMemoryRpc {
+  mintWorkspaceGeneration(input: unknown): Promise<string>;
+  currentWorkspaceGeneration(input: unknown): Promise<unknown>;
+  recordWorkspaceGeneration(input: unknown): Promise<void>;
+  tombstoneWorkspaceGeneration(input: unknown): Promise<void>;
+  conflictWorkspaceGeneration(input: unknown): Promise<void>;
+  listWorkspaceConflicts(input: unknown): Promise<unknown>;
+  listMemoryGroups(input: unknown): Promise<unknown>;
+  operateMemory(input: unknown): Promise<unknown>;
+}
+
+function decodeRecord(value: unknown): WorkspaceGenerationRecordV1 | undefined {
+  return value === undefined || value === null
+    ? undefined
+    : decodeWorkspaceGenerationRecordV1(value);
+}
+
+/** `WorkspaceGenerationsV1` over the User Durable Object, for shared roots. */
+export function createUserWorkspaceGenerationsV1(
+  rpc: UserMemoryRpc,
+  userId: string,
+): WorkspaceGenerationsV1 {
+  const envelope = (extra: Record<string, unknown>) => ({
+    schemaVersion: 1,
+    userId,
+    ...extra,
+  });
+  // Every one of these crosses a Durable Object boundary, so every one gets a
+  // deadline and one retry: a User object that is mid-eviction or briefly
+  // unreachable must cost a retry, never a Turn that hangs to the platform
+  // limit with nothing on screen.
+  const call = <T>(label: string, invoke: () => Promise<T>) =>
+    remoteCallV1(label, invoke);
+  return {
+    mint: (at, root) =>
+      call("the generation ledger", () =>
+        rpc.mintWorkspaceGeneration(envelope({ at: at.toISOString(), root })),
+      ),
+    current: async (root, path) =>
+      decodeRecord(
+        await call("the generation ledger", () =>
+          rpc.currentWorkspaceGeneration(envelope({ root, path })),
+        ),
+      ),
+    record: (entry) =>
+      call("the generation ledger", () =>
+        rpc.recordWorkspaceGeneration(envelope({ entry })),
+      ),
+    tombstone: (entry) =>
+      call("the generation ledger", () =>
+        rpc.tombstoneWorkspaceGeneration(envelope({ entry })),
+      ),
+    conflict: (entry) =>
+      call("the generation ledger", () =>
+        rpc.conflictWorkspaceGeneration(envelope({ entry })),
+      ),
+    conflicts: async (root, path) => {
+      const answer = await call("the generation ledger", () =>
+        rpc.listWorkspaceConflicts(envelope({ root, path })),
+      );
+      if (!Array.isArray(answer)) return [];
+      return answer.map((value) => decodeWorkspaceGenerationRecordV1(value));
+    },
+  };
+}
+
+/**
+ * One ledger interface over two authorities, routed by the root itself.
+ *
+ * A shared Memory root belongs to the User; every other durable root belongs
+ * to the Bot whose object holds it. The routing is a function of the root and
+ * nothing else, so no caller can send a record to the wrong authority by
+ * holding the wrong handle.
+ */
+export function createRoutedWorkspaceGenerationsV1(options: {
+  bot: WorkspaceGenerationsV1;
+  user: WorkspaceGenerationsV1;
+}): WorkspaceGenerationsV1 {
+  const owner = (root: WorkspaceRootV1): WorkspaceGenerationsV1 =>
+    isWorkspaceSharedMemoryRootV1(root) ? options.user : options.bot;
+  return {
+    // A minted id must order against the other ids in the ledger that holds
+    // it, so minting follows exactly the same routing as recording: shared
+    // roots mint in the User object, the Bot's own roots in its own.
+    mint: (at, root) => owner(root).mint(at, root),
+    current: (root, path) => owner(root).current(root, path),
+    record: (entry) => owner(entry.root).record(entry),
+    tombstone: (entry) => owner(entry.root).tombstone(entry),
+    conflict: (entry) => owner(entry.root).conflict(entry),
+    conflicts: (root, path) => owner(root).conflicts(root, path),
+  };
+}
+
+/** The Bot's Group Chat membership, over the User Durable Object. */
+export function createUserMemoryGroupsV1(
+  rpc: UserMemoryRpc,
+  identity: { userId: string; botId: string },
+): MemoryGroupsV1 {
+  return {
+    memberOf: async () => {
+      const answer = await remoteCallV1("the Group Chat list", () =>
+        rpc.listMemoryGroups({
+          schemaVersion: 1,
+          userId: identity.userId,
+          botId: identity.botId,
+        }),
+      );
+      const groupIds = (answer as { groupIds?: unknown } | null)?.groupIds;
+      if (!Array.isArray(groupIds) || !groupIds.every(isGroupIdV1)) {
+        throw new Error("Group Chat membership answer is invalid");
+      }
+      return groupIds;
+    },
+  };
+}