@ixo/oracle-runtime-workers 0.38.0 → 0.39.0

package/src/memory/session-history-indexer.ts

@@ -27,8 +27,13 @@
  *    transcript's last chance).
  *  - Speakers get real identities (the user's preferred name / the oracle's
  *    preferred or configured name) so Graphiti's extractor does not pin
- *    facts to literal "user"/"assistant" nodes. Tool replies fold into the
- *    assistant role (the engine has no tool role).
+ *    facts to literal "user"/"assistant" nodes.
+ *  - Only the conversation is sent: what the user said and the oracle's
+ *    replies (`conversationReader`). The engine makes every message an episode
+ *    of evidence, so a tool result, a status line before a tool call, or a
+ *    reply that repeats what a memory search just returned would come back
+ *    as a fact, and push real ones out of the capped user-context block. Those
+ *    messages still count towards the watermark.
  *  - Auth is the oracle's two-hop UCAN invocation minted from the user's
  *    delegation (`ixo:memory` / `memory/*`) — no delegation, no indexing.
  *  - Endpoint: `POST <MEMORY_ENGINE_URL>/messages` with `x-room-id`, as
@@ -45,13 +50,18 @@
  * Not ported: Node also asks Matrix for the user's display name when no
  * preferred name is set; here the fallback is the literal "Me" straight away.
  */
+import { AIMessage, type BaseMessage } from '@langchain/core/messages';
+import { visibleText, visibleToUser } from '../do/transcript';
 import type { Logger } from '../plugin-api/types';
 import { MEMORY_ENTITY_HEADER } from '../plugins/memory/memory-entity';
