@relayflows/sdk 2.0.16 → 2.0.18

package/src/authored-worker-step.ts

@@ -7,12 +7,11 @@ import { classifyOutcome, type RunLifecycleOptions } from './cli/run.js';
 import type { PreflightDiagnostic } from './preflight.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
-import { SPEC_SCHEMA_VERSION, type FlowSpec, type StepSpec } from './spec.js';
+import { SPEC_SCHEMA_VERSION, type FlowSpec, type PermissionsSpec, type StepSpec } from './spec.js';
 import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput } from './authored-step-output.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { snapshotJsonValue } from './json-value.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
-import { diffWorkspaceFiles, snapshotWorkspaceFiles } from './agent-artifacts.js';
 
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
 
@@ -97,13 +96,10 @@ export function authoredWorkerRunner(
       if (options.workspace !== undefined && WORKSPACE_PERMISSION_ANNOTATION.test(options.workspace)) {
         throw new AuthoredFlowExecutionError(
           'unsupported_workspace_permission',
-          `flow "${definition.name}" step "${id}": workspace "${options.workspace}" declares a `
-            + 'permission annotation ("...: readonly" / "...: readwrite"), but nothing enforces it — '
-            + 'no parser anywhere in this package turns that annotation into a real restriction '
-            + '(kernel/DAEMON-LIFECYCLE.md\'s permission model is untouched by f.agent). '
-            + 'Silently accepting and ignoring it would let a flow believe a restriction is in effect '
-            + "when it is not. Declare a bare surface name (no trailing \": readonly\"/\": readwrite\") "
-            + 'if you do not need enforcement, or use the declarative spec\'s `permissions` field, which is real.',
+          `flow "${definition.name}" step "${id}": workspace "${options.workspace}": `
+            + "Workspace permission suffixes are unsupported. Use a bare workspace name and f.agent's "
+            + "permissions option, for example permissions: { fileGlobs: ['src/**'], accessPreset: 'readonly' }. "
+            + 'This declaration is validated and recorded with the step spec; it is not currently enforced (gate 8 / #442).',
         );
       }
       if (options.cli !== undefined && typeof options.cli !== 'string') {
@@ -130,22 +126,12 @@ export function authoredWorkerRunner(
           `f.agent options.transport must be 'direct' or 'relay' (got ${JSON.stringify(options.transport)}).`,
         );
       }
-      // Artifact detection only tells the truth for the local-agent DIRECT
-      // path: that is the only case that runs in this same process, on this
-      // same filesystem, so `options.cwd` (or `process.cwd()`) is provably
-      // where the CLI actually wrote — a workspace-scoped step never reaches
-      // here with a local agent attached (refused above). `transport: 'relay'`
-      // dispatches to agent-relay, which executes on a remote host even
-      // though a local agent stream is still attached, so it gets no local
-      // snapshot either. Any other worker attachment may execute on a
-      // different host entirely; snapshotting this process's filesystem for
-      // that case would be a guess, not a fact, so `artifacts` stays `[]`
-      // there, exactly as before this fix.
-      const artifactRoot = localAgentStream === undefined || options.transport === 'relay'
-        ? undefined : options.cwd ?? process.cwd();
-      const before = artifactRoot === undefined ? undefined : await snapshotWorkspaceFiles(artifactRoot);
+      const permissions = options.permissions;
+      const permissionsSnapshot = permissions === undefined ? undefined
+        : snapshotJsonValue(permissions, 'f.agent options.permissions') as unknown as PermissionsSpec;
       const output = await run({
         id, type: 'agent', instruction: options.task,
+        ...(permissionsSnapshot === undefined ? {} : { permissions: permissionsSnapshot }),
         ...(localAgentStream === undefined ? {} : { surfaces: { streams: [{ stream: localAgentStream }] } }),
         ...(options.workspace === undefined ? {} : { surfaces: { workspace: [{ surface: options.workspace }] } }),
         ...(options.cli === undefined ? {} : { cli: options.cli }),
@@ -158,9 +144,12 @@ export function authoredWorkerRunner(
         throw new AuthoredFlowExecutionError('journal_protocol_violation', `step "${id}" produced a non-object output`);
       }
       const stdout = 'stdout_tail' in output ? output.stdout_tail : undefined;
-      const artifacts = before === undefined || artifactRoot === undefined
-        ? []
-        : diffWorkspaceFiles(before, await snapshotWorkspaceFiles(artifactRoot));
+      // The worker that ran the CLI measured the artifacts and journaled them
+      // in the step's output; read that fact back rather than re-scanning a
+      // directory this process may not even share with the agent.
+      const journaled = 'artifacts' in output ? output.artifacts : undefined;
+      const artifacts = Array.isArray(journaled) && journaled.every(entry => typeof entry === 'string')
+        ? [...journaled] : [];
       return { summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts };
     },
     async llm(id: string, prompt: string, options?: LlmOptions, verification?: NamedGate): Promise<unknown> {

package/src/cli/answer.ts

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

package/src/cli/build.ts

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

package/src/cli/check-triggers.ts

@@ -2,7 +2,9 @@ import { dirname, resolve } from 'node:path';
 import { loadAuthoredFlow, type LoadedAuthoredFlow } from '../authored-flow-loader.js';
 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';
 
 /**
@@ -31,12 +33,21 @@ export async function checkAuthoredTriggers(path: string): Promise<{
     const diagnostics = [
       ...triggerDiagnostics, ...providerDiagnostics, ...helperReport.diagnostics,
     ];
+    // A schedule is inspectable data: print what it lowers to, and say plainly
+    // when the local runner cannot drive it. Neither is a refusal — Cloud can.
+    const schedules = triggers.flatMap((trigger, handler) => {
+      if (trigger.kind !== 'schedule') return [];
+      const lowering = scheduleLowering(definition.name, trigger);
+      return [{ handler, ...lowering }];
+    });
     return {
       loaded,
       report: {
         // Severity, not emptiness: a warning must never refuse a flow.
         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;
 }
@@ -45,9 +54,26 @@ export interface CheckReport {
   projectConfigPath?: string;
   gates: StepGateInspection[];
   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>;
 }
 
+export interface ScheduleInspection {
+  /** Position among the flow's handlers, so two identical declarations stay distinct. */
+  handler: number;
+  cron?: string;
+  tz?: string;
+  intervalMs?: number;
+  epochMs?: number;
+  staleAfterMs?: number;
+  scheduleId: string;
+  /** Present when the local tick runner cannot drive it (only a cron-aware runner can). */
+  localUnsupported?: string;
+}
+
 export interface CheckWarningDiagnostic {
   severity: 'warning';
   kind: CheckWarningKind;
@@ -102,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);
@@ -113,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
@@ -132,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 } : {}),
     };
