@relayflows/sdk 2.0.9 → 2.0.11

package/src/bundle-typescript.ts

@@ -0,0 +1,98 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { canonicalize } from './canonical.js';
+import { compileSpec } from './compile.js';
+import type { BundleFile } from './bundle.js';
+
+/** Bun is an explicit build dependency, never an implicit install. */
+function bun(args: string[], cwd: string): string {
+  const result = spawnSync('bun', ['--no-env-file', ...args], {
+    cwd, encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024,
+    env: { PATH: process.env['PATH'], NODE_ENV: 'production', TZ: 'UTC' },
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error(`TypeScript build requires Bun: ${result.error?.message ?? result.stderr}`);
+  }
+  return result.stdout.trim();
+}
+
+export async function buildTypescript(input: string) {
+  const directory = dirname(input);
+  const lockPath = await findLock(directory);
+  const lock = JSON.parse(await readFile(lockPath, 'utf8'));
+  if (![2, 3].includes(lock.lockfileVersion) || !lock.packages) {
+    throw new Error('package-lock.json: expected npm lockfile version 2 or 3 with pinned packages');
+  }
+  await checkInstalledVersions(dirname(lockPath), lock.packages);
+  const compiler = `bun@${bun(['--version'], directory)}`;
+  const staging = await mkdtemp(join(tmpdir(), 'flows-ts-'));
+  try {
+    // Evaluate module declarations, never the authored body. Resolve the runtime
+    // beside the input, keeping flow()'s WeakMap identity in the same module.
+    const probe = `
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+const module = await import(${JSON.stringify(pathToFileURL(input).href)});
+let spec = module.default;
+let authored = false;
+if (!spec || !Array.isArray(spec.steps)) {
+  const require = createRequire(${JSON.stringify(pathToFileURL(input).href)});
+  const { getFlowDefinition } = await import(pathToFileURL(require.resolve('@relayflows/surface/runtime')).href);
+  const definition = getFlowDefinition(spec);
+  if (Object.keys(definition.header).length) throw new Error('unsupported authored flow header');
+  if (!module.spec) throw new Error('authored flow() requires an exported spec declaration for build-time preflight; the body is not executed during build');
+  spec = module.spec;
+  if (spec.name !== definition.name) throw new Error('exported spec name must match flow() name');
+  authored = true;
+}
+
+process.stdout.write(JSON.stringify({ spec, authored }));
+`;
+    const probePath = join(staging, 'inspect.ts');
+    await writeFile(probePath, probe);
+    const inspected = JSON.parse(bun([probePath], directory));
+    const spec = compileSpec(inspected.spec);
+    const executable = join(staging, 'flow');
+    bun(['build', '--compile', '--env=disable', '--no-compile-autoload-dotenv',
+      '--no-compile-autoload-bunfig', '--outfile', executable, input], directory);
+    const files: BundleFile[] = [
+      { path: 'flow', data: await readFile(executable) },
+      { path: 'lockfile.json', data: canonicalize(lock) },
+    ];
+    return { spec, authored: inspected.authored === true, compiler, files };
+  } finally { await rm(staging, { recursive: true, force: true }); }
+}
+
+/** Do not label a stale node_modules tree with a newer lockfile's pins. */
+async function checkInstalledVersions(root: string, packages: Record<string, {
+  version?: string; optional?: boolean; dev?: boolean; link?: boolean; resolved?: string;
+}>): Promise<void> {
+  for (const [path, entry] of Object.entries(packages)) {
+    if (path === '') continue;
+    if (path.startsWith('/') || path.includes('\\') || path.split('/').includes('..')
+      || (entry.resolved !== undefined && /^(?:file:|\/|[A-Za-z]:)/.test(entry.resolved))) {
+      throw new Error(`package-lock.json: ${path} must use portable, pinned dependency locations`);
+    }
+    if (entry.link) continue; // Workspace source is captured by the compiler.
+    let installed;
+    try { installed = JSON.parse(await readFile(join(root, path, 'package.json'), 'utf8')); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT' && (entry.optional || entry.dev)) continue;
+      throw new Error(`package-lock.json: ${path} is missing; run npm ci before building`);
+    }
+    if (typeof entry.version !== 'string' || installed.version !== entry.version) {
+      throw new Error(`package-lock.json: ${path} does not match its pinned version; run npm ci before building`);
+    }
+  }
+}
+async function findLock(start: string): Promise<string> {
+  for (let directory = start; ; directory = dirname(directory)) {
+    const candidate = join(directory, 'package-lock.json');
+    try { await readFile(candidate); return candidate; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    if (dirname(directory) === directory) throw new Error('package-lock.json: no workspace lockfile found for TS flow');
+  }
+}

package/src/bundle.ts

@@ -0,0 +1,182 @@
+import { createHash, createPrivateKey, createPublicKey, randomBytes, sign, verify } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { canonicalize } from './canonical.js';
+
+export interface BundleEntry { path: string; sha256: string; bytes: number }
+export interface BundleFile { path: string; data: Uint8Array | string; executable?: boolean }
+export interface BundleOptions {
+  name: string;
+  out: string;
+  repo: string;
+  files: BundleFile[];
+  env?: NodeJS.ProcessEnv;
+  warn(message: string): void;
+}
+
+export function sha256(data: Uint8Array | string): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+function safePath(path: string): boolean {
+  return path.length > 0 && !path.includes('\\') && !path.includes('\0')
+    && path.split('/').every(part => part !== '' && part !== '.' && part !== '..')
+    && !path.includes(':');
+}
+
+/** 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)) {
+    throw new Error('spec.canonical.json: name must be a safe single directory component');
+  }
+  const files = options.files.map(file => ({ ...file, data: Buffer.from(file.data) }))
+    .sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const paths = new Set<string>();
+  for (const file of files) {
+    if (!safePath(file.path) || ['manifest.json', 'identity.json'].includes(file.path) || paths.has(file.path)) {
+      throw new Error(`${file.path}: invalid or duplicate bundle path`);
+    }
+    paths.add(file.path);
+  }
+  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 digest = sha256(manifest);
+  const out = resolve(options.out);
+  const target = join(out, `${options.name}@sha256:${digest}`);
+  let exists = false;
+  try { await lstat(target); exists = true; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  if (exists) { await verifyBundle(target); return target; }
+  const identity = await signDigest(digest, options);
+  await mkdir(out, { recursive: true });
+  const staging = await mkdtemp(join(out, '.build-'));
+  try {
+    for (const file of files) {
+      await mkdir(dirname(join(staging, file.path)), { recursive: true });
+      await writeFile(join(staging, file.path), file.data, { mode: file.path === 'flow' || file.executable ? 0o755 : 0o644 });
+    }
+    await writeFile(join(staging, 'manifest.json'), manifest);
+    await writeFile(join(staging, 'identity.json'), canonicalize(identity));
+    try { await rename(staging, target); }
+    catch (error) {
+      if (!['EEXIST', 'ENOTEMPTY'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      await verifyBundle(target);
+    }
+    return target;
+  } finally { await rm(staging, { recursive: true, force: true }); }
+}
+
+async function signDigest(digest: string, options: BundleOptions) {
+  let seedText = (options.env ?? process.env)['FLOWS_BUILD_KEY'];
+  if (seedText === undefined) {
+    try { seedText = (await readFile(join(options.repo, '.flows/build.key'), 'utf8')).trim(); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  }
+  let seed: Buffer;
+  if (seedText === undefined) {
+    options.warn('identity_ephemeral: bundle can be verified but not attributed');
+    seed = randomBytes(32);
+  } else {
+    seed = Buffer.from(seedText, 'base64');
+    if (seed.length !== 32 || seed.toString('base64') !== seedText) {
+      throw new Error('build key: expected a base64-encoded 32-byte seed');
+    }
+  }
+  const privateKey = createPrivateKey({
+    key: Buffer.concat([Buffer.from('302e020100300506032b657004220420', 'hex'), seed]),
+    format: 'der', type: 'pkcs8',
+  });
+  const publicKey = createPublicKey(privateKey).export({ format: 'der', type: 'spki' }).subarray(-32);
+  return {
+    algorithm: 'ed25519', keyid: sha256(publicKey).slice(0, 16), pubkey_b64: publicKey.toString('base64'),
+    signature_hex: sign(null, Buffer.from(digest, 'hex'), privateKey).toString('hex'),
+  };
+}
+
+async function regularFile(root: string, path: string): Promise<Buffer> {
+  try {
+    const parts = path.split('/');
+    for (let i = 1; i <= parts.length; i++) {
+      const stat = await lstat(join(root, ...parts.slice(0, i)));
+      if (i === parts.length ? !stat.isFile() : !stat.isDirectory()) {
+        throw new Error('expected a regular file, without symlinks');
+      }
+    }
+    return await readFile(join(root, path));
+  } catch (error) {
+    throw new Error(`${path}: ${error instanceof Error ? error.message : 'unreadable'}`);
+  }
+}
+
+/** Verify an untrusted directory without following symlinks or manifest traversal.
+ * Bucket/cache readers supply the requested digest; local builds bind it to the directory name. */
+export async function verifyBundle(directory: string, expectedDigest?: string): Promise<string> {
+  const root = resolve(directory);
+  if (!(await lstat(root)).isDirectory()) throw new Error('manifest.json: bundle must be a directory, not a symlink');
+  const raw = (await regularFile(root, 'manifest.json')).toString('utf8');
+  let manifest: BundleEntry[];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) throw new Error('expected an array');
+    manifest = parsed;
+  } catch { throw new Error('manifest.json: invalid manifest'); }
+  const paths = new Set<string>();
+  let previous = '';
+  for (const entry of manifest) {
+    if (entry === null || typeof entry !== 'object' || typeof entry.path !== 'string'
+      || !safePath(entry.path) || entry.path <= previous
+      || ['manifest.json', 'identity.json'].includes(entry.path)
+      || Object.keys(entry).sort().join(',') !== 'bytes,path,sha256'
+      || !/^[a-f0-9]{64}$/.test(entry.sha256) || !Number.isSafeInteger(entry.bytes) || entry.bytes < 0) {
+      throw new Error('manifest.json: invalid, duplicate, or unsorted entry');
+    }
+    previous = entry.path;
+    paths.add(entry.path);
+    const bytes = await regularFile(root, entry.path);
+    if (bytes.length !== entry.bytes || sha256(bytes) !== entry.sha256) {
+      throw new Error(`${entry.path}: sha256 or byte count mismatch`);
+    }
+  }
+  for (const required of ['spec.canonical.json', 'preflight.json', 'lockfile.json']) {
+    if (!paths.has(required)) throw new Error(`${required}: missing manifest entry`);
+  }
+  const canonical = canonicalize(manifest);
+  if (raw !== canonical) throw new Error('manifest.json: noncanonical bytes');
+  const digest = sha256(canonical);
+  const matchesDigest = expectedDigest === undefined
+    ? basename(root).endsWith(`@sha256:${digest}`) : digest === expectedDigest;
+  if (!matchesDigest) throw new Error('manifest.json: directory digest mismatch');
+  await rejectExtras(root, '', new Set([...paths, 'manifest.json', 'identity.json']));
+  try {
+    const identity = JSON.parse((await regularFile(root, 'identity.json')).toString('utf8'));
+    const publicKey = Buffer.from(identity.pubkey_b64, 'base64');
+    if (identity.algorithm !== 'ed25519' || publicKey.length !== 32
+      || publicKey.toString('base64') !== identity.pubkey_b64
+      || identity.keyid !== sha256(publicKey).slice(0, 16)
+      || !/^[a-f0-9]{128}$/.test(identity.signature_hex)) throw new Error('invalid identity');
+    const key = createPublicKey({
+      key: Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), publicKey]), format: 'der', type: 'spki',
+    });
+    if (!verify(null, Buffer.from(digest, 'hex'), key, Buffer.from(identity.signature_hex, 'hex'))) {
+      throw new Error('signature mismatch');
+    }
+  } catch (error) {
+    throw new Error(`identity.json: ${error instanceof Error ? error.message : 'signature verification failed'}`);
+  }
+  return digest;
+}
+
+async function rejectExtras(root: string, prefix: string, paths: Set<string>): Promise<void> {
+  for (const entry of await readdir(join(root, prefix), { withFileTypes: true })) {
+    const path = prefix + entry.name;
+    if (entry.isDirectory() && [...paths].some(file => file.startsWith(`${path}/`))) {
+      await rejectExtras(root, `${path}/`, paths);
+    } else if (!entry.isFile() || !paths.has(path)) {
+      throw new Error(`${path}: unlisted file or unsupported file type`);
+    }
+  }
+}

