@relayflows/sdk 2.0.17 → 2.0.19

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

@@ -12,14 +12,20 @@ import type { FlowSpec } from '../spec.js';
 
 export interface BuildArgs { command: 'build'; value: string; out?: string; verify: boolean; json: boolean }
 
+/**
+ * `--verify` is an ordinary flag, not a leading mode token: the command surface
+ * lists it beside `--out` and `--json`, so every order the help implies has to
+ * parse (`build --verify --json <dir>` and `build <dir> --verify` alike).
+ *
+ * `--out` is the one combination genuinely refused: it names where a build
+ * writes, and a verify builds nothing, so accepting the pair would silently
+ * ignore the destination. The surface says so in the option's description.
+ */
 export function parseBuildArgs(args: readonly string[]): BuildArgs | undefined {
-  if (args[0] === '--verify') {
-    return args.length === 2 && !args[1]!.startsWith('-')
-      ? { command: 'build', value: args[1]!, verify: true, json: false } : undefined;
-  }
   let out: string | undefined;
   let value: string | undefined;
   let json = false;
+  let verify = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]!;
     if (arg === '--out') {
@@ -28,10 +34,14 @@ export function parseBuildArgs(args: readonly string[]): BuildArgs | undefined {
     } else if (arg === '--json') {
       if (json) return undefined;
       json = true;
+    } else if (arg === '--verify') {
+      if (verify) return undefined;
+      verify = true;
     } else if (arg.startsWith('-') || value !== undefined) return undefined;
     else value = arg;
   }
