@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/editor/prompts.ts

@@ -0,0 +1,59 @@
+/**
+ * Prompts for the content-assistant editor surface: one sub-agent prompt and
+ * two main-agent overlays (a document is open / a workspace is in scope).
+ */
+
+import { GRANT_ACCESS_TOOL } from './failures';
+
+/** The Portal browser tool that lists the user's documents. */
+const LIST_PAGES_TOOL = 'list_workspace_pages';
+const CREATE_PAGE_TOOL = 'create_page_room';
+
+const TOOL_REFERENCE = `## Your tools
+
+**Reading**
+- \`read_document\` — every block in order: id, type, props, text (markdown), plus the page title. Paginate with \`start\`/\`limit\`.
+- \`read_block\` — one block in full, including nested children.
+- \`search_document\` — find blocks by a phrase in their text or props.
+
+**Writing**
+- \`insert_content\` — add new content from markdown, at the end (default), at the start, or before/after a block.
+- \`edit_block\` — change existing blocks. Takes a **batch** of edits applied atomically: if one is refused, none are applied.
+- \`delete_block\` — remove a block and everything nested in it.
+- \`move_block\` — reorder by moving a block before/after another.
+- \`replace_text\` — swap a phrase wherever it appears, preserving surrounding formatting.
+
+## Rules
+
+1. **Read before you write.** Block ids come from \`read_document\` or \`search_document\` in this turn. Never guess an id, and never reuse one from an earlier turn — the user may have edited the document since.
+2. **Small edits use \`replace_text\`.** Reserve \`edit_block\` text rewrites for when a block is genuinely being replaced; rewriting a whole block to fix one word loses the author's formatting.
+3. **Batch related \`edit_block\` edits into one call.** One call is one atomic change to the document.
+4. **You edit prose, not behaviour.** Paragraphs, headings, lists, quotes and code blocks are yours. Custom blocks (checkboxes, actions, forms, proposals, claims, …) accept only \`title\` and \`description\` — everything else configures how they behave and will be refused. \`secrets\` and \`skills\` blocks are never editable and their values are never shown to you.
+5. **Confirm before destroying.** Ask the user before deleting or wholesale-replacing content they did not explicitly ask you to change.
+6. **Report what you changed, precisely.** Name the blocks and the values. Never claim an edit that a tool did not confirm.
+
+## When a tool refuses
+
+Tool results carry a \`code\` you must act on:
+
+- \`needs_access\` — the document is readable but not writable by you. You do NOT hold the tool that fixes this. Stop and return the \`needs_access\` code to whoever delegated the task; they hold \`${GRANT_ACCESS_TOOL}\` and will grant access and re-delegate. Do not retry the edit, and do not tell the user to grant access themselves.
+- \`read_only_flow\` — the document is a live flow. Read it and describe it; say that edits have to be made in the flow builder. Do not retry.
+- \`prop_not_editable\` — name the exact property in your reply and say why it cannot be changed. Do not retry with the same property.
+- \`block_not_found\` — the id is stale. Re-read the document and use current ids.
+- \`not_a_member\` — the document is not the user's. Say so plainly. Do not retry.
+- \`no_document\` — no document is open and no room id was given. Return the code; do not invent a room id.
+- \`flush_timeout\` — the edit could **not** be confirmed as saved. Treat it as not applied and say so.
+
+Never present a refusal as a success, and never silently retry a refusal.`;
+
+/** System prompt for the room-bound content sub-agent. */
+export const editorAgentPrompt = `You are the Editor Agent: a content assistant for one document in the user's workspace.
+
+You read and edit the document's content — its words, its structure, its ordering. You do not build flows, configure action blocks, run anything, or fill in forms.
+
+You receive a single self-contained task and have no access to the wider conversation. Do exactly what the task asks, then report concretely what you read or changed.
+
+${TOOL_REFERENCE}`;
+
+/** Why the editor surface could not be attached to this request. */
+export type EditorUnavailableReason = 'not-member' | 'bind-error';

package/src/plugins/editor/prop-policy.ts

