@relayflows/sdk 2.0.8 → 2.0.10

package/src/cli/build.ts

@@ -0,0 +1,214 @@
+import { readFile, lstat } from 'node:fs/promises';
+import { dirname, extname, join, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { sealBundle, verifyBundle, type BundleFile } from '../bundle.js';
+import { canonicalize } from '../canonical.js';
+import { compileSpec, toKernelSpec } from '../compile.js';
+import { preflight } from '../preflight.js';
+import { buildTypescript } from '../bundle-typescript.js';
+import { checkBuildableFlow, readProjectConfig, type CheckReport } from './check.js';
+import type { CliIo } from '../cli.js';
+import type { FlowSpec } from '../spec.js';
+
+export interface BuildArgs { command: 'build'; value: string; out?: string; verify: boolean; json: boolean }
+
+export function parseBuildArgs(args: readonly string[]): BuildArgs | undefined {
+  if (args[0] === '--verify') {
+    return args.length === 2 && !args[1]!.startsWith('-')
+      ? { command: 'build', value: args[1]!, verify: true, json: false } : undefined;
+  }
+  let out: string | undefined;
+  let value: string | undefined;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--out') {
+      if (out !== undefined || args[i + 1] === undefined || args[i + 1]!.startsWith('-')) return undefined;
+      out = args[++i];
+    } else if (arg === '--json') {
+      if (json) return undefined;
+      json = true;
+    } else if (arg.startsWith('-') || value !== undefined) return undefined;
+    else value = arg;
+  }
+  return value === undefined ? undefined : { command: 'build', value, out, verify: false, json };
+}
+
+/**
+ * Emit a check report in the same shape `flows check` uses so build-time
+ * refusals are consumable by the same tooling.
+ */
+function emitBuildCheckReport(report: CheckReport, json: boolean, io: CliIo): void {
+  for (const diagnostic of report.diagnostics) {
+    if (diagnostic.severity !== 'refusal') continue;
+    io.stderr(`REFUSED [${diagnostic.kind}] ${diagnostic.message}`);
+  }
+  if (json) io.stdout(JSON.stringify(report));
+}
+
+export async function runBuild(args: BuildArgs, io: CliIo): Promise<0 | 2> {
+  try {
+    if (args.verify) {
+      io.stdout(`VERIFIED sha256:${await verifyBundle(args.value)}`);
+      return 0;
+    }
+    // Gate the build on the same preflight pipeline `flows check` uses.
+    // Refusals never leave partial artifacts — no file capture, no canonical
+    // spec write, no digest computation, no bundle directory creation. A
+    // previous `dist/flows/<name>@sha256:<hex>/` directory from an earlier
+    // successful build is not touched (buildFlow is never called).
+    const gate = await checkBuildableFlow(args.value);
+    if (!gate.report.ok) {
+      emitBuildCheckReport(gate.report, args.json, io);
+      return 2;
+    }
+    io.stdout(await buildFlow(args.value, args.out ?? 'dist/flows', io.stderr));
+    return 0;
+  } catch (error) {
+    io.stderr(`REFUSED [bundle_invalid] ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}
+
+/** Build checks never probe credentials, workers, or the author's PATH. */
+export async function buildFlow(path: string, out: string, warn: (line: string) => void): Promise<string> {
+  const input = resolve(path);
+  const directory = dirname(input);
+  const files: BundleFile[] = [];
+  let authoring: FlowSpec;
+  let authored = false;
+  let compiler: string | undefined;
+  if (extname(input) === '.ts') {
+    const result = await buildTypescript(input);
+    authoring = result.spec;
+    authored = result.authored;
+    compiler = result.compiler;
+    files.push(...result.files);
+  } else if (['.yaml', '.yml'].includes(extname(input))) {
+    authoring = compileSpec(parse(await readFile(input, 'utf8')));
+    files.push({ path: 'lockfile.json', data: canonicalize({ version: 1, adapters: [] }) });
+  } else throw new Error('build expects a .yaml, .yml, or .ts flow');
+
+  // The current preflight API reports uncollected environment facts as
+  // probe_failed. Preserve that truthful report verbatim and separately declare
+  // the deployment obligations; never manufacture successful auth probes.
+  //
+  // Load the nearest flows.json so declared model allowlists and the project
+  // CLI participate in build-time preflight. Without them a declared `model:`
+  // that appears in flows.json/models refuses the whole build as
+  // `model_unknown`, because preflight defaults treat "no registry" as "no
+  // model is known" and only environment probes (deferred here) would rescue
+  // it. Model existence is a build-provable fact; only the live probe is not.
+  const config = readProjectConfig(directory);
+  const report = preflight(authoring, {
+    ...(config.cli !== undefined ? { projectCli: config.cli } : {}),
+    ...(config.path !== undefined ? { projectConfigPath: config.path } : {}),
+    projectSearchStart: directory,
+    models: config.models,
+    ...(config.path !== undefined ? { modelRegistryPath: config.path } : {}),
+    probes: {
+      cli: () => { throw new Error('deferred to deployment'); },
+      executor: () => { throw new Error('deferred to deployment'); },
+      command: () => { throw new Error('deferred to deployment'); },
+    },
+  });
+  const refusals = report.diagnostics.filter(d => d.severity === 'refusal' && d.kind !== 'probe_failed');
+  if (refusals.length > 0) throw new Error(refusals.map(d => `[${d.kind}] ${d.message}`).join('\n'));
+  authoring = await captureFiles(authoring, directory, files);
+  files.push(
+    { path: 'spec.canonical.json', data: canonicalize(toKernelSpec(authoring)) },
+    { path: 'preflight.json', data: canonicalize(report) },
+    { path: 'metadata.json', data: canonicalize({
+      version: 1, platform: { os: process.platform, arch: process.arch },
+      executables: files.filter(file => file.path === 'flow' || file.executable).map(file => file.path).sort(),
+      kind: authored ? 'authored-typescript' : 'declarative',
+      ...(compiler === undefined ? {} : { compiler }),
+      preflight: { buildPassed: true, deferred: ['commands', 'credentials', 'workers', 'mcp_servers'],
+        ...(authored ? { dynamicSteps: 'exported spec declaration checked; body was not executed during build' } : {}) },
+    }) },
+  );
+  return sealBundle({ name: authoring.name ?? 'flow', out, files,
+    repo: await repositoryRoot(directory), warn });
+}
+
+async function repositoryRoot(start: string): Promise<string> {
+  for (let dir = start; ; dir = dirname(dir)) {
+    try { await lstat(join(dir, '.git')); return dir; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    if (dirname(dir) === dir) return start;
+  }
+}
+
+/** Relative CLI executables are the file references in the current spec schema.
+ * Shell commands are opaque; explicit ./file words are captured without
+ * interpreting substitutions or running a shell at build time. */
+async function captureFiles(flow: FlowSpec, directory: string, files: BundleFile[]): Promise<FlowSpec> {
+  // Cache the in-flight *promise*, not the resolved string. Two concurrent
+  // captures of the same path (Promise.all over named agents that share a CLI)
+  // both pass a `captured.has(path)` guard before either has finished awaiting
+  // its lstat/readFile, so both would push the same `assets/...` entry -- and
+  // sealBundle then refuses the whole flow as a duplicate. Storing the promise
+  // dedups on the first synchronous look-up.
+  const captured = new Map<string, Promise<string>>();
+  function capture(path: string): Promise<string> {
+    if (!path.includes('/')) return Promise.resolve(path);
+    if (!path.startsWith('./') || path.split('/').includes('..') || path.includes('\\')) {
+      return Promise.reject(new Error(`${path}: bundle file references must start with ./ and stay inside the flow directory`));
+    }
+    const existing = captured.get(path);
+    if (existing !== undefined) return existing;
+    const pending = (async () => {
+      const parts = path.slice(2).split('/');
+      if (parts.some(p => p === '' || p === '.')) throw new Error(`${path}: invalid file reference`);
+      let executable = false;
+      for (let i = 1; i <= parts.length; i++) {
+        const stat = await lstat(join(directory, ...parts.slice(0, i)));
+        if (i === parts.length ? !stat.isFile() : !stat.isDirectory()) throw new Error(`${path}: expected regular file without symlinks`);
+        if (i === parts.length) executable = (stat.mode & 0o111) !== 0;
+      }
+      const target = `assets/${parts.join('/')}`;
+      files.push({ path: target, data: await readFile(join(directory, ...parts)), executable });
+      return `./${target}`;
+    })();
+    captured.set(path, pending);
+    return pending;
+  }
+  // Capture the flow-level `cli` default and every named-agent `cli` BEFORE
+  // walking steps. Otherwise a step that inherits its CLI from the flow header
+  // or an agents-map entry never emits its own `cli`, so the step-level walk
+  // below misses it, the executable never enters the bundle, and the sealed
+  // spec still points at the author's absolute path outside the bundle.
+  const flowCli = flow.cli !== undefined ? await capture(flow.cli) : undefined;
+  const agents: FlowSpec['agents'] = flow.agents === undefined ? undefined
+    : Object.fromEntries(await Promise.all(Object.entries(flow.agents).map(
+        async ([name, agent]) => [name, { ...agent, cli: await capture(agent.cli) }] as const,
+      )));
+  const compiled = toKernelSpec(flow);
+  // Lower named/flow CLI resolution first so every runtime reference is bound.
+  const steps: FlowSpec['steps'] = [];
+  for (const [index, step] of flow.steps.entries()) {
+    if (step.type !== 'deterministic') {
+      const lowered = compiled.steps[index];
+      const cli = lowered && lowered.type !== 'deterministic' ? lowered.cli : undefined;
+      steps.push(cli === undefined ? step : { ...step, cli: await capture(cli) });
+      continue;
+    }
+    let command = step.command;
+    const references = [...command.matchAll(/(?:^|[\s;|&<>])(?:"(\.\/[^"$`]+)"|'(\.\/[^']+)'|(\.\/[^\s;|&<>"'$`]+))/g)];
+    // Replace only each complete matched word, from right to left so offsets
+    // stay valid and similarly prefixed filenames cannot rewrite one another.
+    for (const match of references.reverse()) {
+      const ref = (match[1] ?? match[2] ?? match[3])!;
+      const start = match.index! + match[0].indexOf(ref);
+      command = command.slice(0, start) + await capture(ref) + command.slice(start + ref.length);
+    }
+    if (/^\s*["']?\//.test(command)) throw new Error(`${step.id}: absolute command paths cannot be bundled`);
+    steps.push({ ...step, command });
+  }
+  return {
+    ...flow,
+    ...(flowCli !== undefined ? { cli: flowCli } : {}),
+    ...(agents !== undefined ? { agents } : {}),
+    steps,
+  };
+}

package/src/cli/bundle-preflight.ts

@@ -0,0 +1,28 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BundleFailure } from '../bundle-transport.js';
+import { compileSpec, kernelToAuthoring } from '../compile.js';
+import { checkAuthoredFlow, type CheckExecution } from './check.js';
+
+/** Refuse unsupported execution: a TS declaration is not its body, and
+ * daemon-relative assets must never resolve in an unrelated checkout. */
+export async function checkRunnableBundle(directory: string, name: string): Promise<CheckExecution> {
+  const metadata = JSON.parse(await readFile(join(directory, 'metadata.json'), 'utf8'));
+  const manifest = JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8')) as { path: string }[];
+  const flow = compileSpec(kernelToAuthoring(JSON.parse(await readFile(join(directory, 'spec.canonical.json'), 'utf8'))));
+  if (flow.name !== undefined && flow.name !== name) throw new BundleFailure('bundle_signature_invalid', 'Bundle name does not match the requested flow.');
+  flow.name ??= name;
+  if (metadata.kind !== 'declarative' || flow.steps.some(step => step.type !== 'deterministic'
+      || step.requirements !== undefined) || (flow.triggers?.length ?? 0) > 0
+      || manifest.some(entry => entry.path.startsWith('assets/'))) {
+    throw new BundleFailure('bundle_unsupported',
+      'This slice runs declarative deterministic bundles without assets, placement requirements, or triggers.');
+  }
+  // Keep existing fail-closed environment checks before transport/journal.
+  // Splitting static and environment checks is follow-up.
+  // This deterministic-only slice declares no project models or executors.
+  // Never discover flows.json in the deployment/cache tree or its ancestors.
+  return checkAuthoredFlow(flow, join(directory, 'spec.canonical.json'), {
+    directory, models: [], executors: [],
+  });
+}

