@ixo/oracle-runtime-workers 0.37.2 → 0.39.0

package/src/core/tool-access.ts

@@ -6,13 +6,8 @@ import type {
   PluginTool,
 } from '../plugin-api/types';
 import type { CapabilityRequirement } from './manifest';
-import type {
-  RegisteredSubAgent,
-  SubAgentRegistry,
-  ToolRegistry,
-} from './registries';
+import type { RegisteredSubAgent } from './registries';
 import { computeSubAgentToolName } from './subagent-as-tool';
-import { NOOP_LOGGER } from './utils';
 
 /** `ctx.ucan.hasCapability` bound to the turn's delegation. */
 export type HasCapability = (resource: string, action: string) => boolean;
@@ -53,8 +48,8 @@ export interface TurnToolAccess<
   /**
    * Plugins that contributed tools or sub-agents of which none is left.
    * Treated like a plugin whose `requires` are unmet (left out of the
-   * prompt, refused by `load_capability`, never preloaded) except that they
-   * are hidden outright: `list_capabilities` does not list them.
+   * prompt, refused by `load_capability`, not offered to the router) except
+   * that they are hidden outright: `list_capabilities` does not list them.
    */
   hiddenPlugins: ReadonlySet<string>;
 }
@@ -145,30 +140,6 @@ export function resolveTurnToolAccess<
   return { tools, subAgents, withheldToolNames, hiddenPlugins };
 }
 
-/**
- * `hiddenPlugins` from the boot-time contributions alone, for the
- * capability router, which predicts before the turn's request-time tools are
- * collected. A plugin whose request-time tools would make it usable may be
- * left out here (the router does not offer it; `load_capability` still
- * can); one whose request-time tools are all withheld may be offered, and
- * the turn's build voids that preload (`createMainAgent`).
- */
-export async function bootHiddenPlugins(input: {
-  registries: { tools: ToolRegistry; subAgents: SubAgentRegistry };
-  buildCtx: PluginContext;
-  has: HasCapability;
-}): Promise<ReadonlySet<string>> {
-  const { registries, buildCtx, has } = input;
-  return resolveTurnToolAccess({
-    tools: await registries.tools.collectBoot(buildCtx),
-    subAgents: registries.subAgents.collectBoot(buildCtx),
-    buildCtx,
-    has,
-    // A failing sub-agent is reported by the turn's build, once.
-    logger: NOOP_LOGGER,
-  }).hiddenPlugins;
-}
-
 /**
  * The manifest as this turn may show it: `examples` naming a withheld tool
  * removed, so neither the Tier-1 prompt nor `load_capability` teaches the

package/src/core/wrap-plugin-tool.ts

@@ -1,5 +1,6 @@
 import { ToolMessage } from '@langchain/core/messages';
 import { Command } from '@langchain/langgraph';
+import { withoutStructuredCopy } from './mcp-result';
 import { capToolResult, type ResultCapConfig } from './middlewares/result-cap';
 import { tool } from '@langchain/core/tools';
 import type { StructuredTool } from 'langchain';
@@ -125,7 +126,7 @@ export function wrapPluginTool(
       );
       if (pluginName !== undefined)
         requireToolPlane(ctx, pluginName, pluginTool);
-      const output = await pluginTool.handler(args, ctx);
+      const output = withoutStructuredCopy(await pluginTool.handler(args, ctx));
       // A tool's own message (a result that says the tool did not run) is
       // returned whole, never capped into text.
       if (

package/src/do/contracts.ts

@@ -248,6 +248,13 @@ export interface OracleWorkerEnv {
    * `"ai": { "binding": "AI" }` in the wrangler config.
    */
   AI?: Ai;
+  /**
+   * Cloudflare Images binding. Optional: images sent natively to a model are
+   * downscaled to a 1568 px long edge as JPEG first (`attachments/resize.ts`); the
+   * sandbox keeps the original. Absent = images go as they are. Declare it
+   * with `"images": { "binding": "IMAGES" }` in the wrangler config.
+   */
+  IMAGES?: ImagesBinding;
 
   // --- llm ----------------------------------------------------------------
   OPEN_ROUTER_API_KEY: string;
