@relayflows/sdk 2.0.17 → 2.0.18

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';
@@ -54,7 +56,7 @@ type ParsedArgs =
   | 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: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect: boolean }
   | { command: 'sync'; runId: string; json: boolean; root: string }
   | CloudDeployArgs
   | { command: 'deployments'; json: boolean }
@@ -65,6 +67,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 +79,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 +90,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 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] [--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>',
@@ -142,6 +146,15 @@ 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);
 
@@ -277,6 +290,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,
     },
@@ -479,6 +495,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 +503,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 +517,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 +603,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 +616,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;
@@ -790,6 +870,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 +894,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
     ? ''

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.
+  }
+}

package/src/cloud-deploy.ts

@@ -1,9 +1,13 @@
 import { randomBytes, createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
 import { loadAuthoredFlow } from './authored-flow-loader.js';
+import { ensureIntegrationsConnected, type ConnectPrompt } from './cloud-connect.js';
 import {
   CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions,
 } from './cloud-http.js';
+import { flowRequirements, type FlowRequirements } from './flow-requirements.js';
+import { readProjectConfig } from './cli/check.js';
 
 /**
  * Hosted listener deployment: the CLI form of the agentrelay.com onboarding's
@@ -47,10 +51,22 @@ export interface DeployToCloudInput {
   approver: string;
   /** Defaults to the flow's declared name. */
   name?: string;
-  /** Coding-agent harnesses the flow uses; Cloud checks their credentials are connected. Default `["claude"]`. */
+  /**
+   * Coding-agent harnesses the flow uses; Cloud checks their credentials are
+   * connected. Defaults to the `cli:` declarations the source carries
+   * (`flowRequirements`), else `["claude"]`.
+   */
   agents?: FlowAgentHarness[];
   /** Save without activating: no connection checks, no listener until activated. */
   draft?: boolean;
+  /**
+   * How a missing integration is connected before activation. Omitted, a
+   * missing one refuses with `integration_not_connected` (the `--no-connect`
+   * and non-interactive behaviour); given, each is offered a browser connect.
+   */
+  connect?: ConnectPrompt;
+  /** Skip the pre-submission integration check entirely (Cloud still checks on activation). */
+  checkConnections?: boolean;
 }
 
 export const FLOW_AGENT_HARNESSES = ['claude', 'codex'] as const;
