@relayflows/sdk 2.0.24 → 2.0.25

package/src/cli/plugin.ts

@@ -0,0 +1,286 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CliIo } from '../cli.js';
+import { diffExtension, extensionManifestOf } from './add-extension.js';
+import { assertCompatible, runtimeVersions, type RuntimeVersions } from '../flow-extension-compat.js';
+import { validateFlowExtensionManifest, type FlowExtensionManifest } from '../flow-extension-manifest.js';
+import { fetchGithubPlugin, resolveGithubSha, type FetchLike } from '../plugin-github.js';
+import {
+  PLUGIN_LOCK_FILE, lockForDeclared, lockWithPlugin, lockedPlugins, readPluginLock, reconcileDeclaredExtensions, recoverFlowsAndLock,
+  writeFlowsAndLock, type PluginLock, type PluginLockEntry,
+} from '../plugin-lock.js';
+import { findPluginProject } from '../plugin-loader.js';
+import { PluginError } from '../plugin-manifest.js';
+import { canonicalPluginRef, parsePluginSource } from '../plugin-source.js';
+import { materializePlugin, pluginStoreDirectory, removeStoredPlugin, verifyStoredPlugin } from '../plugin-store.js';
+
+export type PluginArgs =
+  | { command: 'plugin'; sub: 'list'; json: boolean }
+  | { command: 'plugin'; sub: 'verify'; json: boolean; offline: boolean }
+  | { command: 'plugin'; sub: 'remove'; json: boolean; name: string }
+  | { command: 'plugin'; sub: 'update'; json: boolean; yes: boolean; name: string | undefined; to: string | undefined };
+
+/** `flows plugin list|verify|remove|update` */
+export function parsePluginArgs(args: readonly string[]): PluginArgs | undefined {
+  const [sub, ...rest] = args;
+  if (sub === 'list' || sub === 'verify') {
+    let json = false;
+    let offline = false;
+    for (const arg of rest) {
+      if (arg === '--json' && !json) json = true;
+      else if (arg === '--offline' && !offline && sub === 'verify') offline = true;
+      else return undefined;
+    }
+    return sub === 'list' ? { command: 'plugin', sub, json } : { command: 'plugin', sub, json, offline };
+  }
+  if (sub === 'remove') {
+    let json = false;
+    let name: string | undefined;
+    for (const arg of rest) {
+      if (arg === '--json' && !json) json = true;
+      else if (arg.startsWith('-') || name !== undefined) return undefined;
+      else name = arg;
+    }
+    return name === undefined ? undefined : { command: 'plugin', sub: 'remove', json, name };
+  }
+  if (sub !== 'update') return undefined;
+  let json = false;
+  let yes = false;
+  let to: string | undefined;
+  let name: string | undefined;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i]!;
+    if (arg === '--json' && !json) json = true;
+    else if (arg === '--yes' && !yes) yes = true;
+    else if (arg === '--to') {
+      const value = rest[i + 1];
+      if (to !== undefined || value === undefined || value.startsWith('-')) return undefined;
+      to = value;
+      i += 1;
+    } else if (arg.startsWith('-') || name !== undefined) return undefined;
+    else name = arg;
+  }
+  return { command: 'plugin', sub: 'update', json, yes, name, to };
+}
+
+/**
+ * Cross-check the three records that must agree: `flows.json.plugins`
+ * (declaration), `flows.lock.json` (provenance), and `.flows/plugins` (bytes).
+ * With the network, the pinned commit is re-fetched and re-hashed too.
+ */
+export async function verifyPlugins(root: string, options: { offline: boolean; fetch?: FetchLike }): Promise<{ entry: PluginLockEntry; ref: string; directory: string; remote: 'verified' | 'skipped' }[]> {
+  const results = [];
+  for (const { ref, entry, source } of reconcileDeclaredExtensions(root)) {
+    const directory = pluginStoreDirectory(root, entry.name, entry.digest);
+    await verifyStoredPlugin(directory, entry.digest);
+    let remote: 'verified' | 'skipped' = 'skipped';
+    if (!options.offline) {
+      const fetched = await fetchGithubPlugin(source, options.fetch);
+      if (fetched.digest !== entry.digest) throw new PluginError('plugin_source_drift', `${ref}: GitHub now serves digest ${fetched.digest}, lockfile has ${entry.digest}.`);
+      remote = 'verified';
+    }
+    results.push({ entry, ref, directory, remote });
+  }
+  return results;
+}
+
+export interface PluginCommandOptions {
+  cwd?: string;
+  fetch?: FetchLike;
+  now?: () => Date;
+  versions?: RuntimeVersions;
+}
+
+export async function runPluginCommand(parsed: PluginArgs, io: CliIo, options: PluginCommandOptions = {}): Promise<0 | 2> {
+  try {
+    const root = findPluginProject(options.cwd ?? process.cwd());
+    if (!root) throw new PluginError('plugin_manifest_invalid', 'flows plugin requires a project with flows.json.');
+    if (parsed.sub === 'list') {
+      const plugins = lockedPlugins(readPluginLock(root));
+      if (parsed.json) { io.stdout(JSON.stringify({ plugins: plugins.map(p => ({ ...p.entry, ref: p.ref })) })); return 0; }
+      if (plugins.length === 0) { io.stdout('No flow-extension plugins installed.'); return 0; }
+      for (const { entry, ref } of plugins) io.stdout(`${entry.order}. ${entry.name}@${entry.version}  ${ref}  sha256:${entry.digest}`);
+      return 0;
+    }
+    if (parsed.sub === 'verify') {
+      const results = await verifyPlugins(root, { offline: parsed.offline, ...(options.fetch === undefined ? {} : { fetch: options.fetch }) });
+      if (parsed.json) { io.stdout(JSON.stringify({ ok: true, plugins: results.map(r => ({ name: r.entry.name, ref: r.ref, digest: r.entry.digest, remote: r.remote })) })); return 0; }
+      for (const r of results) io.stdout(`OK ${r.entry.name}@${r.entry.version}  ${r.ref}  local digest matches lockfile; remote ${r.remote}`);
+      if (results.length === 0) io.stdout('No flow-extension plugins to verify.');
+      return 0;
+    }
+    if (parsed.sub === 'remove') return await removePlugin(root, parsed, io);
+    return await updatePlugins(root, parsed, io, options);
+  } catch (error) {
+    const refusal = error instanceof PluginError ? error : new PluginError('plugin_manifest_invalid', (error as Error).message);
+    if (parsed.json) io.stdout(JSON.stringify({ ok: false, code: refusal.code, message: refusal.message }));
+    io.stderr(`REFUSED [${refusal.code}] ${refusal.message}`);
+    return 2;
+  }
+}
+
+function readFlowsConfig(root: string): { path: string; config: Record<string, unknown>; plugins: string[] } {
+  recoverFlowsAndLock(root);
+  const path = join(root, 'flows.json');
+  let parsed: unknown;
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')); }
+  catch { throw new PluginError('plugin_manifest_invalid', 'Invalid flows.json.'); }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)
+    || ((parsed as { plugins?: unknown }).plugins !== undefined
+      && (!Array.isArray((parsed as { plugins?: unknown }).plugins)
+        || !(parsed as { plugins: unknown[] }).plugins.every(p => typeof p === 'string')))) {
+    throw new PluginError('plugin_manifest_invalid', 'Invalid flows.json plugins list.');
+  }
+  const config = parsed as Record<string, unknown>;
+  return { path, config, plugins: [...((config.plugins as string[] | undefined) ?? [])] };
+}
+
+function storedManifest(directory: string): FlowExtensionManifest {
+  let raw: string;
+  try { raw = readFileSync(join(directory, 'flows-plugin.json'), 'utf8'); }
+  catch { throw new PluginError('plugin_source_drift', `${directory}: flows-plugin.json is missing.`); }
+  let input: unknown;
+  try { input = JSON.parse(raw); }
+  catch { throw new PluginError('plugin_manifest_invalid', `${directory}: flows-plugin.json is unreadable or invalid JSON.`); }
+  return validateFlowExtensionManifest(input);
+}
+
+function storeReferenced(lock: PluginLock, name: string, digest: string): boolean {
+  return lock.plugins.some(p => p.name === name && p.digest === digest);
+}
+
+async function dropUnreferencedStore(root: string, name: string, digest: string, lock: PluginLock): Promise<void> {
+  if (storeReferenced(lock, name, digest)) return;
+  await removeStoredPlugin(pluginStoreDirectory(root, name, digest));
+}
+
+async function removePlugin(root: string, parsed: Extract<PluginArgs, { sub: 'remove' }>, io: CliIo): Promise<0 | 2> {
+  const locked = lockedPlugins(readPluginLock(root));
+  const match = locked.find(p => p.entry.name === parsed.name);
+  if (match === undefined) throw new PluginError('plugin_manifest_invalid', `No flow-extension plugin named ${parsed.name}.`);
+  const { path, config, plugins } = readFlowsConfig(root);
+  const nextDeclared = plugins.filter(ref => ref !== match.ref);
+  const nextLock = lockForDeclared(readPluginLock(root), nextDeclared);
+  writeFlowsAndLock(root, path, config, nextDeclared, nextLock);
+  await dropUnreferencedStore(root, match.entry.name, match.entry.digest, nextLock);
+  if (parsed.json) {
+    io.stdout(JSON.stringify({ ok: true, removed: { name: match.entry.name, ref: match.ref, digest: match.entry.digest } }));
+    return 0;
+  }
+  io.stdout(`Removed ${match.entry.name}@${match.entry.version}  ${match.ref}`);
+  return 0;
+}
+
+function replaceDeclaredRef(plugins: readonly string[], oldRef: string, newRef: string): string[] {
+  const without = plugins.filter(ref => ref !== oldRef);
+  if (without.includes(newRef)) return without;
+  const at = plugins.indexOf(oldRef);
+  const next = [...without];
+  next.splice(at === -1 ? next.length : at, 0, newRef);
+  return next;
+}
+
+async function updatePlugins(
+  root: string,
+  parsed: Extract<PluginArgs, { sub: 'update' }>,
+  io: CliIo,
+  options: PluginCommandOptions,
+): Promise<0 | 2> {
+  if (parsed.to !== undefined && parsed.name === undefined) {
+    throw new PluginError('plugin_manifest_invalid', 'flows plugin update --to requires a plugin name.');
+  }
+  const locked = lockedPlugins(readPluginLock(root));
+  const targets = parsed.name === undefined ? locked : locked.filter(p => p.entry.name === parsed.name);
+  if (parsed.name !== undefined && targets.length === 0) {
+    throw new PluginError('plugin_manifest_invalid', `No flow-extension plugin named ${parsed.name}.`);
+  }
+  if (targets.length === 0) {
+    if (parsed.json) { io.stdout(JSON.stringify({ ok: true, plugins: [] })); return 0; }
+    io.stdout('No flow-extension plugins to update.');
+    return 0;
+  }
+
+  type Plan = {
+    current: (typeof locked)[number];
+    ref: string;
+    digest: string;
+    manifest: FlowExtensionManifest;
+    manifestSha256: string;
+    source: { host: 'github'; owner: string; repo: string; sha: string; path: string };
+    files: readonly { path: string; data: Uint8Array }[];
+    diff: string[];
+    changed: boolean;
+  };
+  const plans: Plan[] = [];
+  for (const current of targets) {
+    const requested = parsed.to === undefined ? { ...current.source } : parsePluginSource(parsed.to);
+    const source = await resolveGithubSha(requested, options.fetch);
+    const fetched = await fetchGithubPlugin(source, options.fetch);
+    const { manifest, manifestSha256 } = extensionManifestOf(fetched);
+    if (manifest.name !== current.entry.name) {
+      throw new PluginError('plugin_manifest_invalid', `Update of ${current.entry.name} resolved to plugin ${manifest.name}; remove it and add the new name instead.`);
+    }
+    assertCompatible(manifest, options.versions ?? runtimeVersions());
+    const directory = pluginStoreDirectory(root, current.entry.name, current.entry.digest);
+    const before = storedManifest(directory);
+    const ref = canonicalPluginRef(source);
+    const changed = ref !== current.ref || fetched.digest !== current.entry.digest || manifestSha256 !== current.entry.manifestSha256;
+    plans.push({
+      current, ref, digest: fetched.digest, manifest, manifestSha256,
+      source: { host: 'github', owner: source.owner, repo: source.repo, sha: source.sha, path: source.path },
+      files: fetched.files, diff: diffExtension(before, manifest), changed,
+    });
+  }
+
+  const pending = plans.filter(p => p.changed);
+  const summary = plans.map(p => ({
+    name: p.current.entry.name, from: p.current.ref, to: p.ref, digest: p.digest, changed: p.changed, diff: p.diff,
+  }));
+  if (!parsed.json) {
+    for (const plan of plans) {
+      if (!plan.changed) {
+        io.stdout(`${plan.current.entry.name} is already at ${plan.ref}  sha256:${plan.digest}`);
+        continue;
+      }
+      io.stdout(`Update ${plan.current.entry.name}  ${plan.current.ref} → ${plan.ref}`);
+      io.stdout(`  digest sha256:${plan.current.entry.digest} → sha256:${plan.digest}`);
+      for (const line of plan.diff) io.stdout(line);
+    }
+  }
+  if (pending.length === 0) {
+    if (parsed.json) io.stdout(JSON.stringify({ ok: true, plugins: summary }));
+    return 0;
+  }
+  if (!parsed.yes) {
+    if (parsed.json) {
+      io.stdout(JSON.stringify({
+        ok: false, applied: false, code: 'plugin_manifest_invalid',
+        message: 'Re-run with --yes to apply this update.', plugins: summary,
+      }));
+      io.stderr('REFUSED [plugin_manifest_invalid] Re-run with --yes to apply this update.');
+      return 2;
+    }
+    throw new PluginError('plugin_manifest_invalid', 'Re-run with --yes to apply this update.');
+  }
+
+  let declared = readFlowsConfig(root).plugins;
+  let lock = readPluginLock(root);
+  const applied: { name: string; ref: string; digest: string }[] = [];
+  for (const plan of pending) {
+    const { directory, digest } = await materializePlugin(root, plan.manifest.name, plan.files);
+    if (digest !== plan.digest) throw new PluginError('plugin_source_drift', 'Materialized digest differs from the fetched digest.');
+    declared = replaceDeclaredRef(declared, plan.current.ref, plan.ref);
+    lock = lockWithPlugin(lock, declared, {
+      name: plan.manifest.name, version: plan.manifest.version, source: plan.source,
+      digest, manifestSha256: plan.manifestSha256,
+      resolvedAt: (options.now ?? (() => new Date()))().toISOString(),
+    });
+    const { path, config } = readFlowsConfig(root);
+    writeFlowsAndLock(root, path, config, declared, lock);
+    await dropUnreferencedStore(root, plan.current.entry.name, plan.current.entry.digest, lock);
+    applied.push({ name: plan.manifest.name, ref: plan.ref, digest });
+  }
+  if (parsed.json) io.stdout(JSON.stringify({ ok: true, plugins: applied }));
+  else for (const item of applied) io.stdout(`Updated ${item.name}  ${item.ref}  sha256:${item.digest}  recorded in flows.json and ${PLUGIN_LOCK_FILE}`);
+  return 0;
+}

