@relayflows/sdk 2.0.24 → 2.0.25

package/src/flow-extension-loader.ts

@@ -0,0 +1,217 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { Ctx } from '@relayflows/surface';
+import type { AuthoredFlowDefinition, FlowHandle } from './authored-flow.js';
+import { sha256 } from './bundle.js';
+import { assertBaseCompatible, assertCompatible, runtimeVersions, type RuntimeVersions } from './flow-extension-compat.js';
+import { validateFlowExtensionManifest, type FlowExtensionManifest } from './flow-extension-manifest.js';
+import { findPluginProject } from './plugin-loader.js';
+import { reconcileDeclaredExtensions, type PluginLockEntry } from './plugin-lock.js';
+import { PluginError } from './plugin-manifest.js';
+import { pluginStoreDirectory, verifyStoredPlugin } from './plugin-store.js';
+
+/**
+ * Compose schema-2 flow extensions onto a base authored flow.
+ *
+ * Order of operations is the security argument, so it is fixed:
+ *   1. `flows.json.plugins` and `flows.lock.json` must agree (declaration ⇔
+ *      provenance, same order);
+ *   2. the materialized store is re-hashed against the lock's digest and the
+ *      manifest bytes against the lock's manifest hash — nothing under
+ *      `.flows/plugins` is read as code before this passes;
+ *   3. the manifest is validated, its compat checked against the runtime and
+ *      the base flow, and anything this slice does not compose (hooks, `use`,
+ *      schedule triggers, non-provider webhooks, gates) is refused;
+ *   4. only then is the entry imported, and its handlers are checked against
+ *      the manifest's declared triggers — an entry cannot subscribe to more
+ *      than it declared.
+ * Extensions compose after the base, in lock order; nothing replaces,
+ * reorders, or widens a base handler.
+ */
+type TriggerHandler = AuthoredFlowDefinition['handlers'][number];
+
+export type FlowHook = (f: Ctx, input: unknown) => Promise<boolean>;
+
+export interface LoadedFlowExtension {
+  readonly name: string;
+  readonly version: string;
+  readonly ref: string;
+  readonly digest: string;
+  readonly directory: string;
+  readonly entryPath: string;
+  readonly manifest: FlowExtensionManifest;
+  readonly handle: FlowHandle;
+  /** Bound to the surface copy the entry itself imported; the base's accessor cannot see this handle's WeakMap entry. */
+  readonly getDefinition: ImportedFlow<unknown>['getDefinition'];
+  readonly handlers: readonly TriggerHandler[];
+  readonly hooks: Readonly<Record<string, FlowHook>>;
+}
+
+export interface ImportedFlow<Authority> {
+  readonly handle: FlowHandle;
+  readonly getDefinition: <Input = unknown>(handle: FlowHandle) => AuthoredFlowDefinition<Input>;
+  readonly surfaceAuthority: Authority;
+  readonly hooks: Readonly<Record<string, FlowHook>>;
+}
+
+export interface LoadFlowExtensionsOptions<Authority> {
+  readonly importFlow: (path: string) => Promise<ImportedFlow<Authority>>;
+  readonly sameAuthority: (a: Authority, b: Authority) => boolean;
+  readonly versions?: RuntimeVersions;
+}
+
+const EXTENSION_HEADER_FIELDS = new Set(['budget', 'tools']);
+const WALLCLOCK_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
+
+function wallclockMs(value: string): number | undefined {
+  const match = /^(\d+)(ms|s|m|h|d)$/.exec(value);
+  if (!match) return undefined;
+  const unit = match[2] as keyof typeof WALLCLOCK_MS;
+  return Number(match[1]) * WALLCLOCK_MS[unit];
+}
+
+/** Credentials and servers declared on a flow-extension, probed before the base body starts. */
+export async function probeFlowExtension(manifest: FlowExtensionManifest, env: NodeJS.ProcessEnv = process.env): Promise<void> {
+  for (const credential of manifest.preflight.credentials) {
+    if (!env[credential]?.trim()) throw new PluginError('plugin_credential_missing', `${manifest.name} requires ${credential}.`);
+  }
+  for (const server of manifest.preflight.servers) {
+    try {
+      const response = await fetch(server, { method: 'HEAD', signal: AbortSignal.timeout(5000) });
+      await response.body?.cancel();
+      if (!response.ok) throw new Error('unsuccessful response');
+    } catch { throw new PluginError('plugin_server_unreachable', `${manifest.name} cannot reach ${server}.`); }
+  }
+}
+
+function unsupported(name: string, what: string): never {
+  throw new PluginError('plugin_unsupported', `${name}: ${what} is not composed by this release.`);
+}
+
+/** The `{provider, event, action?}` a provider subscription lowers to, or undefined for anything else. */
+function subscriptionOf(handler: TriggerHandler): { provider: string; event: string; action?: string } | undefined {
+  const trigger = handler.trigger;
+  if (trigger.kind !== 'webhook' || trigger.filter === undefined) return undefined;
+  const { provider, type, payload } = trigger.filter as { provider?: unknown; type?: unknown; payload?: unknown };
+  if (typeof provider !== 'string' || provider !== trigger.name || typeof type !== 'string') return undefined;
+  const action = typeof payload === 'object' && payload !== null && !Array.isArray(payload) ? (payload as { action?: unknown }).action : undefined;
+  if (action !== undefined && typeof action !== 'string') return undefined;
+  return action === undefined ? { provider, event: type } : { provider, event: type, action };
+}
+
+function assertDeclaredSubscription(name: string, manifest: FlowExtensionManifest, handler: TriggerHandler, index: number): void {
+  const subscription = subscriptionOf(handler);
+  if (handler.trigger.kind === 'schedule') unsupported(name, `handler ${index} (a schedule trigger)`);
+  if (subscription === undefined) {
+    throw new PluginError('plugin_manifest_invalid', `${name}: handler ${index} is not a provider subscription; extension handlers must be provider triggers declared in flows-plugin.json.`);
+  }
+  const declared = manifest.triggers.find(t => t.provider === subscription.provider && t.event === subscription.event);
+  const covered = declared !== undefined && (subscription.action === undefined ? declared.actions.length === 0 : declared.actions.includes(subscription.action));
+  if (!covered) {
+    const spelled = `${subscription.provider} ${subscription.event}${subscription.action === undefined ? '' : `.${subscription.action}`}`;
+    throw new PluginError('plugin_manifest_invalid', `${name}: handler ${index} subscribes to ${spelled}, which flows-plugin.json does not declare in triggers.`);
+  }
+}
+
+async function loadOne<Authority>(
+  root: string, lock: PluginLockEntry, ref: string,
+  base: { readonly definition: AuthoredFlowDefinition; readonly surfaceAuthority: Authority },
+  options: LoadFlowExtensionsOptions<Authority>,
+): Promise<LoadedFlowExtension> {
+  const directory = pluginStoreDirectory(root, lock.name, lock.digest);
+  await verifyStoredPlugin(directory, lock.digest);
+  const manifestBytes = readFileSync(join(directory, 'flows-plugin.json'));
+  if (sha256(manifestBytes) !== lock.manifestSha256) throw new PluginError('plugin_source_drift', `${ref}: flows-plugin.json differs from the lockfile's manifest hash.`);
+  let input: unknown;
+  try { input = JSON.parse(manifestBytes.toString('utf8')); }
+  catch { throw new PluginError('plugin_manifest_invalid', `${ref}: flows-plugin.json is not valid JSON.`); }
+  const manifest = validateFlowExtensionManifest(input);
+  if (manifest.name !== lock.name || manifest.version !== lock.version) throw new PluginError('plugin_source_drift', `${ref}: manifest names ${manifest.name}@${manifest.version}, lockfile has ${lock.name}@${lock.version}.`);
+  assertCompatible(manifest, options.versions ?? runtimeVersions());
+  assertBaseCompatible(manifest, { name: base.definition.name, version: base.definition.header.version });
+  const baseBudget = base.definition.header.budget;
+  const ceiling = manifest.permissions.budget;
+  if (ceiling?.dollars !== undefined && typeof baseBudget === 'object' && baseBudget.dollars !== undefined && ceiling.dollars > baseBudget.dollars) {
+    throw new PluginError('plugin_incompatible', `${manifest.name} declares a $${ceiling.dollars} budget ceiling above the base flow's $${baseBudget.dollars}.`);
+  }
+  if (ceiling?.wallclock !== undefined && typeof baseBudget === 'object' && baseBudget.wallclock !== undefined) {
+    const pluginMs = wallclockMs(ceiling.wallclock);
+    const baseMs = wallclockMs(baseBudget.wallclock);
+    if (pluginMs !== undefined && baseMs !== undefined && pluginMs > baseMs) {
+      throw new PluginError('plugin_incompatible', `${manifest.name} declares a ${ceiling.wallclock} wallclock ceiling above the base flow's ${baseBudget.wallclock}.`);
+    }
+  }
+  const entryPath = join(directory, manifest.entry);
+  let imported: ImportedFlow<Authority>;
+  try { imported = await options.importFlow(entryPath); }
+  catch (error) { throw new PluginError('plugin_manifest_invalid', `${ref}: entry ${manifest.entry} did not load: ${error instanceof Error ? error.message : String(error)}`); }
+  if (!options.sameAuthority(imported.surfaceAuthority, base.surfaceAuthority)) {
+    throw new PluginError('plugin_incompatible', `${manifest.name}: entry resolves a different @relayflows/surface than the base flow.`);
+  }
+  const definition = imported.getDefinition(imported.handle);
+  const foreign = Object.keys(definition.header).filter(key => !EXTENSION_HEADER_FIELDS.has(key));
+  if (foreign.length > 0) unsupported(manifest.name, `entry header ${foreign.join(', ')}`);
+  if (manifest.extends.handlers && definition.handlers.length === 0) {
+    throw new PluginError('plugin_manifest_invalid', `${manifest.name}: extends.handlers is true but ${manifest.entry} declares no .on() handlers.`);
+  }
+  if (!manifest.extends.handlers && definition.handlers.length > 0) {
+    throw new PluginError('plugin_manifest_invalid', `${manifest.name}: ${manifest.entry} declares handlers but extends.handlers is false.`);
+  }
+  definition.handlers.forEach((handler, index) => assertDeclaredSubscription(manifest.name, manifest, handler, index));
+  const hooks = imported.hooks;
+  const exported = Object.keys(hooks).sort();
+  const declared = [...manifest.extends.hooks].sort();
+  if (exported.join('\0') !== declared.join('\0')) {
+    throw new PluginError('plugin_manifest_invalid', `${manifest.name}: extends.hooks [${manifest.extends.hooks.join(', ')}] does not match exported hooks [${exported.join(', ')}].`);
+  }
+  const baseHooks = base.definition.header.hooks ?? [];
+  for (const hook of manifest.extends.hooks) {
+    if (!baseHooks.includes(hook)) {
+      throw new PluginError('plugin_incompatible', `${manifest.name}: hook ${hook} is not declared by the base flow.`);
+    }
+  }
+  return Object.freeze({
+    name: manifest.name, version: manifest.version, ref, digest: lock.digest, directory, entryPath, manifest,
+    handle: imported.handle, getDefinition: imported.getDefinition, handlers: Object.freeze([...definition.handlers]),
+    hooks,
+  });
+}
+
+export function parseHooksExport(module: Record<string, unknown>, name: string): Readonly<Record<string, FlowHook>> {
+  const exported = module['hooks'];
+  if (exported === undefined) return Object.freeze({});
+  if (typeof exported !== 'object' || exported === null || Array.isArray(exported)) {
+    throw new PluginError('plugin_manifest_invalid', `${name}: hooks export must be a record of functions.`);
+  }
+  const hooks: Record<string, FlowHook> = {};
+  for (const [key, value] of Object.entries(exported)) {
+    if (typeof value !== 'function') {
+      throw new PluginError('plugin_manifest_invalid', `${name}: hooks.${key} is not a function.`);
+    }
+    hooks[key] = value as FlowHook;
+  }
+  return Object.freeze(hooks);
+}
+
+/** Extensions declared by the project that owns `flowPath`, verified and loaded in lock order; empty when none are declared. */
+export async function loadFlowExtensions<Authority>(
+  flowPath: string,
+  base: { readonly definition: AuthoredFlowDefinition; readonly surfaceAuthority: Authority },
+  options: LoadFlowExtensionsOptions<Authority>,
+): Promise<readonly LoadedFlowExtension[]> {
+  const root = findPluginProject(dirname(flowPath));
+  if (root === undefined) return Object.freeze([]);
+  const declared = reconcileDeclaredExtensions(root);
+  const loaded: LoadedFlowExtension[] = [];
+  for (const { ref, entry } of declared) loaded.push(await loadOne(root, entry, ref, base, options));
+  return Object.freeze(loaded);
+}
+
+/** The base definition with extension handlers appended in lock order; the base's own fields are untouched. */
+export function composeDefinition<Input>(base: AuthoredFlowDefinition<Input>, extensions: readonly LoadedFlowExtension[]): AuthoredFlowDefinition<Input> {
+  if (extensions.length === 0) return base;
+  return Object.freeze({
+    ...base,
+    handlers: Object.freeze([...base.handlers, ...extensions.flatMap(extension => extension.handlers)]),
+  });
+}

