@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/plugins/editor/standalone-editor-tool.ts

@@ -18,7 +18,12 @@ import { z } from 'zod';
 
 import { filterForwardedMessages } from '../../core/subagent-as-tool';
 import { tool as pluginTool } from '../../plugin-api/tool-helper';
+import {
+  canAccessToolPlane,
+  requireToolPlane,
+} from '../../plugin-api/tool-plane';
 import type { PluginTool, RuntimeContext } from '../../plugin-api/types';
+import { sharedDocumentSource, type DocumentOpener } from './content-session';
 import { createContentTools } from './content-tools';
 import { buildAppConfig, EDITOR_AGENT_TOOL_NAME } from './editor-agent';
 import type { BlocknoteToolsConfig } from './editor-config';
@@ -84,23 +89,42 @@ function lastMessageContent(messages: BaseMessage[]): string {
 export interface CreateStandaloneEditorToolOptions {
   /** Editor config built when the plugin's request tools are resolved. */
   toolsConfig: BlocknoteToolsConfig;
+  /** The contributing plugin: names an admin content tool's capability. */
+  pluginName: string;
+  /**
+   * Opens the target document. Defaults to the matrix-crdt opener; tests
+   * pass an in-memory one.
+   */
+  openDocument?: DocumentOpener;
 }
 
 /**
  * Bridge the content `PluginTool`s into LangChain tools for the inner agent,
  * reusing the outer request's `RuntimeContext` rather than rebuilding one.
+ * The handlers are called here, not through `wrapPluginTool`, so the plane
+ * check it applies is applied here too: an admin content tool the user's
+ * delegation does not grant is not bound, and the call re-checks it.
  */
 function toStructuredTools(
   tools: PluginTool[],
   ctx: RuntimeContext,
+  pluginName: string,
 ): StructuredTool[] {
-  return tools.map((t) =>
-    lcTool(async (args) => t.handler(args, ctx), {
-      name: t.name,
-      description: t.description,
-      schema: t.schema,
-    }),
-  );
+  return tools
+    .filter((t) => canAccessToolPlane(ctx, pluginName, t))
+    .map((t) =>
+      lcTool(
+        async (args) => {
+          requireToolPlane(ctx, pluginName, t);
+          return t.handler(args, ctx);
+        },
+        {
+          name: t.name,
+          description: t.description,
+          schema: t.schema,
+        },
+      ),
+    );
 }
 
 /** The document the client reports as open, when there is one. */
@@ -130,6 +154,7 @@ export function createStandaloneEditorTool(
         return JSON.stringify(notAMember(roomId));
       }
 
+      let documents: ReturnType<typeof sharedDocumentSource> | undefined;
       try {
         const matrixClient = await resolveEditorMatrixClient({
           baseUrl: opts.toolsConfig.matrix.baseUrl,
@@ -138,14 +163,24 @@ export function createStandaloneEditorTool(
           matrixClient: opts.toolsConfig.matrixClient,
         });
 
-        const contentTools = createContentTools({
-          matrixClient,
-          appConfig: buildAppConfig(opts.toolsConfig, {
-            type: 'id',
-            value: roomId,
-          }),
-        });
-        const boundTools = toStructuredTools(contentTools, ctx);
+        // One session for the whole run: the room cannot change identity
+        // within a call, so every content tool reuses the same open doc.
+        documents = sharedDocumentSource(
+          {
+            matrixClient,
+            appConfig: buildAppConfig(opts.toolsConfig, {
+              type: 'id',
+              value: roomId,
+            }),
+          },
+          opts.openDocument,
+        );
+        const contentTools = createContentTools({ documents });
+        const boundTools = toStructuredTools(
+          contentTools,
+          ctx,
+          opts.pluginName,
+        );
 
         const agent = createAgent({
           model: ctx.llm.get('subagent'),
@@ -154,9 +189,12 @@ export function createStandaloneEditorTool(
           middleware: [],
         });
 
-        const result = await agent.invoke({
-          messages: [new HumanMessage(task)],
-        });
+        // The turn's signal stops the inner agent's model calls and document
+        // writes when the user cancels or the turn times out.
+        const result = await agent.invoke(
+          { messages: [new HumanMessage(task)] },
+          { signal: ctx.abortSignal },
+        );
         const messages = result.messages as BaseMessage[];
         const text = lastMessageContent(messages);
 
@@ -184,11 +222,16 @@ export function createStandaloneEditorTool(
           },
         });
       } catch (err) {
+        // A cancelled turn is not a document error: let the cancellation
+        // propagate.
+        if (ctx.abortSignal.aborted) throw err;
         const message = err instanceof Error ? err.message : String(err);
         ctx.logger.error(
           `[editor] standalone failed for ${roomId}: ${message}`,
         );
         return `Error opening the document ${roomId}: ${message}`;
+      } finally {
+        await documents?.close();
       }
     },
     {

package/src/plugins/firecrawl/firecrawl-tools.ts

@@ -1,7 +1,11 @@
 import { MultiServerMCPClient } from '@langchain/mcp-adapters';
 import { withCallTimeout } from '../mcp-call-timeout';
+import { adaptMcpClientTools } from '../mcp-tool-adapter';
 
-/** Our own per-call limit (never given to the SDK — see `mcp-call-timeout.ts`). */
+/**
+ * Per-call limit: the MCP request's own timeout (`metadata.timeoutMs`, see
+ * `mcp-tool-adapter.ts`), also enforced by {@link withCallTimeout}.
+ */
 const FIRECRAWL_TOOL_TIMEOUT_MS = 120_000;
 import { z } from 'zod';
 import { tool } from '../../plugin-api/tool-helper';
@@ -112,10 +116,14 @@ export function createDefaultFirecrawlMcpFactory(
     try {
       const all = await client.getTools();
       return await run(
-        all.filter(
-          (t) =>
-            t.name === FIRECRAWL_SCRAPE_MCP_NAME ||
-            t.name === FIRECRAWL_SEARCH_MCP_NAME,
+        adaptMcpClientTools(
+          all.filter(
+            (t) =>
+              t.name === FIRECRAWL_SCRAPE_MCP_NAME ||
+              t.name === FIRECRAWL_SEARCH_MCP_NAME,
+          ),
+          console,
+          { requestTimeoutMs: FIRECRAWL_TOOL_TIMEOUT_MS },
         ),
       );
     } finally {

package/src/plugins/flows/action-metadata.ts

@@ -16,8 +16,10 @@
  *     `describe_action`) and are not derivable from the registry.
  *
  * `requires` captures human/environment prerequisites the user must supply (a
- * claim collection, a template id, a connected account, a PIN) — the things the
- * agent must STOP and ASK the user for rather than invent. The multi-operation
+ * claim collection, a template id, a connected account) — the things the
+ * agent must STOP and ASK the user for rather than invent. A PIN is the
+ * exception: it is listed so the agent knows the step needs one, but the
+ * portal collects it at run time ({@link PIN_AT_RUN_TIME}). The multi-operation
  * actions (`qi/collection.lifecycle`, `qi/collection.users`) dispatch on an
  * `operation` input; their `inputPorts` note which fields apply to which op.
  *
@@ -30,6 +32,12 @@ export interface ActionPort {
   portType: string;
   /** True when the action's `run()` throws if this field is missing. */
   required?: boolean;
+  /**
+   * The value is a credential (PIN, mnemonic, password, token, API key). It
+   * is never stored in a flow document — every room member can read it — so
+   * an input with this name only accepts a `{{step.output.field}}` reference.
+   */
+  secret?: boolean;
   /** One-line, agent-facing description of what to put here. */
   description?: string;
 }
@@ -55,6 +63,13 @@ export interface OverlayEntry {
  * NOT listed here — they come from the registry's `outputSchema` (actions.ts
  * outputFields). Covers every registered action type.
  */
+/**
+ * How every PIN prerequisite is described: the portal collects the PIN when
+ * the user runs the step, so the agent never asks for one and never stores one.
+ */
+const PIN_AT_RUN_TIME =
+  'Collected by the portal when the user runs the step — never ask for it in chat and never write it into the flow.';
+
 export const ACTION_METADATA: Record<string, OverlayEntry> = {
   // ── Claims & bids ─────────────────────────────────────────────────────────
   'qi/claim.submit': {
@@ -93,6 +108,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'pin',
         portType: 'string',
+        secret: true,
         required: false,
         description:
           'Verification PIN; if omitted the action requests it from the user at runtime.',
@@ -413,7 +429,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'collectionId',
         portType: 'claimCollectionId',
-        required: true,
+        required: false,
         description:
           'Target collection — required for every op EXCEPT create (which mints a new one).',
       },
@@ -903,6 +919,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'mnemonic',
         portType: 'mnemonic',
+        secret: true,
         required: true,
         description:
           'Wallet mnemonic used to sign the IID creation. Typically wired from an upstream wallet step output (mnemonic).',
@@ -946,6 +963,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'mnemonic',
         portType: 'mnemonic',
+        secret: true,
         required: true,
         description:
           'Wallet mnemonic used to create the IID document and Matrix account. Typically wired from an upstream wallet step output (mnemonic).',
@@ -974,6 +992,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'pin',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'PIN used to register the Matrix account.',
       },
@@ -999,7 +1018,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
     requires: [
       {
         kind: 'pin',
-        description: 'A PIN is required to register the Matrix account.',
+        description: `A PIN is required to register the Matrix account. ${PIN_AT_RUN_TIME}`,
       },
       {
         kind: 'oracleName',
@@ -1022,6 +1041,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'mnemonic',
         portType: 'mnemonic',
+        secret: true,
         required: true,
         description:
           'Wallet mnemonic used to register the Matrix account. Typically wired from an upstream wallet step output (mnemonic).',
@@ -1043,6 +1063,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'pin',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'PIN used to register the Matrix account.',
       },
@@ -1061,7 +1082,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
     requires: [
       {
         kind: 'pin',
-        description: 'A PIN is required to register the Matrix account.',
+        description: `A PIN is required to register the Matrix account. ${PIN_AT_RUN_TIME}`,
       },
       {
         kind: 'oracleName',
@@ -1082,6 +1103,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'mnemonic',
         portType: 'mnemonic',
+        secret: true,
         required: true,
         description:
           'Oracle wallet BIP39 mnemonic, typically from the wallet.generate output.',
@@ -1109,6 +1131,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'pin',
         portType: 'string',
+        secret: true,
         required: true,
         description:
           'PIN used to sign the entity creation; typically from the form output.',
@@ -1116,6 +1139,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'matrixAccessToken',
         portType: 'string',
+        secret: true,
         required: true,
         description:
           'Oracle Matrix access token, typically from the matrix.register output.',
@@ -1215,7 +1239,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       },
       {
         kind: 'pin',
-        description: 'A PIN used to sign the entity creation — ask the user.',
+        description: `A PIN used to sign the entity creation. ${PIN_AT_RUN_TIME}`,
       },
     ],
   },
@@ -1301,12 +1325,14 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'matrixPassword',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'Matrix password, from the matrix.register output.',
       },
       {
         path: 'mnemonic',
         portType: 'mnemonic',
+        secret: true,
         required: true,
         description:
           'Oracle wallet mnemonic, from the wallet.generate output; stored as SECP_MNEMONIC secret.',
@@ -1314,12 +1340,14 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'matrixRecoveryPhrase',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'Matrix recovery phrase, from the matrix.register output.',
       },
       {
         path: 'pin',
         portType: 'string',
+        secret: true,
         required: true,
         description:
           'PIN, from the form output; stored as MATRIX_VALUE_PIN secret.',
@@ -1346,6 +1374,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'openRouterApiKeyPlaintext',
         portType: 'string',
+        secret: true,
         description:
           'Optional plaintext OpenRouter API key passed through to the deploy output.',
       },
@@ -1448,7 +1477,10 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
         description:
           'An OpenRouter API key, JWE-encrypted before submit (openRouterApiKeyJwe) — ask the user.',
       },