-  return value === undefined ? undefined : { command: 'build', value, out, verify: false, json };
+  if (value === undefined || (verify && out !== undefined)) return undefined;
+  return { command: 'build', value, out, verify, json };
 }
 
 /**
@@ -49,7 +59,11 @@ function emitBuildCheckReport(report: CheckReport, json: boolean, io: CliIo): vo
 export async function runBuild(args: BuildArgs, io: CliIo): Promise<0 | 2> {
   try {
     if (args.verify) {
-      io.stdout(`VERIFIED sha256:${await verifyBundle(args.value)}`);
+      const digest = `sha256:${await verifyBundle(args.value)}`;
+      // `--json` is declared on the verb, not on one of its forms: a verify
+      // under it emits the same single object a `--json` consumer parses.
+      if (args.json) io.stdout(JSON.stringify({ ok: true, verified: true, bundle: args.value, digest }));
+      else io.stdout(`VERIFIED ${digest}`);
       return 0;
     }
     // Gate the build on the same preflight pipeline `flows check` uses.
@@ -112,7 +126,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,
   };

package/src/cli/cloud-connect-cli.ts

@@ -0,0 +1,130 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { parse as parseYaml } from 'yaml';
+import { loadAuthoredFlow } from '../authored-flow-loader.js';
+import { ensureIntegrationsConnected, type ConnectPrompt, type ConnectionsOutcome } from '../cloud-connect.js';
+import { CloudFlowError, cloudRequest, isCloudRecord, type CloudConnectionOptions } from '../cloud-http.js';
+import { CompileError, compileSpec, kernelToAuthoring } from '../compile.js';
+import { FLOW_HARNESSES, flowRequirements, type FlowRequirements, type FlowRequirementsContext } from '../flow-requirements.js';
+import { readProjectConfig } from './check.js';
+import type { CliIo } from '../cli.js';
+
+/**
+ * The hosted verbs' shared "are the integrations connected?" step. It runs
+ * before `flows deploy`, `flows schedule` and `flows run --cloud` submit
+ * anything, so a flow that would fail at its first `f.slack.post` with
+ * `helper_slack.credential_missing` is connected — or refused — first.
+ *
+ * The flow is read the same way the submission reads it (authored loader or
+ * YAML compile); a source that does not load is left for the submission to
+ * refuse with its own, better diagnostic, so this step never masks one.
+ */
+
+export interface FlowConnectionsInput extends FlowRequirementsContext {
+  path: string;
+  /** `undefined` refuses a missing integration instead of prompting (`--no-connect`, `--json`, no TTY). */
+  prompt: ConnectPrompt | undefined;
+  /** Known already (deploy resolved it); otherwise `whoami` supplies it. */
+  workspaceId?: string;
+}
+
+export async function flowRequirementsForPath(
+  path: string, context: FlowRequirementsContext = {},
+): Promise<FlowRequirements | undefined> {
+  const projectCli = context.projectCli ?? projectCliFor(path);
+  const withCli = { ...context, ...(projectCli === undefined ? {} : { projectCli }) };
+  try {
+    if (/\.flow\.ts$/iu.test(path)) {
+      const loaded = await loadAuthoredFlow(path);
+      return flowRequirements(loaded.getDefinition(loaded.handle), withCli);
+    }
+    if (!/\.(?:ya?ml|json)$/iu.test(path)) return undefined;
+    const parsed: unknown = parseYaml(await readFile(path, 'utf8'));
+    let spec;
+    try {
+      spec = compileSpec(parsed);
+    } catch (error) {
+      if (!(error instanceof CompileError)) throw error;
+      spec = compileSpec(kernelToAuthoring(parsed));
+    }
+    return flowRequirements(spec, withCli);
+  } catch {
+    return undefined;
+  }
+}
+
+function projectCliFor(path: string): string | undefined {
+  try {
+    return readProjectConfig(dirname(resolve(path))).cli;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `whoami`'s current workspace: the one every hosted verb submits into. */
+export async function currentWorkspaceId(options: CloudConnectionOptions): Promise<string> {
+  const whoami = await cloudRequest('/api/v1/auth/whoami', options);
+  const workspace = isCloudRecord(whoami) && isCloudRecord(whoami.currentWorkspace) ? whoami.currentWorkspace : undefined;
+  if (workspace === undefined || typeof workspace.id !== 'string' || !workspace.id) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not report a current workspace for this credential.');
+  }
+  return workspace.id;
+}
+
+/**
+ * Connects (or refuses on) every integration `path` requires. Nothing is
+ * contacted when the flow requires no integration, so a flow with no
+ * helpers, sources or repository submits exactly as before; the derived
+ * requirements still come back so a later harness refusal can name its remedy.
+ * `undefined` only when the source does not load — the submission says why.
+ */
+export async function ensureFlowConnections(
+  input: FlowConnectionsInput, options: CloudConnectionOptions = {},
+): Promise<{ requirements: FlowRequirements; outcome: ConnectionsOutcome } | undefined> {
+  const requirements = await flowRequirementsForPath(input.path, input);
+  if (requirements === undefined) return undefined;
+  if (requirements.integrations.length === 0) return { requirements, outcome: { ready: [], connected: [] } };
+  const workspaceId = input.workspaceId ?? await currentWorkspaceId(options);
+  const outcome = await ensureIntegrationsConnected(requirements, {
+    ...options, workspaceId, ...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+  });
+  return { requirements, outcome };
+}
+
+/**
+ * A terminal prompt, or nothing. `--json` output is for a machine, and a
+ * pipe cannot answer a question, so both refuse instead of asking; `--no-connect`
+ * is the explicit form of the same choice.
+ */
+export function cliConnectPrompt(
+  io: CliIo, { noConnect, json }: { noConnect: boolean; json: boolean },
+  streams: { stdin: NodeJS.ReadStream; stdout: NodeJS.WriteStream } = { stdin: process.stdin, stdout: process.stdout },
+): ConnectPrompt | undefined {
+  if (noConnect || json || !streams.stdin.isTTY || !streams.stdout.isTTY) return undefined;
+  return {
+    info: line => io.stderr(line),
+    confirm: question => new Promise(resolveAnswer => {
+      const rl = createInterface({ input: streams.stdin, output: streams.stdout });
+      rl.question(question, answer => {
+        rl.close();
+        resolveAnswer(/^\s*(?:y(?:es)?)?\s*$/iu.test(answer));
+      });
+    }),
+  };
+}
+
+/**
+ * Cloud refuses a run or activation whose coding-agent credential is missing
+ * (`flow_model_not_connected`, `cli_credentials_missing`); there is no status
+ * route to ask first, so the refusal is where the remedy is named.
+ */
+export function harnessRemedy(error: unknown, harnesses: readonly string[]): string {
+  if (!(error instanceof CloudFlowError) || error.refusal === undefined) return '';
+  if (!['flow_model_not_connected', 'cli_credentials_missing'].includes(error.refusal.code)) return '';
+  if (/agent-relay cloud connect/u.test(error.refusal.error)) return '';
+  const message = error.refusal.error.toLowerCase();
+  const named = FLOW_HARNESSES.filter(harness => message.includes(harness));
+  const targets = named.length > 0 ? named : harnesses.length > 0 ? harnesses : ['claude'];
+  return ` Connect it with: ${targets.map(harness => `agent-relay cloud connect ${harness}`).join('; ')}.`;
+}