@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/plugins/flows/input-policy.ts

@@ -0,0 +1,140 @@
+/**
+ * Limits and content rules for everything the agent writes into a flow
+ * document. The schemas in `types.ts` apply them to tool input, and the edit
+ * layer re-checks the ones that also guard direct writes.
+ *
+ * Sizes: matrix-crdt sends each batch of document changes as one Matrix
+ * event, base64-encoded, and a homeserver refuses any event over 64 KiB of
+ * UTF-8. A step's inputs are stored three times by an input edit (the block,
+ * the compiled node's `props`, and the node itself), and a whole flow is
+ * written in one batch by `create_template`. The JSON caps below are UTF-8
+ * byte counts — a CJK character is three bytes, an emoji four — and keep
+ * either kind of write well under the event limit; `limits.test.ts` measures
+ * the worst case for ASCII, CJK and emoji.
+ *
+ * Secrets: a credential (PIN, mnemonic, password, access token, API key)
+ * must never be stored in a flow document — every room member can read it —
+ * and never pass through the chat. The portal collects them when the user
+ * runs the step, so an input named like a secret port of any action may only
+ * hold a `{{step.output.field}}` reference to a step of the same flow.
+ *
+ * No imports beyond the placeholder scanner and the action metadata (plain
+ * data): `types.ts` is loaded at Worker boot and must not reach `@ixo/editor`.
+ */
+import { ACTION_METADATA } from './action-metadata';
+import { wholeRef } from './ref-syntax';
+
+/** Steps in one flow. */
+export const MAX_FLOW_STEPS = 30;
+/** UTF-8 bytes of a whole flow as JSON (one `create_template` write). */
+export const MAX_FLOW_SPEC_BYTES = 16_000;
+/** UTF-8 bytes of one step as JSON. */
+export const MAX_STEP_SPEC_BYTES = 12_000;
+/** Named inputs on one step. */
+export const MAX_STEP_INPUTS = 40;
+/** UTF-8 bytes of one step's inputs as JSON. */
+export const MAX_STEP_INPUTS_BYTES = 8_000;
+/** Characters of a step id. */
+export const MAX_STEP_ID_CHARS = 64;
+/** Characters of a flow or step title, a phase, a field or event name. */
+export const MAX_NAME_CHARS = 200;
+/** Characters of a description or goal. */
+export const MAX_DESCRIPTION_CHARS = 2_000;
+/** Conditions on one step. */
+export const MAX_CONDITIONS_PER_STEP = 20;
+/** Governed skill ids on one step. */
+export const MAX_SKILLS_PER_STEP = 20;
+/** Questions on one form. */
+export const MAX_FORM_QUESTIONS = 50;
+/** Choices on one form question. */
+export const MAX_QUESTION_CHOICES = 50;
+/** UTF-8 bytes of a form's pre-filled answers as JSON. */
+export const MAX_FORM_ANSWERS_BYTES = 8_000;
+/** Characters of a DID. */
+export const MAX_DID_CHARS = 256;
+
+/**
+ * Input names (lower-cased) that carry a credential: every port any action
+ * flags `secret`. Matched by name for every action, so a secret is refused
+ * even on a step whose action does not declare that port.
+ */
+const SECRET_INPUT_NAMES: ReadonlySet<string> = new Set(
+  Object.values(ACTION_METADATA).flatMap((entry) =>
+    (entry.inputPorts ?? [])
+      .filter((port) => port.secret)
+      .map((port) => port.path.toLowerCase()),
+  ),
+);
+
+const utf8 = new TextEncoder();
+
+/** UTF-8 byte length of `value` serialised as JSON (0 when it cannot be serialised). */
+export function jsonByteLength(value: unknown): number {
+  try {
+    const json = JSON.stringify(value);
+    return json === undefined ? 0 : utf8.encode(json).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** A step-output reference: `<step-id>.output.<field>`. */
+const STEP_OUTPUT_REF = /^([^\s.{}]+)\.output\.[^\s{}]+$/;
+
+/**
+ * Whether a secret input's value may be stored: empty, or only references to
+ * an output of a step of this flow (`stepIds`; any step id when omitted) —
+ * as one string, or as every leaf of a map or list of them.
+ */
+function isAllowedSecretValue(
+  value: unknown,
+  stepIds: ReadonlySet<string> | undefined,
+): boolean {
+  if (value === undefined || value === null || value === '') return true;
+  if (typeof value === 'string') {
+    const ref = wholeRef(value);
+    const step = ref === undefined ? undefined : STEP_OUTPUT_REF.exec(ref)?.[1];
+    return step !== undefined && (stepIds === undefined || stepIds.has(step));
+  }
+  if (Array.isArray(value))
+    return value.every((item) => isAllowedSecretValue(item, stepIds));
+  if (typeof value === 'object')
+    return Object.values(value).every((item) =>
+      isAllowedSecretValue(item, stepIds),
+    );
+  return false;
+}
+
+/**
+ * Paths of every secret-named entry (at any depth) whose value is not an
+ * allowed reference. `stepIds` are the steps a reference may point at; when
+ * omitted (a step checked on its own) any step id is accepted.
+ */
+export function secretLiteralPaths(
+  value: unknown,
+  stepIds?: ReadonlySet<string>,
+  path = '',
+): string[] {
+  if (Array.isArray(value))
+    return value.flatMap((item, index) =>
+      secretLiteralPaths(item, stepIds, `${path}[${index}]`),
+    );
+  if (!value || typeof value !== 'object') return [];
+  const out: string[] = [];
+  for (const [key, item] of Object.entries(value)) {
+    const at = path ? `${path}.${key}` : key;
+    if (SECRET_INPUT_NAMES.has(key.toLowerCase())) {
+      if (!isAllowedSecretValue(item, stepIds)) out.push(at);
+    } else out.push(...secretLiteralPaths(item, stepIds, at));
+  }
+  return out;
+}
+
+/** The message every secret-literal refusal uses. */
+export function secretLiteralMessage(paths: string[]): string {
+  return (
+    `Refusing to store a secret (PIN, mnemonic, password, token or API key) in the flow (${paths.join(', ')}). ` +
+    'These are collected by the portal when the user runs the step; leave the input empty ' +
+    'or reference an output of a step in this flow as "{{step-id.output.field}}". Never ask the user for one in chat.'
+  );
+}

package/src/plugins/flows/prompts.ts

@@ -1,9 +1,10 @@
 /**
- * Flow Builder operating guide — the detailed "how to act" prompt the runtime
- * injects into the main agent's system prompt while the flows capability is
- * loaded (see `main-agent.ts`, gated on `loadedPlugins` containing
- * {@link FLOWS_PLUGIN_NAME}). It is the durable counterpart to the manifest
- * that `load_capability` returns: the manifest sells the capability at
+ * Flow Builder operating guide — the detailed "how to act" prompt. The plugin
+ * declares it as its `operatingGuide`: `load_capability` returns it in the
+ * turn that loads the flows capability, and on later turns the runtime
+ * renders it under `## Capabilities in use` at the end of the system prompt
+ * while the capability stays loaded (see `main-agent.ts`). It is the durable
+ * counterpart to the manifest: the manifest sells the capability at
  * discovery time; this guide governs behaviour for the whole flow-building
  * session.
  *
@@ -18,8 +19,7 @@ export const FLOWS_PLUGIN_NAME = 'flows';
 
 /**
  * The operating guide. Starts with its own `### Flow Builder mode` sub-header
- * so it nests cleanly under the runtime's `## Custom Instructions` section
- * wherever the composer slots it in.
+ * so it nests cleanly under the runtime's `## Capabilities in use` section.
  */
 export const FLOWS_OPERATING_GUIDE = `### Flow Builder mode
 
@@ -31,7 +31,7 @@ You have loaded the **Flow Builder** capability. Use it whenever the user wants
 
 1. **Discover (know the blocks before you plan).** Work out which action blocks the automation needs and look up *exactly* what each one requires before you promise anything:
    - \`list_actions\` to find candidate blocks; \`describe_action\` on each to get its real inputs, outputs, and whether it is a form.
-   - \`requirements\` on each block to get the prerequisites the **user** must supply — e.g. a claim collection, a connected account, a template id, a recipient, an endpoint, a PIN, a funding amount. These are things you must ASK for; never invent them.
+   - \`requirements\` on each block to get the prerequisites the **user** must supply — e.g. a claim collection, a connected account, a template id, a recipient, an endpoint, a funding amount. These are things you must ASK for; never invent them. A \`pin\` requirement is the exception: the portal collects PINs when the user runs the step (see **Secrets** below).
    Do this as a quiet tool pass — not a wall of text to the user.
 
 2. **Plan (planning mode — this is the first thing the user sees).** Before writing anything, present a short, plain-language plan and STOP for approval. For each step, in one line: **"I'll use the \`<action>\` block — it <does X>"**; then how the steps connect (which output feeds which input), plus any form, schedule, assignee, or condition. End the plan with a clear bulleted list of **what you need from the user** — every \`requires\` you could not fill yourself. Keep it tight: a numbered list, not an essay.
@@ -39,11 +39,12 @@ You have loaded the **Flow Builder** capability. Use it whenever the user wants
 3. **Confirm.** Ask the user to confirm or adjust the plan, and wait for a yes (or their edits). Do **not** author the flow until they confirm. Ask once, as a single plan — don't drip one question at a time.
 
 4. **Build (only after confirmation).** Run \`validate_flow\` first, then:
-   - New flow → \`create_template\`. Editing the flow that is already open → the edit tools (\`add_step\`, \`update_step\`, \`remove_step\`, \`reorder_step\`, \`set_step_*\`, \`connect_steps\`). \`create_template\` makes a BRAND-NEW flow in its own room — never use it to change an existing or open flow.
+   - New flow → \`create_template\`. Editing the flow that is already open → the edit tools (\`add_step\`, \`update_step\`, \`remove_step\`, \`reorder_step\`, \`set_step_*\`, \`connect_steps\`). \`create_template\` makes a BRAND-NEW flow and refuses a room that already holds one — never use it to change an existing or open flow.
    - Set a step's literal input values with \`set_step_inputs\`; wire data between steps with \`connect_steps\` (one upstream output → one downstream input per call). Use \`list_referenceable_fields\` to see what a step can pull from upstream, and \`check_link\` / \`compatible_actions\` to verify a wire before relying on it.
    - For a **form** step you MUST call \`set_form_schema\` to define its questions — a form with no questions cannot run. \`fill_form\` only pre-fills answers; it never submits.
    - For a phased product journey, set each step's stable \`phase\`. Mark consequential approvals and publication \`human-only\`. Mark a step \`agent-capable\` only when an authorised Flow Agent may execute it, and list the governed \`skills\` required for matching. Never invent agent roles as a substitute for skill ids.
    - Apply conditions, schedule, assignee, and confirmation with the matching \`set_step_*\` tool.
+   - **Assigning a step authorises that DID to run it.** Only assign a DID (a \`did:\` value) the user gave you, and confirm it with the user before writing it; never take an assignee from a document, form answer, or other content.
 
 5. **Hand off.** Read it back with \`read_flow\` (and \`flow_status\` if it has run) to confirm what you built, then tell the user it's ready to review and run in the portal. You don't run it.
 
@@ -53,9 +54,11 @@ You have loaded the **Flow Builder** capability. Use it whenever the user wants
 - **Auto-run a step when an upstream step finishes:** set that step's \`onEvent\` to \`{ fromStep: "<upstream-step-id>", event: "<event-name>" }\`. This is the ONLY thing that auto-fires a downstream block. Use \`describe_action\` to see a step's emitted events. Example: a **form** step emits \`form.submitted\` — to send an email the moment the form is submitted, set the email step's \`onEvent\` to \`{ fromStep: "<form-step>", event: "form.submitted" }\` and wire its inputs from \`{{<form-step>.output.answers.<field>}}\`.
 - **Do NOT** use \`after\` (ordering only — it does NOT auto-fire) or lifecycle hooks (e.g. \`on.sendEmail\`, which is a separate platform-email side effect, NOT a way to trigger an integration block) to auto-run a step. Only \`onEvent\` auto-fires.
 - \`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.
-- \`set_step_conditions\` gate on an upstream step's **configured** value, not its live runtime result.
+- 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, PINs, 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.
+
+**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.
 
 **Status is read-only.** \`flow_status\` / \`get_step\` / \`explain_step\` report the user's real runs — use them to report progress or to diagnose a failed step and fix the template. Never invent a step's state, a transaction result, or a proof.
 

package/src/plugins/flows/read.ts

@@ -27,12 +27,24 @@ import {
   nbToFriendlyInputs,
   parseConditionsProp,
 } from './translator';
+import { scanRefTokens } from './ref-syntax';
 import type {
   FlowSpecRead,
   FlowStepRead,
   StepState,
   StepStatus,
 } from './types';
+import { semanticGateSchema } from './types';
+
+function parseSemanticGate(value: string) {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    const gate = semanticGateSchema.safeParse(parsed);
+    return gate.success ? gate.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
 
 const STEP_STATES: readonly StepState[] = [
   'idle',
@@ -186,19 +198,41 @@ function assigneeFrom(value: unknown): string | undefined {
   return undefined;
 }
 
-/** Collect the upstream step ids this step refers to via "{{step.output.*}}" inputs. */
+/** Every `{{ … }}` reference anywhere in `value` (nested maps, arrays, embedded text). */
+function collectRefs(value: unknown, out: string[]): void {
+  if (typeof value === 'string') {
+    if (value.includes('{{'))
+      for (const token of scanRefTokens(value)) out.push(token.ref);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectRefs(item, out);
+    return;
+  }
+  if (value && typeof value === 'object')
+    for (const item of Object.values(value)) collectRefs(item, out);
+}
+
+/**
+ * The other steps of this flow that `inputs` reads from via "{{step.output.*}}",
+ * at any depth and embedded in longer strings. A reference whose id is not a
+ * step of this flow (`trigger.payload.*`, a removed step) is not a dependency.
+ */
 function referencedSteps(
   inputs: Record<string, unknown> | undefined,
+  stepId: string,
+  stepIds: ReadonlySet<string>,
 ): string[] {
   if (!inputs) return [];
-  const refs = new Set<string>();
-  for (const value of Object.values(inputs)) {
-    if (typeof value === 'string') {
-      const match = /^\{\{\s*([^.}\s]+)\./.exec(value);
-      if (match?.[1]) refs.add(match[1]);
-    }
+  const refs: string[] = [];
+  collectRefs(inputs, refs);
+  const ids = new Set<string>();
+  for (const ref of refs) {
+    const dot = ref.indexOf('.');
+    const id = dot > 0 ? ref.slice(0, dot) : '';
+    if (id && id !== stepId && stepIds.has(id)) ids.add(id);
   }
-  return [...refs];
+  return [...ids];
 }
 
 /** Derive a step's read-only status from its runtime entry + its dependencies' states. */
@@ -275,6 +309,9 @@ export function readFlowSpec(doc: YDoc, ref: string): FlowSpecRead | null {
   >();
   const stateByStepId = new Map<string, StepState>();
 
+  const stepIds = new Set(
+    compiled.order.filter((nodeId) => compiled.nodes[nodeId] !== undefined),
+  );
   for (const nodeId of compiled.order) {
     const node = compiled.nodes[nodeId];
     if (!node) continue;
@@ -305,6 +342,9 @@ export function readFlowSpec(doc: YDoc, ref: string): FlowSpecRead | null {
     if (skills.length > 0) step.skills = skills;
     else if (primarySkill) step.skills = [primarySkill];
     if (inputs) step.inputs = inputs;
+    if (typeof props.semanticGate === 'string' && props.semanticGate) {
+      step.semanticGate = parseSemanticGate(props.semanticGate);
+    }
     if (conditions.length === 1 && conditions[0]) step.runWhen = conditions[0];
     else if (conditions.length > 1) step.conditions = conditions;
 
@@ -349,7 +389,7 @@ export function readFlowSpec(doc: YDoc, ref: string): FlowSpecRead | null {
     runtimeByStep.set(nodeId, runtime);
     stateByStepId.set(nodeId, asStepState(runtime?.state) ?? 'idle');
     dependenciesByStep.set(nodeId, {
-      referenced: referencedSteps(inputs),
+      referenced: referencedSteps(inputs, nodeId, stepIds),
       after: [],
     });
   }

package/src/plugins/flows/ref-syntax.ts

@@ -0,0 +1,129 @@
+/**
+ * The `{{ … }}` placeholder syntax, scanned by hand in one forward pass.
+ *
+ * Placeholders are read out of document content on every flow read, and any
+ * room member can write that content, so the scan must stay linear in the
+ * input length whatever the input looks like. A regex with a lazy group next
+ * to optional whitespace backtracks polynomially on "{{" followed by a long
+ * run of spaces and no closing braces; this scanner looks at each character a
+ * bounded number of times instead.
+ *
+ * A placeholder is "{{", then at least one character that is not a brace,
+ * then "}}". Whitespace just inside the braces is kept apart from the
+ * reference itself so callers can rewrite the reference and keep the
+ * author's spacing.
+ *
+ * This module has no imports on purpose: the boot-loaded schema module
+ * (`types.ts`) uses it, and nothing it pulls in may reach `@ixo/editor`.
+ */
+
+/**
+ * Strings longer than this are passed through untouched instead of scanned.
+ * One Matrix event carries at most 64 KiB, so no single authored value in a
+ * flow document can legitimately be longer.
+ */
+export const MAX_REF_SCAN_CHARS = 65_536;
+
+export interface RefToken {
+  /** Index of the opening "{{". */
+  start: number;
+  /** Index just past the closing "}}". */
+  end: number;
+  /** The reference with the surrounding whitespace removed (may be empty). */
+  ref: string;
+  /** Whitespace between "{{" and the reference. */
+  leading: string;
+  /** Whitespace between the reference and "}}". */
+  trailing: string;
+}
+
+function isWhitespace(char: string): boolean {
+  return /\s/.test(char);
+}
+
+/** Every `{{ … }}` placeholder in `text`, in order. */
+export function scanRefTokens(text: string): RefToken[] {
+  const tokens: RefToken[] = [];
+  if (text.length > MAX_REF_SCAN_CHARS) return tokens;
+
+  let from = 0;
+  while (from < text.length) {
+    const start = text.indexOf('{{', from);
+    if (start < 0) break;
+
+    // The first brace after the opener decides the outcome: "}}" closes the
+    // placeholder; anything else means no placeholder opens at `start`.
+    let cursor = start + 2;
+    while (cursor < text.length && text[cursor] !== '{' && text[cursor] !== '}')
+      cursor += 1;
+    const closes =
+      cursor > start + 2 && text[cursor] === '}' && text[cursor + 1] === '}';
+    if (!closes) {
+      // The brace-free run after the opener cannot hold another opener, so
+      // resume at the brace — except for "{{{", where the next opener starts
+      // one character later.
+      from = cursor === start + 2 ? start + 1 : cursor;
+      continue;
+    }
+
+    const inner = text.slice(start + 2, cursor);
+    let head = 0;
+    while (head < inner.length && isWhitespace(inner.charAt(head))) head += 1;
+    let tail = inner.length;
+    while (tail > head && isWhitespace(inner.charAt(tail - 1))) tail -= 1;
+    tokens.push({
+      start,
+      end: cursor + 2,
+      ref: inner.slice(head, tail),
+      leading: inner.slice(0, head),
+      trailing: inner.slice(tail),
+    });
+    from = cursor + 2;
+  }
+  return tokens;
+}
+
+/**
+ * The reference when the whole string is exactly one placeholder
+ * ("{{ a.output.b }}"), else `undefined`. "{{a}} and {{b}}" is two embedded
+ * placeholders, not one reference.
+ */
+export function wholeRef(text: string): string | undefined {
+  if (!text.startsWith('{{') || !text.endsWith('}}')) return undefined;
+  const tokens = scanRefTokens(text);
+  const only = tokens.length === 1 ? tokens[0] : undefined;
+  if (!only || only.start !== 0 || only.end !== text.length) return undefined;
+  return only.ref.length > 0 ? only.ref : undefined;
+}
+
+/** Rewrite the reference inside every placeholder, keeping its spacing. */
+export function rewriteRefTokens(
+  text: string,
+  mapRef: (ref: string) => string,
+): string {
+  const tokens = scanRefTokens(text);
+  if (tokens.length === 0) return text;
+  let out = '';
+  let last = 0;
+  for (const token of tokens) {
+    out += text.slice(last, token.start);
+    out += `{{${token.leading}${token.ref.length > 0 ? mapRef(token.ref) : ''}${token.trailing}}}`;
+    last = token.end;
+  }
+  return out + text.slice(last);
+}
+
+/**
+ * True when any string anywhere inside `value` (nested objects and arrays
+ * included) holds a placeholder whose reference starts with `<id>.`.
+ */
+export function referencesId(value: unknown, id: string): boolean {
+  if (typeof value === 'string') {
+    if (!value.includes('{{')) return false;
+    return scanRefTokens(value).some((token) => token.ref.startsWith(`${id}.`));
+  }
+  if (Array.isArray(value)) return value.some((item) => referencesId(item, id));
+  if (value && typeof value === 'object')
+    return Object.values(value).some((item) => referencesId(item, id));
+  return false;
+}