@relayflows/sdk 2.0.41 → 2.0.43

package/src/cloud-run.ts

@@ -10,7 +10,7 @@ import { snapshotJsonValue, type JsonValue } from './json-value.js';
 import { loadAuthoredFlow, type SurfaceModuleAuthority } from './authored-flow-loader.js';
 import { assertNoUseDependencies, collectExtensionSubmissions, type FlowExtensionSubmission } from './flow-extension-submit.js';
 import {
-  CloudFlowError, cloudConnection, cloudFetch, cloudRequest, cloudRunId, isCloudRecord,
+  CloudFlowError, resolveCloudConnection, cloudFetch, cloudRequest, cloudRunId, isCloudRecord,
   type CloudConnectionOptions,
 } from './cloud-http.js';
 import { cloudRunState, isCloudRunActive, type CloudRunState } from './cloud-run-record.js';
@@ -37,6 +37,15 @@ export interface RunInCloudOptions extends CloudConnectionOptions {
    * admitted" from "admission unknown".
    */
   onSubmit?: () => void;
+  /**
+   * Per-run environment variables for the hosted sandbox, e.g. a short-lived
+   * token for the caller's own API. Sent with this run's submission only: never
+   * part of {@link cloudSubmissionBody}, so a schedule never stores them, and
+   * never echoed in errors or the receipt. Names must match
+   * `^[A-Za-z_][A-Za-z0-9_]*$`; Cloud refuses names it owns (run identity,
+   * Relay/Relayfile auth, provider keys such as `ANTHROPIC_API_KEY`).
+   */
+  envSecrets?: Readonly<Record<string, string>>;
 }
 export interface CloudRunReceipt {
   runId: string;
@@ -68,6 +77,37 @@ export function cloudSubmissionBody(submission: CloudSubmission): Record<string,
 
 export type { CloudRunState };
 
+const ENV_SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+
+/**
+ * Validate and copy per-run env secrets before any network call. Errors name
+ * the offending variable, never its value.
+ */
+function snapshotEnvSecrets(value: unknown): Record<string, string> | undefined {
+  if (value === undefined) return undefined;
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new CloudFlowError('invalid_input', 'envSecrets must be an object mapping variable names to string values.');
+  }
+  // Null prototype: an own `__proto__` key (JSON.parse creates one) must not
+  // hit the inherited setter and vanish from the copy.
+  const copy: Record<string, string> = Object.create(null) as Record<string, string>;
+  for (const [name, secret] of Object.entries(value)) {
+    if (!ENV_SECRET_NAME.test(name)) {
+      throw new CloudFlowError('invalid_input', `envSecrets name "${name}" must match ^[A-Za-z_][A-Za-z0-9_]*$.`);
+    }
+    if (name === '__proto__') {
+      // Valid shell syntax, but Cloud's plain-object env handling cannot carry
+      // it and refuses it; fail here, by name, instead of losing it silently.
+      throw new CloudFlowError('invalid_input', 'envSecrets name "__proto__" cannot be delivered to a hosted run.');
+    }
+    if (typeof secret !== 'string') {
+      throw new CloudFlowError('invalid_input', `envSecrets value for "${name}" must be a string.`);
+    }
+    copy[name] = secret;
+  }
+  return Object.keys(copy).length === 0 ? undefined : copy;
+}
+
 /**
  * Submit a declarative flow to Cloud's pinned v2 runtime. Compilation only
  * happens here; Cloud owns provisioning and the Rust engine owns execution.
@@ -210,8 +250,11 @@ export async function runInCloud(
   flow: CloudFlowSource,
   options: RunInCloudOptions = {},
 ): Promise<CloudRunReceipt> {
-  const { baseUrl } = cloudConnection(options);
+  // Validate locally first: resolving the connection may refresh a stored
+  // login, which posts the refresh token and rotates the credential file.
+  const envSecrets = snapshotEnvSecrets(options.envSecrets);
   const submission = await prepareCloudSubmission(flow, options);
+  const { baseUrl } = await resolveCloudConnection(options);
   const hash = submission.specHash;
   // Sync before submission: `prepare` reserves the run ID and the upload lands
   // under it, so the run request below names code Cloud already holds. A
@@ -239,6 +282,7 @@ export async function runInCloud(
       ...cloudSubmissionBody(submission),
       ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
       ...(synced === undefined ? {} : { runId: synced.runId, s3CodeKey: synced.codeKey }),
+      ...(envSecrets === undefined ? {} : { envSecrets }),
     }) });
   } catch (error) {
     // Cloud accepts exactly one authored Surface (the one its sandbox runs).

package/src/communication/local.ts

@@ -1,5 +1,6 @@
 import { onWorkerFailure } from '../worker-lease.js';
 import { randomUUID } from 'node:crypto';
+import { FLOW_READ_BUDGET_MS } from '../journal-read-policy.js';
 import { JournalClient } from '../journal-client.js';
 import { AgentWorker } from '../worker.js';
 import type { KernelRunSpec } from '../spec.js';
@@ -18,6 +19,9 @@ export async function attachCommunicationWorkers(spec: KernelRunSpec, socketPath
   let failure: unknown;
   const close = async () => {
     const outcomes = await Promise.allSettled(workers.map(async ({ client, worker }) => {
+      // Stop budgeted reads first: draining the worker must not wait out a
+      // delayed history read on shutdown.
+      client.cancelReads();
       try { await worker.close(); } finally { client.close(); }
     }));
     const rejected = outcomes.find(result => result.status === 'rejected');
@@ -28,7 +32,8 @@ export async function attachCommunicationWorkers(spec: KernelRunSpec, socketPath
       if (step.type !== 'agent') continue;
       requireCommunicationCli(step.cli ?? spec.cli);
       if (step.surfaces?.workspace?.length) throw new Error('Local communication workers support stream surfaces only');
-      const client = new JournalClient(socketPath);
+      // History reads on a retried attempt meet the same CPU load as flow reads.
+      const client = new JournalClient(socketPath, { readBudgetMs: FLOW_READ_BUDGET_MS });
       const worker = new AgentWorker(client, { workerId: `communication-${randomUUID()}`, dataDir, environment,
         requiredStreams: [channelName(step.id, '$receipts')],
         pins: { workspace: [], streams: step.surfaces?.streams?.map(({ stream }) => ({ stream, read_offset: 0 })) ?? [] } });

package/src/communication/worker.ts

@@ -5,7 +5,8 @@ import { setTimeout as delay } from 'node:timers/promises';
 import type { JournalClient } from '../journal-client.js';
 import type { StepDispatchEvent } from '../protocol.js';
 import type { ResolvedKernelAgentStep } from '../resolved-cli-identity.js';
-import { withWorkerLease } from '../worker-lease.js';
+import { isLeaseLost, withWorkerLease } from '../worker-lease.js';
+import { isReadInterruptionError } from '../journal-read-policy.js';
 import { workerInstruction } from '../worker-input.js';
 import { resolveCliModel } from '../cli-adapter.js';
 import { resolveAgentCwd } from '../agent-cwd.js';
@@ -26,9 +27,16 @@ export async function completeCommunicationDispatch(client: JournalClient, dispa
   let output: unknown;
   let completionReason: 'success' | 'worker_error' = 'success';
   try {
-    output = await withWorkerLease(client, dispatch, signal =>
-      run(client, dispatch, instruction, spec, dataDir, signal, runRoot, environment));
+    output = await withWorkerLease(client, dispatch, signal => {
+      // A lost lease stops this attempt's history reads instead of letting
+      // them run out the budget beside the kernel's retry.
+      const releaseReads = client.scopeReads?.(signal) ?? (() => {});
+      return run(client, dispatch, instruction, spec, dataDir, signal, runRoot, environment).finally(releaseReads);
+    });
   } catch (error) {
+    // A lost lease or an unanswered read belongs to the kernel's sweep and
+    // retry: never complete the attempt here as a worker failure.
+    if (isLeaseLost(error) || isReadInterruptionError(error)) throw error;
     completionReason = 'worker_error';
     output = { error: error instanceof Error ? error.message : String(error) };
   }

package/src/compile.ts

@@ -253,6 +253,7 @@ function compileStep(step: StepSpec): StepSpec {
         ...(s.cli !== undefined ? { cli: s.cli } : {}),
         ...(s.model !== undefined ? { model: s.model } : {}),
         ...(s.cwd !== undefined ? { cwd: s.cwd } : {}),
+        ...(s.resume !== undefined ? { resume: s.resume } : {}),
         ...(s.transport !== undefined ? { transport: s.transport } : {}),
         recoveryMode,
         ...(s.surfaces !== undefined ? { surfaces: s.surfaces } : {}),
@@ -464,7 +465,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
   const unionKeys = [
     'id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input',
     'command', 'timeout_ms', 'lease_ms', 'on_non_zero', 'prompt', 'model', 'cli', 'instruction',
-    'cwd', 'recovery_mode', 'surfaces', 'permissions', 'transport', 'cli_identity',
+    'cwd', 'resume', 'recovery_mode', 'surfaces', 'permissions', 'transport', 'cli_identity',
   ] as const;
   const step = requireKernelObject(value, unionKeys, at);
   if (step['cli_identity'] !== undefined) {
@@ -479,7 +480,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
     : type === 'llm'
       ? ['prompt', 'model', 'cli', 'cli_identity'] as const
       : type === 'agent'
-        ? ['timeout_ms', 'instruction', 'cli', 'model', 'recovery_mode', 'surfaces', 'permissions', 'cwd', 'transport', 'cli_identity'] as const
+        ? ['timeout_ms', 'instruction', 'cli', 'model', 'recovery_mode', 'surfaces', 'permissions', 'cwd', 'resume', 'transport', 'cli_identity'] as const
         : [];
   assertKernelKeys(step, [...commonKeys, ...typeKeys], at);
   const transportRetries = step['retry'] === undefined
@@ -516,7 +517,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
       instruction: step['instruction'],
       ...(step['timeout_ms'] === undefined ? {} : { timeoutMs: step['timeout_ms'] }),
       ...(step['recovery_mode'] !== undefined ? { recoveryMode: step['recovery_mode'] } : {}),
-      ...copyDefined(step, ['cli', 'model', 'surfaces', 'cwd', 'transport']),
+      ...copyDefined(step, ['cli', 'model', 'surfaces', 'cwd', 'resume', 'transport']),
       ...(step['permissions'] !== undefined
         ? { permissions: kernelPermissionsToAuthoring(step['permissions'], `${at}.permissions`) }
         : {}),
@@ -691,6 +692,7 @@ function toKernelStep(step: StepSpec, cliIdentity?: string): ResolvedKernelStepS
         ...(step.cli !== undefined ? { cli: step.cli } : {}),
         ...(step.model !== undefined ? { model: step.model } : {}),
         ...(step.cwd !== undefined ? { cwd: step.cwd } : {}),
+        ...(step.resume !== undefined ? { resume: step.resume } : {}),
         ...(step.transport !== undefined ? { transport: step.transport } : {}),
         recovery_mode: step.recoveryMode ?? 'reset',
       };

package/src/daemon-spec-validation.ts

@@ -0,0 +1,126 @@
+import { spawnSync } from 'node:child_process';
+import { canonicalize } from './canonical.js';
+import { CompileError, toKernelSpec } from './compile.js';
+import { PROTOCOL_VERSION } from './protocol.js';
+import { RelayflowdNotFoundError, resolveRelayflowdBinary } from './relayflowd-path.js';
+import type { FlowSpec } from './spec.js';
+import type { CheckReport } from './cli/check.js';
+
+export type DaemonValidationMode = 'auto' | 'required' | 'off';
+type Unavailable = 'disabled' | 'not_reached' | 'authored_body' | 'relayflowd_not_found'
+  | 'relayflowd_bin_invalid' | 'no_verdict' | 'spawn_failed' | 'timed_out' | 'protocol_mismatch' | 'abnormal_exit';
+export interface DaemonValidation {
+  mode: 'daemon' | 'local';
+  binary?: string;
+  protocol?: number;
+  specVersion?: string;
+  reason?: Unavailable;
+}
+export interface DaemonValidationDeps {
+  resolveBinary(): string;
+  run(binary: string, input: string): {
+    status: number | null; signal?: NodeJS.Signals | null; stdout: string; stderr: string; error?: Error;
+  };
+}
+type Result = { validation: DaemonValidation; diagnostics: CheckReport['diagnostics'] };
+// Cache discovery, never verdicts. Changed resolution inputs get a fresh lookup.
+const binaries = new Map<string, string | Error>();
+const defaults: DaemonValidationDeps = {
+  resolveBinary() {
+    const key = JSON.stringify([process.env['RELAYFLOWD_BIN'], process.env['PATH'], process.cwd(), process.argv[1]]);
+    let found = binaries.get(key);
+    if (found === undefined) {
+      try { found = resolveRelayflowdBinary(); }
+      catch (error) { found = error instanceof Error ? error : new Error(String(error)); }
+      binaries.set(key, found);
+    }
+    if (found instanceof Error) throw found;
+    return found;
+  },
+  run: (binary, input) => spawnSync(binary, ['validate-spec'], {
+    input, encoding: 'utf8', timeout: 5000, killSignal: 'SIGKILL', maxBuffer: 1024 * 1024,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }),
+};
+
+export function unavailableValidation(
+  mode: DaemonValidationMode, reason: Unavailable, detail = '', binary?: string,
+): Result {
+  const message = `${binary === undefined ? 'relayflowd' : `relayflowd at ${binary}`}: ${detail || reason.replaceAll('_', ' ')}. `
+    + 'Daemon acceptance is unproven; an already attached daemon from another build is not checked.';
+  return {
+    validation: { mode: 'local', reason, ...(binary === undefined ? {} : { binary }) },
+    diagnostics: mode === 'required'
+      ? [{ severity: 'refusal', kind: 'daemon_validation_unavailable', message }]
+      : reason === 'disabled' || reason === 'not_reached' || reason === 'relayflowd_not_found'
+        ? [] : [{ severity: 'warning', kind: 'daemon_unvalidated', message }],
+  };
+}
+
+/** Same spec value run.start submits, in canonical form; no socket or run. */
+export function validateSpecWithDaemon(
+  flow: FlowSpec, mode: DaemonValidationMode, deps: DaemonValidationDeps = defaults,
+): Result {
+  if (mode === 'off') return unavailableValidation(mode, 'disabled');
+  let submitted: ReturnType<typeof toKernelSpec>;
+  let input: string;
+  try { submitted = toKernelSpec(flow); input = canonicalize(submitted); }
+  catch (error) {
+    // run refuses this lowering too: degrading to local would fail open.
+    const errors = error instanceof CompileError ? error.errors : [String(error)];
+    return { validation: { mode: 'local', reason: 'not_reached' },
+      diagnostics: [{ severity: 'refusal', kind: 'invalid_spec', message: errors.join('; '), errors }] };
+  }
+  let binary: string;
+  try { binary = deps.resolveBinary(); }
+  catch (error) {
+    const reason = error instanceof RelayflowdNotFoundError
+      ? error.attempts[0]?.startsWith('RELAYFLOWD_BIN=') ? 'relayflowd_bin_invalid' : 'relayflowd_not_found'
+      : 'spawn_failed';
+    return unavailableValidation(mode, reason, String(error));
+  }
+  try {
+    const result = deps.run(binary, input);
+    if (result.error) return unavailableValidation(mode,
+      (result.error as NodeJS.ErrnoException).code === 'ETIMEDOUT' ? 'timed_out' : 'spawn_failed', result.error.message, binary);
+    let verdict: unknown;
+    try { verdict = JSON.parse(result.stdout); } catch { /* Old binaries have no envelope. */ }
+    if (!isVerdict(verdict)) return unavailableValidation(mode, 'no_verdict',
+      'no validation verdict (the binary may predate validate-spec)', binary);
+    if (verdict.protocol !== PROTOCOL_VERSION) return unavailableValidation(mode, 'protocol_mismatch',
+      `validator protocol ${verdict.protocol}, SDK protocol ${PROTOCOL_VERSION}`, binary);
+    const validation: DaemonValidation = { mode: 'daemon', binary,
+      protocol: verdict.protocol, specVersion: verdict.spec_version };
+    if (verdict.ok) {
+      // Acceptance is the envelope AND exit 0; a validator that fails or is
+      // killed after printing it has not completed validation.
+      if (result.status !== 0) return unavailableValidation(mode, 'abnormal_exit',
+        `validator ${result.status === null ? `was terminated by ${result.signal ?? 'a signal'}` : `exited ${result.status}`} after an accepting verdict`, binary);
+      return { validation, diagnostics: [] };
+    }
+    // A refusal fails closed whatever the exit status, so it is reported as-is.
+    const message = verdict.error.message;
+    const index = /steps\[(\d+)\]/.exec(message)?.[1];
+    const stepId = index === undefined ? undefined : submitted.steps[Number(index)]?.id;
+    const generated = stepId !== undefined && !flow.steps.some(step => step.id === stepId);
+    return { validation, diagnostics: [{ severity: 'refusal', kind: 'invalid_spec',
+      message: message + (generated ? `\nStep "${stepId}" is generated by this compiler's gate lowering, not declared in the flow; `
+        + 'the installed relayflowd and this @relayflows/sdk disagree (SDK lowering bug). Report this rather than editing the flow.' : ''),
+      errors: [message], ...(stepId === undefined ? {} : { stepId }) }] };
+  } catch (error) { return unavailableValidation(mode, 'spawn_failed', String(error), binary); }
+}
+
+type Verdict = { protocol: number; spec_version: string } &
+  ({ ok: true } | { ok: false; error: { code: 'invalid_spec'; message: string } });
+function isVerdict(value: unknown): value is Verdict {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Partial<Verdict>;
+  return Number.isInteger(v.protocol) && typeof v.spec_version === 'string'
+    && (v.ok === true || (v.ok === false && v.error?.code === 'invalid_spec' && typeof v.error.message === 'string'));
+}
+
+export function validationAnnotation(validation?: DaemonValidation): string {
+  return validation?.mode === 'daemon'
+    ? ` [validated by relayflowd at ${validation.binary}, protocol ${validation.protocol}]`
+    : ` [local only: ${(validation?.reason ?? 'not_reached').replaceAll('_', ' ')}, so daemon acceptance is unproven]`;
+}

