@relayflows/sdk 2.0.24 → 2.0.26

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

package/src/plugin-github.ts

@@ -0,0 +1,98 @@
+import { payloadManifest, safePath, sha256 } from './bundle.js';
+import { PluginError } from './plugin-manifest.js';
+import { SHA, type PluginSourceInput, type PluginSourceRef } from './plugin-source.js';
+
+/**
+ * Public, unauthenticated GitHub reads for flow-extension plugins — the same
+ * posture as Cloud's deploy links: no credential ever travels to GitHub, so a
+ * private repository simply answers 404 and is reported as unresolved.
+ *
+ * Two calls resolve a ref and enumerate a tree; blobs come from
+ * raw.githubusercontent.com pinned to the resolved commit. Every byte count is
+ * checked against the tree listing, and the tree is refused if GitHub
+ * truncated it, if it contains a symlink or submodule under the plugin path,
+ * or if any file or the whole plugin exceeds the bounds below.
+ */
+export type FetchLike = (url: string, init: { headers: Record<string, string>; signal: AbortSignal }) => Promise<Response>;
+
+export const MAX_PLUGIN_FILE_BYTES = 256_000;
+export const MAX_PLUGIN_TOTAL_BYTES = 2_000_000;
+export const MAX_PLUGIN_FILES = 500;
+const TIMEOUT_MS = 15_000;
+const API = 'https://api.github.com';
+const RAW = 'https://raw.githubusercontent.com';
+
+export interface FetchedPluginFile { readonly path: string; readonly data: Buffer }
+export interface FetchedPlugin {
+  readonly source: PluginSourceRef;
+  /** Plugin-relative paths, sorted. */
+  readonly files: readonly FetchedPluginFile[];
+  /** sha256 of `payloadManifest(files)`: the content identity persisted as `@sha256:`. */
+  readonly digest: string;
+}
+
+async function request(fetch: FetchLike, url: string, accept: string): Promise<Response> {
+  let response: Response;
+  try {
+    response = await fetch(url, { headers: { accept, 'user-agent': 'relayflows-sdk' }, signal: AbortSignal.timeout(TIMEOUT_MS) });
+  } catch (error) {
+    throw new PluginError('plugin_fetch_failed', `GitHub request failed: ${url} (${error instanceof Error ? error.message : String(error)}).`);
+  }
+  if (response.status === 404) throw new PluginError('plugin_source_unresolved', `Not found on GitHub (or not public): ${url}.`);
+  if (!response.ok) throw new PluginError('plugin_fetch_failed', `GitHub answered ${response.status} for ${url}.`);
+  return response;
+}
+
+/** Branch, tag, or commit → the commit sha it names right now; a sha input is verified to exist. */
+export async function resolveGithubSha(source: PluginSourceInput, fetch: FetchLike = globalThis.fetch): Promise<PluginSourceRef> {
+  const url = `${API}/repos/${source.owner}/${source.repo}/commits/${encodeURIComponent(source.ref)}`;
+  const sha = (await (await request(fetch, url, 'application/vnd.github.sha')).text()).trim();
+  if (!SHA.test(sha)) throw new PluginError('plugin_fetch_failed', `GitHub returned a malformed commit sha for ${source.ref}.`);
+  if (SHA.test(source.ref) && sha !== source.ref) throw new PluginError('plugin_source_unresolved', `Commit ${source.ref} resolved to ${sha}.`);
+  return Object.freeze({ ...source, sha });
+}
+
+interface TreeEntry { path: string; mode: string; type: string; size?: number }
+
+async function listTree(source: PluginSourceRef, fetch: FetchLike): Promise<TreeEntry[]> {
+  const url = `${API}/repos/${source.owner}/${source.repo}/git/trees/${source.sha}?recursive=1`;
+  let body: unknown;
+  try { body = await (await request(fetch, url, 'application/vnd.github+json')).json(); }
+  catch { throw new PluginError('plugin_fetch_failed', 'GitHub tree listing is not JSON.'); }
+  const tree = typeof body === 'object' && body !== null ? (body as { tree?: unknown; truncated?: unknown }) : {};
+  if (tree.truncated === true) throw new PluginError('plugin_fetch_failed', 'GitHub truncated the tree listing; the repository is too large to enumerate safely.');
+  if (!Array.isArray(tree.tree)) throw new PluginError('plugin_fetch_failed', 'GitHub tree listing has no entries.');
+  return tree.tree.filter((e): e is TreeEntry => typeof e === 'object' && e !== null
+    && typeof (e as TreeEntry).path === 'string' && typeof (e as TreeEntry).mode === 'string' && typeof (e as TreeEntry).type === 'string');
+}
+
+/** Enumerate and download the plugin directory at the pinned commit, bounded and verified. */
+export async function fetchGithubPlugin(source: PluginSourceRef, fetch: FetchLike = globalThis.fetch): Promise<FetchedPlugin> {
+  const prefix = source.path === '' ? '' : `${source.path}/`;
+  const entries = (await listTree(source, fetch)).filter(e => e.path.startsWith(prefix));
+  if (source.path !== '' && entries.length === 0) throw new PluginError('plugin_source_unresolved', `${source.path} does not exist at ${source.sha}.`);
+  const blobs: { path: string; size: number }[] = [];
+  let total = 0;
+  for (const entry of entries) {
+    const relative = entry.path.slice(prefix.length);
+    if (entry.type === 'tree') continue;
+    if (entry.type === 'commit') throw new PluginError('plugin_path_invalid', `${entry.path} is a submodule; plugins must be plain files.`);
+    if (entry.mode === '120000') throw new PluginError('plugin_path_invalid', `${entry.path} is a symlink; plugins must be plain files.`);
+    if (entry.type !== 'blob' || !safePath(relative)) throw new PluginError('plugin_path_invalid', `${entry.path} is not a plain repository file.`);
+    if (!Number.isSafeInteger(entry.size) || entry.size! < 0) throw new PluginError('plugin_fetch_failed', `${entry.path} has no size in the tree listing.`);
+    if (entry.size! > MAX_PLUGIN_FILE_BYTES) throw new PluginError('plugin_too_large', `${entry.path} is ${entry.size} bytes; the limit is ${MAX_PLUGIN_FILE_BYTES}.`);
+    total += entry.size!;
+    if (total > MAX_PLUGIN_TOTAL_BYTES) throw new PluginError('plugin_too_large', `Plugin exceeds ${MAX_PLUGIN_TOTAL_BYTES} bytes in total.`);
+    blobs.push({ path: relative, size: entry.size! });
+    if (blobs.length > MAX_PLUGIN_FILES) throw new PluginError('plugin_too_large', `Plugin has more than ${MAX_PLUGIN_FILES} files.`);
+  }
+  if (!blobs.some(b => b.path === 'flows-plugin.json')) throw new PluginError('plugin_manifest_missing', `${source.owner}/${source.repo}@${source.sha}${prefix === '' ? '' : `#${source.path}`} has no flows-plugin.json.`);
+  const files: FetchedPluginFile[] = [];
+  for (const blob of blobs.sort((a, b) => a.path < b.path ? -1 : 1)) {
+    const url = `${RAW}/${source.owner}/${source.repo}/${source.sha}/${prefix}${blob.path}`;
+    const data = Buffer.from(await (await request(fetch, url, 'application/octet-stream')).arrayBuffer());
+    if (data.length !== blob.size) throw new PluginError('plugin_source_drift', `${blob.path}: fetched ${data.length} bytes, tree lists ${blob.size}.`);
+    files.push(Object.freeze({ path: blob.path, data }));
+  }
+  return Object.freeze({ source, files: Object.freeze(files), digest: sha256(payloadManifest(files)) });
+}

package/src/plugin-loader.ts

@@ -5,6 +5,7 @@ import { Ajv } from 'ajv';
 import type { Step } from '@relayflows/surface';
 import { snapshotJsonValue } from './json-value.js';
 import { assertSupportedPlugin, PluginError, pluginPackageName, validatePluginManifest, type PluginManifest, type PluginVerb } from './plugin-manifest.js';
+import { isGithubPluginRef } from './plugin-source.js';
 
 export interface LoadedPlugin { readonly directory: string; readonly manifest: PluginManifest }
 export function findPluginProject(start: string): string | undefined {
@@ -47,8 +48,11 @@ export async function loadPlugins(start: string): Promise<readonly LoadedPlugin[
   if (config === null || typeof config !== 'object' || (config.plugins !== undefined && (!Array.isArray(config.plugins) || !config.plugins.every(p => typeof p === 'string')))) {
     throw new PluginError('plugin_manifest_invalid', 'flows.json plugins must be package names.');
   }
+  // Flow extensions (github:… entries) are not helpers: the authored flow
+  // loader verifies and composes them (flow-extension-loader.ts). Here they
+  // are simply not helper packages, so they are left out of the helper set.
   const scope = join(root, 'node_modules/@flows');
-  const names = new Set<string>((config.plugins as string[] | undefined)?.map(pluginPackageName));
+  const names = new Set<string>((config.plugins as string[] | undefined)?.filter(p => !isGithubPluginRef(p)).map(pluginPackageName));
   if (existsSync(scope)) for (const name of readdirSync(scope).sort()) {
     if (name.startsWith('helper-') && !names.has(`@flows/${name}`)) {
       throw new PluginError('plugin_unlisted', `@flows/${name} is installed but not declared in flows.json plugins. Run flows add ${name}.`);

package/src/plugin-lock.ts

@@ -0,0 +1,194 @@
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PluginError } from './plugin-manifest.js';
+import { SHA, canonicalPluginRef, isGithubPluginRef, parseCanonicalPluginRef, type PluginSourceRef } from './plugin-source.js';
+
+/**
+ * `flows.lock.json` — the project's plugin provenance. `flows.json.plugins`
+ * says *what* is declared; the lockfile says exactly which bytes that meant:
+ * the commit, the content digest, the manifest hash, and the order the
+ * operator declared. Version 2 is also the sealed bundle `lockfile.json`
+ * shape when the bundle carries plugins (RFC-0001 decision 14).
+ */
+export const PLUGIN_LOCK_FILE = 'flows.lock.json';
+export const PLUGIN_LOCK_VERSION = 2;
+const FLOWS_FILE = 'flows.json';
+
+export interface PluginLockEntry {
+  readonly name: string;
+  readonly kind: 'flow-extension';
+  readonly version: string;
+  readonly source: { readonly host: 'github'; readonly owner: string; readonly repo: string; readonly sha: string; readonly path: string };
+  /** sha256 of the payload manifest — the `@sha256:` in `.flows/plugins`. */
+  readonly digest: string;
+  /** sha256 of the `flows-plugin.json` bytes as installed. */
+  readonly manifestSha256: string;
+  /**
+   * 1-based position among the flow-extension (`github:`) entries of
+   * `flows.json.plugins`, in declaration order. Helper entries interspersed in
+   * that list do not count, so the order is the composition order exactly.
+   */
+  readonly order: number;
+  readonly resolvedAt: string;
+}
+export interface PluginLock { readonly version: 2; readonly plugins: readonly PluginLockEntry[] }
+
+const HEX64 = /^[0-9a-f]{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_lock_invalid', `${PLUGIN_LOCK_FILE}: ${message}`); };
+
+export function parsePluginLock(input: unknown): PluginLock {
+  if (!object(input) || input.version !== PLUGIN_LOCK_VERSION || !Array.isArray(input.plugins)
+    || Object.keys(input).some(k => !['version', 'plugins'].includes(k))) return invalid(`expected { version: ${PLUGIN_LOCK_VERSION}, plugins: [] }.`);
+  const names = new Set<string>();
+  const plugins = input.plugins.map((entry, index) => {
+    if (!object(entry) || Object.keys(entry).sort().join(',') !== 'digest,kind,manifestSha256,name,order,resolvedAt,source,version'
+      || entry.kind !== 'flow-extension' || typeof entry.name !== 'string' || typeof entry.version !== 'string'
+      || typeof entry.digest !== 'string' || !HEX64.test(entry.digest)
+      || typeof entry.manifestSha256 !== 'string' || !HEX64.test(entry.manifestSha256)
+      || entry.order !== index + 1 || typeof entry.resolvedAt !== 'string' || Number.isNaN(Date.parse(entry.resolvedAt))
+      || !object(entry.source) || entry.source.host !== 'github' || typeof entry.source.owner !== 'string'
+      || typeof entry.source.repo !== 'string' || typeof entry.source.sha !== 'string' || !SHA.test(entry.source.sha)
+      || typeof entry.source.path !== 'string') return invalid(`plugins[${index}] is malformed.`);
+    if (names.has(entry.name)) return invalid(`plugin ${entry.name} is listed twice.`);
+    names.add(entry.name);
+    const source = parseCanonicalPluginRef(canonicalPluginRef({ host: 'github', owner: entry.source.owner, repo: entry.source.repo, ref: entry.source.sha, sha: entry.source.sha, path: entry.source.path }));
+    return Object.freeze({
+      name: entry.name, kind: 'flow-extension' as const, version: entry.version,
+      source: Object.freeze({ host: 'github' as const, owner: source.owner, repo: source.repo, sha: source.sha, path: source.path }),
+      digest: entry.digest, manifestSha256: entry.manifestSha256, order: entry.order, resolvedAt: entry.resolvedAt,
+    });
+  });
+  return Object.freeze({ version: PLUGIN_LOCK_VERSION, plugins: Object.freeze(plugins) });
+}
+
+/** Absent file → empty lock; unreadable or malformed → refusal. */
+export function readPluginLock(root: string): PluginLock {
+  recoverFlowsAndLock(root);
+  const path = join(root, PLUGIN_LOCK_FILE);
+  if (!existsSync(path)) return Object.freeze({ version: PLUGIN_LOCK_VERSION, plugins: Object.freeze([]) });
+  let parsed: unknown;
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')); }
+  catch { return invalid('not valid JSON.'); }
+  return parsePluginLock(parsed);
+}
+
+export function writePluginLock(root: string, lock: PluginLock): void {
+  writeFileSync(join(root, PLUGIN_LOCK_FILE), `${JSON.stringify(parsePluginLock(lock), null, 2)}\n`);
+}
+
+/**
+ * Finish or abort a two-file update left by a process crash. The lock temp is
+ * written first: by itself it is only preparation and can be discarded. Once
+ * the config temp exists, both complete snapshots exist and recovery rolls
+ * them forward in the same lock-then-declaration order as the writer.
+ */
+export function recoverFlowsAndLock(root: string, configPath = join(root, FLOWS_FILE)): void {
+  const jsonTmp = `${configPath}.tmp`;
+  const lockPath = join(root, PLUGIN_LOCK_FILE);
+  const lockTmp = `${lockPath}.tmp`;
+  const hasJson = existsSync(jsonTmp);
+  const hasLock = existsSync(lockTmp);
+  if (!hasJson && !hasLock) return;
+  if (!hasJson) {
+    unlinkSync(lockTmp);
+    return;
+  }
+  let pendingConfig: unknown;
+  try { pendingConfig = JSON.parse(readFileSync(jsonTmp, 'utf8')); }
+  catch {
+    if (hasLock) { unlinkSync(jsonTmp); unlinkSync(lockTmp); return; }
+    return invalid('pending transaction has invalid flows.json.tmp.');
+  }
+  if (!object(pendingConfig) || !Array.isArray(pendingConfig.plugins)
+    || !pendingConfig.plugins.every(plugin => typeof plugin === 'string')) {
+    if (hasLock) { unlinkSync(jsonTmp); unlinkSync(lockTmp); return; }
+    return invalid('pending transaction has invalid flows.json.tmp.');
+  }
+  const lockSource = hasLock ? lockTmp : lockPath;
+  let pendingLock: unknown;
+  try { pendingLock = JSON.parse(readFileSync(lockSource, 'utf8')); }
+  catch {
+    if (hasLock) { unlinkSync(jsonTmp); unlinkSync(lockTmp); return; }
+    return invalid('pending transaction has no valid lock snapshot.');
+  }
+  try { parsePluginLock(pendingLock); }
+  catch (error) {
+    if (hasLock) { unlinkSync(jsonTmp); unlinkSync(lockTmp); return; }
+    throw error;
+  }
+  if (hasLock) renameSync(lockTmp, lockPath);
+  renameSync(jsonTmp, configPath);
+}
+
+/** Write complete snapshots, then recover them as one roll-forward transaction. */
+export function writeFlowsAndLock(root: string, configPath: string, config: Record<string, unknown>, plugins: readonly string[], lock: PluginLock): void {
+  const jsonTmp = `${configPath}.tmp`;
+  const lockPath = join(root, PLUGIN_LOCK_FILE);
+  const lockTmp = `${lockPath}.tmp`;
+  writeFileSync(lockTmp, `${JSON.stringify(parsePluginLock(lock), null, 2)}\n`);
+  writeFileSync(jsonTmp, `${JSON.stringify({ ...config, plugins: [...plugins] }, null, 2)}\n`);
+  recoverFlowsAndLock(root, configPath);
+}
+
+/**
+ * Rebuild the entry list in `flows.json.plugins` order: `order` is derived from
+ * the declaration list, never stored independently, so the two cannot disagree.
+ * Lock entries that are no longer declared are dropped; a declaration with no
+ * matching lock entry is a refusal.
+ */
+export function lockForDeclared(lock: PluginLock, declared: readonly string[]): PluginLock {
+  const byRef = new Map(lock.plugins.map(p => [canonicalPluginRef({ ...p.source, ref: p.source.sha }), p]));
+  const plugins = declared.filter(isGithubPluginRef).map((ref, index) => {
+    const found = byRef.get(ref);
+    if (found === undefined) return invalid(`flows.json declares ${ref} but the lockfile has no entry for it; run flows add ${ref}.`);
+    return Object.freeze({ ...found, order: index + 1 });
+  });
+  return Object.freeze({ version: PLUGIN_LOCK_VERSION, plugins: Object.freeze(plugins) });
+}
+
+export function lockWithPlugin(
+  lock: PluginLock, declared: readonly string[],
+  entry: Omit<PluginLockEntry, 'kind' | 'order'>,
+): PluginLock {
+  const byRef = new Map(lock.plugins.map(p => [canonicalPluginRef({ ...p.source, ref: p.source.sha }), p]));
+  byRef.set(canonicalPluginRef({ ...entry.source, ref: entry.source.sha }), { ...entry, kind: 'flow-extension', order: 0 });
+  return lockForDeclared({ version: PLUGIN_LOCK_VERSION, plugins: Object.freeze([...byRef.values()]) }, declared);
+}
+
+/** Lock entries paired with their declared reference, in declaration order. */
+export function lockedPlugins(lock: PluginLock): readonly { ref: string; entry: PluginLockEntry; source: PluginSourceRef }[] {
+  return lock.plugins.map(entry => {
+    const source = { ...entry.source, ref: entry.source.sha };
+    return { ref: canonicalPluginRef(source), entry, source };
+  });
+}
+
+/** The `github:` entries of `flows.json.plugins`, in declaration order; helper entries are left out. */
+export function declaredExtensionRefs(root: string): readonly string[] {
+  recoverFlowsAndLock(root);
+  let config: { plugins?: unknown };
+  try { config = JSON.parse(readFileSync(join(root, 'flows.json'), 'utf8')); }
+  catch { throw new PluginError('plugin_manifest_invalid', 'Invalid flows.json.'); }
+  if (config === null || typeof config !== 'object' || (config.plugins !== undefined && (!Array.isArray(config.plugins) || !config.plugins.every(p => typeof p === 'string')))) {
+    throw new PluginError('plugin_manifest_invalid', 'flows.json plugins must be strings.');
+  }
+  return Object.freeze(((config.plugins as string[] | undefined) ?? []).filter(isGithubPluginRef));
+}
+
+/**
+ * The three records that must agree before an extension is trusted:
+ * `flows.json.plugins` (declaration), `flows.lock.json` (provenance), and —
+ * checked by the caller against the returned digests — `.flows/plugins`
+ * (bytes). Any declaration without a lock entry, lock entry without a
+ * declaration, or order disagreement is `plugin_lock_invalid`.
+ */
+export function reconcileDeclaredExtensions(root: string): readonly { ref: string; entry: PluginLockEntry; source: PluginSourceRef }[] {
+  const declared = declaredExtensionRefs(root);
+  const locked = lockedPlugins(readPluginLock(root));
+  const lockedRefs = locked.map(p => p.ref);
+  for (const ref of declared) if (!lockedRefs.includes(ref)) throw new PluginError('plugin_lock_invalid', `flows.json declares ${ref} but flows.lock.json has no entry for it.`);
+  for (const ref of lockedRefs) if (!declared.includes(ref)) throw new PluginError('plugin_lock_invalid', `flows.lock.json records ${ref} but flows.json does not declare it.`);
+  if (declared.some((ref, index) => lockedRefs[index] !== ref)) throw new PluginError('plugin_lock_invalid', 'flows.lock.json order differs from flows.json.plugins.');
+  return locked;
+}

package/src/plugin-manifest.ts

@@ -5,6 +5,11 @@ export const PLUGIN_FAILURE_KINDS = [
   'plugin_unknown', 'plugin_unlisted', 'plugin_install_failed', 'plugin_manifest_missing',
   'plugin_manifest_invalid', 'plugin_preflight_missing', 'plugin_verb_unknown_primitive',
   'plugin_unsupported', 'plugin_credential_missing', 'plugin_server_unreachable',
+  // schema 2 flow extensions (see flow-extension-manifest.ts, plugin-source.ts, plugin-github.ts)
+  'plugin_kind_invalid', 'plugin_incompatible', 'plugin_event_unroutable', 'plugin_source_invalid',
+  'plugin_event_ambiguous',
+  'plugin_source_unresolved', 'plugin_fetch_failed', 'plugin_path_invalid', 'plugin_too_large',
+  'plugin_source_drift', 'plugin_lock_invalid',
 ] as const;
 export type PluginFailureKind = typeof PLUGIN_FAILURE_KINDS[number];
 export class PluginError extends Error {
@@ -16,6 +21,15 @@ export interface PluginVerb {
   lowersTo: 'run' | 'llm' | 'agent' | 'effect' | 'wait';
   args: Record<string, unknown>;
 }
+/** The kind a `flows-plugin.json` declares; absent means the schema-1 helper plugin. */
+export type PluginKind = 'helper' | 'flow-extension';
+export function pluginKindOf(input: unknown): PluginKind {
+  const kind = typeof input === 'object' && input !== null && !Array.isArray(input) ? (input as { kind?: unknown }).kind : undefined;
+  if (kind === undefined || kind === 'helper') return 'helper';
+  if (kind === 'flow-extension') return 'flow-extension';
+  throw new PluginError('plugin_kind_invalid', `Unknown plugin kind ${JSON.stringify(kind)}; expected "helper" or "flow-extension".`);
+}
+/** A schema-1 helper plugin: verbs that lower to kernel primitives. */
 export interface PluginManifest {
   name: string;
   version: string;
@@ -41,6 +55,10 @@ export function validatePluginManifest(input: unknown, packageName?: string): Pl
   catch { throw new PluginError('plugin_manifest_invalid', 'Plugin manifest must be JSON data.'); }
   const invalid = (message: string): never => { throw new PluginError('plugin_manifest_invalid', message); };
   if (!object(v)) return invalid('Expected a plugin manifest object.');
+  if (pluginKindOf(v) !== 'helper') {
+    throw new PluginError('plugin_kind_invalid', 'A flow-extension manifest installs from a GitHub reference (flows add github:<owner>/<repo>@<ref>#<path>), not as a helper package.');
+  }
+  if (v.schema !== undefined && v.schema !== 1) return invalid('Helper plugin manifests are schema 1.');
   if (!Object.hasOwn(v, 'preflight')) throw new PluginError('plugin_preflight_missing', 'Plugin must declare preflight.');
   if (typeof v.name !== 'string' || typeof v.version !== 'string' || !v.version.trim()) return invalid('Plugin name and version are required.');
   const resolved = pluginPackageName(v.name);

package/src/plugin-source.ts

@@ -0,0 +1,91 @@
+import { safePath } from './bundle.js';
+import { PluginError } from './plugin-manifest.js';
+
+/**
+ * Where a flow-extension plugin comes from: a public GitHub repository, pinned
+ * to a commit. A branch or tag is accepted as *input* only; what gets written
+ * to `flows.json` and the lockfile is always the canonical 40-hex form,
+ * `github:<owner>/<repo>@<sha>#<path>`, so a later reader can never resolve
+ * to different bytes than the installer saw.
+ */
+export interface PluginSourceInput {
+  readonly host: 'github';
+  readonly owner: string;
+  readonly repo: string;
+  /** Branch, tag, or commit as typed. */
+  readonly ref: string;
+  /** Directory inside the repository holding `flows-plugin.json`; `''` is the root. */
+  readonly path: string;
+}
+export interface PluginSourceRef extends PluginSourceInput {
+  /** Exactly 40 lowercase hex characters. */
+  readonly sha: string;
+}
+
+const OWNER = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const REPO = /^[A-Za-z0-9_.-]{1,100}$/;
+const REF = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/;
+export const SHA = /^[0-9a-f]{40}$/;
+
+function invalid(message: string): never {
+  throw new PluginError('plugin_source_invalid', message);
+}
+
+export function isGithubPluginRef(value: string): boolean {
+  return value.startsWith('github:') || /^https:\/\/github\.com\//.test(value);
+}
+
+/**
+ * Accepts `github:<owner>/<repo>@<ref>#<path>`,
+ * `https://github.com/<owner>/<repo>/tree/<ref>/<path>` (or `/blob/`), and
+ * `github:<owner>/<repo>@<ref>` for a root-level plugin.
+ *
+ * In the URL form the ref is the single segment after `tree/`: GitHub itself
+ * disambiguates `tree/feat/x/dir` against the repository's refs, which an
+ * offline parser cannot. A ref containing `/` must use the `github:` form,
+ * where `@ref#path` is unambiguous.
+ */
+export function parsePluginSource(input: string): PluginSourceInput {
+  if (input.length > 2048) return invalid('Plugin source is too long.');
+  let owner: string | undefined, repo: string | undefined, ref: string | undefined, path = '';
+  if (input.startsWith('github:')) {
+    const m = /^github:([^/@#]+)\/([^/@#]+)@([^#]+)(?:#(.*))?$/.exec(input);
+    if (!m) return invalid('Expected github:<owner>/<repo>@<ref>[#<path>].');
+    [, owner, repo, ref] = m;
+    path = m[4] ?? '';
+  } else if (/^https:\/\/github\.com\//.test(input)) {
+    let url: URL;
+    try { url = new URL(input); } catch { return invalid('Plugin source is not a valid URL.'); }
+    if (url.username || url.password || url.search || url.hash) return invalid('Plugin URL must not carry credentials, a query, or a fragment.');
+    const m = /^\/([^/]+)\/([^/]+)\/(?:tree|blob)\/([^/]+)(?:\/(.*))?$/.exec(url.pathname);
+    if (!m) return invalid('Expected https://github.com/<owner>/<repo>/tree/<ref>/<path>.');
+    try {
+      [, owner, repo, ref] = m.map(part => part === undefined ? part : decodeURIComponent(part));
+      path = m[4] === undefined ? '' : decodeURIComponent(m[4]);
+    } catch {
+      return invalid('Plugin URL contains invalid percent-encoding.');
+    }
+  } else return invalid('Expected a github: reference or a https://github.com/ URL.');
+  if (owner === undefined || !OWNER.test(owner)) return invalid('Invalid GitHub owner.');
+  if (repo === undefined || !REPO.test(repo) || repo === '.' || repo === '..') return invalid('Invalid GitHub repository name.');
+  if (repo.endsWith('.git')) repo = repo.slice(0, -4);
+  if (ref === undefined || !REF.test(ref) || ref.includes('..') || ref.endsWith('/') || ref.endsWith('.lock')) return invalid('Invalid git ref.');
+  path = path.replace(/\/+$/, '');
+  if (path !== '' && !safePath(path)) return invalid('Plugin path must be repository-relative without traversal.');
+  if (path.split('/').some(part => part === 'flows-plugin.json')) return invalid('Plugin path names the directory holding flows-plugin.json, not the file.');
+  return Object.freeze({ host: 'github', owner, repo, ref, path });
+}
+
+/** The one spelling that is ever persisted. */
+export function canonicalPluginRef(source: PluginSourceRef): string {
+  return `github:${source.owner}/${source.repo}@${source.sha}${source.path === '' ? '' : `#${source.path}`}`;
+}
+
+/** Parses a persisted reference; refuses anything but the canonical sha form. */
+export function parseCanonicalPluginRef(value: string): PluginSourceRef {
+  const parsed = parsePluginSource(value);
+  if (!value.startsWith('github:') || !SHA.test(parsed.ref)) {
+    throw new PluginError('plugin_source_invalid', `Persisted plugin reference must be github:<owner>/<repo>@<sha>[#<path>], got ${value}.`);
+  }
+  return Object.freeze({ ...parsed, sha: parsed.ref });
+}