@@ -72,6 +88,10 @@ export interface CloudDeployment {
   repository: { owner: string; name: string };
   sources: FlowTriggerSource[];
   sourceSha256: string;
+  /** What the source declared it needs; the harnesses became `inputs.agents` unless `agents` was given. */
+  requirements: FlowRequirements;
+  /** Integrations connected through the prompt during this deploy. */
+  connected: string[];
 }
 
 export function parseRepository(value: string): { owner: string; name: string } {
@@ -154,6 +174,12 @@ export async function deployToCloud(
     throw new CloudFlowError('unsupported_source',
       'Cloud deploys one self-contained .flow.ts source without use dependencies.');
   }
+  let projectCli: string | undefined;
+  try {
+    projectCli = readProjectConfig(dirname(resolve(input.path))).cli;
+  } catch {
+    projectCli = undefined;
+  }
   if (input.sources.length === 0 || input.sources.length > 10) {
     throw new CloudFlowError('invalid_input', 'Give between one and ten --on trigger sources.');
   }
@@ -176,7 +202,30 @@ export async function deployToCloud(
   if (workspace === undefined || typeof workspace.id !== 'string' || !workspace.id) {
     throw new CloudFlowError('invalid_response', 'Cloud did not report a current workspace for this credential.');
   }
-  const agents = input.agents ?? ['claude'];
+  // Every launched run lands in the deployment's repository, so GitHub is
+  // required even when no GitHub source wakes it.
+  const requirements = flowRequirements(definition, {
+    sources, repository: input.repository, ...(projectCli === undefined ? {} : { projectCli }),
+  });
+  // The declared harnesses become `inputs.agents`; one Cloud cannot run is
+  // refused here rather than silently replaced by Claude, which activation
+  // would then check while the deployed runs still call the declared CLI.
+  const unsupported = requirements.harnesses.filter(harness => !(FLOW_AGENT_HARNESSES as readonly string[]).includes(harness));
+  if (input.agents === undefined && unsupported.length > 0) {
+    const uses = requirements.harnessUses.filter(use => unsupported.includes(use.harness));
+    throw new CloudFlowError('unsupported_source',
+      `This flow declares ${uses.map(use => `${use.harness} (${use.detail})`).join(', ')}, which Cloud deployments cannot run yet; `
+      + `Cloud runs ${FLOW_AGENT_HARNESSES.join(' and ')}. Change the declaration, or pass --agents to deploy it anyway.`);
+  }
+  const declaredAgents = requirements.harnesses.filter((harness): harness is FlowAgentHarness => !unsupported.includes(harness));
+  const agents = input.agents ?? (declaredAgents.length > 0 ? declaredAgents : ['claude']);
+  // A draft activates nothing, so Cloud checks nothing; match it here.
+  const connected = input.draft || input.checkConnections === false
+    ? []
+    : (await ensureIntegrationsConnected(requirements, {
+        ...options, workspaceId: workspace.id, ...(input.connect === undefined ? {} : { prompt: input.connect }),
+      })).connected;
+  options.signal?.throwIfAborted();
   const result = await cloudFetch('/api/v1/flows/deploy', options, { method: 'POST', detail: true, body: JSON.stringify({
     workspaceId: workspace.id,
     mode: input.draft ? 'draft' : 'activate',
@@ -188,6 +237,11 @@ export async function deployToCloud(
     inputs: { approver, agents },
     repository: input.repository,
     sources,
+    requirements: {
+      integrations: requirements.integrations.map(i => i.provider),
+      harnesses: requirements.harnesses,
+      mcp: requirements.mcp,
+    },
   }) });
   if (!isCloudRecord(result) || typeof result.agentId !== 'string' || typeof result.status !== 'string') {
     throw new CloudFlowError('invalid_response', 'Cloud did not return a deployment.');
@@ -196,6 +250,7 @@ export async function deployToCloud(
     agentId: result.agentId, name, status: result.status,
     repository: input.repository, sources,
     sourceSha256: createHash('sha256').update(bytes).digest('hex'),
+    requirements, connected,
   };
 }
 

package/src/cloud-http.ts

@@ -25,7 +25,7 @@ export class CloudFlowError extends Error {
   constructor(
     readonly code: 'configuration' | 'unsupported_source' | 'invalid_input' | 'invalid_response' | 'http_error'
       | 'transport_error' | 'transient_error' | 'unsupported_storage_backend' | 'sync_too_large' | 'sync_unsupported'
-      | 'patch_conflict',
+      | 'patch_conflict' | 'integration_not_connected',
     message: string,
     readonly status?: number,
     readonly refusal?: CloudRefusal,

package/src/cloud-schedule.ts

@@ -69,12 +69,29 @@ function assertTimeZone(tz: string): string {
   return tz;
 }
 
-export async function scheduleInCloud(
-  input: ScheduleInCloudInput, options: CloudConnectionOptions = {},
-): Promise<CloudSchedule> {
+/**
+ * The argument checks `scheduleInCloud` makes before it reads the flow, so a
+ * caller can refuse a bad cron, interval or zone before any side effect (the
+ * CLI connects integrations in between). Declared-schedule resolution needs
+ * the flow and stays in `scheduleInCloud`.
+ */
+export function validateScheduleArgs(input: Pick<ScheduleInCloudInput, 'cron' | 'every' | 'tz'>): void {
   if (input.cron !== undefined && input.every !== undefined) {
     throw new CloudFlowError('invalid_input', 'Give --cron or --every, not both.');
   }
+  if (input.cron !== undefined) {
+    try { parseCron(input.cron); } catch (error) {
+      throw new CloudFlowError('invalid_input', `--cron: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (input.every !== undefined) everyToCron(input.every);
+  if (input.tz !== undefined) assertTimeZone(input.tz);
+}
+
+export async function scheduleInCloud(
+  input: ScheduleInCloudInput, options: CloudConnectionOptions = {},
+): Promise<CloudSchedule> {
+  validateScheduleArgs(input);
   const submission = await prepareCloudSubmission(input.flow, {
     ...(Object.prototype.hasOwnProperty.call(input, 'input') ? { input: input.input } : {}),
     ...(options.signal === undefined ? {} : { signal: options.signal }),

package/src/failure-kinds.ts

@@ -113,6 +113,8 @@ export const RUN_FAILURE_KINDS = [
   'run_unavailable',
   /** A predicate `.gate(fn)` judged false; the verdict is journaled as `<step>.gate`. */
   'gate_failed',
+  /** `flows answer` named a wait the run is not asking: unknown, or already answered. */
+  'human_wait_unknown',
 ] as const;
 
 /**