package/src/child-stop.ts

@@ -0,0 +1,138 @@
+import type { ChildProcess } from 'node:child_process';
+
+/**
+ * Grace between the graceful signal and the force kill. A tree that ignores
+ * `SIGTERM` still has to go: it is holding the inherited stdio pipes that keep
+ * the `flows run` event loop alive long after the step itself has settled.
+ */
+export const FORCE_KILL_DELAY_MS = 1_000;
+
+/**
+ * The one stop path for a spawned agent process.
+ *
+ * There are three stops — lease abort, execution timeout, and protocol
+ * `terminate` — and the decision they share is whether a signal must address
+ * the process GROUP or the direct child. That decision used to be made at each
+ * call site, which meant it was made once and omitted twice: only abort killed
+ * the group, so a timeout or a protocol violation left the grandchildren alive
+ * holding the pipes they inherited. The step Promise settled; `flows run` never
+ * exited, because those pipe handles stay open and referenced.
+ *
+ * So the decision lives here instead, bound once at the spawn site. A call site
+ * chooses only the FORCE of the stop, never its REACH — and, per
+ * {@link ChildStop.maySettleOnChildExit}, never gets to decide on its own that
+ * a stop is finished.
+ */
+export interface ChildStop {
+  /** Stop the tree now, unconditionally. */
+  kill(): void;
+  /** Ask the tree to stop, then force whatever is still alive. */
+  terminate(): void;
+  /**
+   * Answer the only question a child-level event can raise: the direct child is
+   * gone — may the session settle?
+   *
+   * INVARIANT: a session may not settle until either the process group is
+   * confirmed dead or the escalation has actually run.
+   *
+   * `'close'` and `'error'` are evidence about the CHILD, never about the
+   * group. A descendant that ignores `SIGTERM` and inherited none of the
+   * wrapper's stdio emits exactly those events while it is still running, so no
+   * call site may read one as a dead tree. This is therefore the only place a
+   * pending escalation may be dropped for any reason other than a forced kill,
+   * and it drops one only after asking the group whether it is empty.
+   *
+   * Returns true when settling is safe: no escalation is armed, or the group is
+   * confirmed gone and the now-pointless escalation has been dropped here.
+   * Returns false when an escalation is armed over a group that still answers —
+   * the caller must then leave the settle to that escalation's own deadline.
+   */
+  maySettleOnChildExit(): boolean;
+}
+
+/**
+ * Whether a stop can reach descendants at all. It can only when the spawn asked
+ * for a process group of its own, which needs POSIX and is only worth the
+ * detach on the lease-bound path. Callers pass this same value to `spawn`'s
+ * `detached` and to {@link childStop}, so the spawn flag and the stop strategy
+ * cannot drift apart.
+ */
+export function ownsProcessGroup(signal: AbortSignal | undefined): boolean {
+  return signal !== undefined && process.platform !== 'win32';
+}
+
+export function childStop(
+  child: ChildProcess,
+  ownsGroup: boolean,
+  forceKillDelayMs: number = FORCE_KILL_DELAY_MS,
+): ChildStop {
+  // Pinned at the spawn rather than read per signal. Every interesting use of
+  // this id happens AFTER the direct child has been reaped — the escalation
+  // fires a second later, and the group probe runs on `'close'` — so reading
+  // `child.pid` there would be reading a field the runtime owns and is free to
+  // clear. The group keeps this id for as long as any member of it is alive,
+  // which is exactly the window both of those need to address.
+  const pid = child.pid;
+  let forceTimer: NodeJS.Timeout | undefined;
+  const cancel = (): void => {
+    if (forceTimer !== undefined) clearTimeout(forceTimer);
+    forceTimer = undefined;
+  };
+  /** Whether anything is still in the group. See `maySettleOnChildExit`. */
+  const groupAnswers = (): boolean => {
+    // With no group of our own a stop never reached past the direct child, so
+    // that child's exit IS the whole of our reach and there is nothing left to
+    // ask about.
+    if (!ownsGroup || pid === undefined) return false;
+    try {
+      process.kill(-pid, 0);
+      return true;
+    } catch (error) {
+      // Only `ESRCH` proves the group is empty. `EPERM` proves the opposite —
+      // something is in there that we may not signal — and any other errno
+      // proves nothing at all, so both must read as alive: an unproven group is
+      // not a reason to spare a survivor.
+      return (error as NodeJS.ErrnoException).code !== 'ESRCH';
+    }
+  };
+  const signalTree = (name: NodeJS.Signals): void => {
+    if (ownsGroup && pid !== undefined) {
+      // `-pid` addresses the group this detached child leads, which is every
+      // descendant that has not left it. It throws only once the whole group
+      // is gone — the outcome we were asking for — so fall through and let the
+      // direct-child signal report on a child that never became a leader.
+      try {
+        process.kill(-pid, name);
+        return;
+      } catch { /* the group is gone, or we never led one */ }
+    }
+    child.kill(name);
+  };
+  return {
+    kill: (): void => {
+      cancel();
+      signalTree('SIGKILL');
+    },
+    terminate: (): void => {
+      cancel();
+      signalTree('SIGTERM');
+      forceTimer = setTimeout(() => {
+        forceTimer = undefined;
+        signalTree('SIGKILL');
+      }, forceKillDelayMs);
+      // Deliberately REFERENCED, unlike every other timer we arm. The survivor
+      // this escalation exists for is the one that ignored `SIGTERM` and holds
+      // none of our stdio: nothing it does keeps our loop alive, so an unref'd
+      // escalation would be dropped by the drain in precisely the case it was
+      // armed for. The cost is bounded by `forceKillDelayMs`, is paid only
+      // after a stop was actually issued, and is refunded the moment
+      // `maySettleOnChildExit` confirms the group is empty.
+    },
+    maySettleOnChildExit: (): boolean => {
+      if (forceTimer === undefined) return true;
+      if (groupAnswers()) return false;
+      cancel();
+      return true;
+    },
+  };
+}

