@relayflows/sdk 2.0.24 → 2.0.26

package/src/authored-hooks.ts

@@ -0,0 +1,136 @@
+import type { Ctx } from '@relayflows/surface';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { LoadedFlowExtension } from './flow-extension-loader.js';
+import type { JournalClient } from './journal-client.js';
+
+const HOOK_STREAM = 'hooks';
+
+export interface HookRecord {
+  hook: string;
+  step: string;
+  plugin: string | null;
+  verdict: 'pass' | 'fail' | 'noop';
+  because?: string;
+  /** Parent `nextStep` after this verdict, so resume does not reuse inner step ids. */
+  afterStep?: number;
+}
+
+function recordKey(record: HookRecord): string {
+  return `${record.step}:${record.plugin ?? 'noop'}`;
+}
+
+/**
+ * AND-compose installed hook implementations in lock order. Verdicts are
+ * appended to the root run's `hooks` stream before the boolean is returned,
+ * so a resume reads the recorded verdict and never re-runs the closure.
+ * No implementations is a journaled no-op returning true. A false short-circuits.
+ */
+export function createHookEvaluator(options: {
+  readonly journal: JournalClient;
+  readonly rootRunId?: string;
+  readonly flowName: string;
+  readonly declared: readonly string[];
+  readonly extensions: readonly LoadedFlowExtension[];
+  readonly peekStep?: () => number;
+  readonly restoreStep?: (step: number) => void;
+  readonly signal?: AbortSignal;
+}): (id: string, name: string, input: unknown, context: Ctx) => Promise<boolean> {
+  let recorded: Promise<Map<string, HookRecord>> | undefined;
+
+  async function load(): Promise<Map<string, HookRecord>> {
+    const verdicts = new Map<string, HookRecord>();
+    if (options.rootRunId === undefined) return verdicts;
+    let offset = 0;
+    for (;;) {
+      const page = await options.journal.streamRead(options.rootRunId, HOOK_STREAM, offset, 1000);
+      for (const message of page.messages) {
+        const raw = (message as { message?: unknown }).message ?? message;
+        if (typeof raw !== 'object' || raw === null) continue;
+        const record = raw as HookRecord;
+        if (typeof record.hook !== 'string' || typeof record.step !== 'string') continue;
+        if (record.verdict !== 'pass' && record.verdict !== 'fail' && record.verdict !== 'noop') continue;
+        if (record.plugin !== null && typeof record.plugin !== 'string') continue;
+        verdicts.set(recordKey(record), record);
+      }
+      if (page.messages.length === 0 || page.next_offset <= offset) break;
+      offset = page.next_offset;
+    }
+    return verdicts;
+  }
+
+  async function lookup(key: string): Promise<HookRecord | undefined> {
+    if (options.rootRunId === undefined) return undefined;
+    recorded ??= load();
+    return (await recorded).get(key);
+  }
+
+  async function append(record: HookRecord): Promise<void> {
+    if (options.rootRunId === undefined) return;
+    recorded ??= load();
+    await options.journal.streamAppend(options.rootRunId, HOOK_STREAM, record);
+    (await recorded).set(recordKey(record), record);
+  }
+
+  return async (id, name, input, context) => {
+    if (!options.declared.includes(name)) {
+      throw new AuthoredFlowExecutionError(
+        'unsupported_verb',
+        `hook "${name}" is not declared by flow "${options.flowName}"`,
+      );
+    }
+    const impls = options.extensions.filter(extension => extension.hooks[name] !== undefined);
+    if (impls.length === 0) {
+      const existing = await lookup(`${id}:noop`);
+      const record = existing ?? { hook: name, step: id, plugin: null, verdict: 'noop' as const };
+      if (existing === undefined) await append(record);
+      else if (existing.afterStep !== undefined) options.restoreStep?.(existing.afterStep);
+      return true;
+    }
+    for (const extension of impls) {
+      const key = `${id}:${extension.name}`;
+      let record = await lookup(key);
+      if (record === undefined) {
+        let verdict = false;
+        let because: string | undefined;
+        try {
+          verdict = await boundHook(extension.hooks[name]!(context, input), options.signal) === true;
+        } catch (error) {
+          // Cancellation is control-plane state, not a plugin verdict. The
+          // shared execution signal also stops tracked f.run/f.agent work;
+          // rethrow so a later resume may run the hook again instead of
+          // replaying a permanent decline caused by an interrupted attempt.
+          if (options.signal?.aborted) throw error;
+          verdict = false;
+          because = error instanceof Error ? error.message : String(error);
+        }
+        record = {
+          hook: name, step: id, plugin: extension.name,
+          verdict: verdict ? 'pass' : 'fail',
+          ...(because === undefined ? {} : { because }),
+          ...(options.peekStep === undefined ? {} : { afterStep: options.peekStep() }),
+        };
+        await append(record);
+      } else if (record.afterStep !== undefined) {
+        options.restoreStep?.(record.afterStep);
+      }
+      if (record.verdict === 'fail') return false;
+    }
+    return true;
+  };
+}
+
+async function boundHook(run: Promise<boolean>, signal?: AbortSignal): Promise<boolean> {
+  // The parent run's wallclock budget owns the deadline. A second timer here
+  // would not be the signal captured by the hook's Ctx operations, allowing
+  // those operations to continue after this wrapper returned.
+  if (signal === undefined) return await run;
+  if (signal.aborted) throw signal.reason ?? new Error('hook cancelled');
+  return await new Promise<boolean>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason ?? new Error('hook cancelled'));
+    signal.addEventListener('abort', onAbort, { once: true });
+    run.then(
+      value => { signal.removeEventListener('abort', onAbort); resolve(value); },
+      error => { signal.removeEventListener('abort', onAbort); reject(error); },
+    );
+  });
+}

