@relayflows/sdk 2.0.14 → 2.0.16

package/src/cli/cloud-deploy.ts

@@ -0,0 +1,157 @@
+import { CloudFlowError } from '../cloud-http.js';
+import {
+  deployToCloud, listCloudDeployments, parseAgentHarnesses, parseRepository, parseTriggerSource, undeployFromCloud,
+  type FlowTriggerSource,
+} from '../cloud-deploy.js';
+import type { CliIo } from '../cli.js';
+
+export interface CloudDeployArgs {
+  command: 'cloud-deploy';
+  value: string;
+  repo: string;
+  on: string[];
+  approver: string | undefined;
+  name: string | undefined;
+  agents: string | undefined;
+  draft: boolean;
+  json: boolean;
+}
+
+/**
+ * `flows deploy <flow.ts> --repo <owner/name> --on <provider>[:k=v,…] [--on …]
+ *   --approver <handle> [--name <n>] [--json]`
+ *
+ * Parsed here rather than in `parseDeployArgs` because the two `deploy` forms
+ * share nothing but the word: the digest form copies a sealed bundle into a
+ * file bucket, this one creates a hosted listener. The positional decides.
+ */
+export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs | undefined {
+  let value: string | undefined;
+  let repo: string | undefined;
+  let approver: string | undefined;
+  let name: string | undefined;
+  let agents: string | undefined;
+  let draft = false;
+  let json = false;
+  const on: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--json') {
+      if (json) return undefined;
+      json = true;
+      continue;
+    }
+    if (arg === '--draft') {
+      if (draft) return undefined;
+      draft = true;
+      continue;
+    }
+    if (arg === '--agents') {
+      const next = args[i + 1];
+      if (agents !== undefined || next === undefined || next.startsWith('-')) return undefined;
+      agents = next;
+      i += 1;
+      continue;
+    }
+    if (arg === '--repo' || arg === '--approver' || arg === '--name' || arg === '--on') {
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('-')) return undefined;
+      i += 1;
+      if (arg === '--on') { on.push(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;
+      name = next;
+      continue;
+    }
+    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, json };
+}
+
+function describeSource(source: FlowTriggerSource): string {
+  const settings = Object.entries(source.settings).map(([k, v]) => `${k}=${v}`).join(' ');
+  return settings ? `${source.provider} ${settings}` : source.provider;
+}
+
+export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promise<0 | 1 | 2> {
+  try {
+    if (args.approver === undefined) {
+      throw new CloudFlowError('invalid_input',
+        '--approver <handle> is required: every launched run receives it as input.approver for f.human.');
+    }
+    const deployment = await deployToCloud({
+      path: args.value,
+      repository: parseRepository(args.repo),
+      sources: args.on.map(parseTriggerSource),
+      approver: args.approver,
+      draft: args.draft,
+      ...(args.name === undefined ? {} : { name: args.name }),
+      ...(args.agents === undefined ? {} : { agents: parseAgentHarnesses(args.agents) }),
+    });
+    if (args.json) {
+      io.stdout(JSON.stringify({ ok: true, ...deployment }));
+      return 0;
+    }
+    io.stdout(`${deployment.status === 'draft' ? 'SAVED' : 'DEPLOYED'} ${deployment.agentId} ${deployment.status}`);
+    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)}`);
+    io.stdout(deployment.status === 'draft'
+      ? 'Saved without activating; activate it from the Cloud dashboard, or redeploy without --draft.'
+      : 'Each matching ticket launches a run of this source in a fresh branch; list with: flows deployments');
+    return 0;
+  } catch (error) {
+    return reportCloudFailure(error, args.json, io);
+  }
+}
+
+export async function runCloudDeploymentsCli({ json }: { json: boolean }, io: CliIo): Promise<0 | 1 | 2> {
+  try {
+    const deployments = await listCloudDeployments();
+    if (json) {
+      io.stdout(JSON.stringify({ ok: true, deployments }));
+      return 0;
+    }
+    if (deployments.length === 0) {
+      io.stdout('No flow deployments in this workspace.');
+      return 0;
+    }
+    for (const d of deployments) {
+      const repo = d.repository ? ` ${d.repository.owner}/${d.repository.name}` : '';
+      io.stdout(`${d.agentId} ${d.status} ${JSON.stringify(d.name)}${repo}`);
+      for (const source of d.sources) io.stdout(`  on: ${describeSource(source)}`);
+    }
+    return 0;
+  } catch (error) {
+    return reportCloudFailure(error, json, io);
+  }
+}
+
+export async function runCloudUndeployCli({ agentId, json }: { agentId: string; json: boolean }, io: CliIo): Promise<0 | 1 | 2> {
+  try {
+    await undeployFromCloud(agentId);
+    io.stdout(json ? JSON.stringify({ ok: true, agentId, status: 'deleted' }) : `UNDEPLOYED ${agentId}`);
+    return 0;
+  } catch (error) {
+    return reportCloudFailure(error, json, io);
+  }
+}
+
+function reportCloudFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
+  const code = error instanceof CloudFlowError ? error.code : 'cloud_deploy_failed';
+  let message = error instanceof Error ? error.message : 'Cloud deploy failed.';
+  // The deploy routes take a browser session or a `cli:auth` token. A
+  // deployment (CI) token gets 403 `session_required`; say what fixes it.
+  if (error instanceof CloudFlowError && error.status === 403) {
+    message += ' Deploying needs an interactive `cli:auth` credential: run `agent-relay cloud login` '
+      + '(a deployment token can run flows but not deploy them).';
+  }
+  if (json) io.stdout(JSON.stringify({ ok: false, code, message }));
+  else io.stderr(`${code}: ${message}`);
+  return error instanceof CloudFlowError
+    && (['configuration', 'unsupported_source', 'invalid_input'].includes(error.code) || error.status === 403 || error.status === 401)
+    ? 2 : 1;
+}

package/src/cli/cloud-run.ts

@@ -1,10 +1,14 @@
 import { CloudFlowError } from '../cloud-http.js';
-import { runInCloud, waitForCloudFlowRun } from '../cloud-run.js';
+import { runInCloud, waitForCloudFlowRun, type RunInCloudOptions } from '../cloud-run.js';
+import { DirectInputError, isAuthoredFlowPath, parseDirectInput } from '../direct-input.js';
+import { snapshotJsonValue } from '../json-value.js';
 import type { CliIo } from '../cli.js';
 
 /** Presentation only: the central CLI parser owns argv; the SDK owns the lifecycle. */
 export async function runCloudCli(
-  { value: path, json, wait }: { value: string; json: boolean; wait: boolean },
+  { value: path, json, wait, input, syncCode }: {
+    value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean;
+  },
   io: CliIo,
 ): Promise<0 | 1 | 2> {
   const controller = new AbortController();
@@ -12,12 +16,36 @@ export async function runCloudCli(
   process.once('SIGINT', abort);
   process.once('SIGTERM', abort);
   let runId: string | undefined;
+  // Flips at the run submission. An interruption before it — during prepare,
+  // packing or upload — admitted nothing and is safe to retry; only an
+  // interrupted submission has unknown admission.
+  let submitting = false;
   try {
-    const receipt = await runInCloud({ path }, { signal: controller.signal });
+    const options: RunInCloudOptions = { signal: controller.signal, onSubmit: () => { submitting = true; } };
+    if (isAuthoredFlowPath(path)) {
+      // Same parse as a local direct run, so a file-or-inline argument means
+      // the same thing on both sides of `--cloud`.
+      try {
+        options.input = snapshotJsonValue(parseDirectInput(input), 'Cloud authored input');
+      } catch (error) {
+        if (error instanceof DirectInputError) throw new CloudFlowError('invalid_input', error.message);
+        throw error;
+      }
+    }
+    // The tree is the invoking directory, as with v1: the flow path is where
+    // the body lives, not the boundary of what the run may read.
+    if (syncCode) options.syncCode = { root: process.cwd() };
+    const receipt = await runInCloud({ path }, options);
     runId = receipt.runId;
     if (!json) {
       io.stdout(`ACCEPTED ${receipt.runId} (${receipt.status})`);
       io.stdout(receipt.apiUrl);
+      if (receipt.synced) {
+        io.stdout(`SYNCED ${receipt.synced.files} files (${receipt.synced.bytes} bytes); pull changes with: flows sync ${receipt.runId}`);
+        for (const link of receipt.synced.skippedLinks) {
+          io.stderr(`WARNING [sync_link_skipped] ${link} points outside the synced tree and was not uploaded`);
+        }
+      }
     }
     if (!wait) {
       if (json) io.stdout(JSON.stringify({ ok: true, ...receipt }));
@@ -29,16 +57,19 @@ export async function runCloudCli(
     else io.stdout(`${run.status.toUpperCase()} ${run.runId} completionReason: ${'completionReason' in run ? run.completionReason : 'unavailable'}`);
     return ok ? 0 : 1;
   } catch (error) {
-    const code = controller.signal.aborted ? (runId ? 'observation_aborted' : 'admission_unknown')
+    const code = controller.signal.aborted
+      ? runId ? 'observation_aborted' : submitting ? 'admission_unknown' : 'submission_aborted'
       : error instanceof CloudFlowError ? error.code : 'cloud_run_failed';
     const message = controller.signal.aborted
       ? runId ? 'Stopped observing; the hosted run has not been cancelled.'
-        : 'Submission interrupted before a receipt was received. Admission is unknown; Cloud may have started the run. Do not resubmit blindly.'
+        : submitting
+          ? 'Submission interrupted before a receipt was received. Admission is unknown; Cloud may have started the run. Do not resubmit blindly.'
+          : 'Interrupted before the run was submitted; nothing was admitted. Safe to run again.'
       : error instanceof Error ? error.message : 'Cloud run failed.';
     if (json) io.stdout(JSON.stringify({ ok: false, code, message, ...(runId ? { runId } : {}) }));
     else io.stderr(`${code}: ${message}${runId ? ` (run ${runId})` : ''}`);
     return error instanceof CloudFlowError
-      && (['configuration', 'unsupported_source', 'invalid_input'].includes(error.code)
+      && (['configuration', 'unsupported_source', 'invalid_input', 'unsupported_storage_backend', 'sync_too_large', 'sync_unsupported'].includes(error.code)
         || (runId === undefined && error.code === 'http_error' && [401, 403].includes(error.status ?? 0))) ? 2 : 1;
   } finally {
     process.off('SIGINT', abort);

package/src/cli/cloud-sync.ts

@@ -0,0 +1,37 @@
+import { CloudFlowError } from '../cloud-http.js';
+import { applyCloudPatch, downloadCloudPatch, patchedPaths } from '../cloud-sync.js';
+import type { CliIo } from '../cli.js';
+
+/**
+ * `flows sync <run-id>`: fetch the diff a hosted run left in its synced tree
+ * and apply it here. The patch is the sandbox's own `git diff` against the
+ * uploaded baseline, so applying it reproduces exactly what the run's steps
+ * wrote — no re-execution, no re-upload.
+ */
+export async function runCloudSyncCli(
+  { runId, json, root }: { runId: string; json: boolean; root: string },
+  io: CliIo,
+): Promise<0 | 1 | 2> {
+  try {
+    const { patch, hasChanges } = await downloadCloudPatch(runId, {});
+    if (!hasChanges || !patch.trim()) {
+      if (json) io.stdout(JSON.stringify({ ok: true, runId, hasChanges: false, applied: false }));
+      else io.stdout(`NO CHANGES ${runId}`);
+      return 0;
+    }
+    applyCloudPatch(root, patch);
+    const files = patchedPaths(patch);
+    if (json) io.stdout(JSON.stringify({ ok: true, runId, hasChanges: true, applied: true, files }));
+    else {
+      io.stdout(`APPLIED ${runId}: ${files.length} file${files.length === 1 ? '' : 's'}${files.length ? `\n  ${files.join('\n  ')}` : ''}`);
+      io.stdout('Applied to the working tree, uncommitted: review with git diff before keeping it.');
+    }
+    return 0;
+  } catch (error) {
+    const code = error instanceof CloudFlowError ? error.code : 'cloud_sync_failed';
+    const message = error instanceof Error ? error.message : 'Cloud sync failed.';
+    if (json) io.stdout(JSON.stringify({ ok: false, code, message, runId }));
+    else io.stderr(`${code}: ${message} (run ${runId})`);
+    return error instanceof CloudFlowError && ['configuration', 'sync_unsupported', 'patch_conflict'].includes(error.code) ? 2 : 1;
+  }
+}

package/src/cli/direct-run.ts

@@ -14,6 +14,7 @@ import { JournalClient } from '../journal-client.js';
 import { inputFailureReport } from './check.js';
 import { checkAuthoredTriggers } from './check-triggers.js';
 import {
+  authoredCompletion,
   authoredStepFailure,
   connect,
   emptyReport,
@@ -99,31 +100,7 @@ export async function runDirectFlow(
         `authored flow "${result.name}" completed without a journal step`,
       ));
     }
-    if (result.completionReason === 'needs_human') {
-      return {
-        exitCode: 3,
-        report: {
-          ...base, ok: false, runId: result.rootRunId, socketPath, status: 'parked',
-          completedSteps: result.journalSteps.length,
-          diagnostics: [...base.diagnostics, {
-            severity: 'parked', kind: 'run_parked',
-            message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.`,
-          }],
-        },
-      };
-    }
-    return {
-      exitCode: 0,
-      report: {
-        ...base,
-        ok: true,
-        runId: result.rootRunId,
-        socketPath,
-        status: 'completed',
-        completionReason: result.completionReason,
-        completedSteps: result.journalSteps.length,
-      },
-    };
+    return authoredCompletion('run', base, socketPath, result, result.rootRunId);
   } catch (caught) {
     if (caught instanceof McpPreflightError) return {
       exitCode: 2, report: fromCheckReport('run', caught.report),

package/src/cli/run.ts

@@ -22,6 +22,7 @@ import type {
   RunStatus,
 } from '../protocol.js';
 import type { StepType } from '../spec.js';
+import type { LoweredCompletionReason } from '../authored-flow-executor.js';
 import {
   checkFlow,
   type CheckReport,
@@ -36,7 +37,7 @@ export interface ParkedStep {
 }
 
 export interface RunDiagnostic extends StepFailedDetails {
-  severity: 'refusal' | 'failure' | 'parked' | 'warning';
+  severity: 'refusal' | 'failure' | 'parked' | 'warning' | 'declined';
   kind: RunFailureKind | RunWarningKind | RunCompletionReason;
   message: string;
 }
@@ -191,21 +192,7 @@ export async function resumeFlow(
         lifecycle: options,
       });
       if (result === undefined) throw new Error('authored root disappeared during resume');
-      return {
-        exitCode: result.completionReason === 'needs_human' ? 3 : 0,
-        report: {
-          ...base,
-          ok: result.completionReason === 'success',
-          runId,
-          socketPath,
-          status: result.completionReason === 'needs_human' ? 'parked' : 'completed',
-          ...(result.completionReason === 'success'
-            ? { completionReason: 'success' as const }
-            : { diagnostics: [{ severity: 'parked' as const, kind: 'run_parked' as const,
-              message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.` }] }),
-          completedSteps: result.journalSteps.length,
-        },
-      };
+      return authoredCompletion('resume', base, socketPath, result, runId);
     }
     // resumeHelperEffect subsumes the old resumeSlackEffect: it handles the
     // slack effect resume plus every other provider from N's codegen. The
@@ -309,6 +296,89 @@ export function authoredStepFailure(
   };
 }
 
+/**
+ * An authored body that returned its own terminal verdict, reported as that verdict.
+ *
+ * Shared by `runDirectFlow` and `resumeFlow` for the reason `authoredStepFailure`
+ * is shared: the run and resume paths had already drifted once, and the
+ * `needs_human` report was duplicated verbatim in both files.
+ *
+ * This is NOT `authoredStepFailure`, even though a `step_failed` verdict lands
+ * on the same exit code and report shape. That function describes a step that
+ * ran and failed, and carries the failing step's evidence. Here every step
+ * succeeded and the BODY declared the outcome, so there is no failing step to
+ * name — routing this through the other helper would invent one.
+ */
+export function authoredCompletion(
+  command: RunCommand,
+  base: RunReport,
+  socketPath: string,
+  result: { name: string; completionReason: LoweredCompletionReason; journalSteps: readonly unknown[] },
+  runId: string | undefined,
+): RunExecution {
+  const common: RunReport = {
+    ...fromBase(command, base),
+    ...(runId === undefined ? {} : { runId }),
+    socketPath,
+    completedSteps: result.journalSteps.length,
+  };
+  switch (result.completionReason) {
+    case 'success':
+      return {
+        exitCode: 0,
+        report: { ...common, ok: true, status: 'completed', completionReason: 'success' },
+      };
+    case 'declined':
+      return {
+        exitCode: 0,
+        report: {
+          ...common, ok: true, status: 'completed', completionReason: 'success',
+          diagnostics: [...base.diagnostics, {
+            severity: 'declined', kind: 'run_declined',
+            message: 'Flow deliberately chose not to act on this input.',
+          }],
+        },
+      };
+    case 'needs_human':
+      return {
+        exitCode: 3,
+        report: {
+          ...common, ok: false, status: 'parked',
+          diagnostics: [...base.diagnostics, {
+            severity: 'parked', kind: 'run_parked',
+            message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.`,
+          }],
+        },
+      };
+    case 'step_failed':
+      // A declared run failure. Exit 1, not the parked 3: nothing here is
+      // waiting for a human to recover it, and exit 3 is the local kit's
+      // manual-approval stop. `status: failed` with this `completionReason` is
+      // also the only terminal shape Cloud accepts for a non-success run
+      // (see cloud-run.ts).
+      return {
+        exitCode: 1,
+        report: {
+          ...common, ok: false, status: 'failed', completionReason: 'step_failed',
+          diagnostics: [...base.diagnostics, {
+            severity: 'failure', kind: 'step_failed',
+            message: `Flow "${result.name}" declared done("step_failed"): its own checks did not pass. `
+              + 'No step failed, so there is no step-level evidence to inspect; the journal holds '
+              + 'every step the flow ran before it decided.',
+          }],
+        },
+      };
+  }
+  // Exhaustive by construction. A new lowered completion has to choose its
+  // own exit code and wording here; it must not inherit "its own checks did not
+  // pass", which would state something the body never declared. Letting an
+  // unlisted reason fall through to the failure branch is how a reporting-side
+  // copy of the same vocabulary drifts from the executor's — the defect this
+  // change exists to close — so it is a compile error, not a wrong report.
+  const unreachable: never = result.completionReason;
+  throw new Error(`unreachable authored completion: ${String(unreachable)}`);
+}
+
 /**
  * Get a live daemon, then open the socket to it.
  *

package/src/cli.ts

@@ -24,6 +24,8 @@ import { runDirectFlow } from './cli/direct-run.js';
 import { parseReplayArgs, replayJournal, type ReplayArgs } from './cli/replay.js';
 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 { isAuthoredFlowPath } from './direct-input.js';
 import { parseDeployArgs, runDeploy, type DeployArgs } from './cli/deploy.js';
 import { parseDigestReference } from './bundle-transport.js';
@@ -51,7 +53,11 @@ type ParsedArgs =
   | BuildArgs
   | DeployArgs
   | { command: 'serve-webhook'; dataDir: string; port: number; admitted?: readonly string[] }
-  | { command: 'cloud-run'; value: string; json: boolean; wait: boolean }
+  | { command: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean }
+  | { command: 'sync'; runId: string; json: boolean; root: string }
+  | CloudDeployArgs
+  | { command: 'deployments'; json: boolean }
+  | { command: 'undeploy'; agentId: string; json: boolean }
   | { command: 'check'; json: boolean; watch: boolean; value: string }
   | { command: 'run'; bucket: string | undefined; reuseFromRunId: string | undefined; localAgent: boolean; dataDir: string; input: string | undefined; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
   | { command: 'resume'; localAgent: boolean; dataDir: string; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
@@ -66,12 +72,17 @@ const USAGE = [
   'flows add <helper-name|@flows/helper-name>',
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
+  'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--json]',
+  'flows deployments [--json]',
+  'flows undeploy [--json] <deployment-id>',
   'flows deploy <flow>@sha256:<digest> --to <file-bucket-uri>',
   'flows run <flow>@sha256:<digest> [--bucket <file-bucket-uri>] [--data-dir <dir>] [--json]',
   'flows check [--watch] [--json] <flow.ts|flow.yaml|spec.json>',
   'flows serve-webhook --data-dir <dir> --port <p> [--allow <name>[,<name>]]',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] [--reuse-from <run-id>] <flow.yaml|spec.json>',
-  'flows run --cloud [--json] [--wait] <flow.yaml|spec.json>',
+  'flows run --cloud [--json] [--wait] [--sync-code] <flow.yaml|spec.json>',
+  'flows run --cloud [--json] [--wait] [--sync-code] <flow.ts> --input <inline-json-or-file>',
+  'flows sync [--json] [--dir <path>] <run-id>',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>',
   'flows tick start --schedule-id <id> --interval-ms <ms> [--epoch-ms <ms>] [--max-catch-up <n>] [--poll-interval-ms <ms>] [--data-dir <dir>] <spec.json>',
   'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <run-id>',
@@ -116,6 +127,10 @@ export async function runCli(
   if (parsed.command === 'serve-webhook') return runServeWebhook(parsed, io);
 
   if (parsed.command === 'cloud-run') return runCloudCli(parsed, io);
+  if (parsed.command === 'sync') return runCloudSyncCli(parsed, io);
+  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 === 'replay') return replayJournal(parsed, io);
   if (parsed.command === 'build') return runBuild(parsed, io);
   if (parsed.command === 'deploy') return runDeploy(parsed, io);
@@ -419,17 +434,35 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   if (command === 'add') return args.length === 2 ? { command: 'add', value: args[1]! } : undefined;
   if (command === 'replay') return parseReplayArgs(args.slice(1));
   if (command === 'build') return parseBuildArgs(args.slice(1));
-  if (command === 'deploy') return parseDeployArgs(args.slice(1));
+  if (command === 'deploy') {
+    // The positional decides the form: an authored source deploys a hosted
+    // listener; a digest reference copies a sealed bundle into a file bucket.
+    const source = args.slice(1).find(a => !a.startsWith('-') && isAuthoredFlowPath(a));
+    return source !== undefined ? parseCloudDeployArgs(args.slice(1)) : parseDeployArgs(args.slice(1));
+  }
+  if (command === 'undeploy') {
+    const rest = args.slice(1).filter(a => a !== '--json');
+    const json = args.length - 1 - rest.length;
+    if (json > 1 || rest.length !== 1 || rest[0]!.startsWith('-')) return undefined;
+    return { command: 'undeploy', agentId: rest[0]!, json: json === 1 };
+  }
+  if (command === 'deployments') {
+    const rest = args.slice(1);
+    if (rest.length > 1 || (rest.length === 1 && rest[0] !== '--json')) return undefined;
+    return { command: 'deployments', json: rest.length === 1 };
+  }
   if (command === 'serve-webhook') return parseWebhookArgs(args.slice(1));
   if (command === 'hn-monitor') return parseHnMonitorArgs(args.slice(1));
   if (command === 'tick') return parseTickArgs(args.slice(1));
   if (command === 'observer') return parseObserverArgs(args.slice(1));
+  if (command === 'sync') return parseSyncArgs(args.slice(1));
   if (command !== 'check' && command !== 'run' && command !== 'resume') return undefined;
 
   let json = false;
   let watch = false;
   let cloud = false;
   let wait = false;
+  let syncCode = false;
   let localAgent = false;
   let allowHumanInfluenced = false;
   let dataDir = DEFAULT_DATA_DIR;
@@ -443,10 +476,11 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   const positionals: string[] = [];
   for (let index = 1; index < args.length; index += 1) {
     const argument = args[index]!;
-    if (argument === '--cloud' || argument === '--wait') {
-      if (command !== 'run' || (argument === '--cloud' ? cloud : wait)) return undefined;
+    if (argument === '--cloud' || argument === '--wait' || argument === '--sync-code') {
+      if (command !== 'run' || (argument === '--cloud' ? cloud : argument === '--wait' ? wait : syncCode)) return undefined;
       if (argument === '--cloud') cloud = true;
-      else wait = true;
+      else if (argument === '--wait') wait = true;
+      else syncCode = true;
       continue;
     }
     if (argument === '--allow-human-influenced') {
@@ -520,13 +554,15 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   if (bucket !== undefined && (cloud || !parseDigestReference(positionals[0]!))) return undefined;
   if (cloud) {
     // `--cloud` submits the spec to Cloud, so every flag that only describes a
-    // local run -- an inline input, a data dir, a suppressed daemon, a local
-    // agent, a local observer-link opt-out -- describes nothing there and is
-    // refused rather than ignored.
-    if (allowHumanInfluenced || sawInput || sawDataDir || !spawn || localAgent || noObserverLink || reuseFromRunId !== undefined) return undefined;
-    return { command: 'cloud-run', value: positionals[0]!, json, wait };
+    // local run -- a data dir, a suppressed daemon, a local agent, a local
+    // observer-link opt-out -- describes nothing there and is refused rather
+    // than ignored. `--input` is the authored body's argument and travels with
+    // the source, so it is accepted exactly where a local run accepts it.
+    if (allowHumanInfluenced || sawDataDir || !spawn || localAgent || noObserverLink || reuseFromRunId !== undefined) return undefined;
+    if (sawInput && !isAuthoredFlowPath(positionals[0]!)) return undefined;
+    return { command: 'cloud-run', value: positionals[0]!, json, wait, input, syncCode };
   }
-  if (wait) return undefined;
+  if (wait || syncCode) return undefined;
   if (reuseFromRunId !== undefined && isAuthoredFlowPath(positionals[0]!)) return undefined;
 
   if (command === 'run' && input !== undefined && !isAuthoredFlowPath(positionals[0]!)) return undefined;
@@ -579,6 +615,32 @@ function parseHnMonitorArgs(rest: readonly string[]): ParsedArgs | undefined {
  * directory at all -- the mint is a pure Relaycast API round-trip. No
  * positional argument, no other flags.
  */
+/** `flows sync [--json] [--dir <path>] <run-id>`: apply a hosted run's patch to a local tree. */
+function parseSyncArgs(args: readonly string[]): ParsedArgs | undefined {
+  let json = false;
+  let root: string | undefined;
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]!;
+    if (argument === '--json') {
+      if (json) return undefined;
+      json = true;
+      continue;
+    }
+    if (argument === '--dir') {
+      const value = args[index + 1];
+      if (root !== undefined || value === undefined || value.startsWith('-')) return undefined;
+      root = value;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith('-')) return undefined;
+    positionals.push(argument);
+  }
+  if (positionals.length !== 1) return undefined;
+  return { command: 'sync', runId: positionals[0]!, json, root: root ?? '.' };
+}
+
 function parseObserverArgs(rest: readonly string[]): ParsedArgs | undefined {
   let dataDir = DEFAULT_DATA_DIR;
   let sawDataDir = false;
@@ -750,6 +812,7 @@ function diagnosticLabel(severity: string): string {
     case 'warning': return 'WARNING';
     case 'failure': return 'FAILED';
     case 'parked': return 'PARKED';
+    case 'declined': return 'DECLINED';
     default: return 'REFUSED';
   }
 }