package/src/cli/check-helper-body.ts

@@ -0,0 +1,14 @@
+import { loadAuthoredFlow } from '../authored-flow-loader.js';
+import { checkSlackHelpers } from '../slack-preflight.js';
+import { inputFailureReport, type CheckExecution } from './check.js';
+
+/** Imports the definition, but never executes arbitrary authored body code. */
+export async function checkHelperBody(path: string): Promise<CheckExecution> {
+  try {
+    const { handle, getDefinition } = await loadAuthoredFlow(path);
+    return { report: { ...checkSlackHelpers(getDefinition(handle)), path } };
+  } catch (error) {
+    return { report: inputFailureReport({ kind: 'invalid_spec',
+      message: error instanceof Error ? error.message : 'Could not import authored flow.' }, path) };
+  }
+}

package/src/cli/check-triggers.ts

@@ -0,0 +1,41 @@
+import { dirname, resolve } from 'node:path';
+import { loadAuthoredFlow, type LoadedAuthoredFlow } from '../authored-flow-loader.js';
+import { preflightWebhookTriggers } from '../preflight.js';
+import { checkSlackHelpers } from '../slack-preflight.js';
+import { inputFailureReport, readProjectConfig, type CheckReport } from './check.js';
+
+/**
+ * Inspect an authored flow without running a handler or contacting the daemon.
+ * Combines the two authored-only preflight paths that share a loaded flow: the
+ * webhook-trigger check (E) and the f.slack helper check (B). Skipping either
+ * turned this into a silent trapdoor -- a `.flow.ts` using `f.slack.post`
+ * without a token would pass `flows check` and only crash at run.
+ */
+export async function checkAuthoredTriggers(path: string): Promise<{
+  report: CheckReport;
+  loaded?: LoadedAuthoredFlow;
+}> {
+  try {
+    const loaded = await loadAuthoredFlow(path);
+    const definition = loaded.getDefinition(loaded.handle);
+    const config = readProjectConfig(dirname(resolve(path)));
+    const triggerDiagnostics = preflightWebhookTriggers(
+      (definition.handlers ?? []).map(handler => handler.trigger), config.executors,
+    );
+    const helperReport = checkSlackHelpers(definition);
+    const diagnostics = [...triggerDiagnostics, ...helperReport.diagnostics];
+    return {
+      loaded,
+      report: {
+        ok: diagnostics.length === 0, path, gates: [], resolutions: [], diagnostics,
+        ...(config.path === undefined ? {} : { projectConfigPath: config.path }),
+      },
+    };
+  } catch (error) {
+    return { report: inputFailureReport({
+      kind: typeof error === 'object' && error !== null && 'kind' in error && error.kind === 'config_invalid'
+        ? 'config_invalid' : 'invalid_spec',
+      message: error instanceof Error ? error.message : 'Cannot inspect authored triggers',
+    }, path) };
+  }
+}