@@ -0,0 +1,147 @@
+/**
+ * What the assistant may write, and what it may see.
+ *
+ * The assistant is a *content* assistant: it owns prose. Custom IXO blocks are
+ * behaviour — their props configure actions, authorisation, conditions, and
+ * delegation — so only their two human-readable labels are writable, and two of
+ * them are off limits entirely.
+ */
+
+import { proseBlockTypes } from './blocknote-bridge';
+
+/**
+ * The custom blocks the IXO editor registers on top of BlockNote's own set,
+ * from `packages/editor/src/mantine/blocks/index.ts` (`blockSpecs`). All of
+ * them declare `content: 'none'` — they carry no inline text, only props.
+ */
+export const IXO_BLOCK_TYPES: readonly string[] = [
+  'action',
+  'apiRequest',
+  'checkbox',
+  'claim',
+  'domainCardViewer',
+  'domainCreator',
+  'domainCreatorSign',
+  'dynamicList',
+  'email',
+  'embed',
+  'enumChecklist',
+  'evaluator',
+  'flowLink',
+  'form',
+  'governanceGroup',
+  'list',
+  'location',
+  'notify',
+  'overview',
+  'proposal',
+  'protocolSelector',
+  'secrets',
+  'skills',
+  'visualization',
+];
+
+/** Blocks the assistant never writes to, whatever the prop. */
+export const LOCKED_BLOCK_TYPES: readonly string[] = ['secrets', 'skills'];
+
+/** Blocks whose prop values are withheld on read. */
+export const REDACTED_BLOCK_TYPES: readonly string[] = ['secrets'];
+
+/** The only props writable on a custom IXO block. */
+export const IXO_WRITABLE_PROPS: readonly string[] = ['title', 'description'];
+
+/** Placeholder shown instead of a redacted prop value. */
+export const REDACTED_VALUE = '[redacted]';
+
+export type BlockClass = 'prose' | 'ixo' | 'locked' | 'unknown';
+
+/**
+ * Classify a block type.
+ *
+ * `unknown` covers block types this runtime has never heard of — a newer editor
+ * version, or a block from another schema. They are treated like IXO blocks
+ * (labels only, no text) rather than like prose, because assuming a block is
+ * inert prose is the destructive assumption.
+ */
+export function classifyBlockType(blockType: string): BlockClass {
+  if (LOCKED_BLOCK_TYPES.includes(blockType)) return 'locked';
+  if (proseBlockTypes().has(blockType)) return 'prose';
+  if (IXO_BLOCK_TYPES.includes(blockType)) return 'ixo';
+  return 'unknown';
+}
+
+/** Prose blocks own their inline content; everything else has none. */
+export function isTextEditable(blockType: string): boolean {
+  return classifyBlockType(blockType) === 'prose';
+}
+
+export interface PropFilterResult {
+  /** Props that may be written, normalised to attribute strings. */
+  allowed: Record<string, string>;
+  /** Props refused, with the reason to report to the agent. */
+  rejected: Array<{ prop: string; reason: string }>;
+}
+
+function normalise(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  return JSON.stringify(value) ?? '';
+}
+
+/**
+ * Split a requested prop patch into what may be written and what may not.
+ *
+ * - prose blocks: every prop (they are presentation only — alignment, colour,
+ *   heading level).
+ * - IXO blocks and unknown types: `title` and `description` only. Behavioural
+ *   props (`conditions`, `authorisedActors`, action `type`, `inputs`,
+ *   delegation config, …) are refused by falling outside that pair.
+ * - locked blocks: nothing.
+ */
+export function filterWritableProps(
+  blockType: string,
+  props: Record<string, unknown>,
+): PropFilterResult {
+  const result: PropFilterResult = { allowed: {}, rejected: [] };
+  const blockClass = classifyBlockType(blockType);
+
+  for (const [prop, value] of Object.entries(props)) {
+    if (blockClass === 'locked') {
+      result.rejected.push({
+        prop,
+        reason: `'${blockType}' blocks are never editable by the assistant`,
+      });
+      continue;
+    }
+    if (blockClass === 'prose' || IXO_WRITABLE_PROPS.includes(prop)) {
+      result.allowed[prop] = normalise(value);
+      continue;
+    }
+    result.rejected.push({
+      prop,
+      reason:
+        `'${prop}' configures how the '${blockType}' block behaves — only ` +
+        `${IXO_WRITABLE_PROPS.join(' and ')} are editable on this block type`,
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Redact prop values the assistant must not relay. Keys stay visible so the
+ * agent can still describe the block's shape.
+ */
+export function redactProps(
+  blockType: string,
+  props: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!REDACTED_BLOCK_TYPES.includes(blockType)) return props;
+  const redacted: Record<string, unknown> = {};
+  for (const key of Object.keys(props)) {
+    redacted[key] = REDACTED_VALUE;
+  }
+  return redacted;
+}

package/src/plugins/editor/provider.ts

@@ -0,0 +1,386 @@
+import { MatrixProvider } from '@ixo/matrix-crdt';
+import type { MatrixClient } from 'matrix-js-sdk';
+import * as Y from 'yjs';
+
+import { createConsoleLogger } from '../../core/utils';
+
+const logger = createConsoleLogger({ module: 'editor-provider' });
+
+const wait = (ms: number) =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+type RoomDescriptor =
+  | { type: 'id'; id: string }
+  | { type: 'alias'; alias: string };
+
+/**
+ * The oracle cannot see the room at all — it is neither a member nor able to
+ * join it. Distinct from a sync timeout so callers can tell "no access" from
+ * "service is slow".
+ */
+export class RoomNotAccessibleError extends Error {
+  constructor(
+    readonly roomId: string,
+    readonly detail: string,
+  ) {
+    super(`Room ${roomId} not accessible: ${detail}`);
+    this.name = 'RoomNotAccessibleError';
+  }
+}
+
+export interface ProviderInitResult {
+  doc: Y.Doc;
+  awareness?: unknown;
+  provider: MatrixProvider;
+}
+export interface MatrixRoomById {
+  type: 'id';
+  value: string;
+}
+
+export interface MatrixRoomByAlias {
+  type: 'alias';
+  value: string;
+}
+export interface ProviderConfig {
+  docName: string;
+  enableAwareness: boolean;
+  retryAttempts: number;
+  retryDelayMs: number;
+  /** How long matrix-crdt batches Y.Doc updates before sending them. */
+  flushInterval?: number;
+  /** How long to wait before retrying a write the homeserver rejected. */
+  retryIfForbiddenInterval?: number;
+  /** How many rejected writes to retry before giving up (0 = unlimited). */
+  maxForbiddenRetries?: number;
+}
+
+export type MatrixRoomConfig = MatrixRoomById | MatrixRoomByAlias;
+
+export interface MatrixConfig {
+  baseUrl: string;
+  accessToken: string;
+  userId: string;
+  room: MatrixRoomConfig;
+  initialSyncTimeoutMs: number;
+}
+export interface BlockNoteConfig {
+  defaultBlockId?: string;
+  blockNamespace?: string;
+  mutableAttributeKeys: string[];
+}
+
+export interface AppConfig {
+  matrix: MatrixConfig;
+  provider: ProviderConfig;
+  blocknote: BlockNoteConfig;
+}
+
+/**
+ * MatrixProviderManager
+ *
+ * Manages a Y.Doc CRDT for a specific Matrix room.
+ *
+ * IMPORTANT: This class assumes the Matrix client is ALREADY synced
+ * via the EditorMatrixClient singleton. It does NOT manage client lifecycle.
+ *
+ * Each instance creates:
+ * - A new Y.Doc for the room
+ * - A MatrixProvider to sync Y.Doc with Matrix
+ *
+ * The singleton EditorMatrixClient handles:
+ * - Matrix connection
+ * - Background sync
+ * - Client lifecycle
+ */
+export class MatrixProviderManager {
+  private readonly doc: Y.Doc;
+  private provider: MatrixProvider | undefined;
+  private readonly disposables: Array<{ dispose: () => void }> = [];
+  private documentAvailable = false;
+  private disposed = false;
+  private availabilityResolvers: Array<() => void> = [];
+
+  constructor(
+    private readonly matrixClient: MatrixClient,
+    private readonly cfg: AppConfig,
+  ) {
+    this.doc = new Y.Doc();
+  }
+
+  public get ydoc(): Y.Doc {
+    return this.doc;
+  }
+
+  public get matrixProvider(): MatrixProvider | undefined {
+    return this.provider;
+  }
+
+  /**
+   * Initialize the provider for the configured room.
+   *
+   * Assumes the Matrix client is already synced (via EditorMatrixClient singleton).
+   * Creates a MatrixProvider to sync the Y.Doc with the Matrix room.
+   */
+  public async init(): Promise<ProviderInitResult> {
+    if (this.disposed) {
+      throw new Error('MatrixProviderManager was already disposed');
+    }
+
+    const attempts = Math.max(1, this.cfg.provider.retryAttempts);
+    const delayMs = Math.max(0, this.cfg.provider.retryDelayMs);
+
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      try {
+        // Initialize the provider (creates MatrixProvider, fetches room history)
+        await this.initializeProvider();
+
+        // Wait for document to become available
+        await this.waitForAvailability(this.cfg.matrix.initialSyncTimeoutMs);
+
+        logger.log('Matrix provider initialized', { attempt });
+        logger.log(`📄 Y.Doc GUID: ${this.doc.guid}`);
+        logger.log(`📄 Room ID: ${JSON.stringify(this.cfg.matrix.room)}`);
+
+        return {
+          doc: this.doc,
+          awareness: this.provider?.awarenessInstance,
+          provider: this.ensureProvider(),
+        };
+      } catch (error) {
+        logger.warn(`Matrix provider init attempt ${attempt} failed`, error);
+        await this.cleanupProvider();
+
+        if (attempt === attempts) {
+          throw error;
+        }
+
+        const backoff = delayMs * attempt;
+        logger.log(`Retrying provider initialization in ${backoff}ms`);
+        await wait(backoff);
+      }
+    }
+
+    throw new Error('Matrix provider initialization failed');
+  }
+
+  /**
+   * Ensures the room is available in the Matrix client's store.
+   * This is critical for createMessagesRequest() to work correctly.
+   */
+  private async ensureRoomAvailable(roomId: string): Promise<void> {
+    const room = this.matrixClient.getRoom(roomId);
+
+    if (!room) {
+      logger.warn(
+        `Room ${roomId} not in client store, attempting to join/peek...`,
+      );
+
+      try {
+        // Try joining first — peek fails when room previews are disabled
+        await this.matrixClient.joinRoom(roomId);
+        logger.log(`Successfully joined room ${roomId}`);
+      } catch (joinError) {
+        logger.warn(joinError);
+        // Fall back to peek if join fails (e.g. already joined but not synced)
+        try {
+          await this.matrixClient.peekInRoom(roomId);
+          logger.log(`Successfully peeked into room ${roomId}`);
+        } catch (peekError) {
+          const errorMsg =
+            peekError instanceof Error ? peekError.message : String(peekError);
+          throw new RoomNotAccessibleError(roomId, errorMsg);
+        }
+      }
+    } else {
+      logger.debug?.(`Room ${roomId} found in client store`);
+    }
+  }
+
+  private async initializeProvider() {
+    this.cleanupProviderListeners();
+
+    const roomDescriptor = this.resolveRoomDescriptor();
+
+    // Resolve room ID (handle both 'id' and 'alias' types)
+    let roomId: string;
+    if (roomDescriptor.type === 'id') {
+      roomId = roomDescriptor.id;
+    } else {
+      // Resolve room alias to room ID
+      const ret = await this.matrixClient.getRoomIdForAlias(
+        roomDescriptor.alias,
+      );
+      roomId = ret.room_id;
+    }
+
+    // Ensure the room is in the client's store before proceeding
+    // This is critical for MatrixProvider to fetch room history correctly
+    await this.ensureRoomAvailable(roomId);
+
+    logger.log('Creating MatrixProvider', roomDescriptor);
+
+    this.provider = new MatrixProvider(
+      this.doc,
+      this.matrixClient,
+      roomDescriptor,
+      {
+        enableAwareness: this.cfg.provider.enableAwareness,
+        reader: {
+          snapshotInterval: 10,
+        },
+
+        // A rejected write is final within one request — room power levels do
+        // not change mid-call — so retry once, fast, instead of matrix-crdt's
+        // default 3 attempts 30s apart. Without this a caller awaiting
+        // `waitForFlush()` before reporting success would block for ~90s.
+        writer: {
+          flushInterval: this.cfg.provider.flushInterval ?? 10,
+          retryIfForbiddenInterval:
+            this.cfg.provider.retryIfForbiddenInterval ?? 1_000,
+          maxForbiddenRetries: this.cfg.provider.maxForbiddenRetries ?? 1,
+        },
+      },
+    );
+
+    this.registerProviderListeners(this.provider);
+
+    await this.provider.initialize();
+  }
+
+  private waitForAvailability(timeoutMs: number): Promise<void> {
+    if (this.documentAvailable) {
+      return Promise.resolve();
+    }
+
+    return new Promise((resolve, reject) => {
+      const timeoutHandle = setTimeout(() => {
+        this.availabilityResolvers = this.availabilityResolvers.filter(
+          (candidate) => candidate !== resolver,
+        );
+        reject(
+          new Error(
+            `Document did not become available within ${timeoutMs}ms. Check room permissions or connectivity.`,
+          ),
+        );
+      }, timeoutMs);
+
+      const resolver = () => {
+        clearTimeout(timeoutHandle);
+        resolve();
+      };
+
+      this.availabilityResolvers.push(resolver);
+    });
+  }
+
+  private registerProviderListeners(provider: MatrixProvider) {
+    this.disposables.push(
+      provider.onDocumentAvailable(() => {
+        logger.log('Matrix document available');
+
+        // Wait briefly for Y.Doc to apply initial sync
+        // Can't rely on onReceivedEvents - it only fires for NEW events,
+        // not when connecting to an already-synced client
+        setTimeout(() => {
+          logger.log('Marking document as available after sync delay');
+          this.documentAvailable = true;
+          const resolvers = [...this.availabilityResolvers];
+          this.availabilityResolvers = [];
+          resolvers.forEach((resolver) => resolver());
+        }, 500); // Short delay for Y.Doc sync
+      }),
+    );
+
+    this.disposables.push(
+      provider.onDocumentUnavailable(() => {
+        logger.warn('Matrix document unavailable');
+        this.documentAvailable = false;
+      }),
+    );
+
+    this.disposables.push(
+      provider.onReceivedEvents(() => {
+        logger.debug?.('Received Matrix events - Y.Doc syncing content');
+      }),
+    );
+  }
+
+  private cleanupProviderListeners() {
+    while (this.disposables.length > 0) {
+      const disposable = this.disposables.pop();
+      try {
+        disposable?.dispose();
+      } catch (error) {
+        logger.warn('Failed to dispose provider listener', error);
+      }
+    }
+  }
+
+  private resolveRoomDescriptor(): RoomDescriptor {
+    if (this.cfg.matrix.room.type === 'id') {
+      return { type: 'id', id: this.cfg.matrix.room.value };
+    }
+
+    return { type: 'alias', alias: this.cfg.matrix.room.value };
+  }
+
+  private ensureProvider(): MatrixProvider {
+    if (!this.provider) {
+      throw new Error('Matrix provider not initialized');
+    }
+    return this.provider;
+  }
+
+  /**
+   * Dispose of this provider manager.
+   *
+   * Cleans up:
+   * - MatrixProvider (stops polling, removes listeners)
+   * - Y.Doc (destroys local document state)
+   *
+   * Does NOT touch the Matrix client - it's managed by EditorMatrixClient singleton
+   * and shared across all providers/rooms.
+   */
+  public async dispose() {
+    if (this.disposed) {
+      return;
+    }
+
+    logger.log('Disposing Matrix provider manager');
+
+    // Clean up provider and Y.Doc
+    await this.cleanupProvider();
+    this.doc.destroy();
+
+    // NOTE: We NEVER call matrixClient.stopClient() here!
+    // The Matrix client is managed by EditorMatrixClient singleton
+    // and is shared across all rooms. Stopping it would break
+    // all other active providers.
+
+    this.disposed = true;
+  }
+
+  private async cleanupProvider() {
+    this.cleanupProviderListeners();
+
+    if (this.provider) {
+      try {
+        await this.provider.waitForFlush();
+        this.provider.dispose();
+      } catch (error) {
+        logger.warn('Error while disposing MatrixProvider', error);
+      } finally {
+        this.provider = undefined;
+      }
+    }
+
+    if (!this.documentAvailable) {
+      return;
+    }
+
+    this.documentAvailable = false;
+  }
+}

package/src/plugins/editor/room-membership.ts

@@ -0,0 +1,95 @@
+/**
+ * Cached Matrix room-membership guard, Workers edition.
+ *
+ * The editor and flows plugins act on a room with the oracle's privileged
+ * admin identity, where the *room id comes from the request*. Left unchecked,
+ * a user could pass another user's room id and have the oracle read or edit a
+ * page they don't own. Before any such read/write we assert the requesting
+ * user is actually a joined member of the room.
+ *
+ * On Workers, membership is resolved through the gateway Durable Object via
+ * `ctx.matrix.getRoomState(roomId)` — the full state array carries every
+ * `m.room.member` event — and cached per room for a short TTL so repeated
+ * tool calls in one turn don't pay the gateway round-trip each time.
+ */
+import type { RuntimeContext } from '../../plugin-api/types';
+
+interface MembershipEntry {
+  members: Set<string>;
+  expiresAt: number;
+}
+
+const DEFAULT_TTL_MS = 60_000;
+const cache = new Map<string, MembershipEntry>();
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** Joined member ids from a room-state snapshot's event array. */
+function joinedMembers(state: ReadonlyArray<unknown>): Set<string> {
+  const members = new Set<string>();
+  for (const event of state) {
+    if (!isRecord(event)) continue;
+    if (event.type !== 'm.room.member') continue;
+    const stateKey = event.state_key;
+    if (typeof stateKey !== 'string' || stateKey.length === 0) continue;
+    const content = event.content;
+    if (isRecord(content) && content.membership === 'join') {
+      members.add(stateKey);
+    }
+  }
+  return members;
+}
+
+function sweepExpiredEntries(): void {
+  const now = Date.now();
+  for (const [key, entry] of cache) {
+    if (entry.expiresAt <= now) cache.delete(key);
+  }
+}
+
+async function getRoomMembers(
+  ctx: Pick<RuntimeContext, 'matrix'>,
+  roomId: string,
+  ttlMs: number,
+): Promise<Set<string>> {
+  const cached = cache.get(roomId);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.members;
+  }
+  const snapshot = await ctx.matrix.getRoomState(roomId);
+  const members = joinedMembers(snapshot.state);
+  sweepExpiredEntries();
+  cache.set(roomId, { members, expiresAt: Date.now() + ttlMs });
+  return members;
+}
+
+/**
+ * True when `matrixUserId` is a joined member of `roomId`. Fails closed:
+ * returns `false` on a missing id or any lookup error, so a Matrix outage
+ * denies access rather than silently granting it.
+ */
+export async function isUserInRoom(
+  ctx: Pick<RuntimeContext, 'matrix'>,
+  roomId: string,
+  matrixUserId: string | undefined,
+  opts: { ttlMs?: number } = {},
+): Promise<boolean> {
+  if (!roomId || !matrixUserId) return false;
+  try {
+    const members = await getRoomMembers(
+      ctx,
+      roomId,
+      opts.ttlMs ?? DEFAULT_TTL_MS,
+    );
+    return members.has(matrixUserId);
+  } catch {
+    return false;
+  }
+}
+
+/** Drop a room's cached membership (e.g. after a known membership change). */
+export function invalidateRoomMembership(roomId: string): void {
+  cache.delete(roomId);
+}