package/src/cli-commands.ts

@@ -104,8 +104,8 @@ const LOCAL_EXECUTION_OPTIONS = [
 export const CLI_VERBS = [
   {
     name: 'add',
-    description: 'Install a helper plugin into this project',
-    args: [{ name: 'helper', description: 'Helper name or @flows/<helper-name>', required: true }],
+    description: 'Install a helper plugin, or a flow-extension plugin from a public GitHub repository, into this project',
+    args: [{ name: 'plugin', description: 'Helper name, @flows/<helper-name>, github:<owner>/<repo>@<ref>#<path>, or a github.com tree URL', required: true }],
     variants: ['add'],
   },
   {
@@ -155,6 +155,7 @@ export const CLI_VERBS = [
       { flags: '--agents <list>', description: 'Agent harnesses to allow, as claude[,codex]' },
       { flags: '--name <name>', description: 'Name for the hosted listener' },
       { flags: '--draft', description: 'Create the listener without activating it' },
+      { flags: '--plugin <ref>', description: 'Send-only GitHub flow-extension ref; repeatable. Does not write flows.json' },
       NO_CONNECT_OPTION,
       JSON_OPTION,
     ],
@@ -199,6 +200,35 @@ export const CLI_VERBS = [
     options: [DATA_DIR_OPTION],
     variants: ['observer'],
   },
+  {
+    name: 'plugin',
+    description: 'Inspect, remove, or update the flow-extension plugins recorded in flows.lock.json',
+    subcommands: [
+      { name: 'list', description: 'List installed flow extensions in composition order', options: [JSON_OPTION] },
+      {
+        name: 'verify',
+        description: 'Re-hash .flows/plugins against the lockfile and, unless --offline, against the pinned commit on GitHub',
+        options: [JSON_OPTION, { flags: '--offline', description: 'Skip the GitHub re-fetch; check only the local store against the lockfile' }],
+      },
+      {
+        name: 'remove',
+        description: 'Drop a flow-extension plugin from flows.json, the lockfile, and the local store',
+        args: [{ name: 'name', description: 'Plugin name as recorded in the lockfile', required: true }],
+        options: [JSON_OPTION],
+      },
+      {
+        name: 'update',
+        description: 'Re-resolve a flow-extension plugin, show the permissions/events/budget diff, and rewrite the lock with --yes',
+        args: [{ name: 'name', description: 'Plugin name; omit to update every installed flow extension', required: false }],
+        options: [
+          JSON_OPTION,
+          { flags: '--to <ref>', description: 'GitHub reference to resolve instead of the locked commit' },
+          { flags: '--yes', description: 'Apply the update; without this flag the diff is printed and the lock is left unchanged' },
+        ],
+      },
+    ],
+    variants: ['plugin'],
+  },
   {
     name: 'replay',
     description: 'Replay a finished run from its local journal',

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { addPlugin } from './cli/add.js';
+import { parsePluginArgs, runPluginCommand, type PluginArgs } from './cli/plugin.js';
 import { watchCheck } from './cli-watch.js';
 import { checkHelperBody } from './cli/check-helper-body.js';
 import { describeFlowRequirements } from './flow-requirements.js';
@@ -64,6 +65,7 @@ type CliExitCode = 0 | 1 | 2 | 3;
  */
 export type ParsedArgs =
   | { command: 'add'; value: string }
+  | PluginArgs
   | ReplayArgs
   | StatusArgs
   | BuildArgs
@@ -92,9 +94,14 @@ export type ParsedArgs =
 const USAGE = [
   'Usage:',
   'flows add <helper-name|@flows/helper-name>',
+  'flows add <github:owner/repo@ref#path|https://github.com/owner/repo/tree/ref/path>',
+  'flows plugin list [--json]',
+  'flows plugin verify [--json] [--offline]',
+  'flows plugin remove [--json] <name>',
+  'flows plugin update [--json] [--yes] [--to <ref>] [<name>]',
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
-  'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--no-connect] [--json]',
+  'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--plugin <ref>] [--no-connect] [--json]',
   'flows deployments [--json]',
   'flows undeploy [--json] <deployment-id>',
   'flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>] [--tz <IANA>] [--input <inline-json-or-file>] [--name <name>] [--no-connect] [--json]',
@@ -192,6 +199,7 @@ export async function runCli(
   }
 
   if (parsed.command === 'add') return addPlugin(parsed.value, io);
+  if (parsed.command === 'plugin') return runPluginCommand(parsed, io);
 
   if (parsed.command === 'serve-webhook') {
     return withInterrupt(options.signal, (signal) => runServeWebhook(parsed, io, signal));
@@ -347,6 +355,8 @@ async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckR
     report: {
       ...mcp.report,
       ...(triggers?.report.schedules === undefined ? {} : { schedules: triggers.report.schedules }),
+      ...(triggers?.report.extensions === undefined ? {} : { extensions: triggers.report.extensions }),
+      ...(triggers?.report.hooks === undefined ? {} : { hooks: triggers.report.hooks }),
       // The authored definition sees helper flags, body use and `cli:`
       // declarations; the compiled view underneath knows only its steps.
       ...(triggers?.report.requirements === undefined ? {} : { requirements: triggers.report.requirements }),
@@ -521,6 +531,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   // parser, so the declared tree and the dispatched tree cannot drift apart.
   if (command === undefined || !CLI_VERB_NAMES.has(command)) return undefined;
   if (command === 'add') return args.length === 2 ? { command: 'add', value: args[1]! } : undefined;
+  if (command === 'plugin') return parsePluginArgs(args.slice(1));
   if (command === 'replay') return parseReplayArgs(args.slice(1));
   if (command === 'status') return parseStatusArgs(args.slice(1));
   if (command === 'runs') return parseRunsArgs(args.slice(1));
@@ -937,6 +948,17 @@ function emitCheckReport(report: CheckReport, json: boolean, io: CliIo): void {
       : `local: flows tick start --schedule-id ${schedule.scheduleId} --interval-ms ${schedule.intervalMs} --epoch-ms ${schedule.epochMs}`;
     io.stdout(`SCHEDULE handler ${schedule.handler} ${declared} -> flows.tick schedule_id ${schedule.scheduleId} [${local}]`);
   }
+  for (const extension of report.extensions ?? []) {
+    const hookList = (extension.hooks ?? []).length === 0 ? '' : `, hooks: ${extension.hooks!.join(', ')}`;
+    io.stdout(`EXTENSION ${extension.name}@${extension.version} ${extension.ref} sha256:${extension.digest} -> ${extension.handlers} handler(s) composed after the base flow${hookList}`);
+  }
+  if (report.hooks !== undefined) {
+    io.stdout(`HOOKS declared: ${report.hooks.declared.join(', ') || '(none)'}`);
+    for (const row of report.hooks.implementations) io.stdout(`HOOK ${row.hook} <- ${row.plugin}`);
+    for (const name of report.hooks.declared) {
+      if (!report.hooks.implementations.some(row => row.hook === name)) io.stdout(`HOOK ${name} <- (none)`);
+    }
+  }
   for (const resolution of report.resolutions) {
     const config = resolution.source === 'project' && report.projectConfigPath !== undefined
       ? ` (${report.projectConfigPath})`

package/src/cloud-deploy.ts

@@ -6,8 +6,11 @@ import { ensureIntegrationsConnected, type ConnectPrompt } from './cloud-connect
 import {
   CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions,
 } from './cloud-http.js';
-import { flowRequirements, type FlowRequirements } from './flow-requirements.js';
+import {
+  flowRequirements, mergeFlowExtensionRequirements, type FlowRequirements,
+} from './flow-requirements.js';
 import { readProjectConfig } from './cli/check.js';
+import { assertNoUseDependencies, collectExtensionSubmissions } from './flow-extension-submit.js';
 
 /**
  * Hosted listener deployment: the CLI form of the agentrelay.com onboarding's
@@ -67,6 +70,11 @@ export interface DeployToCloudInput {
   connect?: ConnectPrompt;
   /** Skip the pre-submission integration check entirely (Cloud still checks on activation). */
   checkConnections?: boolean;
+  /**
+   * Extra GitHub plugin refs resolved send-only (same path as `flows add`,
+   * without writing flows.json). Project-declared extensions are always sent.
+   */
+  plugins?: readonly string[];
 }
 
 export const FLOW_AGENT_HARNESSES = ['claude', 'codex'] as const;
@@ -170,10 +178,8 @@ export async function deployToCloud(
     throw new CloudFlowError('unsupported_source',
       `${input.path} is not a loadable authored flow: ${error instanceof Error ? error.message : String(error)}`);
   }
-  if (loaded.graph.length !== 1) {
-    throw new CloudFlowError('unsupported_source',
-      'Cloud deploys one self-contained .flow.ts source without use dependencies.');
-  }
+  assertNoUseDependencies(loaded);
+  const extensions = await collectExtensionSubmissions(loaded, input.plugins ?? []);
   let projectCli: string | undefined;
   try {
     projectCli = readProjectConfig(dirname(resolve(input.path))).cli;
@@ -204,9 +210,12 @@ export async function deployToCloud(
   }
   // Every launched run lands in the deployment's repository, so GitHub is
   // required even when no GitHub source wakes it.
-  const requirements = flowRequirements(definition, {
-    sources, repository: input.repository, ...(projectCli === undefined ? {} : { projectCli }),
-  });
+  const requirements = mergeFlowExtensionRequirements(
+    flowRequirements(definition, {
+      sources, repository: input.repository, ...(projectCli === undefined ? {} : { projectCli }),
+    }),
+    extensions.map(extension => ({ name: extension.name, permissions: extension.manifest.permissions })),
+  );
   // The declared harnesses become `inputs.agents`; one Cloud cannot run is
   // refused here rather than silently replaced by Claude, which activation
   // would then check while the deployed runs still call the declared CLI.
@@ -237,6 +246,7 @@ export async function deployToCloud(
     inputs: { approver, agents },
     repository: input.repository,
     sources,
+    ...(extensions.length === 0 ? {} : { extensions }),
     requirements: {
       integrations: requirements.integrations.map(i => i.provider),
       harnesses: requirements.harnesses,

package/src/cloud-run.ts

@@ -9,6 +9,7 @@ import { CompileError, compileSpec, kernelToAuthoring, toKernelSpec } from './co
 import type { FlowSpec } from './spec.js';
 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,
   type CloudConnectionOptions,
@@ -61,6 +62,7 @@ export function cloudSubmissionBody(submission: CloudSubmission): Record<string,
     relayflowVersion: 'v2',
     ...(submission.authoredAuthority === undefined ? {} : { authoredAuthority: submission.authoredAuthority }),
     ...(submission.inputPresent ? { inputs: submission.inputs } : {}),
+    ...(submission.extensions === undefined || submission.extensions.length === 0 ? {} : { extensions: submission.extensions }),
   };
 }
 
@@ -90,6 +92,7 @@ export interface CloudSubmission {
   readonly name: string;
   /** Authored `schedule.*` handlers, for `flows schedule` to pick up. */
   readonly schedules: readonly ScheduleTriggerSource[];
+  readonly extensions?: readonly FlowExtensionSubmission[];
 }
 
 export async function prepareCloudSubmission(
@@ -97,7 +100,7 @@ export async function prepareCloudSubmission(
   options: { input?: JsonValue; signal?: AbortSignal } = {},
 ): Promise<CloudSubmission> {
   let spec: FlowSpec | undefined;
-  let authored: { source: string; authority: CloudAuthoredAuthority; name: string; schedules: ScheduleTriggerSource[] } | undefined;
+  let authored: { source: string; authority: CloudAuthoredAuthority; name: string; schedules: ScheduleTriggerSource[]; extensions: readonly FlowExtensionSubmission[] } | undefined;
   const inputPresent = Object.prototype.hasOwnProperty.call(options, 'input');
   let authoredInput: JsonValue | undefined;
   try {
@@ -122,14 +125,13 @@ export async function prepareCloudSubmission(
             `${flow.path} is not a loadable authored flow: ${error instanceof Error ? error.message : String(error)}. `
             + 'Run `flows check` on it from the same directory.');
         }
-        if (loaded.graph.length !== 1) {
-          throw new CloudFlowError('unsupported_source',
-            'Cloud authored submission currently accepts one self-contained .flow.ts source without use dependencies.');
-        }
+        assertNoUseDependencies(loaded);
+        const extensions = await collectExtensionSubmissions(loaded);
         authored = {
           source,
           name: definition.name,
           schedules: definition.handlers.flatMap(h => h.trigger.kind === 'schedule' ? [h.trigger] : []),
+          extensions,
           authority: Object.freeze({
             schemaVersion: 1,
             sourceSha256: createHash('sha256').update(bytes).digest('hex'),
@@ -182,7 +184,15 @@ export async function prepareCloudSubmission(
   return {
     workflow: authored.source, fileType: 'ts', authoredAuthority: authored.authority,
     inputs: authoredInput, inputPresent: true, name: authored.name, schedules: authored.schedules,
-    specHash: createHash('sha256').update(canonicalize({ authority: authored.authority, input: authoredInput })).digest('hex'),
+    ...(authored.extensions.length === 0 ? {} : { extensions: authored.extensions }),
+    specHash: createHash('sha256').update(canonicalize({
+      authority: authored.authority, input: authoredInput,
+      ...(authored.extensions.length === 0 ? {} : {
+        extensions: authored.extensions.map(extension => ({
+          name: extension.name, digest: extension.digest, ref: extension.ref,
+        })),
+      }),
+    })).digest('hex'),
   };
 }
 

package/src/flow-extension-compat.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+import type { FlowExtensionManifest } from './flow-extension-manifest.js';
+import { PluginError } from './plugin-manifest.js';
+import { satisfiesRange } from './semver-range.js';
+
+export interface RuntimeVersions { readonly sdk: string; readonly surface: string }
+
+/** The versions a plugin's `compat` is checked against: this SDK and the surface it pins. */
+export function runtimeVersions(): RuntimeVersions {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string; dependencies: Record<string, string> };
+  return { sdk: pkg.version, surface: pkg.dependencies['@relayflows/surface']! };
+}
+
+/** `compat.surface` / `compat.sdk` against the runtime: a miss is a refusal, never a warning. */
+export function assertCompatible(manifest: FlowExtensionManifest, versions: RuntimeVersions): void {
+  for (const [what, range, actual] of [['surface', manifest.compat.surface, versions.surface], ['sdk', manifest.compat.sdk, versions.sdk]] as const) {
+    if (!satisfiesRange(actual, range)) throw new PluginError('plugin_incompatible', `${manifest.name} requires ${what} ${range}; this runtime has ${actual}.`);
+  }
+}
+
+/**
+ * `compat.base` against the flow being extended. `FlowHeader.version` is
+ * optional: a base without it matches only `"*"`.
+ */
+export function assertBaseCompatible(manifest: FlowExtensionManifest, base: { readonly name: string; readonly version?: string }): void {
+  const entry = manifest.compat.base.find(b => b.name === base.name);
+  if (entry === undefined) {
+    throw new PluginError('plugin_incompatible', `${manifest.name} extends ${manifest.compat.base.map(b => b.name).join(', ')}, not "${base.name}".`);
+  }
+  if (base.version === undefined) {
+    if (entry.version !== '*') throw new PluginError('plugin_incompatible', `${manifest.name} requires ${base.name} ${entry.version}, but the base flow declares no version; only "*" can be satisfied.`);
+    return;
+  }
+  if (!satisfiesRange(base.version, entry.version)) throw new PluginError('plugin_incompatible', `${manifest.name} requires ${base.name} ${entry.version}; the base flow is ${base.version}.`);
+}