package/src/cli/check-typescript.ts

@@ -0,0 +1,63 @@
+import type { LoadedPlugin } from '../plugin-loader.js';
+import { dirname, resolve } from 'node:path';
+import type { AuthoredFlowDefinition } from '../authored-flow.js';
+import { loadAuthoredFlow } from '../authored-flow-loader.js';
+import { preflight } from '../preflight.js';
+import { SPEC_SCHEMA_VERSION, type McpServerConfig } from '../spec.js';
+import { inputFailureReport, readProjectConfig, type CheckReport } from './check.js';
+
+export interface CheckedMcp {
+  plugins?: readonly LoadedPlugin[];
+  report: CheckReport;
+  servers: Readonly<Record<string, McpServerConfig>>;
+  inventory: Readonly<Record<string, readonly string[]>>;
+}
+
+export async function checkTypeScriptFlow(path: string): Promise<{ report: CheckReport }> {
+  try {
+    const { handle, getDefinition } = await loadAuthoredFlow(path);
+    return await checkMcpHeader(getDefinition(handle), path);
+  } catch (error) {
+    return { report: inputFailureReport({ kind: 'invalid_spec', message: (error as Error).message }, path) };
+  }
+}
+
+/** Check declarations without executing the authored body. */
+export async function checkMcpHeader(
+  definition: Pick<AuthoredFlowDefinition, 'name' | 'header'>,
+  path: string,
+): Promise<CheckedMcp> {
+  const empty = { servers: Object.freeze({}), inventory: Object.freeze({}) };
+  const KNOWN_HEADER_FIELDS = new Set(['tools', 'budget', 'identity', 'memory', 'workspace', 'use']);
+  const header = definition.header ?? {};
+  const unsupported = Object.keys(header).filter(key => !KNOWN_HEADER_FIELDS.has(key));
+  if (header.tools?.relayfile !== undefined) unsupported.push('tools.relayfile');
+  if (unsupported.length) {
+    return { ...empty, report: inputFailureReport({ kind: 'invalid_spec',
+      message: `flow "${definition.name}" uses unsupported header fields: ${unsupported.join(', ')}` }, path) };
+  }
+  try {
+    const config = readProjectConfig(dirname(resolve(path)));
+    const result = await preflight({ version: SPEC_SCHEMA_VERSION, name: definition.name,
+      steps: [{ id: 'header', type: 'deterministic', command: ':' }] }, {
+      pluginSearchStart: dirname(resolve(path)),
+      mcpServers: header.tools?.mcp ?? [], mcp: config.mcp,
+      probes: { command: () => true, cli: () => { throw new Error('no CLI declared'); }, executor: () => false },
+    });
+    return {
+      plugins: result.plugins,
+      servers: config.mcp ?? empty.servers,
+      inventory: result.mcpTools ?? empty.inventory,
+      report: { ...result, path, projectConfigPath: config.path, gates: [],
+        diagnostics: result.diagnostics.filter(d => d.stepId !== 'header') },
+    };
+  } catch (error) {
+    return { ...empty, report: inputFailureReport({ kind: 'config_invalid', message: (error as Error).message }, path) };
+  }
+}
+
+export class McpPreflightError extends Error {
+  constructor(readonly report: CheckReport) {
+    super(report.diagnostics.map(d => d.message).join('; '));
+  }
+}

