@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/plugins/flows/edit.ts

@@ -17,7 +17,14 @@ import * as Y from 'yjs';
 import { deleteBlock, editBlock, findParentOf } from './ydoc-helpers';
 import { getActionDef, isEventCapable } from './actions';
 import { FlowError } from './errors';
+import {
+  MAX_STEP_INPUTS_BYTES,
+  jsonByteLength,
+  secretLiteralMessage,
+  secretLiteralPaths,
+} from './input-policy';
 import { readFlowSpec } from './read';
+import { referencesId } from './ref-syntax';
 import {
   BLOCK_ID_PREFIX,
   blockIdToStepId,
@@ -26,17 +33,116 @@ import {
   friendlyInputsToNb,
   stepIdToBlockId,
 } from './translator';
-import type { Condition } from './types';
+import { didSchema, type Condition, type FlowStep } from './types';
 
 const DOC = 'document';
 
-function requireStep(doc: YDoc, stepId: string): string {
+/** The step's block id; throws `step_not_found` when the flow has no such step. */
+export function requireStep(doc: YDoc, stepId: string): string {
   if (!doc.getMap('qi.flow.nodes').has(stepId)) {
     throw new FlowError('step_not_found', `No step "${stepId}" in this flow.`);
   }
   return stepIdToBlockId(stepId);
 }
 
+/** The ids of the flow's steps, plus `extra` (steps about to be added). */
+function stepIdsOf(doc: YDoc, extra: readonly string[]): Set<string> {
+  return new Set([...doc.getMap('qi.flow.nodes').keys(), ...extra]);
+}
+
+/*
+ * Checks. Each throws the error its setter would, without writing, so a tool
+ * that makes several edits can validate all of them before the first change
+ * (a change already made would still reach the room).
+ */
+
+/**
+ * Throw unless `inputs` may be stored: no secret outside a reference to a
+ * step of this flow (or of `extraStepIds`), and within the size cap. Returns
+ * the serialised value to store.
+ */
+export function checkStepInputs(
+  doc: YDoc,
+  inputs: Record<string, unknown>,
+  extraStepIds: readonly string[] = [],
+): string {
+  const secrets = secretLiteralPaths(inputs, stepIdsOf(doc, extraStepIds));
+  if (secrets.length > 0)
+    throw new FlowError('validation_failed', secretLiteralMessage(secrets));
+  const nb = friendlyInputsToNb(inputs) ?? {};
+  const bytes = jsonByteLength(nb);
+  if (bytes > MAX_STEP_INPUTS_BYTES)
+    throw new FlowError(
+      'validation_failed',
+      `A step's inputs may be at most ${MAX_STEP_INPUTS_BYTES} bytes of JSON (got ${bytes}).`,
+    );
+  return JSON.stringify(nb);
+}
+
+/** Throw unless every condition reads a step of this flow (or of `extraStepIds`). */
+export function checkConditions(
+  doc: YDoc,
+  conditions: readonly Condition[],
+  extraStepIds: readonly string[] = [],
+): void {
+  // A condition on a step that is not in the flow can never be evaluated.
+  const ids = stepIdsOf(doc, extraStepIds);
+  for (const condition of conditions)
+    if (!ids.has(condition.fromStep))
+      throw new FlowError(
+        'step_not_found',
+        `No step "${condition.fromStep}" in this flow.`,
+      );
+}
+
+/** Throw unless `assignTo` is a DID (assigning grants run authority). */
+export function checkAssignee(assignTo: string | undefined): void {
+  if (assignTo !== undefined && !didSchema.safeParse(assignTo).success)
+    throw new FlowError(
+      'validation_failed',
+      `"${assignTo}" is not a DID. Assigning a step authorises that DID to run it, so it must be a did: value.`,
+    );
+}
+
+/**
+ * Throw unless `stepId` may auto-trigger on `onEvent.fromStep`: a step of
+ * this flow whose action can emit events. Returns the source's block id.
+ */
+export function checkEventTrigger(
+  doc: YDoc,
+  stepId: string,
+  onEvent: { fromStep: string; event: string },
+): string {
+  if (onEvent.fromStep.startsWith(BLOCK_ID_PREFIX)) {
+    throw new FlowError(
+      'validation_failed',
+      `"${onEvent.fromStep}" is an internal block id — use the short step id ("${blockIdToStepId(onEvent.fromStep)}").`,
+    );
+  }
+  const sourceBlockId = requireStep(doc, onEvent.fromStep);
+
+  // Same event-capability rule validate_flow enforces at plan level.
+  const source = doc.getMap('qi.flow.nodes').get(onEvent.fromStep);
+  const registryType =
+    source instanceof Y.Map ? source.get('registryType') : undefined;
+  const can = source instanceof Y.Map ? source.get('can') : undefined;
+  const action =
+    typeof registryType === 'string'
+      ? registryType
+      : typeof can === 'string'
+        ? canToAction(can)
+        : undefined;
+  const def = action ? getActionDef(action) : undefined;
+  if (def && !isEventCapable(def)) {
+    throw new FlowError(
+      'validation_failed',
+      `Step "${stepId}" can't auto-trigger on "${onEvent.fromStep}" — its action "${action}" cannot emit events. ` +
+        'Use ordering (after) + an input reference instead.',
+    );
+  }
+  return sourceBlockId;
+}
+
 /** Write a set of value props onto a step's block (per-block, lossless). */
 export function setStepProps(
   doc: YDoc,
@@ -47,14 +153,18 @@ export function setStepProps(
   editBlock(doc, { blockId, attributes: { props }, docName: DOC });
 }
 
+/**
+ * Replace a step's inputs. Every path that writes inputs ends here, so the
+ * secret and size rules are enforced here as well as in the tool schemas.
+ */
 export function setStepInputs(
   doc: YDoc,
   stepId: string,
   inputs: Record<string, unknown>,
 ): void {
-  setStepProps(doc, stepId, {
-    inputs: JSON.stringify(friendlyInputsToNb(inputs) ?? {}),
-  });
+  requireStep(doc, stepId);
+  const serialized = checkStepInputs(doc, inputs);
+  setStepExecutionProps(doc, stepId, { inputs: serialized });
 }
 
 export function setStepConditions(
@@ -62,11 +172,54 @@ export function setStepConditions(
   stepId: string,
   conditions: Condition[],
 ): void {
-  setStepProps(doc, stepId, {
+  requireStep(doc, stepId);
+  checkConditions(doc, conditions);
+  setStepExecutionProps(doc, stepId, {
     conditions: conditions.length > 0 ? buildConditionsProp(conditions) : '',
   });
 }
 
+export function setStepSemanticGate(
+  doc: YDoc,
+  stepId: string,
+  gate: FlowStep['semanticGate'] | null,
+): void {
+  setStepExecutionProps(doc, stepId, {
+    semanticGate: gate ? JSON.stringify(gate) : '',
+  });
+}
+
+function setStepExecutionProps(
+  doc: YDoc,
+  stepId: string,
+  props: Record<string, string>,
+): void {
+  requireStep(doc, stepId);
+  const nodes = doc.getMap('qi.flow.nodes');
+  const node = nodes.get(stepId);
+  if (!(node instanceof Y.Map))
+    throw new FlowError(
+      'step_not_found',
+      `No compiled step "${stepId}" in this flow.`,
+    );
+  doc.transact(() => {
+    setStepProps(doc, stepId, props);
+    const existing: unknown = node.get('props');
+    if (existing instanceof Y.Map) {
+      for (const [key, value] of Object.entries(props))
+        existing.set(key, value);
+    } else {
+      node.set('props', {
+        ...(existing && typeof existing === 'object' && !Array.isArray(existing)
+          ? existing
+          : {}),
+        ...props,
+      });
+    }
+    for (const [key, value] of Object.entries(props)) node.set(key, value);
+  });
+}
+
 export function setStepSchedule(
   doc: YDoc,
   stepId: string,
@@ -88,6 +241,8 @@ export function setStepAssignment(
   // The portal shows + nudges the assignee from `props.assignment`; the
   // `authorisedActors` whitelist also lets that actor run the step. Write both
   // so the assignee is visible AND authorized; clear both when unassigned.
+  // Because this grants run authority, only a well-formed DID is accepted.
+  checkAssignee(assignTo);
   setStepProps(doc, stepId, {
     assignment: assignTo
       ? JSON.stringify({ assignedActor: { did: assignTo } })
@@ -176,34 +331,7 @@ export function setStepEventTrigger(
   stepId: string,
   onEvent: { fromStep: string; event: string },
 ): void {
-  if (onEvent.fromStep.startsWith(BLOCK_ID_PREFIX)) {
-    throw new FlowError(
-      'validation_failed',
-      `"${onEvent.fromStep}" is an internal block id — use the short step id ("${blockIdToStepId(onEvent.fromStep)}").`,
-    );
-  }
-  const sourceBlockId = requireStep(doc, onEvent.fromStep);
-
-  // Same event-capability rule validate_flow enforces at plan level (spec §2.3).
-  const source = doc.getMap('qi.flow.nodes').get(onEvent.fromStep);
-  const registryType =
-    source instanceof Y.Map ? source.get('registryType') : undefined;
-  const can = source instanceof Y.Map ? source.get('can') : undefined;
-  const action =
-    typeof registryType === 'string'
-      ? registryType
-      : typeof can === 'string'
-        ? canToAction(can)
-        : undefined;
-  const def = action ? getActionDef(action) : undefined;
-  if (def && !isEventCapable(def)) {
-    throw new FlowError(
-      'validation_failed',
-      `Step "${stepId}" can't auto-trigger on "${onEvent.fromStep}" — its action "${action}" cannot emit events. ` +
-        'Use ordering (after) + an input reference instead.',
-    );
-  }
-
+  const sourceBlockId = checkEventTrigger(doc, stepId, onEvent);
   setStepProps(doc, stepId, {
     trigger: JSON.stringify({
       type: 'block.event',
@@ -221,10 +349,9 @@ function referrersOf(doc: YDoc, ref: string, stepId: string): string[] {
   const referrers: string[] = [];
   for (const step of flow.steps) {
     if (step.id === stepId) continue;
-    const refsInput = Object.values(step.inputs ?? {}).some(
-      (v) =>
-        typeof v === 'string' && new RegExp(`\\{\\{\\s*${stepId}\\.`).test(v),
-    );
+    // Inputs nest (an email's `variables` map, arrays of recipients), and a
+    // reference may sit inside a longer template string.
+    const refsInput = referencesId(step.inputs ?? {}, stepId);
     const conds = [
       ...(step.runWhen ? [step.runWhen] : []),
       ...(step.conditions ?? []),
@@ -259,8 +386,14 @@ export function removeStep(doc: YDoc, ref: string, stepId: string): void {
     const edges = doc.getMap('qi.flow.edges');
     const toDelete: string[] = [];
     edges.forEach((value, edgeId) => {
-      const edge = value as { source?: unknown; target?: unknown } | undefined;
-      if (edge && (edge.source === stepId || edge.target === stepId))
+      // The compiler stores each edge as a Y.Map; plain objects are tolerated.
+      const endpoint = (key: 'source' | 'target'): unknown =>
+        value instanceof Y.Map
+          ? value.get(key)
+          : value && typeof value === 'object'
+            ? Object.getOwnPropertyDescriptor(value, key)?.value
+            : undefined;
+      if (endpoint('source') === stepId || endpoint('target') === stepId)
         toDelete.push(edgeId);
     });
     for (const edgeId of toDelete) edges.delete(edgeId);
@@ -269,9 +402,57 @@ export function removeStep(doc: YDoc, ref: string, stepId: string): void {
   deleteBlock(doc, { blockId, docName: DOC });
 }
 
+/**
+ * Move a step's block in the document so it sits next to its neighbours in
+ * `order`: right before the next step's block, or right after the previous
+ * one's. The document also holds headings and notes between step blocks, so
+ * an index taken from `order` would land in the wrong place.
+ *
+ * Yjs has no move operation: the block is cloned and the original deleted, so
+ * an edit another client makes to the original at the same moment is lost.
+ * The block is left alone when it already sits between the right neighbours.
+ */
+export function placeStepBlock(
+  doc: YDoc,
+  stepId: string,
+  order: readonly string[],
+): void {
+  const fragment = doc.getXmlFragment(DOC);
+  const found = findParentOf(fragment, stepIdToBlockId(stepId));
+  if (!found) return;
+  const { parent } = found;
+  const siblings = parent.toArray();
+  // A neighbour's index among the same siblings, or -1 when it has no block
+  // or its block lives under a different parent.
+  const indexIn = (id: string | undefined): number => {
+    if (id === undefined) return -1;
+    const located = findParentOf(fragment, stepIdToBlockId(id));
+    return located && located.parent === parent ? located.index : -1;
+  };
+  const at = order.indexOf(stepId);
+  const before = indexIn(order[at - 1]);
+  const after = indexIn(order[at + 1]);
+  const current = found.index;
+  if ((before < 0 || before < current) && (after < 0 || current < after))
+    return;
+
+  const element = siblings[current];
+  if (!(element instanceof Y.XmlElement)) return;
+  // Position in the sibling list once the original is removed.
+  const shift = (index: number): number =>
+    index > current ? index - 1 : index;
+  const target =
+    after >= 0 ? shift(after) : before >= 0 ? shift(before) + 1 : current;
+  doc.transact(() => {
+    const clone = element.clone();
+    parent.delete(current, 1);
+    parent.insert(target, [clone]);
+  });
+}
+
 /** Reorder a step to a new 0-based index. Sequence is display-only; runtime/edges untouched. */
 export function reorderStep(doc: YDoc, stepId: string, toIndex: number): void {
-  const blockId = requireStep(doc, stepId);
+  requireStep(doc, stepId);
   const orderArr = doc.getArray<string>('qi.flow.order');
   const current = orderArr.toArray();
   const from = current.indexOf(stepId);
@@ -285,19 +466,9 @@ export function reorderStep(doc: YDoc, stepId: string, toIndex: number): void {
   without.splice(target, 0, stepId);
 
   doc.transact(() => {
-    // Move the fragment block by CLONE (yjs can't reinsert a deleted element).
-    const fragment = doc.getXmlFragment(DOC);
-    const found = findParentOf(fragment, blockId);
-    if (found) {
-      const element = found.parent.toArray()[found.index];
-      if (element instanceof Y.XmlElement) {
-        const clone = element.clone();
-        found.parent.delete(found.index, 1);
-        found.parent.insert(Math.min(target, found.parent.length), [clone]);
-      }
-    }
     orderArr.delete(0, orderArr.length);
     orderArr.push(without);
+    placeStepBlock(doc, stepId, without);
   });
 }
 

package/src/plugins/flows/errors.ts

@@ -1,8 +1,11 @@
 /**
  * Uniform error model (spec §6.1). Tools never throw to the agent; expected
  * failures come back as `{ ok: false, error: { code, message } }` with
- * friendly, leak-safe messages.
+ * friendly, leak-safe messages. Invalid tool input (a zod parse failure,
+ * including a size limit) is `validation_failed` with the schema's messages.
  */
+import { z } from 'zod';
+
 export type FlowErrorCode =
   | 'no_flow_ref'
   | 'not_in_room'
@@ -11,6 +14,14 @@ export type FlowErrorCode =
   | 'step_not_found'
   | 'referenced'
   | 'unknown_action'
+  | 'needs_access'
+  /**
+   * A write the homeserver never acknowledged (server errors, a network
+   * failure, or the wait ran out): it may or may not have been saved. The
+   * same code the editor uses, so the runtime keeps the write's claim and
+   * does not blindly run the identical write again.
+   */
+  | 'write_not_saved'
   | 'error';
 
 export class FlowError extends Error {
@@ -33,6 +44,16 @@ export function toToolError(err: unknown): ToolErrorResult {
   if (err instanceof FlowError) {
     return { ok: false, error: { code: err.code, message: err.message } };
   }
+  if (err instanceof z.ZodError) {
+    const message = err.issues
+      .map((issue) =>
+        issue.path.length > 0
+          ? `${issue.path.join('.')}: ${issue.message}`
+          : issue.message,
+      )
+      .join(' ');
+    return { ok: false, error: { code: 'validation_failed', message } };
+  }
   const message = err instanceof Error ? err.message : String(err);
   return { ok: false, error: { code: 'error', message } };
 }

package/src/plugins/flows/flow-doc.ts

@@ -10,7 +10,12 @@
  */
 import type { Doc as YDoc } from 'yjs';
 import type { MatrixClient } from 'matrix-js-sdk';
-import { MatrixProviderManager, type AppConfig } from '../editor/provider';
+import {
+  DocWriteGuard,
+  MatrixProviderManager,
+  type AppConfig,
+  type DocWriteFailure,
+} from '../editor/provider';
 import { buildBlocknoteToolsConfig } from '../editor/editor-config';
 import { resolveEditorMatrixClient } from '../editor/editor-mx';
 import { isUserInRoom } from '../editor/room-membership';
@@ -58,17 +63,83 @@ export async function requireRoomMembership(
 }
 
 /**
- * Resolve a Matrix client for compile-driven authoring (`setupFlowFromBaseUcan`),
- * which manages its own provider/doc rather than taking the one `withFlowDoc` opens.
+ * The tool error for a write that did not reach the room:
+ *  - refused as forbidden → `needs_access` (nothing was written);
+ *  - refused with a client error (e.g. too large) → `error` (nothing was written);
+ *  - not acknowledged (server errors, network, timeout) → `write_not_saved`:
+ *    the change may have landed, so the flow must be re-read before any retry.
  */
-export async function resolveFlowsMatrixClient(
+function writeFailureError(failure: DocWriteFailure): FlowError {
+  if (failure.kind === 'forbidden')
+    return new FlowError(
+      'needs_access',
+      'The flow was not saved: this assistant is not allowed to edit this flow. ' +
+        'Ask a room admin to give it edit rights, then try again.',
+    );
+  if (!failure.mayHaveLanded)
+    return new FlowError(
+      'error',
+      `The flow was not saved: the homeserver refused the change (${failure.detail}).`,
+    );
+  return new FlowError(
+    'write_not_saved',
+    `The change may or may not have been saved: the homeserver did not acknowledge it (${failure.detail}). ` +
+      'Re-read the flow (read_flow or get_step) before retrying, so the change is not applied twice.',
+  );
+}
+
+/**
+ * Run compile-driven authoring (`setupFlowFromBaseUcan`), which opens and
+ * disposes its own provider, against a Matrix client whose document writes
+ * are bounded ({@link DocWriteGuard}, `drain` mode: the editor's own writer
+ * is configured to retry rejected writes for minutes). A write the
+ * homeserver refused or that could not be delivered becomes a tool error.
+ */
+export async function withFlowsCompileClient<T>(
   rtCtx: RuntimeContext,
   injectedClient: MatrixClient | undefined,
-): Promise<MatrixClient> {
-  return resolveEditorMatrixClient({
+  fn: (client: MatrixClient) => Promise<T>,
+): Promise<T> {
+  const client = await resolveEditorMatrixClient({
     ...(await readMatrixCreds(rtCtx)),
     matrixClient: injectedClient,
   });
+  const guard = new DocWriteGuard(client, { onGiveUp: 'drain' });
+  try {
+    const result = await raceAbort(rtCtx, () => fn(guard.client));
+    if (guard.failure) throw writeFailureError(guard.failure);
+    return result;
+  } finally {
+    guard.close();
+  }
+}
+
+/**
+ * Settle with `start()`'s result, or reject as soon as the request is
+ * aborted. `start` runs only when the request is still live: a promise
+ * created before an abort check that then throws would be left with no
+ * handler, and its later rejection would go unhandled. Once started, the
+ * work stays attached to the race, so a rejection it produces after the
+ * abort is handled (the caller already has the abort as its error).
+ */
+function raceAbort<T>(
+  rtCtx: RuntimeContext,
+  start: () => Promise<T>,
+): Promise<T> {
+  const signal = rtCtx.abortSignal;
+  signal.throwIfAborted();
+  const work = start();
+  let onAbort: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = () => {
+      const reason: unknown = signal.reason;
+      reject(reason instanceof Error ? reason : new Error('Request aborted'));
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+  return Promise.race([work, aborted]).finally(() => {
+    if (onAbort) signal.removeEventListener('abort', onAbort);
+  });
 }
 
 function buildAppConfig(creds: MatrixCreds, roomId: string): AppConfig {
@@ -82,7 +153,15 @@ function buildAppConfig(creds: MatrixCreds, roomId: string): AppConfig {
 
 /**
  * Resolve the flow ref, enforce the room-membership guard (fail closed), open
- * the room's Y.Doc, run `fn`, and always dispose the provider.
+ * the room's Y.Doc, run `fn`, wait until every change `fn` made has reached
+ * the room, and always dispose the provider — on success, on a tool error,
+ * on abort and on a timeout.
+ *
+ * `fn` returning is not success on its own: Y.Doc edits apply locally at
+ * once and reach Matrix later. A forbidden write is `needs_access`; one
+ * refused with a client error is an `error`; one the homeserver never
+ * acknowledged (server errors, network, or the flush timeout ran out) is
+ * `write_not_saved` — see {@link writeFailureError}.
  */
 export async function withFlowDoc<T>(
   rtCtx: RuntimeContext,
@@ -90,6 +169,7 @@ export async function withFlowDoc<T>(
   injectedClient: MatrixClient | undefined,
   fn: (doc: YDoc, roomId: string) => Promise<T>,
 ): Promise<T> {
+  rtCtx.abortSignal.throwIfAborted();
   const roomId = resolveFlowRef(rtCtx, ref);
   await requireRoomMembership(rtCtx, roomId);
 
@@ -103,8 +183,11 @@ export async function withFlowDoc<T>(
     buildAppConfig(creds, roomId),
   );
   try {
-    const { doc } = await manager.init();
-    return await fn(doc, roomId);
+    const { doc } = await raceAbort(rtCtx, () => manager.init());
+    const result = await raceAbort(rtCtx, () => fn(doc, roomId));
+    const failure = await raceAbort(rtCtx, () => manager.flush());
+    if (failure) throw writeFailureError(failure);
+    return result;
   } finally {
     await manager.dispose();
   }

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

@@ -25,7 +25,7 @@ import type {
   PluginTool,
   RuntimeContext,
 } from '../../plugin-api/types';
-import { FLOWS_PLUGIN_NAME } from './prompts';
+import { FLOWS_OPERATING_GUIDE, FLOWS_PLUGIN_NAME } from './prompts';
 
 export interface FlowsPluginOptions {
   /** A long-lived Matrix client owned by the host (or a test), shared across rooms. */
@@ -35,10 +35,13 @@ export interface FlowsPluginOptions {
 /**
  * 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.
+ * the agent when and how to load it. The full operating contract,
+ * `FLOWS_OPERATING_GUIDE` (prompts.ts), is the plugin's `operatingGuide`, not
+ * part of the manifest: `load_capability` returns it when it loads flows (also
+ * when the capability router had only preloaded it for the turn), and the
+ * system prompt carries it on every later turn that starts with flows loaded
+ * on the thread. A one-turn router preload leaves the system prompt alone, and
+ * turns that never use flows pay no tokens for it.
  */
 const manifest: PluginManifest = {
   title: 'Flow Builder',
@@ -54,6 +57,7 @@ const manifest: PluginManifest = {
   whenNotToUse: [
     'Editing prose/pages/documents (use the editor).',
     'Actually executing/running/signing a step — that happens in the portal, by the user.',
+    'Collecting a PIN, mnemonic or other secret — the portal asks for it when the user runs the step; never ask for one in chat or write one into a flow.',
   ],
   examples: [
     {
@@ -83,6 +87,8 @@ export class FlowsPlugin extends OraclePlugin {
   readonly name = FLOWS_PLUGIN_NAME;
   readonly version = '0.1.0';
   readonly manifest = manifest;
+  /** The operating contract — see the manifest comment above. */
+  override readonly operatingGuide = FLOWS_OPERATING_GUIDE;
 
   private readonly matrixClient?: MatrixClient;
 

package/src/plugins/flows/forms.ts

@@ -19,10 +19,23 @@ import {
 } from './ydoc-helpers';
 import { setStepInputs } from './edit';
 import { FlowError } from './errors';
+import {
+  MAX_FORM_ANSWERS_BYTES,
+  jsonByteLength,
+  secretLiteralMessage,
+  secretLiteralPaths,
+} from './input-policy';
 import { inferPortType } from './port-types';
 import { readStep } from './read';
 import { stepIdToBlockId } from './translator';
 
+/** Runtime states in which a form's answers belong to the user's submission. */
+const LOCKED_FORM_STATES: readonly string[] = [
+  'running',
+  'completed',
+  'awaiting_readback',
+];
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
@@ -197,6 +210,27 @@ export function fillForm(
   merge = true,
 ): FillFormResult {
   const { blockId, questions } = readSurveySchema(doc, stepId);
+
+  // Once the user has submitted (or the step is executing), the stored
+  // answers are what downstream steps read; a pre-fill must never replace them.
+  const state = readRuntimeState(doc, blockId)[blockId]?.state;
+  if (typeof state === 'string' && LOCKED_FORM_STATES.includes(state)) {
+    throw new FlowError(
+      'validation_failed',
+      `Step "${stepId}" is ${state}; its answers can no longer be pre-filled.`,
+    );
+  }
+  if (jsonByteLength(answers) > MAX_FORM_ANSWERS_BYTES) {
+    throw new FlowError(
+      'validation_failed',
+      `Form answers may be at most ${MAX_FORM_ANSWERS_BYTES} bytes of JSON.`,
+    );
+  }
+  // Answers are values, not wiring: a secret answer is refused whatever it holds.
+  const secrets = secretLiteralPaths(answers, new Set());
+  if (secrets.length > 0)
+    throw new FlowError('validation_failed', secretLiteralMessage(secrets));
+
   const byName = new Map(questions.map((q) => [q.name, q]));
 
   const applied: string[] = [];

package/src/plugins/flows/index.ts

@@ -1,2 +1,4 @@
 export { FlowsPlugin, type FlowsPluginOptions } from './flows.plugin';
 export { FLOWS_PLUGIN_NAME, FLOWS_OPERATING_GUIDE } from './prompts';
+export { readFlowDecisionContext } from './decision-context';
+export type { FlowSpecRead, FlowStepRead } from './types';