@relayflows/sdk 2.0.38 → 2.0.39

package/dist/cloud-versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-versions.js","sourceRoot":"","sources":["../src/cloud-versions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/sdk",
-  "version": "2.0.38",
+  "version": "2.0.39",
   "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@relayfile/adapter-core": "0.6.2",
     "@relayfile/relay-helpers": "0.4.12",
-    "@relayflows/surface": "2.0.38",
+    "@relayflows/surface": "2.0.39",
     "@types/js-yaml": "^4.0.9",
     "acorn": "^8.18.0",
     "ai-hist": "0.4.1",

package/src/cli/cloud-deploy.ts

@@ -4,13 +4,17 @@ import {
   type FlowTriggerSource,
 } from '../cloud-deploy.js';
 import { describeFlowRequirements } from '../flow-requirements.js';
+import { describeVersionChange } from '../cloud-versions-wire.js';
+import { runCloudDeployVersionCli } from './cloud-versions.js';
 import { cliConnectPrompt, flowRequirementsForPath, harnessRemedy } from './cloud-connect-cli.js';
 import type { CliIo } from '../cli.js';
 
 export interface CloudDeployArgs {
   command: 'cloud-deploy';
   value: string;
-  repo: string;
+  /** Update form: the flow (name or listener id) this source becomes the next version of. */
+  flow: string | undefined;
+  repo: string | undefined;
   on: string[];
   approver: string | undefined;
   name: string | undefined;
@@ -25,6 +29,11 @@ export interface CloudDeployArgs {
 /**
  * `flows deploy <flow.ts> --repo <owner/name> --on <provider>[:k=v,…] [--on …]
  *   --approver <handle> [--name <n>] [--agents <list>] [--draft] [--no-connect] [--json]`
+ * `flows deploy <flow.ts> --flow <name-or-listener-id> [--plugin <ref>] [--no-connect] [--json]`
+ *
+ * The `--flow` form makes the source the next version of an existing flow and
+ * changes nothing else; listener settings given beside it are refused when run,
+ * by name, rather than silently ignored.
  *
  * 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 +41,7 @@ export interface CloudDeployArgs {
  */
 export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs | undefined {
   let value: string | undefined;
+  let flow: string | undefined;
   let repo: string | undefined;
   let approver: string | undefined;
   let name: string | undefined;
@@ -72,11 +82,12 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
       i += 1;
       continue;
     }
-    if (arg === '--repo' || arg === '--approver' || arg === '--name' || arg === '--on') {
+    if (arg === '--repo' || arg === '--approver' || arg === '--name' || arg === '--on' || arg === '--flow') {
       const next = args[i + 1];
       if (next === undefined || next.startsWith('-')) return undefined;
       i += 1;
       if (arg === '--on') { on.push(next); continue; }
+      if (arg === '--flow') { if (flow !== undefined) return undefined; flow = next; continue; }
       if (arg === '--repo') { if (repo !== undefined) return undefined; repo = next; continue; }
       if (arg === '--approver') { if (approver !== undefined) return undefined; approver = next; continue; }
       if (name !== undefined) return undefined;
@@ -86,8 +97,9 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
     if (arg.startsWith('-') || value !== undefined) return undefined;
     value = arg;
   }
-  if (value === undefined || repo === undefined || on.length === 0) return undefined;
-  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, noConnect, json, plugins };
+  if (value === undefined) return undefined;
+  if (flow === undefined && (repo === undefined || on.length === 0)) return undefined;
+  return { command: 'cloud-deploy', value, flow, repo, on, approver, name, agents, draft, noConnect, json, plugins };
 }
 
 function describeSource(source: FlowTriggerSource): string {
@@ -96,6 +108,7 @@ function describeSource(source: FlowTriggerSource): string {
 }
 
 export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promise<0 | 1 | 2> {
+  if (args.flow !== undefined) return runCloudDeployVersionCli({ ...args, flow: args.flow }, io);
   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
@@ -111,7 +124,7 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
     if (agents === undefined) harnesses = (await flowRequirementsForPath(args.value))?.harnesses ?? [];
     const deployment = await deployToCloud({
       path: args.value,
-      repository: parseRepository(args.repo),
+      repository: parseRepository(args.repo!),
       sources: args.on.map(parseTriggerSource),
       approver: args.approver,
       draft: args.draft,
@@ -124,7 +137,8 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
       io.stdout(JSON.stringify({ ok: true, ...deployment }));
       return 0;
     }
-    io.stdout(`${deployment.status === 'draft' ? 'SAVED' : 'DEPLOYED'} ${deployment.agentId} ${deployment.status}`);
+    io.stdout(`${deployment.status === 'draft' ? 'SAVED' : 'DEPLOYED'} ${deployment.agentId} ${deployment.status}`
+      + (deployment.version === undefined ? '' : ` · ${describeVersionChange(deployment.version)}`));
     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)}`);
@@ -181,7 +195,7 @@ export async function runCloudUndeployCli({ agentId, json }: { agentId: string;
   }
 }
 
-function reportCloudFailure(error: unknown, json: boolean, io: CliIo, harnesses: readonly string[] = []): 1 | 2 {
+export 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.

package/src/cli/cloud-versions.ts

@@ -0,0 +1,103 @@
+import { CloudFlowError } from '../cloud-http.js';
+import {
+  activateCloudFlowVersion, deployVersionToCloud, getCloudListener, resolveCloudFlow,
+} from '../cloud-versions.js';
+import { describeVersionChange } from '../cloud-versions-wire.js';
+import { describeFlowRequirements } from '../flow-requirements.js';
+import { cliConnectPrompt } from './cloud-connect-cli.js';
+import { reportCloudFailure, type CloudDeployArgs } from './cloud-deploy.js';
+import type { CliIo } from '../cli.js';
+
+/**
+ * `flows deploy <flow.ts> --flow <name-or-id>`: the source becomes the next
+ * version of that flow. Listener settings are not part of a version, so a
+ * flag that would change one is refused by name instead of being dropped.
+ */
+export async function runCloudDeployVersionCli(
+  args: CloudDeployArgs & { flow: string }, io: CliIo,
+): Promise<0 | 1 | 2> {
+  try {
+    const settings = [
+      args.repo === undefined ? undefined : '--repo',
+      args.on.length === 0 ? undefined : '--on',
+      args.approver === undefined ? undefined : '--approver',
+      args.name === undefined ? undefined : '--name',
+      args.agents === undefined ? undefined : '--agents',
+      args.draft ? '--draft' : undefined,
+    ].filter((flag): flag is string => flag !== undefined);
+    if (settings.length > 0) {
+      throw new CloudFlowError('invalid_input',
+        `--flow deploys a new version of the flow's source only; ${settings.join(', ')} stay on the listener. `
+        + 'Drop them, or change them in the Cloud dashboard.');
+    }
+    const connect = cliConnectPrompt(io, { noConnect: args.noConnect, json: args.json });
+    const deployment = await deployVersionToCloud({
+      path: args.value,
+      flow: args.flow,
+      ...(connect === undefined ? {} : { connect }),
+      ...(args.plugins.length === 0 ? {} : { plugins: args.plugins }),
+    });
+    if (args.json) {
+      io.stdout(JSON.stringify({ ok: true, ...deployment }));
+      return 0;
+    }
+    io.stdout(`${deployment.status === 'draft' ? 'SAVED' : 'DEPLOYED'} ${deployment.agentId} ${deployment.status}`
+      + ` · ${describeVersionChange(deployment.version)}`);
+    io.stdout(`  flow: ${deployment.name} (${args.value}, sha256 ${deployment.sourceSha256.slice(0, 12)})`);
+    const requires = describeFlowRequirements(deployment.requirements);
+    if (requires) io.stdout(`  requires: ${requires}`);
+    for (const provider of deployment.connected) io.stdout(`  connected: ${provider}`);
+    io.stdout('New runs launch this version; runs already started finish on theirs. History: flows versions '
+      + JSON.stringify(deployment.name));
+    return 0;
+  } catch (error) {
+    return reportCloudFailure(error, args.json, io);
+  }
+}
+
+/** `flows versions <name-or-id>`: newest first, the active one marked. */
+export async function runCloudVersionsCli(
+  { flow, json }: { flow: string; json: boolean }, io: CliIo,
+): Promise<0 | 1 | 2> {
+  try {
+    const listener = await getCloudListener(await resolveCloudFlow(flow));
+    if (json) {
+      io.stdout(JSON.stringify({
+        ok: true, agentId: listener.agentId, name: listener.name,
+        activeVersion: listener.activeVersion?.version ?? null, versions: listener.versions,
+      }));
+      return 0;
+    }
+    if (listener.versions.length === 0) {
+      io.stdout(`${listener.agentId} ${JSON.stringify(listener.name)} has no recorded versions.`);
+      return 0;
+    }
+    io.stdout(`${listener.agentId} ${JSON.stringify(listener.name)} ${listener.status}`);
+    for (const version of listener.versions) {
+      const active = version.version === listener.activeVersion?.version ? ' (active)' : '';
+      io.stdout(`  version ${version.version}${active}  ${version.createdAt}  ${version.origin}  sha256 ${version.sourceSha256.slice(0, 12)}`);
+    }
+    return 0;
+  } catch (error) {
+    return reportCloudFailure(error, json, io);
+  }
+}
+
+/** `flows rollback <name-or-id> <version>`: move the pointer; later versions stay recorded. */
+export async function runCloudRollbackCli(
+  { flow, version, json }: { flow: string; version: string; json: boolean }, io: CliIo,
+): Promise<0 | 1 | 2> {
+  try {
+    // Cloud numbers versions up to nine digits; anything longer cannot exist.
+    if (!/^[1-9][0-9]{0,8}$/u.test(version)) {
+      throw new CloudFlowError('invalid_input', `A version is a positive whole number, got "${version}".`);
+    }
+    const result = await activateCloudFlowVersion(flow, Number(version));
+    io.stdout(json
+      ? JSON.stringify({ ok: true, ...result })
+      : `ACTIVATED ${result.agentId} ${result.status} · ${describeVersionChange(result.version)}`);
+    return 0;
+  } catch (error) {
+    return reportCloudFailure(error, json, io);
+  }
+}

