editor

Read and edit BlockNote pages in the user's workspace over Matrix. Covers the tools and sub-agent the plugin adds, the env vars it reads and its Matrix client.

The editor plugin lets the agent read and edit BlockNote pages, the collaborative documents in the user's workspace. It is on by default, and it contributes tools only on a request that names an editor room or a space.

Source: packages/oracle-runtime/src/plugins/editor/

AttributeValue
Feature keyeditor
Visibilityalways
Stabilitystable
Categorydata
Default stateOn
Depends onNone

Summary

Reads and edits BlockNote pages, the collaborative documents in the user's workspace, via Matrix CRDT. Behaviour depends on per-request state:

  • state.editorRoomId set → editor sub-agent (call_editor_agent) bound to that room; plus apply_sandbox_output_to_block when sandbox 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.

Environment variables

The plugin owns no env vars. It reads the following from the core base env schema:

VarRequiredDescription
MATRIX_BASE_URLyes (base schema)Matrix homeserver base URL.
MATRIX_ORACLE_ADMIN_USER_IDyes (base schema)Admin Matrix user ID.
MATRIX_ORACLE_ADMIN_ACCESS_TOKENyes (base schema)Admin Matrix access token.
SANDBOX_MCP_URLnoRead when apply_sandbox_output_to_block is constructed.
SKILLS_CAPSULES_BASE_URLnoRead when apply_sandbox_output_to_block is constructed.
ORACLE_SECRETSnoRead when apply_sandbox_output_to_block is constructed.

What it contributes

  • Tools: apply_sandbox_output_to_block (when an editor room + sandbox plugin are both available); standalone call_editor_agent (when only a spaceId is in scope). On the Workers runtime from 0.39.0 the manifest sets routable: false: an open document loads the plugin by itself, so the capability router never preloads it.
  • Sub-agents: call_editor_agent, built only when state.editorRoomId is set.
  • Middleware: none.
  • HTTP routes: none.
  • Shared state: none.

Matrix client (optional)

The bundled editorPlugin is fully functional from env. When no matrixClient is passed, the plugin lazily builds an internal Matrix client from the MATRIX_* admin env vars (MATRIX_BASE_URL, MATRIX_ORACLE_ADMIN_USER_ID, MATRIX_ORACLE_ADMIN_ACCESS_TOKEN). So you do not need to construct it explicitly for production.

Pass a matrixClient only as a reuse optimization, when your app already keeps a long-lived matrix-js-sdk client synced and you want the editor tools to share it:

import { createOracleApp, EditorPlugin } from '@ixo/oracle-runtime';
import * as sdk from 'matrix-js-sdk';

const matrixClient = sdk.createClient({ /* … */ });

const app = await createOracleApp({
  config,
  plugins: [new EditorPlugin({ matrixClient })], // optional — env fallback otherwise
});

Opt out / opt in

const app = await createOracleApp({
  config,
  features: { editor: false }, // never load
  // features: { editor: true }, // force load (default)
});

When to use it

  • User asks to read, summarise, 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.

When not to use it

  • IXO domain lookups. Use domain-indexer. Pages are documents, not domains.
  • Web search or scraping. Use firecrawl.
  • Long-term user memory. Use memory.