@ixo/oracle-runtime 0.0.1

package/dist/plugins/editor/editor-agent.d.ts

@@ -0,0 +1,47 @@
+import type { PluginSubAgent } from '../../plugin-api/types.js';
+import { type BlocknoteToolsConfig } from './blocknote-tools.js';
+import { type BlobStoreCapable, type UcanMintCapable } from './mint-invocation-tool.js';
+import type { AppConfig, MatrixRoomConfig } from './provider.js';
+type AppConfigOverrides = {
+    matrix?: Partial<AppConfig['matrix']>;
+    provider?: Partial<AppConfig['provider']>;
+    blocknote?: Partial<AppConfig['blocknote']>;
+};
+export type EditorAgentMode = 'edit' | 'readOnly';
+export interface CreateEditorSubAgentParams {
+    /** Matrix room ID (or `{ type: 'alias', value: '#alias:domain' }`). */
+    room: string | MatrixRoomConfig;
+    /** Read-only restricts the toolset to non-destructive reads. */
+    mode?: EditorAgentMode;
+    /** Blocknote tools config built once at plugin boot from validated env. */
+    toolsConfig: BlocknoteToolsConfig;
+    /** Optional per-call overrides — primarily for tests. */
+    configOverrides?: AppConfigOverrides;
+    /** Tool name surfaced to the main agent (default `Editor Agent`). */
+    name?: string;
+    /** Tool description surfaced to the main agent. */
+    description?: string;
+    /** Matrix user ID of the page owner — invited and given power level 50 on page creation. */
+    userMatrixId?: string;
+    /** Matrix space ID to nest new pages under. */
+    spaceId?: string;
+    /** When provided, registers `mint_invocation` on the editor agent so skills
+     * can sign UCAN invocations against external services without round-
+     * tripping the delegation CAR through the LLM. */
+    ucanService?: UcanMintCapable;
+    /** When provided alongside `ucanService`, the minted invocation is also
+     * stored in the blob store under a fresh blobId; the tool returns that
+     * blobId so the main agent can pass it to `sandbox_write_blob` instead of
+     * relaying the CAR through the LLM. */
+    blobStore?: BlobStoreCapable;
+    /** Owner of the blob — used as the cache namespace. */
+    userDid?: string;
+}
+/**
+ * Build the editor `PluginSubAgent` for the given room. The Matrix admin
+ * client (`EditorMatrixClient`) is a process-wide singleton bootstrapped on
+ * first call with the credentials carried in `toolsConfig`.
+ */
+export declare function createEditorSubAgent(params: CreateEditorSubAgentParams): Promise<PluginSubAgent>;
+export {};
+//# sourceMappingURL=editor-agent.d.ts.map

package/dist/plugins/editor/editor-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-agent.d.ts","sourceRoot":"","sources":["../../../src/plugins/editor/editor-agent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AASjE,KAAK,kBAAkB,GAAG;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1C,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;CAC7C,CAAC;AA+DF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAElD,MAAM,WAAW,0BAA0B;IACzC,uEAAuE;IACvE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,2EAA2E;IAC3E,WAAW,EAAE,oBAAoB,CAAC;IAClC,yDAAyD;IACzD,eAAe,CAAC,EAAE,kBAAkB,CAAC;IACrC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;sDAEkD;IAClD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;2CAGuC;IACvC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA6FD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,cAAc,CAAC,CAyFzB"}

package/dist/plugins/editor/editor-agent.js

