From 5a704f147643af2d7df72f705a8457dca5ea3f08 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 30 Jun 2026 01:13:18 +0000 Subject: [PATCH 1/2] docs: add flows plugin reference page --- .../reference/bundled-plugins/flows.mdx | 150 ++++++++++++++++++ .../reference/bundled-plugins/overview.mdx | 8 +- docs.json | 3 +- 3 files changed, 158 insertions(+), 3 deletions(-) create mode 100644 build-an-oracle/reference/bundled-plugins/flows.mdx diff --git a/build-an-oracle/reference/bundled-plugins/flows.mdx b/build-an-oracle/reference/bundled-plugins/flows.mdx new file mode 100644 index 0000000..64b6983 --- /dev/null +++ b/build-an-oracle/reference/bundled-plugins/flows.mdx @@ -0,0 +1,150 @@ +--- +title: "flows" +description: "Author, inspect, and form-fill multi-step Qi Flow action flows on top of the editor engine." +icon: "diagram-project" +--- + +| Attribute | Value | +| --- | --- | +| Feature key | `flows` | +| Visibility | `on-demand` | +| Stability | `beta` | +| Category | `automation` | +| Default state | Off — opt-in only | +| Depends on | [`editor`](/build-an-oracle/reference/bundled-plugins/editor) Qi Flow engine + Matrix CRDT (shared at runtime) | + + +The `flows` plugin is **not loaded by default** even though it ships in `@ixo/oracle-runtime`. Wire it in explicitly via the `plugins` array (see [Opt in](#opt-in)). The bundled set in `BUNDLED_PLUGINS` does not include it. + + +## Summary + +`flows` is a flow **builder** capability. The agent designs reusable flow *templates* — steps (action blocks), the data wired between them, conditions, schedules, assignees, and forms — and reads the live state of running flows. The agent never executes, signs, mints, holds a key, or enters a PIN; **the user runs the flow in the portal**, where signing and any state transitions happen. + +It coexists with the [`editor`](/build-an-oracle/reference/bundled-plugins/editor) plugin: flows are written as documents over the `@ixo/editor` Qi Flow engine, using oracle-runtime's native yjs reads/writes. The plugin does not require `editor` to be loaded — it contributes its own tool surface. + +## When to use it + +- User wants to build an automation/workflow from steps or action blocks. +- User wants to change a step's inputs, condition, trigger, schedule, or assignee. +- User wants to know what an action needs (its inputs/prerequisites) before adding it. +- User wants to fill in a form or survey attached to a flow step. +- User wants to inspect a flow run, find out why a step failed, and fix the template. + +## When NOT to use it + +- Editing prose, pages, or BlockNote documents — use [`editor`](/build-an-oracle/reference/bundled-plugins/editor). +- Actually executing, running, or signing a step — that happens in the portal, by the user. No transaction tooling lives here. +- IXO entity lookups — use [`domain-indexer`](/build-an-oracle/reference/bundled-plugins/domain-indexer). + +## Environment variables + +The plugin owns no env vars. It relies on the same admin Matrix credentials the `editor` plugin reads from the core base env schema: + +| Var | Required | Description | +| --- | --- | --- | +| `MATRIX_BASE_URL` | yes (base schema) | Matrix homeserver base URL. | +| `MATRIX_ORACLE_ADMIN_USER_ID` | yes (base schema) | Admin Matrix user ID. | +| `MATRIX_ORACLE_ADMIN_ACCESS_TOKEN` | yes (base schema) | Admin Matrix access token. | + +## What it contributes + +- **Tools:** a flow-authoring surface grouped into five buckets — see below. +- **Sub-agents:** none. +- **Middleware:** none. +- **HTTP routes:** none. +- **Shared state:** reads `state.spaceId` / current flow ref from the per-request runtime context; writes flow documents through the editor Qi Flow engine. + +### Tools + +**Discovery** — learn what blocks exist and what they need before adding them. + +- `list_actions` — list available action blocks (optionally filtered by tag). +- `describe_action` — return an action's inputs, outputs, and prerequisites. +- `list_referenceable_fields` — list fields the agent can wire from prior steps. + +**Linkage** — typed wiring checks between steps. + +- `check_link` — verify a single field-to-input wiring between two steps. +- `compatible_actions` — find actions whose inputs match a step's outputs. +- `requirements` — pure action lookup of required inputs. + +**Inspect** — read live flow state to debug a run or review a template. + +- `read_flow` — assemble the full flow document from its native sources. +- `get_step` — fetch a single step's configuration and current state. +- `flow_status` — high-level status of the flow and each step. +- `explain_step` — explain why a step is in its current state. + +**Authoring** — build and edit the template. + +- `validate_flow` — run static checks against the current flow. +- `create_flow` — start a new flow template from `get_flow_template`. +- `add_step`, `remove_step`, `reorder_step` — manipulate the step list. +- `update_flow_meta` — title, description, tags. +- `connect_steps` — wire an upstream output to a downstream input. +- `update_step` — per-block / delta edit that never disturbs sibling steps. + +**Settings** — per-step mutators with narrow scope. + +- `set_step_inputs` — set or replace a step's static inputs. +- `set_step_conditions` — set `props.conditions` directly in the FE evaluator's operator vocabulary. +- `set_step_schedule` — set or clear a step's schedule. +- `set_step_assignment` — set or clear a step's assignee. +- `set_step_confirmation` — toggle the user-confirmation gate before a step runs. +- `set_step_trigger` — configure the trigger that starts the flow. + +**Forms** — attach and fill structured forms on a step. + +- `set_form_schema` — set or replace a step's form schema. +- `describe_form` — return a form's schema and current values. +- `fill_form` — fill or update form fields. + +## How the agent should behave + +Follow a tight loop: **discover → plan → confirm → build → hand off.** One discovery pass, one short plan, one user confirmation, then build with the authoring tools. The plugin injects an operating guide into the system prompt while it is loaded — see the `FLOWS_OPERATING_GUIDE` exported from the package. + +Conditions are written **directly as `props.conditions`** in the FE evaluator's operator vocabulary; the compiler's verbatim operators never evaluate at runtime. + +## Opt in + +`flows` is opt-in. Add the plugin instance explicitly — the bundled loader will not load it for you: + +```ts +import { createOracleApp, FlowsPlugin } from '@ixo/oracle-runtime'; +import * as sdk from 'matrix-js-sdk'; + +const matrixClient = sdk.createClient({ /* … */ }); + +const app = await createOracleApp({ + config, + plugins: [new FlowsPlugin({ matrixClient })], // matrixClient is optional — env fallback otherwise +}); +``` + +If your app already constructs the [`editor`](/build-an-oracle/reference/bundled-plugins/editor) plugin with a shared `matrixClient`, reuse it here so both plugins share the same long-lived sync. + +## Examples + +**User: "Build a flow that emails the applicant when their claim is approved."** + +The agent calls `list_actions` (tag: `claims`) to discover blocks, picks a submit/approve/email chain, confirms the plan, then `create_flow` + `add_step` + `connect_steps` + `set_step_conditions` to wire it up. The user runs the flow from the portal. + +**User: "What does the submit-claim step need before I can add it?"** + +The agent calls `describe_action` with `action: 'qi/claim.submit'` and reports its required inputs and prerequisites. + +**User: "Why did the second step of my flow fail?"** + +The agent calls `flow_status` followed by `explain_step` on the failed step to surface the error, then proposes an `update_step` or `set_step_inputs` fix on the template. + +## Where to read next + + + + The Qi Flow engine the builder writes against. + + + `spaceId` and the per-request flow ref the tools key off. + + diff --git a/build-an-oracle/reference/bundled-plugins/overview.mdx b/build-an-oracle/reference/bundled-plugins/overview.mdx index e187329..2627ac0 100644 --- a/build-an-oracle/reference/bundled-plugins/overview.mdx +++ b/build-an-oracle/reference/bundled-plugins/overview.mdx @@ -1,10 +1,10 @@ --- title: "Bundled plugins" -description: "The 15 plugins the runtime ships with. Toggle each one through the features map, set its env vars, ship." +description: "The plugins the runtime ships with. Toggle each one through the features map, set its env vars, ship." icon: "boxes-stacked" --- -The runtime bundles 15 plugins. They load by default; opt out per plugin via the `features` map on `createOracleApp`. +The runtime bundles 15 plugins that load by default; opt out per plugin via the `features` map on `createOracleApp`. One additional plugin — [`flows`](/build-an-oracle/reference/bundled-plugins/flows) — ships in the package but is **opt-in only**: wire it in explicitly via the `plugins` array. ## At a glance @@ -25,6 +25,7 @@ The runtime bundles 15 plugins. They load by default; opt out per plugin via the | [`calls`](/build-an-oracle/reference/bundled-plugins/calls) | `silent` | On (stub) | — | — | | [`user-preferences`](/build-an-oracle/reference/bundled-plugins/user-preferences) | `always` | On | — | — | | [`matrix-group-chats`](/build-an-oracle/reference/bundled-plugins/matrix-group-chats) | `on-demand` | On | — | — | +| [`flows`](/build-an-oracle/reference/bundled-plugins/flows) | `on-demand` | Opt-in (not bundled) | — | `editor` Qi Flow engine | `Default state` legend: @@ -95,6 +96,9 @@ const app = await createOracleApp({ Gate the bot + per-room compacted memory for Matrix group rooms. + + Author and inspect multi-step Qi Flow templates (opt-in). + ## Wiring custom-constructed plugins diff --git a/docs.json b/docs.json index 49c8dca..7e72b01 100644 --- a/docs.json +++ b/docs.json @@ -224,7 +224,8 @@ "build-an-oracle/reference/bundled-plugins/credits", "build-an-oracle/reference/bundled-plugins/calls", "build-an-oracle/reference/bundled-plugins/user-preferences", - "build-an-oracle/reference/bundled-plugins/matrix-group-chats" + "build-an-oracle/reference/bundled-plugins/matrix-group-chats", + "build-an-oracle/reference/bundled-plugins/flows" ] } ] From e0df3a390751578c3a8d62b2f5d46071039f0ca9 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 30 Jun 2026 01:14:52 +0000 Subject: [PATCH 2/2] docs: tighten flows plugin metadata and clarify FE jargon --- build-an-oracle/reference/bundled-plugins/flows.mdx | 6 +++--- build-an-oracle/reference/bundled-plugins/overview.mdx | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/build-an-oracle/reference/bundled-plugins/flows.mdx b/build-an-oracle/reference/bundled-plugins/flows.mdx index 64b6983..9832de9 100644 --- a/build-an-oracle/reference/bundled-plugins/flows.mdx +++ b/build-an-oracle/reference/bundled-plugins/flows.mdx @@ -1,6 +1,6 @@ --- title: "flows" -description: "Author, inspect, and form-fill multi-step Qi Flow action flows on top of the editor engine." +description: "Opt-in flow-builder plugin: author, inspect, wire, and form-fill multi-step Qi Flow action templates on top of the editor's Qi Flow engine." icon: "diagram-project" --- @@ -88,7 +88,7 @@ The plugin owns no env vars. It relies on the same admin Matrix credentials the **Settings** — per-step mutators with narrow scope. - `set_step_inputs` — set or replace a step's static inputs. -- `set_step_conditions` — set `props.conditions` directly in the FE evaluator's operator vocabulary. +- `set_step_conditions` — set `props.conditions` directly in the frontend evaluator's operator vocabulary. - `set_step_schedule` — set or clear a step's schedule. - `set_step_assignment` — set or clear a step's assignee. - `set_step_confirmation` — toggle the user-confirmation gate before a step runs. @@ -104,7 +104,7 @@ The plugin owns no env vars. It relies on the same admin Matrix credentials the Follow a tight loop: **discover → plan → confirm → build → hand off.** One discovery pass, one short plan, one user confirmation, then build with the authoring tools. The plugin injects an operating guide into the system prompt while it is loaded — see the `FLOWS_OPERATING_GUIDE` exported from the package. -Conditions are written **directly as `props.conditions`** in the FE evaluator's operator vocabulary; the compiler's verbatim operators never evaluate at runtime. +Conditions are written **directly as `props.conditions`** in the frontend evaluator's operator vocabulary; the compiler's verbatim operators never evaluate at runtime. ## Opt in diff --git a/build-an-oracle/reference/bundled-plugins/overview.mdx b/build-an-oracle/reference/bundled-plugins/overview.mdx index 2627ac0..2cea292 100644 --- a/build-an-oracle/reference/bundled-plugins/overview.mdx +++ b/build-an-oracle/reference/bundled-plugins/overview.mdx @@ -1,6 +1,6 @@ --- title: "Bundled plugins" -description: "The plugins the runtime ships with. Toggle each one through the features map, set its env vars, ship." +description: "Reference for every plugin the oracle runtime ships with — toggle each one through the features map, set its env vars, and ship to production." icon: "boxes-stacked" ---