@ixo/oracle-runtime-workers 0.9.0 → 0.11.0

package/src/matrix/inbox-store.ts

@@ -46,6 +46,20 @@ export function ensureInboxTable(sql: SqlStorage): void {
       attempts INTEGER NOT NULL DEFAULT 0
     ) WITHOUT ROWID`,
   );
+  // Columns added after the table first shipped (the group-chat gate reads
+  // them on replay): CREATE TABLE IF NOT EXISTS leaves an existing table alone.
+  const columns = new Set(
+    sql
+      .exec<{ name: string }>(`PRAGMA table_info(turn_inbox)`)
+      .toArray()
+      .map((row) => row.name),
+  );
+  if (!columns.has('mentions_bot'))
+    sql.exec(
+      `ALTER TABLE turn_inbox ADD COLUMN mentions_bot INTEGER NOT NULL DEFAULT 0`,
+    );
+  if (!columns.has('in_reply_to'))
+    sql.exec(`ALTER TABLE turn_inbox ADD COLUMN in_reply_to TEXT`);
 }
 
 /** Record a message before its turn starts. A repeat of the same event id is a no-op. */
@@ -56,8 +70,8 @@ export function insertInboxRow(
 ): void {
   sql.exec(
     `INSERT OR IGNORE INTO turn_inbox
-      (event_id, room_id, sender, ts, body, thread_root_id, attachment, received_at, attempts)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`,
+      (event_id, room_id, sender, ts, body, thread_root_id, attachment, received_at, attempts, mentions_bot, in_reply_to)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?)`,
     msg.eventId,
     msg.roomId,
     msg.sender,
@@ -66,6 +80,8 @@ export function insertInboxRow(
     msg.threadRootId ?? null,
     msg.attachment ? JSON.stringify(msg.attachment) : null,
     receivedAt,
+    msg.mentionsBot ? 1 : 0,
+    msg.inReplyTo ?? null,
   );
 }
 