@@ -0,0 +1,158 @@
+import { tool as pluginTool } from '../../plugin-api/tool-helper.js';
+import { createBlocknoteTools, } from './blocknote-tools.js';
+import { resolveEditorMatrixClient } from './editor-mx.js';
+import { createMintInvocationEditorTool, } from './mint-invocation-tool.js';
+import { createPageTools } from './page-tools.js';
+import { editorAgentPrompt, editorAgentReadOnlyPrompt } from './prompts.js';
+const normalizeRoom = (room) => {
+    if (typeof room === 'string') {
+        return { type: 'id', value: room };
+    }
+    return room;
+};
+const buildAppConfig = (base, room, overrides) => {
+    const merged = {
+        matrix: {
+            ...base.matrix,
+            room,
+        },
+        provider: { ...base.provider },
+        blocknote: { ...base.blocknote },
+    };
+    if (!overrides) {
+        return merged;
+    }
+    return {
+        matrix: {
+            ...merged.matrix,
+            ...overrides.matrix,
+            room: overrides.matrix?.room ?? merged.matrix.room,
+        },
+        provider: { ...merged.provider, ...overrides.provider },
+        blocknote: { ...merged.blocknote, ...overrides.blocknote },
+    };
+};
+const resolveStructuredTools = (mode, toolset) => {
+    if (mode === 'readOnly') {
+        return [
+            toolset.listBlocksTool,
+            toolset.readBlockByIdTool,
+            toolset.searchBlocksTool,
+            toolset.readFlowContextTool,
+            toolset.readFlowStatusTool,
+            toolset.readBlockHistoryTool,
+            toolset.readPermissionsTool,
+            toolset.readSurveyTool,
+            toolset.validateSurveyAnswersTool,
+        ];
+    }
+    const writableToolset = toolset;
+    if (!writableToolset.editBlockTool || !writableToolset.createBlockTool) {
+        throw new Error('Writable editor mode requires edit and create tools.');
+    }
+    return [
+        writableToolset.listBlocksTool,
+        writableToolset.editBlockTool,
+        writableToolset.createBlockTool,
+        writableToolset.deleteBlockTool,
+        writableToolset.readBlockByIdTool,
+        writableToolset.searchBlocksTool,
+        writableToolset.readFlowContextTool,
+        writableToolset.readFlowStatusTool,
+        writableToolset.readBlockHistoryTool,
+        writableToolset.readPermissionsTool,
+        writableToolset.readSurveyTool,
+        writableToolset.fillSurveyAnswersTool,
+        writableToolset.validateSurveyAnswersTool,
+        writableToolset.executeActionTool,
+        writableToolset.findAndReplaceTool,
+        writableToolset.moveBlockTool,
+        writableToolset.bulkEditBlocksTool,
+    ];
+};
+/**
+ * Adapt a LangChain `StructuredTool` into the runtime's `PluginTool` shape so
+ * it can flow through the plugin sub-agent assembly path. The handler simply
+ * delegates to the underlying tool's `invoke` — the inner tool keeps its
+ * strict argument validation; the wrapper exposes the same Zod schema verbatim.
+ */
+function wrapStructuredTool(t) {
+    // The inner tool already validates its own input shape; the wrapper just
+    // forwards the value through. LangChain's `StructuredTool.invoke` accepts
+    // the same `unknown` input at runtime — the wrapper's `args: unknown`
+    // contract matches the tool's runtime contract even though the static
+    // signature is narrower (`ToolInputSchemaBase`-derived).
+    return pluginTool(async (args) => {
+        return t.invoke(args);
+    }, {
+        name: t.name,
+        description: t.description ?? '',
+        schema: t.schema,
+    });
+}
+/**
+ * Build the editor `PluginSubAgent` for the given room. The Matrix admin
+ * client (`EditorMatrixClient`) is a process-wide singleton bootstrapped on
+ * first call with the credentials carried in `toolsConfig`.
+ */
+export async function createEditorSubAgent(params) {
+    const { room, mode = 'edit', toolsConfig, configOverrides, name = 'Editor Agent', description = 'AI Agent that reads and writes pages and blocks in the BlockNote editor.', userMatrixId, spaceId, ucanService, blobStore, userDid, } = params;
+    const roomConfig = normalizeRoom(room);
+    const matrixClient = await resolveEditorMatrixClient({
+        baseUrl: toolsConfig.matrix.baseUrl,
+        userId: toolsConfig.matrix.userId,
+        accessToken: toolsConfig.matrix.accessToken,
+        matrixClient: toolsConfig.matrixClient,
+    });
+    const appConfig = buildAppConfig(toolsConfig, roomConfig, configOverrides);
+    const blocknoteTools = (await createBlocknoteTools(matrixClient, appConfig, mode === 'readOnly'));
+    const structuredTools = resolveStructuredTools(mode, blocknoteTools);
+    const editorRoomId = roomConfig.type === 'id' ? roomConfig.value : undefined;
+    const pageTools = createPageTools({
+        matrixClient,
+        toolsConfig,
+        userMatrixId,
+        defaultSpaceId: spaceId,
+        defaultRoomId: editorRoomId,
+    });
+    structuredTools.push(pageTools.readPageTool);
+    if (mode === 'edit') {
+        structuredTools.push(pageTools.createPageTool);
+        structuredTools.push(pageTools.updatePageTool);
+    }
+    // mint_invocation lives on the editor (not the main agent) because the
+    // delegation CAR is read from the flow's Y.Doc by CID — only this closure
+    // has the matrixClient + roomId baked in. The main agent reaches it via
+    // call_editor_agent + the `forwardTools` list below.
+    if (ucanService && editorRoomId) {
+        structuredTools.push(createMintInvocationEditorTool({
+            matrixClient,
+            appConfig,
+            roomId: editorRoomId,
+            ucanService,
+            blobStore,
+            userDid,
+        }));
+    }
+    const tools = structuredTools.map(wrapStructuredTool);
+    return {
+        name,
+        description,
+        systemPrompt: mode === 'readOnly' ? editorAgentReadOnlyPrompt : editorAgentPrompt,
+        tools,
+        model: 'subagent',
+        middlewares: [],
+        // Bubble the page + block mutation events into the main chat so the FE
+        // renders artifact previews and edit confirmations inline. Names absent
+        // in the read-only toolset are simply nothing-to-forward. `mint_invocation`
+        // is forwarded so the main agent sees the returned `blobId` and can pass
+        // it straight to `sandbox_write_blob`.
+        forwardTools: [
+            'create_page',
+            'update_page',
+            'edit_block',
+            'create_block',
+            'mint_invocation',
+        ],
+    };
+}

