@ixo/oracle-runtime-workers 0.4.0 → 0.9.0

package/src/matrix/work-status.ts

@@ -15,6 +15,7 @@
  * replaces it — which also guarantees a terminal phase is never dropped.
  * Fire-and-forget throughout: a failed post is logged, never thrown.
  */
+import { retryTxnId } from './txn-id';
 
 export const ORACLE_COMPONENT_EVENT_TYPE = 'ixo.oracle.component';
 
@@ -129,11 +130,16 @@ interface TurnEntry extends WorkStatusTurn {
 }
 
 export interface WorkStatusProducerDeps {
-  /** Posts a room event and resolves its event id (the gateway's `sendEvent`). */
+  /**
+   * Posts a room event and resolves its event id (the gateway's `sendEvent`).
+   * `txnId` pins the transaction id so the anchor's single retry cannot post
+   * a second card when only the response was lost.
+   */
   postEvent: (
     roomId: string,
     eventType: string,
     content: object,
+    opts?: { txnId?: string },
   ) => Promise<string>;
   clock?: () => Date;
   logger?: { warn: (message: string) => void };
@@ -205,14 +211,20 @@ export class WorkStatusProducer {
     content: object,
     retryOnce: boolean,
   ): Promise<string> {
+    const opts = { txnId: retryTxnId('work-status') };
     try {
-      return await this.postEvent(roomId, ORACLE_COMPONENT_EVENT_TYPE, content);
+      return await this.postEvent(
+        roomId,
+        ORACLE_COMPONENT_EVENT_TYPE,
+        content,
+        opts,
+      );
     } catch (error) {
       if (!retryOnce) throw error;
       await new Promise((resolve) =>
         setTimeout(resolve, this.anchorRetryDelayMs),
       );
-      return this.postEvent(roomId, ORACLE_COMPONENT_EVENT_TYPE, content);
+      return this.postEvent(roomId, ORACLE_COMPONENT_EVENT_TYPE, content, opts);
     }
   }
 

package/src/owner-store/matrix-media-store.ts

@@ -4,41 +4,49 @@
  * Wire format is the Node runtime's (`m.ixo.media_upload` timeline event +
  * `m.ixo.media_state[storageKey]` pointer), so a user migrating from the
  * Node runtime finds their checkpoint file where they left it. The gateway
- * handles encryption and media transfer; this class owns gzip and the
- * SQLite sanity check.
+ * moves the media across the object boundary as a stream, as stored; this
+ * class decrypts, gunzips and header-checks it chunk by chunk (and gzips +
+ * hands over a stream on the way up), so the file is never held whole in
+ * either isolate — a 50 MB Node-era history used to be materialised three
+ * times over in the user object and reset its 128 MB isolate.
  */
 
+import { createAttachmentDecryptor } from '@ixo/matrix-bot-workers-sdk';
 import type { MatrixGatewayObject } from '../do/contracts';
 import {
-  bytesOfStream,
-  gunzip,
-  gzip,
-  isSqliteFile,
-  streamOfBytes,
+  assertSqliteStream,
+  countStream,
+  gunzipStreamIfNeeded,
+  gzipStream,
   type FileSnapshot,
   type OwnerCopy,
   type OwnerStore,
   type SaveResult,
 } from './types';
 