+import { MEMORY_SEARCH_MCP_NAME } from '../plugins/memory/memory-tools';
 
 export interface HistoryMessage {
   /** LangChain message type: `human` | `ai` | `tool` | `system`. */
   type: string;
   content: string;
+  /** Counted by the watermark but not sent (`conversationReader`). */
+  notConversation?: boolean;
 }
 
 export interface MemoryEngineMessage {
@@ -230,6 +240,47 @@ interface QuietWait {
   resolve: () => void;
 }
 
+/** Text that parses as a JSON object or list: a tool's output, not a reply. */
+function isJsonDocument(text: string): boolean {
+  const start = text.trimStart()[0];
+  if (start !== '{' && start !== '[') return false;
+  try {
+    JSON.parse(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads a transcript in order, one reader per read, and turns each message
+ * into what the indexer takes. A turn's memory search is seen before its reply,
+ * so that reply is known to repeat what memory returned, which must not go
+ * back in as new evidence. A read that starts in the middle of a turn has not
+ * seen the search; a pass normally starts at a turn's end.
+ */
+export function conversationReader(): (message: BaseMessage) => HistoryMessage {
+  let readMemory = false;
+  return (message) => {
+    const content = visibleText(message);
+    const calls = AIMessage.isInstance(message)
+      ? (message.tool_calls ?? [])
+      : [];
+    if (message.type === 'human') readMemory = false;
+    if (calls.some((call) => call.name === MEMORY_SEARCH_MCP_NAME))
+      readMemory = true;
+    const conversation =
+      visibleToUser(message) &&
+      (message.type === 'human' ||
+        (calls.length === 0 && !readMemory && !isJsonDocument(content)));
+    return {
+      type: message.type,
+      content,
+      ...(conversation ? {} : { notConversation: true }),
+    };
+  };
+}
+
 /** Node's `transformMessagesToMemoryEngineFormat`, verbatim in mapping. */
 export function transformMessagesToMemoryEngineFormat(
   messages: readonly HistoryMessage[],
@@ -237,7 +288,12 @@ export function transformMessagesToMemoryEngineFormat(
   userSpeakerLabel: string,
   oracleSpeakerLabel: string,
 ): MemoryEngineMessage[] {
-  return messages.map((message) => {
+  // The engine rejects empty episodes, and has no tool role.
+  const conversation = messages.filter(
+    (m) =>
+      m.type !== 'tool' && !m.notConversation && m.content.trim().length > 0,
+  );
+  return conversation.map((message) => {
     let role_type: MemoryEngineMessage['role_type'];
     let label: string;
     switch (message.type) {
@@ -253,12 +309,6 @@ export function transformMessagesToMemoryEngineFormat(
         role_type = 'system';
         label = 'System';
         break;
-      case 'tool':
-        // The engine has no tool role — tool replies are the oracle
-        // reporting back, so they share the oracle speaker label.
-        role_type = 'assistant';
-        label = oracleSpeakerLabel;
-        break;
       default:
         role_type = 'user';
         label = userSpeakerLabel;
@@ -564,11 +614,7 @@ export class SessionHistoryIndexer {
     try {
       while (chunk.length > 0) {
         const transformed = transformMessagesToMemoryEngineFormat(
-          // Tool-call-only AI turns carry no text; the engine has nothing to
-          // extract from them and rejects empty episodes.
-          chunk
-            .map((entry) => entry.message)
-            .filter((m) => m.content.trim().length > 0),
+          chunk.map((entry) => entry.message),
           session.title ?? '',
           labels.user,
           labels.oracle,

package/src/plugin-api/oracle-plugin.ts

@@ -63,11 +63,10 @@ export abstract class OraclePlugin {
    * plugin's working rules, as plain text (markdown, starting at a `###`
    * heading). Never part of the manifest, the Tier-1 capability block or
    * `list_capabilities`, so it costs nothing on turns that do not use the
-   * plugin. `load_capability` returns it (once per turn) when it loads the
-   * plugin or the capability router preloaded it for the turn, and the
-   * system prompt carries it on every turn that starts with the plugin
-   * loaded on the thread (or `always` visible) and usable by the user's
-   * delegation.
+   * plugin. The model has it when it first uses the plugin's tools: in the
+   * load result or on the turn's message when the plugin loads on a warm
+   * turn, in the system prompt from the next cold turn on, and always there
+   * for an `always` plugin the user's delegation can use.
    */
   readonly operatingGuide?: string;
 

package/src/plugin-api/types.ts

@@ -473,15 +473,39 @@ export interface PluginManifest {
   /**
    * Discovery and loading mode:
    *  - `always`    — tools bound to agent at boot; listed in Tier-1 prompt.
-   *  - `on-demand` — tools NOT bound; manifest discoverable via
-   *                  `list_capabilities`; agent calls `load_capability(name)`
-   *                  to load.
+   *  - `on-demand` — tools NOT bound; named in the prompt's on-demand
+   *                  catalogue; agent calls `load_capability(name)` to load.
    *  - `silent`    — invisible to agent; runs as middleware-only.
    *
    * Default: `on-demand`.
    */
   visibility?: 'always' | 'on-demand' | 'silent';
 
+  /**
+   * A few words (at most 60 characters) on what `load_capability` adds: the
+   * line the system prompt's on-demand catalogue shows for this plugin, so
+   * the model can pick it without a `list_capabilities` round trip. Falls
+   * back to a clipped `summary`.
+   */
+  brief?: string;
+
+  /**
+   * Tools this plugin keeps out of the model's tool list until
+   * `load_capability` names the plugin, while its other tools (and, for an
+   * `always` plugin, its Tier-1 entry) stay in place. Names are matched at
+   * request time, so MCP-sourced tools can be listed. A tool's own
+   * `visibility` wins over this list. A host keeps every tool bound with
+   * `manifestOverrides: { name: { onDemandTools: [] } }`.
+   */
+  onDemandTools?: readonly string[];
+  /**
+   * `false` keeps the plugin away from the capability router: it stays in the
+   * catalogue and `load_capability` loads it, but no message preloads it. For
+   * a plugin whose name attracts messages its gated tools do not serve, or
+   * one the host loads itself when it applies.
+   */
+  routable?: boolean;
+
   /** Stability hint surfaced to the agent (`experimental` → warning footnote). */
   stability?: 'stable' | 'beta' | 'experimental';
 
@@ -1297,6 +1321,11 @@ export interface PluginSubAgent {
   forwardTools?: boolean | string[];
   /** Called after sub-agent completes; can emit follow-up events. */
   onComplete?: (result: string, ctx: RuntimeContext) => Promise<void>;
+  /**
+   * Added to the error the model reads when the sub-agent could not run, so a
+   * capability that is not loaded can still be the way forward.
+   */
+  failureHint?: string;
 }
 
 /**

package/src/plugins/action-proposals/action-proposals.plugin.ts

@@ -10,6 +10,7 @@ import {
   type ActionReference,
 } from '@ixo/ixo-transaction/action-proposals';
 import { z } from 'zod';
+import { modelFacingSchema } from '../compact-schema';
 import { OraclePlugin } from '../../plugin-api/oracle-plugin';
 import { tool } from '../../plugin-api/tool-helper';
 import type {
@@ -131,7 +132,9 @@ export async function prepareAction(
   const parsed = PrepareActionSchema.safeParse(input);
   if (!parsed.success)
     return clarify(
-      'Provide the exact supported action, network, recipient and amount.',
+      `Provide the exact supported action, network, recipient and amount (${parsed.error.issues
+        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+        .join('; ')}).`,
     );
   if (ctx.config.ACTION_PROPOSALS_ENABLED !== 'true' || !ctx.actionProposals)
     return clarify('Action proposals are not enabled for this companion.');
@@ -459,6 +462,7 @@ const manifest: PluginManifest = {
   tags: ['actions', 'wallet', 'channels'],
   category: 'integration',
   visibility: 'on-demand',
+  brief: 'transfers, discussions and grants to sign in Portal',
   stability: 'experimental',
 };
 export class ActionProposalsPlugin extends OraclePlugin {
@@ -478,7 +482,8 @@ export class ActionProposalsPlugin extends OraclePlugin {
         name: 'prepare_action',
         description:
           'Prepare a validated transfer, draft discussion or topic claim-access grant for explicit owner review. Never executes. Use exact supported inputs from current-session user evidence and authenticated current-room/owner bindings. Other topic kinds and unverified identities require clarification.',
-        schema: PrepareActionSchema,
+        // The handler parses PrepareActionSchema and names what it refuses.
+        schema: modelFacingSchema(PrepareActionSchema),
         effect: 'write',
       }),
     ];

package/src/plugins/agui/agui.plugin.ts

@@ -50,6 +50,7 @@ const manifest: PluginManifest = {
   tags: ['agui', 'ui', 'portal', 'copilot'],
   category: 'ui',
   visibility: 'on-demand',
+  brief: 'show interactive tables, charts and forms',
   stability: 'stable',
 };
 

package/src/plugins/compact-schema.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+
+type JsonSchema = z.core.JSONSchema._JSONSchema;
+type ObjectSchema = z.core.JSONSchema.JSONSchema;
+
+/**
+ * Keywords a model does not need to write a valid call and that repeat all
+ * over a large schema. They stay enforced by the handler's strict parse.
+ */
+const CHECK_ONLY = [
+  'minLength',
+  'maxLength',
+  'pattern',
+  'minItems',
+  'maxItems',
+  'minimum',
+  'maximum',
+  'exclusiveMinimum',
+  'exclusiveMaximum',
+  'propertyNames',
+  '$schema',
+] as const;
+
+type Options = { descriptions?: boolean };
+
+function compactInner(schema: JsonSchema, options: Options): JsonSchema {
+  return typeof schema === 'boolean'
+    ? schema
+    : compactJsonSchema(schema, options);
+}
+
+/**
+ * `schema` with the same shape (properties, required keys, types, enums,
+ * constants, nesting) and without {@link CHECK_ONLY}, and without its
+ * descriptions when `descriptions` is false.
+ */
+export function compactJsonSchema(
+  schema: ObjectSchema,
+  options: Options = {},
+): ObjectSchema {
+  const compact = { ...schema };
+  for (const keyword of CHECK_ONLY) delete compact[keyword];
+  if (options.descriptions === false) delete compact.description;
+  const { properties, items, additionalProperties, anyOf, oneOf } = schema;
+  if (properties)
+    compact.properties = Object.fromEntries(
+      Object.entries(properties).map(([name, property]) => [
+        name,
+        compactInner(property, options),
+      ]),
+    );
+  if (items !== undefined)
+    compact.items = Array.isArray(items)
+      ? items.map((item) => compactInner(item, options))
+      : compactInner(items, options);
+  if (additionalProperties !== undefined)
+    compact.additionalProperties = compactInner(additionalProperties, options);
+  if (anyOf) compact.anyOf = anyOf.map((s) => compactJsonSchema(s, options));
+  if (oneOf) compact.oneOf = oneOf.map((s) => compactJsonSchema(s, options));
+  return compact;
+}
+
+/**
+ * The schema a tool binds when its handler parses its input strictly itself:
+ * the shape of `schema` as its input, reduced by {@link compactJsonSchema}.
+ * Tools repeating a large schema bind this, so the model reads each field's
+ * limits and words once at most; a call the bound schema lets through and
+ * the handler refuses must name the problem in its answer.
+ */
+export function modelFacingSchema(
+  schema: z.ZodType,
+  options: Options = {},
+): z.ZodType {
+  return z.fromJSONSchema(
+    compactJsonSchema(
+      z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' }),
+      options,
+    ),
+  );
+}

package/src/plugins/composio/composio.plugin.ts

@@ -100,6 +100,7 @@ const manifest: PluginManifest = {
   ],
   category: 'integration',
   visibility: 'on-demand',
+  brief: 'Gmail, GitHub, Slack, Calendar and hundreds of apps',
   stability: 'stable',
   requires: [SANDBOX_CAPABILITY],
 };

package/src/plugins/domain-indexer/domain-indexer.plugin.ts

@@ -45,14 +45,14 @@ function resolveDomainIndexerUrl(config: MergedConfig): string {
 const manifest: PluginManifest = {
   title: 'Domain Indexer',
   summary:
-    'Domain analysis and entity lookup across the IXO ecosystem — organizations, projects, DAOs, DIDs.',
+    'Search the IXO ecosystem by name or topic: organizations, projects, DAOs and their domain cards.',
   whenToUse: [
-    'User asks "what is X?" or "tell me about X" for an organization, project, DAO, or DID.',
+    'User asks "what is X?" or "tell me about X" for an organization, project or DAO by name.',
     'User needs the summary, overview, or FAQ of an IXO entity.',
-    'Looking up a domain card by its DID.',
     'Discovering entities by topic, category, or keyword.',
   ],
   whenNotToUse: [
+    'One exact DID: read the chain first (`chain_lookup` kind `entity`).',
     'General web search unrelated to IXO entities (use Firecrawl).',
     'Personal memory or past-conversation recall (use Memory).',
     'Page editing or workspace pages (use Editor) — pages are NOT entities.',
@@ -75,6 +75,7 @@ const manifest: PluginManifest = {
   // via `load_capability` when the conversation actually needs it, keeping
   // the sub-agent schema out of every unrelated chat turn.
   visibility: 'on-demand',
+  brief: 'search organisations, projects and DAOs by name or topic',
   stability: 'stable',
 };
 

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

@@ -72,6 +72,10 @@ const manifest: PluginManifest = {
   category: 'data',
   // On-demand so ordinary chats carry no editor Tier-1 entry or gated tools.
   visibility: 'on-demand',
+  brief: "read and edit the user's open editor document",
+  // An open document loads it (the editor context); without one there is
+  // nothing for its tools to read.
+  routable: false,
   stability: 'stable',
 };
 

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

@@ -89,5 +89,7 @@ export function createFirecrawlSubAgent(tools: PluginTool[]): PluginSubAgent {
     tools,
     model: 'subagent',
     middlewares: [],
+    failureHint:
+      'Web search is unavailable, but this is not the end of the request: a page or feed can still be fetched with code. Load the `sandbox` capability if it is not in your tool list and fetch the URL with `sandbox_run`, or use another capability that can answer. Tell the user only if none can.',
   };
 }

package/src/plugins/firecrawl/firecrawl.plugin.ts

@@ -48,6 +48,7 @@ const manifest: PluginManifest = {
   tags: ['web', 'search', 'scrape', 'firecrawl'],
   category: 'data',
   visibility: 'on-demand',
+  brief: 'search the web; scrape and read web pages',
   stability: 'stable',
 };
 

package/src/plugins/flows/flows.plugin.ts

@@ -19,12 +19,14 @@
  * context where timers are allowed.
  */
 import type { MatrixClient } from 'matrix-js-sdk';
+import type { z } from 'zod';
 import { OraclePlugin } from '../../plugin-api/oracle-plugin';
 import type {
   PluginManifest,
   PluginTool,
   RuntimeContext,
 } from '../../plugin-api/types';
+import { modelFacingSchema } from '../compact-schema';
 import { FLOWS_OPERATING_GUIDE, FLOWS_PLUGIN_NAME } from './prompts';
 
 export interface FlowsPluginOptions {
@@ -37,11 +39,9 @@ export interface FlowsPluginOptions {
  * `summary` is the one-line teaser; `whenToUse`/`whenNotToUse`/`examples` teach
  * the agent when and how to load it. The full operating contract,
  * `FLOWS_OPERATING_GUIDE` (prompts.ts), is the plugin's `operatingGuide`, not
- * part of the manifest: `load_capability` returns it when it loads flows (also
- * when the capability router had only preloaded it for the turn), and the
- * system prompt carries it on every later turn that starts with flows loaded
- * on the thread. A one-turn router preload leaves the system prompt alone, and
- * turns that never use flows pay no tokens for it.
+ * part of the manifest: it reaches the model with the load, in the system
+ * prompt on a cold turn and at the tail of the messages otherwise, and turns
+ * that never use flows pay no tokens for it (core/operating-guides.ts).
  */
 const manifest: PluginManifest = {
   title: 'Flow Builder',
@@ -80,9 +80,39 @@ const manifest: PluginManifest = {
   tags: ['flows', 'templates', 'automation', 'workflow', 'forms'],
   category: 'automation',
   visibility: 'on-demand',
+  brief: 'build and run automation flows from action blocks',
   stability: 'beta',
 };
 
+/**
+ * The tools that repeat `create_template`'s step in their schema. All 27 are
+ * bound together, so the step's words appear once, on `create_template`.
+ */
+const REPEATS_STEP: ReadonlySet<string> = new Set([
+  'validate_flow',
+  'add_step',
+  'update_step',
+]);
+
+const boundSchemas = new Map<string, z.ZodType>();
+
+/**
+ * What a flow tool binds: its schema's shape without limits and patterns.
+ * Every handler parses its own strict schema first and answers
+ * `validation_failed` with its messages.
+ * Built once per isolate; a tool's schema does not depend on the turn.
+ */
+function boundSchema(tool: PluginTool): z.ZodType {
+  let schema = boundSchemas.get(tool.name);
+  if (!schema) {
+    schema = modelFacingSchema(tool.schema, {
+      descriptions: !REPEATS_STEP.has(tool.name),
+    });
+    boundSchemas.set(tool.name, schema);
+  }
+  return schema;
+}
+
 export class FlowsPlugin extends OraclePlugin {
   readonly name = FLOWS_PLUGIN_NAME;
   readonly version = '0.1.0';
@@ -112,7 +142,7 @@ export class FlowsPlugin extends OraclePlugin {
         import('./tools/settings'),
       ]);
 
-    return [
+    const tools = [
       // Discovery
       discovery.buildListActionsTool(),
       discovery.buildDescribeActionTool(),
@@ -131,5 +161,6 @@ export class FlowsPlugin extends OraclePlugin {
       // Forms
       ...forms.buildFormTools(this.matrixClient),
     ];
+    return tools.map((tool) => ({ ...tool, schema: boundSchema(tool) }));
   }
 }

package/src/plugins/flows/prompts.ts

@@ -56,7 +56,7 @@ You have loaded the **Flow Builder** capability. Use it whenever the user wants
 - \`set_step_trigger\` sets \`manual\` vs \`flow-start\`. \`onEvent\` is only valid when the upstream action actually emits events (\`validate_flow\` enforces this); otherwise fall back to order + data references and the user runs the step manually.
 - Every newly authored condition declares \`source: "configured_input"\` or \`source: "runtime_output"\`. Use configured inputs for authored values and runtime output for a previous step's successful result. Untagged stored conditions retain the runner's runtime-output interpretation.
 
-**Asking vs guessing:** STOP and ask for any \`requires\` you can't fill from context (collection ids, DIDs, recipients, connected accounts, template names, endpoints, amounts). Never fabricate them. But don't ask for things the portal collects at run time, or that you can reasonably infer.
+**Asking vs guessing:** STOP and ask for any \`requires\` you can't fill from context (collection ids, DIDs, recipients, connected accounts, template names, endpoints, amounts). Never fabricate them. But don't ask for things the portal collects at run time, or that you can reasonably infer. When the user tells you not to ask or to make your own choices, skip the confirmation and build: put a visible placeholder such as \`<claim collection id>\` in place of what you can't fill, never an invented value, and list the placeholders when you hand off.
 
 **Secrets:** never ask for a PIN, mnemonic, password, access token, recovery phrase or API key in chat, and never write one into a flow — every room member can read the flow. PINs are collected by the portal when the user runs the step. A secret input (\`pin\`, \`mnemonic\`, \`matrixPassword\`, \`matrixAccessToken\`, \`matrixRecoveryPhrase\`, a plaintext API key) may only hold a \`{{step-id.output.field}}\` reference to a step of this flow (e.g. a wallet step's mnemonic output); the tools refuse anything else. If the user offers a PIN in chat, tell them not to share it and that the portal will ask for it.
 

package/src/plugins/flows/tools/authoring.ts

@@ -65,10 +65,7 @@ const flowSpecTitleSchema = z.string().min(1).max(MAX_NAME_CHARS);
 const flowSpecGoalSchema = z.string().max(MAX_DESCRIPTION_CHARS);
 
 const base = {
-  flowRef: z
-    .string()
-    .optional()
-    .describe('Which flow. Omit to use the flow that is currently open.'),
+  flowRef: z.string().optional().describe('Default: the open flow.'),
 };
 const ok = { ok: true } as const;
 
@@ -141,7 +138,8 @@ function buildValidateFlowTool(): PluginTool {
       name: 'validate_flow',
       description:
         'Check whether a flow is valid without saving it. Returns the exact problems (unknown action, duplicate step id, ' +
-        'a non-event-capable auto-trigger, a trigger cycle, etc.) so they can be fixed before creating the flow.',
+        'a non-event-capable auto-trigger, a trigger cycle, etc.) so they can be fixed before creating the flow. ' +
+        '`flow` as in create_template.',
       schema: validateSchema,
     },
   );
@@ -415,7 +413,7 @@ function buildAddStepTool(matrixClient: MatrixClient | undefined): PluginTool {
       name: 'add_step',
       description:
         'Add one step to an existing flow without disturbing the others: the title, owner and step order stay as they are. ' +
-        'Optionally place it at a position. A step id that already exists is refused.',
+        'A step id that already exists is refused. `step` as in create_template. `position`: a 0-based index, {after: id} or {before: id}; default: append.',
       schema: addStepSchema,
     },
   );
@@ -611,7 +609,7 @@ export function buildAuthoringTools(
         name: 'update_step',
         description:
           "Update any subset of a step's settings in one call (phase, execution boundary, required skills, inputs, conditions, schedule, assignee, confirmation, " +
-          'trigger, onEvent). onEvent takes precedence over trigger when both are given; set trigger to "manual" to ' +
+          'trigger, onEvent). `patch` fields as in create_template\'s step. onEvent takes precedence over trigger when both are given; set trigger to "manual" to ' +
           'clear an onEvent auto-trigger. Set phase or semanticGate to null to clear it.',
         schema: updateStepSchema,
       },

package/src/plugins/flows/tools/discovery.ts

@@ -27,10 +27,7 @@ const describeActionSchema = z.object({
 });
 
 const referenceableSchema = z.object({
-  flowRef: z
-    .string()
-    .optional()
-    .describe('Which flow. Omit to use the flow that is currently open.'),
+  flowRef: z.string().optional().describe('Default: the open flow.'),
   stepId: z
     .string()
     .min(1)

package/src/plugins/flows/tools/forms.ts

@@ -18,10 +18,7 @@ import {
 } from '../input-policy';
 
 const describeSchema = z.object({
-  flowRef: z
-    .string()
-    .optional()
-    .describe('Which flow. Omit to use the flow that is currently open.'),
+  flowRef: z.string().optional().describe('Default: the open flow.'),
   stepId: stepIdSchema.describe('The form step to describe.'),
 });
 
@@ -59,10 +56,7 @@ const questionSchema = z.object({
 });
 
 const setFormSchemaSchema = z.object({
-  flowRef: z
-    .string()
-    .optional()
-    .describe('Which flow. Omit to use the flow that is currently open.'),
+  flowRef: z.string().optional().describe('Default: the open flow.'),
   stepId: z
     .string()
     .min(1)

package/src/plugins/flows/tools/linkage.ts

@@ -10,10 +10,7 @@ import { toToolError } from '../errors';
 import { withFlowDoc } from '../flow-doc';
 import { checkLink, compatibleActions, requirements } from '../linkage';
 
-const flowRef = z
-  .string()
-  .optional()
-  .describe('Which flow. Omit to use the flow that is currently open.');
+const flowRef = z.string().optional().describe('Default: the open flow.');
 
 const checkLinkSchema = z.object({
   flowRef,

package/src/plugins/flows/tools/settings.ts

@@ -27,10 +27,7 @@ import {
 } from '../types';
 
 const base = {
-  flowRef: z
-    .string()
-    .optional()
-    .describe('Which flow. Omit to use the flow that is currently open.'),
+  flowRef: z.string().optional().describe('Default: the open flow.'),
 };
 
 const inputsSchema = z.object({

package/src/plugins/flows/translator.ts

@@ -19,7 +19,12 @@ import type {
   FlowCapability,
   TriggerSpec,
 } from '@ixo/editor/core';
-import { canToType, getActionByCan, typeToCan } from '@ixo/editor/core';
+import {
+  canToType,
+  getAction,
+  getActionByCan,
+  typeToCan,
+} from '@ixo/editor/core';
 import { FlowError } from './errors';
 import { rewriteRefTokens, wholeRef } from './ref-syntax';
 import type { Condition, FlowSpecInput, FlowStep } from './types';
@@ -93,18 +98,24 @@ function rewriteEmbeddedRefs(
   return rewriteRefTokens(text, mapRef);
 }
 
-/** Resolve a friendly action name (registry `type`) to its `can` ability string. */
+/**
+ * Resolve a friendly action name (registry `type`) to its `can` ability
+ * string. The editor's type-to-can table does not cover every action its
+ * registry lists (`qi/form.submit` among them), so the action's own
+ * definition answers when the table does not: an action `list_actions`
+ * offers always resolves.
+ */
 export function actionToCan(action: string): string {
-  const can = typeToCan(action);
+  const can = typeToCan(action) ?? getAction(action)?.can;
   if (can) return can;
   // Tolerate an action that is already a `can` string.
   if (getActionByCan(action)) return action;
   throw new FlowError('unknown_action', `Unknown action "${action}".`);
 }
 
-/** Resolve a `can` ability string back to the friendly action name (registry `type`). */
+/** Resolve a `can` ability string back to the friendly action name (registry `type`), by the table, then the registry. */
 export function canToAction(can: string): string {
-  return canToType(can) ?? can;
+  return canToType(can) ?? getActionByCan(can)?.type ?? can;
 }
 
 /** A `{ $ref: string }` runtime reference — the only shape the engine resolves. */