package/dist/plugins/editor/editor-mx.d.ts

@@ -0,0 +1,56 @@
+import { type MatrixClient } from 'matrix-js-sdk';
+/** Matrix admin credentials needed to bootstrap the editor client. */
+export interface EditorMatrixClientConfig {
+    baseUrl: string;
+    userId: string;
+    accessToken: string;
+}
+/**
+ * Singleton wrapper around a `matrix-js-sdk` `MatrixClient`. Used by
+ * `@ixo/matrix-crdt` to read/write BlockNote Y.js documents.
+ *
+ * No `startClient()` / sync is performed — matrix-crdt's `MatrixReader`
+ * explicitly tells consumers NOT to use the Sync API and polls the
+ * `/events` endpoint itself. Initialization here is just `createClient`,
+ * which is synchronous-ish (a few ms).
+ */
+export declare class EditorMatrixClient {
+    private static instance;
+    private readonly cfg;
+    private matrixClient;
+    private isInitialized;
+    private initializationPromise;
+    private readonly logger;
+    private constructor();
+    /**
+     * Get the singleton instance. First caller supplies the Matrix admin
+     * config used for the lifetime of the process; subsequent callers
+     * receive the same instance and the config argument is ignored.
+     */
+    static getInstance(cfg: EditorMatrixClientConfig): EditorMatrixClient;
+    /**
+     * Test-only — reset the singleton so tests can swap the underlying client.
+     */
+    static resetForTesting(): void;
+    /**
+     * Build the underlying `matrix-js-sdk` client. Idempotent — safe to call
+     * concurrently; only the first call does work.
+     */
+    init(): Promise<void>;
+    private performInitialization;
+    getClient(): MatrixClient;
+    isReady(): boolean;
+    waitUntilReady(): Promise<void>;
+}
+/**
+ * Resolve the `MatrixClient` used by editor tools. Prefers the
+ * `matrixClient` from the plugin's runtime config (host-provided DI);
+ * otherwise lazily constructs the internal singleton.
+ *
+ * Centralised so every call site (editor-agent, apply-sandbox-output,
+ * standalone-editor-tool) goes through one resolution path.
+ */
+export declare function resolveEditorMatrixClient(cfg: EditorMatrixClientConfig & {
+    matrixClient?: MatrixClient;
+}): Promise<MatrixClient>;
+//# sourceMappingURL=editor-mx.d.ts.map