package/src/authored-node-entry.ts

@@ -72,6 +72,7 @@ try {
     request.metadata.inputPresent ? request.metadata.input : undefined, {
       getDefinition: loaded.getDefinition, dataDir: request.dataDir,
       flowPath: request.metadata.flowPath, rootRunId: request.rootRunId,
+      extensions: loaded.extensions,
       localAgentStream: request.localAgentStream, signal: controller.signal,
       onProgress: event => send({ type: 'progress', event }),
       onWait: event => send({ type: 'wait', event }),

package/src/authored-root.ts

@@ -21,6 +21,12 @@ import { isSurfaceCompletionReason } from './authored-step-output.js';
 
 const ROOT_KIND = 'relayflows.authored-root.v1';
 
+export interface AuthoredRootExtension {
+  readonly name: string;
+  readonly digest: string;
+  readonly ref: string;
+}
+
 export interface AuthoredRootMetadata {
   readonly kind: typeof ROOT_KIND;
   readonly flowName: string;
@@ -28,6 +34,8 @@ export interface AuthoredRootMetadata {
   readonly sourceSha256: string;
   readonly surface: SurfaceModuleAuthority;
   readonly sources: readonly AuthoredRootSourceAuthority[];
+  /** Plugin-level provenance in lock order; empty when the project declares none. */
+  readonly extensions: readonly AuthoredRootExtension[];
   readonly localAgentStream?: string;
   readonly inputPresent: boolean;
   readonly input?: unknown;
@@ -68,6 +76,9 @@ export async function executeDurableAuthoredFlow(
     sourceSha256: sha256(source),
     surface: loaded.surfaceAuthority,
     sources: Object.freeze(sources),
+    extensions: Object.freeze((loaded.extensions ?? []).map(extension => Object.freeze({
+      name: extension.name, digest: extension.digest, ref: extension.ref,
+    }))),
     ...(options.localAgentStream === undefined ? {} : { localAgentStream: options.localAgentStream }),
     inputPresent: input !== undefined,
     ...(input === undefined ? {} : { input: jsonSnapshot(input, 'authored root input') }),
@@ -172,7 +183,7 @@ export async function readAuthoredRootMetadata(
   if (!isRootMetadata(value)) {
     throw new Error('authored root journal has malformed authority metadata');
   }
-  return value;
+  return Object.freeze({ ...value, extensions: value.extensions ?? [] });
 }
 
 async function driveRoot(
@@ -203,6 +214,7 @@ async function driveRoot(
           flowPath: metadata.flowPath,
           localAgentStream: options.localAgentStream,
           rootRunId: dispatch.run_id,
+          extensions: loaded.extensions,
           ...options.lifecycle,
           signal: callerSignal === undefined
             ? rootSignal
@@ -409,10 +421,19 @@ function isRootMetadata(value: unknown): value is AuthoredRootMetadata {
     && typeof surface.version === 'string' && /^[a-f0-9]{64}$/.test(surface.packageSha256 ?? '')
     && /^[a-f0-9]{64}$/.test(surface.runtimeSha256 ?? '')
     && Array.isArray(sources) && sources.length > 0 && sources.every(isRootSourceAuthority)
+    && (root.extensions === undefined || (Array.isArray(root.extensions) && root.extensions.every(isRootExtension)))
     && (root.localAgentStream === undefined
       || /^local-agent-[a-f0-9-]+$/.test(root.localAgentStream));
 }
 
+function isRootExtension(value: unknown): value is AuthoredRootExtension {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const extension = value as Partial<AuthoredRootExtension>;
+  return typeof extension.name === 'string' && extension.name.length > 0
+    && /^[a-f0-9]{64}$/.test(extension.digest ?? '')
+    && typeof extension.ref === 'string' && extension.ref.startsWith('github:');
+}
+
 function isRootSourceAuthority(value: unknown): value is AuthoredRootSourceAuthority {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
   const source = value as Partial<AuthoredRootSourceAuthority>;

package/src/authored-source-authority.ts

@@ -35,6 +35,12 @@ export async function loadPinnedAuthoredSource(metadata: AuthoredRootMetadata, i
   if (canonicalize(loadedSources) !== canonicalize(metadata.sources)) {
     throw new Error('authored root declared source graph authority mismatch');
   }
+  const loadedExtensions = (loaded.extensions ?? []).map(extension => ({
+    name: extension.name, digest: extension.digest, ref: extension.ref,
+  }));
+  if (canonicalize(loadedExtensions) !== canonicalize(metadata.extensions ?? [])) {
+    throw new Error('authored root declared extension authority mismatch');
+  }
   return loaded;
 }
 

package/src/babysitter-catalog-export.ts

@@ -0,0 +1,44 @@
+import { assertBaseCompatible } from './flow-extension-compat.js';
+import { resolveExtensionSubmission, type FlowExtensionSubmission } from './flow-extension-submit.js';
+import { canonicalPluginRef, parseCanonicalPluginRef } from './plugin-source.js';
+
+export interface BabysitterCatalogPin {
+  readonly ref: string;
+  readonly digest: string;
+  readonly manifestSha256: string;
+}
+
+/** Export reviewed bytes, never execute the entry or infer runtime readiness. */
+export async function exportBabysitterCatalogBundle(
+  pin: BabysitterCatalogPin,
+  options: Parameters<typeof resolveExtensionSubmission>[1] = {},
+): Promise<FlowExtensionSubmission> {
+  const source = parseCanonicalPluginRef(pin.ref);
+  if (canonicalPluginRef(source) !== pin.ref || source.owner !== 'AgentWorkforce' || source.repo !== 'flows') {
+    throw new Error('Babysitter catalog source must be a canonical AgentWorkforce/flows commit ref.');
+  }
+  if (![pin.digest, pin.manifestSha256].every(value => /^[0-9a-f]{64}$/.test(value))) {
+    throw new Error('Expected reviewed bundle and manifest SHA-256 digests.');
+  }
+  const bundle = await resolveExtensionSubmission(pin.ref, options);
+  if (bundle.ref !== pin.ref || bundle.digest !== pin.digest || bundle.manifestSha256 !== pin.manifestSha256) {
+    throw new Error('Babysitter artifact differs from the reviewed pin.');
+  }
+  const manifest = bundle.manifest;
+  if (manifest.name !== 'babysitter') throw new Error('Expected the babysitter extension.');
+  assertBaseCompatible(manifest, { name: 'software-factory' });
+  const p = manifest.permissions;
+  const exactly = (values: readonly string[], expected: string) => values.length === 1 && values[0] === expected;
+  if (!exactly(p.integrations, 'github') || !exactly(p.harnesses, 'codex') || p.mcp.length !== 0
+    || !exactly(p.writes, 'cloud:babysitter-turn')) {
+    throw new Error('Babysitter requires only github, codex, no MCP, and cloud:babysitter-turn.');
+  }
+  if (!manifest.extends.handlers || manifest.extends.hooks.length !== 0) {
+    throw new Error('Native Babysitter must contribute handlers only, without merge hooks.');
+  }
+  // The validator normalizes optional source fields. The wire manifest must
+  // remain the actual digest-bound JSON so Cloud can independently parse it.
+  const file = bundle.files.find(entry => entry.path === 'flows-plugin.json')!;
+  const rawManifest = JSON.parse(Buffer.from(file.content, file.encoding).toString('utf8'));
+  return { ...bundle, manifest: rawManifest };
+}

package/src/bundle-extensions.ts

@@ -0,0 +1,85 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import type { BundleFile } from './bundle.js';
+import { safePath, sha256 } from './bundle.js';
+import { findPluginProject } from './plugin-loader.js';
+import { parsePluginLock, readPluginLock, reconcileDeclaredExtensions, type PluginLock } from './plugin-lock.js';
+import { PluginError } from './plugin-manifest.js';
+import { pluginStoreDirectory, readStoredPluginFiles, verifyStoredPlugin } from './plugin-store.js';
+
+const EMPTY_LOCK: PluginLock = Object.freeze({ version: 2, plugins: Object.freeze([]) });
+
+/**
+ * Plugin provenance and bytes to put in a sealed bundle: `lockfile.json` is
+ * the same v2 lock the project records, and each extension's materialized
+ * files land under `plugins/<name>/…`. No project / no github: plugins →
+ * `{ version: 2, plugins: [] }` and no files. Fail closed on lock/store drift.
+ */
+export async function collectBundleExtensions(flowPath: string): Promise<{ lock: PluginLock; files: BundleFile[] }> {
+  const root = findPluginProject(dirname(flowPath));
+  if (root === undefined) return { lock: EMPTY_LOCK, files: [] };
+  const locked = reconcileDeclaredExtensions(root);
+  const files: BundleFile[] = [];
+  for (const { entry } of locked) {
+    const stored = await readStoredPluginFiles(pluginStoreDirectory(root, entry.name, entry.digest), entry.digest);
+    for (const file of stored) files.push({ path: `plugins/${entry.name}/${file.path}`, data: file.data });
+  }
+  return { lock: readPluginLock(root), files };
+}
+
+/**
+ * After `verifyBundle` has hashed every payload file, check that `lockfile.json`
+ * is a v2 plugin lock (or a legacy v1 `{version:1, adapters}` with no plugins)
+ * and that each locked extension's store digest matches `plugins/<name>/manifest.json`.
+ */
+export async function verifyBundlePluginLock(bundle: string): Promise<void> {
+  let parsed: unknown;
+  try { parsed = JSON.parse(await readFile(join(bundle, 'lockfile.json'), 'utf8')); }
+  catch { throw new Error('lockfile.json: not valid JSON'); }
+  if (isLegacyV1Lock(parsed) || isLegacyNpmLock(parsed)) {
+    await assertNoLegacyPluginPayload(bundle);
+    return;
+  }
+  let lock: PluginLock;
+  try { lock = parsePluginLock(parsed); }
+  catch (error) {
+    throw new Error(error instanceof PluginError ? error.message : 'lockfile.json: not a plugin lock');
+  }
+  for (const entry of lock.plugins) {
+    if (!safePath(entry.name) || entry.name.includes('/')) {
+      throw new Error(`lockfile.json: plugin name ${entry.name} is not a safe path component`);
+    }
+    const directory = join(bundle, 'plugins', entry.name);
+    await verifyStoredPlugin(directory, entry.digest);
+    let pluginManifest: Buffer;
+    try { pluginManifest = await readFile(join(directory, 'flows-plugin.json')); }
+    catch { throw new Error(`lockfile.json: plugin ${entry.name} is missing plugins/${entry.name}/flows-plugin.json`); }
+    if (sha256(pluginManifest) !== entry.manifestSha256) {
+      throw new Error(`lockfile.json: plugin ${entry.name} flows-plugin.json does not match the lockfile manifest hash`);
+    }
+  }
+}
+
+async function assertNoLegacyPluginPayload(bundle: string): Promise<void> {
+  let entries: string[];
+  try { entries = await readdir(join(bundle, 'plugins')); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw error;
+  }
+  if (entries.length > 0) {
+    throw new Error('lockfile.json: legacy locks cannot authenticate plugins/ payloads');
+  }
+}
+
+function isLegacyV1Lock(value: unknown): boolean {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && (value as { version?: unknown }).version === 1
+    && Array.isArray((value as { adapters?: unknown }).adapters);
+}
+
+function isLegacyNpmLock(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const lock = value as { lockfileVersion?: unknown; packages?: unknown };
+  return (lock.lockfileVersion === 2 || lock.lockfileVersion === 3) && typeof lock.packages === 'object' && lock.packages !== null;
+}

package/src/bundle-typescript.ts

@@ -60,7 +60,7 @@ process.stdout.write(JSON.stringify({ spec, authored }));
       '--no-compile-autoload-bunfig', '--outfile', executable, input], directory);
     const files: BundleFile[] = [
       { path: 'flow', data: await readFile(executable) },
-      { path: 'lockfile.json', data: canonicalize(lock) },
+      { path: 'package-lock.json', data: canonicalize(lock) },
     ];
     return { spec, authored: inspected.authored === true, compiler, files };
   } finally { await rm(staging, { recursive: true, force: true }); }

package/src/bundle.ts

@@ -18,12 +18,24 @@ export function sha256(data: Uint8Array | string): string {
   return createHash('sha256').update(data).digest('hex');
 }
 
-function safePath(path: string): boolean {
+/** A bundle-relative path: no empty, `.`, or `..` component, no backslash, NUL, or drive colon. */
+export function safePath(path: string): boolean {
   return path.length > 0 && !path.includes('\\') && !path.includes('\0')
     && path.split('/').every(part => part !== '' && part !== '.' && part !== '..')
     && !path.includes(':');
 }
 
+/**
+ * The canonical entry list whose sha256 is a payload's content digest. Shared
+ * by sealed flow bundles and materialized plugins so `@sha256:` means one
+ * thing everywhere: the digest of `[{bytes,path,sha256}]`, sorted by path.
+ */
+export function payloadManifest(files: readonly { path: string; data: Uint8Array }[]): string {
+  return canonicalize([...files]
+    .sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
+    .map(file => ({ path: file.path, sha256: sha256(file.data), bytes: file.data.length })));
+}
+
 /** Manifest and identity are envelopes, excluded to avoid circular hashing. */
 export async function sealBundle(options: BundleOptions): Promise<string> {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(options.name)) {
@@ -41,9 +53,7 @@ export async function sealBundle(options: BundleOptions): Promise<string> {
   for (const required of ['spec.canonical.json', 'preflight.json', 'lockfile.json']) {
     if (!paths.has(required)) throw new Error(`${required}: missing bundle file`);
   }
-  const manifest = canonicalize(files.map(file => ({
-    path: file.path, sha256: sha256(file.data), bytes: file.data.length,
-  })));
+  const manifest = payloadManifest(files);
   const digest = sha256(manifest);
   const out = resolve(options.out);
   const target = join(out, `${options.name}@sha256:${digest}`);

package/src/cli/add-extension.ts

@@ -0,0 +1,134 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CliIo } from '../cli.js';
+import { sha256 } from '../bundle.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, type FetchedPlugin } from '../plugin-github.js';
+import { PLUGIN_LOCK_FILE, lockWithPlugin, readPluginLock, recoverFlowsAndLock, writeFlowsAndLock } 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 } from '../plugin-store.js';
+
+export { assertCompatible, runtimeVersions };
+
+/** Parse and validate the manifest inside a fetched plugin, checking that any self-declared source is the one it came from. */
+export function extensionManifestOf(plugin: FetchedPlugin): { manifest: FlowExtensionManifest; manifestSha256: string } {
+  const file = plugin.files.find(f => f.path === 'flows-plugin.json');
+  if (file === undefined) throw new PluginError('plugin_manifest_missing', 'Plugin has no flows-plugin.json.');
+  let input: unknown;
+  try { input = JSON.parse(file.data.toString('utf8')); }
+  catch { throw new PluginError('plugin_manifest_invalid', 'flows-plugin.json is unreadable or invalid JSON.'); }
+  const manifest = validateFlowExtensionManifest(input);
+  const { source } = plugin;
+  if (manifest.source !== undefined && (manifest.source.owner !== source.owner || manifest.source.repo !== source.repo || manifest.source.path !== source.path
+    || (manifest.source.sha !== undefined && manifest.source.sha !== source.sha))) {
+    throw new PluginError('plugin_source_drift', `flows-plugin.json declares source ${manifest.source.owner}/${manifest.source.repo}#${manifest.source.path}, but it was fetched from ${source.owner}/${source.repo}#${source.path}.`);
+  }
+  if (!plugin.files.some(f => f.path === manifest.entry)) throw new PluginError('plugin_manifest_invalid', `entry ${manifest.entry} is not in the plugin.`);
+  return { manifest, manifestSha256: sha256(file.data) };
+}
+
+function eventKeys(manifest: FlowExtensionManifest): readonly string[] {
+  return manifest.triggers.map(t => `${t.provider} ${t.event}[${t.actions.join(',')}]`);
+}
+
+function formatBudget(budget: FlowExtensionManifest['permissions']['budget']): string {
+  if (budget === undefined) return 'inherits base';
+  return [budget.dollars === undefined ? '' : `$${budget.dollars}`, budget.wallclock ?? ''].filter(Boolean).join(' / ') || 'inherits base';
+}
+
+export function describeExtension(manifest: FlowExtensionManifest): string[] {
+  const p = manifest.permissions;
+  return [
+    `  integrations: ${p.integrations.join(', ') || 'none'}; harnesses: ${p.harnesses.join(', ') || 'none'}; mcp: ${p.mcp.join(', ') || 'none'}`,
+    `  events: ${eventKeys(manifest).join('; ') || 'none'}`,
+    `  hooks: ${manifest.extends.hooks.join(', ') || 'none'}; handlers: ${manifest.extends.handlers ? 'yes' : 'no'}`,
+    `  writes (declared, unenforced): ${p.writes.join(', ') || 'none'}`,
+    `  budget: ${formatBudget(p.budget)}`,
+  ];
+}
+
+/** Permissions / events / budget (and version/hooks) changes between two manifests. */
+export function diffExtension(before: FlowExtensionManifest, after: FlowExtensionManifest): string[] {
+  const lines: string[] = [];
+  const change = (label: string, oldValue: string, newValue: string): void => {
+    if (oldValue !== newValue) lines.push(`  ${label}: ${oldValue} → ${newValue}`);
+  };
+  const setDiff = (label: string, oldList: readonly string[], newList: readonly string[]): void => {
+    const removed = oldList.filter(x => !newList.includes(x));
+    const added = newList.filter(x => !oldList.includes(x));
+    if (removed.length === 0 && added.length === 0) return;
+    lines.push(`  ${label}: ${[...removed.map(x => `-${x}`), ...added.map(x => `+${x}`)].join(', ')}`);
+  };
+  change('version', before.version, after.version);
+  setDiff('integrations', before.permissions.integrations, after.permissions.integrations);
+  setDiff('harnesses', before.permissions.harnesses, after.permissions.harnesses);
+  setDiff('mcp', before.permissions.mcp, after.permissions.mcp);
+  setDiff('writes', before.permissions.writes, after.permissions.writes);
+  setDiff('events', eventKeys(before), eventKeys(after));
+  setDiff('hooks', before.extends.hooks, after.extends.hooks);
+  change('budget', formatBudget(before.permissions.budget), formatBudget(after.permissions.budget));
+  if (lines.length === 0) lines.push('  (no permissions/events/budget changes)');
+  return lines;
+}
+
+export interface AddExtensionOptions {
+  cwd?: string;
+  fetch?: FetchLike;
+  now?: () => Date;
+  versions?: RuntimeVersions;
+}
+
+/**
+ * `flows add github:<owner>/<repo>@<ref>#<path>` — resolve the ref to a commit,
+ * fetch the plugin directory, validate its schema-2 manifest, materialize it
+ * under `.flows/plugins`, and record the canonical reference in `flows.json`
+ * plus the provenance in `flows.lock.json`. Runtime composition is a later
+ * slice: installing records a declaration, it does not enable execution.
+ */
+export async function addExtensionPlugin(input: string, io: CliIo, options: AddExtensionOptions = {}): Promise<0 | 2> {
+  try {
+    // Parse before touching the filesystem or the network: a malformed
+    // reference is refused offline, with the same code from any directory.
+    const requested = parsePluginSource(input);
+    const root = findPluginProject(options.cwd ?? process.cwd());
+    if (!root) throw new PluginError('plugin_manifest_invalid', 'flows add requires a project with flows.json.');
+    recoverFlowsAndLock(root);
+    const configPath = join(root, 'flows.json');
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    if (!config || Array.isArray(config) || typeof config !== 'object' || (config.plugins !== undefined && (!Array.isArray(config.plugins) || !config.plugins.every((p: unknown) => typeof p === 'string')))) throw new PluginError('plugin_manifest_invalid', 'Invalid flows.json plugins list.');
+    const lock = readPluginLock(root);
+    const source = await resolveGithubSha(requested, options.fetch);
+    const fetched = await fetchGithubPlugin(source, options.fetch);
+    const { manifest, manifestSha256 } = extensionManifestOf(fetched);
+    assertCompatible(manifest, options.versions ?? runtimeVersions());
+    const ref = canonicalPluginRef(source);
+    const declared: string[] = config.plugins ?? [];
+    for (const other of lock.plugins) {
+      if (other.name === manifest.name && canonicalPluginRef({ ...other.source, ref: other.source.sha }) !== ref) {
+        throw new PluginError('plugin_manifest_invalid', `Plugin ${manifest.name} is already installed from ${other.source.owner}/${other.source.repo}@${other.source.sha}; remove it before installing another source under the same name.`);
+      }
+    }
+    const { directory, digest } = await materializePlugin(root, manifest.name, fetched.files);
+    if (digest !== fetched.digest) throw new PluginError('plugin_source_drift', 'Materialized digest differs from the fetched digest.');
+    const plugins = declared.includes(ref) ? declared : [...declared, ref];
+    const next = lockWithPlugin(lock, plugins, {
+      name: manifest.name, version: manifest.version,
+      source: { host: 'github', owner: source.owner, repo: source.repo, sha: source.sha, path: source.path },
+      digest, manifestSha256, resolvedAt: (options.now ?? (() => new Date()))().toISOString(),
+    });
+    writeFlowsAndLock(root, configPath, config, plugins, next);
+    io.stdout(`Added ${manifest.name}@${manifest.version} (flow-extension) from ${ref}`);
+    io.stdout(`  digest sha256:${digest}`);
+    io.stdout(`  materialized at ${directory}`);
+    for (const line of describeExtension(manifest)) io.stdout(line);
+    io.stdout(`  recorded in flows.json and ${PLUGIN_LOCK_FILE}`);
+    return 0;
+  } catch (error) {
+    const refusal = error instanceof PluginError ? error : new PluginError('plugin_manifest_invalid', (error as Error).message);
+    io.stderr(`REFUSED [${refusal.code}] ${refusal.message}`);
+    return 2;
+  }
+}

package/src/cli/add.ts

@@ -3,16 +3,25 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { CliIo } from '../cli.js';
 import { findPluginProject, probePlugin, readPlugin } from '../plugin-loader.js';
+import { recoverFlowsAndLock } from '../plugin-lock.js';
 import { PluginError, pluginPackageName } from '../plugin-manifest.js';
+import { isGithubPluginRef } from '../plugin-source.js';
+import { addExtensionPlugin, type AddExtensionOptions } from './add-extension.js';
 
 export async function addPlugin(name: string, io: CliIo, options: {
   cwd?: string;
   install?: (packageName: string, root: string) => void;
+  /** GitHub-sourced flow extensions only; ignored for helper packages. */
+  extension?: Omit<AddExtensionOptions, 'cwd'>;
 } = {}): Promise<0 | 2> {
+  // A GitHub reference is a schema-2 flow extension; everything else is the
+  // helper-package path below, which this branch leaves exactly as it was.
+  if (isGithubPluginRef(name)) return addExtensionPlugin(name, io, { ...options.extension, ...(options.cwd === undefined ? {} : { cwd: options.cwd }) });
   try {
     const packageName = pluginPackageName(name);
     const root = findPluginProject(options.cwd ?? process.cwd());
     if (!root) throw new PluginError('plugin_manifest_invalid', 'flows add requires a project with flows.json.');
+    recoverFlowsAndLock(root);
     const configPath = join(root, 'flows.json');
     const config = JSON.parse(readFileSync(configPath, 'utf8'));
     if (!config || Array.isArray(config) || typeof config !== 'object' || (config.plugins !== undefined && (!Array.isArray(config.plugins) || !config.plugins.every((p: unknown) => typeof p === 'string')))) throw new PluginError('plugin_manifest_invalid', 'Invalid flows.json plugins list.');

package/src/cli/build.ts

@@ -2,6 +2,7 @@ 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 { collectBundleExtensions, verifyBundlePluginLock } from '../bundle-extensions.js';
 import { canonicalize } from '../canonical.js';
 import { compileSpec, toKernelSpec } from '../compile.js';
 import { preflight } from '../preflight.js';
@@ -60,6 +61,7 @@ export async function runBuild(args: BuildArgs, io: CliIo): Promise<0 | 2> {
   try {
     if (args.verify) {
       const digest = `sha256:${await verifyBundle(args.value)}`;
+      await verifyBundlePluginLock(args.value);
       // `--json` is declared on the verb, not on one of its forms: a verify
       // under it emits the same single object a `--json` consumer parses.
       if (args.json) io.stdout(JSON.stringify({ ok: true, verified: true, bundle: args.value, digest }));
@@ -107,7 +109,7 @@ export async function buildFlow(path: string, out: string, warn: (line: string)
     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: [] }) });
+    files.push({ path: 'lockfile.json', data: canonicalize({ version: 2, plugins: [] }) });
   } else throw new Error('build expects a .yaml, .yml, or .ts flow');
 
   // The current preflight API reports uncollected environment facts as
@@ -148,7 +150,10 @@ export async function buildFlow(path: string, out: string, warn: (line: string)
         ...(authored ? { dynamicSteps: 'exported spec declaration checked; body was not executed during build' } : {}) },
     }) },
   );
-  return sealBundle({ name: authoring.name ?? 'flow', out, files,
+  const extensions = await collectBundleExtensions(input);
+  const bundled = files.filter(file => file.path !== 'lockfile.json');
+  bundled.push({ path: 'lockfile.json', data: canonicalize(extensions.lock) }, ...extensions.files);
+  return sealBundle({ name: authoring.name ?? 'flow', out, files: bundled,
     repo: await repositoryRoot(directory), warn });
 }
 

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

@@ -1,4 +1,5 @@
 import { loadAuthoredFlow } from '../authored-flow-loader.js';
+import { PluginError } from '../plugin-manifest.js';
 import { checkSlackHelpers } from '../slack-preflight.js';
 import { inputFailureReport, type CheckExecution } from './check.js';
 
@@ -8,6 +9,9 @@ export async function checkHelperBody(path: string): Promise<CheckExecution> {
     const { handle, getDefinition } = await loadAuthoredFlow(path);
     return { report: { ...checkSlackHelpers(getDefinition(handle)), path } };
   } catch (error) {
+    if (error instanceof PluginError) {
+      return { report: inputFailureReport({ kind: error.code, message: error.message }, path) };
+    }
     return { report: inputFailureReport({ kind: 'invalid_spec',
       message: error instanceof Error ? error.message : 'Could not import authored flow.' }, path) };
   }