package/src/flow-extension-manifest.ts

@@ -0,0 +1,190 @@
+import { Ajv } from 'ajv';
+import { providerEventTypes } from '@relayflows/surface';
+import { FLOW_HARNESSES } from './flow-requirements.js';
+import { snapshotJsonValue } from './json-value.js';
+import { PluginError, pluginKindOf } from './plugin-manifest.js';
+import { safePath } from './bundle.js';
+import { SHA, parsePluginSource, type PluginSourceInput } from './plugin-source.js';
+import { isVersionRange, parseVersion } from './semver-range.js';
+
+/**
+ * Schema 2, `kind: "flow-extension"`: a plugin whose `entry` default-exports
+ * `flow()` and contributes handlers, hooks, and gates to a base flow. It is the
+ * same `flows-plugin.json` file and the same preflight covenant as a helper
+ * plugin (RFC-0001 decision 13); only the kind decides which validator reads it.
+ * Helper manifests (`kind` absent) never reach this module.
+ *
+ * This slice validates and records the declaration. Runtime composition is
+ * refused with `plugin_unsupported` (plugin-loader.ts) until the handlers slice.
+ */
+export interface FlowExtensionTrigger { readonly provider: string; readonly event: string; readonly actions: readonly string[] }
+export interface FlowExtensionCompat {
+  readonly surface: string;
+  readonly sdk: string;
+  readonly base: readonly { readonly name: string; readonly version: string }[];
+}
+export interface FlowExtensionPermissions {
+  readonly integrations: readonly string[];
+  readonly harnesses: readonly string[];
+  readonly mcp: readonly string[];
+  /** Declared effect classes, shown for review; not enforced by this runtime (gate 8 / #442). */
+  readonly writes: readonly string[];
+  readonly budget?: { readonly dollars?: number; readonly wallclock?: string };
+}
+export interface FlowExtensionManifest {
+  readonly schema: 2;
+  readonly kind: 'flow-extension';
+  readonly name: string;
+  readonly version: string;
+  readonly description?: string;
+  /** Authoring copies may omit it; `flows add` records the resolved origin in the lockfile regardless. */
+  readonly source?: PluginSourceInput & { readonly sha?: string };
+  readonly compat: FlowExtensionCompat;
+  readonly entry: string;
+  readonly extends: { readonly handlers: boolean; readonly hooks: readonly string[] };
+  readonly triggers: readonly FlowExtensionTrigger[];
+  readonly permissions: FlowExtensionPermissions;
+  readonly preflight: { readonly credentials: readonly string[]; readonly servers: readonly string[] };
+  readonly config?: Record<string, unknown>;
+}
+
+const TOP_LEVEL = new Set(['schema', 'kind', 'name', 'version', 'description', 'source', 'compat', 'entry', 'extends', 'triggers', 'gates', 'verbs', 'permissions', 'preflight', 'config']);
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PROVIDER = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const WRITE_CLASS = /^[a-z0-9-]+(?::[a-z0-9_-]+)+$/;
+const WALLCLOCK = /^\d+(?:ms|s|m|h|d)$/;
+const MAX_DESCRIPTION = 500;
+const MAX_LIST = 64;
+
+const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const invalid = (message: string): never => { throw new PluginError('plugin_manifest_invalid', message); };
+
+function stringList(value: unknown, what: string, pattern: RegExp): readonly string[] {
+  if (!Array.isArray(value) || value.length > MAX_LIST) return invalid(`${what} must be a list of at most ${MAX_LIST} strings.`);
+  const out: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== 'string' || !pattern.test(entry)) return invalid(`${what} has an invalid entry ${JSON.stringify(entry)}.`);
+    if (out.includes(entry)) return invalid(`${what} lists ${entry} twice.`);
+    out.push(entry);
+  }
+  return Object.freeze(out);
+}
+
+function compat(value: unknown): FlowExtensionCompat {
+  if (!object(value) || Object.keys(value).some(k => !['surface', 'sdk', 'base'].includes(k))) return invalid('compat expects surface, sdk, and base.');
+  for (const key of ['surface', 'sdk'] as const) {
+    if (typeof value[key] !== 'string' || !isVersionRange(value[key])) return invalid(`compat.${key} must be a version range (*, x.y.z, ^x.y.z, ~x.y.z, >=x.y.z [<a.b.c]).`);
+  }
+  if (!Array.isArray(value.base) || value.base.length === 0 || value.base.length > MAX_LIST) return invalid('compat.base must name at least one base flow.');
+  const base = value.base.map(entry => {
+    if (!object(entry) || Object.keys(entry).some(k => !['name', 'version'].includes(k))
+      || typeof entry.name !== 'string' || entry.name.trim().length === 0 || entry.name.length > 100
+      || typeof entry.version !== 'string' || !isVersionRange(entry.version)) return invalid('compat.base entries are { name, version range }.');
+    return Object.freeze({ name: entry.name, version: entry.version });
+  });
+  if (new Set(base.map(b => b.name)).size !== base.length) return invalid('compat.base names a base flow twice.');
+  return Object.freeze({ surface: value.surface as string, sdk: value.sdk as string, base: Object.freeze(base) });
+}
+
+function triggers(value: unknown): readonly FlowExtensionTrigger[] {
+  if (!Array.isArray(value) || value.length > MAX_LIST) return invalid('triggers must be a list.');
+  const registry = providerEventTypes as Readonly<Record<string, readonly string[]>>;
+  const seen = new Set<string>();
+  return Object.freeze(value.map(entry => {
+    if (!object(entry) || Object.keys(entry).some(k => !['provider', 'event', 'actions'].includes(k))
+      || typeof entry.provider !== 'string' || !PROVIDER.test(entry.provider)
+      || typeof entry.event !== 'string' || !IDENTIFIER.test(entry.event)) return invalid('triggers entries are { provider, event, actions }.');
+    const actions = stringList(entry.actions, `triggers ${entry.provider}.${entry.event} actions`, IDENTIFIER);
+    const known = registry[entry.provider];
+    // Fail where ingress would: an event the surface registry cannot lower is
+    // refused now, not after deployment on the first real delivery.
+    if (known === undefined) throw new PluginError('plugin_event_unroutable', `Trigger provider ${entry.provider} is not in the surface event registry.`);
+    const unroutable = (actions.length === 0 ? [entry.event] : actions.map(a => `${entry.event}.${a}`)).filter(type => !known.includes(type));
+    if (unroutable.length > 0) throw new PluginError('plugin_event_unroutable', `Trigger ${entry.provider} ${unroutable.join(', ')} is not in the surface event registry.`);
+    const key = `${entry.provider}:${entry.event}`;
+    if (seen.has(key)) return invalid(`Trigger ${key} is declared twice.`);
+    seen.add(key);
+    return Object.freeze({ provider: entry.provider, event: entry.event, actions });
+  }));
+}
+
+function permissions(value: unknown): FlowExtensionPermissions {
+  if (!object(value) || Object.keys(value).some(k => !['integrations', 'harnesses', 'mcp', 'writes', 'budget'].includes(k))) {
+    return invalid('permissions expects integrations, harnesses, mcp, writes, and optional budget.');
+  }
+  const harnesses = stringList(value.harnesses, 'permissions.harnesses', /^[a-z]+$/);
+  for (const harness of harnesses) if (!(FLOW_HARNESSES as readonly string[]).includes(harness)) return invalid(`permissions.harnesses: unknown harness ${harness}.`);
+  let budget: FlowExtensionPermissions['budget'];
+  if (value.budget !== undefined) {
+    if (!object(value.budget) || Object.keys(value.budget).some(k => !['dollars', 'wallclock'].includes(k))) return invalid('permissions.budget expects dollars and/or wallclock.');
+    if (value.budget.dollars !== undefined && (typeof value.budget.dollars !== 'number' || !(value.budget.dollars > 0) || !Number.isFinite(value.budget.dollars))) return invalid('permissions.budget.dollars must be a positive number.');
+    if (value.budget.wallclock !== undefined && (typeof value.budget.wallclock !== 'string' || !WALLCLOCK.test(value.budget.wallclock))) return invalid('permissions.budget.wallclock must be a duration such as 45m.');
+    budget = Object.freeze({ ...(value.budget.dollars === undefined ? {} : { dollars: value.budget.dollars }), ...(value.budget.wallclock === undefined ? {} : { wallclock: value.budget.wallclock }) });
+  }
+  return Object.freeze({
+    integrations: stringList(value.integrations, 'permissions.integrations', PROVIDER),
+    harnesses,
+    mcp: stringList(value.mcp, 'permissions.mcp', /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/),
+    writes: stringList(value.writes, 'permissions.writes', WRITE_CLASS),
+    ...(budget === undefined ? {} : { budget }),
+  });
+}
+
+function source(value: unknown): FlowExtensionManifest['source'] {
+  if (!object(value) || Object.keys(value).some(k => !['host', 'owner', 'repo', 'sha', 'path'].includes(k))
+    || value.host !== 'github' || typeof value.owner !== 'string' || typeof value.repo !== 'string'
+    || (value.path !== undefined && typeof value.path !== 'string')
+    || (value.sha !== undefined && (typeof value.sha !== 'string' || !SHA.test(value.sha)))) {
+    return invalid('source expects { host: "github", owner, repo, path, sha? }.');
+  }
+  const path = (value.path as string | undefined) ?? '';
+  const parsed = parsePluginSource(`github:${value.owner}/${value.repo}@${(value.sha as string | undefined) ?? 'HEAD'}${path === '' ? '' : `#${path}`}`);
+  return Object.freeze({ ...parsed, ...(value.sha === undefined ? {} : { sha: value.sha as string }) });
+}
+
+export function validateFlowExtensionManifest(input: unknown): FlowExtensionManifest {
+  let v: unknown;
+  try { v = snapshotJsonValue(input, 'plugin manifest'); }
+  catch { return invalid('Plugin manifest must be JSON data.'); }
+  if (!object(v)) return invalid('Expected a plugin manifest object.');
+  if (pluginKindOf(v) !== 'flow-extension') throw new PluginError('plugin_kind_invalid', 'Expected kind "flow-extension".');
+  if (v.schema !== 2) return invalid('A flow-extension manifest is schema 2.');
+  const unknown = Object.keys(v).filter(k => !TOP_LEVEL.has(k));
+  if (unknown.length > 0) return invalid(`Unknown manifest fields: ${unknown.join(', ')}.`);
+  if (!Object.hasOwn(v, 'preflight')) throw new PluginError('plugin_preflight_missing', 'Plugin must declare preflight.');
+  if (typeof v.name !== 'string' || !NAME.test(v.name) || v.name.startsWith('helper-')) return invalid('name must be lowercase kebab-case and must not start with helper-.');
+  if (typeof v.version !== 'string' || parseVersion(v.version) === undefined) return invalid('version must be semver x.y.z.');
+  if (v.description !== undefined && (typeof v.description !== 'string' || v.description.length > MAX_DESCRIPTION)) return invalid(`description must be a string of at most ${MAX_DESCRIPTION} characters.`);
+  if (typeof v.entry !== 'string' || !v.entry.endsWith('.flow.ts') || !safePath(v.entry)) return invalid('entry must be a plugin-relative .flow.ts path.');
+  if (!object(v.extends) || Object.keys(v.extends).some(k => !['handlers', 'hooks', 'verbs', 'gates'].includes(k)) || typeof v.extends.handlers !== 'boolean') return invalid('extends expects { handlers: boolean, hooks: [] }.');
+  const hooks = stringList(v.extends.hooks ?? [], 'extends.hooks', NAME);
+  for (const [field, at] of [['verbs', v.extends.verbs], ['gates', v.extends.gates], ['verbs', v.verbs], ['gates', v.gates]] as const) {
+    if (at !== undefined && (!Array.isArray(at) || at.length > 0)) return invalid(`A flow extension declares no ${field}; ship a helper plugin beside it.`);
+  }
+  if (!v.extends.handlers && hooks.length === 0) return invalid('A flow extension must contribute handlers or at least one hook.');
+  if (!object(v.preflight) || Object.keys(v.preflight).some(k => !['credentials', 'servers'].includes(k))) return invalid('Preflight requires credentials and servers arrays.');
+  const credentials = stringList(v.preflight.credentials, 'preflight.credentials', IDENTIFIER);
+  const servers = stringList(v.preflight.servers, 'preflight.servers', /^https?:\/\/\S+$/);
+  for (const server of servers) {
+    try { if (!['http:', 'https:'].includes(new URL(server).protocol)) return invalid('Servers must be HTTP(S) URLs.'); }
+    catch { return invalid('Servers must be HTTP(S) URLs.'); }
+  }
+  let config: Record<string, unknown> | undefined;
+  if (v.config !== undefined) {
+    if (!object(v.config)) return invalid('config must be a JSON Schema object.');
+    try { new Ajv({ strict: false }).compile(v.config); } catch { return invalid('config is not a valid JSON Schema.'); }
+    config = v.config;
+  }
+  return Object.freeze({
+    schema: 2, kind: 'flow-extension', name: v.name, version: v.version,
+    ...(v.description === undefined ? {} : { description: v.description }),
+    ...(v.source === undefined ? {} : { source: source(v.source) }),
+    compat: compat(v.compat), entry: v.entry,
+    extends: Object.freeze({ handlers: v.extends.handlers, hooks }),
+    triggers: triggers(v.triggers ?? []),
+    permissions: permissions(v.permissions),
+    preflight: Object.freeze({ credentials, servers }),
+    ...(config === undefined ? {} : { config }),
+  });
+}

package/src/flow-extension-submit.ts

@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sha256 } from './bundle.js';
+import { CloudFlowError } from './cloud-http.js';
+import { extensionManifestOf } from './cli/add-extension.js';
+import { assertCompatible, runtimeVersions } from './flow-extension-compat.js';
+import type { LoadedAuthoredFlow } from './authored-flow-loader.js';
+import type { FlowExtensionManifest } from './flow-extension-manifest.js';
+import { probeFlowExtension, type LoadedFlowExtension } from './flow-extension-loader.js';
+import { fetchGithubPlugin, MAX_PLUGIN_TOTAL_BYTES, resolveGithubSha, type FetchLike } from './plugin-github.js';
+import { PluginError } from './plugin-manifest.js';
+import { canonicalPluginRef, parsePluginSource } from './plugin-source.js';
+import { readStoredPluginFiles } from './plugin-store.js';
+
+export const MAX_EXTENSIONS_BYTES = MAX_PLUGIN_TOTAL_BYTES;
+
+export interface FlowExtensionFileSubmission {
+  readonly path: string;
+  readonly sha256: string;
+  readonly bytes: number;
+  readonly encoding: 'utf8' | 'base64';
+  readonly content: string;
+}
+
+export interface FlowExtensionSubmission {
+  readonly name: string;
+  readonly version: string;
+  readonly ref: string;
+  readonly digest: string;
+  readonly manifestSha256: string;
+  readonly manifest: FlowExtensionManifest;
+  readonly files: readonly FlowExtensionFileSubmission[];
+}
+
+function encodeFile(path: string, data: Uint8Array): FlowExtensionFileSubmission {
+  const text = Buffer.from(data).toString('utf8');
+  const utf8 = Buffer.from(text, 'utf8').equals(Buffer.from(data));
+  return {
+    path,
+    sha256: sha256(data),
+    bytes: data.length,
+    encoding: utf8 ? 'utf8' : 'base64',
+    content: utf8 ? text : Buffer.from(data).toString('base64'),
+  };
+}
+
+async function submissionFromStore(extension: LoadedFlowExtension): Promise<FlowExtensionSubmission> {
+  const stored = await readStoredPluginFiles(extension.directory, extension.digest);
+  const files = stored.filter(file => file.path !== 'manifest.json').map(file => encodeFile(file.path, file.data));
+  const manifestBytes = readFileSync(join(extension.directory, 'flows-plugin.json'));
+  return {
+    name: extension.name, version: extension.version, ref: extension.ref, digest: extension.digest,
+    manifestSha256: sha256(manifestBytes),
+    manifest: extension.manifest,
+    files,
+  };
+}
+
+/** Resolve a GitHub plugin reference without writing the working tree. */
+export async function resolveExtensionSubmission(
+  input: string,
+  options: { fetch?: FetchLike; versions?: { sdk: string; surface: string } } = {},
+): Promise<FlowExtensionSubmission> {
+  try {
+    const source = await resolveGithubSha(parsePluginSource(input), options.fetch);
+    const fetched = await fetchGithubPlugin(source, options.fetch);
+    const { manifest, manifestSha256 } = extensionManifestOf(fetched);
+    assertCompatible(manifest, options.versions ?? runtimeVersions());
+    const files = fetched.files.map(file => encodeFile(file.path, file.data));
+    return {
+      name: manifest.name, version: manifest.version, ref: canonicalPluginRef(source),
+      digest: fetched.digest, manifestSha256, manifest, files,
+    };
+  } catch (error) {
+    if (error instanceof CloudFlowError) throw error;
+    if (error instanceof PluginError) throw new CloudFlowError('invalid_input', error.message);
+    throw new CloudFlowError('invalid_input', error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * Installed extensions plus optional send-only `--plugin` refs. Caps the
+ * extensions field at 2 MB separately from the 256 KB source cap.
+ */
+export async function collectExtensionSubmissions(
+  loaded: LoadedAuthoredFlow,
+  extraRefs: readonly string[] = [],
+  options: { fetch?: FetchLike } = {},
+): Promise<readonly FlowExtensionSubmission[]> {
+  const submissions: FlowExtensionSubmission[] = [];
+  for (const extension of loaded.extensions) submissions.push(await submissionFromStore(extension));
+  const names = new Set(submissions.map(s => s.name));
+  for (const ref of extraRefs) {
+    const extra = await resolveExtensionSubmission(ref, options);
+    if (names.has(extra.name)) {
+      throw new CloudFlowError('invalid_input', `Plugin ${extra.name} is already in this project; omit --plugin or remove the installed copy.`);
+    }
+    names.add(extra.name);
+    submissions.push(extra);
+  }
+  const total = Buffer.byteLength(JSON.stringify(submissions), 'utf8');
+  if (total > MAX_EXTENSIONS_BYTES) {
+    throw new CloudFlowError('invalid_input', `Flow extensions exceed Cloud's ${MAX_EXTENSIONS_BYTES}-byte extensions cap.`);
+  }
+  try {
+    for (const submission of submissions) await probeFlowExtension(submission.manifest);
+  } catch (error) {
+    if (error instanceof PluginError) throw new CloudFlowError('invalid_input', error.message);
+    throw error;
+  }
+  return submissions;
+}
+
+/** Graph nodes besides the root must be the composed extensions, not `use:` children. */
+export function assertNoUseDependencies(loaded: LoadedAuthoredFlow): void {
+  if (loaded.graph.length !== 1 + loaded.extensions.length) {
+    throw new CloudFlowError('unsupported_source',
+      'Cloud deploys one self-contained .flow.ts source without use dependencies.');
+  }
+}

package/src/flow-requirements.ts

@@ -26,9 +26,9 @@ export type FlowHarness = (typeof FLOW_HARNESSES)[number];
 export interface FlowIntegrationRequirement {
   /** Cloud integration provider id (`slack`, `github`, `linear`, …). */
   provider: string;
-  /** `tools`: a header declaration; `source`: a trigger or deploy target; `helper`: body use without a flag, or a YAML helper step. */
-  from: 'tools' | 'source' | 'helper' | 'human';
-  /** The declaration that requires it, as a reader would name it: `tools.slack`, `--on github`, `f.slack`, `f.human to`. */
+  /** Where this need was declared: a header/source/helper/human route, or an extension manifest. */
+  from: 'tools' | 'source' | 'helper' | 'human' | 'extension';
+  /** The declaration that requires it, as a reader would name it: `tools.slack`, `--on github`, `f.slack`, or `plugin "name"`. */
   detail: string;
 }
 
@@ -56,6 +56,47 @@ export interface FlowRequirementsContext {
   projectCli?: string;
 }
 
+export interface FlowExtensionRequirements {
+  readonly name: string;
+  readonly permissions: {
+    readonly integrations: readonly string[];
+    readonly harnesses: readonly string[];
+    readonly mcp: readonly string[];
+  };
+}
+
+/** Add manifest-only needs without replacing the base flow's first declaration. */
+export function mergeFlowExtensionRequirements(
+  base: FlowRequirements,
+  extensions: readonly FlowExtensionRequirements[],
+): FlowRequirements {
+  const integrations = [...base.integrations];
+  const integrationNames = new Set(integrations.map(entry => entry.provider));
+  const harnessUses = [...base.harnessUses];
+  const harnessNames = new Set<string>(base.harnesses);
+  const mcp = [...base.mcp];
+  const mcpNames = new Set(mcp);
+
+  for (const extension of extensions) {
+    for (const provider of extension.permissions.integrations) {
+      if (integrationNames.has(provider)) continue;
+      integrationNames.add(provider);
+      integrations.push({ provider, from: 'extension', detail: `plugin "${extension.name}"` });
+    }
+    for (const harness of extension.permissions.harnesses) {
+      if (harnessNames.has(harness)) continue;
+      harnessNames.add(harness);
+      harnessUses.push({ harness: harness as FlowHarness, detail: `plugin "${extension.name}"` });
+    }
+    for (const server of extension.permissions.mcp) {
+      if (mcpNames.has(server)) continue;
+      mcpNames.add(server);
+      mcp.push(server);
+    }
+  }
+  return { integrations, harnesses: harnessUses.map(use => use.harness), harnessUses, mcp };
+}
+
 /** The inert subset of an authored definition this module reads. */
 export interface RequirementsFlowDefinition {
   readonly header?: { readonly tools?: Readonly<Record<string, unknown>> };