@relayflows/sdk 2.0.24 → 2.0.25

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) };
   }

package/src/cli/check-triggers.ts

@@ -1,10 +1,12 @@
 import { dirname, resolve } from 'node:path';
 import { loadAuthoredFlow, type LoadedAuthoredFlow } from '../authored-flow-loader.js';
+import { probeFlowExtension } from '../flow-extension-loader.js';
 import { preflightWebhookTriggers } from '../preflight.js';
 import { preflightProviderTriggers } from '../provider-trigger-contract.js';
 import { scheduleLowering } from '../schedule-trigger.js';
 import { checkSlackHelpers } from '../slack-preflight.js';
-import { flowRequirements } from '../flow-requirements.js';
+import { flowRequirements, mergeFlowExtensionRequirements } from '../flow-requirements.js';
+import { PluginError } from '../plugin-manifest.js';
 import { inputFailureReport, readProjectConfig, type CheckReport } from './check.js';
 
 /**
@@ -22,6 +24,7 @@ export async function checkAuthoredTriggers(path: string): Promise<{
     const loaded = await loadAuthoredFlow(path);
     const definition = loaded.getDefinition(loaded.handle);
     const config = readProjectConfig(dirname(resolve(path)));
+    for (const extension of loaded.extensions ?? []) await probeFlowExtension(extension.manifest);
     const triggers = (definition.handlers ?? []).map(handler => handler.trigger);
     const triggerDiagnostics = preflightWebhookTriggers(triggers, config.executors);
     // Registration answers "may this inbox run here"; the provider contract
@@ -40,6 +43,17 @@ export async function checkAuthoredTriggers(path: string): Promise<{
       const lowering = scheduleLowering(definition.name, trigger);
       return [{ handler, ...lowering }];
     });
+    // `?? []` tolerates the partial loader doubles the direct-run tests install.
+    const extensions = (loaded.extensions ?? []).map(extension => ({
+      name: extension.name, version: extension.version, ref: extension.ref, digest: extension.digest,
+      handlers: extension.handlers.length,
+      hooks: extension.manifest?.extends.hooks ?? [],
+    }));
+    const declaredHooks = definition.header?.hooks ?? [];
+    const implementations = (loaded.extensions ?? []).flatMap(extension =>
+      (extension.manifest?.extends.hooks ?? []).map(hook => ({ hook, plugin: extension.name })));
+    const hooks = declaredHooks.length > 0 || implementations.length > 0
+      ? { declared: declaredHooks, implementations } : undefined;
     return {
       loaded,
       report: {
@@ -47,11 +61,22 @@ export async function checkAuthoredTriggers(path: string): Promise<{
         ok: !diagnostics.some(diagnostic => diagnostic.severity === 'refusal'),
         path, gates: [], resolutions: [], diagnostics,
         ...(schedules.length === 0 ? {} : { schedules }),
-        requirements: flowRequirements(definition, { projectCli: config.cli }),
+        ...(extensions.length === 0 ? {} : { extensions }),
+        ...(hooks === undefined ? {} : { hooks }),
+        requirements: mergeFlowExtensionRequirements(
+          flowRequirements(definition, { projectCli: config.cli }),
+          (loaded.extensions ?? []).map(extension => ({
+            name: extension.name, permissions: extension.manifest.permissions,
+          })),
+        ),
         ...(config.path === undefined ? {} : { projectConfigPath: config.path }),
       },
     };
   } catch (error) {
+    // A flow-extension refusal keeps its own code (plugin_source_drift,
+    // plugin_incompatible, …): the operator needs to know which record
+    // disagreed, not that "the spec is invalid".
+    if (error instanceof PluginError) return { report: inputFailureReport({ kind: error.code, message: error.message }, path) };
     return { report: inputFailureReport({
       kind: typeof error === 'object' && error !== null && 'kind' in error && error.kind === 'config_invalid'
         ? 'config_invalid' : 'invalid_spec',

package/src/cli/check-typescript.ts

@@ -2,6 +2,7 @@ import type { LoadedPlugin } from '../plugin-loader.js';
 import { dirname, resolve } from 'node:path';
 import type { AuthoredFlowDefinition } from '../authored-flow.js';
 import { loadAuthoredFlow } from '../authored-flow-loader.js';
+import { PluginError } from '../plugin-manifest.js';
 import { preflight } from '../preflight.js';
 import { SPEC_SCHEMA_VERSION, type McpServerConfig } from '../spec.js';
 import { inputFailureReport, readProjectConfig, type CheckReport } from './check.js';
@@ -18,6 +19,9 @@ export async function checkTypeScriptFlow(path: string): Promise<{ report: Check
     const { handle, getDefinition } = await loadAuthoredFlow(path);
     return await checkMcpHeader(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 as Error).message }, path) };
   }
 }
@@ -28,7 +32,7 @@ export async function checkMcpHeader(
   path: string,
 ): Promise<CheckedMcp> {
   const empty = { servers: Object.freeze({}), inventory: Object.freeze({}) };
-  const KNOWN_HEADER_FIELDS = new Set(['tools', 'budget', 'identity', 'memory', 'workspace', 'use']);
+  const KNOWN_HEADER_FIELDS = new Set(['tools', 'budget', 'identity', 'memory', 'workspace', 'use', 'version', 'hooks']);
   const header = definition.header ?? {};
   const unsupported = Object.keys(header).filter(key => !KNOWN_HEADER_FIELDS.has(key));
   if (header.tools?.relayfile !== undefined) unsupported.push('tools.relayfile');

package/src/cli/check.ts

@@ -61,9 +61,32 @@ export interface CheckReport {
   schedules?: ScheduleInspection[];
   /** Integrations, harnesses and MCP servers the flow declares it needs (`flow-requirements.ts`). */
   requirements?: FlowRequirements;