-      { kind: 'pin', description: 'A PIN stored as a secret — ask the user.' },
+      {
+        kind: 'pin',
+        description: `A PIN stored as a secret. ${PIN_AT_RUN_TIME}`,
+      },
     ],
   },
   'qi/oracle.storeSecrets': {
@@ -1499,12 +1531,14 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'matrixPassword',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'Matrix password, from the matrix.register output.',
       },
       {
         path: 'mnemonic',
         portType: 'mnemonic',
+        secret: true,
         required: true,
         description:
           'Oracle wallet mnemonic, from the wallet.generate output; stored as SECP_MNEMONIC.',
@@ -1512,12 +1546,14 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'matrixRecoveryPhrase',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'Matrix recovery phrase, from the matrix.register output.',
       },
       {
         path: 'pin',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'PIN, from the form output; stored as MATRIX_VALUE_PIN.',
       },
@@ -1541,7 +1577,10 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
         description:
           'An OpenRouter API key, JWE-encrypted before submit (openRouterApiKeyJwe) — ask the user.',
       },
-      { kind: 'pin', description: 'A PIN stored as a secret — ask the user.' },
+      {
+        kind: 'pin',
+        description: `A PIN stored as a secret. ${PIN_AT_RUN_TIME}`,
+      },
     ],
   },
   'qi/oracle.storeConfig': {
@@ -1704,12 +1743,14 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'matrixPassword',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'Matrix password, from the matrix.register output.',
       },
       {
         path: 'mnemonic',
         portType: 'mnemonic',
+        secret: true,
         required: true,
         description:
           'Oracle wallet mnemonic, from the wallet.generate output; stored as SECP_MNEMONIC.',
@@ -1717,12 +1758,14 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'matrixRecoveryPhrase',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'Matrix recovery phrase, from the matrix.register output.',
       },
       {
         path: 'pin',
         portType: 'string',
+        secret: true,
         required: true,
         description: 'PIN, from the form output; stored as MATRIX_VALUE_PIN.',
       },
