@relayflows/sdk 2.0.17 → 2.0.18

package/src/authored-flow-executor.ts

@@ -32,8 +32,10 @@ import type { GetFlowDefinition } from './authored-flow-loader.js';
 import type { RunLifecycleOptions } from './cli/run.js';
 import {
   AuthoredFlowExecutionError,
+  AuthoredHumanParked,
   type AuthoredFlowExecutionErrorCode,
 } from './authored-flow-error.js';
+import { readHumanAnswer } from './authored-human.js';
 import {
   AuthoredFlowOperation,
   stopAuthoredOperations,
@@ -406,9 +408,59 @@ export async function executeAuthoredFlow<Input = undefined>(
       );
       return trackStep(authoredSteps, agentOp);
     },
-    human() {
+    /**
+     * `f.human` (docs/SURFACE.md §1, §7). The question is not a child run: it
+     * is the ROOT attempt parking on the kernel's `wait.human`. The body
+     * cannot park itself — it holds no lease — so when no answer is journaled
+     * it throws `AuthoredHumanParked`, the durable root turns that into
+     * `step.wait`, and the CLI reports the question with exit 3.
+     *
+     * The wait id is the operation's ordinal (`human-N`), so a resumed body
+     * re-executes to the same call and finds the recorded
+     * `wait.completed{human_responded}`. The ANSWER is then lowered as a
+     * `human-N` deterministic step carrying `{"answer":…}` on stdout: the
+     * boolean the author's code branches on is a journaled, memoized fact in
+     * the same shape as every other authored step, so the IPC verifier and a
+     * later replay hold it to the same evidence.
+     */
+    human(question, humanOptions) {
       assertOperationAllowed('human', definition.name, requestedCompletion);
-      throw unsupportedVerb('human');
+      if (typeof question !== 'string' || question.trim() === '') {
+        throw new AuthoredFlowExecutionError('human_answer_invalid', 'f.human requires a non-empty question');
+      }
+      if (typeof humanOptions?.to !== 'string' || humanOptions.to.trim() === '') {
+        throw new AuthoredFlowExecutionError('human_answer_invalid', 'f.human requires { to } naming who answers');
+      }
+      const id = `human-${nextStep++}`;
+      const to = humanOptions.to;
+      // Hoisted like `llmOp`/`runOp`: the start closure reads the caller's
+      // `.gate(config)` at spec-build time, so a named gate on the answer is
+      // lowered into the `human-N` step's `verification` like any other step's.
+      let humanOp!: AuthoredFlowOperation<boolean>;
+      humanOp = new AuthoredFlowOperation<boolean>(
+        id, 'human',
+        () => assertOperationAllowed('human', definition.name, requestedCompletion),
+        () => observeStep(id, 'deterministic', async () => {
+          const rootRunId = options.rootRunId;
+          if (rootRunId === undefined) {
+            throw new AuthoredFlowExecutionError(
+              'unsupported_verb',
+              `f.human needs a durable root to park in; "${id}" has no run to wait on. Run the flow with flows run.`,
+            );
+          }
+          const recorded = await readHumanAnswer(journal, rootRunId, id);
+          if (recorded === undefined) throw new AuthoredHumanParked({ waitId: id, question, to }, rootRunId);
+          const record = { human: id, to, answer: recorded.answer,
+            ...(recorded.note === undefined ? {} : { note: recorded.note }),
+            answeredBy: recorded.answeredBy,
+            ...(recorded.atMs === undefined ? {} : { at: new Date(recorded.atMs).toISOString() }) };
+          const literal = `'${JSON.stringify(record).replaceAll("'", "'\\''")}'`;
+          await lowerDeterministic(id, `printf '%s' ${literal}`, false, undefined, humanOp.namedGate);
+          return recorded.answer;
+        }, options.onProgress),
+        lifecycle,
+      );
+      return trackStep(authoredSteps, humanOp);
     },
     dispatch<T>() {
       assertOperationAllowed('dispatch', definition.name, requestedCompletion);

package/src/authored-human.ts

@@ -0,0 +1,150 @@
+import { AuthoredFlowExecutionError, type AuthoredHumanWait } from './authored-flow-error.js';
+import type { JournalClient } from './journal-client.js';
+
+/**
+ * The answer contract for a parked `f.human`.
+ *
+ * The CLIENT sends `{ answer, note?, answeredBy }` as the `payload` of the
+ * `event.emit` that closes the wait (kernel DESIGN.md §5: `event_key` is the
+ * `wait_id`); `answeredBy` is required — the kernel refuses an unattributed
+ * answer. The KERNEL journals it as the `result` of
+ * `wait.completed{human_responded}` with two fields of its own: `at_ms`, the
+ * entry's clock (any client `at` is dropped — the journal says when), and
+ * `attribution: "client_asserted"`, because the daemon socket, not the kernel,
+ * is what authenticated whoever said `answeredBy`. `flows answer` and Cloud's
+ * resumed sandbox both produce the client half; the body reads the kernel half.
+ */
+export interface HumanAnswer {
+  readonly answer: boolean;
+  readonly note?: string;
+  readonly answeredBy: string;
+  /** Kernel clock at the journaled `wait.completed`, epoch milliseconds. */
+  readonly atMs?: number;
+  /** How `answeredBy` was established. The kernel writes `client_asserted`. */
+  readonly attribution?: string;
+}
+
+export type HumanAnswerPayload = Pick<HumanAnswer, 'answer' | 'note' | 'answeredBy'>;
+
+/** An open `wait.human` on a run: asked, not yet answered. */
+export interface OpenHumanWait extends AuthoredHumanWait {
+  readonly stepId: string;
+  readonly attempt: number;
+}
+
+export const HUMAN_WAIT_ID = /^human-[1-9][0-9]*$/;
+
+export function humanAnswerPayload(answer: boolean, extra: { note?: string; answeredBy: string }): HumanAnswerPayload {
+  if (extra.answeredBy.trim() === '') {
+    throw new AuthoredFlowExecutionError('human_answer_invalid', 'an answer must say who gave it (answeredBy)');
+  }
+  return {
+    answer,
+    ...(extra.note === undefined || extra.note === '' ? {} : { note: extra.note }),
+    answeredBy: extra.answeredBy,
+  };
+}
+
+/** Narrow an untrusted journal `result` to the answer contract, or refuse it. */
+export function parseHumanAnswer(value: unknown, waitId: string): HumanAnswer {
+  const record = value as { answer?: unknown; note?: unknown; answeredBy?: unknown; at_ms?: unknown; attribution?: unknown } | null;
+  if (typeof record !== 'object' || record === null || typeof record.answer !== 'boolean'
+    || (record.note !== undefined && typeof record.note !== 'string')
+    || typeof record.answeredBy !== 'string' || record.answeredBy.trim() === ''
+    || (record.at_ms !== undefined && !Number.isSafeInteger(record.at_ms))
+    || (record.attribution !== undefined && typeof record.attribution !== 'string')) {
+    throw new AuthoredFlowExecutionError(
+      'human_answer_invalid',
+      `the recorded answer to ${waitId} is not { answer: boolean, answeredBy: string }; answer it again with flows answer`,
+    );
+  }
+  return {
+    answer: record.answer,
+    ...(record.note === undefined ? {} : { note: record.note }),
+    answeredBy: record.answeredBy,
+    ...(record.at_ms === undefined ? {} : { atMs: record.at_ms as number }),
+    ...(record.attribution === undefined ? {} : { attribution: record.attribution }),
+  };
+}
+
+interface WaitEntry {
+  entry_type?: string;
+  step_id?: string | null;
+  attempt?: number | null;
+  payload?: {
+    wait_id?: unknown; prompt?: unknown; requested_of?: unknown;
+    completionReason?: unknown; result?: unknown;
+  };
+}
+
+async function readWaitEntries(journal: JournalClient, runId: string): Promise<WaitEntry[]> {
+  const waits: WaitEntry[] = [];
+  let fromSeq = 1;
+  for (;;) {
+    const page = (await journal.journalRead(runId, fromSeq, 1000)).entries as Array<WaitEntry & { seq?: number }>;
+    if (page.length === 0) break;
+    for (const entry of page) {
+      if (typeof entry.seq !== 'number' || entry.seq < fromSeq) {
+        throw new AuthoredFlowExecutionError('journal_protocol_violation', `journal.read for ${runId} returned out-of-order entries`);
+      }
+      fromSeq = entry.seq + 1;
+      if (entry.entry_type === 'wait.human' || entry.entry_type === 'wait.completed') waits.push(entry);
+    }
+  }
+  return waits;
+}
+
+/**
+ * The recorded answer to `waitId`, or `undefined` while the question is open
+ * or not yet asked. The first `human_responded` completion wins: the kernel
+ * closes a wait once, so a second answer never reaches the journal.
+ */
+export async function readHumanAnswer(
+  journal: JournalClient,
+  runId: string,
+  waitId: string,
+): Promise<HumanAnswer | undefined> {
+  for (const entry of await readWaitEntries(journal, runId)) {
+    if (entry.entry_type === 'wait.completed' && entry.payload?.wait_id === waitId
+      && entry.payload.completionReason === 'human_responded') {
+      return parseHumanAnswer(entry.payload.result, waitId);
+    }
+  }
+  return undefined;
+}
+
+/** Every `wait.human` on the run that no `wait.completed` has closed. */
+export async function readOpenHumanWaits(journal: JournalClient, runId: string): Promise<OpenHumanWait[]> {
+  const open = new Map<string, OpenHumanWait>();
+  for (const entry of await readWaitEntries(journal, runId)) {
+    const waitId = entry.payload?.wait_id;
+    if (typeof waitId !== 'string') continue;
+    if (entry.entry_type === 'wait.human') {
+      open.set(waitId, {
+        waitId,
+        question: typeof entry.payload?.prompt === 'string' ? entry.payload.prompt : '',
+        to: typeof entry.payload?.requested_of === 'string' ? entry.payload.requested_of : '',
+        stepId: typeof entry.step_id === 'string' ? entry.step_id : '',
+        attempt: typeof entry.attempt === 'number' ? entry.attempt : 0,
+      });
+    } else {
+      open.delete(waitId);
+    }
+  }
+  return [...open.values()];
+}
+
+/** How to answer a parked question from a shell, with the run's own data dir. */
+export function answerCommand(runId: string, waitId: string, dataDir?: string): string {
+  const dir = dataDir === undefined ? '' : ` --data-dir ${shellWord(dataDir)}`;
+  return `flows answer${dir} ${runId} ${waitId} yes|no`;
+}
+
+export function resumeCommand(runId: string, dataDir?: string, localAgent = false): string {
+  const dir = dataDir === undefined ? '' : ` --data-dir ${shellWord(dataDir)}`;
+  return `flows resume${dir}${localAgent ? ' --local-agent' : ''} ${runId}`;
+}
+
+function shellWord(value: string): string {
+  return /^[A-Za-z0-9_./=:@%+,-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}

package/src/authored-node-entry.ts

@@ -5,7 +5,7 @@ import { JournalClient } from './journal-client.js';
 import { executeAuthoredFlow } from './authored-flow-executor.js';
 import { loadPinnedAuthoredSource } from './authored-source-authority.js';
 import { assertAuthoredNodeVersion, parseAuthoredParentPid } from './authored-runtime-capability.js';
-import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
 import type { AuthoredRootMetadata } from './authored-root.js';
 
 let channelKey: string | undefined, sequence = 0;
@@ -82,7 +82,8 @@ try {
   const prefix = error instanceof AuthoredFlowExecutionError ? `${error.code}: ` : '';
   send({ type: 'error', message: prefix && message.startsWith(prefix) ? message.slice(prefix.length) : message,
     ...(error instanceof AuthoredFlowExecutionError ? { code: error.code,
-      completionReason: error.completionReason, runId: error.runId } : {}) });
+      completionReason: error.completionReason, runId: error.runId } : {}),
+    ...(error instanceof AuthoredHumanParked ? { wait: error.wait } : {}) });
   process.exitCode = 1;
 } finally {
   finished = true; await watchdog.terminate(); client?.close(); process.stdin.destroy();

package/src/authored-node-runner.ts

@@ -9,7 +9,11 @@ import type { Readable } from 'node:stream';
 import type { AuthoredRootMetadata } from './authored-root.js';
 import type { AuthoredExecutionRuntime, AuthoredFlowExecutionResult, ExecuteAuthoredFlowOptions } from './authored-flow-executor.js';
 import { completionMarker, isLoweredCompletion } from './authored-flow-executor.js';
-import { AuthoredFlowExecutionError, type AuthoredFlowExecutionErrorCode } from './authored-flow-error.js';
+import {
+  AuthoredFlowExecutionError, AuthoredHumanParked,
+  type AuthoredFlowExecutionErrorCode, type AuthoredHumanWait,
+} from './authored-flow-error.js';
+import { HUMAN_WAIT_ID } from './authored-human.js';
 import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
 
 let embeddedSource: string | undefined;
@@ -131,10 +135,12 @@ export async function runAuthoredInNode(
             else if (message.type === 'wait') options.onWait?.(message.event);
             else if (message.type === 'result') result = { ...message.result, executionRuntime: runtime };
             else if (message.type === 'error') {
-              failure = typeof message.code === 'string'
-                ? new AuthoredFlowExecutionError(message.code as AuthoredFlowExecutionErrorCode,
-                  message.message, message.completionReason, message.runId)
-                : new Error(message.message);
+              failure = message.code === 'human_parked' && isHumanWaitFrame(message.wait) && message.runId === rootRunId
+                ? new AuthoredHumanParked(message.wait, rootRunId)
+                : typeof message.code === 'string'
+                  ? new AuthoredFlowExecutionError(message.code as AuthoredFlowExecutionErrorCode,
+                    message.message, message.completionReason, message.runId)
+                  : new Error(message.message);
             } else throw new Error('unknown authored runtime message');
           } catch (error) { stop(error instanceof Error ? error : new Error('invalid authored runtime message')); }
         }
