@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/plugins/editor/content-tools.ts

@@ -8,7 +8,6 @@
  * per tool.
  */
 
-import type { MatrixClient } from 'matrix-js-sdk';
 import type * as Y from 'yjs';
 import { z } from 'zod';
 
@@ -18,7 +17,7 @@ import {
   markdownToBlockContainers,
   markdownToInlineContent,
 } from './blocknote-bridge';
-import { applyDocumentEdit, withDocument } from './content-session';
+import { applyDocumentEdit, type DocumentSource } from './content-session';
 import {
   appendBlocks,
   flattenBlocks,
@@ -47,16 +46,17 @@ import {
   type EditorFailure,
 } from './failures';
 import {
+  classifyBlockType,
   filterWritableProps,
   isTextEditable,
   redactProps,
 } from './prop-policy';
-import type { AppConfig } from './provider';
-
 export interface ContentToolsOptions {
-  matrixClient: MatrixClient;
-  /** Provider config with the target room already baked in. */
-  appConfig: AppConfig;
+  /**
+   * The one document every tool reads and writes, shared across the calls of
+   * one `call_editor_agent` run.
+   */
+  documents: DocumentSource;
 }
 
 const DEFAULT_READ_LIMIT = 60;
@@ -84,6 +84,45 @@ function redactFlat(block: FlatDocumentBlock): FlatDocumentBlock {
   return { ...block, props: redactProps(block.type, block.props) };
 }
 
+/**
+ * The first locked block (`secrets`, `skills`) in `blockId`'s subtree,
+ * itself included. Deleting or moving a block rewrites its whole subtree, so
+ * a locked block nested anywhere inside refuses the operation.
+ */
+function findLockedBlock(
+  doc: Y.Doc,
+  blockId: string,
+): { id: string; type: string } | undefined {
+  const visit = (block: DocumentBlock): DocumentBlock | undefined => {
+    if (classifyBlockType(block.type) === 'locked') return block;
+    for (const child of block.children) {
+      const hit = visit(child);
+      if (hit) return hit;
+    }
+    return undefined;
+  };
+  const root = readBlockById(doc, blockId);
+  const hit = root ? visit(root) : undefined;
+  return hit ? { id: hit.id, type: hit.type } : undefined;
+}
+
+/** The refusal for a delete/move that would touch a locked block. */
+function lockedBlockRefusal(
+  blockId: string,
+  blockType: string,
+  locked: { id: string; type: string },
+  verb: 'deleted' | 'moved',
+): EditorFailure {
+  const where =
+    locked.id === blockId ? '' : ` (block ${locked.id} is nested inside it)`;
+  return propNotEditable(blockId, blockType, [
+    {
+      prop: 'block',
+      reason: `'${locked.type}' blocks are never editable by the assistant, so this block cannot be ${verb}${where}`,
+    },
+  ]);
+}
+
 /** Case-insensitive substring match. */
 function matches(haystack: string, needle: string): boolean {
   return haystack.toLowerCase().includes(needle.toLowerCase());
@@ -118,7 +157,7 @@ function createReadDocumentTool(options: ContentToolsOptions): PluginTool {
       const start = args.start ?? 0;
       const limit = args.limit ?? DEFAULT_READ_LIMIT;
 
-      const result = await withDocument(options, async (session) => {
+      const result = await options.documents.use(async (session) => {
         const blocks = flattenBlocks(readDocumentBlocks(session.doc)).map(
           redactFlat,
         );
@@ -161,7 +200,7 @@ function createReadBlockTool(options: ContentToolsOptions): PluginTool {
   return pluginTool(
     async (rawArgs) => {
       const args = schema.parse(rawArgs);
-      const result = await withDocument(options, async (session) => {
+      const result = await options.documents.use(async (session) => {
         const block = readBlockById(session.doc, args.block_id);
         if (!block) return blockNotFound(args.block_id);
         return {
@@ -199,7 +238,7 @@ function createSearchDocumentTool(options: ContentToolsOptions): PluginTool {
       const args = schema.parse(rawArgs);
       const limit = args.limit ?? 20;
 
-      const result = await withDocument(options, async (session) => {
+      const result = await options.documents.use(async (session) => {
         const blocks = flattenBlocks(readDocumentBlocks(session.doc)).map(
           redactFlat,
         );
@@ -292,7 +331,7 @@ function createInsertContentTool(options: ContentToolsOptions): PluginTool {
         );
       }
 
-      const result = await withDocument(options, async (session) =>
+      const result = await options.documents.use(async (session) =>
         applyDocumentEdit(session, {
           plan: (doc) => {
             // Anchored inserts need a live reference; end/start do not.
@@ -395,7 +434,7 @@ function createEditBlockTool(options: ContentToolsOptions): PluginTool {
         parsedText.set(index, await markdownToInlineContent(edit.text));
       }
 
-      const result = await withDocument(options, async (session) =>
+      const result = await options.documents.use(async (session) =>
         applyDocumentEdit(session, {
           plan: (doc): PreparedEdit[] | EditorFailure => {
             const prepared: PreparedEdit[] = [];
@@ -484,7 +523,7 @@ function createDeleteBlockTool(options: ContentToolsOptions): PluginTool {
     async (rawArgs) => {
       const args = schema.parse(rawArgs);
 
-      const result = await withDocument(options, async (session) =>
+      const result = await options.documents.use(async (session) =>
         applyDocumentEdit(session, {
           plan: (doc) => {
             const located = locateBlock(
@@ -493,7 +532,17 @@ function createDeleteBlockTool(options: ContentToolsOptions): PluginTool {
             );
             if (!located) return blockNotFound(args.block_id);
             const content = getContentElement(located.container);
-            return { blockType: content?.nodeName ?? 'unknown' };
+            const blockType = content?.nodeName ?? 'unknown';
+            const locked = findLockedBlock(doc, args.block_id);
+            if (locked) {
+              return lockedBlockRefusal(
+                args.block_id,
+                blockType,
+                locked,
+                'deleted',
+              );
+            }
+            return { blockType };
           },
           apply: (doc, plan) => {
             const removed = removeBlock(doc, args.block_id);
@@ -537,13 +586,23 @@ function createMoveBlockTool(options: ContentToolsOptions): PluginTool {
     async (rawArgs) => {
       const args = schema.parse(rawArgs);
 
-      const result = await withDocument(options, async (session) =>
+      const result = await options.documents.use(async (session) =>
         applyDocumentEdit(session, {
           plan: (doc) => {
             const fragment = doc.getXmlFragment(DOCUMENT_FRAGMENT_NAME);
-            if (!locateBlock(fragment, args.block_id)) {
+            const source = locateBlock(fragment, args.block_id);
+            if (!source) {
               return blockNotFound(args.block_id);
             }
+            const locked = findLockedBlock(doc, args.block_id);
+            if (locked) {
+              return lockedBlockRefusal(
+                args.block_id,
+                getContentElement(source.container)?.nodeName ?? 'unknown',
+                locked,
+                'moved',
+              );
+            }
             if (!locateBlock(fragment, args.reference_block_id)) {
               return blockNotFound(args.reference_block_id);
             }
@@ -619,7 +678,7 @@ function createReplaceTextTool(options: ContentToolsOptions): PluginTool {
     async (rawArgs) => {
       const args = schema.parse(rawArgs);
 
-      const result = await withDocument(options, async (session) =>
+      const result = await options.documents.use(async (session) =>
         applyDocumentEdit(session, {
           plan: (doc) => {
             if (args.block_id) {

package/src/plugins/editor/editor-mx.ts

@@ -11,7 +11,8 @@ export interface EditorMatrixClientConfig {
 const logger = createConsoleLogger({ module: 'editor-mx' });
 
 /**
- * Per-isolate singleton wrapper around a `matrix-js-sdk` `MatrixClient`. Used
+ * Per-isolate wrapper around a `matrix-js-sdk` `MatrixClient`, one live
+ * instance per set of credentials (see {@link EditorMatrixClient.getInstance}). Used
  * by `@ixo/matrix-crdt` to read/write BlockNote Y.js documents.
  *
  * No `startClient()` / sync is performed — matrix-crdt's `MatrixReader`
@@ -35,15 +36,32 @@ export class EditorMatrixClient {
   }
 
   /**
-   * Get the singleton instance. First caller supplies the Matrix admin
-   * config used for the lifetime of the isolate; subsequent callers
-   * receive the same instance and the config argument is ignored.
+   * Get the isolate's instance for these credentials. Callers pass the
+   * credentials the gateway handed out for the current request; when they
+   * differ from the cached instance's (the gateway re-minted the device
+   * token, or the homeserver or user changed) a new instance replaces it, so
+   * a warm isolate never keeps sending a revoked token. Requests already
+   * holding the previous client finish with it; it runs no sync loop, so
+   * nothing needs stopping.
    */
   public static getInstance(cfg: EditorMatrixClientConfig): EditorMatrixClient {
-    if (!EditorMatrixClient.instance) {
-      EditorMatrixClient.instance = new EditorMatrixClient(cfg);
-    }
-    return EditorMatrixClient.instance;
+    const current = EditorMatrixClient.instance;
+    if (current && current.hasCredentials(cfg)) return current;
+    const next = new EditorMatrixClient({
+      baseUrl: cfg.baseUrl,
+      userId: cfg.userId,
+      accessToken: cfg.accessToken,
+    });
+    EditorMatrixClient.instance = next;
+    return next;
+  }
+
+  private hasCredentials(cfg: EditorMatrixClientConfig): boolean {
+    return (
+      this.cfg.baseUrl === cfg.baseUrl &&
+      this.cfg.userId === cfg.userId &&
+      this.cfg.accessToken === cfg.accessToken
+    );
   }
 
   /**
@@ -113,7 +131,8 @@ export class EditorMatrixClient {
 /**
  * Resolve the `MatrixClient` used by editor tools. Prefers the
  * `matrixClient` from the plugin's runtime config (host/test-provided);
- * otherwise lazily constructs the internal singleton.
+ * otherwise lazily constructs the internal instance, rebuilt whenever the
+ * credentials passed in differ from the ones it was built with.
  *
  * Centralised so every call site (standalone-editor-tool, the flows plugin's
  * flow-doc) goes through one resolution path.

package/src/plugins/editor/editor.plugin.ts

@@ -133,7 +133,9 @@ export class EditorPlugin extends OraclePlugin {
       // the import, so only the first turn in an isolate pays for it.
       const { createStandaloneEditorTool } =
         await import('./standalone-editor-tool');
-      return [createStandaloneEditorTool({ toolsConfig })];
+      return [
+        createStandaloneEditorTool({ toolsConfig, pluginName: this.name }),
+      ];
     } catch (error) {
       const detail = error instanceof Error ? error.message : String(error);
       rtCtx.logger.error(`[editor] failed to build standalone tool: ${detail}`);

package/src/plugins/editor/failures.ts

@@ -16,7 +16,7 @@ export type EditorFailureCode =
   | 'block_not_found'
   | 'not_a_member'
   | 'no_document'
-  | 'flush_timeout'
+  | 'write_not_saved'
   | 'error';
 
 export interface EditorFailure {
@@ -120,19 +120,40 @@ export function notAMember(roomId: string): EditorFailure {
   };
 }
 
-/** The write was made locally but could not be confirmed as sent. */
-export function flushTimeout(roomId: string): EditorFailure {
+/**
+ * The write was made locally but its delivery could not be confirmed: the
+ * homeserver kept failing (5xx, timeouts, network) until the retry budget ran
+ * out, so the change may or may not have been stored. Not an access problem —
+ * the assistant may write here.
+ */
+export function writeNotSaved(roomId: string, detail: string): EditorFailure {
   return {
     ok: false,
-    code: 'flush_timeout',
+    code: 'write_not_saved',
     roomId,
     message:
-      `The edit could not be confirmed as saved within the time limit — treat ` +
-      `it as NOT applied. Tell the user the document service is not responding ` +
-      `and they can retry shortly. Do not claim the edit succeeded.`,
+      `The edit could not be confirmed as saved — the document service did ` +
+      `not acknowledge it (${detail}), so it may or may not have landed. Do ` +
+      `not claim it succeeded. It can be retried: in a later request, read ` +
+      `the document first, then apply it again only if it is missing.`,
   };
 }
 
+/**
+ * The homeserver refused the write outright (an oversized change, a revoked
+ * token, a malformed request): nothing was stored, and sending the same
+ * change again fails the same way. Not an access problem in the room.
+ */
+export function writeRefused(roomId: string, detail: string): EditorFailure {
+  return editorError(
+    `The edit was NOT saved — the document service refused it (${detail}). ` +
+      `Nothing was stored. Do not claim it succeeded, and do not send the ` +
+      `same change again: if it was a large change, split it into smaller ` +
+      `edits.`,
+    roomId,
+  );
+}
+
 /**
  * Nothing to act on: no document is open and the call named no `room_id`.
  * Distinct from `not_a_member` — there is no room to be a member of yet.

package/src/plugins/editor/prompts.ts

@@ -42,7 +42,8 @@ Tool results carry a \`code\` you must act on:
 - \`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.
+- \`write_not_saved\` — the edit could **not** be confirmed as saved: the document service did not acknowledge it, so it may or may not have landed. Say so; do not claim it succeeded. Do not repeat it in this task — further edits in this task are refused too. In a later request, re-read the document first and apply the edit again only if it is missing.
+- \`error\` after an edit — the document service refused it outright (for example, the change was too large): nothing was stored. Say so; do not claim it succeeded, and never send the same change again unchanged — split a large change into smaller edits.
 
 Never present a refusal as a success, and never silently retry a refusal.`;