package/dist/plugins/editor/editor-mx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-mx.d.ts","sourceRoot":"","sources":["../../../src/plugins/editor/editor-mx.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAEhE,sEAAsE;AACtE,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAE1D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA2B;IAC/C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,qBAAqB,CAA8B;IAE3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAE3D,OAAO;IAIP;;;;OAIG;WACW,WAAW,CAAC,GAAG,EAAE,wBAAwB,GAAG,kBAAkB;IAO5E;;OAEG;WACW,eAAe,IAAI,IAAI;IAIrC;;;OAGG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAYpB,qBAAqB;IAmB5B,SAAS,IAAI,YAAY;IASzB,OAAO,IAAI,OAAO;IAIZ,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7C;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,wBAAwB,GAAG;IAAE,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,GAC9D,OAAO,CAAC,YAAY,CAAC,CAKvB"}

package/dist/plugins/editor/editor-mx.js

@@ -0,0 +1,100 @@
+import { Logger } from '@nestjs/common';
+import { createClient } from 'matrix-js-sdk';
+/**
+ * Singleton wrapper around a `matrix-js-sdk` `MatrixClient`. Used by
+ * `@ixo/matrix-crdt` to read/write BlockNote Y.js documents.
+ *
+ * No `startClient()` / sync is performed — matrix-crdt's `MatrixReader`
+ * explicitly tells consumers NOT to use the Sync API and polls the
+ * `/events` endpoint itself. Initialization here is just `createClient`,
+ * which is synchronous-ish (a few ms).
+ */
+export class EditorMatrixClient {
+    static instance = null;
+    cfg;
+    matrixClient = null;
+    isInitialized = false;
+    initializationPromise = null;
+    logger = new Logger('EditorMatrixClient');
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /**
+     * Get the singleton instance. First caller supplies the Matrix admin
+     * config used for the lifetime of the process; subsequent callers
+     * receive the same instance and the config argument is ignored.
+     */
+    static getInstance(cfg) {
+        if (!EditorMatrixClient.instance) {
+            EditorMatrixClient.instance = new EditorMatrixClient(cfg);
+        }
+        return EditorMatrixClient.instance;
+    }
+    /**
+     * Test-only — reset the singleton so tests can swap the underlying client.
+     */
+    static resetForTesting() {
+        EditorMatrixClient.instance = null;
+    }
+    /**
+     * Build the underlying `matrix-js-sdk` client. Idempotent — safe to call
+     * concurrently; only the first call does work.
+     */
+    async init() {
+        if (this.isInitialized && this.matrixClient)
+            return;
+        if (this.initializationPromise)
+            return this.initializationPromise;
+        this.initializationPromise = this.performInitialization();
+        try {
+            await this.initializationPromise;
+        }
+        finally {
+            this.initializationPromise = null;
+        }
+    }
+    async performInitialization() {
+        const { baseUrl, userId, accessToken } = this.cfg;
+        if (!baseUrl || !userId || !accessToken) {
+            throw new Error('Missing Matrix configuration. Editor plugin requires MATRIX_BASE_URL, MATRIX_ORACLE_ADMIN_USER_ID, MATRIX_ORACLE_ADMIN_ACCESS_TOKEN.');
+        }
+        this.matrixClient = createClient({
+            baseUrl,
+            accessToken,
+            userId,
+            timelineSupport: true,
+            fetchFn: fetch,
+        });
+        this.isInitialized = true;
+        this.logger.log('EditorMatrixClient ready (no sync, polling-only mode)');
+    }
+    getClient() {
+        if (!this.isInitialized || !this.matrixClient) {
+            throw new Error('EditorMatrixClient not initialized. Call await init() first.');
+        }
+        return this.matrixClient;
+    }
+    isReady() {
+        return this.isInitialized && this.matrixClient !== null;
+    }
+    async waitUntilReady() {
+        if (this.isReady())
+            return;
+        await this.init();
+    }
+}
+/**
+ * Resolve the `MatrixClient` used by editor tools. Prefers the
+ * `matrixClient` from the plugin's runtime config (host-provided DI);
+ * otherwise lazily constructs the internal singleton.
+ *
+ * Centralised so every call site (editor-agent, apply-sandbox-output,
+ * standalone-editor-tool) goes through one resolution path.
+ */
+export async function resolveEditorMatrixClient(cfg) {
+    if (cfg.matrixClient)
+        return cfg.matrixClient;
+    const inst = EditorMatrixClient.getInstance(cfg);
+    await inst.init();
+    return inst.getClient();
+}

