@relayflows/sdk 2.0.16 → 2.0.18

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
@@ -21,7 +25,9 @@ export type FlowTriggerProvider = (typeof FLOW_TRIGGER_PROVIDERS)[number];
 
 /** Settings Cloud's launcher prefilter reads per provider (`flow-trigger-sources.ts`). */
 const PROVIDER_SETTINGS: Record<FlowTriggerProvider, readonly string[]> = {
-  github: ['repository', 'labels', 'contains'],
+  // `events`: `issues` (default) or `pull_request` — which GitHub records
+  // wake the listener (AgentWorkforce/cloud#3772).
+  github: ['repository', 'labels', 'contains', 'events'],
   slack: ['channel', 'contains'],
   linear: ['team', 'contains'],
   jira: ['project', 'contains'],
@@ -45,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;
@@ -70,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 } {
@@ -102,6 +124,15 @@ export function parseTriggerSource(value: string): FlowTriggerSource {
       if (!setting || setting.length > MAX_SETTING_LENGTH || key in settings) {
         throw new CloudFlowError('invalid_input', `Trigger setting "${key}" must be given once with a non-empty value.`);
       }
+      if (key === 'events') {
+        // Cloud's enum is lowercase; send it that way whatever the shell typed.
+        const events = setting.toLowerCase();
+        if (!['issues', 'pull_request'].includes(events)) {
+          throw new CloudFlowError('invalid_input', `github events must be "issues" or "pull_request", got "${setting}".`);
+        }
+        settings[key] = events;
+        continue;
+      }
       settings[key] = setting;
     }
   }
@@ -143,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.');
   }
@@ -165,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',
@@ -177,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.');
@@ -185,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

@@ -12,13 +12,23 @@ export interface CloudConnectionOptions {
   requestTimeoutMs?: number;
 }
 
+/** A refusal Cloud answered as JSON: only these fields are ever read. */
+export interface CloudRefusal {
+  code: string;
+  error: string;
+  /** Version-only descriptions, when a route names what it wanted vs. got. */
+  expected?: { packageName?: string; version?: string };
+  received?: { packageName?: string; version?: string };
+}
+
 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,
   ) {
     super(message);
     this.name = 'CloudFlowError';
@@ -175,10 +185,20 @@ export async function cloudFetch(
   }
   if (!response.ok) {
     // Do not echo server response bodies: they may contain credentials or source.
-    const refusal = init.detail ? await structuredRefusal(response) : undefined;
+    // Reading the body is itself a transport step: a cancellation or timeout
+    // there keeps its own classification instead of becoming an http_error.
+    let refusal: CloudRefusal | undefined;
+    if (init.detail) {
+      try {
+        refusal = await structuredRefusal(response);
+      } catch (error) {
+        options.signal?.throwIfAborted();
+        throw transportError(deadline.aborted ? deadline.reason : error);
+      }
+    }
     throw new CloudFlowError('http_error', refusal === undefined
       ? `Cloud request failed with HTTP ${response.status}.`
-      : `Cloud refused (${refusal.code}): ${refusal.error}`, response.status);
+      : `Cloud refused (${refusal.code}): ${refusal.error}`, response.status, refusal);
   }
   try {
     return await response.json();
@@ -189,12 +209,36 @@ export async function cloudFetch(
   }
 }
 