package/src/failure-kinds.ts

@@ -48,7 +48,9 @@ export const CHECK_INPUT_FAILURE_KINDS = [
   ...SHARED_SPEC_FAILURE_KINDS,
 ] as const;
 
+// run never enables daemon validation; fromCheckReport needs a mapping if that changes.
 export const CHECK_FAILURE_KINDS = [
+  'daemon_validation_unavailable',
   ...CHECK_INPUT_FAILURE_KINDS,
   ...PREFLIGHT_ENVIRONMENT_FAILURE_KINDS,
 ] as const;
@@ -136,6 +138,14 @@ export const RUN_FAILURE_KINDS = [
   'gate_failed',
   /** `flows answer` named a wait the run is not asking: unknown, or already answered. */
   'human_wait_unknown',
+  /** `f.memory.learn` was given a finding without non-empty string fields. */
+  'memory_finding_invalid',
+  /** `f.memory.learn` could not persist the finding to script memory. */
+  'memory_unwritable',
+  /** `f.memory.learn` ran without a durable root run to journal the finding in. */
+  'memory_unjournaled',
+  /** `f.memory` lost its database, or found a damaged learned finding, after the run started. */
+  'memory_unreachable',
   /**
    * `--local-agent` cannot be honoured for this invocation, so it is refused
    * rather than accepted and ignored. A local agent worker is admitted at run
@@ -149,6 +159,7 @@ export const RUN_FAILURE_KINDS = [
    * reach this process. The run is NOT failed (`status: running`): its
    * completed steps are journaled and `flows resume <rootRunId>` continues it.
    */
+  'daemon_unresponsive',
   'root_lease_lost',
 ] as const;
 
