@ixo/oracle-runtime-workers 0.37.2 → 0.39.0

package/src/index.ts

@@ -60,6 +60,7 @@ export {
 } from './do/user-oracle-do';
 export type {
   DocumentRequest,
+  DomainBriefDetail,
   DomainCapsuleInspection,
   DomainContextOptions,
   DomainContextPins,

package/src/llm/provider-error.ts

@@ -268,10 +268,13 @@ export function markPlatformFallbackFailure(error: unknown): void {
   if (error && typeof error === 'object') PLATFORM_FALLBACK_FAILURES.add(error);
 }
 
-/** The error, or one it wraps (`cause`, as LangChain's MiddlewareError does). */
+/**
+ * The error, or one it wraps (`cause`, as LangChain's MiddlewareError does,
+ * once per middleware layer).
+ */
 function isPlatformFallbackFailure(error: unknown): boolean {
   let current: unknown = error;
-  for (let depth = 0; depth < 8; depth += 1) {
+  for (let depth = 0; depth < 32; depth += 1) {
     if (!current || typeof current !== 'object') return false;
     if (PLATFORM_FALLBACK_FAILURES.has(current)) return true;
     current = 'cause' in current ? current.cause : undefined;

package/src/llm/stream-liveness.ts

@@ -83,11 +83,12 @@ export class ProviderStallError extends Error {
 /**
  * The `ProviderStallError` in `error` or its `cause` chain — the OpenAI SDK
  * wraps a failed `fetch` in `APIConnectionError` with the original as
- * `cause`, LangChain's middleware errors wrap again.
+ * `cause`, LangChain's middleware errors wrap again, once per middleware
+ * layer (a dozen on the main agent), so the walk goes deep.
  */
 export function findProviderStall(error: unknown): ProviderStallError | null {
   let current: unknown = error;
-  for (let depth = 0; depth < 8; depth += 1) {
+  for (let depth = 0; depth < 32; depth += 1) {
     if (current instanceof ProviderStallError) return current;
     if (!current || typeof current !== 'object' || !('cause' in current))
       return null;

package/src/matrix/gateway-do.ts

@@ -24,9 +24,11 @@ import {
   listPendingSends,
   MatrixBotDO,
   optionsFromEnv,
+  parseEncryptedFileInfo,
   Semaphore,
   withRateLimitRetry,
   type BotMessage,
+  type EncryptedFileInfo,
   type BotTimelineEvent,
   type MatrixBotOptions,
   type StartResult,
@@ -37,6 +39,7 @@ import {
   userOracleRoomAlias,
   type BotCredentials,
   type CreateRoomOptions,
+  type EventMediaInfo,
   type GatewayStatus,
   type GroupRoomInfo,
   type JsonString,
@@ -99,11 +102,7 @@ import {
 } from './user-homeserver';
 import { replyPartTxnId, roomReplyMessages } from './reply-parts';
 import { VerifiedRoomAliases } from './room-alias';
-import {
-  boundedSignal,
-  raceSignal,
-  streamWithDeadline,
-} from './media-deadline';
+import { boundedSignal, raceSignal } from './media-deadline';
 
 const TYPING_REFRESH_MS = 20_000;
 const TYPING_TIMEOUT_MS = 30_000;
@@ -122,11 +121,19 @@ const MEMO_MAX_ENTRIES = 5_000;
  */
 const STATUS_CACHE_MS = 5_000;
 /**
- * Upper bound on one media download (response and body), unless the caller
- * asks for less. A stalled homeserver stream must not hold the reader — and
- * with it the user's turn — open indefinitely.
+ * Upper bound on one media event lookup (`eventMediaInfo`), unless the caller
+ * asks for less. A stalled homeserver must not hold the user's turn open
+ * indefinitely.
  */
 export const MEDIA_DOWNLOAD_TIMEOUT_MS = 60_000;
+/**
+ * `sendEvent` calls with `priority: 'background'` (channel text mirrors and
+ * file events) in the SDK's send path at once. The SDK 0.7.0 `sendEvent`
+ * dispatches every event `interactive`, so this lane is what keeps a burst
+ * of them from queueing ahead of replies in the rate-limited sender: at most
+ * this many sit there, the rest wait here.
+ */
+export const BACKGROUND_SEND_CONCURRENCY = 2;
 /**
  * A live message whose sender's homeserver could not be looked up stays in
  * the inbox and is replayed on its own after this delay (each replay is
@@ -184,6 +191,90 @@ interface OracleGatewayConfig {
   oracleRoomDid: string;
 }
 
+/** A JSON object's own property, or undefined. */
+function prop(value: unknown, name: string): unknown {
+  return typeof value === 'object' && value !== null && name in value
+    ? Reflect.get(value, name)
+    : undefined;
+}
+
+/** Whether event content (JSON) carries an attachment key (`file.key`, `EncryptedFile`). */
+function carriesAttachmentKey(content: JsonString): boolean {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    // The SDK refuses content that is not a JSON object.
+    return false;
+  }
+  return prop(prop(parsed, 'file'), 'key') !== undefined;
+}
+
+/**
+ * The `EncryptedFile` fields of an event's `file`, validated
+ * (`parseEncryptedFileInfo` throws on a malformed one) and rebuilt from the
+ * checked values, without `url`, `mimetype` and `size`.
+ */
+function encryptedFileOf(file: unknown): EncryptedFileInfo {
+  parseEncryptedFileInfo(file);
+  const key = prop(file, 'key');
+  const k = prop(key, 'k');
+  const iv = prop(file, 'iv');
+  const sha256 = prop(prop(file, 'hashes'), 'sha256');
+  if (
+    typeof k !== 'string' ||
+    typeof iv !== 'string' ||
+    typeof sha256 !== 'string'
+  )
+    throw new Error('encrypted attachment: malformed EncryptedFile');
+  const ops = prop(key, 'key_ops');
+  return {
+    v: 'v2',
+    key: {
+      kty: 'oct',
+      key_ops: Array.isArray(ops)
+        ? ops.filter((op): op is string => typeof op === 'string')
+        : ['encrypt', 'decrypt'],
+      alg: 'A256CTR',
+      k,
+      ext: true,
+    },
+    iv,
+    hashes: { sha256 },
+  };
+}
+
+/**
+ * Where a decrypted media event's file lives (`eventMediaInfo`): null for a
+ * redaction, a redacted (empty) event or one without an `mxc://` URL.
+ */
+export function mediaInfoOfEvent(
+  event: unknown,
+  eventId: string,
+): EventMediaInfo | null {
+  if (prop(event, 'type') === 'm.room.redaction') return null;
+  const content = prop(event, 'content');
+  if (typeof content !== 'object' || content === null) return null;
+  if (Object.keys(content).length === 0) return null;
+  const file = prop(content, 'file');
+  const mxc = file !== undefined ? prop(file, 'url') : prop(content, 'url');
+  if (typeof mxc !== 'string' || !mxc.startsWith('mxc://'))
+    throw new Error(
+      `MatrixGatewayDO: media event ${eventId} carries no mxc url`,
+    );
+  const info = prop(content, 'info');
+  const mimetype = prop(info, 'mimetype');
+  const size = prop(info, 'size');
+  const filename = prop(content, 'filename') ?? prop(content, 'body');
+  return {
+    mxc,
+    ...(file !== undefined ? { file: encryptedFileOf(file) } : {}),
+    ...(typeof mimetype === 'string' ? { mimetype } : {}),
+    ...(typeof filename === 'string' ? { filename } : {}),
+    ...(typeof size === 'number' ? { size } : {}),
+  };
+}
+
 /** The plugins' device credentials as stored (`identity:bot-client`). */
 interface StoredDevice {
   userId: string;
@@ -197,9 +288,9 @@ interface AliasCacheEntry {
   at: number;
 }
 
-/** A media download's bound. `signal` only works for a caller in this isolate: an `AbortSignal` cannot cross an RPC boundary. */
+/** A media event lookup's bound. `signal` only works for a caller in this isolate: an `AbortSignal` cannot cross an RPC boundary. */
 export interface MediaDownloadOptions {
-  /** Upper bound on the whole transfer (default `MEDIA_DOWNLOAD_TIMEOUT_MS`). */
+  /** Upper bound on the whole lookup (default `MEDIA_DOWNLOAD_TIMEOUT_MS`). */
   timeoutMs?: number;
   signal?: AbortSignal;
 }
@@ -371,6 +462,9 @@ export class MatrixGatewayDO
     gateSizeFromEnv(this.env.MATRIX_TURN_CONCURRENCY, DEFAULT_TURN_CONCURRENCY),
   );
   private pluginDevice: BotCredentials | null = null;
+  /** The plugin device lookup in flight: concurrent first callers share one `whoami` / login. */
+  private pluginDeviceLoad: Promise<BotCredentials> | null = null;
+  private readonly backgroundSends = new Semaphore(BACKGROUND_SEND_CONCURRENCY);
   /** Memoised `getOracleSecretsKey` result (private JWK JSON). */
   private oracleSecretsKeyJson: string | null = null;
   private oracleSigningMnemonic: string | null = null;
@@ -1535,7 +1629,7 @@ export class MatrixGatewayDO
   }
 
   // -------------------------------------------------------------------------
-  // User snapshots (SQLite files as room media) and media downloads
+  // User snapshots (SQLite files as room media) and media event lookups
   // -------------------------------------------------------------------------
 
   async uploadUserSnapshotStream(
@@ -1648,105 +1742,28 @@ export class MatrixGatewayDO
   }
 
   /**
-   * A media message (`m.image` / `m.file` / …) for the attachments pipeline,
-   * as stored (see `mediaStream`). Null when the event is unknown or redacted.
+   * See `MatrixGatewayObject.eventMediaInfo`: the media event fetched and
+   * decrypted here, its file left on the homeserver for the caller to read.
    */
-  async downloadEventMediaStream(
+  async eventMediaInfo(
     roomId: string,
     eventId: string,
     opts: MediaDownloadOptions = {},
-  ): Promise<MediaStream | null> {
+  ): Promise<EventMediaInfo | null> {
     const bound = boundedSignal(
       opts.timeoutMs ?? MEDIA_DOWNLOAD_TIMEOUT_MS,
       opts.signal,
     );
-    let media: MediaStream | null;
     try {
-      // The SDK opens the download without a signal: race it, and release a
-      // stream that arrives after the bound.
-      media = await raceSignal(
-        this.mediaStream(roomId, eventId),
+      const raw = await raceSignal(
+        this.getEvent(roomId, eventId),
         bound.signal,
-        (late) => void late?.stream.cancel().catch(() => undefined),
+        () => undefined,
       );
-    } catch (err) {
-      bound.clear();
-      throw err;
-    }
-    if (!media) {
-      bound.clear();
-      return null;
-    }
-    return { ...media, stream: streamWithDeadline(media.stream, bound) };
-  }
-
-  /**
-   * Authenticated download of an `mxc://` URI as a stream
-   * (`/_matrix/client/v1/media/download`, legacy fallback on 404), bounded
-   * by `opts.timeoutMs` (default `MEDIA_DOWNLOAD_TIMEOUT_MS`) from the
-   * request to the last byte.
-   */
-  async downloadMxcMediaStream(
-    mxc: string,
-    opts: MediaDownloadOptions = {},
-  ): Promise<ReadableStream<Uint8Array>> {
-    const bound = boundedSignal(
-      opts.timeoutMs ?? MEDIA_DOWNLOAD_TIMEOUT_MS,
-      opts.signal,
-    );
-    try {
-      const body = await this.fetchMxc(mxc, bound.signal);
-      return streamWithDeadline(body, bound);
-    } catch (err) {
+      return raw ? mediaInfoOfEvent(JSON.parse(raw), eventId) : null;
+    } finally {
       bound.clear();
-      throw err;
-    }
-  }
-
-  private async fetchMxc(
-    mxc: string,
-    signal: AbortSignal,
-  ): Promise<ReadableStream<Uint8Array>> {
-    const client = await this.startedClient();
-    const token = client.getAccessToken();
-    const headers: Record<string, string> = token
-      ? { Authorization: `Bearer ${token}` }
-      : {};
-    const authed = client.mxcUrlToHttp(
-      mxc,
-      undefined,
-      undefined,
-      undefined,
-      false,
-      true,
-      true,
-    );
-    if (!authed) throw new Error(`MatrixGatewayDO: invalid mxc url ${mxc}`);
-    let res = await fetch(authed, { headers, signal });
-    if (res.status === 404) {
-      const legacy = client.mxcUrlToHttp(
-        mxc,
-        undefined,
-        undefined,
-        undefined,
-        false,
-        true,
-        false,
-      );
-      if (legacy) {
-        await res.body?.cancel().catch(() => undefined);
-        res = await fetch(legacy, { headers, signal });
-      }
-    }
-    if (!res.ok) {
-      await res.body?.cancel().catch(() => undefined);
-      throw new Error(
-        `MatrixGatewayDO: media download failed: ${res.status} ${res.statusText}`,
-      );
     }
-    if (!res.body)
-      throw new Error('MatrixGatewayDO: media download has no body');
-    return res.body;
   }
 
   // -------------------------------------------------------------------------
@@ -1801,13 +1818,31 @@ export class MatrixGatewayDO
   /**
    * See `MatrixGatewayObject.botCredentials`: a second password device with
    * NO crypto store, for plugins that drive a raw matrix-js-sdk client
-   * (editor, flows) — it must never be the gateway's own E2EE device, whose
-   * one-time keys and store are the SDK's. Its id is pinned in storage so a
-   * re-login (token rejected) keeps the same device. Cached per instance
-   * after one `whoami`.
+   * (editor, flows) and the user objects' media transfers — it must never
+   * be the gateway's own E2EE device, whose one-time keys and store are the
+   * SDK's. Its id is pinned in storage so a re-login keeps the same device.
+   * Cached per instance after one `whoami`; concurrent callers share one
+   * lookup (a login rotates the token, so a herd would invalidate each
+   * other's). `rejected` drops the cache only when it is the cached token.
    */
-  async botCredentials(): Promise<BotCredentials> {
+  async botCredentials(
+    opts: { rejected?: string } = {},
+  ): Promise<BotCredentials> {
+    if (opts.rejected && this.pluginDevice?.accessToken === opts.rejected) {
+      this.log(
+        'warn',
+        'plugin device token rejected by a caller; re-validating',
+      );
+      this.pluginDevice = null;
+    }
     if (this.pluginDevice) return this.pluginDevice;
+    this.pluginDeviceLoad ??= this.loadPluginDevice().finally(() => {
+      this.pluginDeviceLoad = null;
+    });
+    return this.pluginDeviceLoad;
+  }
+
+  private async loadPluginDevice(): Promise<BotCredentials> {
     const cfg = this.cfg();
     const stored = await this.ctx.storage.get<StoredDevice>(
       BOT_CLIENT_IDENTITY_KEY,
@@ -1841,6 +1876,33 @@ export class MatrixGatewayDO
     return this.pluginDevice;
   }
 
+  /**
+   * See `MatrixGatewayObject.sendEvent`: the SDK's send, behind the
+   * background lane for `priority: 'background'`, and never an attachment
+   * key into a room this gateway does not see as end-to-end encrypted.
+   */
+  override async sendEvent(
+    roomId: string,
+    type: string,
+    content: JsonString,
+    opts: { txnId?: string; priority?: 'interactive' | 'background' } = {},
+  ): Promise<string> {
+    if (carriesAttachmentKey(content) && !(await this.isRoomEncrypted(roomId)))
+      throw new Error(
+        `MatrixGatewayDO: refusing to send an encrypted attachment's key into ${roomId}, which is not end-to-end encrypted`,
+      );
+    const send = (): Promise<string> =>
+      super.sendEvent(
+        roomId,
+        type,
+        content,
+        opts.txnId ? { txnId: opts.txnId } : {},
+      );
+    return opts.priority === 'background'
+      ? this.backgroundSends.run(send)
+      : send();
+  }
+
   // -------------------------------------------------------------------------
   // Operator surface
   // -------------------------------------------------------------------------

package/src/matrix/ingest.ts

@@ -85,9 +85,10 @@ export interface IngestDeps {
    */
   userServerName(userDid: string): string | null;
   /**
-   * The bot's Matrix user id. Its first occurrence in a message is rewritten
-   * to `(USER MENTIONED YOU @AI_AGENT)` before the agent sees it, as the Node
-   * bridge does; omit to leave messages as sent.
+   * The bot's Matrix user id. Its own messages are dropped (`'own'`), and its
+   * first occurrence in a message is rewritten to `(USER MENTIONED YOU
+   * @AI_AGENT)` before the agent sees it, as the Node bridge does; omit to
+   * leave messages as sent.
    */
   botUserId?: string;
   debounceMs?: number;
@@ -210,6 +211,7 @@ export type OfferOutcome =
   | 'queued'
   | 'unverified'
   | 'empty'
+  | 'own'
   | 'unmapped'
   | 'foreign';
 
@@ -229,6 +231,13 @@ export class IngestPipeline {
    * for none); omitted, `canonicalAlias` is asked.
    */
   offer(msg: InboundMessage, alias?: string | null): OfferOutcome {
+    // The oracle's own events — its room mirrors and the channel files it
+    // posts in a session thread — are never a turn. The bot SDK already
+    // drops them before `onMessage`; this holds on every path that offers a
+    // message here (inbox replays included), and keeps a DID-shaped bot
+    // account from being attributed to itself.
+    if (this.deps.botUserId !== undefined && msg.sender === this.deps.botUserId)
+      return 'own';
     if (!msg.body.trim() && !msg.attachment) return 'empty';
     const attribution = attributeUser({
       alias: alias === undefined ? this.deps.canonicalAlias(msg.roomId) : alias,

package/src/matrix/media-deadline.ts

@@ -1,12 +1,9 @@
 /**
- * Deadlines for the gateway's media downloads. A homeserver that stops
- * sending mid-body would otherwise keep the reading side — a user object
- * assembling an attachment for a turn — waiting for as long as the
- * connection stays open.
- *
- * The bound covers the whole transfer: opening the download and every byte
- * of the body. When it passes (or the caller's own signal aborts), the
- * source is cancelled and the stream handed out errors with the reason.
+ * Deadlines for the gateway's media event lookups (`eventMediaInfo`). A
+ * homeserver that never answers would otherwise keep the asking side — a
+ * user object assembling an attachment for a turn — waiting for as long as
+ * the connection stays open. When the bound passes (or the caller's own
+ * signal aborts), the lookup rejects with the reason.
  */
 
 export interface BoundedSignal {
@@ -89,42 +86,3 @@ export function raceSignal<T>(
     );
   });
 }
-
-/**
- * `source` behind the deadline: the returned stream carries the same bytes,
- * and errors with the signal's reason (the source cancelled) when the bound
- * passes before the last byte. The timer is cleared once the transfer ends
- * either way, including when the reader cancels.
- */
-export function streamWithDeadline(
-  source: ReadableStream<Uint8Array>,
-  bound: BoundedSignal,
-): ReadableStream<Uint8Array> {
-  const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
-  const writer = writable.getWriter();
-  const reader = source.getReader();
-  const stop = (reason: unknown): void => {
-    void writer.abort(reason).catch(() => undefined);
-    void reader.cancel(reason).catch(() => undefined);
-  };
-  const onAbort = (): void => stop(bound.signal.reason);
-  if (bound.signal.aborted) onAbort();
-  else bound.signal.addEventListener('abort', onAbort, { once: true });
-  void (async () => {
-    try {
-      for (;;) {
-        const { done, value } = await reader.read();
-        if (done || bound.signal.aborted) break;
-        await writer.write(value);
-      }
-      if (!bound.signal.aborted) await writer.close();
-    } catch (err) {
-      // The reader went away (cancelled) or the source failed: end both.
-      stop(err);
-    } finally {
-      bound.signal.removeEventListener('abort', onAbort);
-      bound.clear();
-    }
-  })();
-  return readable;
-}

package/src/memory/session-history-indexer.ts

@@ -27,8 +27,13 @@
  *    transcript's last chance).
  *  - Speakers get real identities (the user's preferred name / the oracle's
  *    preferred or configured name) so Graphiti's extractor does not pin
- *    facts to literal "user"/"assistant" nodes. Tool replies fold into the
- *    assistant role (the engine has no tool role).
+ *    facts to literal "user"/"assistant" nodes.
+ *  - Only the conversation is sent: what the user said and the oracle's
+ *    replies (`conversationReader`). The engine makes every message an episode
+ *    of evidence, so a tool result, a status line before a tool call, or a
+ *    reply that repeats what a memory search just returned would come back
+ *    as a fact, and push real ones out of the capped user-context block. Those
+ *    messages still count towards the watermark.
  *  - Auth is the oracle's two-hop UCAN invocation minted from the user's
  *    delegation (`ixo:memory` / `memory/*`) — no delegation, no indexing.
  *  - Endpoint: `POST <MEMORY_ENGINE_URL>/messages` with `x-room-id`, as
@@ -45,13 +50,18 @@
  * Not ported: Node also asks Matrix for the user's display name when no
  * preferred name is set; here the fallback is the literal "Me" straight away.
  */
+import { AIMessage, type BaseMessage } from '@langchain/core/messages';
+import { visibleText, visibleToUser } from '../do/transcript';
 import type { Logger } from '../plugin-api/types';
 import { MEMORY_ENTITY_HEADER } from '../plugins/memory/memory-entity';
+import { MEMORY_SEARCH_MCP_NAME } from '../plugins/memory/memory-tools';
 
 export interface HistoryMessage {
   /** LangChain message type: `human` | `ai` | `tool` | `system`. */
   type: string;
   content: string;
+  /** Counted by the watermark but not sent (`conversationReader`). */
+  notConversation?: boolean;
 }
 
 export interface MemoryEngineMessage {
@@ -230,6 +240,47 @@ interface QuietWait {
   resolve: () => void;
 }
 
+/** Text that parses as a JSON object or list: a tool's output, not a reply. */
+function isJsonDocument(text: string): boolean {
+  const start = text.trimStart()[0];
+  if (start !== '{' && start !== '[') return false;
+  try {
+    JSON.parse(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads a transcript in order, one reader per read, and turns each message
+ * into what the indexer takes. A turn's memory search is seen before its reply,
+ * so that reply is known to repeat what memory returned, which must not go
+ * back in as new evidence. A read that starts in the middle of a turn has not
+ * seen the search; a pass normally starts at a turn's end.
+ */
+export function conversationReader(): (message: BaseMessage) => HistoryMessage {
+  let readMemory = false;
+  return (message) => {
+    const content = visibleText(message);
+    const calls = AIMessage.isInstance(message)
+      ? (message.tool_calls ?? [])
+      : [];
+    if (message.type === 'human') readMemory = false;
+    if (calls.some((call) => call.name === MEMORY_SEARCH_MCP_NAME))
+      readMemory = true;
+    const conversation =
+      visibleToUser(message) &&
+      (message.type === 'human' ||
+        (calls.length === 0 && !readMemory && !isJsonDocument(content)));
+    return {
+      type: message.type,
+      content,
+      ...(conversation ? {} : { notConversation: true }),
+    };
+  };
+}
+
 /** Node's `transformMessagesToMemoryEngineFormat`, verbatim in mapping. */
 export function transformMessagesToMemoryEngineFormat(
   messages: readonly HistoryMessage[],
@@ -237,7 +288,12 @@ export function transformMessagesToMemoryEngineFormat(
   userSpeakerLabel: string,
   oracleSpeakerLabel: string,
 ): MemoryEngineMessage[] {
-  return messages.map((message) => {
+  // The engine rejects empty episodes, and has no tool role.
+  const conversation = messages.filter(
+    (m) =>
+      m.type !== 'tool' && !m.notConversation && m.content.trim().length > 0,
+  );
+  return conversation.map((message) => {
     let role_type: MemoryEngineMessage['role_type'];
     let label: string;
     switch (message.type) {
@@ -253,12 +309,6 @@ export function transformMessagesToMemoryEngineFormat(
         role_type = 'system';
         label = 'System';
         break;
-      case 'tool':
-        // The engine has no tool role — tool replies are the oracle
-        // reporting back, so they share the oracle speaker label.
-        role_type = 'assistant';
-        label = oracleSpeakerLabel;
-        break;
       default:
         role_type = 'user';
         label = userSpeakerLabel;
@@ -564,11 +614,7 @@ export class SessionHistoryIndexer {
     try {
       while (chunk.length > 0) {
         const transformed = transformMessagesToMemoryEngineFormat(
-          // Tool-call-only AI turns carry no text; the engine has nothing to
-          // extract from them and rejects empty episodes.
-          chunk
-            .map((entry) => entry.message)
-            .filter((m) => m.content.trim().length > 0),
+          chunk.map((entry) => entry.message),
           session.title ?? '',
           labels.user,
           labels.oracle,

package/src/plugin-api/oracle-plugin.ts

@@ -63,11 +63,10 @@ export abstract class OraclePlugin {
    * plugin's working rules, as plain text (markdown, starting at a `###`
    * heading). Never part of the manifest, the Tier-1 capability block or
    * `list_capabilities`, so it costs nothing on turns that do not use the
-   * plugin. `load_capability` returns it (once per turn) when it loads the
-   * plugin or the capability router preloaded it for the turn, and the
-   * system prompt carries it on every turn that starts with the plugin
-   * loaded on the thread (or `always` visible) and usable by the user's
-   * delegation.
+   * plugin. The model has it when it first uses the plugin's tools: in the
+   * load result or on the turn's message when the plugin loads on a warm
+   * turn, in the system prompt from the next cold turn on, and always there
+   * for an `always` plugin the user's delegation can use.
    */
   readonly operatingGuide?: string;