@@ -1838,7 +1881,10 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
         description:
           'An OpenRouter API key, JWE-encrypted before submit (openRouterApiKeyJwe) — ask the user.',
       },
-      { kind: 'pin', description: 'A PIN stored as a secret — ask the user.' },
+      {
+        kind: 'pin',
+        description: `A PIN stored as a secret. ${PIN_AT_RUN_TIME}`,
+      },
     ],
   },
   'qi/oracle.deploy': {
@@ -1880,6 +1926,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'secrets',
         portType: 'object',
+        secret: true,
         description: 'Optional map of secret name to value passed to deploy.',
       },
     ],
@@ -1917,6 +1964,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'secrets',
         portType: 'object',
+        secret: true,
         description:
           'Optional map of secret name to value passed to deploy setup.',
       },
@@ -1955,6 +2003,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'secrets',
         portType: 'object',
+        secret: true,
         description:
           'Optional map of secret name to value passed to deploy start.',
       },
@@ -1997,7 +2046,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'userMessage',
         portType: 'string',
-        required: true,
+        required: false,
         description:
           'User-provided purpose text used to query the Domain Indexer (run() throws if both this and purposeDescription are empty).',
       },
@@ -2066,7 +2115,7 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       {
         path: 'selectedEntityDid',
         portType: 'did',
-        required: true,
+        required: false,
         description:
           'DID of the parent entity; required when not skipping (run() throws if absent and skipped is falsy).',
       },
