@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/flows/translator.ts

@@ -0,0 +1,328 @@
+/**
+ * The FlowSpec <-> BaseUcanFlow translator — the one module where the editor's
+ * internals could leak, so it is small and exhaustively tested. It maps the
+ * friendly FlowSpec (types.ts) onto the verified `BaseUcanFlow`/`FlowCapability`
+ * shape and back.
+ *
+ * Two deliberate decisions, both load-bearing (see spec §2.3, §7.1):
+ *  - Sequencing is `capabilities[]` ORDER + data references. `after` is ordering
+ *    only; `onEvent` is the advanced event-trigger path.
+ *  - Conditions are NEVER routed through `capability.condition`. The compiler
+ *    writes that operator verbatim and the FE evaluator can't read it, so a
+ *    condition authored that way never fires. Instead we build the compiled
+ *    `props.conditions` JSON directly, in the evaluator's operator vocabulary,
+ *    and the edit layer writes it onto the block. `buildConditionsProp` /
+ *    `parseConditionsProp` own that mapping.
+ */
+import type {
+  BaseUcanFlow,
+  FlowCapability,
+  TriggerSpec,
+} from '@ixo/editor/core';
+import { canToType, getActionByCan, typeToCan } from '@ixo/editor/core';
+import { FlowError } from './errors';
+import type { Condition, FlowSpecInput, FlowStep } from './types';
+
+/** The compiler's block-id convention (verified: `generateBlockId`). */
+export const BLOCK_ID_PREFIX = 'flow_block_';
+export const stepIdToBlockId = (stepId: string): string =>
+  `${BLOCK_ID_PREFIX}${stepId}`;
+export const blockIdToStepId = (blockId: string): string =>
+  blockId.startsWith(BLOCK_ID_PREFIX)
+    ? blockId.slice(BLOCK_ID_PREFIX.length)
+    : blockId;
+
+/** Friendly condition operator -> the FE evaluator's exact operator string. */
+const OP_TO_EVALUATOR: Record<Condition['is'], string> = {
+  equals: 'equals',
+  notEquals: 'not_equals',
+  greaterThan: 'greater_than',
+  lessThan: 'less_than',
+  contains: 'contains',
+  isEmpty: 'is_empty',
+  isNotEmpty: 'is_not_empty',
+};
+const EVALUATOR_TO_OP: Record<string, Condition['is']> = Object.fromEntries(
+  Object.entries(OP_TO_EVALUATOR).map(([friendly, evaluator]) => [
+    evaluator,
+    friendly as Condition['is'],
+  ]),
+);
+
+const REF_PATTERN = /^\{\{\s*(.+?)\s*\}\}$/;
+
+/**
+ * Data refs cross an id boundary. The agent works in STEP ids
+ * ("fill-form.output.answers.did"), but the flow engine resolves a `$ref` by
+ * calling `runtime.get(<id>)`, and the runtime is keyed by the BLOCK id
+ * (`flow_block_<stepId>`). So the stored `$ref` must carry the block id, or the
+ * engine reads `runtime.get("fill-form")` (empty) and the input resolves to
+ * nothing. These translate the id half of an "<id>.output.<path>" ref; non-output
+ * refs (e.g. `trigger.payload.*`) pass through untouched.
+ */
+function stepRefToBlockRef(ref: string): string {
+  const i = ref.indexOf('.output.');
+  if (i <= 0) return ref;
+  return `${stepIdToBlockId(ref.slice(0, i))}${ref.slice(i)}`;
+}
+function blockRefToStepRef(ref: string): string {
+  const i = ref.indexOf('.output.');
+  if (i <= 0) return ref;
+  const id = ref.slice(0, i);
+  return id.startsWith(BLOCK_ID_PREFIX)
+    ? `${id.slice(BLOCK_ID_PREFIX.length)}${ref.slice(i)}`
+    : ref;
+}
+
+/**
+ * Rewrite every embedded "{{ <id>.output.<path> }}" placeholder inside a template
+ * string, mapping the id half with `mapRef` (`stepRefToBlockRef` outbound,
+ * `blockRefToStepRef` inbound). A *standalone* ref becomes a `{ $ref }` (handled
+ * above) so the engine resolves it as a typed value; an *embedded* ref lives in a
+ * larger string — e.g. an oracle `prompt` ("Employee {{x.output.answers.name}}
+ * submitted ..."). The engine only resolves `$ref` objects, so these placeholders
+ * are filled downstream against the same block-id-keyed runtime state; they must
+ * therefore carry the block id, or every "{{...}}" resolves to an empty string.
+ * Non-output tokens (handlebars helpers like `{{#if}}`, `trigger.payload.*`)
+ * contain no ".output." and pass through untouched.
+ */
+function rewriteEmbeddedRefs(
+  text: string,
+  mapRef: (ref: string) => string,
+): string {
+  return text.replace(
+    /(\{\{\s*)([^{}]+?)(\s*\}\})/g,
+    (_full, open: string, ref: string, close: string) =>
+      `${open}${mapRef(ref)}${close}`,
+  );
+}
+
+/** Resolve a friendly action name (registry `type`) to its `can` ability string. */
+export function actionToCan(action: string): string {
+  const can = typeToCan(action);
+  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`). */
+export function canToAction(can: string): string {
+  return canToType(can) ?? can;
+}
+
+/** A `{ $ref: string }` runtime reference — the only shape the engine resolves. */
+function isRuntimeRef(value: unknown): value is { $ref: string } {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    '$ref' in value &&
+    typeof value.$ref === 'string'
+  );
+}
+
+/**
+ * Convert a single friendly value into its `nb` form, recursing through objects
+ * and arrays. A "{{step-id.output.field}}" string becomes a `{ $ref }`; every
+ * other value passes through. Recursion matters because the engine's
+ * `resolveRuntimeRefs` resolves `$ref` at any depth — a nested mustache string
+ * (e.g. inside an email `variables` map) would otherwise ship verbatim.
+ */
+function friendlyValueToNb(value: unknown): unknown {
+  if (typeof value === 'string') {
+    const match = REF_PATTERN.exec(value);
+    if (match?.[1]) return { $ref: stepRefToBlockRef(match[1]) };
+    return value.includes('{{')
+      ? rewriteEmbeddedRefs(value, stepRefToBlockRef)
+      : value;
+  }
+  if (Array.isArray(value)) return value.map(friendlyValueToNb);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      out[key] = friendlyValueToNb(val);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Convert a single `nb` value back to its friendly form (reverse + recursive). */
+function nbValueToFriendly(value: unknown): unknown {
+  if (isRuntimeRef(value)) return `{{${blockRefToStepRef(value.$ref)}}}`;
+  if (typeof value === 'string')
+    return value.includes('{{')
+      ? rewriteEmbeddedRefs(value, blockRefToStepRef)
+      : value;
+  if (Array.isArray(value)) return value.map(nbValueToFriendly);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      out[key] = nbValueToFriendly(val);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Convert friendly inputs into capability `nb`. A value written as
+ * "{{step-id.output.field}}" becomes a `{ $ref }` (the BaseUcanFlow ref form);
+ * everything else passes through as a literal. Nested objects/arrays are walked
+ * so refs inside maps (e.g. email `variables`) resolve at execution too.
+ */
+export function friendlyInputsToNb(
+  inputs: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!inputs) return undefined;
+  const nb: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(inputs)) {
+    nb[key] = friendlyValueToNb(value);
+  }
+  return nb;
+}
+
+/** Reverse of {@link friendlyInputsToNb}: `{ $ref }` -> "{{...}}", recursively. */
+export function nbToFriendlyInputs(
+  nb: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!nb || Object.keys(nb).length === 0) return undefined;
+  const inputs: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(nb)) {
+    inputs[key] = nbValueToFriendly(value);
+  }
+  return inputs;
+}
+
+/** Build the compiled `props.conditions` JSON string in the FE evaluator's vocabulary. */
+export function buildConditionsProp(conditions: Condition[]): string {
+  return JSON.stringify({
+    enabled: true,
+    mode: 'all_must_pass',
+    conditions: conditions.map((c) => ({
+      id: `cond_${c.fromStep}_${c.field}`,
+      name: `Condition from ${c.fromStep}`,
+      sourceBlockId: stepIdToBlockId(c.fromStep),
+      sourceBlockType: 'action',
+      rule: {
+        type: 'property_value',
+        property: c.field,
+        operator: OP_TO_EVALUATOR[c.is],
+        value: c.value,
+      },
+      effect: { action: 'enable' },
+    })),
+  });
+}
+
+/**
+ * Parse a compiled `props.conditions` JSON string back into friendly
+ * Conditions. Defensive: returns [] on anything unparseable. `blockToStep`
+ * maps a source block id back to a step id (falls back to stripping the
+ * `flow_block_` prefix).
+ */
+export function parseConditionsProp(
+  raw: unknown,
+  blockToStep?: (blockId: string) => string,
+): Condition[] {
+  if (typeof raw !== 'string' || raw.length === 0) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  const list = (parsed as { conditions?: unknown }).conditions;
+  if (!Array.isArray(list)) return [];
+  const resolveStep = blockToStep ?? blockIdToStepId;
+  const out: Condition[] = [];
+  for (const entry of list) {
+    const rule = (entry as { rule?: Record<string, unknown> }).rule;
+    const sourceBlockId = (entry as { sourceBlockId?: unknown }).sourceBlockId;
+    if (!rule || typeof sourceBlockId !== 'string') continue;
+    const friendlyOp = EVALUATOR_TO_OP[String(rule.operator)];
+    if (!friendlyOp) continue;
+    out.push({
+      fromStep: resolveStep(sourceBlockId),
+      field: String(rule.property),
+      is: friendlyOp,
+      value: rule.value,
+    });
+  }
+  return out;
+}
+
+function triggerForStep(step: FlowStep): TriggerSpec | undefined {
+  if (step.onEvent) {
+    return {
+      type: 'block.event',
+      // Plan-level triggers carry the STEP id; the editor compiler remaps it to
+      // the block id (flow_block_<stepId>) when writing the compiled `props.trigger`.
+      sourceBlockId: step.onEvent.fromStep,
+      eventName: step.onEvent.event,
+    };
+  }
+  if (step.trigger === 'flow-start') return { type: 'flow.start' };
+  if (step.trigger === 'manual') return { type: 'manual' };
+  return undefined;
+}
+
+function ttlForStep(step: FlowStep): FlowCapability['ttl'] | undefined {
+  if (!step.due) return undefined;
+  const ttl: NonNullable<FlowCapability['ttl']> = {};
+  if (step.due.at) ttl.absoluteDueDate = step.due.at;
+  if (step.due.within) ttl.fromEnablement = step.due.within;
+  if (step.due.afterCommitment) ttl.fromCommitment = step.due.afterCommitment;
+  if (step.commitTo) ttl.fromCommitment = step.commitTo;
+  return Object.keys(ttl).length > 0 ? ttl : undefined;
+}
+
+function actorForStep(step: FlowStep): FlowCapability['actor'] | undefined {
+  if (!step.assignTo) return undefined;
+  return { authorisedActors: [step.assignTo] };
+}
+
+/** Translate one step into a FlowCapability (without conditions — see module note). */
+export function stepToCapability(
+  step: FlowStep,
+  flowId: string,
+): FlowCapability {
+  const cap: FlowCapability = {
+    id: step.id,
+    can: actionToCan(step.action),
+    with: `ixo:flow:${flowId}:${step.id}`,
+  };
+  const nb = friendlyInputsToNb(step.inputs);
+  if (nb) cap.nb = nb;
+  if (step.title) cap.title = step.title;
+  if (step.description) cap.description = step.description;
+  if (step.phase) cap.phase = step.phase;
+  const trigger = triggerForStep(step);
+  if (trigger) cap.trigger = trigger;
+  const ttl = ttlForStep(step);
+  if (ttl) cap.ttl = ttl;
+  const actor = actorForStep(step);
+  if (actor) cap.actor = actor;
+  return cap;
+}
+
+/**
+ * Translate a FlowSpec into a BaseUcanFlow. Capability order follows step
+ * order (the engine's sequencing primitive). Conditions are NOT emitted here;
+ * the caller writes `props.conditions` directly via the edit layer.
+ */
+export function flowSpecToBaseUcan(
+  spec: FlowSpecInput,
+  opts: { flowId: string; ownerDid?: string },
+): BaseUcanFlow {
+  const plan: BaseUcanFlow = {
+    kind: 'qi.flow.base-ucan',
+    version: '1.0',
+    flowId: opts.flowId,
+    title: spec.title,
+    capabilities: spec.steps.map((step) => stepToCapability(step, opts.flowId)),
+  };
+  if (spec.goal) plan.goal = spec.goal;
+  if (opts.ownerDid) plan.meta = { rootIssuer: opts.ownerDid };
+  return plan;
+}

package/src/plugins/flows/types.ts

@@ -0,0 +1,210 @@
+/**
+ * The FlowSpec model — the friendly, leak-proof projection of the editor's
+ * `BaseUcanFlow` that the agent operates on. No tool I/O ever mentions a
+ * block, Y.Doc, `can`/`with`, CAR/CID, delegation, or `nb`; the agent thinks
+ * in steps / actions / inputs / conditions / schedules / forms.
+ *
+ * `translator.ts` owns the FlowSpec <-> BaseUcanFlow projection. These zod
+ * schemas are the contract for every tool's input; the read path returns the
+ * same shape augmented with a read-only `status`.
+ */
+import { z } from 'zod';
+
+/**
+ * Condition operators, aligned 1:1 with the FE condition evaluator's
+ * vocabulary (see translator's CONDITION_OP_TO_EVALUATOR). We deliberately do
+ * NOT expose the compiler's `eq`/`neq`/... vocabulary — those never evaluate
+ * because no normalizer maps them to the evaluator's strings.
+ */
+export const CONDITION_OPERATORS = [
+  'equals',
+  'notEquals',
+  'greaterThan',
+  'lessThan',
+  'contains',
+  'isEmpty',
+  'isNotEmpty',
+] as const;
+
+export const conditionSchema = z.object({
+  fromStep: z
+    .string()
+    .describe('Id of the upstream step whose value is checked.'),
+  field: z.string().describe('Field on the upstream step to inspect.'),
+  is: z.enum(CONDITION_OPERATORS).describe('Comparison operator.'),
+  value: z
+    .unknown()
+    .optional()
+    .describe('Value to compare against (omit for isEmpty/isNotEmpty).'),
+});
+
+export const hookSchema = z.object({
+  type: z.enum(['sendEmail', 'addLinkedEntity', 'sendMatrixDM']),
+  config: z.record(z.string(), z.unknown()),
+});
+
+export const dueSchema = z.object({
+  at: z.string().optional().describe('Absolute due date (ISO 8601).'),
+  within: z
+    .string()
+    .optional()
+    .describe(
+      'Duration from when the step becomes active (ISO 8601 duration).',
+    ),
+  afterCommitment: z
+    .string()
+    .optional()
+    .describe('Duration from commitment (ISO 8601 duration).'),
+});
+
+export const onEventSchema = z.object({
+  fromStep: z.string().describe('Upstream step that emits the event.'),
+  event: z.string().describe('Event name the upstream step emits.'),
+});
+
+/**
+ * A single step the agent authors. Mirrors FlowStep in the spec (§2.1). The
+ * read-only `status` is intentionally absent here — agents never write it; it
+ * is only attached on read (see FlowStepRead).
+ */
+export const flowStepSchema = z.object({
+  id: z
+    .string()
+    .min(1)
+    .describe('Stable, human-readable step id, e.g. "load-batches".'),
+  action: z
+    .string()
+    .min(1)
+    .describe('Action name from list_actions (e.g. "qi/email.send").'),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  phase: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Stable semantic group for this step, such as "discovery" or "deployment".',
+    ),
+  execution: z
+    .enum(['human-only', 'agent-capable'])
+    .optional()
+    .describe(
+      'Whether only a person may run this step or a suitably skilled, authorised Flow Agent may run it.',
+    ),
+
+  inputs: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe(
+      'Inputs for the action. A value may be a reference to an upstream output, written as "{{step-id.output.field}}".',
+    ),
+  form: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe(
+      'For human form steps: pre-filled answers keyed by question name. Pre-fill only — the user submits in the portal.',
+    ),
+
+  after: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Order this step after the named steps. Pair with an input reference for a real data dependency. This is ordering only, not an auto-trigger.',
+    ),
+  runWhen: conditionSchema
+    .optional()
+    .describe(
+      'Gate this step on an upstream value (static configuration only).',
+    ),
+  conditions: z
+    .array(conditionSchema)
+    .optional()
+    .describe('Multiple activation gates (all must pass).'),
+  onEvent: onEventSchema
+    .optional()
+    .describe(
+      'Advanced: auto-trigger this step when an upstream step emits an event. Only valid for event-capable upstream actions; validate_flow enforces this.',
+    ),
+
+  trigger: z
+    .enum(['manual', 'flow-start'])
+    .optional()
+    .describe('When the step runs. Default "manual".'),
+  due: dueSchema.optional(),
+
+  assignTo: z
+    .string()
+    .optional()
+    .describe('Assignee (a DID or known alias) — metadata only.'),
+  commitTo: z
+    .string()
+    .optional()
+    .describe('Commitment window (ISO 8601 duration).'),
+
+  on: z
+    .record(z.string(), z.array(hookSchema))
+    .optional()
+    .describe('Lifecycle hooks: event name -> hooks.'),
+  skills: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Governed skill ids required for agent-capable execution. The first is used for Flow Agent matching.',
+    ),
+  requireConfirmation: z
+    .boolean()
+    .optional()
+    .describe('Hint the portal to force a confirmation before this step runs.'),
+});
+
+/**
+ * A whole flow as the agent authors it. `ref` is the opaque flow handle; it is
+ * omitted on create and assigned by the plugin.
+ */
+export const flowSpecSchema = z.object({
+  ref: z
+    .string()
+    .optional()
+    .describe('Opaque flow handle. Omit when creating; the plugin assigns it.'),
+  title: z.string().min(1),
+  goal: z.string().optional(),
+  steps: z.array(flowStepSchema),
+});
+
+export type Condition = z.infer<typeof conditionSchema>;
+export type FlowStep = z.infer<typeof flowStepSchema>;
+export type FlowSpecInput = z.infer<typeof flowSpecSchema>;
+
+/** Lifecycle state of a step, read from the runtime map. */
+export type StepState =
+  | 'idle'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'awaiting_readback';
+
+/**
+ * Read-only status derived from the runtime map (§2.6). `state`/`error`/
+ * `lastRunAt` are stored; `blockedBy`/`stale` are computed on read.
+ */
+export interface StepStatus {
+  state: StepState;
+  error?: { message: string; code?: string; at?: number };
+  lastRunAt?: number;
+  /** Upstream step ids that are failed or whose output this step still needs. */
+  blockedBy?: string[];
+  /** Completed but missing its expected proof (e.g. a transaction hash / claim id). */
+  stale?: boolean;
+}
+
+/** A step as returned by read tools: the authored shape plus its read-only status. */
+export type FlowStepRead = FlowStep & { status?: StepStatus };
+
+/** A flow as returned by read tools. */
+export interface FlowSpecRead {
+  ref: string;
+  title: string;
+  goal?: string;
+  steps: FlowStepRead[];
+}