-const GZIP_MAGIC_0 = 0x1f;
-const GZIP_MAGIC_1 = 0x8b;
-
-function looksGzipped(bytes: Uint8Array): boolean {
-  return (
-    bytes.length >= 2 && bytes[0] === GZIP_MAGIC_0 && bytes[1] === GZIP_MAGIC_1
-  );
-}
+/**
+ * The slice of the gateway RPC surface this store needs — structurally
+ * satisfied by `DurableObjectStub<MatrixGatewayObject>` and faked in tests.
+ */
+export type SnapshotGateway = Pick<
+  MatrixGatewayObject,
+  | 'downloadUserSnapshotStream'
+  | 'uploadUserSnapshotStream'
+  | 'resolveUserRoom'
+  | 'getRoomStateEvent'
+  | 'sendEvent'
+  | 'sendStateEvent'
+>;
 
 export interface MatrixMediaOwnerStoreOptions {
-  gateway: DurableObjectStub<MatrixGatewayObject>;
+  gateway: SnapshotGateway;
   userDid: string;
   storageKey: string;
 }
 
 export class MatrixMediaOwnerStore implements OwnerStore {
   readonly kind = 'matrix' as const;
-  private readonly gateway: DurableObjectStub<MatrixGatewayObject>;
+  private readonly gateway: SnapshotGateway;
   private readonly userDid: string;
   private readonly storageKey: string;
 
@@ -53,43 +61,55 @@ export class MatrixMediaOwnerStore implements OwnerStore {
   }
 
   /**
-   * The gateway RPC hands the whole (encrypted, then decrypted) media blob
-   * over; this path is the legacy one and inherently materializes the file.
+   * Streamed end to end: the gateway hands the media over as stored (the
+   * ciphertext plus its `EncryptedFile` fields in an E2EE room, the plain
+   * upload otherwise), this side decrypts and gunzips as the bytes arrive and
+   * rejects anything that does not start like a SQLite file before the object
+   * writes a single chunk. A hash mismatch surfaces at the END of the stream
+   * (the SDK verifies the ciphertext SHA-256 once the last byte is in), which
+   * fails the import and leaves the working copy untouched. Peak memory is a
+   * few chunks, whatever the file size.
    */
   async load(): Promise<OwnerCopy | null> {
-    const found = await this.gateway.downloadUserSnapshot(
+    const found = await this.gateway.downloadUserSnapshotStream(
       this.userDid,
       this.storageKey,
     );
     if (!found) return null;
+    const plain = found.file
+      ? found.stream.pipeThrough(createAttachmentDecryptor(found.file))
+      : found.stream;
     // Old Node-runtime uploads were always gzipped, but tolerate a raw file
     // so a hand-uploaded database still loads.
-    const bytes = looksGzipped(found.bytes)
-      ? await gunzip(found.bytes)
-      : found.bytes;
-    if (!isSqliteFile(bytes)) {
-      throw new Error(
-        `MatrixMediaOwnerStore: snapshot ${found.eventId} for ${this.storageKey} is not a SQLite file (${bytes.length} bytes)`,
-      );
-    }
-    return { stream: streamOfBytes(bytes), etag: found.eventId };
+    const stream = await assertSqliteStream(
+      await gunzipStreamIfNeeded(plain),
+      `MatrixMediaOwnerStore: snapshot ${found.eventId} for ${this.storageKey}`,
+    );
+    return { stream, etag: found.eventId };
   }
 
+  /**
+   * Streamed as well: the snapshot is opened three times — a header peek, a
+   * gzip pass that only counts (the homeserver needs the exact ciphertext
+   * length up front; gzip output is deterministic for identical input, the
+   * VFS store relies on the same property) and the gzip pass that is
+   * uploaded — and never held whole.
+   */
   async save(snapshot: FileSnapshot): Promise<SaveResult> {
-    const bytes = await bytesOfStream(snapshot.open());
-    if (!isSqliteFile(bytes)) {
-      throw new Error(
-        `MatrixMediaOwnerStore: refusing to save ${bytes.length} bytes that are not a SQLite file`,
-      );
-    }
-    const compressed = await gzip(bytes);
-    const { eventId } = await this.gateway.uploadUserSnapshot(
+    const checked = await assertSqliteStream(
+      snapshot.open(),
+      `MatrixMediaOwnerStore: refusing to save — the working copy (${snapshot.size} bytes)`,
+    );
+    await checked.cancel().catch(() => undefined);
+    const gzLength = await countStream(gzipStream(snapshot.open()));
+    const { eventId } = await this.gateway.uploadUserSnapshotStream(
       this.userDid,
       this.storageKey,
-      compressed,
+      gzipStream(snapshot.open()),
       this.filename,
+      gzLength,
     );
-    return { etag: eventId, bytes: compressed.byteLength };
+    return { etag: eventId, bytes: gzLength };
   }
 
   async head(): Promise<{ etag: string } | null> {

package/src/owner-store/migrating-store.ts

@@ -3,10 +3,12 @@
  * Matrix room media is only a read-only *legacy* source, checked when VFS has
  * no file yet so users coming from the Node runtime keep their history.
  *
- *   load():  VFS first. If absent there but present in Matrix media, import
- *            the legacy file AND write it to VFS immediately — from that
- *            moment the VFS copy is authoritative and Matrix is never
- *            consulted again (head() sees the VFS file).
+ *   load():  VFS first. If absent there but present in Matrix media, hand
+ *            the legacy stream over flagged `fromLegacy`: the object imports
+ *            it chunk by chunk and writes it to VFS from its working copy at
+ *            once (`flushToOwnerStore`) — from that moment the VFS copy is
+ *            authoritative and Matrix is never consulted again (head() sees
+ *            the VFS file). Nothing on this path holds the file in memory.
  *   save():  VFS, and only VFS. Nothing is ever written to Matrix media any
  *            more: a failed VFS write (no `ixo:filesystem` delegation yet, a
  *            VFS outage) propagates, and the object keeps its working copy
@@ -18,15 +20,7 @@
  *            Matrix copy so no second copy of the user's history lingers.
  */
 import { VfsNoDelegationError } from './ixo-vfs-store';
-import {
-  bytesOfStream,
-  snapshotOfBytes,
-  streamOfBytes,
-  type FileSnapshot,
-  type OwnerCopy,
-  type OwnerStore,
-  type SaveResult,
-} from './types';
+import type { FileSnapshot, OwnerCopy, OwnerStore, SaveResult } from './types';
 
 export interface MigratingOwnerStoreOptions {
   /** System of record (IXO VFS). */
@@ -93,24 +87,16 @@ export class MigratingOwnerStore implements OwnerStore {
       return null;
     }
 
-    // One-time migration: the legacy file becomes the first VFS version. The
-    // legacy copy is already in memory (gateway RPCs hand over bytes), so
-    // re-opening it for the VFS upload costs nothing extra.
-    const legacyBytes = await bytesOfStream(fromLegacy.stream);
-    try {
-      const { etag } = await this.primary.save(snapshotOfBytes(legacyBytes));
-      this.log(
-        'log',
-        `[owner-store] migrated ${legacyBytes.byteLength} bytes from Matrix media to VFS (${etag})`,
-      );
-      return { stream: streamOfBytes(legacyBytes), etag };
-    } catch (err) {
-      this.log(
-        'warn',
-        `[owner-store] VFS migration write failed — serving the legacy Matrix copy for now: ${err instanceof Error ? err.message : String(err)}`,
-      );
-      return { stream: streamOfBytes(legacyBytes), etag: fromLegacy.etag };
-    }
+    // One-time migration, streamed: the object imports this copy chunk by
+    // chunk and then flushes its working copy to VFS (`fromLegacy`). Writing
+    // VFS from here would need the whole file in memory twice over (the VFS
+    // store measures the gzip before it uploads) — what used to reset the
+    // isolate on large Node-era histories.
+    this.log(
+      'log',
+      `[owner-store] legacy Matrix copy ${fromLegacy.etag} found and no VFS copy yet — importing it for migration`,
+    );
+    return { ...fromLegacy, fromLegacy: true };
   }
 
   /**
@@ -159,13 +145,16 @@ export class MigratingOwnerStore implements OwnerStore {
 
   /** The legacy Matrix copy regardless of what VFS holds (see `OwnerStore.loadLegacy`). */
   async loadLegacy(): Promise<OwnerCopy | null> {
-    return this.legacy.load().catch((err) => {
+    try {
+      const copy = await this.legacy.load();
+      return copy ? { ...copy, fromLegacy: true } : null;
+    } catch (err) {
       this.log(
         'warn',
         `[owner-store] legacy Matrix load failed: ${err instanceof Error ? err.message : String(err)}`,
       );
       return null;
-    });
+    }
   }
 
   async remove(): Promise<void> {

package/src/plugin-api/types.ts

@@ -415,6 +415,17 @@ export interface PluginContext<TConfig = MergedConfig> {
  * Passed to tool handlers, sub-agent handlers, and to plugin middlewares' hook
  * functions. Built fresh per graph invocation.
  */
+/**
+ * Options of a room post made through `RuntimeContext.matrix`. A plugin
+ * that retries a post after a lost response should pin `txnId` (one id for
+ * the whole retry loop, see `retryTxnId`): the homeserver deduplicates sends
+ * by transaction id per device, so the retried post lands once. Printable
+ * ASCII without `/`, at most 255 characters.
+ */
+export interface MatrixPostOpts {
+  txnId?: string;
+}
+
 export interface RuntimeContext<TConfig = MergedConfig> {
   /** Authenticated user identity (validated by core auth middleware). */
   user: {
@@ -492,7 +503,11 @@ export interface RuntimeContext<TConfig = MergedConfig> {
 
   /** Matrix client, scoped operations only. */
   matrix: {
-    postToRoom: (roomId: string, content: unknown) => Promise<string>;
+    postToRoom: (
+      roomId: string,
+      content: unknown,
+      opts?: MatrixPostOpts,
+    ) => Promise<string>;
     /**
      * Post a timeline event with a caller-chosen event type (e.g. the
      * `ixo.oracle.*` protocol events). `postToRoom` is the `m.room.message`
@@ -502,6 +517,7 @@ export interface RuntimeContext<TConfig = MergedConfig> {
       roomId: string,
       eventType: string,
       content: object,
+      opts?: MatrixPostOpts,
     ) => Promise<string>;
     getRoomState: (roomId: string) => Promise<RoomStateSnapshot>;
     getEventById: (roomId: string, eventId: string) => Promise<MatrixEvent>;
@@ -637,6 +653,14 @@ export interface RuntimeContext<TConfig = MergedConfig> {
    */
   onTurnEnd?: (dispose: () => void | Promise<void>) => void;
 
+  /**
+   * Keep un-awaited work alive past the end of the request that started it
+   * (a best-effort room post retried across a gateway restart). On Workers
+   * this is the Durable Object's `waitUntil`; absent on hosts where pending
+   * promises run to completion on their own.
+   */
+  background?: (work: Promise<unknown>) => void;
+
   /** Propagates from the HTTP request / graph invocation. */
   abortSignal: AbortSignal;
 

package/src/plugins/portal/action-log.ts

@@ -2,7 +2,16 @@
  * The Node runtime's `logActionToMatrix`: a best-effort `ixo.action.log`
  * room event recording a frontend action (browser tool / AG-UI action) and
  * its outcome, posted only when the turn has a room. Never throws.
+ *
+ * Retried across a gateway restart (the gateway object is replaced on every
+ * deploy and can be drained mid-turn) and handed to the host to keep alive
+ * past the turn, so the audit trail does not lose entries to resets. The
+ * post carries one transaction id for the life of its retry loop, so a
+ * response lost between the homeserver's ack and the reply to the gateway
+ * is deduplicated instead of logged twice.
  */
+import { retryGateway, type RetryGatewayOptions } from '../../do/gateway-retry';
+import { retryTxnId } from '../../matrix/txn-id';
 import type { RuntimeContext } from '../../plugin-api/types';
 
 export const ACTION_LOG_EVENT_TYPE = 'ixo.action.log';
@@ -16,19 +25,37 @@ export interface LoggedAction {
 }
 
 export function logActionToMatrix(
-  ctx: Pick<RuntimeContext, 'matrix' | 'session' | 'logger'>,
+  ctx: Pick<RuntimeContext, 'matrix' | 'session' | 'logger' | 'background'>,
   action: LoggedAction,
+  retry?: Pick<RetryGatewayOptions, 'delaysMs' | 'sleep' | 'isTransient'>,
 ): void {
   const roomId = ctx.session.roomId;
   if (!roomId) return;
-  void ctx.matrix
-    .postEvent(roomId, ACTION_LOG_EVENT_TYPE, {
-      action,
-      threadId: ctx.session.id,
-    })
-    .catch((err: unknown) => {
+  const errorText = (err: unknown): string =>
+    err instanceof Error ? err.message : String(err);
+  const txnId = retryTxnId('action-log');
+  const work = retryGateway(
+    () =>
+      ctx.matrix.postEvent(
+        roomId,
+        ACTION_LOG_EVENT_TYPE,
+        { action, threadId: ctx.session.id },
+        { txnId },
+      ),
+    {
+      ...retry,
+      onRetry: (err, attempt, delayMs) =>
+        ctx.logger.warn?.(
+          `[portal] action log for ${action.name} failed (attempt ${attempt}) — retrying in ${delayMs} ms: ${errorText(err)}`,
+        ),
+    },
+  ).then(
+    () => undefined,
+    (err: unknown) => {
       ctx.logger.warn?.(
-        `[portal] action log for ${action.name} not posted: ${err instanceof Error ? err.message : String(err)}`,
+        `[portal] action log for ${action.name} not posted: ${errorText(err)}`,
       );
-    });
+    },
+  );
+  ctx.background?.(work);
 }

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

@@ -17,11 +17,8 @@ import type {
   RuntimeContext,
 } from '../../plugin-api/types';
 import { summarizeSchedule } from '../../tasks/schedule';
-import {
-  TASK_ID_PATTERN,
-  TASK_STATUSES,
-  TaskScheduleSchema,
-} from '../../tasks/spec';
+import { TASK_ID_PATTERN, TASK_STATUSES } from '../../tasks/spec';
+import { ScheduleInputToScheduleSchema } from '../../tasks/schedule-input';
 import { pendingApprovalOf } from '../../tasks/store';
 
 const TASKS_UNAVAILABLE = {
@@ -51,7 +48,10 @@ const taskInputShape = {
     .describe(
       'Markdown instructions the run executes. Scheduled runs are BACKGROUND sessions with NO memory of this conversation — put every ID, URL, and name the run needs into this text, never assume the run "knows" anything discussed here.',
     ),
-  schedule: TaskScheduleSchema,
+  // Flat at the tool boundary (a `kind` enum + optional per-kind fields),
+  // converted to the store's discriminated union on parse — see
+  // tasks/schedule-input.ts for why the union itself cannot be the input.
+  schedule: ScheduleInputToScheduleSchema,
   approval: z
     .enum(['never', 'before-action'])
     .default('never')
@@ -259,7 +259,7 @@ const updateInput = z.object({
   taskId: taskIdSchema.shape.taskId,
   title: z.string().min(1).max(120).optional(),
   intent: taskInputShape.intent.optional(),
-  schedule: TaskScheduleSchema.optional(),
+  schedule: ScheduleInputToScheduleSchema.optional(),
   approval: z
     .enum(['never', 'before-action'])
     .optional()

package/src/shell/app.ts

@@ -26,6 +26,18 @@ import {
   type AuthResult,
   type RouteExclusion,
 } from './auth';
+import { turnBodyTooLarge } from './turn-body-cap';
+import { z } from 'zod';
+
+const DebugEventBody = z.object({
+  type: z
+    .string()
+    .min(1)
+    .max(255)
+    .refine((t) => t !== 'm.room.redaction', 'redactions are not events'),
+  content: z.record(z.string(), z.unknown()).default({}),
+  txnId: z.string().min(1).max(255).optional(),
+});
 
 export interface PluginRoute {
   method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'ALL';
@@ -54,6 +66,17 @@ export interface ShellOptions {
 
 type Variables = { auth: AuthResult };
 
+function errorText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** The rejection an in-flight RPC gets when `ctx.abort()` resets its object. */
+function isAbortRejection(err: unknown): boolean {
+  return /debug reset requested|reset requested by the debug route|durable object reset|no longer active|aborted/i.test(
+    errorText(err),
+  );
+}
+
 const BUILTIN_EXCLUSIONS: RouteExclusion[] = [
   { path: '/', method: 'GET' },
   { path: '/health', method: 'ALL' },
@@ -66,9 +89,6 @@ const BUILTIN_EXCLUSIONS: RouteExclusion[] = [
   { path: '/debug/matrix/stop', method: 'POST' },
 ];
 
-/** Express body-parser default in the Node runtime: JSON bodies over 100 KiB are a 413. */
-const MAX_TURN_BODY_BYTES = 100 * 1024;
-
 export function createShell(
   opts: ShellOptions = {},
 ): Hono<{ Bindings: OracleWorkerEnv; Variables: Variables }> {
@@ -267,9 +287,9 @@ export function createShell(
     const identity = identityOf(c.get('auth'), c.req.raw.headers);
     const sessionId = c.req.param('sessionId');
     const body = await c.req.text();
-    // Node (express body-parser default) refuses JSON bodies over 100 KiB
-    // with a 413; attachments are references, so real turns never get near it.
-    if (new TextEncoder().encode(body).byteLength > MAX_TURN_BODY_BYTES) {
+    // Bounds the memory one request can pin (see turn-body-cap.ts); the
+    // status and message are the ones Node's body parser uses.
+    if (turnBodyTooLarge(body)) {
       return c.json(
         { statusCode: 413, message: 'request entity too large' },
         413,
@@ -454,6 +474,18 @@ export function createShell(
   app.post('/debug/storage/reset', async (c) =>
     c.json(await userStub(c.env, c.get('auth').userDid).resetWorkingCopy()),
   );
+  app.post('/debug/object/abort', async (c) => {
+    try {
+      await userStub(c.env, c.get('auth').userDid).debugAbortObject();
+    } catch (err) {
+      // The abort tears the object down under the call: that rejection is
+      // the expected signal. Anything else (an older build without the
+      // method, a transport error) is a real failure.
+      if (!isAbortRejection(err))
+        return c.json({ aborted: false, error: errorText(err) }, 500);
+    }
+    return c.json({ aborted: true });
+  });
   app.get('/debug/memory-schema', async (c) => {
     const userDid = c.get('auth').userDid;
     return c.json(await userStub(c.env, userDid).debugMemorySchema(userDid));
@@ -469,11 +501,19 @@ export function createShell(
       : c.json({ statusCode: 404, message: 'Session not found' }, 404);
   });
   app.get('/debug/tasks', async (c) =>
-    c.json(await userStub(c.env, c.get('auth').userDid).tasksStatus()),
+    c.json(
+      await userStub(c.env, c.get('auth').userDid).tasksStatus(
+        c.get('auth').userDid,
+      ),
+    ),
   );
   app.get('/debug/realtime', async (c) =>
     c.json(await userStub(c.env, c.get('auth').userDid).realtimeStatus()),
   );
+  app.post('/debug/reauth-prompt/reset', async (c) => {
+    await userStub(c.env, c.get('auth').userDid).debugResetReauthThrottle();
+    return c.json({ reset: true });
+  });
   app.get('/debug/delegation', async (c) =>
     c.json(
       await userStub(c.env, c.get('auth').userDid).delegationStatus(
@@ -487,6 +527,39 @@ export function createShell(
   app.get('/debug/matrix/outbox', async (c) =>
     c.json({ rows: await gateway(c.env).listOutbox() }),
   );
+  // Drill: post a custom event into the caller's own room under a
+  // caller-pinned transaction id. The same id twice returns the same event
+  // (the homeserver deduplicates per device), which is what makes a
+  // best-effort post retried across a gateway restart land once.
+  app.post('/debug/matrix/event', async (c) => {
+    const parsed = DebugEventBody.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success)
+      return c.json(
+        { error: 'expected { type: string, content: object, txnId?: string }' },
+        400,
+      );
+    const room = await gateway(c.env).resolveUserRoom(c.get('auth').userDid);
+    if (!room) return c.json({ error: 'no room for this user' }, 404);
+    const { type, content, txnId } = parsed.data;
+    const eventId = await gateway(c.env).sendEvent(
+      room.roomId,
+      type,
+      JSON.stringify(content),
+      txnId === undefined ? {} : { txnId },
+    );
+    return c.json({ roomId: room.roomId, eventId });
+  });
+  app.post('/debug/matrix/abort', async (c) => {
+    try {
+      await gateway(c.env).debugAbortObject();
+    } catch (err) {
+      if (!isAbortRejection(err))
+        return c.json({ aborted: false, error: errorText(err) }, 500);
+    }
+    return c.json({ aborted: true });
+  });
   app.post('/debug/matrix/restart', async (c) =>
     c.json(await gateway(c.env).restart()),
   );

package/src/shell/turn-body-cap.ts

@@ -0,0 +1,19 @@
+/**
+ * Upper bound on a chat turn's request body (`POST /messages/:sessionId`).
+ *
+ * The cap bounds the memory one request can pin: the shell reads the body in
+ * full before forwarding it to the user object. It no longer mirrors the Node
+ * runtime, which keeps Express body-parser's 100 kb default — a normal Portal
+ * turn now exceeds that. Every turn carries the browser-tool catalogue (26–32
+ * tools, 65–70 KiB of JSON schema) and the AG-UI action schemas (~27 KiB)
+ * before the message text, and a compose-topic turn adds the pinned text in
+ * `metadata.contextToolCall`; on devnet turns of 102–115 KiB were refused.
+ * 256 KiB leaves room for those. Attachments never count: files go to Matrix
+ * media first and the body carries only their references.
+ */
+export const MAX_TURN_BODY_BYTES = 256 * 1024;
+
+/** Whether a raw body is over the cap, measured as the UTF-8 bytes the wire carried. */
+export function turnBodyTooLarge(body: string): boolean {
+  return new TextEncoder().encode(body).byteLength > MAX_TURN_BODY_BYTES;
+}