@ixo/oracle-runtime-workers 0.2.0

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

@@ -0,0 +1,516 @@
+/**
+ * Authoring tools. `validate_flow` is a pure compile-without-write.
+ * `create_template`/`add_step` go through the editor's compiler (`setupFlowFromBaseUcan`,
+ * which manages its own doc and syncs to the room). The remaining mutators are
+ * thin wrappers over the tested per-block edit functions (edit.ts).
+ *
+ * Conditions are applied as a post-pass via the direct `props.conditions` write
+ * (setStepConditions) — never through the compiler's `cap.condition`, which
+ * never evaluates (translator.ts).
+ */
+import {
+  compileBaseUcanFlow,
+  getActionByCan,
+  setupFlowFromBaseUcan,
+} from '@ixo/editor/core';
+import type { MatrixClient } from 'matrix-js-sdk';
+import type { Doc as YDoc } from 'yjs';
+import { z } from 'zod';
+import { tool } from '../../../plugin-api/tool-helper';
+import type { PluginTool, RuntimeContext } from '../../../plugin-api/types';
+import { getActionDef, isEventCapable } from '../actions';
+import {
+  removeStep,
+  reorderStep,
+  setStepAssignment,
+  setStepConditions,
+  setStepConfirmation,
+  setStepEventTrigger,
+  setStepExecution,
+  setStepInputs,
+  setStepPhase,
+  setStepSchedule,
+  setStepSkills,
+  setStepTrigger,
+  updateFlowMeta,
+} from '../edit';
+import { FlowError, toToolError } from '../errors';
+import {
+  requireRoomMembership,
+  resolveFlowRef,
+  resolveFlowsMatrixClient,
+  withFlowDoc,
+} from '../flow-doc';
+import { readStep } from '../read';
+import { flowSpecToBaseUcan } from '../translator';
+import {
+  flowSpecSchema,
+  flowStepSchema,
+  type Condition,
+  type FlowSpecInput,
+  type FlowStep,
+} from './../types';
+
+const base = {
+  flowRef: z
+    .string()
+    .optional()
+    .describe('Which flow. Omit to use the flow that is currently open.'),
+};
+const ok = { ok: true } as const;
+
+/** All conditions declared on a step (runWhen folded with conditions[]). */
+function conditionsOf(step: FlowStep): Condition[] {
+  return [...(step.runWhen ? [step.runWhen] : []), ...(step.conditions ?? [])];
+}
+
+/** onEvent must point at an event-capable upstream action. Returns error strings. */
+function eventCapabilityErrors(flow: FlowSpecInput): string[] {
+  const errors: string[] = [];
+  for (const step of flow.steps) {
+    if (!step.onEvent) continue;
+    const source = flow.steps.find((s) => s.id === step.onEvent?.fromStep);
+    if (!source) {
+      errors.push(
+        `Step "${step.id}" triggers on an unknown step "${step.onEvent.fromStep}".`,
+      );
+      continue;
+    }
+    const def = getActionDef(source.action);
+    if (def && !isEventCapable(def)) {
+      errors.push(
+        `Step "${step.id}" auto-triggers on "${source.id}", but its action "${source.action}" cannot emit events. ` +
+          'Use ordering (after) + an input reference instead.',
+      );
+    }
+  }
+  return errors;
+}
+
+const validateSchema = z.object({ flow: flowSpecSchema });
+
+function buildValidateFlowTool(): PluginTool {
+  return tool(
+    async (args) => {
+      try {
+        const { flow } = validateSchema.parse(args);
+        const errors = eventCapabilityErrors(flow);
+        if (errors.length === 0) {
+          // Surfaces the compiler's exact messages (duplicate id, unknown action, trigger cycle, ...).
+          try {
+            compileBaseUcanFlow(
+              flowSpecToBaseUcan(flow, { flowId: flow.ref ?? 'validate' }),
+              { getActionByCan },
+            );
+          } catch (err) {
+            errors.push(err instanceof Error ? err.message : String(err));
+          }
+        }
+        return { ok: errors.length === 0, errors, warnings: [] };
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      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.',
+      schema: validateSchema,
+    },
+  );
+}
+
+/** Apply each step's conditions to an already-authored flow room (post-pass). */
+async function applyConditions(
+  ctx: RuntimeContext,
+  flowRef: string,
+  matrixClient: MatrixClient | undefined,
+  steps: FlowStep[],
+): Promise<void> {
+  const withConditions = steps.filter((s) => conditionsOf(s).length > 0);
+  if (withConditions.length === 0) return;
+  await withFlowDoc(ctx, flowRef, matrixClient, async (doc) => {
+    for (const step of withConditions)
+      setStepConditions(doc, step.id, conditionsOf(step));
+  });
+}
+
+/**
+ * Apply each step's assignee to an already-authored flow room (post-pass).
+ * The compiler only writes the authorization whitelist; the assignee the portal
+ * shows + nudges lives in `props.assignment`, written by setStepAssignment.
+ */
+async function applyAssignments(
+  ctx: RuntimeContext,
+  flowRef: string,
+  matrixClient: MatrixClient | undefined,
+  steps: FlowStep[],
+): Promise<void> {
+  const withAssignee = steps.filter((s) => s.assignTo);
+  if (withAssignee.length === 0) return;
+  await withFlowDoc(ctx, flowRef, matrixClient, async (doc) => {
+    for (const step of withAssignee)
+      setStepAssignment(doc, step.id, step.assignTo);
+  });
+}
+
+/** Apply Flow Agent execution boundaries and governed skill matching metadata. */
+async function applyExecutionPolicy(
+  ctx: RuntimeContext,
+  flowRef: string,
+  matrixClient: MatrixClient | undefined,
+  steps: FlowStep[],
+): Promise<void> {
+  const configured = steps.filter(
+    (step) => step.execution !== undefined || step.skills !== undefined,
+  );
+  if (configured.length === 0) return;
+  await withFlowDoc(ctx, flowRef, matrixClient, async (doc) => {
+    for (const step of configured) {
+      if (step.execution) setStepExecution(doc, step.id, step.execution);
+      if (step.skills) setStepSkills(doc, step.id, step.skills);
+    }
+  });
+}
+
+/**
+ * Allocate the room to author the template into.
+ *
+ * The Node runtime first asks the user's front-end (over its WS browser-tool
+ * channel) to create a dedicated `#template-*` room and invite the oracle.
+ * The Workers runtime has no request/response browser-tool channel — its
+ * `emit.browserToolCall` is a one-way SSE event — so that path does not exist
+ * here: the template is authored into the room the portal already opened
+ * (`state.editorRoomId`, or an explicit `flow.ref`). When a round-trip
+ * browser-tool channel lands on Workers, restore the Node runtime's
+ * `create_template_room` request here.
+ */
+function allocateTemplateRoom(
+  ctx: RuntimeContext,
+  flow: FlowSpecInput,
+): string {
+  return resolveFlowRef(ctx, flow.ref);
+}
+
+function buildCreateTemplateTool(
+  matrixClient: MatrixClient | undefined,
+): PluginTool {
+  const createTemplateSchema = z.object({
+    flow: flowSpecSchema,
+
+    personalSpace: z
+      .boolean()
+      .optional()
+      .describe(
+        'Where to put the template. Default false = the domain the user is currently viewing. ' +
+          'Set true only when the user explicitly asks for their personal/private flows space.',
+      ),
+  });
+  return tool(
+    async (args, ctx: RuntimeContext) => {
+      try {
+        const { flow } = createTemplateSchema.parse(args);
+        const errors = eventCapabilityErrors(flow);
+        if (errors.length > 0)
+          return {
+            ok: false,
+            error: { code: 'validation_failed', message: errors.join(' ') },
+          };
+
+        const client = await resolveFlowsMatrixClient(ctx, matrixClient);
+        const roomId = allocateTemplateRoom(ctx, flow);
+        await requireRoomMembership(ctx, roomId);
+
+        const flowId = `flow-${crypto.randomUUID().slice(0, 8)}`;
+        const plan = flowSpecToBaseUcan(flow, {
+          flowId,
+          ownerDid: ctx.user.did,
+        });
+        await setupFlowFromBaseUcan({
+          plan,
+          roomId,
+          matrixClient: client,
+          creatorDid: ctx.user.did,
+        });
+        await applyConditions(ctx, roomId, matrixClient, flow.steps);
+        await applyAssignments(ctx, roomId, matrixClient, flow.steps);
+        await applyExecutionPolicy(ctx, roomId, matrixClient, flow.steps);
+
+        return { ok: true, flowRef: roomId };
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      name: 'create_template',
+      description:
+        'Create a BRAND-NEW flow template — a reusable blueprint the user instantiates and runs in ' +
+        'the portal. Do NOT use this to change a template that already exists or is currently open — use the editing tools ' +
+        '(add_step, update_step, set_step_*, remove_step, reorder_step, connect_steps), which modify the open template in ' +
+        'place. Validate first with validate_flow.',
+      schema: createTemplateSchema,
+    },
+  );
+}
+
+const addStepSchema = z.object({
+  ...base,
+  step: flowStepSchema,
+  position: z
+    .union([
+      z.number().int().nonnegative(),
+      z.object({ after: z.string() }),
+      z.object({ before: z.string() }),
+    ])
+    .optional()
+    .describe(
+      'Where to place the step: a 0-based index, {after: id}, or {before: id}. Omitted = append.',
+    ),
+});
+
+function buildAddStepTool(matrixClient: MatrixClient | undefined): PluginTool {
+  return tool(
+    async (args, ctx: RuntimeContext) => {
+      try {
+        const { flowRef, step, position } = addStepSchema.parse(args);
+        const roomId = resolveFlowRef(ctx, flowRef);
+        await requireRoomMembership(ctx, roomId);
+        const client = await resolveFlowsMatrixClient(ctx, matrixClient);
+
+        // Read the existing flow id so the merge targets the same document.
+        const flowId = await withFlowDoc(
+          ctx,
+          flowRef,
+          matrixClient,
+          async (doc) => {
+            const value = doc.getMap('qi.flow.meta').get('flowId');
+            return typeof value === 'string' && value.length > 0
+              ? value
+              : `flow-${crypto.randomUUID().slice(0, 8)}`;
+          },
+        );
+
+        const plan = flowSpecToBaseUcan(
+          { title: '', steps: [step] },
+          { flowId, ownerDid: ctx.user.did },
+        );
+        await setupFlowFromBaseUcan({
+          plan,
+          roomId,
+          matrixClient: client,
+          creatorDid: ctx.user.did,
+          strategy: 'merge',
+        });
+        await applyConditions(ctx, roomId, matrixClient, [step]);
+        await applyAssignments(ctx, roomId, matrixClient, [step]);
+        await applyExecutionPolicy(ctx, roomId, matrixClient, [step]);
+
+        if (typeof position === 'number') {
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            reorderStep(doc, step.id, position),
+          );
+        } else if (position) {
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) => {
+            const order = doc
+              .getArray('qi.flow.order')
+              .toArray()
+              .filter((v): v is string => typeof v === 'string');
+            const anchor =
+              'after' in position ? position.after : position.before;
+            const idx = order.indexOf(anchor);
+            if (idx >= 0)
+              reorderStep(doc, step.id, 'after' in position ? idx + 1 : idx);
+          });
+        }
+        return ok;
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      name: 'add_step',
+      description:
+        'Add one step to an existing flow without disturbing the others. Optionally place it at a position.',
+      schema: addStepSchema,
+    },
+  );
+}
+
+const removeSchema = z.object({ ...base, stepId: z.string().min(1) });
+const reorderSchema = z.object({
+  ...base,
+  stepId: z.string().min(1),
+  toIndex: z.number().int().nonnegative(),
+});
+const metaSchema = z.object({
+  ...base,
+  title: z.string().optional(),
+  goal: z.string().optional(),
+});
+const connectSchema = z.object({
+  ...base,
+  fromStep: z.string().min(1),
+  field: z.string().min(1),
+  toStep: z.string().min(1),
+  input: z.string().min(1),
+});
+const stepPatchSchema = flowStepSchema.partial().extend({
+  phase: z
+    .string()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe('Set the step phase, or use null to clear an existing phase.'),
+});
+const updateStepSchema = z.object({
+  ...base,
+  stepId: z.string().min(1),
+  patch: stepPatchSchema,
+});
+
+/** Route an update_step patch to the focused per-block edits. */
+export function applyStepPatch(
+  doc: YDoc,
+  stepId: string,
+  patch: z.infer<typeof stepPatchSchema>,
+): void {
+  if (patch.inputs) setStepInputs(doc, stepId, patch.inputs);
+  if (patch.runWhen !== undefined || patch.conditions !== undefined) {
+    setStepConditions(doc, stepId, [
+      ...(patch.runWhen ? [patch.runWhen] : []),
+      ...(patch.conditions ?? []),
+    ]);
+  }
+  if (patch.due !== undefined || patch.commitTo !== undefined)
+    setStepSchedule(doc, stepId, patch.due, patch.commitTo);
+  if (patch.assignTo !== undefined)
+    setStepAssignment(doc, stepId, patch.assignTo);
+  if (patch.requireConfirmation !== undefined)
+    setStepConfirmation(doc, stepId, patch.requireConfirmation);
+  if (patch.phase !== undefined)
+    setStepPhase(doc, stepId, patch.phase ?? undefined);
+  if (patch.execution !== undefined)
+    setStepExecution(doc, stepId, patch.execution);
+  if (patch.skills !== undefined) setStepSkills(doc, stepId, patch.skills);
+  // Both write the same trigger props; onEvent is the more specific intent.
+  if (patch.onEvent !== undefined)
+    setStepEventTrigger(doc, stepId, patch.onEvent);
+  else if (patch.trigger !== undefined)
+    setStepTrigger(doc, stepId, patch.trigger);
+}
+
+export function buildAuthoringTools(
+  matrixClient: MatrixClient | undefined,
+): PluginTool[] {
+  return [
+    buildValidateFlowTool(),
+    buildCreateTemplateTool(matrixClient),
+    buildAddStepTool(matrixClient),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId } = removeSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc, roomId) =>
+            removeStep(doc, roomId, stepId),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'remove_step',
+        description:
+          'Remove a step from a flow. Rejected if another step still references it (the referrers are named).',
+        schema: removeSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, toIndex } = reorderSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            reorderStep(doc, stepId, toIndex),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'reorder_step',
+        description: 'Move a step to a new 0-based position in the flow.',
+        schema: reorderSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, title, goal } = metaSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            updateFlowMeta(doc, { title, goal }),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'update_flow_meta',
+        description: "Update a flow's title and/or goal.",
+        schema: metaSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, fromStep, field, toStep, input } =
+            connectSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc, roomId) => {
+            const current = readStep(doc, roomId, toStep);
+            if (!current)
+              throw new FlowError(
+                'step_not_found',
+                `No step "${toStep}" in this flow.`,
+              );
+            setStepInputs(doc, toStep, {
+              ...(current.inputs ?? {}),
+              [input]: `{{${fromStep}.output.${field}}}`,
+            });
+          });
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'connect_steps',
+        description:
+          "Wire one step's output into another step's input (a data reference).",
+        schema: connectSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, patch } = updateStepSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            applyStepPatch(doc, stepId, patch),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        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 ' +
+          'clear an onEvent auto-trigger. Set phase to null to clear an existing phase.',
+        schema: updateStepSchema,
+      },
+    ),
+  ];
+}

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