-async function structuredRefusal(response: Response): Promise<{ code: string; error: string } | undefined> {
+const REFUSAL_CODE = /^[a-z0-9_]{1,64}$/u;
+
+/**
+ * Routes answer either `{ code, error }` or a bare `{ error: "<code>" }`;
+ * both are read, and an optional `expected`/`received` pair is reduced to
+ * package name and version. Nothing else in the body is looked at.
+ */
+async function structuredRefusal(response: Response): Promise<CloudRefusal | undefined> {
   let body: unknown;
-  try { body = await response.json(); } catch { return undefined; }
-  if (!isCloudRecord(body) || typeof body.code !== 'string' || typeof body.error !== 'string') return undefined;
-  if (!/^[a-z0-9_]{1,64}$/u.test(body.code) || body.error.length > 500) return undefined;
-  return { code: body.code, error: body.error };
+  try {
+    body = await response.json();
+  } catch (error) {
+    // Only a body that is not JSON is "no structured refusal"; an aborted or
+    // timed-out read is a transport failure and propagates.
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+  if (!isCloudRecord(body) || typeof body.error !== 'string' || body.error.length > 500) return undefined;
+  const code = typeof body.code === 'string' ? body.code : body.error;
+  if (!REFUSAL_CODE.test(code)) return undefined;
+  const versionOnly = (value: unknown): CloudRefusal['expected'] => {
+    if (!isCloudRecord(value)) return undefined;
+    const out: { packageName?: string; version?: string } = {};
+    if (typeof value.packageName === 'string' && value.packageName.length <= 100) out.packageName = value.packageName;
+    if (typeof value.version === 'string' && /^[0-9A-Za-z.+-]{1,64}$/u.test(value.version)) out.version = value.version;
+    return out;
+  };
+  const expected = versionOnly(body.expected);
+  const received = versionOnly(body.received);
+  return { code, error: body.error, ...(expected ? { expected } : {}), ...(received ? { received } : {}) };
 }
 
 // Defensive path-segment constraint; accepting a new server ID format needs an SDK change.

package/src/cloud-run.ts

@@ -1,4 +1,4 @@
-import { RUN_COMPLETION_REASONS } from '@relayflows/surface';
+import { RUN_COMPLETION_REASONS, type ScheduleTriggerSource } from '@relayflows/surface';
 import type { RunCompletionReason } from './protocol.js';
 import { readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
@@ -10,7 +10,7 @@ import type { FlowSpec } from './spec.js';
 import { snapshotJsonValue, type JsonValue } from './json-value.js';
 import { loadAuthoredFlow, type SurfaceModuleAuthority } from './authored-flow-loader.js';
 import {
-  CloudFlowError, cloudConnection, cloudRequest, cloudRunId, isCloudRecord,
+  CloudFlowError, cloudConnection, cloudFetch, cloudRequest, cloudRunId, isCloudRecord,
   type CloudConnectionOptions,
 } from './cloud-http.js';
 import { packWorkingTree, prepareCloudSync, uploadCloudCode } from './cloud-sync.js';
@@ -53,6 +53,17 @@ export interface CloudAuthoredAuthority {
   readonly byteLength: number;
   readonly surface: SurfaceModuleAuthority;
 }
+/** The request-body fields a submission contributes; identical for a run and a schedule. */
+export function cloudSubmissionBody(submission: CloudSubmission): Record<string, unknown> {
+  return {
+    workflow: submission.workflow,
+    fileType: submission.fileType,
+    relayflowVersion: 'v2',
+    ...(submission.authoredAuthority === undefined ? {} : { authoredAuthority: submission.authoredAuthority }),
+    ...(submission.inputPresent ? { inputs: submission.inputs } : {}),
+  };
+}
+
 export type CloudRunState =
   | { runId: string; status: 'pending' | 'launching' | 'running' }
   | { runId: string; status: 'completed' | 'failed' | 'cancelled'; completionReason: RunCompletionReason };
@@ -62,13 +73,31 @@ export type CloudRunState =
  * happens here; Cloud owns provisioning and the Rust engine owns execution.
  * Returns acceptance, not completion. No local daemon, CLI probe, or node up.
  */
-export async function runInCloud(
+/**
+ * What a Cloud submission carries, before any request: the exact source or
+ * canonical spec, the pinned authority for authored source, the input, and a
+ * local correlation hash. Shared by `runInCloud` and `scheduleInCloud`, so a
+ * schedule stores exactly what a run would send.
+ */
+export interface CloudSubmission {
+  readonly workflow: string;
+  readonly fileType: 'yaml' | 'ts';
+  readonly authoredAuthority?: CloudAuthoredAuthority;
+  readonly inputs?: JsonValue;
+  readonly inputPresent: boolean;
+  readonly specHash: string;
+  /** The authored flow's declared name, or the spec name. */
+  readonly name: string;
+  /** Authored `schedule.*` handlers, for `flows schedule` to pick up. */
+  readonly schedules: readonly ScheduleTriggerSource[];
+}
+
+export async function prepareCloudSubmission(
   flow: CloudFlowSource,
-  options: RunInCloudOptions = {},
-): Promise<CloudRunReceipt> {
-  const { baseUrl } = cloudConnection(options);
+  options: { input?: JsonValue; signal?: AbortSignal } = {},
+): Promise<CloudSubmission> {
   let spec: FlowSpec | undefined;
-  let authored: { source: string; authority: CloudAuthoredAuthority } | undefined;
+  let authored: { source: string; authority: CloudAuthoredAuthority; name: string; schedules: ScheduleTriggerSource[] } | undefined;
   const inputPresent = Object.prototype.hasOwnProperty.call(options, 'input');
   let authoredInput: JsonValue | undefined;
   try {
@@ -80,14 +109,27 @@ export async function runInCloud(
         if (!bytes.length || Buffer.from(source, 'utf8').compare(bytes) !== 0) {
           throw new CloudFlowError('invalid_input', 'Authored source must be nonempty, lossless UTF-8.');
         }
-        const loaded = await loadAuthoredFlow(flow.path);
-        loaded.getDefinition(loaded.handle);
+        let loaded: Awaited<ReturnType<typeof loadAuthoredFlow>>;
+        let definition: ReturnType<typeof loaded.getDefinition>;
+        try {
+          loaded = await loadAuthoredFlow(flow.path);
+          definition = loaded.getDefinition(loaded.handle);
+        } catch (error) {
+          // An authored source that does not load is an authoring problem, and
+          // the most common one is `@relayflows/surface` not being resolvable
+          // from the flow's directory. Name it; do not call it a spec problem.
+          throw new CloudFlowError('unsupported_source',
+            `${flow.path} is not a loadable authored flow: ${error instanceof Error ? error.message : String(error)}. `
+            + 'Run `flows check` on it from the same directory.');
+        }
         if (loaded.graph.length !== 1) {
           throw new CloudFlowError('unsupported_source',
             'Cloud authored submission currently accepts one self-contained .flow.ts source without use dependencies.');
         }
         authored = {
           source,
+          name: definition.name,
+          schedules: definition.handlers.flatMap(h => h.trigger.kind === 'schedule' ? [h.trigger] : []),
           authority: Object.freeze({
             schemaVersion: 1,
             sourceSha256: createHash('sha256').update(bytes).digest('hex'),
@@ -130,12 +172,32 @@ export async function runInCloud(
     throw new CloudFlowError('invalid_input', 'Cannot read or compile the declarative flow. Check the file path and YAML/JSON spec.');
   }
   options.signal?.throwIfAborted();
-  const hash = authored === undefined
-    ? specHash(toKernelSpec(spec!))
-    : createHash('sha256').update(canonicalize({
-        authority: authored.authority,
-        input: authoredInput,
-      })).digest('hex');
+  if (authored === undefined) {
+    const kernel = toKernelSpec(spec!);
+    // JSON is a YAML subset. Sending canonical data preserves the exact spec
+    // while using the server's existing YAML-to-config admission path.
+    return { workflow: canonicalize(spec), fileType: 'yaml', inputPresent: false, specHash: specHash(kernel),
+      name: spec!.name ?? "flow", schedules: [] };
+  }
+  return {
+    workflow: authored.source, fileType: 'ts', authoredAuthority: authored.authority,
+    inputs: authoredInput, inputPresent: true, name: authored.name, schedules: authored.schedules,
+    specHash: createHash('sha256').update(canonicalize({ authority: authored.authority, input: authoredInput })).digest('hex'),
+  };
+}
+
+/**
+ * Submit a declarative flow to Cloud's pinned v2 runtime. Compilation only
+ * happens here; Cloud owns provisioning and the Rust engine owns execution.
+ * Returns acceptance, not completion. No local daemon, CLI probe, or node up.
+ */
+export async function runInCloud(
+  flow: CloudFlowSource,
+  options: RunInCloudOptions = {},
+): Promise<CloudRunReceipt> {
+  const { baseUrl } = cloudConnection(options);
+  const submission = await prepareCloudSubmission(flow, options);
+  const hash = submission.specHash;
   // Sync before submission: `prepare` reserves the run ID and the upload lands
   // under it, so the run request below names code Cloud already holds. A
   // refused backend or failed upload therefore never leaves a launched run
@@ -156,17 +218,28 @@ export async function runInCloud(
   }
   options.signal?.throwIfAborted();
   options.onSubmit?.();
-  const result = await cloudRequest('/api/v1/workflows/run', options, {
-    // JSON is a YAML subset. Sending canonical data preserves the exact spec
-    // while using the server's existing YAML-to-config admission path.
-    workflow: authored?.source ?? canonicalize(spec),
-    fileType: authored === undefined ? 'yaml' : 'ts',
-    relayflowVersion: 'v2',
-    ...(authored === undefined ? {} : { authoredAuthority: authored.authority }),
-    ...(authored === undefined ? {} : { inputs: authoredInput }),
-    ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
-    ...(synced === undefined ? {} : { runId: synced.runId, s3CodeKey: synced.codeKey }),
-  });
+  let result: unknown;
+  try {
+    result = await cloudFetch('/api/v1/workflows/run', options, { method: 'POST', detail: true, body: JSON.stringify({
+      ...cloudSubmissionBody(submission),
+      ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+      ...(synced === undefined ? {} : { runId: synced.runId, s3CodeKey: synced.codeKey }),
+    }) });
+  } catch (error) {
+    // Cloud accepts exactly one authored Surface (the one its sandbox runs).
+    // A CLI on another release is refused with this code; say which side is
+    // which instead of leaving the user with a bare 400 (flows#461).
+    if (error instanceof CloudFlowError && submission.authoredAuthority !== undefined
+      && error.refusal?.code === 'relayflow_v2_authored_authority_invalid') {
+      const expected = error.refusal.expected?.version;
+      throw new CloudFlowError('unsupported_source',
+        `Cloud refused this authored flow's Surface: it runs @relayflows/surface ${expected ?? '(version not reported)'} `
+        + `and this CLI authored against ${submission.authoredAuthority.surface.version}. `
+        + 'Install the matching relayflows release, or deploy the flow with `flows deploy`, which uses Cloud\'s own Surface.',
+        error.status, error.refusal);
+    }
+    throw error;
+  }
   if (!isCloudRecord(result) || (result.status !== 'pending' && result.status !== 'running')) {
     throw new CloudFlowError('invalid_response', 'Cloud did not return an accepted run.');
   }