@@ -3502,4 +3551,55 @@ export const ACTION_METADATA: Record<string, OverlayEntry> = {
       },
     ],
   },
+
+  // ── DAO governance proposals ─────────────────────────────────────────────
+  // The registry ships these three without an input schema, so their inputs
+  // are unknown here. Summaries and requirements state only what the action
+  // manifest declares: a side effect, confirmation by default, a
+  // `flow/block/execute` capability, and the output fields.
+  'qi/governance.member-proposal': {
+    summary:
+      'Creates a DAO governance proposal that changes membership (the operation output is add, remove or update-weight). Side effect; asks for confirmation by default. Outputs the proposal id, status, proposal contract address, DAO core address, operation and creation time.',
+    whenToUse: [
+      'A flow needs to put a DAO membership change (add, remove or re-weight a member) to a governance proposal.',
+    ],
+    tags: ['governance', 'proposals', 'dao'],
+    requires: [
+      {
+        kind: 'inputsUndeclared',
+        description:
+          "The action registry does not declare this action's inputs — ask the user what the proposal needs; never invent DAO addresses, members or weights.",
+      },
+    ],
+  },
+  'qi/governance.settings-proposal': {
+    summary:
+      'Creates a DAO governance proposal that changes DAO settings. Side effect; asks for confirmation by default. Outputs the proposal id, status, proposal contract address, DAO core address and creation time.',
+    whenToUse: [
+      'A flow needs to put a change to DAO settings to a governance proposal.',
+    ],
+    tags: ['governance', 'proposals', 'dao'],
+    requires: [
+      {
+        kind: 'inputsUndeclared',
+        description:
+          "The action registry does not declare this action's inputs — ask the user what the proposal needs; never invent DAO addresses or settings.",
+      },
+    ],
+  },
+  'qi/governance.transaction.send-funds': {
+    summary:
+      'Creates a DAO governance proposal to send funds from the DAO to a recipient. Moves money once the proposal executes; side effect; asks for confirmation by default. Outputs the proposal id, status, proposal contract address, DAO core address, recipient and creation time.',
+    whenToUse: [
+      'A flow needs a DAO to vote on spending funds to a recipient address.',
+    ],
+    tags: ['governance', 'proposals', 'dao', 'payments'],
+    requires: [
+      {
+        kind: 'inputsUndeclared',
+        description:
+          "The action registry does not declare this action's inputs — ask the user for the DAO, the recipient and the amount; never invent addresses or amounts.",
+      },
+    ],
+  },
 };