@@ -160,6 +171,9 @@ export const RUN_FAILURE_KINDS = [
  */
 export const RUN_WARNING_KINDS = [
   'connection_file_stale',
+  'reuse_summary_unavailable',
+  'result_unreadable',
+  'inspection_interrupted',
 ] as const;
 
 /**
@@ -172,7 +186,9 @@ export const RUN_WARNING_KINDS = [
  * daemon-free, can see none either — so it opts in, while `flows run`, `flows
  * build` and SDK submissions do not (cli/check-worker-surface.ts).
  */
-export const CHECK_WARNING_KINDS = ['editor_schema_missing', 'agent_worker_unresolved'] as const;
+/** helper_credential_unresolved describes a local mount gap during inspection;
+ * Cloud validates workspace integrations at submit, and local execution refuses. */
+export const CHECK_WARNING_KINDS = ['editor_schema_missing', 'daemon_unvalidated', 'agent_worker_unresolved', 'helper_credential_unresolved'] as const;
 export type CheckWarningKind = (typeof CHECK_WARNING_KINDS)[number];
 
 export type PreflightFailureKind = (typeof PREFLIGHT_FAILURE_KINDS)[number];

package/src/flow-eval-cloud.ts

@@ -0,0 +1,114 @@
+// The Cloud executor for `evaluateFlow`: one fresh hosted run per case,
+// waited on, with its verdict read from the hosted run report and its spend
+// from the run's steps.
+
+import { getCloudRunSteps, type CloudStep } from './cloud-read.js';
+import { runInCloud, waitForCloudFlowRun, type RunInCloudOptions } from './cloud-run.js';
+import { cloudRunState } from './cloud-run-record.js';
+import { cloudRequest, isCloudRecord, type CloudConnectionOptions } from './cloud-http.js';
+import { isAuthoredFlowPath } from './direct-input.js';
+import type { FlowEvalExecutor, FlowEvalRun } from './flow-eval-report.js';
+import { runReportOutcome } from './flow-eval-outcome.js';
+import { flowEvalSources, isPathTarget, type FlowEvalTarget } from './flow-eval-version.js';
+
+const MODULE = /\.(?:[mc]?[jt]s)$/u;
+const EXTENSION_STORE = /(?:^|\/)\.flows\/plugins\//u;
+/** Manifests and locks the version pins but Cloud does not need as imports. */
+const PROJECT_METADATA = /(?:^|\/)(?:package(?:-lock)?|flows(?:\.lock)?)\.json$/u;
+
+/**
+ * Cloud receives the entry file's source alone (cloud-run.ts): a relative
+ * import is not resolved by the hosted runner, even with `syncCode`. A flow
+ * whose version spans local modules would therefore fail only on Cloud, or run
+ * something other than what was judged. Refuse it before submitting anything.
+ */
+async function refuseLocalImports(flow: FlowEvalTarget): Promise<void> {
+  if (!isPathTarget(flow) || !MODULE.test(flow.path)) return;
+  const { files } = await flowEvalSources(flow);
+  const entry = files.find(file => !file.includes('/') && flow.path.endsWith(file));
+  // Locked extension payloads are not imports: Cloud receives them separately
+  // (`extensions` in the submission), so they never make a flow non-self-contained.
+  const modules = files.filter(file => (MODULE.test(file) || /\.json$/u.test(file)) && file !== entry
+    && !EXTENSION_STORE.test(file) && !PROJECT_METADATA.test(file));
+  if (modules.length > 0) {
+    throw new Error(`Cloud evaluation runs the entry file alone, and this flow imports local modules (${modules.join(', ')}). `
+      + 'Evaluate it locally, or inline those modules.');
+  }
+}
+
+export interface CloudFlowEvalExecutorOptions extends CloudConnectionOptions {
+  workspaceId?: string;
+  syncCode?: RunInCloudOptions['syncCode'];
+  pollIntervalMs?: number;
+}
+
+/**
+ * Execute each case as a fresh hosted run and wait for it. Needs a token with
+ * `workflow:invoke:write` and `runs:read`; inside a Cloud step that means an
+ * injected workspace token, since a run-scoped sandbox token reads only its own run.
+ */
+export function cloudFlowEvalExecutor(options: CloudFlowEvalExecutorOptions = {}): FlowEvalExecutor {
+  return async ({ flow, input, signal }) => {
+    await refuseLocalImports(flow);
+    const connection: CloudConnectionOptions = {
+      ...(options.apiUrl === undefined ? {} : { apiUrl: options.apiUrl }),
+      ...(options.token === undefined ? {} : { token: options.token }),
+      ...(options.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: options.requestTimeoutMs }),
+      ...(signal === undefined ? {} : { signal }),
+    };
+    const receipt = await runInCloud(flow, {
+      ...connection,
+      ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+      ...(options.syncCode === undefined ? {} : { syncCode: options.syncCode }),
+      // Cloud requires an explicit input for authored source; `{}` is the
+      // documented "no fields", matching the local executor's default.
+      ...(input !== undefined ? { input } : 'path' in flow && isAuthoredFlowPath(flow.path) ? { input: {} } : {}),
+    });
+    await waitForCloudFlowRun(receipt.runId, {
+      ...connection, ...(options.pollIntervalMs === undefined ? {} : { pollIntervalMs: options.pollIntervalMs }),
+    });
+    // Re-read the terminal record for its stored report: the run state alone
+    // carries the kernel's reason, which says `success` for a declined body
+    // and has no completion detail.
+    const record = await cloudRequest(`/api/v1/workflows/runs/${receipt.runId}`, connection);
+    let steps: CloudStep[] | undefined;
+    try {
+      steps = await getCloudRunSteps(receipt.runId, connection);
+    } catch {
+      // As locally: spend is evidence, not the verdict.
+    }
+    return { runId: receipt.runId, ...cloudRunOutcome(record, receipt.runId), ...cloudSpend(steps) };
+  };
+}
+
+/**
+ * Map a terminal hosted run record onto the eval vocabulary: the validated run
+ * state decides parked/failed/canceled, and the stored report (the same
+ * RunReport a local run prints) supplies `declined` and the completion detail.
+ * Exported for tests.
+ */
+export function cloudRunOutcome(record: unknown, runId: string): Pick<FlowEvalRun, 'completionReason' | 'completionDetail'> {
+  const state = cloudRunState(record, runId);
+  const report = isCloudRecord(record) && isCloudRecord(record.result) ? record.result : {};
+  const mapped = runReportOutcome(report);
+  // A park with nothing attached to run it is the same fact on both sides.
+  if (mapped.completionReason === 'worker_unavailable') return mapped;
+  if (state.status === 'needs_human') return { ...mapped, completionReason: 'needs_human' };
+  if (!('completionReason' in state)) return { ...mapped, completionReason: state.status };
+  if (state.completionReason === 'success') return mapped.completionReason === 'declined' ? mapped : { ...mapped, completionReason: 'success' };
+  return { ...mapped, completionReason: state.completionReason };
+}
+
+/** Sum hosted step spend; any step with unknown cost makes the total unknown. Exported for tests. */
+export function cloudSpend(steps: readonly CloudStep[] | undefined): Pick<FlowEvalRun, 'costUsd' | 'tokensIn' | 'tokensOut' | 'steps'> {
+  if (steps === undefined) return { costUsd: null, tokensIn: null, tokensOut: null };
+  const known = (values: Array<number | null>): number | null =>
+    values.some(v => v === null || !Number.isFinite(v) || v < 0) ? null : values.reduce<number>((sum, v) => sum + v!, 0);
+  const costed = steps.filter(step => step.step_type === 'agent' || step.step_type === 'llm' || step.cost_usd !== null);
+  return {
+    costUsd: known(costed.map(step => step.cost_usd)),
+    tokensIn: known(costed.map(step => step.tokens_in)),
+    tokensOut: known(costed.map(step => step.tokens_out)),
+    steps: steps.map(step => ({ id: step.step_name, status: step.status, durationMs: step.duration_ms, costUsd: step.cost_usd })),
+  };
+}