package/src/cli/check.ts

@@ -3,6 +3,7 @@ import { dirname, isAbsolute, join, parse as parsePath, resolve } from 'node:pat
 import { spawnSync } from 'node:child_process';
 import { parse as parseYaml } from 'yaml';
 import { CompileError, compileSpec, kernelToAuthoring } from '../compile.js';
+import { helperReady } from '../yaml-helper-effect.js';
 import {
   adapterIdentification,
   authenticationProbe,
@@ -14,8 +15,10 @@ import {
 import { MODEL_ENV } from '../worker-cli.js';
 import { modelNameError } from '../model-name.js';
 import type { FlowSpec } from '../spec.js';
+import type { McpServerConfig } from '../spec.js';
+import { parseMcpConfig } from '../mcp-config.js';
 import type { StepGateInspection } from '../gate-contract.js';
-import type { CheckFailureKind } from '../failure-kinds.js';
+import type { CheckFailureKind, CheckWarningKind } from '../failure-kinds.js';
 import {
   preflight,
   CliProbeError,
@@ -25,7 +28,9 @@ import {
   type PreflightProbes,
 } from '../preflight.js';
 
-interface ProjectConfig {
+export interface ProjectConfig {
+  deploy?: { bucket: string };
+  mcp?: Record<string, McpServerConfig>;
   cli?: string;
   executors: string[];
   models: string[];
@@ -34,12 +39,19 @@ interface ProjectConfig {
 }
 
 export interface CheckReport {
+  mcpTools?: Readonly<Record<string, readonly string[]>>;
   ok: boolean;
   path?: string;
   projectConfigPath?: string;
   gates: StepGateInspection[];
   resolutions: CliResolution[];
-  diagnostics: Array<PreflightDiagnostic | CheckInputDiagnostic>;
+  diagnostics: Array<PreflightDiagnostic | CheckInputDiagnostic | CheckWarningDiagnostic>;
+}
+
+export interface CheckWarningDiagnostic {
+  severity: 'warning';
+  kind: CheckWarningKind;
+  message: string;
 }
 
 export interface CheckInputDiagnostic {
@@ -53,7 +65,7 @@ export interface CheckExecution {
   flow?: FlowSpec;
 }
 
-class CheckFailure extends Error {
+export class CheckFailure extends Error {
   constructor(readonly kind: CheckFailureKind, message: string) {
     super(message);
   }
@@ -63,8 +75,25 @@ class CheckFailure extends Error {
 export function checkFlow(path: string): CheckExecution {
   const absolutePath = resolve(path);
   try {
-    const flow = readFlow(absolutePath);
-    return checkAuthoredFlow(flow, path);
+    const source = readFlowSource(absolutePath);
+    const hint = path.endsWith('.flow.yaml') && !/^\uFEFF?[ \t]*# yaml-language-server:/.test(source)
+      ? [{ severity: 'warning' as const, kind: 'editor_schema_missing' as const,
+          message: 'For editor validation, add this first line: # yaml-language-server: $schema=https://schema.relayflows.dev/v0.1/flows.schema.json' }]
+      : [];
+    let execution: CheckExecution;
+    try {
+      execution = checkAuthoredFlow(readFlow(source, absolutePath), path);
+    } catch (error) {
+      if (!(error instanceof CheckFailure)) throw error;
+      execution = { report: inputFailureReport(error, path) };
+    }
+    // The editor-schema hint is a documentation nudge, emitted for every
+    // .flow.yaml without a first-line yaml-language-server comment.
+    // Firing it even when a refusal is present is deliberate: an editor
+    // showing squiggles on this file should still tell the author how to
+    // wire the schema, so the next edit gets real-time feedback.
+    execution.report.diagnostics.push(...hint);
+    return execution;
   } catch (error) {
     const failure = error instanceof CheckFailure
       ? error
@@ -74,10 +103,10 @@ export function checkFlow(path: string): CheckExecution {
 }
 
 /** Preflight a validated authored flow through the same path as YAML/JSON. */
-export function checkAuthoredFlow(authoring: FlowSpec, path: string): CheckExecution {
+export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConfig?: ProjectConfig): CheckExecution {
   const absolutePath = resolve(path);
   try {
-    const config = readProjectConfig(dirname(absolutePath));
+    const config = projectConfig ?? readProjectConfig(dirname(absolutePath));
     const probes = systemProbes(dirname(absolutePath), config);
     const result = preflight(authoring, {
       projectCli: config.cli,
@@ -114,6 +143,72 @@ export function checkAuthoredFlow(authoring: FlowSpec, path: string): CheckExecu
   }
 }
 
+/**
+ * Build-time gate that runs the same preflight pipeline as `checkFlow`
+ * but with deferred probes — a build machine is not the deployment target,
+ * so `cli`/`command`/`executor` existence is checked at run-time, not here.
+ *
+ * "Build-provable" refusals (unknown model, `use:` unresolved, invalid
+ * verification, missing bundle assets, budget syntax, etc.) still surface,
+ * because they are properties of the flow spec, not of the build host.
+ */
+export async function checkBuildableFlow(path: string): Promise<CheckExecution> {
+  const absolutePath = resolve(path);
+  try {
+    const authored = /\.(?:[cm]?[jt]s)$/.test(path);
+    if (authored) {
+      // TS flows are gated by `buildFlow` itself, which runs
+      // `buildTypescript` to compile the authored spec and then invokes
+      // preflight with deferred probes at the same refusal threshold as
+      // this gate. Running `checkTypeScriptFlow` here would need
+      // `@relayflows/surface` to be resolvable from the flow's directory,
+      // which is not a build-time invariant. Return an ok report so the
+      // gate delegates to `buildFlow`'s inline preflight.
+      return {
+        report: { ok: true, path, gates: [], resolutions: [], diagnostics: [] },
+      };
+    }
+    const source = readFlowSource(absolutePath);
+    const authoring: FlowSpec = readFlow(source, absolutePath);
+    const config = readProjectConfig(dirname(absolutePath));
+    const deferred: PreflightProbes = {
+      cli: () => { throw new Error('deferred to deployment'); },
+      executor: () => { throw new Error('deferred to deployment'); },
+      command: () => { throw new Error('deferred to deployment'); },
+    };
+    const result = preflight(authoring, {
+      ...(config.cli !== undefined ? { projectCli: config.cli } : {}),
+      ...(config.path !== undefined ? { projectConfigPath: config.path } : {}),
+      projectSearchStart: dirname(absolutePath),
+      models: config.models,
+      ...(config.path !== undefined ? { modelRegistryPath: config.path } : {}),
+      probes: deferred,
+    });
+    // Refusals rooted in build-machine environment probes (`probe_failed`)
+    // are excluded from the build gate — the build host is not the
+    // deployment target, and those checks are re-run at `flows run`.
+    const diagnostics = result.diagnostics.filter(
+      (d) => !(d.severity === 'refusal' && d.kind === 'probe_failed'),
+    );
+    const ok = !diagnostics.some((d) => d.severity === 'refusal');
+    return {
+      report: {
+        ok,
+        path,
+        ...(config.path !== undefined ? { projectConfigPath: config.path } : {}),
+        gates: result.gates,
+        resolutions: result.resolutions,
+        diagnostics,
+      },
+    };
+  } catch (error) {
+    const failure = error instanceof CheckFailure
+      ? error
+      : new CheckFailure('invalid_spec', `Flow "${path}" could not be checked as a Relayflow spec.`);
+    return { report: inputFailureReport(failure, path) };
+  }
+}
+
 export function inputFailureReport(
   failure: { kind: CheckFailureKind; message: string },
   path?: string,
@@ -127,14 +222,15 @@ export function inputFailureReport(
   };
 }
 
-function readFlow(path: string): FlowSpec {
-  let source: string;
+function readFlowSource(path: string): string {
   try {
-    source = readFileSync(path, 'utf8');
+    return readFileSync(path, 'utf8');
   } catch {
     throw new CheckFailure('input_unreadable', `Flow "${path}" is not readable.`);
   }
+}
 
+function readFlow(source: string, path: string): FlowSpec {
   let parsed: unknown;
   try {
     parsed = parseYaml(source);
@@ -161,7 +257,7 @@ function readFlow(path: string): FlowSpec {
   }
 }
 
-function readProjectConfig(start: string): ProjectConfig {
+export function readProjectConfig(start: string): ProjectConfig {
   const configPath = findConfig(start);
   if (configPath === undefined) return { executors: [], models: [], directory: start };
   let value: unknown;
@@ -170,8 +266,16 @@ function readProjectConfig(start: string): ProjectConfig {
   } catch {
     throw new CheckFailure('config_invalid', `Project config "${configPath}" is not valid JSON.`);
   }
-  if (!isObject(value) || Object.keys(value).some((key) => !['cli', 'executors', 'models'].includes(key))) {
-    throw new CheckFailure('config_invalid', `Project config "${configPath}" expects only cli, executors, and models.`);
+  if (!isObject(value) || Object.keys(value).some((key) => !['cli', 'executors', 'models', 'mcp', 'deploy', 'plugins'].includes(key))) {
+    throw new CheckFailure('config_invalid', `Project config "${configPath}" expects only cli, executors, models, mcp, deploy, and plugins.`);
+  }
+  if (value['deploy'] !== undefined && (!isObject(value['deploy'])
+    || Object.keys(value['deploy']).some(key => key !== 'bucket')
+    || !isNonEmptyString(value['deploy']['bucket']))) {
+    throw new CheckFailure('config_invalid', `Project config "${configPath}" has invalid deploy.bucket.`);
+  }
+  if (value['plugins'] !== undefined && (!Array.isArray(value['plugins']) || !value['plugins'].every(isNonEmptyString))) {
+    throw new CheckFailure('config_invalid', 'Project plugins must be package names.');
   }
   if (value['cli'] !== undefined && !isNonEmptyString(value['cli'])) {
     throw new CheckFailure('config_invalid', `Project config "${configPath}" has an invalid cli.`);
@@ -193,7 +297,20 @@ function readProjectConfig(start: string): ProjectConfig {
       throw new CheckFailure('config_invalid', `Project config "${configPath}" has duplicate models.`);
     }
   }
+  let mcp: Record<string, McpServerConfig> | undefined;
+  if (value['mcp'] !== undefined) {
+    try { mcp = parseMcpConfig(value['mcp']); }
+    catch (error) {
+      throw new CheckFailure('config_invalid', `Project config "${configPath}": ${(error as Error).message}.`);
+    }
+    for (const entry of Object.values(mcp)) {
+      if ('command' in entry) entry.command = resolveExecutable(entry.command, dirname(configPath))
+        ?? canonicalCli(entry.command, dirname(configPath));
+    }
+  }
   return {
+    ...(value['deploy'] !== undefined ? { deploy: value['deploy'] as { bucket: string } } : {}),
+    ...(mcp !== undefined ? { mcp } : {}),
     ...(value['cli'] !== undefined ? { cli: value['cli'] as string } : {}),
     executors: (value['executors'] as string[] | undefined) ?? [],
     models: (value['models'] as string[] | undefined) ?? [],
@@ -220,6 +337,7 @@ function findConfig(start: string): string | undefined {
 
 function systemProbes(flowDirectory: string, config: ProjectConfig): PreflightProbes {
   return {
+    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),

package/src/cli/cloud-run.ts

@@ -0,0 +1,47 @@
+import { CloudFlowError } from '../cloud-http.js';
+import { runInCloud, waitForCloudFlowRun } from '../cloud-run.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 },
+  io: CliIo,
+): Promise<0 | 1 | 2> {
+  const controller = new AbortController();
+  const abort = (): void => controller.abort();
+  process.once('SIGINT', abort);
+  process.once('SIGTERM', abort);
+  let runId: string | undefined;
+  try {
+    const receipt = await runInCloud({ path }, { signal: controller.signal });
+    runId = receipt.runId;
+    if (!json) {
+      io.stdout(`ACCEPTED ${receipt.runId} (${receipt.status})`);
+      io.stdout(receipt.apiUrl);
+    }
+    if (!wait) {
+      if (json) io.stdout(JSON.stringify({ ok: true, ...receipt }));
+      return 0;
+    }
+    const run = await waitForCloudFlowRun(receipt.runId, { signal: controller.signal });
+    const ok = run.status === 'completed';
+    if (json) io.stdout(JSON.stringify({ ok, ...receipt, ...run }));
+    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')
+      : 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.'
+      : 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)
+        || (runId === undefined && error.code === 'http_error' && [401, 403].includes(error.status ?? 0))) ? 2 : 1;
+  } finally {
+    process.off('SIGINT', abort);
+    process.off('SIGTERM', abort);
+  }
+}