@ixo/oracle-runtime-workers 0.22.0 → 0.24.0

package/src/hub-actions/store.ts

@@ -0,0 +1,485 @@
+import {
+  canonicalJson,
+  parseOutcome,
+  parseReference,
+  type ActionOutcomeV1,
+  type ActionOperationV1,
+  type ActionReferenceV1,
+} from '@ixo/action-protocol';
+import type { DoSqliteDatabase } from '../sqlite/database';
+
+/**
+ * Outcomes after which the Hub never reports another for the action
+ * (`expired` and `cancelled`: never executed, protocol 0.4.0).
+ */
+export const TERMINAL_HUB_STATUSES: ReadonlySet<ActionOutcomeV1['status']> =
+  new Set(['succeeded', 'failed', 'declined', 'expired', 'cancelled']);
+/** Status refreshes of a non-terminal action back off 15 s -> 10 min. */
+export const HUB_CHECK_BASE_MS = 15_000;
+export const HUB_CHECK_MAX_MS = 10 * 60_000;
+/** A non-terminal action is no longer refreshed this long after its review expired. */
+export const HUB_CHECK_AFTER_EXPIRY_MS = 24 * 60 * 60_000;
+/** Prepares (Hub POSTs) per agent run, per user per hour and per user per day. */
+export const HUB_ACTIONS_PER_RUN = 2;
+export const HUB_ACTIONS_PER_HOUR = 5;
+export const HUB_ACTIONS_PER_DAY = 10;
+/** Rows are dropped this long after their review expired. */
+const HUB_RETENTION_SECONDS = 30 * 24 * 60 * 60;
+
+/**
+ * A refusal the model can act on: a cap reached, a request that expired, or
+ * an operation the owner's own state rules out (an unknown connection, an
+ * email whose earlier send is unconfirmed: `priorActionId`).
+ */
+export class HubActionRefused extends Error {
+  constructor(
+    readonly kind: 'limit' | 'expired' | 'refused',
+    message: string,
+    readonly priorActionId?: string,
+  ) {
+    super(message);
+    this.name = 'HubActionRefused';
+  }
+}
+
+export interface HubActionOrigin {
+  ownerDid: string;
+  sessionId: string;
+  runId: string;
+  requestId: string;
+  bindingId: string;
+  bindingRevision: number;
+  requestKey: string;
+}
+
+interface ActionRow extends Record<
+  string,
+  string | number | bigint | null | Uint8Array
+> {
+  reference: string;
+  owner_did: string;
+  session_id: string;
+  run_id: string;
+  request_id: string;
+  binding_id: string;
+  binding_revision: number;
+  request_key: string;
+}
+
+export class HubActionStore {
+  constructor(
+    private readonly db: DoSqliteDatabase,
+    private readonly now = Date.now,
+  ) {}
+
+  async setup(): Promise<void> {
+    await this.db.run(`CREATE TABLE IF NOT EXISTS hub_actions (
+      action_id TEXT PRIMARY KEY, owner_did TEXT NOT NULL, session_id TEXT NOT NULL,
+      run_id TEXT NOT NULL, request_id TEXT NOT NULL, binding_id TEXT NOT NULL,
+      binding_revision INTEGER NOT NULL, request_key TEXT NOT NULL UNIQUE,
+      reference TEXT NOT NULL
+    )`);
+    await this.db.run(`CREATE INDEX IF NOT EXISTS hub_actions_turn
+      ON hub_actions(owner_did, session_id, run_id)`);
+    await this.db.run(`CREATE TABLE IF NOT EXISTS hub_action_requests (
+      request_key TEXT PRIMARY KEY, owner_did TEXT NOT NULL, session_id TEXT NOT NULL,
+      run_id TEXT NOT NULL, request_id TEXT NOT NULL, binding_id TEXT NOT NULL,
+      binding_revision INTEGER NOT NULL, operation TEXT NOT NULL, expires_at INTEGER NOT NULL
+    )`);
+    await this.db.run(`CREATE TABLE IF NOT EXISTS hub_action_outcomes (
+      event_id TEXT PRIMARY KEY, action_id TEXT NOT NULL, sequence INTEGER NOT NULL,
+      outcome TEXT NOT NULL, FOREIGN KEY(action_id) REFERENCES hub_actions(action_id)
+    )`);
+    // The unique index below covers the same columns.
+    await this.db.run(`DROP INDEX IF EXISTS hub_action_outcomes_action`);
+    await this.db
+      .run(`CREATE UNIQUE INDEX IF NOT EXISTS hub_action_outcomes_sequence
+      ON hub_action_outcomes(action_id, sequence)`);
+    // Columns added after the first shape (flag-gated, so only test and
+    // devnet objects hold it): adding a column is instant in SQLite.
+    const actionColumns = await this.db.exec<{ name: string }>(
+      `PRAGMA table_info(hub_actions)`,
+    );
+    if (!actionColumns.some((c) => c.name === 'next_check_at'))
+      await this.db.run(
+        `ALTER TABLE hub_actions ADD COLUMN next_check_at INTEGER NOT NULL DEFAULT 0`,
+      );
+    if (!actionColumns.some((c) => c.name === 'check_attempts'))
+      await this.db.run(
+        `ALTER TABLE hub_actions ADD COLUMN check_attempts INTEGER NOT NULL DEFAULT 0`,
+      );
+    if (!actionColumns.some((c) => c.name === 'expires_at'))
+      await this.db.run(
+        `ALTER TABLE hub_actions ADD COLUMN expires_at INTEGER NOT NULL DEFAULT 0`,
+      );
+    const requestColumns = await this.db.exec<{ name: string }>(
+      `PRAGMA table_info(hub_action_requests)`,
+    );
+    if (!requestColumns.some((c) => c.name === 'created_at'))
+      await this.db.run(
+        `ALTER TABLE hub_action_requests ADD COLUMN created_at INTEGER NOT NULL DEFAULT 0`,
+      );
+    await this.db.run(`CREATE INDEX IF NOT EXISTS hub_action_requests_expires
+      ON hub_action_requests(expires_at)`);
+    await this.db.run(`CREATE INDEX IF NOT EXISTS hub_action_requests_owner
+      ON hub_action_requests(owner_did, created_at)`);
+    await this.db.run(
+      `UPDATE hub_actions SET expires_at = json_extract(reference, '$.expiresAt') WHERE expires_at = 0`,
+    );
+    await this.db.run(`CREATE INDEX IF NOT EXISTS hub_actions_expires
+      ON hub_actions(expires_at)`);
+  }
+
+  /**
+   * Drop requests, actions and outcomes whose review expired more than
+   * 30 days ago (bounded per call). Returns how many rows went.
+   */
+  async prune(): Promise<number> {
+    const before = Math.floor(this.now() / 1000) - HUB_RETENTION_SECONDS;
+    return this.db.transaction(async () => {
+      const requests = await this.db.run(
+        `DELETE FROM hub_action_requests WHERE request_key IN (SELECT request_key FROM hub_action_requests WHERE expires_at < ? LIMIT 64)`,
+        [before],
+      );
+      const actions = await this.db.exec<{ action_id: string }>(
+        `SELECT action_id FROM hub_actions WHERE expires_at < ? LIMIT 64`,
+        [before],
+      );
+      for (const { action_id } of actions) {
+        await this.db.run(
+          `DELETE FROM hub_action_outcomes WHERE action_id = ?`,
+          [action_id],
+        );
+        await this.db.run(`DELETE FROM hub_actions WHERE action_id = ?`, [
+          action_id,
+        ]);
+      }
+      return requests.changes + actions.length;
+    });
+  }
+
+  /**
+   * The newest Gmail send to the same mailbox (the same `connectionId`, or
+   * the same account label: a reconnect gets a new id) that is still in
+   * flight: approved and not finished, its latest outcome `authorized`,
+   * `submitted` or `unknown` (the connector could not tell whether it
+   * went). Its action id, or null. One Gmail send in flight per mailbox:
+   * while one exists no other email is prepared.
+   */
+  async gmailSendInFlight(
+    ownerDid: string,
+    connectionId: string,
+    accountLabel: string,
+  ): Promise<string | null> {
+    const row = await this.db.get<{ action_id: string }>(
+      `SELECT a.action_id FROM hub_action_requests r JOIN hub_actions a ON a.request_key = r.request_key
+       WHERE r.owner_did = ? AND json_extract(r.operation, '$.kind') = 'gmail.message.send.v1'
+         AND (json_extract(r.operation, '$.connectionId') = ?
+              OR lower(json_extract(r.operation, '$.accountLabel')) = lower(?))
+         AND (SELECT json_extract(o.outcome, '$.status') FROM hub_action_outcomes o
+              WHERE o.action_id = a.action_id ORDER BY o.sequence DESC LIMIT 1)
+             IN ('authorized', 'submitted', 'unknown')
+       ORDER BY r.created_at DESC LIMIT 1`,
+      [ownerDid, connectionId, accountLabel],
+    );
+    return row?.action_id ?? null;
+  }
+
+  /** The reference already recorded for a request key, if any. */
+  async byRequestKey(requestKey: string): Promise<ActionReferenceV1 | null> {
+    const row = await this.db.get<{ reference: string }>(
+      'SELECT reference FROM hub_actions WHERE request_key = ?',
+      [requestKey],
+    );
+    return row ? parseReference(JSON.parse(row.reference)) : null;
+  }
+
+  /**
+   * A new request (not a retry of a reserved key) within the caps:
+   * `HUB_ACTIONS_PER_RUN` per run, `HUB_ACTIONS_PER_HOUR` and
+   * `HUB_ACTIONS_PER_DAY` per owner.
+   */
+  private async assertCapacity(origin: HubActionOrigin): Promise<void> {
+    const run = await this.db.get<{ n: number }>(
+      'SELECT COUNT(*) AS n FROM hub_action_requests WHERE owner_did = ? AND session_id = ? AND run_id = ?',
+      [origin.ownerDid, origin.sessionId, origin.runId],
+    );
+    if ((run?.n ?? 0) >= HUB_ACTIONS_PER_RUN)
+      throw new HubActionRefused(
+        'limit',
+        'This request already prepared the most reviews one turn may prepare.',
+      );
+    const now = this.now();
+    const counts = await this.db.get<{ hour: number; day: number }>(
+      'SELECT SUM(created_at > ?) AS hour, COUNT(*) AS day FROM hub_action_requests WHERE owner_did = ? AND created_at > ?',
+      [now - 60 * 60_000, origin.ownerDid, now - 24 * 60 * 60_000],
+    );
+    if ((counts?.hour ?? 0) >= HUB_ACTIONS_PER_HOUR)
+      throw new HubActionRefused(
+        'limit',
+        'Too many reviews were prepared in the last hour; try again later.',
+      );
+    if ((counts?.day ?? 0) >= HUB_ACTIONS_PER_DAY)
+      throw new HubActionRefused(
+        'limit',
+        'Too many reviews were prepared today; try again tomorrow.',
+      );
+  }
+
+  async reserve(
+    origin: HubActionOrigin,
+    operation: ActionOperationV1,
+    proposedExpiry: number,
+  ): Promise<number> {
+    return this.db.transaction(async () => {
+      const previous = await this.db.get<
+        ActionRow & { operation: string; expires_at: number }
+      >('SELECT * FROM hub_action_requests WHERE request_key = ?', [
+        origin.requestKey,
+      ]);
+      const encoded = canonicalJson(operation);
+      if (previous) {
+        if (
+          previous.owner_did !== origin.ownerDid ||
+          previous.session_id !== origin.sessionId ||
+          previous.run_id !== origin.runId ||
+          previous.request_id !== origin.requestId ||
+          previous.binding_id !== origin.bindingId ||
+          previous.binding_revision !== origin.bindingRevision ||
+          previous.operation !== encoded
+        )
+          throw new Error(
+            'Hub action request key belongs to another operation',
+          );
+        return previous.expires_at;
+      }
+      await this.assertCapacity(origin);
+      await this.db.run(
+        `INSERT INTO hub_action_requests(request_key,owner_did,session_id,run_id,request_id,binding_id,binding_revision,operation,expires_at,created_at)
+         VALUES(?,?,?,?,?,?,?,?,?,?)`,
+        [
+          origin.requestKey,
+          origin.ownerDid,
+          origin.sessionId,
+          origin.runId,
+          origin.requestId,
+          origin.bindingId,
+          origin.bindingRevision,
+          encoded,
+          proposedExpiry,
+          this.now(),
+        ],
+      );
+      return proposedExpiry;
+    });
+  }
+
+  async record(
+    origin: HubActionOrigin,
+    input: ActionReferenceV1,
+  ): Promise<ActionReferenceV1> {
+    const reference = parseReference(input);
+    if (
+      reference.bindingId !== origin.bindingId ||
+      reference.bindingRevision !== origin.bindingRevision
+    )
+      throw new Error(
+        'Hub action reference does not match the channel binding',
+      );
+    return this.db.transaction(async () => {
+      const previous = await this.db.get<ActionRow>(
+        'SELECT * FROM hub_actions WHERE request_key = ?',
+        [origin.requestKey],
+      );
+      if (previous) {
+        const old = parseReference(JSON.parse(previous.reference));
+        if (
+          previous.owner_did !== origin.ownerDid ||
+          previous.session_id !== origin.sessionId ||
+          previous.run_id !== origin.runId ||
+          previous.request_id !== origin.requestId ||
+          previous.binding_id !== origin.bindingId ||
+          previous.binding_revision !== origin.bindingRevision ||
+          canonicalJson(old) !== canonicalJson(reference)
+        )
+          throw new Error('Hub action request key belongs to another action');
+        return old;
+      }
+      await this.db.run(
+        `INSERT INTO hub_actions(action_id,owner_did,session_id,run_id,request_id,binding_id,binding_revision,request_key,reference,expires_at)
+         VALUES(?,?,?,?,?,?,?,?,?,?)`,
+        [
+          reference.id,
+          origin.ownerDid,
+          origin.sessionId,
+          origin.runId,
+          origin.requestId,
+          origin.bindingId,
+          origin.bindingRevision,
+          origin.requestKey,
+          JSON.stringify(reference),
+          reference.expiresAt,
+        ],
+      );
+      return reference;
+    });
+  }
+
+  async get(
+    ownerDid: string,
+    actionId: string,
+  ): Promise<{ origin: HubActionOrigin; reference: ActionReferenceV1 } | null> {
+    const row = await this.db.get<ActionRow>(
+      'SELECT * FROM hub_actions WHERE owner_did = ? AND action_id = ?',
+      [ownerDid, actionId],
+    );
+    if (!row) return null;
+    return {
+      origin: {
+        ownerDid: row.owner_did,
+        sessionId: row.session_id,
+        runId: row.run_id,
+        requestId: row.request_id,
+        bindingId: row.binding_id,
+        bindingRevision: row.binding_revision,
+        requestKey: row.request_key,
+      },
+      reference: parseReference(JSON.parse(row.reference)),
+    };
+  }
+
+  async forRun(
+    ownerDid: string,
+    sessionId: string,
+    runId: string,
+  ): Promise<ActionReferenceV1[]> {
+    const rows = await this.db.exec<ActionRow>(
+      'SELECT * FROM hub_actions WHERE owner_did = ? AND session_id = ? AND run_id = ? ORDER BY action_id',
+      [ownerDid, sessionId, runId],
+    );
+    return rows.map((row) => parseReference(JSON.parse(row.reference)));
+  }
+
+  /**
+   * The run's actions with their latest stored outcome and refresh
+   * schedule, from SQLite only.
+   */
+  async runState(
+    ownerDid: string,
+    sessionId: string,
+    runId: string,
+  ): Promise<
+    {
+      reference: ActionReferenceV1;
+      latest: ActionOutcomeV1 | null;
+      nextCheckAt: number;
+      checkAttempts: number;
+    }[]
+  > {
+    const rows = await this.db.exec<{
+      reference: string;
+      next_check_at: number;
+      check_attempts: number;
+      outcome: string | null;
+    }>(
+      `SELECT a.reference, a.next_check_at, a.check_attempts, (
+         SELECT e.outcome FROM hub_action_outcomes e WHERE e.action_id=a.action_id
+         ORDER BY e.sequence DESC LIMIT 1) AS outcome
+       FROM hub_actions a WHERE a.owner_did=? AND a.session_id=? AND a.run_id=?
+       ORDER BY a.action_id`,
+      [ownerDid, sessionId, runId],
+    );
+    return rows.map((row) => ({
+      reference: parseReference(JSON.parse(row.reference)),
+      latest: row.outcome ? parseOutcome(JSON.parse(row.outcome)) : null,
+      nextCheckAt: row.next_check_at,
+      checkAttempts: row.check_attempts,
+    }));
+  }
+
+  /** Spend one status refresh: the next waits 15 s, doubling to 10 min. */
+  async scheduleCheck(actionId: string, attempts: number): Promise<void> {
+    await this.db.run(
+      'UPDATE hub_actions SET next_check_at = ?, check_attempts = ? WHERE action_id = ?',
+      [
+        this.now() +
+          Math.min(HUB_CHECK_BASE_MS * 2 ** attempts, HUB_CHECK_MAX_MS),
+        attempts + 1,
+        actionId,
+      ],
+    );
+  }
+
+  /**
+   * Store an authenticated outcome. Returns whether it was new: a repeat
+   * (same event) or an older one than the latest stored (a late or stale
+   * read; sequences only move forward) changes nothing.
+   */
+  async recordOutcome(input: ActionOutcomeV1): Promise<boolean> {
+    const outcome = parseOutcome(input);
+    const held = await this.get(outcome.ownerDid, outcome.reference.id);
+    if (
+      !held ||
+      canonicalJson(held.reference) !== canonicalJson(outcome.reference)
+    )
+      throw new Error('Hub outcome does not match a prepared action');
+    if (
+      outcome.authorizedRevision < held.reference.revision ||
+      (outcome.authorizedRevision === held.reference.revision &&
+        outcome.authorizedDigest !== held.reference.digest)
+    )
+      throw new Error(
+        'Hub outcome revision does not descend from the reference',
+      );
+    return this.db.transaction(async () => {
+      const existing = await this.db.get<{ outcome: string }>(
+        'SELECT outcome FROM hub_action_outcomes WHERE event_id = ?',
+        [outcome.eventId],
+      );
+      if (existing) {
+        if (
+          canonicalJson(JSON.parse(existing.outcome)) !== canonicalJson(outcome)
+        )
+          throw new Error('Hub outcome event ID conflict');
+        return false;
+      }
+      const latest = await this.db.get<{ sequence: number }>(
+        'SELECT MAX(sequence) AS sequence FROM hub_action_outcomes WHERE action_id = ?',
+        [outcome.reference.id],
+      );
+      if (latest?.sequence != null && outcome.sequence < latest.sequence)
+        return false;
+      const sameSequence = await this.db.get<{ outcome: string }>(
+        'SELECT outcome FROM hub_action_outcomes WHERE action_id = ? AND sequence = ?',
+        [outcome.reference.id, outcome.sequence],
+      );
+      if (sameSequence) throw new Error('Hub outcome sequence conflict');
+      await this.db.run(
+        'INSERT INTO hub_action_outcomes(event_id,action_id,sequence,outcome) VALUES(?,?,?,?)',
+        [
+          outcome.eventId,
+          outcome.reference.id,
+          outcome.sequence,
+          JSON.stringify(outcome),
+        ],
+      );
+      return true;
+    });
+  }
+
+  async outcomesForRun(
+    ownerDid: string,
+    sessionId: string,
+    runId: string,
+  ): Promise<ActionOutcomeV1[]> {
+    const rows = await this.db.exec<{ outcome: string }>(
+      `SELECT o.outcome FROM hub_actions a JOIN hub_action_outcomes o ON o.event_id=(
+         SELECT e.event_id FROM hub_action_outcomes e WHERE e.action_id=a.action_id
+         ORDER BY e.sequence DESC LIMIT 1)
+       WHERE a.owner_did=? AND a.session_id=? AND a.run_id=?
+       ORDER BY a.action_id`,
+      [ownerDid, sessionId, runId],
+    );
+    return rows.map((row) => parseOutcome(JSON.parse(row.outcome)));
+  }
+}