@@ -181,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`)
@@ -314,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('; ')}.`;
+}

package/src/cli/cloud-deploy.ts

@@ -3,6 +3,8 @@ import {
   deployToCloud, listCloudDeployments, parseAgentHarnesses, parseRepository, parseTriggerSource, undeployFromCloud,
   type FlowTriggerSource,
 } from '../cloud-deploy.js';
+import { describeFlowRequirements } from '../flow-requirements.js';
+import { cliConnectPrompt, flowRequirementsForPath, harnessRemedy } from './cloud-connect-cli.js';
 import type { CliIo } from '../cli.js';
 
 export interface CloudDeployArgs {
@@ -14,12 +16,14 @@ export interface CloudDeployArgs {
   name: string | undefined;
   agents: string | undefined;
   draft: boolean;
+  /** Refuse a missing integration instead of offering to connect it. */
+  noConnect: boolean;
   json: boolean;
 }
 
 /**
  * `flows deploy <flow.ts> --repo <owner/name> --on <provider>[:k=v,…] [--on …]
- *   --approver <handle> [--name <n>] [--json]`
+ *   --approver <handle> [--name <n>] [--agents <list>] [--draft] [--no-connect] [--json]`
  *
  * Parsed here rather than in `parseDeployArgs` because the two `deploy` forms
  * share nothing but the word: the digest form copies a sealed bundle into a
@@ -32,6 +36,7 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
   let name: string | undefined;
   let agents: string | undefined;
   let draft = false;
+  let noConnect = false;
   let json = false;
   const on: string[] = [];
   for (let i = 0; i < args.length; i++) {
@@ -46,6 +51,11 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
       draft = true;
       continue;
     }
+    if (arg === '--no-connect') {
+      if (noConnect) return undefined;
+      noConnect = true;
+      continue;
+    }
     if (arg === '--agents') {
       const next = args[i + 1];
       if (agents !== undefined || next === undefined || next.startsWith('-')) return undefined;
@@ -68,7 +78,7 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
     value = arg;
   }
   if (value === undefined || repo === undefined || on.length === 0) return undefined;
-  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, json };
+  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, noConnect, json };
 }
 
 function describeSource(source: FlowTriggerSource): string {
@@ -77,11 +87,19 @@ function describeSource(source: FlowTriggerSource): string {
 }
 
 export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promise<0 | 1 | 2> {
+  const agents = args.agents === undefined ? undefined : parseAgentHarnessesOr(args.agents);
+  // What the source declares, so a harness refusal names the right remedy
+  // even when `--agents` was not given; the loader's own failure is reported
+  // by deployToCloud, not here.
+  let harnesses: readonly string[] = agents instanceof CloudFlowError ? [] : agents ?? [];
   try {
     if (args.approver === undefined) {
       throw new CloudFlowError('invalid_input',
         '--approver <handle> is required: every launched run receives it as input.approver for f.human.');
     }
+    if (agents instanceof CloudFlowError) throw agents;
+    const connect = cliConnectPrompt(io, { noConnect: args.noConnect, json: args.json });
+    if (agents === undefined) harnesses = (await flowRequirementsForPath(args.value))?.harnesses ?? [];
     const deployment = await deployToCloud({
       path: args.value,
       repository: parseRepository(args.repo),
@@ -89,7 +107,8 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
       approver: args.approver,
       draft: args.draft,
       ...(args.name === undefined ? {} : { name: args.name }),
-      ...(args.agents === undefined ? {} : { agents: parseAgentHarnesses(args.agents) }),
+      ...(agents === undefined ? {} : { agents }),
+      ...(connect === undefined ? {} : { connect }),
     });
     if (args.json) {
       io.stdout(JSON.stringify({ ok: true, ...deployment }));
@@ -99,12 +118,24 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
     io.stdout(`  flow: ${deployment.name} (${args.value}, sha256 ${deployment.sourceSha256.slice(0, 12)})`);
     io.stdout(`  repository: ${deployment.repository.owner}/${deployment.repository.name}`);
     for (const source of deployment.sources) io.stdout(`  on: ${describeSource(source)}`);
+    const requires = describeFlowRequirements(deployment.requirements);
+    if (requires) io.stdout(`  requires: ${requires}`);
+    for (const provider of deployment.connected) io.stdout(`  connected: ${provider}`);
     io.stdout(deployment.status === 'draft'
       ? 'Saved without activating; activate it from the Cloud dashboard, or redeploy without --draft.'
       : 'Each matching ticket launches a run of this source in a fresh branch; list with: flows deployments');
     return 0;
   } catch (error) {
-    return reportCloudFailure(error, args.json, io);
+    return reportCloudFailure(error, args.json, io, harnesses);
+  }
+}
+
+function parseAgentHarnessesOr(value: string): ReturnType<typeof parseAgentHarnesses> | CloudFlowError {
+  try {
+    return parseAgentHarnesses(value);
+  } catch (error) {
+    if (error instanceof CloudFlowError) return error;
+    throw error;
   }
 }
 
@@ -140,9 +171,11 @@ export async function runCloudUndeployCli({ agentId, json }: { agentId: string;
   }
 }
 
-function reportCloudFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
+function reportCloudFailure(error: unknown, json: boolean, io: CliIo, harnesses: readonly string[] = []): 1 | 2 {
   const code = error instanceof CloudFlowError ? error.code : 'cloud_deploy_failed';
   let message = error instanceof Error ? error.message : 'Cloud deploy failed.';
+  // Cloud names the missing coding-agent credential on activation; say how it is connected.
+  message += harnessRemedy(error, harnesses);
   // The deploy routes take a browser session or a `cli:auth` token. A
   // deployment (CI) token gets 403 `session_required`; say what fixes it.
   if (error instanceof CloudFlowError && error.status === 403) {
@@ -152,6 +185,7 @@ function reportCloudFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
   if (json) io.stdout(JSON.stringify({ ok: false, code, message }));
   else io.stderr(`${code}: ${message}`);
   return error instanceof CloudFlowError
-    && (['configuration', 'unsupported_source', 'invalid_input'].includes(error.code) || error.status === 403 || error.status === 401)
+    && (['configuration', 'unsupported_source', 'invalid_input', 'integration_not_connected'].includes(error.code)
+      || error.status === 403 || error.status === 401)
     ? 2 : 1;
 }

package/src/cli/cloud-run.ts

@@ -2,12 +2,13 @@ import { CloudFlowError } from '../cloud-http.js';
 import { runInCloud, waitForCloudFlowRun, type RunInCloudOptions } from '../cloud-run.js';
 import { DirectInputError, isAuthoredFlowPath, parseDirectInput } from '../direct-input.js';
 import { snapshotJsonValue } from '../json-value.js';
+import { cliConnectPrompt, ensureFlowConnections, harnessRemedy } from './cloud-connect-cli.js';
 import type { CliIo } from '../cli.js';
 
 /** Presentation only: the central CLI parser owns argv; the SDK owns the lifecycle. */
 export async function runCloudCli(
-  { value: path, json, wait, input, syncCode }: {
-    value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean;
+  { value: path, json, wait, input, syncCode, noConnect = false }: {
+    value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect?: boolean;
   },
   io: CliIo,
 ): Promise<0 | 1 | 2> {
@@ -20,6 +21,7 @@ export async function runCloudCli(
   // packing or upload — admitted nothing and is safe to retry; only an
   // interrupted submission has unknown admission.
   let submitting = false;
+  let harnesses: readonly string[] = [];
   try {
     const options: RunInCloudOptions = { signal: controller.signal, onSubmit: () => { submitting = true; } };
     if (isAuthoredFlowPath(path)) {
@@ -32,6 +34,15 @@ export async function runCloudCli(
         throw error;
       }
     }
+    // After local validation, before anything is packed or uploaded: a helper
+    // the run would call against an unconnected integration is connected
+    // here, or refused here. A command that is going to be refused for its
+    // arguments must not first open a browser.
+    const connections = await ensureFlowConnections({
+      path, prompt: cliConnectPrompt(io, { noConnect, json }),
+    }, { signal: controller.signal });
+    harnesses = connections?.requirements.harnesses ?? [];
+    for (const provider of connections?.outcome.connected ?? []) if (!json) io.stdout(`CONNECTED ${provider}`);
     // The tree is the invoking directory, as with v1: the flow path is where
     // the body lives, not the boundary of what the run may read.
     if (syncCode) options.syncCode = { root: process.cwd() };
@@ -65,11 +76,12 @@ export async function runCloudCli(
         : submitting
           ? 'Submission interrupted before a receipt was received. Admission is unknown; Cloud may have started the run. Do not resubmit blindly.'
           : 'Interrupted before the run was submitted; nothing was admitted. Safe to run again.'
-      : error instanceof Error ? error.message : 'Cloud run failed.';
+      : (error instanceof Error ? error.message : 'Cloud run failed.') + harnessRemedy(error, harnesses);
     if (json) io.stdout(JSON.stringify({ ok: false, code, message, ...(runId ? { runId } : {}) }));
     else io.stderr(`${code}: ${message}${runId ? ` (run ${runId})` : ''}`);
     return error instanceof CloudFlowError
-      && (['configuration', 'unsupported_source', 'invalid_input', 'unsupported_storage_backend', 'sync_too_large', 'sync_unsupported'].includes(error.code)
+      && (['configuration', 'unsupported_source', 'invalid_input', 'unsupported_storage_backend', 'sync_too_large', 'sync_unsupported',
+        'integration_not_connected'].includes(error.code)
         || (runId === undefined && error.code === 'http_error' && [401, 403].includes(error.status ?? 0))) ? 2 : 1;
   } finally {
     process.off('SIGINT', abort);