package/src/cli-commands.ts

@@ -163,11 +163,29 @@ export const CLI_VERBS = [
       { flags: '--name <name>', description: 'Name for the hosted listener' },
       { flags: '--draft', description: 'Create the listener without activating it' },
       { flags: '--plugin <ref>', description: 'Send-only GitHub flow-extension ref; repeatable. Does not write flows.json' },
+      { flags: '--flow <name|listener-id>', description: 'Deploy the source as the next version of this flow; its settings stay unchanged' },
       NO_CONNECT_OPTION,
       JSON_OPTION,
     ],
     variants: ['deploy', 'cloud-deploy'],
   },
+  {
+    name: 'versions',
+    description: 'List a hosted flow’s source versions, the active one marked',
+    args: [{ name: 'flow', description: 'Flow name or listener id', required: true }],
+    options: [JSON_OPTION],
+    variants: ['versions'],
+  },
+  {
+    name: 'rollback',
+    description: 'Make an earlier (or later) recorded version of a hosted flow the active one',
+    args: [
+      { name: 'flow', description: 'Flow name or listener id', required: true },
+      { name: 'version', description: 'Version number to activate', required: true },
+    ],
+    options: [JSON_OPTION],
+    variants: ['rollback'],
+  },
   {
     name: 'deployments',
     description: 'List this workspace’s hosted trigger listeners',

package/src/cli.ts

@@ -44,6 +44,7 @@ import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
 import { runCloudSyncCli } from './cli/cloud-sync.js';
 import { parseCloudDeployArgs, runCloudDeployCli, runCloudDeploymentsCli, runCloudUndeployCli, type CloudDeployArgs } from './cli/cloud-deploy.js';
+import { runCloudRollbackCli, runCloudVersionsCli } from './cli/cloud-versions.js';
 import { parseCloudScheduleArgs, runCloudScheduleCli, runCloudSchedulesCli, runCloudUnscheduleCli, type CloudScheduleArgs } from './cli/cloud-schedule.js';
 import { isAuthoredFlowPath } from './direct-input.js';
 import { parseDeployArgs, runDeploy, type DeployArgs } from './cli/deploy.js';
@@ -97,6 +98,8 @@ export type ParsedArgs =
   | CloudDeployArgs
   | { command: 'deployments'; json: boolean }
   | { command: 'undeploy'; agentId: string; json: boolean }
+  | { command: 'versions'; flow: string; json: boolean }
+  | { command: 'rollback'; flow: string; version: string; json: boolean }
   | CloudScheduleArgs
   | { command: 'schedules'; json: boolean }
   | { command: 'unschedule'; scheduleId: string; json: boolean }
@@ -123,7 +126,10 @@ const USAGE = [
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
   'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--plugin <ref>] [--no-connect] [--json]',
+  'flows deploy <flow.ts> --flow <name|listener-id> [--plugin <ref>] [--no-connect] [--json]',
   'flows deployments [--json]',
+  'flows versions [--json] <name|listener-id>',
+  'flows rollback [--json] <name|listener-id> <version>',
   'flows undeploy [--json] <deployment-id>',
   'flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>] [--tz <IANA>] [--input <inline-json-or-file>] [--name <name>] [--no-connect] [--json]',
   'flows schedules [--json]',
@@ -244,6 +250,8 @@ export async function runCli(
   if (parsed.command === 'cloud-deploy') return runCloudDeployCli(parsed, io);
   if (parsed.command === 'deployments') return runCloudDeploymentsCli(parsed, io);
   if (parsed.command === 'undeploy') return runCloudUndeployCli(parsed, io);
+  if (parsed.command === 'versions') return runCloudVersionsCli(parsed, io);
+  if (parsed.command === 'rollback') return runCloudRollbackCli(parsed, io);
   if (parsed.command === 'schedule') return runCloudScheduleCli(parsed, io);
   if (parsed.command === 'schedules') return runCloudSchedulesCli(parsed, io);
   if (parsed.command === 'unschedule') return runCloudUnscheduleCli(parsed, io);
@@ -631,6 +639,13 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     if (json > 1 || rest.length !== 1 || rest[0]!.startsWith('-')) return undefined;
     return { command: 'undeploy', agentId: rest[0]!, json: json === 1 };
   }
+  if (command === 'versions' || command === 'rollback') {
+    const rest = args.slice(1).filter(a => a !== '--json');
+    const json = args.length - 1 - rest.length;
+    if (json > 1 || rest.some(a => a.startsWith('-'))) return undefined;
+    if (command === 'versions') return rest.length === 1 ? { command, flow: rest[0]!, json: json === 1 } : undefined;
+    return rest.length === 2 ? { command, flow: rest[0]!, version: rest[1]!, json: json === 1 } : undefined;
+  }
   if (command === 'deployments') {
     const rest = args.slice(1);
     if (rest.length > 1 || (rest.length === 1 && rest[0] !== '--json')) return undefined;

package/src/cloud-deploy.ts

@@ -11,6 +11,7 @@ import {
 } from './flow-requirements.js';
 import { readProjectConfig } from './cli/check.js';
 import { assertNoUseDependencies, collectExtensionSubmissions } from './flow-extension-submit.js';
+import { parseVersionChange, type CloudFlowVersionChange } from './cloud-versions-wire.js';
 
 /**
  * Hosted listener deployment: the CLI form of the agentrelay.com onboarding's
@@ -104,6 +105,8 @@ export interface CloudDeployment {
   requirements: FlowRequirements;
   /** Integrations connected through the prompt during this deploy. */
   connected: string[];
+  /** The listener's active version after this deploy; absent from a Cloud without versions. */
+  version?: CloudFlowVersionChange;
 }
 
 export function parseRepository(value: string): { owner: string; name: string } {
@@ -165,9 +168,18 @@ export function parseTriggerSource(value: string): FlowTriggerSource {
   return { provider: provider as FlowTriggerProvider, settings };
 }
 
-export async function deployToCloud(
-  input: DeployToCloudInput, options: CloudConnectionOptions = {},
-): Promise<CloudDeployment> {
+/** One authored source, read and loaded the way every hosted deploy sends it. */
+export interface DeploySource {
+  bytes: Buffer;
+  source: string;
+  definition: ReturnType<Awaited<ReturnType<typeof loadAuthoredFlow>>['getDefinition']>;
+  extensions: Awaited<ReturnType<typeof collectExtensionSubmissions>>;
+  projectCli: string | undefined;
+}
+
+export async function loadDeploySource(
+  input: { path: string; plugins?: readonly string[] },
+): Promise<DeploySource> {
   if (!/\.flow\.ts$/iu.test(input.path)) {
     throw new CloudFlowError('unsupported_source', 'flows deploy takes one authored .flow.ts source.');
   }
@@ -204,6 +216,13 @@ export async function deployToCloud(
   } catch {
     projectCli = undefined;
   }
+  return { bytes, source, definition, extensions, projectCli };
+}
+
+export async function deployToCloud(
+  input: DeployToCloudInput, options: CloudConnectionOptions = {},
+): Promise<CloudDeployment> {
+  const { bytes, source, definition, extensions, projectCli } = await loadDeploySource(input);
   if (input.sources.length === 0 || input.sources.length > 10) {
     throw new CloudFlowError('invalid_input', 'Give between one and ten --on trigger sources.');
   }
@@ -274,11 +293,13 @@ export async function deployToCloud(
   if (!isCloudRecord(result) || typeof result.agentId !== 'string' || typeof result.status !== 'string') {
     throw new CloudFlowError('invalid_response', 'Cloud did not return a deployment.');
   }
+  const version = parseVersionChange(result.version);
   return {
     agentId: result.agentId, name, status: result.status,
     repository: input.repository, sources,
     sourceSha256: createHash('sha256').update(bytes).digest('hex'),
     requirements, connected,
+    ...(version === undefined ? {} : { version }),
   };
 }
 

package/src/cloud-versions-wire.ts

@@ -0,0 +1,58 @@
+import { isCloudRecord } from './cloud-http.js';
+
+/**
+ * What a Cloud write did to a listener's active version (cloud#4115).
+ * `reactivated`: the bytes match an earlier version, so the pointer moved to
+ * it without a new row, and `version` can be LOWER than `previousVersion`.
+ */
+export interface CloudFlowVersionChange {
+  version: number;
+  previousVersion: number | null;
+  change: 'created' | 'reactivated' | 'unchanged';
+}
+
+export interface CloudFlowVersion {
+  version: number;
+  sourceSha256: string;
+  origin: string;
+  createdAt: string;
+}
+
+const CHANGES = ['created', 'reactivated', 'unchanged'] as const;
+
+function isVersionNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1;
+}
+
+/** Undefined for a Cloud that predates versions or a malformed field. */
+export function parseVersionChange(value: unknown): CloudFlowVersionChange | undefined {
+  if (!isCloudRecord(value) || !isVersionNumber(value.version)
+    || !(value.previousVersion === null || isVersionNumber(value.previousVersion))
+    || !(CHANGES as readonly unknown[]).includes(value.change)) return undefined;
+  return {
+    version: value.version,
+    previousVersion: value.previousVersion as number | null,
+    change: value.change as CloudFlowVersionChange['change'],
+  };
+}
+
+export function parseVersion(value: unknown): CloudFlowVersion | undefined {
+  if (!isCloudRecord(value) || !isVersionNumber(value.version) || typeof value.sourceSha256 !== 'string'
+    || typeof value.origin !== 'string' || typeof value.createdAt !== 'string') return undefined;
+  return { version: value.version, sourceSha256: value.sourceSha256, origin: value.origin, createdAt: value.createdAt };
+}
+
+/**
+ * `version 4 (was 3)`; a rollback by content says the number went down, so
+ * nobody reads v2-after-v3 as a failed deploy.
+ */
+export function describeVersionChange(change: CloudFlowVersionChange): string {
+  if (change.change === 'unchanged') return `version ${change.version} (unchanged)`;
+  const was = change.previousVersion === null ? '' : ` (was ${change.previousVersion}`;
+  if (change.change === 'reactivated') {
+    const down = change.previousVersion !== null && change.version < change.previousVersion
+      ? '; active version went down' : '';
+    return `re-activated version ${change.version}${was}${down}${was ? ')' : ''}`;
+  }
+  return `version ${change.version}${was}${was ? ')' : ''}`;
+}

package/src/cloud-versions.ts

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { ensureIntegrationsConnected, type ConnectPrompt } from './cloud-connect.js';
+import {
+  CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions,
+} from './cloud-http.js';
+import {
+  FLOW_AGENT_HARNESSES, listCloudDeployments, loadDeploySource, type FlowTriggerSource,
+} from './cloud-deploy.js';
+import {
+  parseVersion, parseVersionChange, type CloudFlowVersion, type CloudFlowVersionChange,
+} from './cloud-versions-wire.js';
+import { flowRequirements, mergeFlowExtensionRequirements, type FlowRequirements } from './flow-requirements.js';
+
+/**
+ * Versions of a hosted listener (AgentWorkforce/cloud#4115). A deployed
+ * flow's source is immutable: `flows deploy <file> --flow <name-or-id>` makes
+ * the next version and moves the listener's pointer to it, leaving the
+ * listener's repository, triggers, approver, agents and run budget untouched;
+ * `flows rollback` moves the pointer to any recorded version.
+ */
+
+const LISTENER_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+export interface CloudListener {
+  agentId: string;
+  name: string;
+  status: string;
+  repository: { owner: string; name: string; host?: 'gitlab' };
+  sources: FlowTriggerSource[];
+  activeVersion: CloudFlowVersion | null;
+  versions: CloudFlowVersion[];
+}
+
+/** A listener id as given, else the one deployment in the workspace with that name. */
+export async function resolveCloudFlow(flow: string, options: CloudConnectionOptions = {}): Promise<string> {
+  const wanted = flow.trim();
+  if (!wanted) throw new CloudFlowError('invalid_input', '--flow needs a flow name or listener id.');
+  if (LISTENER_UUID.test(wanted)) return wanted.toLowerCase();
+  const deployments = await listCloudDeployments(options);
+  // Any listener id the workspace lists, before names: ids are not all uuids.
+  const byId = deployments.find(deployment => deployment.agentId === wanted);
+  if (byId) return byId.agentId;
+  const matches = deployments.filter(deployment => deployment.name.toLowerCase() === wanted.toLowerCase());
+  if (matches.length === 1) return matches[0]!.agentId;
+  if (matches.length === 0) {
+    throw new CloudFlowError('invalid_input', `No flow named "${wanted}" in this workspace; list them with: flows deployments`);
+  }
+  throw new CloudFlowError('invalid_input',
+    `More than one flow is named "${wanted}" (${matches.map(match => match.agentId).join(', ')}); pass the listener id.`);
+}
+
+export async function getCloudListener(agentId: string, options: CloudConnectionOptions = {}): Promise<CloudListener> {
+  const payload = await cloudRequest(`/api/v1/flows/listeners/${encodeURIComponent(agentId)}`, options);
+  const listener = isCloudRecord(payload) && isCloudRecord(payload.listener) ? payload.listener : undefined;
+  if (!listener || typeof listener.name !== 'string' || typeof listener.status !== 'string'
+    || !isCloudRecord(listener.repository) || typeof listener.repository.owner !== 'string'
+    || typeof listener.repository.name !== 'string' || !Array.isArray(listener.sources)) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return the flow listener.');
+  }
+  const versions = isCloudRecord(payload) && Array.isArray(payload.versions)
+    ? payload.versions.flatMap(entry => parseVersion(entry) ?? []) : [];
+  return {
+    agentId,
+    name: listener.name,
+    status: listener.status,
+    repository: {
+      owner: listener.repository.owner, name: listener.repository.name,
+      ...(listener.repository.host === 'gitlab' ? { host: 'gitlab' as const } : {}),
+    },
+    sources: listener.sources.flatMap((entry): FlowTriggerSource[] => isCloudRecord(entry) && typeof entry.provider === 'string'
+      ? [{ provider: entry.provider as FlowTriggerSource['provider'],
+          settings: Object.fromEntries(Object.entries(isCloudRecord(entry.settings) ? entry.settings : {})
+            .flatMap(([key, value]) => typeof value === 'string' ? [[key, value]] : typeof value === 'boolean' ? [[key, String(value)]] : [])) }]
+      : []),
+    activeVersion: isCloudRecord(payload) ? parseVersion(payload.activeVersion) ?? null : null,
+    versions,
+  };
+}
+
+export interface DeployVersionInput {
+  path: string;
+  /** The flow's deployed name or its listener id. */
+  flow: string;
+  plugins?: readonly string[];
+  connect?: ConnectPrompt;
+  checkConnections?: boolean;
+}
+
+export interface CloudVersionDeployment {
+  agentId: string;
+  name: string;
+  status: string;
+  sourceSha256: string;
+  requirements: FlowRequirements;
+  connected: string[];
+  version: CloudFlowVersionChange;
+}
+
+/** `POST /api/v1/flows/listeners/<id>/versions`: the source alone becomes the next version. */
+export async function deployVersionToCloud(
+  input: DeployVersionInput, options: CloudConnectionOptions = {},
+): Promise<CloudVersionDeployment> {
+  const { bytes, source, definition, extensions, projectCli } = await loadDeploySource(input);
+  const agentId = await resolveCloudFlow(input.flow, options);
+  const listener = await getCloudListener(agentId, options);
+  options.signal?.throwIfAborted();
+  // Requirements derive from the source, read against the listener's own
+  // repository and triggers, exactly as the create form reads its flags.
+  const requirements = mergeFlowExtensionRequirements(
+    flowRequirements(definition, {
+      sources: listener.sources,
+      // A GitHub repository means every run needs GitHub; a GitLab project does not.
+      ...(listener.repository.host === 'gitlab' ? {} : { repository: listener.repository }),
+      ...(projectCli === undefined ? {} : { projectCli }),
+    }),
+    extensions.map(extension => ({ name: extension.name, permissions: extension.manifest.permissions })),
+  );
+  // As on create: a harness Cloud cannot run is refused here, not deployed.
+  // There is no --agents override beside --flow; the listener's agents stay.
+  const unsupported = requirements.harnessUses
+    .filter(use => !(FLOW_AGENT_HARNESSES as readonly string[]).includes(use.harness));
+  if (unsupported.length > 0) {
+    throw new CloudFlowError('unsupported_source',
+      `This flow declares ${unsupported.map(use => `${use.harness} (${use.detail})`).join(', ')}, which Cloud deployments cannot run yet; `
+      + `Cloud runs ${FLOW_AGENT_HARNESSES.join(' and ')}. Change the declaration before deploying a new version.`);
+  }
+  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.');
+  }
+  // A draft activates nothing, so Cloud checks nothing; match it here.
+  const connected = listener.status !== 'listening' || 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/listeners/${encodeURIComponent(agentId)}/versions`, options, {
+    method: 'POST', detail: true, body: JSON.stringify({
+      workspaceId: workspace.id,
+      source,
+      requirements: {
+        integrations: requirements.integrations.map(integration => integration.provider),
+        harnesses: requirements.harnesses,
+        mcp: requirements.mcp,
+      },
+      ...(extensions.length === 0 ? {} : { extensions }),
+    }),
+  });
+  const version = isCloudRecord(result) ? parseVersionChange(result.version) : undefined;
+  if (!isCloudRecord(result) || typeof result.status !== 'string' || version === undefined) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return the new flow version.');
+  }
+  return {
+    agentId, name: listener.name, status: result.status,
+    sourceSha256: createHash('sha256').update(bytes).digest('hex'),
+    requirements, connected, version,
+  };
+}
+
+/** `POST /api/v1/flows/listeners/<id>/versions/<n>/activate`: history is kept; only the pointer moves. */
+export async function activateCloudFlowVersion(
+  flow: string, version: number, options: CloudConnectionOptions = {},
+): Promise<{ agentId: string; status: string; version: CloudFlowVersionChange }> {
+  if (!Number.isSafeInteger(version) || version < 1) {
+    throw new CloudFlowError('invalid_input', `A version is a positive whole number, got "${version}".`);
+  }
+  const agentId = await resolveCloudFlow(flow, options);
+  const result = await cloudFetch(
+    `/api/v1/flows/listeners/${encodeURIComponent(agentId)}/versions/${version}/activate`,
+    options, { method: 'POST', detail: true },
+  );
+  const change = isCloudRecord(result) ? parseVersionChange(result.version) : undefined;
+  if (!isCloudRecord(result) || typeof result.status !== 'string' || change === undefined) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not confirm the active version.');
+  }
+  return { agentId, status: result.status, version: change };
+}