package/src/matrix/gateway-do.ts

@@ -249,6 +249,40 @@ function isForbidden(err: unknown): boolean {
   );
 }
 
+/** A topic read's own ceiling when the caller names no deadline. */
+const TOPIC_READ_MS = 10_000;
+/** Relations pages one topic history read may walk (32 relations each). */
+const TOPIC_HISTORY_MAX_PAGES = 16;
+/** Decrypted bytes one topic history read may hand back over the stub. */
+const TOPIC_HISTORY_MAX_BYTES = 2 * 1024 * 1024;
+/** Milliseconds left before `deadlineAt`, at least one. */
+function remaining(deadlineAt: number): number {
+  return Math.max(1, Math.min(TOPIC_READ_MS, deadlineAt - Date.now()));
+}
+/**
+ * `work`, or a rejection at `deadlineAt`. The work itself is not cancelled
+ * (the SDK's decrypt wait takes no signal); the caller just stops waiting.
+ */
+async function withinDeadline<T>(
+  work: Promise<T>,
+  deadlineAt: number,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      work,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new Error('Topic history verification timed out')),
+          Math.max(0, deadlineAt - Date.now()),
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1194,6 +1228,148 @@ export class MatrixGatewayDO
     return { roomId };
   }
 
+  async getTopicRoomState(roomId: string): Promise<JsonString> {
+    const response = await this.fetchCapped<unknown>(
+      `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/state`,
+      {},
+      { capBytes: 524288, timeoutMs: 10000 },
+    );
+    if (response.oversized || !response.json)
+      throw new Error('Topic room state exceeds verification bounds');
+    return JSON.stringify(response.json);
+  }
+  /**
+   * One topic event: `/event` once, with its room binding and state key.
+   * A plaintext event (every state event) is returned from that read; an
+   * encrypted one needs the SDK's decrypting read (a second GET: its
+   * decrypt API takes an event id, not an event). The decrypt wait is cut
+   * at the caller's deadline.
+   */
+  async getTopicEvent(
+    roomId: string,
+    eventId: string,
+    opts: { deadlineAt?: number } = {},
+  ): Promise<JsonString | null> {
+    const deadlineAt = Math.min(
+      opts.deadlineAt ?? Infinity,
+      Date.now() + TOPIC_READ_MS,
+    );
+    const raw = await this.fetchCapped<Record<string, unknown>>(
+      `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/event/${encodeURIComponent(eventId)}`,
+      {},
+      { capBytes: 262144, timeoutMs: remaining(deadlineAt) },
+    );
+    if (raw.oversized || !raw.json)
+      throw new Error('Topic event exceeds verification bounds');
+    if (raw.json.room_id !== undefined && raw.json.room_id !== roomId)
+      throw new Error('Topic event room binding mismatch');
+    const stateKey =
+      typeof raw.json.state_key === 'string'
+        ? { state_key: raw.json.state_key }
+        : {};
+    if (raw.json.type !== 'm.room.encrypted')
+      return JSON.stringify({
+        event_id: raw.json.event_id,
+        type: raw.json.type,
+        content: raw.json.content,
+        sender: raw.json.sender,
+        origin_server_ts: raw.json.origin_server_ts,
+        ...stateKey,
+        room_id: roomId,
+      });
+    const decrypted = await withinDeadline(
+      this.getEvent(roomId, eventId),
+      deadlineAt,
+    );
+    if (!decrypted) return null;
+    return JSON.stringify({
+      ...JSON.parse(decrypted),
+      ...stateKey,
+      room_id: roomId,
+    });
+  }
+  /**
+   * The `m.reference` relations of a topic root, decrypted. Only `sender`'s
+   * relations are decrypted and counted (another member's cost nothing and
+   * cannot fork or overflow the read); at most 256 of them and
+   * `TOPIC_HISTORY_MAX_BYTES` decrypted, within the caller's deadline.
+   */
+  async getTopicHistory(
+    roomId: string,
+    root: string,
+    opts: { deadlineAt?: number; sender?: string } = {},
+  ): Promise<JsonString> {
+    const events: unknown[] = [];
+    let bytes = 0;
+    const deadlineAt = Math.min(
+      opts.deadlineAt ?? Infinity,
+      Date.now() + TOPIC_READ_MS,
+    );
+    const timedOut = () => {
+      if (Date.now() >= deadlineAt)
+        throw new Error('Topic history verification timed out');
+    };
+    let from: string | undefined;
+    for (let page = 0; page < TOPIC_HISTORY_MAX_PAGES; page++) {
+      timedOut();
+      const response = await this.fetchCapped<{
+        chunk: {
+          event_id?: string;
+          room_id?: string;
+          state_key?: string;
+          sender?: string;
+        }[];
+        next_batch?: string;
+      }>(
+        `/_matrix/client/v1/rooms/${encodeURIComponent(roomId)}/relations/${encodeURIComponent(root)}/m.reference`,
+        { limit: '32', ...(from ? { from } : {}) },
+        { capBytes: 524288, timeoutMs: remaining(deadlineAt) },
+      );
+      if (response.oversized || !response.json)
+        throw new Error('Topic history exceeds verification bounds');
+      // The relations page already carries each event's room, sender and
+      // state key; only the decryption read is needed per kept event, eight
+      // at a time, which keeps a 60-event topic inside the caller's budget
+      // without flooding the homeserver from this one shared object.
+      const chunk = response.json.chunk.filter(
+        (event) => opts.sender === undefined || event.sender === opts.sender,
+      );
+      if (events.length + chunk.length > 256)
+        throw new Error('Topic history exceeds 256 events');
+      for (let i = 0; i < chunk.length; i += 8) {
+        timedOut();
+        const values = await Promise.all(
+          chunk.slice(i, i + 8).map(async (event) => {
+            if (!event.event_id)
+              throw new Error('Topic history event has no ID');
+            if (event.room_id !== undefined && event.room_id !== roomId)
+              throw new Error('Topic history event room binding mismatch');
+            timedOut();
+            const decrypted = await withinDeadline(
+              this.getEvent(roomId, event.event_id),
+              deadlineAt,
+            );
+            if (!decrypted) throw new Error('Topic history is incomplete');
+            bytes += decrypted.length;
+            if (bytes > TOPIC_HISTORY_MAX_BYTES)
+              throw new Error('Topic history exceeds verification bounds');
+            return {
+              ...(JSON.parse(decrypted) as Record<string, unknown>),
+              ...(typeof event.state_key === 'string'
+                ? { state_key: event.state_key }
+                : {}),
+              room_id: roomId,
+            };
+          }),
+        );
+        events.push(...values);
+      }
+      if (!response.json.next_batch) return JSON.stringify(events);
+      from = response.json.next_batch;
+    }
+    throw new Error('Topic history exceeds verification bounds');
+  }
+
   override async getRoomState(roomId: string): Promise<JsonString> {
     const deadline = Date.now() + PENDING_INVITE_GRACE_MS;
     for (;;) {

package/src/matrix/reply-parts.ts

@@ -60,10 +60,16 @@ export function replyPartContent(part: ReplyPart): {
       body: part.text,
       formattedBody: renderRoomMarkdown(part.text),
     };
-  const { title, url } = part.artifact;
+  const { title, url } =
+    part.kind === 'action'
+      ? part.action
+      : part.kind === 'hub-action'
+        ? { title: part.summary, url: part.actionReference.url }
+        : part.artifact;
+  const label = part.kind === 'artifact' ? 'Open document' : 'Review action';
   return {
     body: `${title}\n${url}`,
-    formattedBody: `<p><strong>${escapeHtml(title)}</strong><br><a href="${escapeHtml(url)}">Open document</a></p>`,
+    formattedBody: `<p><strong>${escapeHtml(title)}</strong><br><a href="${escapeHtml(url)}">${label}</a></p>`,
   };
 }