@@ -156,6 +162,15 @@ export async function runAuthoredInNode(
   } finally { await rm(directory, { recursive: true, force: true }); }
 }
 
+/** A park signal from the child names the question the parent must journal. */
+function isHumanWaitFrame(value: unknown): value is AuthoredHumanWait {
+  const wait = value as Partial<AuthoredHumanWait> | null;
+  return typeof wait === 'object' && wait !== null
+    && typeof wait.waitId === 'string' && HUMAN_WAIT_ID.test(wait.waitId)
+    && typeof wait.question === 'string' && wait.question !== ''
+    && typeof wait.to === 'string' && wait.to !== '';
+}
+
 /** The IPC frame is a claim, not a durable terminal fact or a sandbox boundary. */
 export async function verifyAuthoredNodeResult(
   result: AuthoredFlowExecutionResult, metadata: AuthoredRootMetadata,

package/src/authored-root.ts

@@ -15,6 +15,8 @@ import type { RunOutcome, StepDispatchEvent } from './protocol.js';
 import { SPEC_SCHEMA_VERSION } from './spec.js';
 import type { RunLifecycleOptions } from './cli/run.js';
 import { withWorkerLease } from './worker-lease.js';
+import { AuthoredHumanParked } from './authored-flow-error.js';
+import { readOpenHumanWaits } from './authored-human.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
 
 const ROOT_KIND = 'relayflows.authored-root.v1';
@@ -94,7 +96,8 @@ export async function executeDurableAuthoredFlow(
     // active run but receives no second dispatch from start itself. Resume is
     // safe for the first caller too: the daemon preserves a live lease and
     // redelivers only when the former worker connection is gone.
-    await journal.runResume(outcome.run_id);
+    const resumed = await journal.runResume(outcome.run_id);
+    await assertNoOpenHumanWait(journal, resumed);
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -133,6 +136,7 @@ export async function resumeDurableAuthoredFlow(
       return await completedRootResult(journal, rootRunId);
     }
     assertRootCanDispatch(outcome);
+    await assertNoOpenHumanWait(journal, outcome);
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -141,6 +145,17 @@ export async function resumeDurableAuthoredFlow(
   }
 }
 
+/**
+ * A root parked on an unanswered `f.human` will not be dispatched: the
+ * kernel holds it in `needs_human` until `event.emit` closes the wait. Report
+ * the open question instead of waiting for a dispatch that cannot arrive.
+ */
+async function assertNoOpenHumanWait(journal: JournalClient, outcome: RunOutcome): Promise<void> {
+  if (outcome.status !== 'parked') return;
+  const [open] = await readOpenHumanWaits(journal, outcome.run_id);
+  if (open !== undefined) throw new AuthoredHumanParked(open, outcome.run_id);
+}
+
 export async function readAuthoredRootMetadata(
   journal: JournalClient,
   runId: string,
@@ -206,6 +221,18 @@ async function driveRoot(
     );
     return Object.freeze({ ...result, rootRunId: dispatch.run_id });
   } catch (error) {
+    if (error instanceof AuthoredHumanParked) {
+      // Not a failure: the body reached a question nobody has answered. Park
+      // THIS attempt on the kernel's `wait.human` under the body's own wait
+      // id, so the answer (`event.emit` keyed by it) re-dispatches the root
+      // and the re-run body finds it. The lease is released by the verb; the
+      // signal propagates so the CLI reports the question with exit 3.
+      await peer.stepWait(dispatch.run_id, dispatch.step_id, dispatch.attempt, dispatch.idempotency_key, {
+        wait_id: error.wait.waitId, prompt: error.wait.question, requested_of: error.wait.to,
+        options: ['yes', 'no'],
+      });
+      throw error;
+    }
     await terminalizeRootFailure(peer, dispatch, error);
     throw error;
   }

package/src/cli/answer.ts

@@ -0,0 +1,98 @@
+import { userInfo } from 'node:os';
+import { readAuthoredRootMetadata } from '../authored-root.js';
+import { HUMAN_WAIT_ID, humanAnswerPayload, readHumanAnswer, readOpenHumanWaits, resumeCommand } from '../authored-human.js';
+import { JournalClient, JournalProtocolError } from '../journal-client.js';
+import type { EnsureDaemonOptions } from '../daemon-lifecycle.js';
+import { connect, emptyReport, protocolFailure, socketFor, type RunExecution } from './run.js';
+
+export interface AnswerOptions {
+  readonly note?: string;
+  /** Who answered, when relaying a person's decision; defaults to the OS user. */
+  readonly answeredBy?: string;
+  readonly daemon?: EnsureDaemonOptions;
+}
+
+/**
+ * `flows answer <run-id> <wait-id> yes|no`: record a person's answer to a
+ * parked `f.human`. The answer is an `event.emit` keyed by the wait id; the
+ * kernel closes the `wait.human` as `human_responded` and the root becomes
+ * runnable. Nothing runs here — this process attaches no worker — so the
+ * report names the `flows resume` that continues the body with the answer.
+ */
+export async function answerFlow(
+  runId: string,
+  waitId: string,
+  answer: boolean,
+  dataDir: string,
+  options: AnswerOptions = {},
+): Promise<RunExecution> {
+  const socketPath = socketFor(dataDir);
+  const base = emptyReport('answer');
+  if (!HUMAN_WAIT_ID.test(waitId)) {
+    return { exitCode: 2, report: { ...base, runId, socketPath, diagnostics: [{
+      severity: 'refusal', kind: 'human_wait_unknown',
+      message: `"${waitId}" is not an f.human wait id; they are named human-<n> in the order the body asked.`,
+    }] } };
+  }
+  const client = new JournalClient(socketPath);
+  const connected = await connect(client, 'answer', dataDir, base, { daemon: options.daemon ?? {} });
+  if (connected !== undefined) return connected;
+  try {
+    const open = await readOpenHumanWaits(client, runId);
+    const wait = open.find(candidate => candidate.waitId === waitId);
+    if (wait === undefined) {
+      const answered = await readHumanAnswer(client, runId, waitId).catch(() => undefined);
+      const others = open.map(candidate => `${candidate.waitId} (${candidate.to}: ${JSON.stringify(candidate.question)})`);
+      return { exitCode: 2, report: { ...base, runId, socketPath, diagnostics: [{
+        severity: 'refusal', kind: 'human_wait_unknown',
+        message: answered !== undefined
+          ? `Run "${runId}" already has an answer to ${waitId} (${answered.answer ? 'yes' : 'no'}); the kernel closes a wait once.`
+          : `Run "${runId}" is not asking ${waitId}.`
+            + (others.length === 0 ? ' It has no open question.' : ` Open: ${others.join(', ')}.`),
+      }] } };
+    }
+    const answeredBy = options.answeredBy ?? safeUsername();
+    if (answeredBy === '') {
+      return { exitCode: 2, report: { ...base, runId, socketPath, diagnostics: [{
+        severity: 'refusal', kind: 'human_wait_unknown',
+        message: 'An answer must say who gave it and this environment has no OS user; pass --by <identity>.',
+      }] } };
+    }
+    const payload = humanAnswerPayload(answer, {
+      ...(options.note === undefined ? {} : { note: options.note }),
+      answeredBy,
+    });
+    const emitted = await client.eventEmit(runId, waitId, payload);
+    if (emitted.matched !== 1) {
+      return protocolFailure('answer', base, socketPath, new Error(
+        `event.emit matched ${emitted.matched} waits for ${waitId}; expected the one open question`,
+      ), runId);
+    }
+    const snapshot = await client.runGet(runId);
+    const root = await readAuthoredRootMetadata(client, runId).catch(() => undefined);
+    return {
+      exitCode: 0,
+      report: {
+        ...base, ok: true, runId, socketPath, status: snapshot.status,
+        answer: { waitId, answer, ...(options.note === undefined ? {} : { note: options.note }) },
+        humanWait: { waitId, question: wait.question, to: wait.to },
+        next: resumeCommand(runId, dataDir, root?.localAgentStream !== undefined),
+        diagnostics: [],
+      },
+    };
+  } catch (error) {
+    if (error instanceof JournalProtocolError && error.code === 'run_not_found') {
+      return { exitCode: 2, report: { ...base, runId, socketPath, diagnostics: [{
+        severity: 'refusal', kind: 'run_unavailable',
+        message: `Run "${runId}" is not known to relayflowd at "${socketPath}".`,
+      }] } };
+    }
+    return protocolFailure('answer', base, socketPath, error, runId);
+  } finally {
+    client.close();
+  }
+}
+
+function safeUsername(): string {
+  try { return userInfo().username; } catch { return ''; }
+}

package/src/cli/build.ts

@@ -112,7 +112,7 @@ export async function buildFlow(path: string, out: string, warn: (line: string)
     ...(config.path !== undefined ? { projectConfigPath: config.path } : {}),
     projectSearchStart: directory,
     models: config.models,
-    ...(config.path !== undefined ? { modelRegistryPath: config.path } : {}),
+    ...(config.modelRegistryPath !== undefined ? { modelRegistryPath: config.modelRegistryPath } : {}),
     probes: {
       cli: () => { throw new Error('deferred to deployment'); },
       executor: () => { throw new Error('deferred to deployment'); },

package/src/cli/check-triggers.ts

@@ -4,6 +4,7 @@ import { preflightWebhookTriggers } from '../preflight.js';
 import { preflightProviderTriggers } from '../provider-trigger-contract.js';
 import { scheduleLowering } from '../schedule-trigger.js';
 import { checkSlackHelpers } from '../slack-preflight.js';
+import { flowRequirements } from '../flow-requirements.js';
 import { inputFailureReport, readProjectConfig, type CheckReport } from './check.js';
 
 /**
@@ -46,6 +47,7 @@ export async function checkAuthoredTriggers(path: string): Promise<{
         ok: !diagnostics.some(diagnostic => diagnostic.severity === 'refusal'),
         path, gates: [], resolutions: [], diagnostics,
         ...(schedules.length === 0 ? {} : { schedules }),
+        requirements: flowRequirements(definition, { projectCli: config.cli }),
         ...(config.path === undefined ? {} : { projectConfigPath: config.path }),
       },
     };

package/src/cli/check.ts

@@ -4,6 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { parse as parseYaml } from 'yaml';
 import { CompileError, compileSpec, kernelToAuthoring } from '../compile.js';
 import { helperReady } from '../yaml-helper-effect.js';
+import { flowRequirements, type FlowRequirements } from '../flow-requirements.js';
 import {
   adapterIdentification,
   authenticationProbe,
@@ -33,7 +34,15 @@ export interface ProjectConfig {
   mcp?: Record<string, McpServerConfig>;
   cli?: string;
   executors: string[];
+  /**
+   * Exact model allowlist. Only a flows.json that DECLARES `models` is a
+   * registry that preflight enforces: `{"cli":"claude"}` alone names the CLI
+   * and leaves model policy to the adapter defaults, exactly as no flows.json
+   * would. Otherwise every scaffolded project (`flows create` writes only
+   * `cli`) refuses its adapter's own default model as "not listed".
+   */
   models: string[];
+  modelRegistryPath?: string;
   directory: string;
   path?: string;
 }
@@ -47,6 +56,8 @@ export interface CheckReport {
   resolutions: CliResolution[];
   /** Authored `schedule.*` handlers and the `flows.tick` subscription each lowers to. */
   schedules?: ScheduleInspection[];
+  /** Integrations, harnesses and MCP servers the flow declares it needs (`flow-requirements.ts`). */
+  requirements?: FlowRequirements;
   diagnostics: Array<PreflightDiagnostic | CheckInputDiagnostic | CheckWarningDiagnostic>;
 }
 
@@ -117,6 +128,15 @@ export function checkFlow(path: string): CheckExecution {
   }
 }
 
+/** Requirements never turn a preflight refusal into an unrelated exception. */
+function safeRequirements(authoring: FlowSpec, projectCli: string | undefined): FlowRequirements | undefined {
+  try {
+    return flowRequirements(authoring, projectCli === undefined ? {} : { projectCli });
+  } catch {
+    return undefined;
+  }
+}
+
 /** Preflight a validated authored flow through the same path as YAML/JSON. */
 export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConfig?: ProjectConfig): CheckExecution {
   const absolutePath = resolve(path);
@@ -128,7 +148,7 @@ export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConf
       projectConfigPath: config.path,
       projectSearchStart: dirname(absolutePath),
       models: config.models,
-      ...(config.path !== undefined ? { modelRegistryPath: config.path } : {}),
+      ...(config.modelRegistryPath !== undefined ? { modelRegistryPath: config.modelRegistryPath } : {}),
       probes,
     });
     const flow = result.ok
