@relayflows/sdk 2.0.15 → 2.0.17

package/src/authored-flow-operation.ts

@@ -8,7 +8,7 @@ import {
 
 /** Slice-P kinds the surface `.gate(config)` accepts and the SDK lowers. */
 const NAMED_GATE_KINDS = new Set([
-  'references_input', 'subprocess_gate', 'word_count_bounds', 'regex_match',
+  'references_input', 'subprocess_gate', 'word_count_bounds', 'regex_match', 'artifact_exists',
 ]);
 
 function isNamedGateConfig(candidate: unknown): candidate is NamedGate {
@@ -31,6 +31,14 @@ export class AuthoredFlowOperation<T> {
    * still throws `unsupported_gate` and never sets this field.
    */
   namedGate: NamedGate | undefined = undefined;
+  /**
+   * Predicate gate attached via `.gate(fn, because?)`. Author code: it runs
+   * in this process after the step completes, and its verdict is journaled as
+   * a lowered `<id>.gate` deterministic step (docs/SURFACE.md §6), so replay
+   * and resume see the recorded verdict and never re-run the closure. The
+   * function itself is never serialized. `flows check` cannot prove it.
+   */
+  predicateGate: { predicate: (value: T) => boolean; because?: string } | undefined = undefined;
   private state: OperationState = 'created';
   private thenInvoked = false;
   private rootFailureRecorded = false;
@@ -61,20 +69,29 @@ export class AuthoredFlowOperation<T> {
     const operation = this;
     const step: Step<T> = {
       gate(configOrPredicate: NamedGate | ((value: T) => boolean), _because?: string): Step<T> {
+        if (operation.namedGate !== undefined || operation.predicateGate !== undefined) {
+          throw new AuthoredFlowExecutionError('unsupported_gate', 'a step takes one .gate().');
+        }
         if (isNamedGateConfig(configOrPredicate)) {
           // Config-object gate: lowers into the compiled StepSpec's
           // `verification:` field via slice-P named-gate lowering.
           operation.namedGate = configOrPredicate;
           return step;
         }
-        // Predicate gate: closures cannot be journaled (covenant 1
-        // journal-as-truth). Refuse — authors should use a config-object
-        // gate or the declarative `verification:` block.
-        throw new AuthoredFlowExecutionError(
-          'unsupported_gate',
-          'postfix .gate(predicate) closures cannot be journaled; '
-            + 'use .gate({type: "…", …}) with a slice-P named gate instead.',
-        );
+        // Predicate gate: runtime control flow. The closure cannot be
+        // journaled, but its VERDICT can — the executor runs it once after
+        // the step completes and records pass/fail as a `<id>.gate` step.
+        if (typeof configOrPredicate !== 'function') {
+          throw new AuthoredFlowExecutionError(
+            'unsupported_gate',
+            '.gate() takes a named gate config ({type: "…", …}) or a predicate function.',
+          );
+        }
+        if (_because !== undefined && typeof _because !== 'string') {
+          throw new AuthoredFlowExecutionError('unsupported_gate', '.gate(predicate, because) takes a string reason.');
+        }
+        operation.predicateGate = { predicate: configOrPredicate, ...(_because === undefined ? {} : { because: _because }) };
+        return step;
       },
       then<TResult1 = T, TResult2 = never>(
         onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
@@ -144,7 +161,15 @@ export class AuthoredFlowOperation<T> {
     try {
       this.assertCanStart();
       this.state = 'running';
-      const value = await this.start();
+      const started = await this.start();
+      // The predicate gate, when present, is applied here for every kind of
+      // operation, so a helper or plugin step cannot carry a gate that never
+      // runs. The executor installs the applier; without one, a predicate
+      // gate is refused rather than skipped.
+      const value = this.predicateGate === undefined ? started
+        : this.scope.applyPredicateGate === undefined
+          ? (() => { throw new AuthoredFlowExecutionError('unsupported_gate', 'this runtime cannot apply predicate gates'); })()
+          : await this.scope.applyPredicateGate(this as unknown as { id: string; predicateGate: unknown }, started);
       this.state = 'fulfilled';
       this.resolve(value);
     } catch (error) {

package/src/authored-node-runner.ts

@@ -161,30 +161,44 @@ export async function verifyAuthoredNodeResult(
   result: AuthoredFlowExecutionResult, metadata: AuthoredRootMetadata,
   rootRunId: string, socketPath: string,
 ): Promise<void> {
-  const invalid = (): never => { throw new Error('authored runtime result has no matching durable completion'); };
+  const invalid = (why = ''): never => { throw new Error(`authored runtime result has no matching durable completion${process.env['FLOWS_VERIFIER_DEBUG'] && why ? ` (${why})` : ''}`); };
   if (result.rootRunId !== rootRunId || result.name !== metadata.flowName
     || !isLoweredCompletion(result.completionReason)
-    || !Array.isArray(result.journalSteps) || result.journalSteps.length === 0) invalid();
+    || !Array.isArray(result.journalSteps) || result.journalSteps.length === 0) invalid('frame');
   const terminal = result.journalSteps.at(-1)!;
-  if (!terminal || !/^complete-[1-9][0-9]*$/.test(terminal.id)) invalid();
+  if (!terminal || !/^complete-[1-9][0-9]*$/.test(terminal.id)) invalid('terminal');
   const count = Number(terminal.id.slice('complete-'.length));
-  if (!Number.isSafeInteger(count) || result.journalSteps.length !== count) invalid();
+  // A predicate gate is journaled as `<step>.gate`: a child run subordinate
+  // to the authored step it judges, in the same `<step>.gate` shape a named
+  // gate lowers to inside its step's own spec. Neither consumes an ordinal —
+  // `complete-N` counts the operations the author wrote (SURFACE.md §6) —
+  // so gates are set aside from the count and the contiguity check, and
+  // verified separately: every gate must name a claimed parent, and is then
+  // held to the same durable-completion evidence as any other child run.
+  const isGate = (id: string): boolean => /\.gate$/.test(id);
+  const authored = result.journalSteps.filter(step => typeof step?.id === 'string' && !isGate(step.id));
+  const gates = result.journalSteps.filter(step => typeof step?.id === 'string' && isGate(step.id));
+  if (!Number.isSafeInteger(count) || authored.length !== count || isGate(terminal.id)) invalid(`count ${authored.length}!=${count}`);
   const ordinal = (id: string): number => Number(/-([1-9][0-9]*)$/.exec(id)?.[1]);
   // Parallel awaits may finish in either order; validate a copy in declaration order.
-  const ordered = [...result.journalSteps].sort((a,b)=>ordinal(a.id)-ordinal(b.id));
+  const ordered = [...authored].sort((a,b)=>ordinal(a.id)-ordinal(b.id));
+  const authoredIds = new Set(ordered.map(step => step.id));
+  for (const gate of gates) {
+    if (!authoredIds.has(gate.id.slice(0, -'.gate'.length))) invalid(`orphan ${gate.id}`);
+  }
   const runs = new Set<string>();
   const journal = new JournalClient(socketPath);
   await journal.connect();
   try {
     await journal.hello('flows-authored-result-verifier');
-    for (const [index, claimed] of ordered.entries()) {
+    for (const [index, claimed] of [...ordered, ...gates].entries()) {
       if (!claimed || typeof claimed.id !== 'string' || typeof claimed.runId !== 'string'
-        || ordinal(claimed.id) !== index+1 || claimed.completionReason !== 'success'
-        || runs.has(claimed.runId)) invalid();
+        || (index < ordered.length && ordinal(claimed.id) !== index+1) || claimed.completionReason !== 'success'
+        || runs.has(claimed.runId)) invalid(`claim ${claimed?.id}`);
       runs.add(claimed.runId);
       const state = await journal.runGet(claimed.runId);
       if (state.run_id !== claimed.runId || state.status !== 'completed'
-        || state.steps[claimed.id]?.state !== 'done') invalid();
+        || state.steps[claimed.id]?.state !== 'done') invalid(`state ${claimed.id} ${state.status} ${state.steps[claimed.id]?.state}`);
       const entries: Array<{
         seq: number; entry_type: string; step_id?: string; payload?: {
           completionReason?: string; spec?: { name?: string; steps?: Array<{id?:string;type?:string;command?:string}> };
@@ -196,7 +210,7 @@ export async function verifyAuthoredNodeResult(
         if (page.length === 0) break;
         for (const raw of page) {
           const entry = raw as typeof entries[number];
-          if (!Number.isSafeInteger(entry?.seq) || entry.seq < fromSeq) invalid();
+          if (!Number.isSafeInteger(entry?.seq) || entry.seq < fromSeq) invalid('seq');
           fromSeq = entry.seq + 1;
           // Keep only completion evidence; streaming logs can span many pages.
           if (['run.spawned', 'step.completed', 'run.completed'].includes(entry.entry_type)) entries.push(entry);
@@ -204,12 +218,20 @@ export async function verifyAuthoredNodeResult(
       }
       const spec = entries.find(entry => entry.entry_type === 'run.spawned')?.payload?.spec;
       const step = spec?.steps?.[0];
+      // A named gate lowers INTO the step's own spec as a second, dependent
+      // `<id>.gate` step (named-gate-lowering.ts); that is the only other
+      // step a child spec may carry, and it must have completed too.
+      const lowered = spec?.steps ?? [];
+      const specShape = lowered.length === 1 || (lowered.length === 2 && lowered[1]?.id === `${claimed.id}.gate`);
       const completed = entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === claimed.id);
+      const gateCompleted = lowered.length === 2
+        ? entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === `${claimed.id}.gate`) : [];
       const terminalFacts = entries.filter(entry => entry.entry_type === 'run.completed');
-      if (spec?.name !== `${metadata.flowName}/${claimed.id}` || spec?.steps?.length !== 1
+      if (spec?.name !== `${metadata.flowName}/${claimed.id}` || !specShape
         || step?.id !== claimed.id || completed.length !== 1
         || completed[0]?.payload?.completionReason !== 'success'
-        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid();
+        || (lowered.length === 2 && (gateCompleted.length !== 1 || gateCompleted[0]?.payload?.completionReason !== 'success'))
+        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid(`evidence ${claimed.id} spec=${spec?.name} step=${step?.id} completed=${completed.length}`);
       if (claimed === terminal) {
         // The claimed verdict must match the marker the journal actually
         // recorded, so an IPC frame cannot claim `success` over a run whose
@@ -219,7 +241,7 @@ export async function verifyAuthoredNodeResult(
         // the runtime validation of untrusted IPC, and it is why nothing has
         // to be re-asserted here just to satisfy the type.
         if (step?.type !== 'deterministic'
-          || step.command !== completionMarker(result.completionReason)) invalid();
+          || step.command !== completionMarker(result.completionReason)) invalid('marker');
       }
     }
   } finally { journal.close(); }

package/src/authored-step-output.ts

@@ -1,4 +1,4 @@
-import { COMPLETION_REASONS, RUN_COMPLETION_REASONS } from '@relayflows/surface';
+import { COMPLETION_REASONS, RUN_COMPLETION_REASONS, FLOW_COMPLETION_REASONS, type FlowCompletionReason } from '@relayflows/surface';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
 import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason as ProtocolRunCompletionReason, RunOutcome } from './protocol.js';
@@ -93,6 +93,11 @@ export function isSurfaceRunCompletionReason(value: unknown): value is ProtocolR
     && (RUN_COMPLETION_REASONS as readonly string[]).includes(value);
 }
 
+export function isSurfaceFlowCompletionReason(value: unknown): value is FlowCompletionReason {
+  return typeof value === 'string'
+    && (FLOW_COMPLETION_REASONS as readonly string[]).includes(value);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/src/authored-worker-step.ts

@@ -7,7 +7,7 @@ import { classifyOutcome, type RunLifecycleOptions } from './cli/run.js';
 import type { PreflightDiagnostic } from './preflight.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
-import { SPEC_SCHEMA_VERSION, type FlowSpec, type StepSpec } from './spec.js';
+import { SPEC_SCHEMA_VERSION, type FlowSpec, type PermissionsSpec, type StepSpec } from './spec.js';
 import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput } from './authored-step-output.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { snapshotJsonValue } from './json-value.js';
@@ -96,13 +96,10 @@ export function authoredWorkerRunner(
       if (options.workspace !== undefined && WORKSPACE_PERMISSION_ANNOTATION.test(options.workspace)) {
         throw new AuthoredFlowExecutionError(
           'unsupported_workspace_permission',
-          `flow "${definition.name}" step "${id}": workspace "${options.workspace}" declares a `
-            + 'permission annotation ("...: readonly" / "...: readwrite"), but nothing enforces it — '
-            + 'no parser anywhere in this package turns that annotation into a real restriction '
-            + '(kernel/DAEMON-LIFECYCLE.md\'s permission model is untouched by f.agent). '
-            + 'Silently accepting and ignoring it would let a flow believe a restriction is in effect '
-            + "when it is not. Declare a bare surface name (no trailing \": readonly\"/\": readwrite\") "
-            + 'if you do not need enforcement, or use the declarative spec\'s `permissions` field, which is real.',
+          `flow "${definition.name}" step "${id}": workspace "${options.workspace}": `
+            + "Workspace permission suffixes are unsupported. Use a bare workspace name and f.agent's "
+            + "permissions option, for example permissions: { fileGlobs: ['src/**'], accessPreset: 'readonly' }. "
+            + 'This declaration is validated and recorded with the step spec; it is not currently enforced (gate 8 / #442).',
         );
       }
       if (options.cli !== undefined && typeof options.cli !== 'string') {
@@ -129,8 +126,12 @@ export function authoredWorkerRunner(
           `f.agent options.transport must be 'direct' or 'relay' (got ${JSON.stringify(options.transport)}).`,
         );
       }
+      const permissions = options.permissions;
+      const permissionsSnapshot = permissions === undefined ? undefined
+        : snapshotJsonValue(permissions, 'f.agent options.permissions') as unknown as PermissionsSpec;
       const output = await run({
         id, type: 'agent', instruction: options.task,
+        ...(permissionsSnapshot === undefined ? {} : { permissions: permissionsSnapshot }),
         ...(localAgentStream === undefined ? {} : { surfaces: { streams: [{ stream: localAgentStream }] } }),
         ...(options.workspace === undefined ? {} : { surfaces: { workspace: [{ surface: options.workspace }] } }),
         ...(options.cli === undefined ? {} : { cli: options.cli }),
@@ -143,7 +144,13 @@ export function authoredWorkerRunner(
         throw new AuthoredFlowExecutionError('journal_protocol_violation', `step "${id}" produced a non-object output`);
       }
       const stdout = 'stdout_tail' in output ? output.stdout_tail : undefined;
-      return { summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts: [] };
+      // The worker that ran the CLI measured the artifacts and journaled them
+      // in the step's output; read that fact back rather than re-scanning a
+      // directory this process may not even share with the agent.
+      const journaled = 'artifacts' in output ? output.artifacts : undefined;
+      const artifacts = Array.isArray(journaled) && journaled.every(entry => typeof entry === 'string')
+        ? [...journaled] : [];
+      return { summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts };
     },
     async llm(id: string, prompt: string, options?: LlmOptions, verification?: NamedGate): Promise<unknown> {
       if (options !== undefined && (typeof options !== 'object' || options === null || options.output === undefined)) {

package/src/cli/check-triggers.ts

@@ -2,6 +2,7 @@ import { dirname, resolve } from 'node:path';
 import { loadAuthoredFlow, type LoadedAuthoredFlow } from '../authored-flow-loader.js';
 import { preflightWebhookTriggers } from '../preflight.js';
 import { preflightProviderTriggers } from '../provider-trigger-contract.js';
+import { scheduleLowering } from '../schedule-trigger.js';
 import { checkSlackHelpers } from '../slack-preflight.js';
 import { inputFailureReport, readProjectConfig, type CheckReport } from './check.js';
 
@@ -31,12 +32,20 @@ export async function checkAuthoredTriggers(path: string): Promise<{
     const diagnostics = [
       ...triggerDiagnostics, ...providerDiagnostics, ...helperReport.diagnostics,
     ];
+    // A schedule is inspectable data: print what it lowers to, and say plainly
+    // when the local runner cannot drive it. Neither is a refusal — Cloud can.
+    const schedules = triggers.flatMap((trigger, handler) => {
+      if (trigger.kind !== 'schedule') return [];
+      const lowering = scheduleLowering(definition.name, trigger);
+      return [{ handler, ...lowering }];
+    });
     return {
       loaded,
       report: {
         // Severity, not emptiness: a warning must never refuse a flow.
         ok: !diagnostics.some(diagnostic => diagnostic.severity === 'refusal'),
         path, gates: [], resolutions: [], diagnostics,
+        ...(schedules.length === 0 ? {} : { schedules }),
         ...(config.path === undefined ? {} : { projectConfigPath: config.path }),
       },
     };

package/src/cli/check.ts

@@ -45,9 +45,24 @@ export interface CheckReport {
   projectConfigPath?: string;
   gates: StepGateInspection[];
   resolutions: CliResolution[];
+  /** Authored `schedule.*` handlers and the `flows.tick` subscription each lowers to. */
+  schedules?: ScheduleInspection[];
   diagnostics: Array<PreflightDiagnostic | CheckInputDiagnostic | CheckWarningDiagnostic>;
 }
 
+export interface ScheduleInspection {
+  /** Position among the flow's handlers, so two identical declarations stay distinct. */
+  handler: number;
+  cron?: string;
+  tz?: string;
+  intervalMs?: number;
+  epochMs?: number;
+  staleAfterMs?: number;
+  scheduleId: string;
+  /** Present when the local tick runner cannot drive it (only a cron-aware runner can). */
+  localUnsupported?: string;
+}
+
 export interface CheckWarningDiagnostic {
   severity: 'warning';
   kind: CheckWarningKind;
@@ -340,7 +355,12 @@ function systemProbes(flowDirectory: string, config: ProjectConfig): PreflightPr
     helper: helperReady,
     cli: (cli, source, model) => probeCli(cli, source === 'project' ? config.directory : flowDirectory, model),
     executor: (trigger) => config.executors.includes(trigger.executor),
-    command: (binary) => executableExists(binary, flowDirectory),
+    // A deterministic step runs in the daemon's working directory — the
+    // directory `flows run` was invoked from, or Cloud's code mount — not in
+    // the flow file's. Probing `./x` against the flow's directory answered a
+    // question the kernel never asks, and refused a Cloud run whose synced
+    // tree held the script while its source sat in the state directory.
+    command: (binary) => executableExists(binary, process.cwd()),
   };
 }
 

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);