@relayflows/sdk 2.0.17 → 2.0.19

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/cloud-sync.ts

@@ -272,37 +272,188 @@ export interface CloudPatch {
   hasChanges: boolean;
 }
 
-/** The sandbox's post-run diff. Multi-path runs carry several patches and are refused here. */
-export async function downloadCloudPatch(runId: string, options: CloudConnectionOptions): Promise<CloudPatch> {
+/** One entry of a multi-path run's patch map: the mounted path's name and its diff. */
+export interface CloudPathPatch extends CloudPatch {
+  name: string;
+}
+
+/**
+ * What `/patch` answered, in both shapes the endpoint can produce.
+ *
+ * A run that declared mounted `paths` gets one `changes-<name>.patch` per path
+ * and the route answers `{ patches: { <name>: { patch, hasChanges } } }`; every
+ * other run gets `changes.patch` and the flat `{ patch, hasChanges }`. The
+ * multi-path shape is not a v1 relic -- `paths` is orthogonal to
+ * `relayflowVersion`, so a v2 run that submits several paths returns it too.
+ */
+export type CloudPatchSet =
+  | { kind: 'single'; patch: string; hasChanges: boolean }
+  | { kind: 'multi-path'; patches: readonly CloudPathPatch[]; hasChanges: boolean };
+
+/**
+ * The sandbox's post-run diff, in whichever shape the run produced.
+ *
+ * Both shapes are modelled rather than one refused at the transport, so a
+ * caller can show a multi-path run's patches (`flows sync --dry-run`) before
+ * deciding what to do with them. Applying them is still the caller's refusal
+ * to make: they target different repositories and no single tree is the right
+ * destination.
+ */
+export async function downloadCloudPatchSet(
+  runId: string, options: CloudConnectionOptions,
+): Promise<CloudPatchSet> {
   const payload = await cloudRequest(`/api/v1/workflows/runs/${encodeURIComponent(cloudRunId(runId))}/patch`, options);
   if (!isCloudRecord(payload)) throw new CloudFlowError('invalid_response', 'Cloud patch response was not an object.');
   if (isCloudRecord(payload.patches)) {
-    const names = Object.keys(payload.patches);
-    throw new CloudFlowError('sync_unsupported',
-      `Run ${runId} produced ${names.length} path-scoped patches (${names.join(', ')}); flows sync applies single-tree runs only.`);
+    const patches: CloudPathPatch[] = [];
+    for (const [name, entry] of Object.entries(payload.patches)) {
+      if (!isCloudRecord(entry) || typeof entry.patch !== 'string' || typeof entry.hasChanges !== 'boolean') {
+        throw new CloudFlowError('invalid_response', `Cloud patch response has an unusable entry for path "${name}".`);
+      }
+      patches.push({ name, patch: entry.patch, hasChanges: entry.hasChanges });
+    }
+    return { kind: 'multi-path', patches, hasChanges: patches.some(entry => entry.hasChanges && entry.patch.trim() !== '') };
   }
   if (typeof payload.patch !== 'string' || typeof payload.hasChanges !== 'boolean') {
     throw new CloudFlowError('invalid_response', 'Cloud patch response is missing patch or hasChanges.');
   }
-  return { patch: payload.patch, hasChanges: payload.hasChanges };
+  return { kind: 'single', patch: payload.patch, hasChanges: payload.hasChanges };
+}
+
+/** The sandbox's post-run diff. Multi-path runs carry several patches and are refused here. */
+export async function downloadCloudPatch(runId: string, options: CloudConnectionOptions): Promise<CloudPatch> {
+  const set = await downloadCloudPatchSet(runId, options);
+  if (set.kind === 'multi-path') {
+    const names = set.patches.map(entry => entry.name);
+    throw new CloudFlowError('sync_unsupported',
+      `Run ${runId} produced ${names.length} path-scoped patches (${names.join(', ')}); flows sync applies single-tree runs only.`);
+  }
+  return { patch: set.patch, hasChanges: set.hasChanges };
+}
+
+/**
+ * Paths a synced patch must never write, the single home for the list.
+ *
+ * These are the agent runtime's own bookkeeping inside a synced tree: helper
+ * binaries staged for the sandbox, the relayfile mount's ACL and state files
+ * (including the temporaries a mid-write state leaves behind), trajectory
+ * records and workflow context. The sandbox commits its baseline before the
+ * run, so every one of them shows up in the post-run diff as a creation or a
+ * modification -- applying that diff verbatim drags the run's own plumbing into
+ * the user's checkout, where at best it is noise in `git diff` and at worst it
+ * overwrites the mount state of the tree being synced into.
+ *
+ * `git apply --exclude` matches these with wildmatch, anchored at the patch
+ * root and with `*` stopping at a `/`: `.agent-bin/**` drops
+ * `.agent-bin/nested/tool` but deliberately not `packages/x/.agent-bin/tool`,
+ * which belongs to a different tree than the one being synced.
+ */
+export const CLOUD_SYNC_PATCH_EXCLUDES = [
+  '.agent-bin/**',
+  '.relayfile.acl',
+  '.relayfile-mount-state.json',
+  '.relayfile-mount-state.json.tmp-*',
+  '.trajectories/**',
+  '.workflow-context/**',
+] as const;
+
+/** The `a/` and `b/` sides of every `diff --git` header, in file order. */
+function patchHeaders(patch: string): { old: string; new: string }[] {
+  const headers: { old: string; new: string }[] = [];
+  for (const match of patch.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gmu)) {
+    headers.push({ old: match[1]!, new: match[2]! });
+  }
+  return headers;
 }
 
 /** Every path a unified diff touches, deletions included, in order of first appearance. */
 export function patchedPaths(patch: string): string[] {
   const paths: string[] = [];
-  for (const match of patch.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gmu)) {
-    for (const path of [match[1]!, match[2]!]) if (!paths.includes(path)) paths.push(path);
+  for (const header of patchHeaders(patch)) {
+    for (const path of [header.old, header.new]) if (!paths.includes(path)) paths.push(path);
   }
   return paths;
 }
 