package/dist/plugins/editor/editor.plugin.d.ts

@@ -0,0 +1,32 @@
+import type { MatrixClient } from 'matrix-js-sdk';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { PluginManifest, PluginSubAgent, PluginTool, RuntimeContext } from '../../plugin-api/types.js';
+/**
+ * Constructor options for `EditorPlugin`. Pass `matrixClient` when the host
+ * app already owns a long-lived matrix-js-sdk client — every editor tool
+ * will reuse it instead of constructing the internal singleton.
+ */
+export interface EditorPluginOptions {
+    matrixClient?: MatrixClient;
+}
+/**
+ * Editor plugin. Behaviour by state:
+ *
+ *   - `state.editorRoomId` set → editor sub-agent (`call_editor_agent`)
+ *     bound to that room; plus `apply_sandbox_output_to_block` when the
+ *     sandbox plugin is also loaded.
+ *   - `state.spaceId` set without `editorRoomId` → standalone
+ *     `call_editor_agent` tool that accepts a `room_id` argument per call.
+ *   - neither set → no contributions; the agent has no editor surface.
+ */
+export declare class EditorPlugin extends OraclePlugin {
+    static readonly NAME = "editor";
+    readonly name = "editor";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    private readonly matrixClient?;
+    constructor(options?: EditorPluginOptions);
+    getRequestSubAgents(rtCtx: RuntimeContext): Promise<PluginSubAgent[]>;
+    getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]>;
+}
+//# sourceMappingURL=editor.plugin.d.ts.map

package/dist/plugins/editor/editor.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/editor/editor.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,cAAc,EACf,MAAM,2BAA2B,CAAC;AAUnC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AA2FD;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC5C,MAAM,CAAC,QAAQ,CAAC,IAAI,YAAY;IAEhC,QAAQ,CAAC,IAAI,YAAqB;IAElC,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,iBAAY;IAK7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;gBAEjC,OAAO,GAAE,mBAAwB;IAK9B,mBAAmB,CAChC,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,cAAc,EAAE,CAAC;IAwCb,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CAyD7E"}