@@ -0,0 +1,119 @@
+/**
+ * Discovery tools (spec §3.1) — enumerate and describe the available actions.
+ * These read only the action catalog, so they never connect to a flow room.
+ */
+import { z } from 'zod';
+import type { MatrixClient } from 'matrix-js-sdk';
+import { tool } from '../../../plugin-api/tool-helper';
+import type { PluginTool, RuntimeContext } from '../../../plugin-api/types';
+import { describeAction, listActions } from '../actions';
+import { toToolError } from '../errors';
+import { withFlowDoc } from '../flow-doc';
+import { listReferenceableFields } from '../references';
+
+const listActionsSchema = z.object({
+  category: z
+    .string()
+    .optional()
+    .describe('Filter to actions in this category.'),
+  tag: z.string().optional().describe('Filter to actions carrying this tag.'),
+});
+
+const describeActionSchema = z.object({
+  action: z.string().min(1).describe('Action name (from list_actions).'),
+});
+
+const referenceableSchema = z.object({
+  flowRef: z
+    .string()
+    .optional()
+    .describe('Which flow. Omit to use the flow that is currently open.'),
+  stepId: z
+    .string()
+    .min(1)
+    .describe(
+      'The step you are wiring data INTO (the downstream/consumer step) — NOT the source. ' +
+        'Returns the outputs of the steps that run before it. Passing the first step returns nothing (nothing runs before it).',
+    ),
+});
+
+export function buildListActionsTool(): PluginTool {
+  return tool(
+    async (args) => {
+      try {
+        const { category, tag } = listActionsSchema.parse(args);
+        return { actions: listActions({ category, tag }) };
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      name: 'list_actions',
+      description:
+        'List the actions available to use as steps in a flow. Optionally filter by category or tag. ' +
+        'Returns each action with a short summary and when to use it.',
+      schema: listActionsSchema,
+    },
+  );
+}
+
+export function buildDescribeActionTool(): PluginTool {
+  return tool(
+    async (args) => {
+      try {
+        const { action } = describeActionSchema.parse(args);
+        const description = describeAction(action);
+        if (!description) {
+          return {
+            ok: false,
+            error: {
+              code: 'unknown_action',
+              message: `Unknown action "${action}".`,
+            },
+          };
+        }
+        return description;
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      name: 'describe_action',
+      description:
+        'Get the full friendly spec of one action: its summary, inputs, outputs, the events it can emit, ' +
+        'the lifecycle hooks it supports, and whether it is a form. Use before adding a step to know how to configure it.',
+      schema: describeActionSchema,
+    },
+  );
+}
+
+export function buildListReferenceableFieldsTool(
+  matrixClient: MatrixClient | undefined,
+): PluginTool {
+  return tool(
+    async (args, ctx: RuntimeContext) => {
+      try {
+        const { flowRef, stepId } = referenceableSchema.parse(args);
+        return await withFlowDoc(
+          ctx,
+          flowRef,
+          matrixClient,
+          async (doc, roomId) => ({
+            fields: listReferenceableFields(doc, roomId, stepId),
+          }),
+        );
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      name: 'list_referenceable_fields',
+      description:
+        'List the outputs a step can pull data FROM. Pass the step that NEEDS the data (the downstream/consumer ' +
+        "step) — it returns the output fields of every step before it (e.g. a form's answers like answers.did), so you " +
+        'wire the right "{{source.output.field}}" or call connect_steps. Passing the source step returns nothing, since ' +
+        'nothing runs before it.',
+      schema: referenceableSchema,
+    },
+  );
+}