package/src/flow-eval-error.ts

@@ -0,0 +1,10 @@
+export type FlowEvalErrorCode =
+  | 'invalid_suite' | 'invalid_baseline' | 'version_mismatch' | 'suite_mismatch' | 'invalid_options' | 'unreadable_flow';
+
+/** The evaluation itself is invalid. Case failures are verdicts in the report, never this. */
+export class FlowEvalError extends Error {
+  constructor(readonly code: FlowEvalErrorCode, message: string) {
+    super(message);
+    this.name = 'FlowEvalError';
+  }
+}

package/src/flow-eval-gate.ts

@@ -0,0 +1,114 @@
+// The verdict of a flow evaluation: case results aggregated into a summary,
+// and the summary judged against the suite's thresholds and a baseline.
+
+import { FlowEvalError } from './flow-eval-error.js';
+import type { FlowEvalCaseResult, FlowEvalOutcome, FlowEvalReport } from './flow-eval-report.js';
+import { isRecord, type FlowEvalSuite } from './flow-eval-suite.js';
+
+/** The part of a prior report a regression check reads, validated. */
+export interface FlowEvalBaseline {
+  suiteSha256: string;
+  outcomes: ReadonlyMap<string, FlowEvalOutcome>;
+}
+
+const OUTCOMES: readonly string[] = ['pass', 'fail', 'error'];
+
+/**
+ * Validate an untrusted prior report (parsed JSON) before any case runs, so a
+ * malformed baseline is refused before an evaluation spends anything.
+ */
+export function parseFlowEvalBaseline(value: unknown): FlowEvalBaseline {
+  const fail = (message: string): never => { throw new FlowEvalError('invalid_baseline', message); };
+  if (!isRecord(value) || value['kind'] !== 'flows.eval.report') fail('Baseline is not a flows eval report.');
+  const report = value as Record<string, unknown>;
+  const suite = report['suite'];
+  if (!isRecord(suite) || typeof suite['sha256'] !== 'string') fail('Baseline report names no suite sha256.');
+  if (!Array.isArray(report['cases'])) fail('Baseline report has no `cases` array.');
+  const outcomes = new Map<string, FlowEvalOutcome>();
+  for (const [index, entry] of (report['cases'] as unknown[]).entries()) {
+    if (!isRecord(entry) || typeof entry['id'] !== 'string' || !OUTCOMES.includes(entry['outcome'] as string)) {
+      fail(`Baseline cases[${index}] needs a string \`id\` and an \`outcome\` of pass, fail or error.`);
+    }
+    const item = entry as Record<string, unknown>;
+    if (outcomes.has(item['id'] as string)) fail(`Baseline case id "${item['id']}" is not unique.`);
+    outcomes.set(item['id'] as string, item['outcome'] as FlowEvalOutcome);
+  }
+  return { suiteSha256: (suite as Record<string, unknown>)['sha256'] as string, outcomes };
+}
+
+export function summarizeFlowEval(results: readonly FlowEvalCaseResult[]): FlowEvalReport['summary'] {
+  const passed = results.filter(r => r.outcome === 'pass').length;
+  const failed = results.filter(r => r.outcome === 'fail').length;
+  const errored = results.filter(r => r.outcome === 'error').length;
+  const costs = results.map(r => r.costUsd);
+  const latencies = results.map(r => r.latencyMs).sort((a, b) => a - b);
+  return {
+    total: results.length, passed, failed, errored,
+    passRate: results.length === 0 ? 0 : passed / results.length,
+    totalCostUsd: costs.some(c => c === null) ? null : fromNanos(sumNanos(costs as number[])),
+    latencyMs: { p50: percentile(latencies, 0.5), p95: percentile(latencies, 0.95), max: latencies.at(-1) ?? 0 },
+  };
+}
+
+export function decideFlowEvalGate(
+  suite: FlowEvalSuite,
+  results: readonly FlowEvalCaseResult[],
+  summary: FlowEvalReport['summary'],
+  baseline: FlowEvalBaseline | undefined,
+): FlowEvalReport['gate'] {
+  const reasons: string[] = [];
+  const thresholds = suite.thresholds ?? {};
+  const minPassRate = thresholds.minPassRate ?? 1;
+  if (summary.passRate < minPassRate) {
+    reasons.push(`pass rate ${formatRate(summary.passRate)} is below ${formatRate(minPassRate)} (${summary.passed}/${summary.total})`);
+  }
+  // Fails closed regardless of minPassRate: an errored case was never judged,
+  // so a tolerance for quality misses must not absorb it.
+  if (summary.errored > 0) reasons.push(`${summary.errored} case(s) errored before a verdict`);
+  if (thresholds.maxTotalCostUsd !== undefined) {
+    // Decimal, not binary: costs and the ceiling are compared in whole
+    // nanodollars, so 0.1 + 0.2 meets a 0.3 ceiling exactly and a total a
+    // fraction of a cent over it still fails. No display rounding is involved.
+    const costs = results.map(r => r.costUsd);
+    if (costs.some(c => c === null)) reasons.push(`total cost is unknown; the suite caps it at $${thresholds.maxTotalCostUsd}`);
+    else {
+      const total = sumNanos(costs as number[]);
+      if (total > toNanos(thresholds.maxTotalCostUsd)) {
+        reasons.push(`total cost $${fromNanos(total)} exceeds $${thresholds.maxTotalCostUsd}`);
+      }
+    }
+  }
+  if (thresholds.maxP95LatencyMs !== undefined && summary.latencyMs.p95 > thresholds.maxP95LatencyMs) {
+    reasons.push(`p95 latency ${summary.latencyMs.p95}ms exceeds ${thresholds.maxP95LatencyMs}ms`);
+  }
+  const regressions: string[] = [];
+  if (baseline !== undefined) {
+    for (const result of results) {
+      if (baseline.outcomes.get(result.id) === 'pass' && result.outcome !== 'pass') regressions.push(result.id);
+    }
+    if (regressions.length > 0) reasons.push(`${regressions.length} case(s) regressed against the baseline: ${regressions.join(', ')}`);
+  }
+  return { pass: reasons.length === 0, reasons, regressions };
+}
+
+function percentile(sorted: readonly number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1))]!;
+}
+
+/** Dollars as whole nanodollars: exact for any cost a run reports, far below a cent. */
+function toNanos(usd: number): bigint {
+  return BigInt(Math.round(usd * 1e9));
+}
+
+function sumNanos(costs: readonly number[]): bigint {
+  return costs.reduce((sum, cost) => sum + toNanos(cost), 0n);
+}
+
+function fromNanos(nanos: bigint): number {
+  return Number(nanos) / 1e9;
+}
+
+function formatRate(rate: number): string {
+  return `${Math.round(rate * 1000) / 10}%`;
+}