package/dist/plugins/editor/editor.plugin.js

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import { isUserInRoom } from '../../matrix/room-membership.js';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import { SandboxPlugin } from '../sandbox/index.js';
+import { createApplySandboxOutputTool } from './apply-sandbox-output.js';
+import { buildBlocknoteToolsConfig, } from './blocknote-tools.js';
+import { createEditorSubAgent } from './editor-agent.js';
+import { createStandaloneEditorTool } from './standalone-editor-tool.js';
+/**
+ * Internal parse schema for `parseToolsConfig`. These 3 env vars already
+ * live in the runtime's core base env schema — re-declaring them via
+ * `OraclePlugin.configSchema` would make schema-composer warn about
+ * duplicate ownership ("editor wins") on every boot. Keep this schema
+ * LOCAL: used to extract typed values from the already-validated
+ * `ctx.config`, but NOT exposed as the plugin's public configSchema.
+ */
+const matrixConfigSchema = z.object({
+    MATRIX_BASE_URL: z.string(),
+    MATRIX_ORACLE_ADMIN_USER_ID: z.string(),
+    MATRIX_ORACLE_ADMIN_ACCESS_TOKEN: z.string(),
+});
+const siblingEnvSchema = z.object({
+    SANDBOX_MCP_URL: z.url().optional(),
+    SKILLS_CAPSULES_BASE_URL: z.url().optional(),
+    ORACLE_SECRETS: z.string().optional(),
+});
+const manifest = {
+    title: 'Editor',
+    summary: "Reads and edits BlockNote pages — collaborative documents in the user's workspace.",
+    whenToUse: [
+        'User asks to read, summarize, or edit a page in their workspace.',
+        'User wants to update specific blocks (status, properties, content) on a page.',
+        'User wants to create a new page or update an existing one.',
+        'A skill produced output (URLs, credentials, status values) that should land on specific blocks.',
+    ],
+    whenNotToUse: [
+        'IXO entity lookups (use Domain Indexer) — pages are documents, not entities.',
+        'Web search or scraping (use Firecrawl).',
+        'Long-term user memory (use Memory).',
+    ],
+    examples: [
+        {
+            user: 'Summarize the current page.',
+            thought: 'Delegate to the Editor sub-agent with the active room. It will read the page and return a summary.',
+            tool: 'call_editor_agent',
+        },
+        {
+            user: 'Set the status block to completed.',
+            thought: 'Page edit — delegate with explicit block target + new value. Never paraphrase block IDs or status names.',
+            tool: 'call_editor_agent',
+        },
+    ],
+    tags: ['editor', 'blocknote', 'pages', 'documents'],
+    category: 'data',
+    visibility: 'on-demand',
+    stability: 'stable',
+};
+function parseToolsConfig(cfg, matrixClient) {
+    const parsed = matrixConfigSchema.parse(cfg);
+    return {
+        ...buildBlocknoteToolsConfig({
+            baseUrl: parsed.MATRIX_BASE_URL,
+            userId: parsed.MATRIX_ORACLE_ADMIN_USER_ID,
+            accessToken: parsed.MATRIX_ORACLE_ADMIN_ACCESS_TOKEN,
+        }),
+        matrixClient,
+    };
+}
+function readEditorRoomId(rtCtx) {
+    const value = rtCtx.history.state.editorRoomId;
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readSpaceId(rtCtx) {
+    const value = rtCtx.history.state.spaceId;
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function buildUserMatrixId(rtCtx) {
+    // Mirrors today's apps/app pattern: derive `@did-ixo-...:homeserver` from
+    // the canonical user DID + base URL when no explicit Matrix ID is wired in.
+    const did = rtCtx.user.did;
+    if (!did)
+        return undefined;
+    const matrixId = rtCtx.user.matrixUserId;
+    return matrixId || undefined;
+}
+/**
+ * Editor plugin. Behaviour by state:
+ *
+ *   - `state.editorRoomId` set → editor sub-agent (`call_editor_agent`)
+ *     bound to that room; plus `apply_sandbox_output_to_block` when the
+ *     sandbox plugin is also loaded.
+ *   - `state.spaceId` set without `editorRoomId` → standalone
+ *     `call_editor_agent` tool that accepts a `room_id` argument per call.
+ *   - neither set → no contributions; the agent has no editor surface.
+ */
+export class EditorPlugin extends OraclePlugin {
+    static NAME = 'editor';
+    name = EditorPlugin.NAME;
+    version = '1.0.0';
+    manifest = manifest;
+    // Intentionally no `configSchema` — the matrix env vars editor needs are
+    // owned by the core base env schema. See `matrixConfigSchema` above.
+    matrixClient;
+    constructor(options = {}) {
+        super();
+        this.matrixClient = options.matrixClient;
+    }
+    async getRequestSubAgents(rtCtx) {
+        const editorRoomId = readEditorRoomId(rtCtx);
+        if (!editorRoomId)
+            return [];
+        // The editor operates on `editorRoomId` with the oracle's admin Matrix
+        // identity. `editorRoomId` came from the request, so verify the
+        // authenticated user is actually a member of that room before binding the
+        // sub-agent to it — otherwise a user could read/edit any room id they pass.
+        if (!(await isUserInRoom(editorRoomId, rtCtx.user.matrixUserId))) {
+            rtCtx.logger.warn(`[editor] user ${rtCtx.user.did} is not a member of room ${editorRoomId} — refusing to bind editor sub-agent`);
+            return [];
+        }
+        const toolsConfig = parseToolsConfig(rtCtx.config, this.matrixClient);
+        try {
+            const subAgent = await createEditorSubAgent({
+                room: editorRoomId,
+                mode: 'edit',
+                toolsConfig,
+                userMatrixId: buildUserMatrixId(rtCtx),
+                spaceId: readSpaceId(rtCtx),
+                // Gate mint_invocation on whether the oracle has a signing key. Without
+                // one, the tool can't mint anything — better to omit it than register
+                // a tool that returns "Oracle has no UCAN signing key configured" on
+                // every call.
+                ucanService: rtCtx.ucan.hasSigningKey() ? rtCtx.ucan : undefined,
+                blobStore: rtCtx.blobStore,
+                userDid: rtCtx.user.did,
+            });
+            return [subAgent];
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            rtCtx.logger.error(`[editor] failed to build sub-agent: ${detail}`);
+            return [];
+        }
+    }
+    async getRequestTools(rtCtx) {
+        const tools = [];
+        const editorRoomId = readEditorRoomId(rtCtx);
+        const spaceId = readSpaceId(rtCtx);
+        if (!editorRoomId && !spaceId) {
+            return tools;
+        }
+        const toolsConfig = parseToolsConfig(rtCtx.config, this.matrixClient);
+        // Standalone editor tool — only when a space is in scope but no specific
+        // editor session is active. The agent supplies `room_id` per call.
+        if (!editorRoomId && spaceId) {
+            tools.push(createStandaloneEditorTool({
+                toolsConfig,
+                spaceId,
+                userMatrixId: buildUserMatrixId(rtCtx),
+            }));
+        }
+        // apply_sandbox_output_to_block — only with both an editor session AND
+        // a loaded sandbox plugin (it brokers UCAN headers for the MCP call).
+        // Same room-ownership guard as the sub-agent path: the tool writes to
+        // `editorRoomId` with the admin identity, so the requesting user must be
+        // a member of it.
+        if (editorRoomId &&
+            rtCtx.availablePlugins.has(SandboxPlugin.NAME) &&
+            (await isUserInRoom(editorRoomId, rtCtx.user.matrixUserId))) {
+            const siblings = siblingEnvSchema.safeParse(rtCtx.config);
+            const sandboxMcpUrl = siblings.success
+                ? siblings.data.SANDBOX_MCP_URL
+                : undefined;
+            if (sandboxMcpUrl) {
+                tools.push(createApplySandboxOutputTool({
+                    sandboxMcpUrl,
+                    skillsServiceUrl: siblings.success
+                        ? siblings.data.SKILLS_CAPSULES_BASE_URL
+                        : undefined,
+                    oracleSecretsRaw: siblings.success
+                        ? (siblings.data.ORACLE_SECRETS ?? '')
+                        : '',
+                    toolsConfig,
+                    editorRoomId,
+                }));
+            }
+        }
+        return tools;
+    }
+}

package/dist/plugins/editor/index.d.ts

@@ -0,0 +1,6 @@
+export { EditorPlugin } from './editor.plugin.js';
+export { createEditorSubAgent, type CreateEditorSubAgentParams, type EditorAgentMode, } from './editor-agent.js';
+export { createStandaloneEditorTool } from './standalone-editor-tool.js';
+export { createApplySandboxOutputTool } from './apply-sandbox-output.js';
+export { buildBlocknoteToolsConfig, type BlocknoteToolsConfig, type BlocknoteToolsMatrixConfig, } from './blocknote-tools.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/editor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/editor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,oBAAoB,EACpB,KAAK,0BAA0B,EAC/B,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EACL,yBAAyB,EACzB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,GAChC,MAAM,sBAAsB,CAAC"}

package/dist/plugins/editor/index.js

@@ -0,0 +1,5 @@
+export { EditorPlugin } from './editor.plugin.js';
+export { createEditorSubAgent, } from './editor-agent.js';
+export { createStandaloneEditorTool } from './standalone-editor-tool.js';
+export { createApplySandboxOutputTool } from './apply-sandbox-output.js';
+export { buildBlocknoteToolsConfig, } from './blocknote-tools.js';