+  /** Schema-2 flow extensions composed onto the authored flow, in lock order (`flow-extension-loader.ts`). */
+  extensions?: ExtensionInspection[];
+  /** Base hook points and which plugins implement them. */
+  hooks?: HookInspection;
   diagnostics: Array<PreflightDiagnostic | CheckInputDiagnostic | CheckWarningDiagnostic>;
 }
 
+export interface ExtensionInspection {
+  name: string;
+  version: string;
+  /** Canonical `github:<owner>/<repo>@<sha>#<path>`. */
+  ref: string;
+  digest: string;
+  /** How many `.on()` handlers it appends after the base flow's own. */
+  handlers: number;
+  /** Hook names this extension implements, in manifest order. */
+  hooks?: readonly string[];
+}
+
+export interface HookInspection {
+  /** Names the base flow header declares. */
+  declared: readonly string[];
+  /** Plugin implementations in lock order. */
+  implementations: readonly { hook: string; plugin: string }[];
+}
+
 export interface ScheduleInspection {
   /** Position among the flow's handlers, so two identical declarations stay distinct. */
   handler: number;

package/src/cli/cloud-deploy.ts

@@ -19,6 +19,7 @@ export interface CloudDeployArgs {
   /** Refuse a missing integration instead of offering to connect it. */
   noConnect: boolean;
   json: boolean;
+  plugins: string[];
 }
 
 /**
@@ -39,6 +40,7 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
   let noConnect = false;
   let json = false;
   const on: string[] = [];
+  const plugins: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]!;
     if (arg === '--json') {
@@ -63,6 +65,13 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
       i += 1;
       continue;
     }
+    if (arg === '--plugin') {
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('-')) return undefined;
+      plugins.push(next);
+      i += 1;
+      continue;
+    }
     if (arg === '--repo' || arg === '--approver' || arg === '--name' || arg === '--on') {
       const next = args[i + 1];
       if (next === undefined || next.startsWith('-')) return undefined;
@@ -78,7 +87,7 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
     value = arg;
   }
   if (value === undefined || repo === undefined || on.length === 0) return undefined;
-  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, noConnect, json };
+  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, noConnect, json, plugins };
 }
 
 function describeSource(source: FlowTriggerSource): string {
@@ -109,6 +118,7 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
       ...(args.name === undefined ? {} : { name: args.name }),
       ...(agents === undefined ? {} : { agents }),
       ...(connect === undefined ? {} : { connect }),
+      ...(args.plugins.length === 0 ? {} : { plugins: args.plugins }),
     });
     if (args.json) {
       io.stdout(JSON.stringify({ ok: true, ...deployment }));