@relayflows/sdk 2.0.14 → 2.0.16

package/src/cloud-deploy.ts

@@ -0,0 +1,236 @@
+import { randomBytes, createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { loadAuthoredFlow } from './authored-flow-loader.js';
+import {
+  CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions,
+} from './cloud-http.js';
+
+/**
+ * Hosted listener deployment: the CLI form of the agentrelay.com onboarding's
+ * deploy wizard. `POST /api/v1/flows/deploy` stores one self-contained
+ * authored source and creates a proactive listener whose watch rules match
+ * the chosen ticket sources on the workspace's relayfile projections. There
+ * is no webhook to register: the GitHub App installation (or Slack/Linear/
+ * Jira/Shortcut connection) is the ingress, and each matching ticket launches
+ * a run of the stored source with `{ approver, issue, event }` as its input,
+ * inside a fresh branch of the deployment's repository.
+ */
+
+export const FLOW_TRIGGER_PROVIDERS = ['github', 'linear', 'jira', 'shortcut', 'slack'] as const;
+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'],
+  slack: ['channel', 'contains'],
+  linear: ['team', 'contains'],
+  jira: ['project', 'contains'],
+  shortcut: ['workspace', 'contains'],
+};
+const MAX_SOURCE_BYTES = 256_000;
+const MAX_SETTING_LENGTH = 500;
+const REPO_OWNER = /^[A-Za-z0-9-]{1,39}$/u;
+const REPO_NAME = /^[A-Za-z0-9_.-]{1,100}$/u;
+
+export interface FlowTriggerSource {
+  provider: FlowTriggerProvider;
+  settings: Record<string, string>;
+}
+
+export interface DeployToCloudInput {
+  path: string;
+  repository: { owner: string; name: string };
+  sources: FlowTriggerSource[];
+  /** The `f.human` approver handle every launched run receives as `input.approver`. */
+  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"]`. */
+  agents?: FlowAgentHarness[];
+  /** Save without activating: no connection checks, no listener until activated. */
+  draft?: boolean;
+}
+
+export const FLOW_AGENT_HARNESSES = ['claude', 'codex'] as const;
+export type FlowAgentHarness = (typeof FLOW_AGENT_HARNESSES)[number];
+
+export function parseAgentHarnesses(value: string): FlowAgentHarness[] {
+  const agents = value.split(',').map(a => a.trim()).filter(Boolean);
+  if (agents.length === 0 || agents.length > 2 || new Set(agents).size !== agents.length
+    || !agents.every(a => (FLOW_AGENT_HARNESSES as readonly string[]).includes(a))) {
+    throw new CloudFlowError('invalid_input', `--agents takes one or two of ${FLOW_AGENT_HARNESSES.join(', ')}, got "${value}".`);
+  }
+  return agents as FlowAgentHarness[];
+}
+
+export interface CloudDeployment {
+  agentId: string;
+  name: string;
+  status: string;
+  repository: { owner: string; name: string };
+  sources: FlowTriggerSource[];
+  sourceSha256: string;
+}
+
+export function parseRepository(value: string): { owner: string; name: string } {
+  const [owner, name, extra] = value.replace(/^https?:\/\/github\.com\//iu, '').replace(/\.git$/iu, '').split('/');
+  if (!owner || !name || extra !== undefined || !REPO_OWNER.test(owner) || !REPO_NAME.test(name)) {
+    throw new CloudFlowError('invalid_input', `Expected --repo <owner>/<name>, got "${value}".`);
+  }
+  return { owner, name };
+}
+
+/** `github`, `github:labels=agent,contains=urgent`, `slack:channel=#eng`. */
+export function parseTriggerSource(value: string): FlowTriggerSource {
+  const colon = value.indexOf(':');
+  const provider = (colon === -1 ? value : value.slice(0, colon)).trim();
+  if (!(FLOW_TRIGGER_PROVIDERS as readonly string[]).includes(provider)) {
+    throw new CloudFlowError('invalid_input',
+      `Unknown trigger provider "${provider}"; expected one of ${FLOW_TRIGGER_PROVIDERS.join(', ')}.`);
+  }
+  const allowed = PROVIDER_SETTINGS[provider as FlowTriggerProvider];
+  const settings: Record<string, string> = {};
+  if (colon !== -1) {
+    for (const pair of value.slice(colon + 1).split(',')) {
+      const eq = pair.indexOf('=');
+      const key = (eq === -1 ? pair : pair.slice(0, eq)).trim();
+      const setting = eq === -1 ? '' : pair.slice(eq + 1).trim();
+      if (!allowed.includes(key)) {
+        throw new CloudFlowError('invalid_input',
+          `"${key}" is not a ${provider} trigger setting; ${provider} accepts ${allowed.join(', ')}.`);
+      }
+      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.`);
+      }
+      settings[key] = setting;
+    }
+  }
+  return { provider: provider as FlowTriggerProvider, settings };
+}
+
+export async function deployToCloud(
+  input: DeployToCloudInput, options: CloudConnectionOptions = {},
+): Promise<CloudDeployment> {
+  if (!/\.flow\.ts$/iu.test(input.path)) {
+    throw new CloudFlowError('unsupported_source', 'flows deploy takes one authored .flow.ts source.');
+  }
+  let bytes: Buffer;
+  try {
+    bytes = await readFile(input.path);
+  } catch (error) {
+    throw new CloudFlowError('invalid_input',
+      `Cannot read ${input.path}: ${(error as NodeJS.ErrnoException).code ?? (error as Error).message}.`);
+  }
+  const source = bytes.toString('utf8');
+  if (!bytes.length || Buffer.from(source, 'utf8').compare(bytes) !== 0) {
+    throw new CloudFlowError('invalid_input', 'Authored source must be nonempty, lossless UTF-8.');
+  }
+  if (bytes.length > MAX_SOURCE_BYTES) {
+    throw new CloudFlowError('invalid_input', `Authored source exceeds Cloud's ${MAX_SOURCE_BYTES}-byte deploy limit.`);
+  }
+  let loaded: Awaited<ReturnType<typeof loadAuthoredFlow>>;
+  let definition: ReturnType<typeof loaded.getDefinition>;
+  try {
+    loaded = await loadAuthoredFlow(input.path);
+    definition = loaded.getDefinition(loaded.handle);
+  } catch (error) {
+    if (error instanceof CloudFlowError) throw error;
+    // A source that does not load is an authoring problem, refused before HTTP.
+    throw new CloudFlowError('unsupported_source',
+      `${input.path} is not a loadable authored flow: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (loaded.graph.length !== 1) {
+    throw new CloudFlowError('unsupported_source',
+      'Cloud deploys one self-contained .flow.ts source without use dependencies.');
+  }
+  if (input.sources.length === 0 || input.sources.length > 10) {
+    throw new CloudFlowError('invalid_input', 'Give between one and ten --on trigger sources.');
+  }
+  if (new Set(input.sources.map(s => s.provider)).size !== input.sources.length) {
+    throw new CloudFlowError('invalid_input', 'Each trigger provider can be given once.');
+  }
+  const approver = input.approver.trim();
+  if (!approver) throw new CloudFlowError('invalid_input', '--approver must name who approves f.human questions.');
+  const name = (input.name ?? definition.name).trim();
+  if (!name || name.length > 100) throw new CloudFlowError('invalid_input', 'Deployment name must be 1-100 characters.');
+  // A GitHub source scoped to nothing would wake on every repository the
+  // installation covers; default it to the deployment's own repository.
+  const sources = input.sources.map(s => s.provider === 'github' && s.settings['repository'] === undefined
+    ? { ...s, settings: { ...s.settings, repository: `${input.repository.owner}/${input.repository.name}` } }
+    : s);
+  options.signal?.throwIfAborted();
+
+  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.');
+  }
+  const agents = input.agents ?? ['claude'];
+  const result = await cloudFetch('/api/v1/flows/deploy', options, { method: 'POST', detail: true, body: JSON.stringify({
+    workspaceId: workspace.id,
+    mode: input.draft ? 'draft' : 'activate',
+    name,
+    // The onboarding's workflow-shape label; the CLI deploys authored source as-is.
+    workflow: 'flows-cli',
+    source,
+    handoffId: `flows-cli-${randomBytes(8).toString('hex')}`,
+    inputs: { approver, agents },
+    repository: input.repository,
+    sources,
+  }) });
+  if (!isCloudRecord(result) || typeof result.agentId !== 'string' || typeof result.status !== 'string') {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return a deployment.');
+  }
+  return {
+    agentId: result.agentId, name, status: result.status,
+    repository: input.repository, sources,
+    sourceSha256: createHash('sha256').update(bytes).digest('hex'),
+  };
+}
+
+export interface CloudDeploymentSummary {
+  agentId: string;
+  name: string;
+  status: string;
+  repository?: { owner: string; name: string };
+  sources: FlowTriggerSource[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export async function listCloudDeployments(options: CloudConnectionOptions = {}): Promise<CloudDeploymentSummary[]> {
+  const payload = await cloudRequest('/api/v1/agents/flow-deployments', options);
+  if (!isCloudRecord(payload) || !Array.isArray(payload.deployments)) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return a deployments list.');
+  }
+  return payload.deployments.map((row): CloudDeploymentSummary => {
+    if (!isCloudRecord(row) || typeof row.agentId !== 'string' || typeof row.name !== 'string') {
+      throw new CloudFlowError('invalid_response', 'Cloud returned a malformed deployment row.');
+    }
+    const repository = isCloudRecord(row.repository) && typeof row.repository.owner === 'string'
+      && typeof row.repository.name === 'string' ? { owner: row.repository.owner, name: row.repository.name } : undefined;
+    const sources = Array.isArray(row.sources) ? row.sources.flatMap((s): FlowTriggerSource[] =>
+      isCloudRecord(s) && typeof s.provider === 'string' && (FLOW_TRIGGER_PROVIDERS as readonly string[]).includes(s.provider)
+        ? [{ provider: s.provider as FlowTriggerProvider,
+            settings: Object.fromEntries(Object.entries(isCloudRecord(s.settings) ? s.settings : {})
+              .flatMap(([k, v]) => typeof v === 'string' ? [[k, v]] : typeof v === 'boolean' ? [[k, String(v)]] : [])) }]
+        : []) : [];
+    return {
+      agentId: row.agentId, name: row.name, status: typeof row.status === 'string' ? row.status : 'unknown',
+      ...(repository === undefined ? {} : { repository }), sources,
+      ...(typeof row.createdAt === 'string' ? { createdAt: row.createdAt } : {}),
+      ...(typeof row.updatedAt === 'string' ? { updatedAt: row.updatedAt } : {}),
+    };
+  });
+}
+
+const LISTENER_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+
+/** `DELETE /api/v1/flows/listeners/<id>`: the listener stops; past runs and their journals stay. */
+export async function undeployFromCloud(agentId: string, options: CloudConnectionOptions = {}): Promise<void> {
+  if (!LISTENER_ID.test(agentId)) throw new CloudFlowError('invalid_input', `"${agentId}" is not a deployment id.`);
+  const result = await cloudFetch(`/api/v1/flows/listeners/${encodeURIComponent(agentId)}`, options, { method: 'DELETE', detail: true });
+  if (!isCloudRecord(result) || result.status !== 'deleted') {
+    throw new CloudFlowError('invalid_response', 'Cloud did not confirm the deletion.');
+  }
+}

package/src/cloud-http.ts

@@ -1,3 +1,7 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
 export interface CloudConnectionOptions {
   /** Cloud application base URL; defaults to https://agentrelay.com/cloud. */
   apiUrl?: string;
@@ -10,7 +14,9 @@ export interface CloudConnectionOptions {
 
 export class CloudFlowError extends Error {
   constructor(
-    readonly code: 'configuration' | 'unsupported_source' | 'invalid_input' | 'invalid_response' | 'http_error' | 'transport_error' | 'transient_error',
+    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',
     message: string,
     readonly status?: number,
   ) {
@@ -19,16 +25,66 @@ export class CloudFlowError extends Error {
   }
 }
 
+/**
+ * The `agent-relay cloud login` credential store. Read only when neither the
+ * `token` option nor `FLOWS_CLOUD_TOKEN` is set, so an explicit credential
+ * always wins and this file can change shape without breaking a configured
+ * caller. Its `apiUrl` becomes the default base URL for the same reason: a
+ * login against one deployment must not send its token to another.
+ */
+export function agentRelayCloudAuthPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(env['AGENT_RELAY_HOME'] ?? join(homedir(), '.agentworkforce/relay'), 'cloud-auth.json');
+}
+
+export interface AgentRelayCloudLogin {
+  apiUrl: string;
+  accessToken: string;
+  /** ISO-8601; the store carries it, so an expired login refuses with a real reason. */
+  accessTokenExpiresAt?: string;
+}
+
+export function readAgentRelayCloudLogin(
+  env: NodeJS.ProcessEnv = process.env,
+  read: (path: string) => string = path => readFileSync(path, 'utf8'),
+): AgentRelayCloudLogin | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(read(agentRelayCloudAuthPath(env)));
+  } catch {
+    return undefined;
+  }
+  if (!isCloudRecord(parsed) || typeof parsed.apiUrl !== 'string' || typeof parsed.accessToken !== 'string'
+    || !parsed.accessToken.trim()) return undefined;
+  return {
+    apiUrl: parsed.apiUrl, accessToken: parsed.accessToken,
+    ...(typeof parsed.accessTokenExpiresAt === 'string' ? { accessTokenExpiresAt: parsed.accessTokenExpiresAt } : {}),
+  };
+}
+
 export function cloudConnection(options: CloudConnectionOptions): { baseUrl: string; token: string } {
-  const rawToken = options.token ?? process.env['FLOWS_CLOUD_TOKEN'];
+  let rawToken = options.token ?? process.env['FLOWS_CLOUD_TOKEN'];
+  let loginApiUrl: string | undefined;
+  if (rawToken === undefined) {
+    const login = readAgentRelayCloudLogin();
+    if (login !== undefined) {
+      const expiresAt = login.accessTokenExpiresAt === undefined ? Number.NaN : Date.parse(login.accessTokenExpiresAt);
+      if (Number.isFinite(expiresAt) && expiresAt <= Date.now()) {
+        throw new CloudFlowError('configuration',
+          'The agent-relay cloud login has expired. Run `agent-relay cloud login` again, or set FLOWS_CLOUD_TOKEN.');
+      }
+      rawToken = login.accessToken;
+      loginApiUrl = login.apiUrl;
+    }
+  }
   const token = rawToken?.trim();
   if (!token || /[\r\n]/u.test(rawToken!) || /^(?:rk|ot)_live_/u.test(token)) {
     throw new CloudFlowError('configuration',
-      'Set FLOWS_CLOUD_TOKEN to a scoped Cloud API token (workflow:invoke:write and workflow:runs:read).');
+      'Set FLOWS_CLOUD_TOKEN to a scoped Cloud API token (workflow:invoke:write and workflow:runs:read), '
+      + 'or sign in with `agent-relay cloud login`.');
   }
   let url: URL;
   try {
-    url = new URL(options.apiUrl ?? process.env['FLOWS_CLOUD_URL'] ?? 'https://agentrelay.com/cloud');
+    url = new URL(options.apiUrl ?? process.env['FLOWS_CLOUD_URL'] ?? loginApiUrl ?? 'https://agentrelay.com/cloud');
   } catch {
     throw new CloudFlowError('configuration', 'FLOWS_CLOUD_URL must be an absolute Cloud application base URL.');
   }
@@ -36,26 +92,79 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
     || url.username || url.password || url.search || url.hash || !/^\/[A-Za-z0-9/_-]*$/u.test(url.pathname)) {
     throw new CloudFlowError('configuration', 'Cloud URL must use HTTPS and a plain base path.');
   }
-  return { baseUrl: `${url.origin}${url.pathname.replace(/\/+$/u, '')}`, token };
+  const baseUrl = `${url.origin}${url.pathname.replace(/\/+$/u, '')}`;
+  // A login-store token is bound to the deployment that issued it. An explicit
+  // URL that names another deployment gets no token at all — set
+  // FLOWS_CLOUD_TOKEN for that deployment instead.
+  if (loginApiUrl !== undefined) {
+    let issued: string | undefined;
+    try {
+      const login = new URL(loginApiUrl);
+      issued = `${login.origin}${login.pathname.replace(/\/+$/u, '')}`;
+    } catch { issued = undefined; }
+    if (issued !== baseUrl) {
+      throw new CloudFlowError('configuration',
+        `The agent-relay cloud login was issued for ${loginApiUrl}, not ${baseUrl}. `
+        + 'Set FLOWS_CLOUD_TOKEN for that deployment, or unset FLOWS_CLOUD_URL to use the login.');
+    }
+  }
+  return { baseUrl, token };
 }
 
 export async function cloudRequest(
   path: string,
   options: CloudConnectionOptions,
   body?: unknown,
+): Promise<unknown> {
+  return cloudFetch(path, options, body === undefined
+    ? { method: 'GET' }
+    : { method: 'POST', body: JSON.stringify(body), contentType: 'application/json' });
+}
+
+export interface CloudFetchInit {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: string | Uint8Array;
+  contentType?: string;
+  /**
+   * A run-scoped token issued by Cloud for one upload (the `prepare` receipt's
+   * storage credential). Used instead of the configured token for that request
+   * only; it is never persisted or logged.
+   */
+  bearerToken?: string;
+  /**
+   * On a non-2xx response, read a `{ code, error }` refusal from the body and
+   * name it. Only those two string fields are ever surfaced, so a route that
+   * answers with structured refusals (the deploy routes) can explain itself
+   * without this client echoing arbitrary response bodies.
+   */
+  detail?: boolean;
+}
+
+/** One authenticated Cloud request. Every transport error is typed; no retries. */
+export async function cloudFetch(
+  path: string,
+  options: CloudConnectionOptions,
+  init: CloudFetchInit,
 ): Promise<unknown> {
   const { baseUrl, token } = cloudConnection(options);
   const timeout = options.requestTimeoutMs ?? 30_000;
   if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2_147_483_647) {
     throw new CloudFlowError('configuration', 'requestTimeoutMs must be a positive 32-bit integer.');
   }
+  const bearer = init.bearerToken ?? token;
+  if (/[\r\n]/u.test(bearer) || !bearer.trim()) {
+    throw new CloudFlowError('invalid_response', 'Cloud issued an unusable storage credential.');
+  }
   const deadline = AbortSignal.timeout(timeout);
   let response: Response;
   try {
     response = await fetch(`${baseUrl}${path}`, {
-      method: body === undefined ? 'GET' : 'POST',
-      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      method: init.method,
+      headers: {
+        authorization: `Bearer ${bearer}`,
+        'content-type': init.contentType ?? 'application/json',
+      },
+      ...(init.body === undefined ? {} : { body: typeof init.body === 'string' ? init.body : new Blob([init.body]) }),
       signal: options.signal ? AbortSignal.any([options.signal, deadline]) : deadline,
       // A redirect must never carry the credential to a different origin.
       redirect: 'error',
@@ -66,7 +175,10 @@ export async function cloudRequest(
   }
   if (!response.ok) {
     // Do not echo server response bodies: they may contain credentials or source.
-    throw new CloudFlowError('http_error', `Cloud request failed with HTTP ${response.status}.`, response.status);
+    const refusal = init.detail ? await structuredRefusal(response) : undefined;
+    throw new CloudFlowError('http_error', refusal === undefined
+      ? `Cloud request failed with HTTP ${response.status}.`
+      : `Cloud refused (${refusal.code}): ${refusal.error}`, response.status);
   }
   try {
     return await response.json();
@@ -77,6 +189,14 @@ export async function cloudRequest(
   }
 }
 
+async function structuredRefusal(response: Response): Promise<{ code: string; error: string } | 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 };
+}
+
 // Defensive path-segment constraint; accepting a new server ID format needs an SDK change.
 export function cloudRunId(value: unknown): string {
   if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/u.test(value)) {

package/src/cloud-run.ts

@@ -13,6 +13,7 @@ import {
   CloudFlowError, cloudConnection, cloudRequest, cloudRunId, isCloudRecord,
   type CloudConnectionOptions,
 } from './cloud-http.js';
+import { packWorkingTree, prepareCloudSync, uploadCloudCode } from './cloud-sync.js';
 
 export type CloudFlowSource = FlowSpec | { path: string };
 export interface RunInCloudOptions extends CloudConnectionOptions {
@@ -20,6 +21,21 @@ export interface RunInCloudOptions extends CloudConnectionOptions {
   workspaceId?: string;
   /** Exact JSON input. Required at runtime for authored .flow.ts; refused for declarative source. */
   input?: JsonValue;
+  /**
+   * Upload this working tree before submission so the hosted run executes
+   * inside it (v1's `--sync-code`). Cloud-API storage only; see cloud-sync.ts.
+   * The submitted flow still travels as source in the request body, so it
+   * must remain self-contained: sibling imports inside the tree are not
+   * resolved by the hosted runner.
+   */
+  syncCode?: { root: string };
+  /**
+   * Called immediately before the one non-idempotent request, the run
+   * submission. Everything before it (prepare, pack, upload) is safe to
+   * retry, so a caller classifying an interruption can tell "nothing was
+   * admitted" from "admission unknown".
+   */
+  onSubmit?: () => void;
 }
 export interface CloudRunReceipt {
   runId: string;
@@ -28,6 +44,8 @@ export interface CloudRunReceipt {
   specHash: string;
   /** Authenticated run API resource; this is not a public sharing URL. */
   apiUrl: string;
+  /** Present when a working tree was synced: what was uploaded, by count and size. */
+  synced?: { files: number; bytes: number; skippedLinks: string[] };
 }
 export interface CloudAuthoredAuthority {
   readonly schemaVersion: 1;
@@ -118,6 +136,26 @@ export async function runInCloud(
         authority: authored.authority,
         input: authoredInput,
       })).digest('hex');
+  // 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
+  // pointing at a tree that is not there.
+  let synced: { runId: string; codeKey: string; files: number; bytes: number; skippedLinks: string[] } | undefined;
+  if (options.syncCode !== undefined) {
+    const prepared = await prepareCloudSync(options);
+    options.signal?.throwIfAborted();
+    const packed = await packWorkingTree(options.syncCode.root);
+    try {
+      options.signal?.throwIfAborted();
+      await uploadCloudCode(prepared, packed, options);
+    } finally {
+      packed.dispose();
+    }
+    synced = { runId: prepared.runId, codeKey: prepared.codeKey, files: packed.files.length, bytes: packed.bytes,
+      skippedLinks: packed.skippedLinks };
+  }
+  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.
@@ -127,12 +165,20 @@ export async function runInCloud(
     ...(authored === undefined ? {} : { authoredAuthority: authored.authority }),
     ...(authored === undefined ? {} : { inputs: authoredInput }),
     ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+    ...(synced === undefined ? {} : { runId: synced.runId, s3CodeKey: synced.codeKey }),
   });
   if (!isCloudRecord(result) || (result.status !== 'pending' && result.status !== 'running')) {
     throw new CloudFlowError('invalid_response', 'Cloud did not return an accepted run.');
   }
   const runId = cloudRunId(result.runId);
-  return { runId, status: result.status, specHash: hash, apiUrl: `${baseUrl}/api/v1/workflows/runs/${runId}` };
+  if (synced !== undefined && runId !== synced.runId) {
+    throw new CloudFlowError('invalid_response',
+      `Cloud accepted run ${runId} but the synced code was uploaded for ${synced.runId}.`);
+  }
+  return {
+    runId, status: result.status, specHash: hash, apiUrl: `${baseUrl}/api/v1/workflows/runs/${runId}`,
+    ...(synced === undefined ? {} : { synced: { files: synced.files, bytes: synced.bytes, skippedLinks: synced.skippedLinks } }),
+  };
 }
 
 export async function getCloudFlowRun(