@ixo/oracle-runtime-workers 0.9.0 → 0.11.0

package/src/plugins/matrix-group-chats/README.md

@@ -0,0 +1,70 @@
+# matrix-group-chats (Workers)
+
+**Status: under development — off by default.** The port of the Node
+runtime's `matrix-group-chats` plugin is complete and tested (unit, local
+harness, devnet), but it has not been reviewed for production use and it
+differs from Node in the ways listed below. Until that review, every
+deployment runs with the gateway's `MATRIX_GROUP_ROOMS=silent` (the default):
+the bot never speaks in a room with more than two members and captures
+nothing there. It only talks in direct rooms — the user↔oracle room and the
+task rooms it creates. Set `MATRIX_GROUP_ROOMS=gate` on the gateway to turn
+the lane on for a deployment; `answer` replies to everything (Node without
+the plugin).
+
+How it works when enabled: [operations — Rooms: group chats](../../../docs/operations.md#rooms-group-chats).
+Env knobs: [configuration](../../../docs/configuration.md#matrix).
+Drills: `pnpm test:e2e:group` (gate) and `GROUP_ROOMS=silent pnpm test:e2e:group`
+(the default) in `apps/qiforge-workers-example`; unit tests in
+`src/matrix/group-chat.test.ts` and this directory.
+
+## What is the Node contract, unchanged
+
+- The gate and its order: a direct room always answers; in a group room the
+  bot answers a message that mentions it (`m.mentions.user_ids`), a
+  quote-reply to one of its own messages, or a message in a thread it
+  answered within `GROUP_CHAT_ACTIVE_THREAD_TTL_MS` (30 min); otherwise it
+  stays silent. An answer is skipped when the bot's power level is below the
+  room's `m.room.message` threshold or `GROUP_CHAT_REQUIRE_POWER_LEVEL`.
+- Every group message, answered or not, is captured into the room's channel
+  memory; batches are compacted with the Node summarizer prompt, verbatim,
+  into summary chunks (FTS5 search with the porter tokenizer, LIKE fallback,
+  `OR` of the words, ranked), next to pinned facts and the member roster.
+- The four tools with Node's names, descriptions and schemas:
+  `recall_channel_memory`, `search_channel_memory`, `pin_room_fact`,
+  `unpin_room_fact` — offered only to a session in a group room.
+- A group message reaches the model as `[DisplayName]: …`; the bot's own
+  user id in a message body becomes `(USER MENTIONED YOU @AI_AGENT)`; the
+  message's `additional_kwargs` carry `senderDid`, `senderMatrixUserId`,
+  `senderDisplayName`, `threadId`, `eventId`.
+- Compaction at 20 buffered messages, and just in time before an answer when
+  5 or more are buffered, capped at 3 s so the reply is not held up.
+- The `delegation_required` prompt for a member without a delegation is
+  posted into the room the message came from, as on Node.
+
+## Where it differs from Node
+
+| Area                                                                                                      | Node                                                                                                                                                                                                              | Workers                                                                                                                                                                    | Why                                                                                                                                                                                                  |
+| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Where the gate runs                                                                                       | An agent middleware inside the speaker's turn: every group message was dispatched as a turn (typing indicator, `work_status` card, the message appended to the speaker's thread history) and then ended silently. | The gateway decides before a turn exists: an ignored message shows no typing, posts no card, wakes no user object and is not appended to the speaker's thread history.     | Cheaper, and a member who cannot boot a user object never fails a turn for a message nobody would answer. Cross-person context came from channel memory on both runtimes.                            |
+| Direct-room rule                                                                                          | `is_direct` on the create event, else ≤ 2 joined members.                                                                                                                                                         | The same two rules, plus: a room whose canonical alias is a user↔oracle alias of this oracle is direct whatever its member count.                                          | A real user↔oracle room also holds the rooms appservice bot and the memory-engine bot (four members on devnet); Node's rule alone would gate the oracle's own conversation with its user.            |
+| Active threads after a restart                                                                            | Scanned the room's last 100 messages for the bot's own replies.                                                                                                                                                   | A durable `group_bot_threads` table written whenever the bot decides to answer; nothing is scanned.                                                                        | The gateway restarts far more often than a Node process; a table read is local and exact. Threads answered before this build are not in it — one mention re-activates them.                          |
+| Where channel memory lives                                                                                | One SQLite file per room on the oracle's disk, gzipped and uploaded into the room as an encrypted media event (`qiforge.channel_memory.v1`) after every change, restored from there on a cold start.              | The gateway's Durable Object SQLite (`group_*` tables), which survives deploys on its own; nothing is uploaded to the room.                                                | No disk and no need for the room copy on Workers. A Node-era snapshot in a room is **not imported**; the tables use Node's column layout, so an importer is a small addition.                        |
+| Who runs the summarizer                                                                                   | The oracle process, `session-title` model role.                                                                                                                                                                   | The speaker's user object (`summarizeGroupMessages` RPC), same model role and prompt.                                                                                      | The gateway script holds no model keys.                                                                                                                                                              |
+| Compaction buffer                                                                                         | In memory; lost on restart.                                                                                                                                                                                       | Durable (`group_message_buffer`); a replayed message is not buffered twice.                                                                                                | Gateway resets are routine.                                                                                                                                                                          |
+| Idle compaction                                                                                           | After 5 quiet minutes.                                                                                                                                                                                            | Not ported; the next engagement compacts the buffer (threshold and just-in-time triggers are unchanged).                                                                   | The gateway's alarm belongs to the bot SDK. A quiet room's summary exists by the first moment anyone could read it.                                                                                  |
+| Tier rollups (weekly / monthly)                                                                           | Code present, never scheduled.                                                                                                                                                                                    | Not ported; `tier` stays 1.                                                                                                                                                | Dead on Node.                                                                                                                                                                                        |
+| Prompt injection of roster, pinned facts, recent messages (`buildSessionContext`) and `getCurrentSpeaker` | Code present, never called.                                                                                                                                                                                       | Not ported.                                                                                                                                                                | Dead on Node.                                                                                                                                                                                        |
+| Speaker prefix on file messages                                                                           | Strings only.                                                                                                                                                                                                     | Also the first text block of block content (a caption with an attachment).                                                                                                 | Workers' attachment pipeline produces block content.                                                                                                                                                 |
+| Members without a delegation                                                                              | Answered (a turn needed no delegation; memory calls failed softly).                                                                                                                                               | On a VFS-backed deployment their user object cannot boot, so a mention from them ends in the "try again" notice.                                                           | The Workers owner-copy design: the user's history file lives in their VFS and needs their delegation. The Portal deposits one for whoever invites the oracle into a room, not for the other members. |
+| Enabling                                                                                                  | On by default (`features: { 'matrix-group-chats': false }` to turn off).                                                                                                                                          | `MATRIX_GROUP_ROOMS` on the gateway: `silent` (default), `gate`, `answer`. Disabling the plugin only removes the tools; the gateway policy decides whether the bot speaks. | The gate is runtime infrastructure here, not a plugin middleware.                                                                                                                                    |
+
+## Open items before this can be the default
+
+- Review the divergences above with the product owner.
+- Decide whether members without a delegation should be prompted in group
+  rooms (the Portal's `delegation_required` listener is deliberately not
+  mounted) or answered without a user file.
+- Decide whether Node-era channel-memory snapshots need importing.
+- Decide whether task rooms should be recognised by the gateway's own record
+  of the rooms it created rather than by member count (a task room with a
+  third member becomes a group room today).

package/src/plugins/matrix-group-chats/index.ts

@@ -0,0 +1,132 @@
+/**
+ * Matrix Group Chats — the Workers port of
+ * `packages/oracle-runtime/src/plugins/matrix-group-chats`.
+ *
+ * STATUS: under development, off by default. The port is complete and
+ * tested but not reviewed for production, and it differs from Node in
+ * several ways — every difference and the open items are listed in
+ * `README.md` next to this file. A deployment turns the lane on with
+ * `MATRIX_GROUP_ROOMS=gate` on the gateway; until then the bot never speaks
+ * in a room with more than two members and this plugin offers no tools.
+ *
+ * On Node the plugin owned both halves: the per-turn gate (an agent
+ * middleware: answer only when mentioned, replied to or already in an active
+ * thread; capture every message into channel memory) and the per-room
+ * memory with its four tools. On Workers the gate and the memory run in the
+ * Matrix gateway, the one object every room message passes through
+ * (`src/matrix/group-chat.ts`); this plugin is the agent-side half: the four
+ * channel-memory tools, offered — exactly as on Node — only to a session in
+ * a Matrix room with more than two members. The `[DisplayName]: ` speaker
+ * prefix is applied by the user object's turn preparer (`speaker-prefix.ts`).
+ *
+ * The lane is opt-in per deployment: `MATRIX_GROUP_ROOMS=gate` on the
+ * gateway. By default (`silent`) the bot never speaks in a group room and
+ * this plugin offers nothing. The gate's knobs are read by the gateway from
+ * its env (`GROUP_CHAT_ACTIVE_THREAD_TTL_MS`, `GROUP_CHAT_REQUIRE_POWER_LEVEL`,
+ * `GROUP_CHAT_ROOM_INFO_TTL_MS`); they are declared here too so an oracle's
+ * config validates them the way Node's did.
+ */
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import type {
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+import { buildChannelMemoryTools } from './tools';
+
+const configSchema = z.object({
+  GROUP_CHAT_ACTIVE_THREAD_TTL_MS: z.coerce
+    .number()
+    .int()
+    .min(60_000)
+    .default(30 * 60 * 1000)
+    .describe('How long a thread stays "active with the bot" after a reply.'),
+  GROUP_CHAT_REQUIRE_POWER_LEVEL: z.coerce
+    .number()
+    .int()
+    .min(0)
+    .default(0)
+    .describe(
+      'Extra minimum power level the bot must have before posting (0 = use the room default).',
+    ),
+  GROUP_CHAT_ROOM_INFO_TTL_MS: z.coerce
+    .number()
+    .int()
+    .min(60_000)
+    .default(30 * 60 * 1000)
+    .describe('How long roomInfo (membership, DM flag) stays cached.'),
+});
+
+const manifest: PluginManifest = {
+  title: 'Matrix Group Chats',
+  summary:
+    'Lets the oracle participate cleanly in Matrix group rooms: it only replies when mentioned, replied to, or already in an active thread, and keeps an FTS5-searchable compacted memory of every room it sits in.',
+  whenToUse: [
+    'A user asks what was said or decided earlier in this Matrix group room.',
+    'A user asks who is in the room or what their role is.',
+    'A durable fact should survive across threads (deadline, decision, project context) — pin it.',
+    'You need to recall the gist of prior conversation before answering a multi-step group request.',
+  ],
+  whenNotToUse: [
+    'Single-user DMs — the plugin only acts in rooms with more than 2 members.',
+    'Long-term personal memory about a specific user — use the Memory plugin.',
+    'Verbatim text of a specific Matrix event — use Matrix history directly.',
+  ],
+  examples: [
+    {
+      user: 'What did we agree about the launch date?',
+      thought:
+        'Search channel memory for "launch date" before answering — the decision may be in an older chunk.',
+      tool: 'search_channel_memory',
+      args: { query: 'launch date' },
+    },
+    {
+      user: 'Remember that Alice owns the redesign.',
+      thought: 'Persist that as a pinned fact for the group room.',
+      tool: 'pin_room_fact',
+      args: { fact: 'Alice owns the redesign.' },
+    },
+  ],
+  tags: ['matrix', 'group-chat', 'memory'],
+  category: 'communication',
+  visibility: 'on-demand',
+  stability: 'beta',
+};
+
+export class MatrixGroupChatsPlugin extends OraclePlugin {
+  static readonly NAME = 'matrix-group-chats';
+
+  readonly name = MatrixGroupChatsPlugin.NAME;
+
+  readonly version = '1.0.0';
+
+  readonly manifest = manifest;
+
+  override readonly configSchema = configSchema;
+
+  /**
+   * Per request: the four channel-memory tools only when the deployment
+   * runs the group-chat lane and the session is in a Matrix group room
+   * (more than two members). DM, portal and task sessions get an empty
+   * list, so the agent never sees them there.
+   */
+  override async getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]> {
+    const roomId = rtCtx.session.roomId;
+    if (rtCtx.session.client !== 'matrix' || !roomId) return [];
+    const roomInfo = rtCtx.matrix.roomInfo;
+    if (!roomInfo || !rtCtx.matrix.channelMemory) return [];
+    try {
+      const info = await roomInfo(roomId);
+      if (!info.groupLane || info.isDirect || info.memberCount <= 2) return [];
+    } catch (err) {
+      rtCtx.logger.warn(
+        `[matrix-group-chats] roomInfo failed for ${roomId}: ${err instanceof Error ? err.message : String(err)} — skipping tools`,
+      );
+      return [];
+    }
+    return buildChannelMemoryTools();
+  }
+}
+
+export { buildChannelMemoryTools } from './tools';

package/src/plugins/matrix-group-chats/tools.ts

@@ -0,0 +1,172 @@
+/**
+ * The four channel-memory tools of a Matrix group room — the Node
+ * `plugins/matrix-group-chats/tools.ts` verbatim in contract; the store is
+ * the gateway's (`RuntimeContext.matrix.channelMemory`).
+ */
+import { z } from 'zod';
+import type {
+  ChannelMemoryChunk,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+
+const formatChunk = (chunk: ChannelMemoryChunk) => ({
+  id: chunk.id,
+  tier: chunk.tier,
+  fromTimestamp: new Date(chunk.fromTimestamp).toISOString(),
+  toTimestamp: new Date(chunk.toTimestamp).toISOString(),
+  messageCount: chunk.messageCount,
+  participants: chunk.participants,
+  threadIds: chunk.threadIds,
+  summary: chunk.summary,
+});
+
+function requireMemory(rtCtx: RuntimeContext) {
+  const memory = rtCtx.matrix.channelMemory;
+  if (!memory)
+    throw new Error(
+      'Channel memory is not available on this host (no Matrix gateway).',
+    );
+  return memory;
+}
+
+function requireRoomId(rtCtx: RuntimeContext): string {
+  const roomId = rtCtx.session.roomId;
+  if (!roomId)
+    throw new Error(
+      'No active Matrix room — channel-memory tools require a roomId in the current session.',
+    );
+  return roomId;
+}
+
+/**
+ * Visibility `always` on each tool so they bypass the capability gate —
+ * the gating is `getRequestTools`, which returns them only for a session in
+ * a Matrix group room.
+ */
+export function buildChannelMemoryTools(): PluginTool[] {
+  return [
+    {
+      name: 'recall_channel_memory',
+      description:
+        'Read recent channel memory: most recent compacted summary chunks, pinned facts, and the member roster for the current group room. Use this to understand what has been happening in this channel before responding.',
+      visibility: 'always',
+      effect: 'read',
+      schema: z.object({
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(30)
+          .optional()
+          .describe(
+            'Number of recent summary chunks to return (default 10, max 30).',
+          ),
+      }),
+      async handler(args, rtCtx) {
+        const roomId = requireRoomId(rtCtx);
+        const memory = requireMemory(rtCtx);
+        const parsed = z
+          .object({ limit: z.number().int().min(1).max(30).optional() })
+          .parse(args);
+        const recalled = await memory.recall(roomId, parsed.limit ?? 10);
+        return {
+          chunks: recalled.chunks.map(formatChunk),
+          pinnedFacts: recalled.pinnedFacts,
+          members: recalled.members,
+        };
+      },
+    },
+    {
+      name: 'search_channel_memory',
+      description:
+        'Keyword-search the compacted summary chunks for the current group room. Use to find earlier discussions of a topic, decisions, names, dates. Returns matching chunks with their summaries.',
+      visibility: 'always',
+      effect: 'read',
+      schema: z.object({
+        query: z
+          .string()
+          .min(1)
+          .describe('Keywords or phrase to search for in channel memory.'),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(30)
+          .optional()
+          .describe('Maximum matching chunks to return (default 10).'),
+      }),
+      async handler(args, rtCtx) {
+        const roomId = requireRoomId(rtCtx);
+        const memory = requireMemory(rtCtx);
+        const parsed = z
+          .object({
+            query: z.string().min(1),
+            limit: z.number().int().min(1).max(30).optional(),
+          })
+          .parse(args);
+        const chunks = await memory.search(
+          roomId,
+          parsed.query,
+          parsed.limit ?? 10,
+        );
+        if (chunks.length === 0)
+          return { chunks: [], note: 'No matching chunks.' };
+        return { chunks: chunks.map(formatChunk) };
+      },
+    },
+    {
+      name: 'pin_room_fact',
+      description:
+        "Save a durable fact to the current group room's memory — survives across threads and sessions. Use for decisions, deadlines, member roles, project context. Surface in your reply so users know it has been saved.",
+      visibility: 'always',
+      schema: z.object({
+        fact: z
+          .string()
+          .min(3)
+          .max(500)
+          .describe('Concise factual statement to remember (max 500 chars).'),
+        sourceEventId: z
+          .string()
+          .optional()
+          .describe('Optional Matrix event id this fact was derived from.'),
+      }),
+      async handler(args, rtCtx) {
+        const roomId = requireRoomId(rtCtx);
+        const memory = requireMemory(rtCtx);
+        const parsed = z
+          .object({
+            fact: z.string().min(3).max(500),
+            sourceEventId: z.string().optional(),
+          })
+          .parse(args);
+        const trimmed = parsed.fact.trim();
+        if (!trimmed) throw new Error('Pinned fact must not be empty.');
+        const pinned = await memory.pin({
+          roomId,
+          fact: trimmed.slice(0, 500),
+          pinnedByDid: rtCtx.user.did,
+          ...(parsed.sourceEventId
+            ? { sourceEventId: parsed.sourceEventId }
+            : {}),
+        });
+        return { factId: pinned.id, fact: pinned.fact };
+      },
+    },
+    {
+      name: 'unpin_room_fact',
+      description:
+        "Remove a previously pinned fact from this group room's memory by its factId.",
+      visibility: 'always',
+      schema: z.object({
+        factId: z.string().min(1).describe('The id of the fact to remove.'),
+      }),
+      async handler(args, rtCtx) {
+        const roomId = requireRoomId(rtCtx);
+        const memory = requireMemory(rtCtx);
+        const parsed = z.object({ factId: z.string().min(1) }).parse(args);
+        return { ok: await memory.unpin(roomId, parsed.factId) };
+      },
+    },
+  ];
+}

package/src/plugins/tasks/tasks-tools.ts

@@ -145,6 +145,7 @@ function previewTask(): PluginTool {
     },
     {
       name: 'preview_task',
+      effect: 'read',
       description:
         'Validate a candidate task spec and return its next run times WITHOUT creating anything. ALWAYS call this before create_task and show the user the result. IMPORTANT: scheduled runs are fresh background sessions with NO memory of this conversation — put every ID, URL, and name the run needs into the intent text.',
       schema: previewInput,
@@ -214,6 +215,7 @@ function listMyTasks(): PluginTool {
     },
     {
       name: 'list_my_tasks',
+      effect: 'read',
       description:
         "List the user's scheduled tasks — id, title, status, schedule, next run. A task with `awaitingApprovalSince` has an approval request waiting for the user in their room — tell them and point them there. Optionally filter by status.",
       schema: listInput,
@@ -246,6 +248,7 @@ function getTask(): PluginTool {
     },
     {
       name: 'get_task',
+      effect: 'read',
       description:
         'Fetch one task: full intent body, status, schedule, last run result, and the consecutive-failure count if it has been failing.',
       schema: taskIdSchema,
@@ -406,6 +409,7 @@ function suggestSpecFix(): PluginTool {
     },
     {
       name: 'suggest_spec_fix',
+      effect: 'read',
       description:
         'For a failing task: returns the current intent plus the last error so you can propose a revised intent to the user. Apply the fix with update_task ONLY after the user agrees — never auto-apply.',
       schema: taskIdSchema,

package/src/shell/app.ts

@@ -6,6 +6,7 @@
  * work unchanged. Every authenticated route resolves the caller's
  * `UserOracleDO` and forwards to it; streaming turns are proxied byte-for-byte.
  */
+import { parseTranscriptPageQuery } from '../do/transcript';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import type { OracleWorkerEnv, TurnIdentity } from '../do/contracts';
@@ -283,6 +284,54 @@ export function createShell(
       headers: { 'content-type': 'application/json' },
     });
   });
+  // One turn-aligned page of the transcript (docs/plans/transcript-paging.md):
+  // the newest `limit` turns, the turns `before=` a cursor, or what came
+  // `after=` one. The legacy listing above stays the whole transcript.
+  app.get('/sessions/:sessionId/messages', async (c) => {
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const parsed = parseTranscriptPageQuery(c.req.query());
+    if (!parsed.ok)
+      return c.json({ statusCode: 400, message: parsed.message }, 400);
+    const page = await userStub(c.env, identity.userDid).listMessagesPage(
+      identity,
+      c.req.param('sessionId'),
+      parsed.options,
+    );
+    if (!page.ok)
+      return c.json({ statusCode: page.status, message: page.message }, 400);
+    return new Response(page.json, {
+      headers: { 'content-type': 'application/json' },
+    });
+  });
+
+  // --- durable runs (docs/plans/durable-runs.md) -------------------------------
+  // The session's active run, if any: a client that reloads asks this first,
+  // then re-joins the run's stream.
+  app.get('/sessions/:sessionId/run', async (c) => {
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const run = await userStub(c.env, identity.userDid).sessionRun(
+      identity,
+      c.req.param('sessionId'),
+    );
+    return c.json({ run });
+  });
+  // Re-join a run's SSE stream after a cursor (`?after=<seq>`, the `id:` of
+  // the last frame the client saw). Frames after it are replayed, then the
+  // live tail until `done`. A run that ended replays and closes at once.
+  app.get('/runs/:runId', async (c) => {
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    const after = c.req.query('after') ?? '0';
+    const res = await userStub(c.env, identity.userDid).fetch(
+      `https://user-oracle/runs/${encodeURIComponent(c.req.param('runId'))}?after=${encodeURIComponent(after)}`,
+      { headers: { 'x-identity': JSON.stringify(identity) } },
+    );
+    const headers = new Headers(res.headers);
+    headers.set(
+      'access-control-expose-headers',
+      'x-request-id, x-run-id, x-run-status',
+    );
+    return new Response(res.body, { status: res.status, headers });
+  });
   app.post('/messages/:sessionId', async (c) => {
     const identity = identityOf(c.get('auth'), c.req.raw.headers);
     const sessionId = c.req.param('sessionId');
@@ -471,6 +520,18 @@ export function createShell(
   app.post('/debug/storage/flush', async (c) =>
     c.json(await userStub(c.env, c.get('auth').userDid).flushToOwnerStore()),
   );
+  app.post('/debug/storage/tier-flush', async (c) => {
+    const body: unknown = await c.req.json().catch(() => ({}));
+    const rec = typeof body === 'object' && body !== null ? body : {};
+    const force = Reflect.get(rec, 'force') === true;
+    const max = Number(Reflect.get(rec, 'maxSegments'));
+    return c.json(
+      await userStub(c.env, c.get('auth').userDid).tierFlush({
+        force,
+        ...(Number.isInteger(max) && max > 0 && { maxSegments: max }),
+      }),
+    );
+  });
   app.post('/debug/storage/reset', async (c) =>
     c.json(await userStub(c.env, c.get('auth').userDid).resetWorkingCopy()),
   );
@@ -510,6 +571,23 @@ export function createShell(
   app.get('/debug/realtime', async (c) =>
     c.json(await userStub(c.env, c.get('auth').userDid).realtimeStatus()),
   );
+  app.get('/debug/runs', async (c) =>
+    c.json(await userStub(c.env, c.get('auth').userDid).runsStatus()),
+  );
+  // The context budget a model gets on this user's object (window origin,
+  // thresholds, saved-result store stats). `?model=` defaults to the
+  // deployment's main model; `?byoProvider=` resolves a BYO-native id.
+  app.get('/debug/context', async (c) => {
+    const identity = identityOf(c.get('auth'), c.req.raw.headers);
+    return c.json(
+      await userStub(c.env, identity.userDid).contextStatus(
+        identity,
+        c.req.query('model') || undefined,
+        c.req.query('byoProvider') || undefined,
+        c.req.query('session') || undefined,
+      ),
+    );
+  });
   app.post('/debug/reauth-prompt/reset', async (c) => {
     await userStub(c.env, c.get('auth').userDid).debugResetReauthThrottle();
     return c.json({ reset: true });

package/src/sqlite/cache-config.ts

@@ -19,22 +19,43 @@ export function parseChunkCacheBytes(
   raw: string | undefined,
   warn: (message: string) => void = () => undefined,
 ): number {
-  if (raw === undefined || raw.trim() === '') return DEFAULT_CHUNK_CACHE_BYTES;
+  return parseByteSize(raw, {
+    name: 'CHUNK_CACHE_BYTES',
+    fallback: DEFAULT_CHUNK_CACHE_BYTES,
+    min: MIN_CHUNK_CACHE_BYTES,
+    max: MAX_CHUNK_CACHE_BYTES,
+    warn,
+  });
+}
+
+/** Same grammar for any byte-sized env knob (`TIER_HOT_BUDGET_BYTES`, ...). */
+export function parseByteSize(
+  raw: string | undefined,
+  options: {
+    name: string;
+    fallback: number;
+    min: number;
+    max: number;
+    warn?: (message: string) => void;
+  },
+): number {
+  const warn = options.warn ?? (() => undefined);
+  if (raw === undefined || raw.trim() === '') return options.fallback;
   const match = /^\s*(\d+)\s*([kKmM]?)\s*$/.exec(raw);
   if (!match) {
     warn(
-      `CHUNK_CACHE_BYTES=${JSON.stringify(raw)} is not a byte count — using the default ${DEFAULT_CHUNK_CACHE_BYTES}`,
+      `${options.name}=${JSON.stringify(raw)} is not a byte count — using the default ${options.fallback}`,
     );
-    return DEFAULT_CHUNK_CACHE_BYTES;
+    return options.fallback;
   }
   const unit = match[2]?.toLowerCase();
   const multiplier = unit === 'k' ? 1024 : unit === 'm' ? 1024 * 1024 : 1;
   const bytes = Number(match[1]) * multiplier;
-  if (bytes < MIN_CHUNK_CACHE_BYTES || bytes > MAX_CHUNK_CACHE_BYTES) {
+  if (bytes < options.min || bytes > options.max) {
     warn(
-      `CHUNK_CACHE_BYTES=${raw} is outside ${MIN_CHUNK_CACHE_BYTES}..${MAX_CHUNK_CACHE_BYTES} — using the default ${DEFAULT_CHUNK_CACHE_BYTES}`,
+      `${options.name}=${raw} is outside ${options.min}..${options.max} — using the default ${options.fallback}`,
     );
-    return DEFAULT_CHUNK_CACHE_BYTES;
+    return options.fallback;
   }
   return bytes;
 }

package/src/sqlite/chunk-layout.ts

@@ -0,0 +1,14 @@
+/**
+ * The storage grain shared by the DO VFS and the R2 page tier. Kept in its
+ * own module so `page-tier.ts` can import it without a cycle through
+ * `do-vfs.ts`.
+ */
+
+/** Bytes per SQLite page. Matches `PRAGMA page_size=4096`. */
+export const VFS_PAGE_SIZE = 4096;
+
+/** SQLite pages packed into one stored row (billing grain). */
+export const PAGES_PER_CHUNK = 16;
+
+/** Bytes per stored chunk row (64 KiB — well under the 2 MB DO value cap). */
+export const CHUNK_SIZE = VFS_PAGE_SIZE * PAGES_PER_CHUNK;