@@ -264,6 +271,8 @@ export interface OracleWorkerEnv {
   LLM_STREAM_IDLE_TIMEOUT_MS?: string;
   LLM_BYO_STREAM_IDLE_TIMEOUT_MS?: string;
   LLM_STREAM_RETRIES?: string;
+  /** Most tokens one platform model call may generate, reasoning included (default 16384; 0 = the model's limit). */
+  LLM_MAX_OUTPUT_TOKENS?: string;
   /** LangGraph steps one turn may take before `GraphRecursionError` (default 600; Node hard-codes 200). */
   TURN_RECURSION_LIMIT?: string;
   /** Turn budget: tool attempts (default 120) and deadline in ms (600000). */
@@ -288,7 +297,12 @@ export interface OracleWorkerEnv {
   MODEL_CONTEXT_TOKENS?: string;
   MODEL_CONTEXT_OVERRIDES?: string;
   CONTEXT_SUMMARIZE_FRACTION?: string;
+  CONTEXT_SUMMARIZE_MAX_TOKENS?: string;
   CONTEXT_PRUNE_FRACTION?: string;
+  CONTEXT_PRUNE_MAX_TOKENS?: string;
+  CONTEXT_STALE_RESULT_TURNS?: string;
+  CONTEXT_CACHE_COLD_MS?: string;
+  CONTEXT_PLUGIN_IDLE_TURNS?: string;
   CONTEXT_RESULT_CAP_FRACTION?: string;
   CONTEXT_RESULT_CAP_MAX_CHARS?: string;
   CONTEXT_REQUEST_FRACTION?: string;
@@ -320,9 +334,14 @@ export interface OracleWorkerEnv {
   /**
    * Capability router (needs a `DECISION_PROVIDER`). `off` (default) never
    * evaluates; `shadow` evaluates and logs the verdict without preloading;
-   * `on` preloads the predicted on-demand plugin's tools for the turn.
+   * `on` loads the predicted plugins on the thread before the first model
+   * call.
    */
   CAPABILITY_ROUTER?: CapabilityRouterMode;
+  /** The score a preload needs on a warm turn (default 0.8; above 1, never). */
+  CAPABILITY_ROUTER_WARM_THRESHOLD?: string;
+  /** The score a preload needs on a cold turn (default 0.7). */
+  CAPABILITY_ROUTER_COLD_THRESHOLD?: string;
   /** Applies exclusively to authenticated channel admission; Portal/Matrix turns never route. */
   CHANNEL_SEMANTIC_ROUTING?: 'off' | 'shadow' | 'on';
   CHANNEL_SEMANTIC_ROUTING_BINDINGS?: string;
@@ -982,10 +1001,9 @@ export interface CreateRoomOptions {
 }
 
 /**
- * Deadline for one gateway media download, from opening it to the last byte
- * (the gateway's default applies when omitted). Only the timeout crosses the
- * RPC: an `AbortSignal` cannot, so the caller stops a transfer early by
- * cancelling the returned stream.
+ * Deadline for one gateway media event lookup (`eventMediaInfo`; the
+ * gateway's default applies when omitted). Only the timeout crosses the RPC:
+ * an `AbortSignal` cannot.
  */
 export interface MediaDownloadDeadline {
   timeoutMs?: number;
@@ -1000,22 +1018,20 @@ export interface MediaDownloadDeadline {
  */
 export interface MatrixGatewayObject extends Rpc.DurableObjectBranded {
   /**
-   * A media event's content as a stream, AS STORED: in an E2EE room the
-   * ciphertext plus the `EncryptedFile` fields to pipe through the SDK's
-   * `createAttachmentDecryptor` on the caller's side (a stream that errors
-   * on the far side of an RPC only surfaces here as a disconnect, so the
-   * hash check belongs to the consumer). Null when unknown or redacted.
+   * Where the media of event `eventId` in `roomId` lives, as small JSON: the
+   * gateway fetches and decrypts the EVENT (only it holds the room keys),
+   * never the media. The caller downloads `mxc` from the homeserver itself
+   * (`openHomeserverMedia`, with the plugin device's token) and decrypts it
+   * with `file` (`createAttachmentDecryptor`), so no media byte crosses the
+   * shared gateway object. Bounded by `opts.timeoutMs` (default the media
+   * download deadline). Null when the event is unknown, redacted or carries
+   * no media.
    */
-  downloadEventMediaStream(
+  eventMediaInfo(
     roomId: string,
     eventId: string,
     opts?: MediaDownloadDeadline,
-  ): Promise<MediaStream | null>;
-  /** Authenticated media download of an `mxc://` URI, as a stream. */
-  downloadMxcMediaStream(
-    mxc: string,
-    opts?: MediaDownloadDeadline,
-  ): Promise<ReadableStream<Uint8Array>>;
+  ): Promise<EventMediaInfo | null>;
   /** Forcibly reset the gateway object like a platform host drain (debug routes only). The call itself rejects. */
   debugAbortObject(): Promise<void>;
   /** Stop the bot (operator/debug; `ensureStarted`/cron brings it back). */
@@ -1042,11 +1058,16 @@ export interface MatrixGatewayObject extends Rpc.DurableObjectBranded {
   listOutbox(): Promise<OutboxRow[]>;
   /**
    * Credentials of the oracle's second, crypto-less device for plugins that
-   * run their own Matrix client (editor, flows). Logged in once with the
-   * account password, kept in the gateway's storage, re-logged in with the
-   * same device id if the homeserver ever rejects the token.
+   * run their own Matrix client (editor, flows) and for the user objects'
+   * own media transfers (channel file uploads, Matrix media downloads).
+   * Logged in once with the account password, kept in the gateway's
+   * storage; concurrent first calls share one login. A caller whose
+   * request the homeserver answered 401 passes the token it used as
+   * `rejected`: when that is still the cached token, the cache is dropped and
+   * the stored token re-validated (`whoami`), else the device is logged in
+   * again with the same device id — once, for every caller waiting.
    */
-  botCredentials(): Promise<BotCredentials>;
+  botCredentials(opts?: { rejected?: string }): Promise<BotCredentials>;
   status(): Promise<GatewayStatus>;
   /** Send a text message (encrypted when the room is). Returns the event id. */
   sendText(
@@ -1075,12 +1096,18 @@ export interface MatrixGatewayObject extends Rpc.DurableObjectBranded {
    * event id. `txnId` pins the transaction id, as for `sendText`: the
    * homeserver deduplicates by it per device, so a send retried after a lost
    * response returns the original event instead of posting a second one.
+   * `priority: 'background'` (channel text mirrors, channel file events)
+   * goes through the gateway's small background lane, so such sends never
+   * hold more than a few of the send path's places ahead of a reply
+   * (`interactive`, the default). Content carrying an attachment key
+   * (`file.key`) is refused for a room the gateway does not see as
+   * end-to-end encrypted.
    */
   sendEvent(
     roomId: string,
     type: string,
     content: JsonString,
-    opts?: { txnId?: string },
+    opts?: { txnId?: string; priority?: 'interactive' | 'background' },
   ): Promise<string>;
   /** Resolve the canonical user↔oracle room for a user DID (alias lookup, cached). */
   resolveUserRoom(
@@ -1105,7 +1132,7 @@ export interface MatrixGatewayObject extends Rpc.DurableObjectBranded {
   ): Promise<{ eventId: string }>;
   /**
    * The latest snapshot for `storageKey` as a stream, as stored (see
-   * `downloadEventMediaStream`), or null when none exists.
+   * `MediaStream`), or null when none exists.
    */
   downloadUserSnapshotStream(
     userDid: string,
@@ -1200,7 +1227,6 @@ export interface OutboxRow {
   enqueuedAt: number;
 }
 
-/** `MatrixBotDO.status()` plus the gateway's own turn bookkeeping. */
 /**
  * Media handed across the Durable Object boundary as a stream, as stored on
  * the homeserver: `file` is present when the event carried an encrypted
@@ -1216,6 +1242,19 @@ export interface MediaStream {
   filename?: string;
 }
 
+/**
+ * Where a media event's file lives (`MatrixGatewayObject.eventMediaInfo`):
+ * its `mxc://` URI and, for an encrypted attachment, the `EncryptedFile`
+ * fields to decrypt it with. `size` is the sender's `info.size` when set.
+ */
+export interface EventMediaInfo {
+  mxc: string;
+  file?: EncryptedFileInfo;
+  mimetype?: string;
+  filename?: string;
+  size?: number;
+}
+
 /** `MediaStream` of a user's snapshot, plus the media event that carries it. */
 export interface SnapshotStream extends MediaStream {
   eventId: string;
@@ -1229,6 +1268,7 @@ export interface GroupRoomInfo {
   groupLane: boolean;
 }
 
+/** `MatrixBotDO.status()` plus the gateway's own turn bookkeeping. */
 export interface GatewayStatus extends BotStatus {
   turns: { inFlight: number; waiting: number };
   /** Channel memory of group rooms: messages awaiting compaction, summary chunks, pinned facts. */

package/src/do/room-mirror.ts

@@ -19,9 +19,20 @@ import {
  * - sends are serialised per session (parallel across sessions), so a reply
  *   being retried can never overtake the message it answers, and a later
  *   turn's mirrors queue behind an earlier turn's.
+ *
+ * The same chain carries the media events of a channel turn's files
+ * (`sendMedia`, built by `attachments/room-media.ts`): the owner object
+ * queues them in file order right after the person's text, so each is
+ * posted after that text and before the reply, whenever its upload ends.
  */
+import type { EncryptedFileInfo } from '@ixo/matrix-bot-workers-sdk';
+import { abortError, untilAborted } from '../attachments/download';
 import { matrixTxnId } from '../matrix/txn-id';
-import { retryGateway, type RetryGatewayOptions } from './gateway-retry';
+import {
+  isTransientGatewayError,
+  retryGateway,
+  type RetryGatewayOptions,
+} from './gateway-retry';
 
 export type MirrorAuthor = 'user' | 'oracle';
 
@@ -53,8 +64,43 @@ export interface MirrorSend {
   };
 }
 
+/** The `org.ixo.qi.origin` input of a channel mirror. */
+export type MirrorOrigin = NonNullable<MirrorSend['origin']>;
+
+/**
+ * The media part of an `m.room.message` file event (`m.image` / `m.video` /
+ * `m.audio` / `m.file`): what the room shows, without the thread relation
+ * and the channel origin, which `mediaEventContent` adds.
+ */
+export interface MediaMessage {
+  msgtype: 'm.image' | 'm.video' | 'm.audio' | 'm.file';
+  body: string;
+  filename: string;
+  info: { mimetype: string; size: number };
+  /**
+   * The encrypted attachment: its `mxc://` plus the `EncryptedFile` fields.
+   * Always encrypted: a file is only ever posted into a Megolm room.
+   */
+  file: { url: string } & EncryptedFileInfo;
+}
+
+export interface MediaMirrorSend {
+  roomId: string;
+  /** The session's marker event — the thread the file is posted under. */
+  threadId: string;
+  txnId: string;
+  origin?: MirrorOrigin;
+  media: MediaMessage;
+}
+
 export interface RoomMirrorDeps {
   sendText(send: MirrorSend): Promise<string>;
+  /**
+   * Send one file event (`content` JSON-encoded) with a pinned transaction
+   * id, at background priority (`MatrixGatewayObject.sendEvent`); returns
+   * its event id.
+   */
+  sendEvent(roomId: string, content: string, txnId: string): Promise<string>;
   /** Keeps the (un-awaited) send alive past the request that started it: `ctx.waitUntil`. */
   keepAlive(work: Promise<unknown>): void;
   log(message: string): void;
@@ -63,6 +109,16 @@ export interface RoomMirrorDeps {
   retry?: Pick<RetryGatewayOptions, 'delaysMs' | 'sleep' | 'isTransient'>;
 }
 
+/** The relation that posts an event in the thread of `threadId` (with the reply fallback for clients without threads). */
+function threadRelation(threadId: string) {
+  return {
+    rel_type: 'm.thread',
+    event_id: threadId,
+    is_falling_back: true,
+    'm.in_reply_to': { event_id: threadId },
+  };
+}
+
 export function mirrorEventContent(send: MirrorSend) {
   return {
     msgtype: 'm.text',
@@ -70,12 +126,7 @@ export function mirrorEventContent(send: MirrorSend) {
     ...(send.formattedBody
       ? { format: 'org.matrix.custom.html', formatted_body: send.formattedBody }
       : {}),
-    'm.relates_to': {
-      rel_type: 'm.thread',
-      event_id: send.threadId,
-      is_falling_back: true,
-      'm.in_reply_to': { event_id: send.threadId },
-    },
+    'm.relates_to': threadRelation(send.threadId),
     ...(send.origin
       ? {
           'org.ixo.qi.origin': channelOrigin(send.origin),
@@ -87,6 +138,19 @@ export function mirrorEventContent(send: MirrorSend) {
   };
 }
 
+/**
+ * A file event in the session thread: the media part, the thread relation
+ * of the text mirrors and their `org.ixo.qi.origin` (never the quote, which
+ * the text mirror of the same message carries).
+ */
+export function mediaEventContent(send: MediaMirrorSend) {
+  return {
+    ...send.media,
+    'm.relates_to': threadRelation(send.threadId),
+    ...(send.origin ? { 'org.ixo.qi.origin': channelOrigin(send.origin) } : {}),
+  };
+}
+
 const errorText = (err: unknown): string =>
   err instanceof Error ? err.message : String(err);
 
@@ -115,38 +179,98 @@ export class RoomMirror {
     label: string,
     required = false,
   ): Promise<void> {
-    const previous = this.chains.get(sessionId) ?? Promise.resolve();
-    // Starts once the previous mirror settled either way: a required mirror
-    // that failed (and rejected its own caller) must not skip this one.
-    const tracked: Promise<void> = previous
-      .catch(() => undefined)
-      .then(() => prepare())
-      .then((send) => (send ? this.send(send, label) : undefined))
-      .catch((err: unknown) => {
+    return this.chain(sessionId, async () => {
+      try {
+        const send = await prepare();
+        if (send)
+          await this.send(() => this.deps.sendText(send), send.threadId, label);
+      } catch (err) {
         if (required) throw err;
         this.deps.warn(
           `[user-do] Matrix replay (${label}) failed — session=${sessionId}: ${errorText(err)}`,
         );
-      })
+      }
+    });
+  }
+
+  /**
+   * Queue one file event behind the session's previous mirrors. When its
+   * turn in the chain comes, `prepare` builds the event (it waits for the
+   * file's upload; `null` = nothing to post) and the send follows with the
+   * transient retries; resolves with the event id, or null when nothing was
+   * posted. `signal` is honoured throughout: checked before `prepare` and
+   * before every send attempt, and it ends the wait on `prepare` — once it
+   * aborts no further attempt is made and the call rejects with its reason.
+   * A send that fails after the retries rejects.
+   */
+  sendMedia(
+    sessionId: string,
+    prepare: () => Promise<MediaMirrorSend | null>,
+    label: string,
+    signal?: AbortSignal,
+  ): Promise<string | null> {
+    return this.chain(sessionId, async () => {
+      if (signal?.aborted) throw abortError(signal);
+      const send = await (signal ? untilAborted(prepare(), signal) : prepare());
+      if (!send) return null;
+      const content = JSON.stringify(mediaEventContent(send));
+      return this.send(
+        () => {
+          if (signal?.aborted) return Promise.reject(abortError(signal));
+          return this.deps.sendEvent(send.roomId, content, send.txnId);
+        },
+        send.threadId,
+        label,
+        signal,
+      );
+    });
+  }
+
+  /**
+   * Run `work` once the session's previous mirrors have settled either way
+   * (a required mirror that failed, and rejected its own caller, must not
+   * skip the next one), keep it alive past the request, and drop the chain
+   * once it drains.
+   */
+  private chain<T>(sessionId: string, work: () => Promise<T>): Promise<T> {
+    const previous = this.chains.get(sessionId) ?? Promise.resolve();
+    // Settles (as `work` did) once the chain entry is gone, so a caller that
+    // awaited it sees the session's chain drained.
+    const done = previous
+      .catch(() => undefined)
+      .then(work)
       .finally(() => {
         if (this.chains.get(sessionId) === tracked)
           this.chains.delete(sessionId);
       });
+    const tracked: Promise<void> = done.then(
+      () => undefined,
+      () => undefined,
+    );
     this.chains.set(sessionId, tracked);
     this.deps.keepAlive(tracked);
-    return tracked;
+    return done;
   }
 
-  private async send(send: MirrorSend, label: string): Promise<void> {
-    const eventId = await retryGateway(() => this.deps.sendText(send), {
+  private async send(
+    post: () => Promise<string>,
+    threadId: string,
+    label: string,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    const isTransient = this.deps.retry?.isTransient ?? isTransientGatewayError;
+    const eventId = await retryGateway(post, {
       ...this.deps.retry,
+      // An abort is final: the transient check would otherwise retry it.
+      isTransient: (err) => !signal?.aborted && isTransient(err),
       onRetry: (err, attempt, delayMs) =>
         this.deps.warn(
           `[user-do] Matrix replay (${label}) send failed (attempt ${attempt}) — retrying in ${delayMs} ms with the same transaction id: ${errorText(err)}`,
         ),
     });
     this.deps.log(
-      `[user-do] Matrix replay (${label}) → ${eventId} in thread ${send.threadId}`,
+      `[user-do] Matrix replay (${label}) → ${eventId} in thread ${threadId}`,
     );
+    return eventId;
   }
 }

package/src/do/transcript.ts

@@ -111,7 +111,7 @@ export function contentToText(content: BaseMessage['content']): string {
         if (typeof part === 'string') return part;
         if (part && typeof part === 'object' && 'text' in part) {
           const text = (part as { text?: unknown }).text;
-          // The retention placeholder is model-facing only; the transcript
+          // The attachment placeholder is model-facing only; the transcript
           // keeps listing the attachment from its metadata.
           return typeof text === 'string' && !isAttachmentPlaceholderText(text)
             ? text
@@ -140,6 +140,45 @@ export function visibleText(message: BaseMessage): string {
   return contentToText(visibleContent(message));
 }
 
+/**
+ * Whether a stored message is one the user sees in the transcript. System and
+ * tool messages never are, nor a failed reply, nor anything the runtime wrote
+ * for the model about an attachment: the extracted text of a file (an AI
+ * message with an `attachment`) and `view_attachment` re-attaching a payload,
+ * nor a chat gateway's delivery notice.
+ */
+export function visibleToUser(message: BaseMessage): boolean {
+  if (message.type === 'system' || message.type === 'tool') return false;
+  const kw = (message.additional_kwargs ?? {}) as Record<string, unknown>;
+  if (kw.isError) return false;
+  if (message.type === 'ai' && Boolean(kw.attachment)) return false;
+  // A chat gateway's delivery notice: the model's, never a user message.
+  return !isAttachmentViewMessage(message) && !isDeliveryNoticeMessage(message);
+}
+
+/**
+ * The latest turns as the user saw them, oldest first and each as
+ * `user: …` or `assistant: …` cut to `maxChars`, from messages listed newest
+ * first. Only what `visibleToUser` lets through, without summaries and rows
+ * with no visible text.
+ */
+export function recentTurnTexts(
+  newestFirst: readonly BaseMessage[],
+  limit: number,
+  maxChars: number,
+): string[] {
+  const turns: string[] = [];
+  for (const message of newestFirst) {
+    if (turns.length === limit) break;
+    if (isSummarizationMessage(message) || !visibleToUser(message)) continue;
+    const text = visibleText(message).trim();
+    if (!text) continue;
+    const speaker = message.type === 'human' ? 'user' : 'assistant';
+    turns.push(`${speaker}: ${text.slice(0, maxChars)}`);
+  }
+  return turns.reverse();
+}
+
 /**
  * The summarization middleware's bookkeeping message — never shown to users.
  * LangChain 1.4 writes it as a HUMAN message tagged
@@ -171,18 +210,8 @@ export async function transformTranscript(
   for (const message of messages) {
     const toolMsg = message.type === 'tool' ? (message as ToolMessage) : null;
     const kw = (message.additional_kwargs ?? {}) as Record<string, unknown>;
-    const isExtractionContext = message.type === 'ai' && Boolean(kw.attachment);
 
-    if (
-      message.type !== 'system' &&
-      message.type !== 'tool' &&
-      !kw.isError &&
-      !isExtractionContext &&
-      // `view_attachment` re-attaching an offloaded payload — model-facing.
-      !isAttachmentViewMessage(message) &&
-      // A chat gateway's delivery notice — the model's, never a user message.
-      !isDeliveryNoticeMessage(message)
-    ) {
+    if (visibleToUser(message)) {
       const reasoning = reasoningToText(kw.reasoning);
       const attachments =
         message.type === 'human'

package/src/do/turn-attachments.ts

@@ -15,6 +15,7 @@ import {
   type ChannelMediaSource,
   type PreparedAttachments,
 } from '../attachments';
+import type { ChannelThreadFile } from '../attachments/room-media';
 import { parseChannelServiceDids } from '../channels/auth';
 import {
   channelAttachmentInputs,
@@ -58,26 +59,64 @@ export function channelTurnLinks(
   }));
 }
 
+/**
+ * A channel turn's files as `room-media.ts` posts them to the session
+ * thread: the first occurrence of each file (a file sent twice in one
+ * message is posted once), with its position in the message.
+ */
+export function channelThreadFiles(req: TurnFiles): ChannelThreadFile[] {
+  if (req.client !== 'channel' || !req.channel?.attachments?.length) return [];
+  const bindingId = req.channel.bindingId;
+  const seen = new Set<string>();
+  const files: ChannelThreadFile[] = [];
+  req.channel.attachments.forEach((file, index) => {
+    const ref = channelAttachmentRef(file.sha256);
+    if (seen.has(ref)) return;
+    seen.add(ref);
+    files.push({
+      ref,
+      index,
+      link: { url: file.url, sha256: file.sha256, bindingId },
+      filename: file.filename,
+      mimetype: file.mimetype,
+      size: file.size,
+      kind: file.kind,
+    });
+  });
+  return files;
+}
+
+/** The https origins channel files are fetched from: the gateways of `CHANNEL_SERVICE_DID`. */
+export function channelGatewayOrigins(
+  channelServiceDid: string | undefined,
+): string[] {
+  return channelMediaOrigins(parseChannelServiceDids(channelServiceDid));
+}
+
 /**
  * The channel source of a turn in `sessionId`: a reference resolves to the
  * turn's own files first, then to the links kept for the session; only the
- * gateways of `CHANNEL_SERVICE_DID` are fetched from.
+ * gateways of `CHANNEL_SERVICE_DID` are fetched from. The store also names
+ * the room copy of a file posted to the session thread, which serves it
+ * when its link fails or has expired (`loadAttachmentBytes`).
  */
 export function turnChannelMediaSource(input: {
   sessionId: string;
   turnLinks: ReadonlyArray<ChannelMediaLink & { ref: string }>;
-  store: Pick<ChannelAttachmentLinkStore, 'get'> | null;
+  store: Pick<ChannelAttachmentLinkStore, 'get' | 'eventIdOf'> | null;
   channelServiceDid: string | undefined;
 }): ChannelMediaSource {
+  const store = input.store;
   return createChannelMediaSource({
-    origins: channelMediaOrigins(
-      parseChannelServiceDids(input.channelServiceDid),
-    ),
+    origins: channelGatewayOrigins(input.channelServiceDid),
     resolve: async (ref) => {
       const own = input.turnLinks.find((link) => link.ref === ref);
       if (own) return own;
-      return input.store?.get(input.sessionId, ref);
+      return store?.get(input.sessionId, ref);
     },
+    ...(store
+      ? { roomEventOf: (ref: string) => store.eventIdOf(input.sessionId, ref) }
+      : {}),
   });
 }
 

package/src/do/turn-metadata.ts

@@ -62,6 +62,16 @@ export interface PriorMetadataState {
   sessionRunId?: string;
   currentEntityDid?: string;
   loadedPlugins?: string[];
+  /** The plugins whose operating guides the prompt carried (`operating-guides.ts`). */
+  promptGuides?: string[];
+  /** The plugins whose usage the thread's messages carry (`operating-guides.ts`). */
+  capabilityUsage?: string[];
+}
+
+function strings(value: unknown): string[] | undefined {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === 'string')
+    : undefined;
 }
 
 function priorString(
@@ -75,15 +85,17 @@ function priorString(
 export function priorMetadataState(
   prior: Record<string, unknown>,
 ): PriorMetadataState {
-  const loaded = prior['loadedPlugins'];
+  const loaded = strings(prior['loadedPlugins']);
+  const promptGuides = strings(prior['promptGuides']);
+  const capabilityUsage = strings(prior['capabilityUsage']);
   return {
     editorRoomId: priorString(prior, 'editorRoomId'),
     spaceId: priorString(prior, 'spaceId'),
     sessionRunId: priorString(prior, 'sessionRunId'),
     currentEntityDid: priorString(prior, 'currentEntityDid'),
-    ...(Array.isArray(loaded)
-      ? { loadedPlugins: loaded.filter((p) => typeof p === 'string') }
-      : {}),
+    ...(loaded ? { loadedPlugins: loaded } : {}),
+    ...(promptGuides ? { promptGuides } : {}),
+    ...(capabilityUsage ? { capabilityUsage } : {}),
   };
 }