@relayflows/sdk 2.0.17 → 2.0.19

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { addPlugin } from './cli/add.js';
 import { watchCheck } from './cli-watch.js';
 import { checkHelperBody } from './cli/check-helper-body.js';
+import { describeFlowRequirements } from './flow-requirements.js';
 
 import { renderProgress, type ProgressEvent } from './progress.js';
 import { realpathSync } from 'node:fs';
@@ -18,6 +19,7 @@ import {
   type RunProgress,
   type RunReport,
 } from './cli/run.js';
+import { answerFlow } from './cli/answer.js';
 import { checkAuthoredTriggers } from './cli/check-triggers.js';
 import { parseWebhookArgs, runServeWebhook } from './cli/serve-webhook.js';
 import { runDirectFlow } from './cli/direct-run.js';
@@ -34,6 +36,7 @@ import { parseBuildArgs, runBuild, type BuildArgs } from './cli/build.js';
 import { runHnMonitor } from './cli/hn-monitor.js';
 import { runTickRunner } from './cli/tick-runner.js';
 import { DEFAULT_DATA_DIR } from './daemon-connection.js';
+import { CLI_VERB_NAMES } from './cli-commands.js';
 import {
   mintObserverUrl,
   resolveObserverLinkEnv,
@@ -48,14 +51,19 @@ export interface CliIo {
 }
 
 type CliExitCode = 0 | 1 | 2 | 3;
-type ParsedArgs =
+
+/**
+ * Every shape `parseArgs` can produce. Exported for `cli-commands.ts`, whose
+ * table must claim each variant or fail to compile.
+ */
+export type ParsedArgs =
   | { command: 'add'; value: string }
   | ReplayArgs
   | BuildArgs
   | DeployArgs
   | { command: 'serve-webhook'; dataDir: string; port: number; admitted?: readonly string[] }
-  | { command: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean }
-  | { command: 'sync'; runId: string; json: boolean; root: string }
+  | { command: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect: boolean }
+  | { command: 'sync'; runId: string; json: boolean; root: string; dryRun: boolean }
   | CloudDeployArgs
   | { command: 'deployments'; json: boolean }
   | { command: 'undeploy'; agentId: string; json: boolean }
@@ -65,6 +73,7 @@ type ParsedArgs =
   | { command: 'check'; json: boolean; watch: boolean; value: string }
   | { command: 'run'; bucket: string | undefined; reuseFromRunId: string | undefined; localAgent: boolean; dataDir: string; input: string | undefined; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
   | { command: 'resume'; localAgent: boolean; dataDir: string; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
+  | { command: 'answer'; dataDir: string; json: boolean; spawn: boolean; note: string | undefined; by: string | undefined; runId: string; waitId: string; answer: boolean }
   | { command: 'observer'; dataDir: string }
   | { command: 'hn-monitor'; sub: 'start'; dataDir: string; specPath: string; pollIntervalMs: number | undefined }
   | { command: 'tick'; sub: 'start'; dataDir: string; specPath: string; scheduleId: string;
@@ -76,10 +85,10 @@ const USAGE = [
   'flows add <helper-name|@flows/helper-name>',
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
-  'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--json]',
+  'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--no-connect] [--json]',
   'flows deployments [--json]',
   'flows undeploy [--json] <deployment-id>',
-  'flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>] [--tz <IANA>] [--input <inline-json-or-file>] [--name <name>] [--json]',
+  'flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>] [--tz <IANA>] [--input <inline-json-or-file>] [--name <name>] [--no-connect] [--json]',
   'flows schedules [--json]',
   'flows unschedule [--json] <schedule-id>',
   'flows deploy <flow>@sha256:<digest> --to <file-bucket-uri>',
@@ -87,12 +96,13 @@ const USAGE = [
   'flows check [--watch] [--json] <flow.ts|flow.yaml|spec.json>',
   'flows serve-webhook --data-dir <dir> --port <p> [--allow <name>[,<name>]]',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] [--reuse-from <run-id>] <flow.yaml|spec.json>',
-  'flows run --cloud [--json] [--wait] [--sync-code] <flow.yaml|spec.json>',
-  'flows run --cloud [--json] [--wait] [--sync-code] <flow.ts> --input <inline-json-or-file>',
-  'flows sync [--json] [--dir <path>] <run-id>',
+  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.yaml|spec.json>',
+  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.ts> --input <inline-json-or-file>',
+  'flows sync [--json] [--dry-run] [--dir <path>] <run-id>',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>',
   'flows tick start --schedule-id <id> --interval-ms <ms> [--epoch-ms <ms>] [--max-catch-up <n>] [--poll-interval-ms <ms>] [--data-dir <dir>] <spec.json>',
   'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <run-id>',
+  'flows answer [--json] [--no-spawn] [--data-dir <dir>] [--note <text>] [--by <identity>] <run-id> <wait-id> <yes|no>',
   'flows replay [--allow-human-influenced] [--json] [--data-dir <dir>] <run-id> [--at <step-id>]',
   'flows observer [--data-dir <dir>]',
   'flows hn-monitor start [--data-dir <dir>] [--poll-interval-ms <n>] <spec.json>',
@@ -113,9 +123,48 @@ const PROCESS_IO: CliIo = {
   stderr: (line) => process.stderr.write(`${line}\n`),
 };
 
+/** Optional knobs for an embedded caller. `bin/flows.js` passes none. */
+export interface RunCliOptions {
+  /**
+   * Cancellation for the long-running verbs (`run --cloud`, `check --watch`,
+   * `serve-webhook`, `hn-monitor start`, `tick start`).
+   *
+   * Supply one and `runCli` installs **no** process signal handlers -- required
+   * of a CLI surface mounted into another host, which owns SIGINT itself.
+   * Omit it and the standalone `flows` binary keeps today's behaviour exactly:
+   * SIGINT/SIGTERM are handled here, for the duration of that verb only.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Run one long-running verb under a cancellation signal.
+ *
+ * With a caller-supplied signal this installs nothing. Without one it owns
+ * SIGINT/SIGTERM for the duration of `body` and removes the handlers after --
+ * the pre-existing standalone behaviour, unchanged.
+ */
+async function withInterrupt<T>(
+  provided: AbortSignal | undefined,
+  body: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  if (provided !== undefined) return body(provided);
+  const controller = new AbortController();
+  const onSignal = (): void => controller.abort();
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  try {
+    return await body(controller.signal);
+  } finally {
+    process.off('SIGINT', onSignal);
+    process.off('SIGTERM', onSignal);
+  }
+}
+
 export async function runCli(
   args: readonly string[],
   io: CliIo = PROCESS_IO,
+  options: RunCliOptions = {},
 ): Promise<CliExitCode> {
   if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
     io.stdout(USAGE);
@@ -131,9 +180,13 @@ export async function runCli(
 
   if (parsed.command === 'add') return addPlugin(parsed.value, io);
 
-  if (parsed.command === 'serve-webhook') return runServeWebhook(parsed, io);
+  if (parsed.command === 'serve-webhook') {
+    return withInterrupt(options.signal, (signal) => runServeWebhook(parsed, io, signal));
+  }
 
-  if (parsed.command === 'cloud-run') return runCloudCli(parsed, io);
+  if (parsed.command === 'cloud-run') {
+    return withInterrupt(options.signal, (signal) => runCloudCli(parsed, io, signal));
+  }
   if (parsed.command === 'sync') return runCloudSyncCli(parsed, io);
   if (parsed.command === 'cloud-deploy') return runCloudDeployCli(parsed, io);
   if (parsed.command === 'deployments') return runCloudDeploymentsCli(parsed, io);
@@ -142,11 +195,22 @@ export async function runCli(
   if (parsed.command === 'schedules') return runCloudSchedulesCli(parsed, io);
   if (parsed.command === 'unschedule') return runCloudUnscheduleCli(parsed, io);
   if (parsed.command === 'replay') return replayJournal(parsed, io);
+  if (parsed.command === 'answer') {
+    const execution = await answerFlow(parsed.runId, parsed.waitId, parsed.answer, parsed.dataDir, {
+      ...(parsed.note === undefined ? {} : { note: parsed.note }),
+      ...(parsed.by === undefined ? {} : { answeredBy: parsed.by }),
+      daemon: { spawn: parsed.spawn && spawnAllowedByEnv() },
+    });
+    emitRunReport(execution, parsed.json, io);
+    return execution.exitCode;
+  }
   if (parsed.command === 'build') return runBuild(parsed, io);
   if (parsed.command === 'deploy') return runDeploy(parsed, io);
 
   if (parsed.command === 'check') {
-    if (parsed.watch) return watchCheck(parsed.value, parsed.json, io);
+    if (parsed.watch) {
+      return withInterrupt(options.signal, (signal) => watchCheck(parsed.value, parsed.json, io, signal));
+    }
     // Deliberately daemon-free (kernel/DAEMON-LIFECYCLE.md §4). `checkFlow` is
     // a compile-and-preflight that opens no daemon socket, and the parser
     // refuses `--data-dir` on `check`, so there is no data dir to attach to.
@@ -161,45 +225,27 @@ export async function runCli(
   if (parsed.command === 'observer') return runObserverCommand(io);
 
   if (parsed.command === 'hn-monitor') {
-    const controller = new AbortController();
-    const onSignal = (): void => controller.abort();
-    process.once('SIGINT', onSignal);
-    process.once('SIGTERM', onSignal);
-    try {
-      return await runHnMonitor({
-        dataDir: parsed.dataDir,
-        specPath: parsed.specPath,
-        pollIntervalMs: parsed.pollIntervalMs,
-        signal: controller.signal,
-      }, io);
-    } finally {
-      process.off('SIGINT', onSignal);
-      process.off('SIGTERM', onSignal);
-    }
+    return withInterrupt(options.signal, (signal) => runHnMonitor({
+      dataDir: parsed.dataDir,
+      specPath: parsed.specPath,
+      pollIntervalMs: parsed.pollIntervalMs,
+      signal,
+    }, io));
   }
 
   if (parsed.command === 'tick') {
-    const controller = new AbortController();
-    const onSignal = (): void => controller.abort();
-    process.once('SIGINT', onSignal);
-    process.once('SIGTERM', onSignal);
-    try {
-      return await runTickRunner({
-        dataDir: parsed.dataDir,
-        specPath: parsed.specPath,
-        schedule: {
-          scheduleId: parsed.scheduleId,
-          intervalMs: parsed.intervalMs,
-          ...(parsed.epochMs === undefined ? {} : { epochMs: parsed.epochMs }),
-          ...(parsed.maxCatchUp === undefined ? {} : { maxCatchUp: parsed.maxCatchUp }),
-        },
-        pollIntervalMs: parsed.pollIntervalMs,
-        signal: controller.signal,
-      }, io) as CliExitCode;
-    } finally {
-      process.off('SIGINT', onSignal);
-      process.off('SIGTERM', onSignal);
-    }
+    return withInterrupt(options.signal, async (signal) => await runTickRunner({
+      dataDir: parsed.dataDir,
+      specPath: parsed.specPath,
+      schedule: {
+        scheduleId: parsed.scheduleId,
+        intervalMs: parsed.intervalMs,
+        ...(parsed.epochMs === undefined ? {} : { epochMs: parsed.epochMs }),
+        ...(parsed.maxCatchUp === undefined ? {} : { maxCatchUp: parsed.maxCatchUp }),
+      },
+      pollIntervalMs: parsed.pollIntervalMs,
+      signal,
+    }, io) as CliExitCode);
   }
 
   // Attach-or-spawn runs inside `runFlow`/`resumeFlow`/`runDirectFlow`, at the
@@ -277,6 +323,9 @@ async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckR
     report: {
       ...mcp.report,
       ...(triggers?.report.schedules === undefined ? {} : { schedules: triggers.report.schedules }),
+      // The authored definition sees helper flags, body use and `cli:`
+      // declarations; the compiled view underneath knows only its steps.
+      ...(triggers?.report.requirements === undefined ? {} : { requirements: triggers.report.requirements }),
       diagnostics: [...helper.report.diagnostics, ...mcp.report.diagnostics, ...triggerDiagnostics],
       ok: helper.report.ok && mcp.report.ok && triggerOk,
     },
@@ -442,6 +491,11 @@ function emitWait(
 
 function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   const command = args[0];
+  // The verb set lives in exactly one place -- `CLI_VERBS` in cli-commands.ts --
+  // which is also what `createRelayCliSurface` projects into `commands`. Gating
+  // dispatch on it means a token the surface does not declare can never reach a
+  // parser, so the declared tree and the dispatched tree cannot drift apart.
+  if (command === undefined || !CLI_VERB_NAMES.has(command)) return undefined;
   if (command === 'add') return args.length === 2 ? { command: 'add', value: args[1]! } : undefined;
   if (command === 'replay') return parseReplayArgs(args.slice(1));
   if (command === 'build') return parseBuildArgs(args.slice(1));
@@ -479,6 +533,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   if (command === 'tick') return parseTickArgs(args.slice(1));
   if (command === 'observer') return parseObserverArgs(args.slice(1));
   if (command === 'sync') return parseSyncArgs(args.slice(1));
+  if (command === 'answer') return parseAnswerArgs(args.slice(1));
   if (command !== 'check' && command !== 'run' && command !== 'resume') return undefined;
 
   let json = false;
@@ -486,6 +541,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   let cloud = false;
   let wait = false;
   let syncCode = false;
+  let noConnect = false;
   let localAgent = false;
   let allowHumanInfluenced = false;
   let dataDir = DEFAULT_DATA_DIR;
@@ -499,11 +555,13 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   const positionals: string[] = [];
   for (let index = 1; index < args.length; index += 1) {
     const argument = args[index]!;
-    if (argument === '--cloud' || argument === '--wait' || argument === '--sync-code') {
-      if (command !== 'run' || (argument === '--cloud' ? cloud : argument === '--wait' ? wait : syncCode)) return undefined;
+    if (argument === '--cloud' || argument === '--wait' || argument === '--sync-code' || argument === '--no-connect') {
+      if (command !== 'run') return undefined;
+      if (argument === '--cloud' ? cloud : argument === '--wait' ? wait : argument === '--sync-code' ? syncCode : noConnect) return undefined;
       if (argument === '--cloud') cloud = true;
       else if (argument === '--wait') wait = true;
-      else syncCode = true;
+      else if (argument === '--sync-code') syncCode = true;
+      else noConnect = true;
       continue;
     }
     if (argument === '--allow-human-influenced') {
@@ -583,9 +641,9 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     // the source, so it is accepted exactly where a local run accepts it.
     if (allowHumanInfluenced || sawDataDir || !spawn || localAgent || noObserverLink || reuseFromRunId !== undefined) return undefined;
     if (sawInput && !isAuthoredFlowPath(positionals[0]!)) return undefined;
-    return { command: 'cloud-run', value: positionals[0]!, json, wait, input, syncCode };
+    return { command: 'cloud-run', value: positionals[0]!, json, wait, input, syncCode, noConnect };
   }
-  if (wait || syncCode) return undefined;
+  if (wait || syncCode || noConnect) return undefined;
   if (reuseFromRunId !== undefined && isAuthoredFlowPath(positionals[0]!)) return undefined;
 
   if (command === 'run' && input !== undefined && !isAuthoredFlowPath(positionals[0]!)) return undefined;
@@ -596,6 +654,66 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
       : { command, localAgent, dataDir, json, spawn, noObserverLink, allowHumanInfluenced, value: positionals[0]! };
 }
 
+/**
+ * `flows answer [--json] [--no-spawn] [--data-dir <dir>] [--note <text>] [--by <identity>] <run-id> <wait-id> <yes|no>`.
+ * The answer is a literal `yes`/`no` (also `true`/`false`) so a shell cannot
+ * hand the kernel an ambiguous word as a decision. `--by` records who answered
+ * when the invoker is relaying a person's decision (Cloud's answer route runs
+ * this inside the resumed sandbox with the caller's identity); it defaults to
+ * the OS user.
+ */
+function parseAnswerArgs(rest: readonly string[]): ParsedArgs | undefined {
+  let json = false;
+  let spawn = true;
+  let dataDir = DEFAULT_DATA_DIR;
+  let sawDataDir = false;
+  let note: string | undefined;
+  let by: string | undefined;
+  const positionals: string[] = [];
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index]!;
+    if (argument === '--json') {
+      if (json) return undefined;
+      json = true;
+      continue;
+    }
+    if (argument === '--no-spawn') {
+      if (!spawn) return undefined;
+      spawn = false;
+      continue;
+    }
+    if (argument === '--by') {
+      const value = rest[index + 1];
+      if (by !== undefined || value === undefined || value.startsWith('-') || value.trim() === '') return undefined;
+      by = value;
+      index += 1;
+      continue;
+    }
+    if (argument === '--data-dir') {
+      const value = rest[index + 1];
+      if (sawDataDir || value === undefined || value.startsWith('-')) return undefined;
+      dataDir = value;
+      sawDataDir = true;
+      index += 1;
+      continue;
+    }
+    if (argument === '--note') {
+      const value = rest[index + 1];
+      if (note !== undefined || value === undefined || value.startsWith('--')) return undefined;
+      note = value;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith('-')) return undefined;
+    positionals.push(argument);
+  }
+  if (positionals.length !== 3) return undefined;
+  const [runId, waitId, word] = positionals as [string, string, string];
+  const answer = word === 'yes' || word === 'true' ? true : word === 'no' || word === 'false' ? false : undefined;
+  if (answer === undefined) return undefined;
+  return { command: 'answer', dataDir, json, spawn, note, by, runId, waitId, answer };
+}
+
 function parseHnMonitorArgs(rest: readonly string[]): ParsedArgs | undefined {
   const sub = rest[0];
   if (sub !== 'start') return undefined;
@@ -638,9 +756,13 @@ function parseHnMonitorArgs(rest: readonly string[]): ParsedArgs | undefined {
  * directory at all -- the mint is a pure Relaycast API round-trip. No
  * positional argument, no other flags.
  */
-/** `flows sync [--json] [--dir <path>] <run-id>`: apply a hosted run's patch to a local tree. */
+/**
+ * `flows sync [--json] [--dry-run] [--dir <path>] <run-id>`: apply a hosted
+ * run's patch to a local tree, or with `--dry-run` print it and apply nothing.
+ */
 function parseSyncArgs(args: readonly string[]): ParsedArgs | undefined {
   let json = false;
+  let dryRun = false;
   let root: string | undefined;
   const positionals: string[] = [];
   for (let index = 0; index < args.length; index += 1) {
@@ -650,6 +772,11 @@ function parseSyncArgs(args: readonly string[]): ParsedArgs | undefined {
       json = true;
       continue;
     }
+    if (argument === '--dry-run') {
+      if (dryRun) return undefined;
+      dryRun = true;
+      continue;
+    }
     if (argument === '--dir') {
       const value = args[index + 1];
       if (root !== undefined || value === undefined || value.startsWith('-')) return undefined;
@@ -661,7 +788,7 @@ function parseSyncArgs(args: readonly string[]): ParsedArgs | undefined {
     positionals.push(argument);
   }
   if (positionals.length !== 1) return undefined;
-  return { command: 'sync', runId: positionals[0]!, json, root: root ?? '.' };
+  return { command: 'sync', runId: positionals[0]!, json, dryRun, root: root ?? '.' };
 }
 
 function parseObserverArgs(rest: readonly string[]): ParsedArgs | undefined {
@@ -790,6 +917,10 @@ function emitCheckReport(report: CheckReport, json: boolean, io: CliIo): void {
     const model = resolution.model === undefined ? '' : ` model "${resolution.model}"`;
     io.stdout(`RESOLVED step "${resolution.stepId}" cli "${resolution.cli}"${model} from ${resolution.source}${config}`);
   }
+  // What the workspace must have connected before this flow can run there;
+  // the hosted verbs check the same list against Cloud before submitting.
+  const requires = report.requirements === undefined ? '' : describeFlowRequirements(report.requirements);
+  if (requires) io.stdout(`REQUIRES ${requires}`);
   if (report.ok) io.stdout(`CHECK PASSED ${report.path ?? ''}`.trimEnd());
 }
 
@@ -810,6 +941,15 @@ function emitRunReport(
     return;
   }
   if (report.runId === undefined) return;
+  if (report.answer !== undefined) {
+    io.stdout(`ANSWERED ${report.runId} ${report.answer.waitId} ${report.answer.answer ? 'yes' : 'no'}`
+      + (report.answer.note === undefined ? '' : ` (${report.answer.note})`));
+    if (report.next !== undefined) io.stdout(`Continue with: ${report.next}`);
+    return;
+  }
+  // A refused answer changed nothing about the run, so there is no run
+  // outcome to summarize; the refusal above is the whole report.
+  if (report.command === 'answer') return;
   const completed = report.completedSteps === undefined ? '' : ` (${report.completedSteps} ${report.completedSteps === 1 ? 'step' : 'steps'})`;
   const reason = report.completionReason === undefined
     ? ''
@@ -863,3 +1003,15 @@ if (isDirectInvocation(process.argv[1])) {
     process.exitCode = exitCode;
   });
 }
+
+/**
+ * The argv parser, exported for the CLI-surface drift test.
+ *
+ * The drift test must prove that every command `cli-commands.ts` declares
+ * actually routes to a `ParsedArgs` variant, and that every variant is
+ * reachable from some declared command. Observing that through `runCli` would
+ * mean executing the commands. Not part of the package's public API --
+ * `@relayflows/sdk/cli` exports `runCli`, and `@relayflows/sdk/relay-cli`
+ * exports the surface.
+ */
+export { parseArgs as parseCliArgs };

package/src/cloud-connect.ts

@@ -0,0 +1,187 @@
+import { spawn } from 'node:child_process';
+import { CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions } from './cloud-http.js';
+import type { FlowIntegrationRequirement, FlowRequirements } from './flow-requirements.js';
+
+/**
+ * Integration readiness before a hosted submission — the CLI form of the
+ * deploy wizard's "Connect integrations" step, and the same relayfile
+ * connect-session flow `agentworkforce deploy` runs for a proactive agent:
+ *
+ *   GET  /api/v1/workspaces/<id>/integrations/<provider>/status?scope=workspace
+ *   POST /api/v1/workspaces/<id>/integrations/connect-session
+ *        { allowedIntegrations: [<provider>], scope: { kind: "workspace" } }
+ *        → { connectLink } (older: sessionUrl / url), opened in the browser,
+ *   then the status is polled until it reports ready.
+ *
+ * Only `workspace` scope is used: a flow deployment runs as the workspace,
+ * which is the scope `checkFlowConnections` reads on the server. Nothing here
+ * stores a credential — Cloud's connect page does — and a refusal names the
+ * provider and the two ways to connect it (this prompt, or the dashboard).
+ */
+
+export interface ConnectPrompt {
+  /** Asked once per missing provider before a browser opens; `false` refuses the submission. */
+  confirm(question: string): Promise<boolean>;
+  info(line: string): void;
+  /** Defaults to the platform opener (`open`, `xdg-open`, `start`); a failure only means the URL was printed. */
+  openUrl?(url: string): Promise<void> | void;
+}
+
+export interface EnsureConnectionsOptions extends CloudConnectionOptions {
+  workspaceId: string;
+  /** Omitted (`--no-connect`, or no TTY) means a missing integration is a refusal, never a prompt. */
+  prompt?: ConnectPrompt;
+  /** Status poll cadence while the browser connect is pending. Default 2 seconds. */
+  pollIntervalMs?: number;
+  /** How long one connect may stay pending. Default 5 minutes. */
+  connectTimeoutMs?: number;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+export interface ConnectionsOutcome {
+  /** Providers the workspace already had. */
+  ready: string[];
+  /** Providers connected through this prompt, in order. */
+  connected: string[];
+}
+
+const WORKSPACE_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+const PROVIDER_ID = /^[a-z0-9][a-z0-9-]{0,63}$/u;
+
+/** Whether the workspace has a ready connection for one provider. */
+export async function integrationConnected(
+  workspaceId: string, provider: string, options: CloudConnectionOptions,
+): Promise<boolean> {
+  assertIds(workspaceId, provider);
+  const base = `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/integrations`;
+  try {
+    const status = await cloudFetch(`${base}/${encodeURIComponent(provider)}/status?scope=workspace`, options,
+      { method: 'GET', detail: true });
+    return isReady(status);
+  } catch (error) {
+    if (!(error instanceof CloudFlowError) || error.code !== 'http_error') throw error;
+    if (error.refusal?.code === 'unknown_provider') {
+      throw new CloudFlowError('integration_not_connected',
+        `"${provider}" is not an integration this Cloud can connect; the flow declares it, so rename the declaration to a provider Cloud lists.`,
+        error.status, error.refusal);
+    }
+    // An older Cloud without the per-provider status route: the list still says which are connected.
+    if (error.status !== 404 && error.status !== 405) throw error;
+    const list = await cloudRequest(base, options);
+    const rows = Array.isArray(list) ? list : isCloudRecord(list) && Array.isArray(list.integrations) ? list.integrations : [];
+    return rows.some(row => isCloudRecord(row) && row.provider === provider && isReady(row));
+  }
+}
+
+/**
+ * Every integration the requirements name is ready when this resolves; each
+ * missing one was connected through the prompt, or the whole submission is
+ * refused with `integration_not_connected` naming the first missing provider.
+ */
+export async function ensureIntegrationsConnected(
+  requirements: Pick<FlowRequirements, 'integrations'>, options: EnsureConnectionsOptions,
+): Promise<ConnectionsOutcome> {
+  const outcome: ConnectionsOutcome = { ready: [], connected: [] };
+  for (const integration of requirements.integrations) {
+    options.signal?.throwIfAborted();
+    if (await integrationConnected(options.workspaceId, integration.provider, options)) {
+      outcome.ready.push(integration.provider);
+      continue;
+    }
+    if (options.prompt === undefined) throw notConnected(integration, options);
+    const label = providerLabel(integration.provider);
+    options.prompt.info(`This flow needs ${label} (${integration.detail}), which is not connected to this workspace.`);
+    if (!await options.prompt.confirm(`Connect ${label} now? (opens browser) [Y/n] `)) {
+      throw notConnected(integration, options);
+    }
+    await connectIntegration(integration.provider, options, options.prompt);
+    outcome.connected.push(integration.provider);
+  }
+  return outcome;
+}
+
+async function connectIntegration(provider: string, options: EnsureConnectionsOptions, prompt: ConnectPrompt): Promise<void> {
+  const base = `/api/v1/workspaces/${encodeURIComponent(options.workspaceId)}/integrations`;
+  const session = await cloudFetch(`${base}/connect-session`, options, {
+    method: 'POST', detail: true,
+    body: JSON.stringify({ allowedIntegrations: [provider], scope: { kind: 'workspace' } }),
+  });
+  const url = isCloudRecord(session)
+    ? [session.connectLink, session.sessionUrl, session.url].find((value): value is string => typeof value === 'string' && value.length > 0)
+    : undefined;
+  if (url === undefined || !/^https:\/\//u.test(url)) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return a connect link.');
+  }
+  prompt.info(`Opening ${url}`);
+  prompt.info(`If the browser did not open, visit that link, then return here; waiting for ${providerLabel(provider)} to connect…`);
+  try {
+    await (prompt.openUrl ?? openInBrowser)(url);
+  } catch {
+    // The link was printed; the poll below is what decides.
+  }
+  const interval = options.pollIntervalMs ?? 2_000;
+  const deadline = Date.now() + (options.connectTimeoutMs ?? 300_000);
+  const sleep = options.sleep ?? defaultSleep;
+  while (Date.now() < deadline) {
+    await sleep(interval, options.signal);
+    options.signal?.throwIfAborted();
+    if (await integrationConnected(options.workspaceId, provider, options)) {
+      prompt.info(`${providerLabel(provider)} connected.`);
+      return;
+    }
+  }
+  throw new CloudFlowError('integration_not_connected',
+    `${providerLabel(provider)} was not connected before the wait ran out. Finish at ${url}, then run the command again.`);
+}
+
+function notConnected(integration: FlowIntegrationRequirement, options: EnsureConnectionsOptions): CloudFlowError {
+  const label = providerLabel(integration.provider);
+  return new CloudFlowError('integration_not_connected',
+    `${label} is not connected to this workspace, and this flow needs it (${integration.detail}). `
+    + `Connect it from the dashboard, or run again without --no-connect in a terminal to connect it now `
+    + `(a browser opens a ${label} connect page for workspace ${options.workspaceId}).`);
+}
+
+function isReady(status: unknown): boolean {
+  if (!isCloudRecord(status)) return false;
+  return status.ready === true || status.state === 'ready' || status.status === 'ready' || status.status === 'connected';
+}
+
+function assertIds(workspaceId: string, provider: string): void {
+  if (!WORKSPACE_ID.test(workspaceId)) throw new CloudFlowError('invalid_response', 'Cloud reported an unusable workspace id.');
+  if (!PROVIDER_ID.test(provider)) throw new CloudFlowError('invalid_input', `"${provider}" is not an integration provider id.`);
+}
+
+/** `google-mail` → `Google Mail`, `github` → `GitHub`; presentation only. */
+export function providerLabel(provider: string): string {
+  const known: Record<string, string> = { github: 'GitHub', gitlab: 'GitLab', hubspot: 'HubSpot', clickup: 'ClickUp' };
+  return known[provider] ?? provider.split('-').map(part => part.charAt(0).toUpperCase() + part.slice(1)).join(' ');
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(signal.reason); return; }
+    const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+    function onAbort(): void { clearTimeout(timer); reject(signal!.reason); }
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * Detached so a browser that outlives the CLI never holds its stdio; every
+ * failure is ignored. `FLOWS_NO_BROWSER=1` (an SSH session, CI) leaves the
+ * printed link as the only opener.
+ */
+function openInBrowser(url: string): void {
+  if (process.env['FLOWS_NO_BROWSER'] === '1') return;
+  const [command, args] = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+  try {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    // Printed URL is the fallback.
+  }
+}