@ixo/oracle-runtime-workers 0.10.0 → 0.11.0

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

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

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

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

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

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

package/src/shell/app.ts

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

package/src/sqlite/sqlite-saver.ts

@@ -94,6 +94,19 @@ type MessageRow = {
   message: Uint8Array | string;
 };
 
+/** A transcript row's position in the listing order. */
+export interface ThreadMessageAnchor {
+  createdAt: string;
+  rowid: number;
+}
+
+/** A transcript row with what a pager needs to continue from it. */
+export interface ThreadMessageRow {
+  message: BaseMessage;
+  messageId: string;
+  anchor: ThreadMessageAnchor;
+}
+
 interface PendingWriteColumn {
   task_id: string;
   channel: string;
@@ -360,6 +373,74 @@ export class SqliteSaver extends BaseCheckpointSaver {
     return Promise.all(rows.map((row) => this.loadMessage(row.message)));
   }
 
+  /**
+   * Where a transcript row sits in the listing order (`created_at`, then
+   * `rowid`), or null when the thread has no row with that message id. A
+   * paging cursor names a message id and is resolved through this at query
+   * time: rowids move when a checkpoint rewrites the thread's rows, message
+   * ids never do.
+   */
+  async findThreadMessageAnchor(
+    threadId: string,
+    messageId: string,
+  ): Promise<ThreadMessageAnchor | null> {
+    await this.setup();
+    const row = await this.db.get<{ created_at: string; rowid: number }>(
+      'SELECT created_at, rowid FROM messages WHERE thread_id = ? AND message_id = ?',
+      [threadId, messageId],
+    );
+    return row ? { createdAt: row.created_at, rowid: row.rowid } : null;
+  }
+
+  /**
+   * A slice of the transcript next to an anchor: `older` walks back from it
+   * (newest first, so a caller can stop once it holds enough turns), `newer`
+   * walks forward (oldest first). Without an anchor `older` starts at the
+   * newest row and `newer` at the oldest. The anchor row itself is left out
+   * unless `inclusive`.
+   */
+  async listThreadMessageRows(
+    threadId: string,
+    opts: {
+      direction: 'older' | 'newer';
+      anchor?: ThreadMessageAnchor | null;
+      /** Include the anchor row itself. */
+      inclusive?: boolean;
+      limit: number;
+    },
+  ): Promise<ThreadMessageRow[]> {
+    await this.setup();
+    const older = opts.direction === 'older';
+    const cmp = older ? '<' : '>';
+    const rowCmp = opts.inclusive ? `${cmp}=` : cmp;
+    const order = older ? 'DESC' : 'ASC';
+    const anchored = opts.anchor
+      ? ` AND (created_at ${cmp} ? OR (created_at = ? AND rowid ${rowCmp} ?))`
+      : '';
+    const rows = await this.db.exec<{
+      message: Uint8Array | string;
+      message_id: string;
+      created_at: string;
+      rowid: number;
+    }>(
+      `SELECT message, message_id, created_at, rowid FROM messages WHERE thread_id = ?${anchored} ORDER BY created_at ${order}, rowid ${order} LIMIT ?`,
+      [
+        threadId,
+        ...(opts.anchor
+          ? [opts.anchor.createdAt, opts.anchor.createdAt, opts.anchor.rowid]
+          : []),
+        opts.limit,
+      ],
+    );
+    return Promise.all(
+      rows.map(async (row) => ({
+        message: await this.loadMessage(row.message),
+        messageId: row.message_id,
+        anchor: { createdAt: row.created_at, rowid: row.rowid },
+      })),
+    );
+  }
+
   /**
    * The thread's messages whose stored plain content (`message_content`)
    * contains `contentContains`, oldest first — a SQL `LIKE` pre-filter, so