package/src/cli/add.ts

@@ -0,0 +1,45 @@
+import { execFileSync } from 'node:child_process';
+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 { PluginError, pluginPackageName } from '../plugin-manifest.js';
+
+export async function addPlugin(name: string, io: CliIo, options: {
+  cwd?: string;
+  install?: (packageName: string, root: string) => void;
+} = {}): Promise<0 | 2> {
+  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.');
+    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 tsPath = join(root, 'tsconfig.json');
+    const tsconfig = existsSync(tsPath) ? { config: JSON.parse(readFileSync(tsPath, 'utf8')) } : { config: {} };
+    if (!tsconfig.config || typeof tsconfig.config !== 'object' || Array.isArray(tsconfig.config) || (tsconfig.config.include !== undefined && (!Array.isArray(tsconfig.config.include) || !tsconfig.config.include.every((p: unknown) => typeof p === 'string')))) throw new PluginError('plugin_manifest_invalid', 'Invalid tsconfig.json include list.');
+    try {
+      (options.install ?? ((pkg, cwd) => { execFileSync('npm', ['install', '--save', pkg], { cwd, encoding: 'utf8', stdio: 'pipe' }); }))(packageName, root);
+    } catch (error) {
+      const message = String((error as { stderr?: unknown }).stderr ?? error);
+      throw new PluginError(/E404|404 Not Found/.test(message) ? 'plugin_unknown' : 'plugin_install_failed', `Could not install ${packageName}.`);
+    }
+    const plugin = readPlugin(join(root, 'node_modules', packageName), packageName);
+    await probePlugin(plugin);
+    if (!existsSync(join(plugin.directory, 'src/index.js'))) throw new PluginError('plugin_manifest_invalid', 'Plugin requires src/index.js.');
+    const declaration = `node_modules/${packageName}/flows-plugin.d.ts`;
+    if (existsSync(join(root, declaration))) {
+      tsconfig.config.include = [...new Set([...(tsconfig.config.include ?? ['**/*']), declaration])];
+      writeFileSync(tsPath, `${JSON.stringify(tsconfig.config, null, 2)}\n`);
+    }
+    config.plugins = [...new Set([...(config.plugins ?? []), packageName])];
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    io.stdout(`Added ${packageName}`);
+    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;
+  }
+}