package/src/plugins/flows/actions.ts

@@ -20,6 +20,8 @@ export const HOOK_TYPES = [
 
 export interface ActionSummary {
   action: string;
+  /** See {@link actionCategory}. */
+  category: string;
   summary: string;
   whenToUse: string[];
   tags: string[];
@@ -146,16 +148,32 @@ function outputFields(def: ActionDefinition): ActionField[] {
   }));
 }
 
+/**
+ * An action's category: the namespace in its name — the part after "qi/" up
+ * to the first dot ("qi/claim.submit" → "claim", "qi/governance.transaction.send-funds"
+ * → "governance"); an action outside the "qi/" namespace is its own category
+ * ("oracle"). The registry declares no category, so the name is the only
+ * stable source.
+ */
+export function actionCategory(type: string): string {
+  const local = type.startsWith('qi/') ? type.slice('qi/'.length) : type;
+  const dot = local.indexOf('.');
+  return (dot > 0 ? local.slice(0, dot) : local).toLowerCase();
+}
+
 export function listActions(filter?: {
   category?: string;
   tag?: string;
 }): ActionSummary[] {
+  const category = filter?.category?.toLowerCase();
   const result: ActionSummary[] = [];
   for (const def of getAllActions()) {
     const overlay = overlayFor(def);
     if (filter?.tag && !(overlay.tags ?? []).includes(filter.tag)) continue;
+    if (category && actionCategory(def.type) !== category) continue;
     result.push({
       action: def.type,
+      category: actionCategory(def.type),
       summary: overlay.summary ?? '',
       whenToUse: overlay.whenToUse ?? [],
       tags: overlay.tags ?? [],

package/src/plugins/flows/decision-context.ts

@@ -0,0 +1,31 @@
+import type { RuntimeContext } from '../../plugin-api/types';
+import { FlowError } from './errors';
+import type { FlowSpecRead } from './types';
+
+/**
+ * This module is re-exported from the plugin index, which the Worker
+ * evaluates at module scope. `flow-doc` and `read` reach `@ixo/editor` →
+ * `@ixo/matrix-crdt` → vscode-lib, which schedules a timer while it is
+ * evaluated — forbidden in workerd's global scope (see `flows.plugin.ts`) —
+ * so both are loaded on the first call, inside a request context.
+ */
+export async function readFlowDecisionContext(
+  ctx: RuntimeContext,
+  ref?: string,
+): Promise<FlowSpecRead> {
+  ctx.abortSignal.throwIfAborted();
+  const [{ withFlowDoc }, { readFlowSpec }] = await Promise.all([
+    import('./flow-doc'),
+    import('./read'),
+  ]);
+  return withFlowDoc(ctx, ref, undefined, async (doc, roomId) => {
+    ctx.abortSignal.throwIfAborted();
+    const flow = readFlowSpec(doc, roomId);
+    if (!flow)
+      throw new FlowError(
+        'flow_not_found',
+        'That flow does not exist or has no steps yet.',
+      );
+    return flow;
+  });
+}