@@ -112,13 +128,15 @@ type InboxSqlRow = {
   attachment: string | null;
   received_at: number;
   attempts: number;
+  mentions_bot: number;
+  in_reply_to: string | null;
 } & Record<string, SqlStorageValue>;
 
 /** Every pending row, oldest first (the order the messages arrived in). */
 export function listInboxRows(sql: SqlStorage): InboxRow[] {
   return sql
     .exec<InboxSqlRow>(
-      `SELECT event_id, room_id, sender, ts, body, thread_root_id, attachment, received_at, attempts
+      `SELECT event_id, room_id, sender, ts, body, thread_root_id, attachment, received_at, attempts, mentions_bot, in_reply_to
        FROM turn_inbox ORDER BY ts ASC, event_id ASC`,
     )
     .toArray()
@@ -132,6 +150,8 @@ export function listInboxRows(sql: SqlStorage): InboxRow[] {
       ...(row.attachment
         ? { attachment: parseAttachment(row.attachment) }
         : {}),
+      ...(Number(row.mentions_bot) ? { mentionsBot: true } : {}),
+      ...(row.in_reply_to ? { inReplyTo: row.in_reply_to } : {}),
       receivedAt: Number(row.received_at),
       attempts: Number(row.attempts),
     }));

package/src/matrix/ingest.ts

@@ -7,6 +7,12 @@
  * so the sender must resolve to a user DID before anything else happens.
  * Own-message, stale and duplicate gating happens upstream, in the bot SDK's
  * pipeline; `gateway-do.ts` adapts its `BotMessage`s into `InboundMessage`s.
+ *
+ * Threads are sessions, exactly as on Node: the thread root of a message is
+ * its session id (`reply-chain.ts` resolves it; a bare message is its own
+ * root), the reply is posted into that thread, and a Portal session — whose
+ * id is its marker event — is continued by replying inside its thread. The
+ * main timeline of a room never carries a reply and is never a session.
  */
 
 import { didToAliasPart } from '../do/contracts';
@@ -28,23 +34,40 @@ export interface InboundMessage {
   ts: number;
   /** Text body; empty for a media-only message. */
   body: string;
-  /** Thread root when the message was sent inside a thread. */
+  /**
+   * The message's thread root: the `m.thread` root, the root of a quote-reply
+   * chain (`gateway-do.ts` resolves it before the offer), or — for a bare
+   * message — nothing: the message roots its own thread (`threadRootIdOf`).
+   */
   threadRootId?: string;
   /** Present for media messages — fetched and decrypted at turn time. */
   attachment?: InboundAttachment;
+  /** The bot is in the message's `m.mentions` (the group-chat gate answers a mention). */
+  mentionsBot?: boolean;
+  /** The event a quote-reply answers (`m.in_reply_to`); a reply to the bot's own message is answered too. */
+  inReplyTo?: string;
 }
 
 export interface IngestTurn {
   userDid: string;
   matrixUserId: string;
   roomId: string;
-  /** Present when the user wrote inside a thread; replies go there too. */
-  threadId?: string;
-  /** `matrix:<roomId>` (main timeline) or `thread:<threadRootId>`. */
+  /** The thread the reply goes to: the message's root, or the message itself. */
+  threadId: string;
+  /** The thread root event id — the session is the thread (Node parity). */
   sessionId: string;
   /** Debounced messages joined with newlines, oldest first. */
   message: string;
   eventIds: string[];
+  /**
+   * The message the turn's metadata comes from — the latest text message of
+   * the burst, else its first (Node's `sourceEvent`): its mentions and reply
+   * target drive the group-chat gate, its timestamp dates the turn.
+   */
+  sourceEventId: string;
+  ts: number;
+  mentionsBot: boolean;
+  inReplyTo?: string;
   /** Media shared in the same debounce window, oldest first. */
   attachments?: InboundAttachment[];
 }
@@ -52,6 +75,12 @@ export interface IngestTurn {
 export interface IngestDeps {
   /** The DID that forms the oracle half of the user↔oracle room alias. */
   oracleDid: string;
+  /**
+   * 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.
+   */
+  botUserId?: string;
   debounceMs?: number;
   /** `m.room.canonical_alias` of the room, when known. */
   canonicalAlias(roomId: string): string | null;
@@ -66,6 +95,8 @@ interface Pending {
 }
 
 export const DEFAULT_DEBOUNCE_MS = 500;
+/** What the bot's own user id becomes in a message body (the Node bridge's wording). */
+export const MENTIONED_BOT_MARKER = '(USER MENTIONED YOU @AI_AGENT)';
 
 /** `did-ixo-ixo1abc` → `did:ixo:ixo1abc`. Only the first two dashes are separators. */
 export function aliasPartToDid(part: string): string | null {
@@ -119,8 +150,11 @@ export function resolveUserDid(opts: {
   return fromAlias ?? fromSender;
 }
 
-export function sessionIdFor(roomId: string, threadRootId?: string): string {
-  return threadRootId ? `thread:${threadRootId}` : `matrix:${roomId}`;
+/** The thread a message belongs to: its resolved root, else the message itself. */
+export function threadRootIdOf(
+  msg: Pick<InboundMessage, 'eventId' | 'threadRootId'>,
+): string {
+  return msg.threadRootId ?? msg.eventId;
 }
 
 export class IngestPipeline {
@@ -144,7 +178,7 @@ export class IngestPipeline {
     });
     if (!userDid) return 'unmapped';
 
-    const key = `${msg.roomId}|${sessionIdFor(msg.roomId, msg.threadRootId)}`;
+    const key = `${msg.roomId}|${threadRootIdOf(msg)}`;
     const existing = this.pending.get(key);
     if (existing) {
       clearTimeout(existing.timer);
@@ -177,27 +211,36 @@ export class IngestPipeline {
     this.pending.delete(key);
     const first = entry.messages[0];
     if (!first) return;
-    const threadId = first.threadRootId;
+    const threadId = threadRootIdOf(first);
     const texts = entry.messages.map((m) => m.body).filter((b) => b.trim());
+    const source =
+      [...entry.messages].reverse().find((m) => m.body.trim()) ?? first;
     const attachments = entry.messages.flatMap((m) =>
       m.attachment ? [m.attachment] : [],
     );
     // A file-only send still needs a user message the agent can act on —
     // the Node bridge's wording.
-    const message =
+    const raw =
       texts.length > 0
         ? texts.join('\n')
         : attachments.length === 1
           ? `User shared a file: ${attachments[0]?.filename ?? 'file'}`
           : `User shared ${attachments.length} file(s): ${attachments.map((a) => a.filename).join(', ')}`;
+    const message = this.deps.botUserId
+      ? raw.replace(this.deps.botUserId, MENTIONED_BOT_MARKER)
+      : raw;
     const turn: IngestTurn = {
       userDid: entry.userDid,
       matrixUserId: first.sender,
       roomId: first.roomId,
-      sessionId: sessionIdFor(first.roomId, threadId),
+      threadId,
+      sessionId: threadId,
       message,
       eventIds: entry.messages.map((m) => m.eventId),
-      ...(threadId ? { threadId } : {}),
+      sourceEventId: source.eventId,
+      ts: source.ts,
+      mentionsBot: source.mentionsBot === true,
+      ...(source.inReplyTo ? { inReplyTo: source.inReplyTo } : {}),
       ...(attachments.length > 0 ? { attachments } : {}),
     };
     try {

package/src/matrix/reply-chain.ts

@@ -1,15 +1,18 @@
 /**
- * Quote-reply → thread resolution — the port of the Node listener bridge's
- * `getThreadRoot`. A client that quote-replies (`m.in_reply_to`) to a
- * message that lives in a thread, without adding the `m.thread` relation
- * itself, still means "continue that thread": walk the reply chain upward
- * until an event that carries `m.thread` (→ its root) or a bare event.
+ * Thread root of an inbound message — the port of the Node listener bridge's
+ * `getThreadRoot`, and with it Node's rule for room conversations: EVERY
+ * message has a thread root, and that root is the session.
  *
- * Unlike Node — where every bare room message opens its own thread-session —
- * this runtime keeps the main timeline as ONE session (`matrix:<roomId>`), so
- * a chain that ends on a bare event resolves to "no thread" (main timeline)
- * rather than to that event. Results are memoised per event id with a
- * bounded cache; cycles and missing events terminate the walk.
+ *  - a message inside a thread (`m.thread`) → the thread's root;
+ *  - a bare message (no relation) → the message itself: the reply opens a
+ *    thread on it, and later replies in that thread continue the session;
+ *  - a quote-reply (`m.in_reply_to` without `m.thread`, from a client that
+ *    does not thread natively) → walk the reply chain upward until an event
+ *    that carries `m.thread` (→ its root) or a bare event (→ that event).
+ *
+ * The walk ends where Node's does: on a cycle, on an event that cannot be
+ * fetched, or past the hop bound, the last event reached is the root.
+ * Results are memoised per event id with a bounded cache.
  */
 
 export interface MatrixRelatesTo {
@@ -35,7 +38,7 @@ export function inReplyToOf(rel: MatrixRelatesTo | undefined): string | null {
   return typeof id === 'string' && id.length > 0 ? id : null;
 }
 
-/** Bounded event-id → thread-root ('' = main timeline) memo. */
+/** Bounded event-id → thread-root memo. */
 export class ThreadRootCache {
   private readonly map = new Map<string, string>();
 
@@ -56,7 +59,7 @@ export class ThreadRootCache {
 
 export interface ResolveReplyChainInput {
   eventId: string;
-  /** The event's own relation (from the clear or wire content). */
+  /** The event's own relation (from the clear or wire content); undefined for a bare message. */
   relatesTo: MatrixRelatesTo | undefined;
   /** Fetches a room event's `m.relates_to` (null when the event is unavailable). */
   fetchRelatesTo: (eventId: string) => Promise<MatrixRelatesTo | null>;
@@ -66,44 +69,50 @@ export interface ResolveReplyChainInput {
 }
 
 /**
- * Thread root for the event, or `null` for the main timeline. Never throws:
- * a fetch failure ends the walk at the last known event (→ main timeline).
+ * The thread root of the event (see the module comment). Never throws: a
+ * fetch failure ends the walk at the event that could not be fetched.
  */
 export async function resolveReplyChainRoot(
   input: ResolveReplyChainInput,
-): Promise<string | null> {
+): Promise<string> {
   const { eventId, relatesTo, fetchRelatesTo, cache } = input;
   const maxHops = input.maxHops ?? 25;
-  const remember = (ids: string[], root: string | null): string | null => {
-    for (const id of ids) cache.set(id, root ?? '');
+  const remember = (ids: string[], root: string): string => {
+    for (const id of ids) cache.set(id, root);
     return root;
   };
 
   const own = threadRootOf(relatesTo);
   if (own) return remember([eventId], own);
   const firstParent = inReplyToOf(relatesTo);
-  if (!firstParent) return remember([eventId], null);
+  // A bare message roots its own thread.
+  if (!firstParent) return remember([eventId], eventId);
 
   const path = [eventId];
   const visited = new Set<string>([eventId]);
-  let cursor: string | null = firstParent;
+  let cursor: string = firstParent;
   let hops = 0;
-  while (cursor && !visited.has(cursor) && hops < maxHops) {
-    hops += 1;
+  for (;;) {
     visited.add(cursor);
     path.push(cursor);
     const known = cache.get(cursor);
-    if (known !== undefined) return remember(path, known === '' ? null : known);
+    if (known !== undefined) return remember(path, known);
     let parentRel: MatrixRelatesTo | null;
     try {
       parentRel = await fetchRelatesTo(cursor);
     } catch {
       parentRel = null;
     }
-    if (parentRel === null) return remember(path, null);
+    // Unavailable: the quoted event is the best root there is (Node's
+    // fallback is the last cursor as well).
+    if (parentRel === null) return remember(path, cursor);
     const parentRoot = threadRootOf(parentRel);
     if (parentRoot) return remember(path, parentRoot);
-    cursor = inReplyToOf(parentRel);
+    const next = inReplyToOf(parentRel);
+    // A bare ancestor is the root of the chain.
+    if (!next) return remember(path, cursor);
+    hops += 1;
+    if (visited.has(next) || hops >= maxHops) return remember(path, cursor);
+    cursor = next;
   }
-  return remember(path, null);
 }

package/src/owner-store/ixo-vfs-store.ts

@@ -50,6 +50,7 @@ import {
   type OwnerCopy,
   type OwnerStore,
   type SaveResult,
+  type SaveHints,
 } from './types';
 
 const VFS_RESOURCE = 'ixo:filesystem';
@@ -233,9 +234,11 @@ export class IxoVfsOwnerStore implements OwnerStore {
    * Atomic replace, always delete + re-create, never a new version:
    *
    *   1. drop stale `.uploading-*` temp files a crashed flush left behind;
-   *   2. measure the gzipped length in a counting pass (the VFS needs
-   *      `Upload-Length` at session creation — `Upload-Defer-Length` is not
-   *      supported — and gzip output is deterministic for identical input);
+   *   2. take the gzipped length from `hints` (the object measured it in the
+   *      same pass as its checksum) or, without a hint, count it in a pass
+   *      of its own (the VFS needs `Upload-Length` at session creation —
+   *      `Upload-Defer-Length` is not supported — and gzip output is
+   *      deterministic for identical input);
    *   3. upload gzip → a TEMP path next to the real one: one `POST /files`
    *      when it fits in a single part, else a tus session in 5 MiB parts
    *      (`tusUpload`, resumable per part);
@@ -247,7 +250,10 @@ export class IxoVfsOwnerStore implements OwnerStore {
    * file is cleaned up then). Peak memory is one part (5 MiB) plus fixed
    * overhead, whatever the file size.
    */
-  async save(snapshot: FileSnapshot): Promise<SaveResult> {
+  async save(
+    snapshot: FileSnapshot,
+    hints: SaveHints = {},
+  ): Promise<SaveResult> {
     const listing = await this.listOracleFiles();
     const existing = listing.filter((f) => f.path === this.path);
     const stale = listing.filter((f) =>
@@ -261,7 +267,8 @@ export class IxoVfsOwnerStore implements OwnerStore {
       });
     }
 
-    const gzLength = await countStream(gzipStream(snapshot.open()));
+    const gzLength =
+      hints.gzippedLength ?? (await countStream(gzipStream(snapshot.open())));
     const tempPath = `${this.path}${TEMP_PATH_INFIX}${Date.now().toString(36)}`;
     const uploaded =
       gzLength <= SINGLE_SHOT_MAX_BYTES

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

@@ -22,6 +22,7 @@ import {
   type OwnerCopy,
   type OwnerStore,
   type SaveResult,
+  type SaveHints,
 } from './types';
 
 /**
@@ -89,19 +90,23 @@ export class MatrixMediaOwnerStore implements OwnerStore {
   }
 
   /**
-   * 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.
+   * Streamed as well: the snapshot is opened for a header peek, for a gzip
+   * pass that only counts unless the caller measured the length already
+   * (`hints`; the homeserver needs the exact ciphertext length up front and
+   * gzip output is deterministic for identical input) and for the gzip pass
+   * that is uploaded — and never held whole.
    */
-  async save(snapshot: FileSnapshot): Promise<SaveResult> {
+  async save(
+    snapshot: FileSnapshot,
+    hints: SaveHints = {},
+  ): Promise<SaveResult> {
     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 gzLength =
+      hints.gzippedLength ?? (await countStream(gzipStream(snapshot.open())));
     const { eventId } = await this.gateway.uploadUserSnapshotStream(
       this.userDid,
       this.storageKey,

package/src/owner-store/measure.ts

@@ -0,0 +1,39 @@
+/**
+ * One streamed pass over a snapshot that yields BOTH what a flush needs
+ * before it uploads: the SHA-256 of the raw SQLite bytes (the "did anything
+ * change" gate against the last upload) and the exact gzipped length (the
+ * VFS needs `Upload-Length` when the tus session is created). Before this
+ * helper the object hashed in one pass and the store counted the gzip in a
+ * second one; with the R2 page tier every pass over a cold file is one R2
+ * GET per segment, so the two are folded together and the upload itself is
+ * the only other read.
+ *
+ * The length is exact for the store's own gzip: `gzipStream` is the same
+ * `CompressionStream('gzip')` the stores pipe the upload through, and its
+ * output is deterministic for identical input.
+ */
+import { createHash } from 'node:crypto';
+import { countStream, gzipStream } from './types';
+
+export interface SnapshotMeasure {
+  /** Hex SHA-256 of the raw (uncompressed) bytes. */
+  sha256Hex: string;
+  /** Byte length of `gzipStream(<the same bytes>)`. */
+  gzippedLength: number;
+}
+
+export async function measureForSave(
+  stream: ReadableStream<Uint8Array>,
+): Promise<SnapshotMeasure> {
+  const hash = createHash('sha256');
+  const tapped = stream.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        hash.update(chunk);
+        controller.enqueue(chunk);
+      },
+    }),
+  );
+  const gzippedLength = await countStream(gzipStream(tapped));
+  return { sha256Hex: hash.digest('hex'), gzippedLength };
+}

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

@@ -20,7 +20,13 @@
  *            Matrix copy so no second copy of the user's history lingers.
  */
 import { VfsNoDelegationError } from './ixo-vfs-store';
-import type { FileSnapshot, OwnerCopy, OwnerStore, SaveResult } from './types';
+import type {
+  FileSnapshot,
+  OwnerCopy,
+  OwnerStore,
+  SaveHints,
+  SaveResult,
+} from './types';
 
 export interface MigratingOwnerStoreOptions {
   /** System of record (IXO VFS). */
@@ -104,8 +110,8 @@ export class MigratingOwnerStore implements OwnerStore {
    * "not on VFS yet" (no delegation) — so the object keeps the copy dirty
    * and retries; Matrix media is never written.
    */
-  async save(snapshot: FileSnapshot): Promise<SaveResult> {
-    return this.primary.save(snapshot);
+  async save(snapshot: FileSnapshot, hints?: SaveHints): Promise<SaveResult> {
+    return this.primary.save(snapshot, hints);
   }
 
   /**

package/src/owner-store/types.ts

@@ -15,9 +15,13 @@
  * Both directions STREAM: `load()` hands back the raw (already gunzipped)
  * SQLite bytes as a `ReadableStream` the object writes into its VFS chunk by
  * chunk, and `save()` takes a `FileSnapshot` — a re-openable, consistent
- * view of the working copy — that the store reads as many times as it needs
- * (the VFS store measures the gzipped length in one pass and uploads in a
- * second). Nothing on this path ever holds the whole file in memory — the
+ * view of the working copy — that the store reads as many times as it needs.
+ * The object measures the hash and the gzipped length in ONE pass
+ * (`measureForSave`) and hands the length in as a `SaveHints`, so a store
+ * only reads the snapshot once more, for the upload itself; a store called
+ * without the hint counts the gzip in a pass of its own. That matters with
+ * the R2 page tier, where every pass over a cold file is one R2 GET per
+ * segment. Nothing on this path ever holds the whole file in memory — the
  * legacy Matrix media path included: the gateway hands the media over as a
  * stream and decryption, gunzip and the SQLite header check run chunk by
  * chunk in the object. Compression is the store's concern. `etag` lets the object skip a reload
@@ -26,7 +30,7 @@
 export interface OwnerStore {
   readonly kind: 'matrix' | 'vfs';
   load(): Promise<OwnerCopy | null>;
-  save(snapshot: FileSnapshot): Promise<SaveResult>;
+  save(snapshot: FileSnapshot, hints?: SaveHints): Promise<SaveResult>;
   /** Cheap upstream freshness probe — null when unsupported/unknown. */
   head(): Promise<{ etag: string } | null>;
   /** Remove the durable copy (user asked to be forgotten). */
@@ -60,6 +64,12 @@ export interface OwnerCopy {
   fromLegacy?: true;
 }
 
+/** What the caller already measured about the snapshot (see `measureForSave`). */
+export interface SaveHints {
+  /** Byte length of `gzipStream(snapshot.open())`; spares the store its counting pass. */
+  gzippedLength?: number;
+}
+
 export interface SaveResult {
   etag: string;
   /** Bytes actually sent upstream (compressed size on the VFS path). */

package/src/plugin-api/tool-helper.ts

@@ -17,6 +17,11 @@ export interface ToolHelperOptions {
    * `manifest.visibility` setting.
    */
   visibility?: PluginTool['visibility'];
+  /**
+   * `'read'` for a tool with no external effect (safe to run again when a
+   * turn resumes after a reset); omitted or `'write'` otherwise.
+   */
+  effect?: PluginTool['effect'];
   /**
    * Billing gate marker, kept for source compatibility with the Node
    * runtime's plugin contract. The Workers runtime has no commerce lane, so
@@ -49,7 +54,7 @@ export function tool(
   if (!options || typeof options !== 'object') {
     throw new TypeError('tool(handler, options): `options` is required.');
   }
-  const { name, description, schema, visibility, billing } = options;
+  const { name, description, schema, visibility, billing, effect } = options;
   if (!name || typeof name !== 'string') {
     throw new TypeError(
       'tool(handler, options): `options.name` must be a non-empty string.',
@@ -78,5 +83,8 @@ export function tool(
   if (billing !== undefined) {
     pluginTool.billing = billing;
   }
+  if (effect !== undefined) {
+    pluginTool.effect = effect;
+  }
   return pluginTool;
 }

package/src/plugin-api/types.ts

@@ -78,6 +78,56 @@ export interface MatrixEvent {
   readonly originServerTs?: number;
 }
 
+export interface MatrixRoomInfo {
+  isDirect: boolean;
+  memberCount: number;
+  joinedMemberIds: string[];
+  /**
+   * Whether the deployment runs the group-chat lane in group rooms
+   * (`MATRIX_GROUP_ROOMS=gate` on the gateway). False by default: the bot
+   * then never speaks in a group room and the channel-memory tools are not
+   * offered.
+   */
+  groupLane: boolean;
+}
+
+/** One compacted batch of a group room's messages (the Node `ChannelMemoryChunk`). */
+export interface ChannelMemoryChunk {
+  id: string;
+  roomId: string;
+  summary: string;
+  fromEventId: string;
+  toEventId: string;
+  fromTimestamp: number;
+  toTimestamp: number;
+  messageCount: number;
+  participants: string[];
+  threadIds: string[];
+  tier: number;
+  createdAt: number;
+}
+
+export interface PinnedRoomFact {
+  id: string;
+  roomId: string;
+  fact: string;
+  pinnedByDid: string;
+  sourceEventId?: string;
+  createdAt: number;
+}
+
+export interface ChannelRoomMember {
+  matrixUserId: string;
+  displayName: string;
+  did?: string;
+}
+
+export interface ChannelMemoryRecall {
+  chunks: ChannelMemoryChunk[];
+  pinnedFacts: PinnedRoomFact[];
+  members: ChannelRoomMember[];
+}
+
 /** Memory-enriched user context (mirrors `state.userContext`). */
 export type UserContextData = Record<string, unknown>;
 
@@ -521,6 +571,34 @@ export interface RuntimeContext<TConfig = MergedConfig> {
     ) => Promise<string>;
     getRoomState: (roomId: string) => Promise<RoomStateSnapshot>;
     getEventById: (roomId: string, eventId: string) => Promise<MatrixEvent>;
+    /**
+     * Whether a room is a direct room or a group room — the Node
+     * `MatrixManager.getRoomInfo` (`is_direct` on the create event, else
+     * ≤ 2 joined members), cached by the gateway. Absent on hosts without a
+     * Matrix gateway.
+     */
+    roomInfo?: (roomId: string) => Promise<MatrixRoomInfo>;
+    /**
+     * A group room's channel memory (the `matrix-group-chats` plugin's
+     * tools read and write it): compacted summary chunks, pinned facts and
+     * the member roster, kept by the gateway per room. Absent on hosts
+     * without a Matrix gateway.
+     */
+    channelMemory?: {
+      recall: (roomId: string, limit?: number) => Promise<ChannelMemoryRecall>;
+      search: (
+        roomId: string,
+        query: string,
+        limit?: number,
+      ) => Promise<ChannelMemoryChunk[]>;
+      pin: (args: {
+        roomId: string;
+        fact: string;
+        pinnedByDid: string;
+        sourceEventId?: string;
+      }) => Promise<PinnedRoomFact>;
+      unpin: (roomId: string, factId: string) => Promise<boolean>;
+    };
     /**
      * Credentials of the oracle's own crypto-less device for plugins that run
      * their own Matrix client (editor, flows). Minted and kept by the gateway.
@@ -790,6 +868,14 @@ export interface PluginTool {
   handler: (args: unknown, ctx: RuntimeContext) => Promise<unknown>;
   /** Override visibility — by default inherits from the plugin's `manifest.visibility`. */
   visibility?: 'always' | 'on-demand' | 'silent';
+  /**
+   * Whether calling the tool changes anything outside the conversation.
+   * `'read'` tools may be executed again when a turn is resumed after a
+   * runtime reset; a `'write'` (the default for undeclared tools) call that
+   * was cut off mid-execution is never repeated — the model is told its
+   * outcome is unknown. See `core/middlewares/tool-marks.ts`.
+   */
+  effect?: 'read' | 'write';
   /**
    * Billing gate. `'contracted'` marks a tool that performs paid contracted
    * work: the runtime binds it only while the turn runs inside an active work

package/src/plugins/index.ts

@@ -21,6 +21,7 @@ import { UserPreferencesPlugin } from './user-preferences';
 import { PortalPlugin } from './portal';
 import { AGUIPlugin } from './agui';
 import { AttachmentsPlugin } from './attachments';
+import { MatrixGroupChatsPlugin } from './matrix-group-chats';
 
 export * from './composio';
 export * from './editor';
@@ -46,6 +47,7 @@ export const userPreferencesPlugin = new UserPreferencesPlugin();
 export const portalPlugin = new PortalPlugin();
 export const aguiPlugin = new AGUIPlugin();
 export const attachmentsPlugin = new AttachmentsPlugin();
+export const matrixGroupChatsPlugin = new MatrixGroupChatsPlugin();
 /** TasksPlugin is already an object (defineOraclePlugin), not a class. */
 export const tasksPlugin = TasksPlugin;
 
@@ -67,4 +69,5 @@ export const BUNDLED_WORKERS_PLUGINS = [
   portalPlugin,
   aguiPlugin,
   attachmentsPlugin,
+  matrixGroupChatsPlugin,
 ] as const satisfies readonly OraclePlugin[];