+/**
+ * `git apply --exclude`'s wildmatch, as a matcher over a patch's own paths.
+ *
+ * Anchored at the patch root, `**` crosses `/` and `*`/`?` do not -- the subset
+ * of wildmatch {@link CLOUD_SYNC_PATCH_EXCLUDES} uses. Kept honest by a test
+ * that runs the same patterns through `git apply --numstat` and requires the
+ * two answers to agree, so a divergence fails here rather than silently
+ * reporting a path as dropped that git actually wrote.
+ */
+function matchesExclude(path: string, pattern: string): boolean {
+  let expression = '^';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index]!;
+    if (character === '*') {
+      if (pattern[index + 1] === '*') { expression += '.*'; index += 1; continue; }
+      expression += '[^/]*';
+      continue;
+    }
+    expression += character === '?' ? '[^/]' : character.replace(/[.+^${}()|[\]\\]/gu, '\\$&');
+  }
+  return new RegExp(`${expression}$`, 'u').test(path);
+}
+
+/**
+ * The subset of a patch's paths `exclude` drops, in order of first appearance.
+ *
+ * Decided per `diff --git` header on its `b/` side, which is the name `git
+ * apply` itself tests -- so a rename is dropped or kept whole, never half. A
+ * deletion names the same path on both sides, so it is covered by the same rule.
+ */
+export function excludedPatchPaths(
+  patch: string, exclude: readonly string[] = CLOUD_SYNC_PATCH_EXCLUDES,
+): string[] {
+  const paths: string[] = [];
+  for (const header of patchHeaders(patch)) {
+    if (!exclude.some(pattern => matchesExclude(header.new, pattern))) continue;
+    for (const path of [header.old, header.new]) if (!paths.includes(path)) paths.push(path);
+  }
+  return paths;
+}
+
+/** Options for {@link applyCloudPatch}. */
+export interface ApplyCloudPatchOptions {
+  /**
+   * Path patterns to drop, defaulting to {@link CLOUD_SYNC_PATCH_EXCLUDES}.
+   * Pass `[]` to apply a patch whole -- including the runtime artifacts the
+   * default list exists to keep out of a working tree.
+   */
+  exclude?: readonly string[];
+}
+
+/** What {@link applyCloudPatch} wrote, and what it dropped on the way. */
+export interface AppliedCloudPatch {
+  /** Paths the apply wrote, in order of first appearance in the patch. */
+  files: string[];
+  /** Paths `exclude` dropped, in order of first appearance in the patch. */
+  excluded: string[];
+}
+
 /**
  * `git apply --check` then `git apply`; a conflict leaves the tree untouched.
  * The patch lands in the working tree uncommitted, so what the run changed is
- * reviewed with `git diff` before anything is kept — the same contract as v1.
+ * reviewed with `git diff` before anything is kept -- the same contract as v1.
+ *
+ * Both invocations carry the identical `--exclude` arguments. A check run
+ * without them is a different question than the apply answers: it can pass on
+ * an excluded hunk that the apply then never writes, or fail on one and refuse
+ * a patch whose applied part was clean. The exclusions are a property of the
+ * patch that lands, so they belong to both halves or neither.
+ *
+ * A patch whose every path is excluded is a no-op, not a failure: `git apply`
+ * exits 0 having written nothing, and the returned `files` is empty.
  */
