@ixo/oracle-runtime-workers 0.2.0

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

@@ -0,0 +1,142 @@
+/**
+ * Form tools (spec §3.5). `describe_form` returns a step's fillable questions
+ * with their exact allowed values; `fill_form` pre-fills answers (never submits).
+ */
+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 { toToolError } from '../errors';
+import { withFlowDoc } from '../flow-doc';
+import { describeForm, fillForm, setFormSchema } from '../forms';
+
+const describeSchema = 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 form step to describe.'),
+});
+
+const questionSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .describe(
+      'The answer key this question produces (referenced downstream as {{step-id.output.<name>}}).',
+    ),
+  label: z
+    .string()
+    .optional()
+    .describe('The question text shown to the user (defaults to the name).'),
+  type: z
+    .string()
+    .optional()
+    .describe(
+      'Question type: text (default), comment (multi-line), dropdown, radiogroup, checkbox (multi-select), boolean, rating.',
+    ),
+  required: z.boolean().optional(),
+  choices: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Allowed options for choice questions (dropdown/radiogroup/checkbox).',
+    ),
+});
+
+const setFormSchemaSchema = 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 form step to define the questions for.'),
+  questions: z
+    .array(questionSchema)
+    .min(1)
+    .describe('The questions the form should ask, in order.'),
+});
+
+const fillSchema = describeSchema.extend({
+  answers: z
+    .record(z.string(), z.unknown())
+    .describe(
+      'Answers keyed by question name. Choice questions need the underlying value, not the label.',
+    ),
+  merge: z
+    .boolean()
+    .optional()
+    .describe('Merge with existing answers (default true).'),
+});
+
+export function buildFormTools(
+  matrixClient: MatrixClient | undefined,
+): PluginTool[] {
+  return [
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, questions } =
+            setFormSchemaSchema.parse(args);
+          return await withFlowDoc(
+            ctx,
+            flowRef,
+            matrixClient,
+            async (doc, roomId) =>
+              setFormSchema(doc, roomId, stepId, questions),
+          );
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'set_form_schema',
+        description:
+          'Define the questions a form step asks (its survey). REQUIRED for any form step — a form with no questions ' +
+          'shows "Configure Survey Schema JSON" and cannot run. Give each question a name (the answer key, referenced ' +
+          'downstream as {{step-id.output.<name>}}), a label, a type, and whether it is required. Call this after adding the form step.',
+        schema: setFormSchemaSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId } = describeSchema.parse(args);
+          return await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            describeForm(doc, stepId),
+          );
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'describe_form',
+        description:
+          'Read the questions of a form step — their names, types, whether they are required, and the exact allowed ' +
+          'values for choice questions — so you can fill it correctly.',
+        schema: describeSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, answers, merge } = fillSchema.parse(args);
+          return await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            fillForm(doc, stepId, answers, merge ?? true),
+          );
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'fill_form',
+        description:
+          'Pre-fill a form step with answers. Does NOT submit — the user reviews and submits in the portal. ' +
+          'Returns which answers applied, which were rejected, and any still-required questions.',
+        schema: fillSchema,
+      },
+    ),
+  ];
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Inspect tools (spec §3.6) — the multi-source read surface. Each connects to
+ * the flow room, gathers the FlowSpec from all sources, and returns the
+ * friendly projection. Status fields are read-only (§2.6).
+ */
+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 { FlowError, toToolError } from '../errors';
+import { explainStep } from '../explain';
+import { withFlowDoc } from '../flow-doc';
+import { readFlowSpec, readFlowStatus, readStep } from '../read';
+
+const flowRefSchema = z.object({
+  flowRef: z
+    .string()
+    .optional()
+    .describe(
+      'Which flow to inspect. Omit to use the flow that is currently open.',
+    ),
+});
+
+const stepRefSchema = flowRefSchema.extend({
+  stepId: z.string().min(1).describe('The step to read.'),
+});
+
+export function buildReadFlowTool(
+  matrixClient: MatrixClient | undefined,
+): PluginTool {
+  return tool(
+    async (args, ctx: RuntimeContext) => {
+      try {
+        const { flowRef } = flowRefSchema.parse(args);
+        return await withFlowDoc(
+          ctx,
+          flowRef,
+          matrixClient,
+          async (doc, roomId) => {
+            const flow = readFlowSpec(doc, roomId);
+            if (!flow)
+              throw new FlowError(
+                'flow_not_found',
+                'That flow does not exist or has no steps yet.',
+              );
+            return flow;
+          },
+        );
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      name: 'read_flow',
+      description:
+        'Read a whole flow as a clean, friendly structure: its title, goal, and every step with inputs, ' +
+        'conditions, schedule, assignee, and a read-only status. Use to see the true current state of a flow.',
+      schema: flowRefSchema,
+    },
+  );
+}
+
+export function buildGetStepTool(
+  matrixClient: MatrixClient | undefined,
+): PluginTool {
+  return tool(
+    async (args, ctx: RuntimeContext) => {
+      try {
+        const { flowRef, stepId } = stepRefSchema.parse(args);
+        return await withFlowDoc(
+          ctx,
+          flowRef,
+          matrixClient,
+          async (doc, roomId) => {
+            const step = readStep(doc, roomId, stepId);
+            if (!step)
+              throw new FlowError(
+                'step_not_found',
+                `No step "${stepId}" in this flow.`,
+              );
+            return step;
+          },
+        );
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      name: 'get_step',
+      description:
+        'Read a single step of a flow, including its read-only runtime status.',
+      schema: stepRefSchema,
+    },
+  );
+}
+
+export function buildFlowStatusTool(
+  matrixClient: MatrixClient | undefined,
+): PluginTool {
+  return tool(
+    async (args, ctx: RuntimeContext) => {
+      try {
+        const { flowRef } = flowRefSchema.parse(args);
+        return await withFlowDoc(
+          ctx,
+          flowRef,
+          matrixClient,
+          async (doc, roomId) => {
+            const status = readFlowStatus(doc, roomId);
+            if (!status)
+              throw new FlowError(
+                'flow_not_found',
+                'That flow does not exist or has no steps yet.',
+              );
+            return { steps: status };
+          },
+        );
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      name: 'flow_status',
+      description:
+        'Get the per-step status of a flow: which steps are idle, running, completed, or failed (with the error), ' +
+        'plus which are blocked and by what. Use to report progress or diagnose why a step failed.',
+      schema: flowRefSchema,
+    },
+  );
+}
+
+export function buildExplainStepTool(
+  matrixClient: MatrixClient | undefined,
+): PluginTool {
+  return tool(
+    async (args, ctx: RuntimeContext) => {
+      try {
+        const { flowRef, stepId } = stepRefSchema.parse(args);
+        return await withFlowDoc(
+          ctx,
+          flowRef,
+          matrixClient,
+          async (doc, roomId) => {
+            const explanation = explainStep(doc, roomId, stepId);
+            if (!explanation)
+              throw new FlowError(
+                'step_not_found',
+                `No step "${stepId}" in this flow.`,
+              );
+            return explanation;
+          },
+        );
+      } catch (err) {
+        return toToolError(err);
+      }
+    },
+    {
+      name: 'explain_step',
+      description:
+        'Explain in plain language what a step will do and the inputs it will run with, plus its current status. ' +
+        'Use to walk the user through a step before they run it.',
+      schema: stepRefSchema,
+    },
+  );
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Linkage tools (spec §3.2) — typed wiring checks. `check_link` and
+ * `compatible_actions` read the flow; `requirements` is a pure action lookup.
+ */
+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 { toToolError } from '../errors';
+import { withFlowDoc } from '../flow-doc';
+import { checkLink, compatibleActions, requirements } from '../linkage';
+
+const flowRef = z
+  .string()
+  .optional()
+  .describe('Which flow. Omit to use the flow that is currently open.');
+
+const checkLinkSchema = z.object({
+  flowRef,
+  fromStep: z.string().min(1).describe('The step producing the value.'),
+  field: z.string().min(1).describe('The output field of fromStep.'),
+  toStep: z.string().min(1).describe('The step receiving the value.'),
+  input: z.string().min(1).describe('The input of toStep to feed.'),
+});
+
+const compatibleSchema = z.object({
+  flowRef,
+  stepId: z
+    .string()
+    .min(1)
+    .describe('The step whose input you want to satisfy.'),
+  forInput: z.string().min(1).describe('The input name you want to fill.'),
+});
+
+const requirementsSchema = z.object({
+  action: z.string().min(1).describe('Action name (from list_actions).'),
+});
+
+export function buildLinkageTools(
+  matrixClient: MatrixClient | undefined,
+): PluginTool[] {
+  return [
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const {
+            flowRef: ref,
+            fromStep,
+            field,
+            toStep,
+            input,
+          } = checkLinkSchema.parse(args);
+          return await withFlowDoc(
+            ctx,
+            ref,
+            matrixClient,
+            async (doc, roomId) =>
+              checkLink(doc, roomId, fromStep, field, toStep, input),
+          );
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'check_link',
+        description:
+          "Check whether one step's output field can feed another step's input. Catches references to outputs a step " +
+          "doesn't produce, and flags type mismatches.",
+        schema: checkLinkSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const {
+            flowRef: ref,
+            stepId,
+            forInput,
+          } = compatibleSchema.parse(args);
+          return await withFlowDoc(
+            ctx,
+            ref,
+            matrixClient,
+            async (doc, roomId) => ({
+              producers: compatibleActions(doc, roomId, stepId, forInput),
+            }),
+          );
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'compatible_actions',
+        description:
+          'List the actions (and their output field) that produce a value compatible with a given input, so you can ' +
+          'pick an upstream step to wire in.',
+        schema: compatibleSchema,
+      },
+    ),
+    tool(
+      async (args) => {
+        try {
+          const { action } = requirementsSchema.parse(args);
+          return { requires: requirements(action) };
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'requirements',
+        description:
+          "List an action's prerequisites (e.g. a needed role, connection, or collection) before using it in a flow.",
+        schema: requirementsSchema,
+      },
+    ),
+  ];
+}

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

@@ -0,0 +1,184 @@
+/**
+ * Settings mutators (spec §3.4) — one focused tool per setting, each a
+ * per-block / delta edit (§4.2). Every tool resolves the flow, runs its edit
+ * against the connected doc, and returns `{ ok: true }`.
+ */
+import type { MatrixClient } from 'matrix-js-sdk';
+import { z } from 'zod';
+import { tool } from '../../../plugin-api/tool-helper';
+import type { PluginTool, RuntimeContext } from '../../../plugin-api/types';
+import {
+  setStepAssignment,
+  setStepConditions,
+  setStepConfirmation,
+  setStepInputs,
+  setStepSchedule,
+  setStepTrigger,
+} from '../edit';
+import { toToolError } from '../errors';
+import { withFlowDoc } from '../flow-doc';
+import { conditionSchema, dueSchema } from '../types';
+
+const base = {
+  flowRef: z
+    .string()
+    .optional()
+    .describe('Which flow. Omit to use the flow that is currently open.'),
+};
+
+const inputsSchema = z.object({
+  ...base,
+  stepId: z.string().min(1),
+  inputs: z.record(z.string(), z.unknown()),
+});
+const conditionsSchema = z.object({
+  ...base,
+  stepId: z.string().min(1),
+  conditions: z.array(conditionSchema),
+});
+const scheduleSchema = z.object({
+  ...base,
+  stepId: z.string().min(1),
+  due: dueSchema.optional(),
+  commitTo: z.string().optional(),
+});
+const assignmentSchema = z.object({
+  ...base,
+  stepId: z.string().min(1),
+  assignTo: z.string().nullable().optional(),
+});
+const confirmationSchema = z.object({
+  ...base,
+  stepId: z.string().min(1),
+  requireConfirmation: z.boolean(),
+});
+const triggerSchema = z.object({
+  ...base,
+  stepId: z.string().min(1),
+  trigger: z.enum(['manual', 'flow-start']),
+});
+
+const ok = { ok: true } as const;
+
+export function buildSettingsTools(
+  matrixClient: MatrixClient | undefined,
+): PluginTool[] {
+  return [
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, inputs } = inputsSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            setStepInputs(doc, stepId, inputs),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'set_step_inputs',
+        description:
+          'Set a step\'s inputs. Reference an upstream output as "{{step-id.output.field}}" — either as the whole value, or embedded inside a longer string (e.g. a prompt: "Employee {{a.output.name}} submitted {{a.output.amount}}."). Replaces the ENTIRE inputs object — it does not merge.',
+        schema: inputsSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, conditions } = conditionsSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            setStepConditions(doc, stepId, conditions),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'set_step_conditions',
+        description:
+          'Set the activation conditions on a step (all must pass). Conditions gate on an upstream step’s configured value. Pass an empty list to clear them.',
+        schema: conditionsSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, due, commitTo } = scheduleSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            setStepSchedule(doc, stepId, due, commitTo),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'set_step_schedule',
+        description:
+          'Set when a step is due (an absolute date and/or a duration after it becomes active).',
+        schema: scheduleSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, assignTo } = assignmentSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            setStepAssignment(doc, stepId, assignTo ?? undefined),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'set_step_assignment',
+        description:
+          'Set who is meant to run a step (a DID or known alias). This is metadata only — it grants nothing.',
+        schema: assignmentSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, requireConfirmation } =
+            confirmationSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            setStepConfirmation(doc, stepId, requireConfirmation),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'set_step_confirmation',
+        description:
+          'Set whether the portal should force a confirmation before this step runs.',
+        schema: confirmationSchema,
+      },
+    ),
+    tool(
+      async (args, ctx: RuntimeContext) => {
+        try {
+          const { flowRef, stepId, trigger } = triggerSchema.parse(args);
+          await withFlowDoc(ctx, flowRef, matrixClient, async (doc) =>
+            setStepTrigger(doc, stepId, trigger),
+          );
+          return ok;
+        } catch (err) {
+          return toToolError(err);
+        }
+      },
+      {
+        name: 'set_step_trigger',
+        description:
+          "Set when a step runs: 'manual' (the user invokes it) or 'flow-start' (runs when the flow begins). " +
+          "For an event-driven auto-trigger, set the step's onEvent via update_step; setting 'manual' here clears one.",
+        schema: triggerSchema,
+      },
+    ),
+  ];
+}