@ixo/oracle-runtime-workers 0.2.0

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

@@ -0,0 +1,129 @@
+/**
+ * FlowsPlugin — the flow-builder plugin. The agent designs reusable flow
+ * *templates* by conversation (steps, data wiring, conditions, schedules,
+ * assignees, forms), inspects live flow *runs*, and fixes the template when a
+ * run reveals a build mistake. It builds on the editor's Qi Flow engine; the
+ * user instantiates and runs the flow in the portal. The agent never executes,
+ * signs, or holds a key — it only writes flow documents and reads their state.
+ *
+ * It reuses the editor plugin's Matrix provider + readers but contributes its
+ * own flow tools; it does not require the editor plugin to be loaded.
+ *
+ * This module must stay statically LIGHT: `new FlowsPlugin()` happens at
+ * Worker module scope, and the tool builders' module graph (`tools/*` →
+ * actions/translator → `@ixo/editor/core` → `@ixo/matrix-crdt` → vscode-lib)
+ * schedules a timer during module evaluation (vscode-lib's
+ * `IdleValue`/`runWhenIdle`), which workerd forbids in global scope. The tool
+ * modules are therefore reached only via `await import()` inside
+ * `getRequestTools`, which runs per turn inside a Durable Object request
+ * context where timers are allowed.
+ */
+import type { MatrixClient } from 'matrix-js-sdk';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import type {
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+import { FLOWS_PLUGIN_NAME } from './prompts';
+
+export interface FlowsPluginOptions {
+  /** A long-lived Matrix client owned by the host (or a test), shared across rooms. */
+  matrixClient?: MatrixClient;
+}
+
+/**
+ * Discovery surface (returned by `list_capabilities` / `load_capability`). The
+ * `summary` is the one-line teaser; `whenToUse`/`whenNotToUse`/`examples` teach
+ * the agent when and how to load it. The full operating contract lives in
+ * `FLOWS_OPERATING_GUIDE` (prompts.ts), injected into the system prompt once
+ * the capability is loaded — kept out of the manifest so it costs no tokens on
+ * turns where flows is never used.
+ */
+const manifest: PluginManifest = {
+  title: 'Flow Builder',
+  summary:
+    'Build runnable automation flows by conversation. Assemble a reusable flow *template* from action blocks — wiring each step into the next, with conditions, schedules, assignees, and forms — then the user reviews and runs it in the portal. You design and write the flow in planning mode (propose the blocks, confirm, then build); you never execute, sign, or run a step.',
+  whenToUse: [
+    'User wants to build an automation/workflow/flow from steps or actions.',
+    "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/survey on a flow.',
+    'User wants to inspect a flow run, find out why a step failed, and fix the template.',
+  ],
+  whenNotToUse: [
+    'Editing prose/pages/documents (use the editor).',
+    'Actually executing/running/signing a step — that happens in the portal, by the user.',
+  ],
+  examples: [
+    {
+      user: 'Build a flow that emails the applicant when their claim is approved',
+      thought:
+        'Discover the blocks and their requirements first, then propose a plan before writing anything.',
+      tool: 'list_actions',
+      args: { tag: 'claims' },
+    },
+    {
+      user: 'What does the submit-claim step need before I can add it?',
+      tool: 'describe_action',
+      args: { action: 'qi/claim.submit' },
+    },
+    {
+      user: 'Why did the second step of my flow fail?',
+      tool: 'flow_status',
+    },
+  ],
+  tags: ['flows', 'templates', 'automation', 'workflow', 'forms'],
+  category: 'automation',
+  visibility: 'on-demand',
+  stability: 'beta',
+};
+
+export class FlowsPlugin extends OraclePlugin {
+  readonly name = FLOWS_PLUGIN_NAME;
+  readonly version = '0.1.0';
+  readonly manifest = manifest;
+
+  private readonly matrixClient?: MatrixClient;
+
+  constructor(options: FlowsPluginOptions = {}) {
+    super();
+    this.matrixClient = options.matrixClient;
+  }
+
+  override async getRequestTools(
+    _rtCtx: RuntimeContext,
+  ): Promise<PluginTool[]> {
+    // Lazy on purpose — see the module header. The module registry caches the
+    // imports, so only the first turn in an isolate pays for them.
+    const [authoring, discovery, forms, inspect, linkage, settings] =
+      await Promise.all([
+        import('./tools/authoring'),
+        import('./tools/discovery'),
+        import('./tools/forms'),
+        import('./tools/inspect'),
+        import('./tools/linkage'),
+        import('./tools/settings'),
+      ]);
+
+    return [
+      // Discovery
+      discovery.buildListActionsTool(),
+      discovery.buildDescribeActionTool(),
+      discovery.buildListReferenceableFieldsTool(this.matrixClient),
+      // Linkage
+      ...linkage.buildLinkageTools(this.matrixClient),
+      // Inspect
+      inspect.buildReadFlowTool(this.matrixClient),
+      inspect.buildGetStepTool(this.matrixClient),
+      inspect.buildFlowStatusTool(this.matrixClient),
+      inspect.buildExplainStepTool(this.matrixClient),
+      // Authoring
+      ...authoring.buildAuthoringTools(this.matrixClient),
+      // Settings mutators
+      ...settings.buildSettingsTools(this.matrixClient),
+      // Forms
+      ...forms.buildFormTools(this.matrixClient),
+    ];
+  }
+}

package/src/plugins/flows/forms.ts

@@ -0,0 +1,330 @@
+/**
+ * Form read/fill (spec §2.5, §7.2). The agent can read a human form step's
+ * questions and PRE-FILL answers; it never submits — the user reviews and
+ * submits in the portal.
+ *
+ * Verified shape: the survey schema lives in `block.props.surveySchema` (a
+ * JSON-stringified SurveyJS schema); the answers persist in the RUNTIME map at
+ * `runtime.output.form.answers` (a JSON string). Filling writes that runtime
+ * field and deliberately does NOT set `state:'completed'` (submission is the
+ * user's action). We reuse the editor plugin's native survey + runtime helpers.
+ */
+import type { Doc as YDoc } from 'yjs';
+import {
+  extractBlockProperties,
+  getBlockDetail,
+  readRuntimeState,
+  updateRuntimeState,
+  type SurveyElement,
+} from './ydoc-helpers';
+import { setStepInputs } from './edit';
+import { FlowError } from './errors';
+import { inferPortType } from './port-types';
+import { readStep } from './read';
+import { stepIdToBlockId } from './translator';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function safeParseObject(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return undefined;
+  }
+}
+
+export interface FormQuestion {
+  name: string;
+  type: string;
+  title?: string;
+  isRequired: boolean;
+  /** Allowed values for choice questions — the agent must fill the value, not the label. */
+  choices?: Array<{ value: string; text: string }>;
+  visibleIf?: string;
+}
+
+export interface FillFormResult {
+  applied: string[];
+  rejected: Array<{ name: string; reason: string }>;
+  validation: { ok: boolean; warnings: string[] };
+}
+
+function readSurveySchema(
+  doc: YDoc,
+  stepId: string,
+): { blockId: string; questions: FormQuestion[] } {
+  const blockId = stepIdToBlockId(stepId);
+  const detail = getBlockDetail(doc, blockId);
+  if (!detail)
+    throw new FlowError('step_not_found', `No step "${stepId}" in this flow.`);
+  const props = extractBlockProperties(detail);
+
+  // The schema location differs by form mechanism: the `form` block stores it at
+  // top-level `surveySchema`; the `qi/human.form.submit` action stores it inside
+  // `inputs.surveySchema`. Check both. (`extractBlockProperties` may auto-parse a
+  // JSON prop to an object, so a value can arrive as an object or a string.)
+  let raw: unknown = props.surveySchema;
+  if (raw === undefined || raw === null || raw === '') {
+    const inputs = props.inputs;
+    const parsedInputs =
+      typeof inputs === 'string' ? safeParseObject(inputs) : inputs;
+    if (isRecord(parsedInputs)) raw = parsedInputs.surveySchema;
+  }
+  if (typeof raw === 'string' && raw.length > 0) raw = safeParseObject(raw);
+
+  if (!isRecord(raw))
+    throw new FlowError(
+      'validation_failed',
+      `Step "${stepId}" has no form to fill.`,
+    );
+
+  // Accept either the pages form (`{ pages: [{ elements }] }`) or the flat
+  // elements form (`{ elements }`) — SurveyJS renders both.
+  const pages = Array.isArray(raw.pages)
+    ? raw.pages
+    : Array.isArray(raw.elements)
+      ? [{ elements: raw.elements }]
+      : [];
+  return { blockId, questions: flattenQuestions(pages) };
+}
+
+/** Flatten SurveyJS pages -> questions, descending into panels (which carry nested elements). */
+function flattenQuestions(
+  pages: Array<{ elements?: SurveyElement[] }>,
+): FormQuestion[] {
+  const out: FormQuestion[] = [];
+  const visit = (elements: SurveyElement[] | undefined): void => {
+    for (const el of elements ?? []) {
+      if (el.elements || el.templateElements) {
+        visit(el.elements);
+        visit(el.templateElements);
+        continue;
+      }
+      out.push({
+        name: el.name,
+        type: el.type,
+        title: el.title,
+        isRequired: el.isRequired ?? false,
+        choices: el.choices,
+        visibleIf: el.visibleIf,
+      });
+    }
+  };
+  for (const page of pages) visit(page.elements);
+  return out;
+}
+
+/** Read a form step's questions with their exact fillable values. */
+export function describeForm(
+  doc: YDoc,
+  stepId: string,
+): { questions: FormQuestion[] } {
+  const { questions } = readSurveySchema(doc, stepId);
+  return { questions };
+}
+
+/** One referenceable output a form step exposes downstream. */
+export interface FormOutputField {
+  field: string;
+  type: string;
+}
+
+/**
+ * The output fields a form step exposes for downstream references. A form emits
+ * a single bundled output, NOT a field per question:
+ *  - `answers` — the whole answers object,
+ *  - `form.answers` — that object as a JSON string (matches the form block's
+ *    runtime output shape).
+ * Plus, for each question, the load-bearing individual runtime path
+ * `answers.<questionName>`. A scalar input (e.g. a DID for `matrix.dm.targetDid`)
+ * MUST reference the single field — wiring the whole `answers` object stringifies
+ * to "[object Object]" at runtime. The per-question paths resolve because the
+ * form action's `run()` returns `answers` as a real object.
+ *
+ * Returns just the two bundle fields when the step has no readable survey schema
+ * yet (so callers still get a usable answer for an unconfigured form step).
+ */
+export function formOutputFields(doc: YDoc, stepId: string): FormOutputField[] {
+  const fields: FormOutputField[] = [
+    { field: 'answers', type: 'object' },
+    { field: 'form.answers', type: 'string' },
+  ];
+  let questions: FormQuestion[];
+  try {
+    questions = readSurveySchema(doc, stepId).questions;
+  } catch {
+    return fields;
+  }
+  for (const q of questions) {
+    fields.push({ field: `answers.${q.name}`, type: inferPortType(q.name) });
+  }
+  return fields;
+}
+
+/** Existing form answers from the runtime map (if any). */
+function existingAnswers(doc: YDoc, blockId: string): Record<string, unknown> {
+  const runtime = readRuntimeState(doc, blockId)[blockId];
+  const output =
+    runtime && typeof runtime.output === 'object'
+      ? (runtime.output as Record<string, unknown>)
+      : undefined;
+  const form =
+    output && typeof output.form === 'object'
+      ? (output.form as Record<string, unknown>)
+      : undefined;
+  if (typeof form?.answers !== 'string') return {};
+  try {
+    const parsed: unknown = JSON.parse(form.answers);
+    return parsed && typeof parsed === 'object'
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Pre-fill a form step's answers. Validates against the schema (choice questions
+ * accept only declared values), writes `runtime.output.form.answers`, and never
+ * marks the step complete. `merge` (default true) keeps existing answers.
+ */
+export function fillForm(
+  doc: YDoc,
+  stepId: string,
+  answers: Record<string, unknown>,
+  merge = true,
+): FillFormResult {
+  const { blockId, questions } = readSurveySchema(doc, stepId);
+  const byName = new Map(questions.map((q) => [q.name, q]));
+
+  const applied: string[] = [];
+  const rejected: Array<{ name: string; reason: string }> = [];
+  const accepted: Record<string, unknown> = {};
+
+  for (const [name, value] of Object.entries(answers)) {
+    const question = byName.get(name);
+    if (!question) {
+      rejected.push({ name, reason: 'no such question' });
+      continue;
+    }
+    if (question.choices && question.choices.length > 0) {
+      const allowed = question.choices.map((c) => c.value);
+      const values = Array.isArray(value) ? value : [value];
+      const bad = values.find((v) => !allowed.includes(String(v)));
+      if (bad !== undefined) {
+        rejected.push({
+          name,
+          reason: `"${String(bad)}" is not an allowed value`,
+        });
+        continue;
+      }
+    }
+    accepted[name] = value;
+    applied.push(name);
+  }
+
+  const base = merge ? existingAnswers(doc, blockId) : {};
+  const finalAnswers = { ...base, ...accepted };
+
+  doc.transact(() => {
+    const runtime = readRuntimeState(doc, blockId)[blockId] ?? {};
+    const output =
+      runtime.output && typeof runtime.output === 'object'
+        ? (runtime.output as Record<string, unknown>)
+        : {};
+    const form =
+      output.form && typeof output.form === 'object'
+        ? (output.form as Record<string, unknown>)
+        : {};
+    // Write answers only — never set state:'completed' (that is the user's submit).
+    updateRuntimeState(doc, blockId, {
+      output: {
+        ...output,
+        form: { ...form, answers: JSON.stringify(finalAnswers) },
+      },
+    });
+  });
+
+  const requiredMissing = questions
+    .filter((q) => q.isRequired && !(q.name in finalAnswers))
+    .map((q) => q.name);
+  const warnings =
+    requiredMissing.length > 0
+      ? [`Required questions still unanswered: ${requiredMissing.join(', ')}`]
+      : [];
+
+  return {
+    applied,
+    rejected,
+    validation: { ok: rejected.length === 0, warnings },
+  };
+}
+
+// ── Authoring a form's questions (build time) ───────────────────────────────
+
+/** One question the agent wants on a form (friendly shape — no SurveyJS internals). */
+export interface FormQuestionInput {
+  /** The answer key this question produces (referenced downstream as output.<name>). */
+  name: string;
+  /** The question text shown to the user (defaults to the name). */
+  label?: string;
+  /**
+   * Question type. Common SurveyJS types: text (default), comment (multi-line),
+   * dropdown, radiogroup, checkbox (multi-select), boolean, rating.
+   */
+  type?: string;
+  required?: boolean;
+  /** Allowed options for choice questions (dropdown/radiogroup/checkbox). */
+  choices?: string[];
+}
+
+/** Build a SurveyJS schema (pages form) from friendly questions. */
+function buildSurveyJs(questions: FormQuestionInput[]): {
+  pages: Array<{ name: string; elements: Array<Record<string, unknown>> }>;
+} {
+  return {
+    pages: [
+      {
+        name: 'page1',
+        elements: questions.map((q) => {
+          const element: Record<string, unknown> = {
+            type: q.type && q.type.length > 0 ? q.type : 'text',
+            name: q.name,
+            title: q.label ?? q.name,
+          };
+          if (q.required) element.isRequired = true;
+          if (q.choices && q.choices.length > 0)
+            element.choices = q.choices.map((c) => ({ value: c, text: c }));
+          return element;
+        }),
+      },
+    ],
+  };
+}
+
+/**
+ * Author a form step's questions. Builds a SurveyJS schema from the friendly
+ * questions and writes it to the step's `surveySchema` input (where the
+ * `qi/human.form.submit` action reads it). Without this a form step shows
+ * "Configure Survey Schema JSON…" and cannot run — this is how the agent
+ * actually defines the form, not just adds an empty form step.
+ */
+export function setFormSchema(
+  doc: YDoc,
+  roomId: string,
+  stepId: string,
+  questions: FormQuestionInput[],
+): { questionCount: number } {
+  const step = readStep(doc, roomId, stepId);
+  if (!step)
+    throw new FlowError('step_not_found', `No step "${stepId}" in this flow.`);
+  const survey = buildSurveyJs(questions);
+  // Preserve any existing inputs; surveySchema is stored as a JSON string.
+  setStepInputs(doc, stepId, {
+    ...(step.inputs ?? {}),
+    surveySchema: JSON.stringify(survey),
+  });
+  return { questionCount: questions.length };
+}

package/src/plugins/flows/index.ts

@@ -0,0 +1,2 @@
+export { FlowsPlugin, type FlowsPluginOptions } from './flows.plugin';
+export { FLOWS_PLUGIN_NAME, FLOWS_OPERATING_GUIDE } from './prompts';

package/src/plugins/flows/linkage.ts

@@ -0,0 +1,147 @@
+/**
+ * Typed wiring checks (spec §3.2). Powered by the action output schemas + the
+ * port-type inference (port-types.ts) and the metadata overlay (§7.5).
+ *
+ * Input ports aren't shipped by the registry, so `check_link`'s primary job is
+ * catching a reference to an output field a step doesn't actually produce; it
+ * additionally rejects a type mismatch when both sides resolve to a known core
+ * port type (the input side via an overlay entry).
+ */
+import type { Doc as YDoc } from 'yjs';
+import type { ActionDefinition } from '@ixo/editor/core';
+import { getAllActions } from '@ixo/editor/core';
+import { ACTION_METADATA, type ActionRequirement } from './action-metadata';
+import { getActionDef, isFormAction } from './actions';
+import { formOutputFields } from './forms';
+import { inferPortType, isCorePortType } from './port-types';
+import { readFlowSpec } from './read';
+
+export interface LinkCheck {
+  ok: boolean;
+  reason?: string;
+  warning?: string;
+}
+
+export interface CompatibleProducer {
+  action: string;
+  field: string;
+  type: string;
+}
+
+/** Output port type for a field of an action: overlay override, else inference. */
+function outputPortType(
+  def: ActionDefinition,
+  field: string,
+): string | undefined {
+  const overlay = ACTION_METADATA[def.type]?.outputPorts?.find(
+    (p) => p.path === field,
+  );
+  if (overlay) return overlay.portType;
+  const out = def.outputSchema?.find(
+    (f: { path: string; type: string }) => f.path === field,
+  );
+  return out ? inferPortType(field, out.type) : undefined;
+}
+
+/** Declared input port type for an action's input — only available from the overlay. */
+function overlayInputPortType(
+  actionType: string,
+  input: string,
+): string | undefined {
+  return ACTION_METADATA[actionType]?.inputPorts?.find((p) => p.path === input)
+    ?.portType;
+}
+
+/** The port type an input expects: overlay if declared, else inferred from the input name. */
+function expectedInputType(actionType: string, input: string): string {
+  return overlayInputPortType(actionType, input) ?? inferPortType(input);
+}
+
+/** Can `fromStep.field` feed `toStep.input`? */
+export function checkLink(
+  doc: YDoc,
+  ref: string,
+  fromStep: string,
+  field: string,
+  toStep: string,
+  input: string,
+): LinkCheck {
+  const flow = readFlowSpec(doc, ref);
+  if (!flow) return { ok: false, reason: 'That flow does not exist.' };
+
+  const from = flow.steps.find((s) => s.id === fromStep);
+  const to = flow.steps.find((s) => s.id === toStep);
+  if (!from)
+    return { ok: false, reason: `No step "${fromStep}" in this flow.` };
+  if (!to) return { ok: false, reason: `No step "${toStep}" in this flow.` };
+
+  const fromDef = getActionDef(from.action);
+  if (!fromDef)
+    return { ok: false, reason: `Step "${fromStep}" has an unknown action.` };
+
+  let outType = outputPortType(fromDef, field);
+  // A form step's outputSchema only declares the bundled `answers`/`form.answers`
+  // ports, so the individual `answers.<questionName>` paths fall through here.
+  // Validate them against the step's actual survey schema and infer the type.
+  if (outType === undefined && isFormAction(fromDef)) {
+    outType = formOutputFields(doc, fromStep).find(
+      (f) => f.field === field,
+    )?.type;
+  }
+  if (outType === undefined) {
+    return {
+      ok: false,
+      reason: `Step "${fromStep}" does not produce an output field "${field}".`,
+    };
+  }
+
+  // Input side is only typed when the overlay declares it; otherwise accept and note.
+  const declaredInput = overlayInputPortType(to.action, input);
+  if (declaredInput === undefined) {
+    return {
+      ok: true,
+      warning: `"${input}" has no declared type, so the value type was not verified.`,
+    };
+  }
+  if (outType === declaredInput) return { ok: true };
+  if (isCorePortType(outType) && isCorePortType(declaredInput)) {
+    return {
+      ok: false,
+      reason: `Type mismatch: "${field}" is ${outType} but "${input}" expects ${declaredInput}.`,
+    };
+  }
+  return {
+    ok: true,
+    warning: `Could not confirm ${outType} is compatible with ${declaredInput}.`,
+  };
+}
+
+/** Actions (and the field) that produce a value compatible with a step's input. */
+export function compatibleActions(
+  doc: YDoc,
+  ref: string,
+  stepId: string,
+  forInput: string,
+): CompatibleProducer[] {
+  const flow = readFlowSpec(doc, ref);
+  const step = flow?.steps.find((s) => s.id === stepId);
+  const wanted = step
+    ? expectedInputType(step.action, forInput)
+    : inferPortType(forInput);
+
+  const out: CompatibleProducer[] = [];
+  for (const def of getAllActions()) {
+    for (const f of def.outputSchema ?? []) {
+      const type = outputPortType(def, f.path);
+      if (type === wanted) out.push({ action: def.type, field: f.path, type });
+    }
+  }
+  return out;
+}
+
+/** Declarative prerequisites of an action (overlay-backed). */
+export function requirements(action: string): ActionRequirement[] {
+  const def = getActionDef(action);
+  if (!def) return [];
+  return ACTION_METADATA[def.type]?.requires ?? [];
+}

package/src/plugins/flows/port-types.ts

@@ -0,0 +1,53 @@
+/**
+ * Semantic port types (spec §5/§7.5). Actions don't ship typed input/output
+ * ports, so we infer a semantic type from the field name (a documented core
+ * vocabulary), with the metadata overlay as the authoritative override.
+ *
+ * Open vocabulary: an unrecognised field falls back to its primitive type.
+ */
+export const CORE_PORT_TYPES = [
+  'did',
+  'entityDid',
+  'chainAddress',
+  'transactionHash',
+  'claimId',
+  'claimCollectionId',
+  'roomId',
+  'messageId',
+  'eventId',
+  'proposalId',
+  'bidId',
+  'invoiceId',
+] as const;
+
+const CORE = new Set<string>(CORE_PORT_TYPES);
+
+/** Field-name (leaf) patterns -> semantic port type. Order matters (most specific first). */
+const PATTERNS: Array<[RegExp, string]> = [
+  [/transactionhash$/i, 'transactionHash'],
+  [/entitydid$/i, 'entityDid'],
+  [/collectionid$/i, 'claimCollectionId'],
+  [/claimid$/i, 'claimId'],
+  [/proposalid$/i, 'proposalId'],
+  [/invoiceid$/i, 'invoiceId'],
+  [/bidid$/i, 'bidId'],
+  [/roomid$/i, 'roomId'],
+  [/messageid$/i, 'messageId'],
+  [/eventid$/i, 'eventId'],
+  [/(^|[a-z])did$/i, 'did'],
+  [/address$/i, 'chainAddress'],
+];
+
+/** Whether a port type is part of the documented core (i.e. safe to enforce on a mismatch). */
+export function isCorePortType(type: string): boolean {
+  return CORE.has(type);
+}
+
+/** Infer a semantic port type from a field path, falling back to the primitive type. */
+export function inferPortType(path: string, primitive?: string): string {
+  const leaf = path.split('.').pop() ?? path;
+  for (const [pattern, type] of PATTERNS) {
+    if (pattern.test(leaf)) return type;
+  }
+  return primitive ?? 'string';
+}