-export function applyCloudPatch(root: string, patch: string): void {
-  const args = ['-C', resolve(root), 'apply', '--whitespace=nowarn'];
+export function applyCloudPatch(
+  root: string, patch: string, options: ApplyCloudPatchOptions = {},
+): AppliedCloudPatch {
+  const exclude = options.exclude ?? CLOUD_SYNC_PATCH_EXCLUDES;
+  const args = ['-C', resolve(root), 'apply', '--whitespace=nowarn',
+    ...exclude.map(pattern => `--exclude=${pattern}`)];
   const check = spawnSync('git', [...args, '--check'], { input: patch, encoding: 'utf8' });
   if (check.status !== 0) {
     throw new CloudFlowError('patch_conflict',
@@ -312,4 +463,6 @@ export function applyCloudPatch(root: string, patch: string): void {
   if (apply.status !== 0) {
     throw new CloudFlowError('patch_conflict', `git apply failed:\n${apply.stderr.trim()}`);
   }
+  const excluded = excludedPatchPaths(patch, exclude);
+  return { files: patchedPaths(patch).filter(path => !excluded.includes(path)), excluded };
 }

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;
 
 /**

package/src/flow-requirements.ts

@@ -0,0 +1,201 @@
+import { helperProviders } from '@relayflows/surface/runtime';
+import type { TriggerSource } from '@relayflows/surface';
+import { providerDeclaration } from './provider-trigger-contract.js';
+import type { FlowSpec } from './spec.js';
+import { helperCall } from './yaml-helpers.js';
+
+/**
+ * What a flow needs from the workspace it deploys into, read from inert
+ * declarations only: the header, the trigger sources, and the text of the
+ * body. Nothing here executes a body or opens a socket, so the same answer is
+ * available to `flows check`, to the hosted verbs before they submit, and to
+ * Cloud's deploy wizard from the source alone.
+ *
+ * Helper use is recognised exactly as `preflightHelpers` recognises it — a
+ * `tools.<namespace>: true` flag or a `f.<namespace>` reference in the body —
+ * so a flow that preflight would refuse for a missing mount is a flow whose
+ * integration this module names. Coding-agent harnesses come from the `cli:`
+ * each `f.agent`/`f.llm` call declares, else the project default, else Cloud's
+ * default (`claude`): the same precedence `resolveCli` applies at run time.
+ */
+
+export const FLOW_HARNESSES = ['claude', 'codex', 'gemini'] as const;
+export type FlowHarness = (typeof FLOW_HARNESSES)[number];
+
+export interface FlowIntegrationRequirement {
+  /** Cloud integration provider id (`slack`, `github`, `linear`, …). */
+  provider: string;
+  /** `tools`: a header declaration; `source`: a trigger or deploy target; `helper`: body use without a flag, or a YAML helper step. */
+  from: 'tools' | 'source' | 'helper';
+  /** The declaration that requires it, as a reader would name it: `tools.slack`, `--on github`, `f.slack`. */
+  detail: string;
+}
+
+export interface FlowHarnessRequirement {
+  harness: FlowHarness;
+  /** `agent "review"`, `llm step`, `step "draft"`, or `default`. */
+  detail: string;
+}
+
+export interface FlowRequirements {
+  integrations: FlowIntegrationRequirement[];
+  harnesses: FlowHarness[];
+  /** One entry per harness, naming the first declaration that needs it. */
+  harnessUses: FlowHarnessRequirement[];
+  /** MCP servers `tools.mcp` names; the workspace must declare each in `flows.json`. */
+  mcp: string[];
+}
+
+export interface FlowRequirementsContext {
+  /** Trigger sources the deployment listens on (`--on`, or the wizard's chosen sources). */
+  sources?: readonly { provider: string }[];
+  /** Set when the deployment targets a repository: every launched run needs GitHub. */
+  repository?: boolean | { owner: string; name: string };
+  /** The nearest `flows.json` `cli`, when one applies. */
+  projectCli?: string;
+}
+
+/** The inert subset of an authored definition this module reads. */
+export interface RequirementsFlowDefinition {
+  readonly header?: { readonly tools?: Readonly<Record<string, unknown>> };
+  readonly body?: Function;
+  readonly handlers?: readonly { readonly trigger: TriggerSource }[];
+}
+
+export function flowRequirements(
+  flow: RequirementsFlowDefinition | FlowSpec,
+  context: FlowRequirementsContext = {},
+): FlowRequirements {
+  const integrations = new Map<string, FlowIntegrationRequirement>();
+  const harnessUses = new Map<FlowHarness, FlowHarnessRequirement>();
+  const mcp = new Set<string>();
+  const declare = (requirement: FlowIntegrationRequirement): void => {
+    if (!integrations.has(requirement.provider)) integrations.set(requirement.provider, requirement);
+  };
+  const need = (harness: FlowHarness | undefined, detail: string): void => {
+    if (harness !== undefined && !harnessUses.has(harness)) harnessUses.set(harness, { harness, detail });
+  };
+  const fallback = harnessFromCli(context.projectCli) ?? 'claude';
+
+  if (isCompiledSpec(flow)) {
+    for (const step of flow.steps) {
+      // Preflight owns shape refusals; a malformed step is simply not a worker step here.
+      if (typeof step !== 'object' || step === null || (step.type !== 'llm' && step.type !== 'agent')) continue;
+      // A YAML helper step (`slack: { post: … }`) compiles to an agent step
+      // carrying a helper envelope: it needs the provider's mount, not a harness.
+      const helper = step.type === 'agent' ? compiledHelper(step) : undefined;
+      if (helper !== undefined) {
+        declare({ provider: helper, from: 'helper', detail: `step "${step.id}"` });
+        continue;
+      }
+      const named = step.type === 'agent' && step.agent !== undefined ? flow.agents?.[step.agent]?.cli : undefined;
+      const cli = step.cli ?? named ?? flow.cli;
+      need(cli === undefined ? fallback : harnessFromCli(cli), `step "${step.id}"`);
+    }
+  } else {
+    const tools = flow.header?.tools ?? {};
+    for (const { provider, namespace } of helperProviders) {
+      if (tools[namespace] === true) declare({ provider, from: 'tools', detail: `tools.${namespace}` });
+    }
+    for (const entry of stringList(tools['relayfile'])) {
+      const provider = entry.split('/')[0]?.trim();
+      if (provider) declare({ provider, from: 'tools', detail: 'tools.relayfile' });
+    }
+    for (const server of stringList(tools['mcp'])) mcp.add(server);
+    for (const handler of flow.handlers ?? []) {
+      const declaration = providerDeclaration(handler.trigger);
+      if (declaration !== undefined) {
+        declare({ provider: declaration.provider, from: 'source', detail: `on ${declaration.provider} ${declaration.type}` });
+      }
+    }
+    // Only the default body is scanned for helper and worker calls: hosted
+    // deployments and schedules dispatch the default body with the trigger's
+    // payload as input, and handler bodies are not dispatched yet (flows #301).
+    // A handler's *trigger* is still a requirement — it is what wakes the flow.
+    const text = typeof flow.body === 'function' ? Function.prototype.toString.call(flow.body) : '';
+    const root = contextParameter(text);
+    if (root !== undefined) {
+      for (const { provider, namespace } of helperProviders) {
+        if (helperReference(root, namespace).test(text)) declare({ provider, from: 'helper', detail: `f.${namespace}` });
+      }
+      for (const use of workerCalls(root, text)) need(use.cli === undefined ? fallback : harnessFromCli(use.cli), use.detail);
+    }
+  }
+
+  for (const source of context.sources ?? []) {
+    declare({ provider: source.provider, from: 'source', detail: `--on ${source.provider}` });
+  }
+  if (context.repository) declare({ provider: 'github', from: 'source', detail: 'deploy target' });
+
+  const uses = [...harnessUses.values()];
+  return {
+    integrations: [...integrations.values()],
+    harnesses: uses.map(use => use.harness),
+    harnessUses: uses,
+    mcp: [...mcp],
+  };
+}
+
+/** `slack (tools.slack), github (deploy target), claude (agent "review")` — the `REQUIRES` line's body. */
+export function describeFlowRequirements(requirements: FlowRequirements): string {
+  return [
+    ...requirements.integrations.map(integration => `${integration.provider} (${integration.detail})`),
+    ...requirements.harnessUses.map(use => `${use.harness} (${use.detail})`),
+    ...requirements.mcp.map(server => `mcp ${server} (tools.mcp)`),
+  ].join(', ');
+}
+
+/** `claude`, `/opt/bin/codex`, `gemini.exe` → the Cloud harness; anything else is not one. */
+export function harnessFromCli(cli: string | undefined): FlowHarness | undefined {
+  if (cli === undefined) return undefined;
+  const base = cli.trim().split(/[\\/]/u).pop()?.replace(/\.(?:exe|cmd|bat)$/iu, '').toLowerCase();
+  return (FLOW_HARNESSES as readonly string[]).includes(base ?? '') ? base as FlowHarness : undefined;
+}
+
+/** The provider of a compiled YAML helper step, or undefined for an ordinary agent step or a malformed envelope. */
+function compiledHelper(step: Parameters<typeof helperCall>[0]): string | undefined {
+  try {
+    return helperCall(step)?.provider;
+  } catch {
+    return undefined;
+  }
+}
+
+function isCompiledSpec(flow: RequirementsFlowDefinition | FlowSpec): flow is FlowSpec {
+  return Array.isArray((flow as FlowSpec).steps) && typeof (flow as FlowSpec).version === 'string';
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+/** The body's first parameter (`f` in `async (f, input) => …`), escaped for a pattern. */
+function contextParameter(body: string): string | undefined {
+  const parameter = body.match(/^(?:async\s+)?(?:function(?:\s+[\w$]+)?\s*)?(?:\(\s*([\w$]+)|([\w$]+)\s*=>)/u);
+  return (parameter?.[1] ?? parameter?.[2])?.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+/** Same recognition as `preflightHelpers`: `f.slack`, `f .slack`, `f["slack"]`. */
+function helperReference(root: string, namespace: string): RegExp {
+  return new RegExp(`(?:^|[^\\w$.])${root}\\s*(?:\\.\\s*${namespace}\\b|\\[\\s*['"]${namespace}['"]\\s*\\])`, 'u');
+}
+
+interface WorkerCall { detail: string; cli?: string }
+
+/**
+ * Each `f.agent(name, { cli })` / `f.llm(prompt, { cli })` call and the CLI it
+ * declares. The options object is read only up to the next worker call, so a
+ * `cli:` belongs to the call it follows; a call without one takes the default.
+ */
+function workerCalls(root: string, body: string): WorkerCall[] {
+  const call = new RegExp(`(?:^|[^\\w$.])${root}\\s*\\.\\s*(agent|llm)\\s*\\(\\s*(?:(['"\`])([^'"\`]*)\\2)?`, 'gu');
+  const starts = [...body.matchAll(call)];
+  return starts.map((match, index) => {
+    const slice = body.slice(match.index! + match[0].length, starts[index + 1]?.index ?? body.length);
+    const cli = slice.match(/(?:^|[^\w$])cli\s*:\s*(['"`])([^'"`]*)\1/u)?.[2];
+    const detail = match[1] === 'agent'
+      ? (match[3] ? `agent ${JSON.stringify(match[3])}` : 'agent step')
+      : 'llm step';
+    return { detail, ...(cli === undefined ? {} : { cli }) };
+  });
+}

package/src/index.ts

@@ -64,8 +64,10 @@ export {
   type CloudFlowSource, type RunInCloudOptions, type CloudRunReceipt, type CloudRunState,
 } from './cloud-run.js';
 export {
-  downloadCloudPatch, applyCloudPatch, packWorkingTree, patchedPaths, MAX_SYNC_BYTES,
-  type CloudPatch, type PackedTree,
+  downloadCloudPatch, downloadCloudPatchSet, applyCloudPatch, packWorkingTree, patchedPaths,
+  excludedPatchPaths, CLOUD_SYNC_PATCH_EXCLUDES, MAX_SYNC_BYTES,
+  type CloudPatch, type CloudPathPatch, type CloudPatchSet, type PackedTree,
+  type ApplyCloudPatchOptions, type AppliedCloudPatch,
 } from './cloud-sync.js';
 export {
   scheduleInCloud, listCloudSchedules, unscheduleInCloud, everyToCron, declaredScheduleCron,
@@ -76,6 +78,14 @@ export {
   deployToCloud, listCloudDeployments, undeployFromCloud, parseRepository, parseTriggerSource, FLOW_TRIGGER_PROVIDERS,
   type DeployToCloudInput, type CloudDeployment, type CloudDeploymentSummary, type FlowTriggerSource, type FlowTriggerProvider,
 } from './cloud-deploy.js';
+export {
+  ensureIntegrationsConnected, integrationConnected, providerLabel,
+  type ConnectPrompt, type EnsureConnectionsOptions, type ConnectionsOutcome,
+} from './cloud-connect.js';
+export {
+  flowRequirements, describeFlowRequirements, harnessFromCli, FLOW_HARNESSES,
+  type FlowRequirements, type FlowRequirementsContext, type FlowIntegrationRequirement, type FlowHarnessRequirement, type FlowHarness,
+} from './flow-requirements.js';
 
 export { canonicalize, specHash } from './canonical.js';
 export {

package/src/journal-client.ts

@@ -386,6 +386,26 @@ export class JournalClient extends EventEmitter {
   }
 
   /** Satisfy `wait.event`; a human response arrives here too. */
+  /**
+   * Park the dispatched attempt this connection holds on a human question.
+   * Releases the lease; the caller must not heartbeat or complete afterwards.
+   */
+  stepWait(
+    runId: string,
+    stepId: string,
+    attempt: number,
+    idempotencyKey: string,
+    wait: { wait_id: string; prompt: string; requested_of: string; options?: string[]; timeout_at_ms?: number },
+  ): Promise<VerbContract['step.wait']['result']> {
+    return this.request('step.wait', {
+      run_id: runId,
+      step_id: stepId,
+      attempt,
+      idempotency_key: idempotencyKey,
+      ...wait,
+    });
+  }
+
   eventEmit(runId: string, eventKey: string, payload: unknown): Promise<VerbContract['event.emit']['result']> {
     return this.request('event.emit', { run_id: runId, event_key: eventKey, payload });
   }