@@ -147,6 +167,7 @@ export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConf
         gates: result.gates,
         resolutions: result.resolutions,
         diagnostics: result.diagnostics,
+        requirements: safeRequirements(authoring, config.cli),
       },
       ...(flow !== undefined ? { flow } : {}),
     };
@@ -196,7 +217,7 @@ export async function checkBuildableFlow(path: string): Promise<CheckExecution>
       ...(config.path !== undefined ? { projectConfigPath: config.path } : {}),
       projectSearchStart: dirname(absolutePath),
       models: config.models,
-      ...(config.path !== undefined ? { modelRegistryPath: config.path } : {}),
+      ...(config.modelRegistryPath !== undefined ? { modelRegistryPath: config.modelRegistryPath } : {}),
       probes: deferred,
     });
     // Refusals rooted in build-machine environment probes (`probe_failed`)
@@ -329,6 +350,7 @@ export function readProjectConfig(start: string): ProjectConfig {
     ...(value['cli'] !== undefined ? { cli: value['cli'] as string } : {}),
     executors: (value['executors'] as string[] | undefined) ?? [],
     models: (value['models'] as string[] | undefined) ?? [],
+    ...(value['models'] !== undefined ? { modelRegistryPath: configPath } : {}),
     directory: dirname(configPath),
     path: configPath,
   };