factoryhub 0.0.0-stage → 0.1.0

package/packages/cli/src/main.mjs

@@ -0,0 +1,68 @@
+// factoryhub: find, run, make and share AI factories from the terminal.
+import process from 'node:process';
+import { readFileSync } from 'node:fs';
+import { parseArgs } from './args.mjs';
+import validate from './commands/validate.mjs';
+import inspect from './commands/inspect.mjs';
+import list from './commands/list.mjs';
+import create from './commands/new.mjs';
+import pack from './commands/pack.mjs';
+import run from './commands/run.mjs';
+import resume from './commands/resume.mjs';
+import exportCommand from './commands/export.mjs';
+import search from './commands/search.mjs';
+import get from './commands/get.mjs';
+import mcp from './commands/mcp.mjs';
+
+export const COMMANDS = [list, inspect, validate, run, resume, create, pack, exportCommand, search, get, mcp];
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/** The streams and environment a command uses. Tests pass their own. */
+export function defaultIo() {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdin: process.stdin,
+    env: process.env,
+    cwd: process.cwd(),
+    fetch: globalThis.fetch,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
+  };
+}
+
+function help(io) {
+  const width = Math.max(...COMMANDS.map((command) => command.name.length));
+  io.stdout.write(`factoryhub ${VERSION}: find, run, make and share AI factories.
+
+Usage: factoryhub <command> [options]
+
+Commands:
+${COMMANDS.map((command) => `  ${command.name.padEnd(width)}  ${command.summary}`).join('\n')}
+
+Run "factoryhub <command> --help" for a command's options.
+A factory is a folder with factory.yaml, flow.yaml and agents/<name>/agent.md.
+The format: spec/factory-format.md in https://github.com/Mindburn-Labs/factoryhub
+`);
+}
+
+/** Runs one command line. Returns the exit code. */
+export async function main(argv, io = defaultIo()) {
+  const [name, ...rest] = argv;
+  if (!name || name === '--help' || name === '-h' || name === 'help') { help(io); return 0; }
+  if (name === '--version' || name === '-v') { io.stdout.write(`${VERSION}\n`); return 0; }
+  const command = COMMANDS.find((item) => item.name === name);
+  if (!command) { io.stderr.write(`Unknown command "${name}". Run "factoryhub --help" for the list.\n`); return 2; }
+  let args;
+  try { args = parseArgs(rest, command.options || {}); } catch (error) {
+    io.stderr.write(`${error.message}\n\n${command.usage}\n`);
+    return 2;
+  }
+  if (args.flags.help) { io.stdout.write(`${command.usage}\n`); return 0; }
+  try {
+    return await command.run(args, io);
+  } catch (error) {
+    io.stderr.write(`${error.message}\n`);
+    return error.usage ? 2 : 1;
+  }
+}

package/packages/cli/src/util.mjs

@@ -0,0 +1,21 @@
+// Shared bits for the commands: styling, output and the engine imports.
+export * as engine from '../../engine/src/factory-engine.mjs';
+export { readFactory, readFolder, writeFiles, listFactoryDirs, usage, HOUSE_FACTORIES } from '../../engine/lib/node.mjs';
+export { summarize, canonicalFiles, matches } from '../../engine/lib/catalog.mjs';
+
+export function styles(io) {
+  const wrap = (open, close) => (text) => (io.color ? `\x1b[${open}m${text}\x1b[${close}m` : String(text));
+  return { bold: wrap(1, 22), dim: wrap(2, 22), red: wrap(31, 39), green: wrap(32, 39), yellow: wrap(33, 39) };
+}
+
+export const out = (io, text = '') => io.stdout.write(`${text}\n`);
+export const err = (io, text = '') => io.stderr.write(`${text}\n`);
+export const json = (io, value) => io.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** Lays rows out in columns, padding every column but the last. */
+export function table(rows) {
+  if (!rows.length) return '';
+  const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => String(row[column] ?? '').length)));
+  return rows.map((row) => row.map((cell, column) => (column === row.length - 1 ? String(cell ?? '') : String(cell ?? '').padEnd(widths[column]))).join('  ').trimEnd()).join('\n');
+}

package/packages/engine/lib/catalog.mjs

@@ -0,0 +1,50 @@
+// A factory's public summary, the same fields the factoryhub site lists, and
+// the canonical bundle those fields and hashes are computed from.
+import { parseBundle, withForeman, bundleHash, inputSchema } from '../src/factory-engine.mjs';
+
+/**
+ * The canonical bundle: the source files plus the foreman the engine writes
+ * from the flow when the author did not write one. An author's own foreman
+ * is kept byte for byte. Its hash is the factory's identity.
+ */
+export function canonicalFiles(files) {
+  return withForeman(files);
+}
+
+/** A summary of a factory for listings, search and `inspect`. */
+export async function summarize(files, { id } = {}) {
+  const bundle = canonicalFiles(files);
+  const { ok, errors, warnings, factory } = parseBundle(bundle);
+  return {
+    id: id || factory.name,
+    name: factory.name,
+    title: factory.title,
+    description: factory.description,
+    author: factory.author,
+    version: factory.version,
+    license: factory.license,
+    tags: factory.tags,
+    time: factory.time,
+    valid: ok,
+    runnable: ok && factory.runnable,
+    errors,
+    warnings,
+    blockers: factory.blockers,
+    inputs: factory.inputs,
+    steps: factory.steps.map((step) => ({ id: step.id, title: step.title, kind: step.kind, agent: step.agent, needs: step.needs, target: step.target, tools: step.tools, missing: step.missing })),
+    agents: Object.values(factory.agents).map((agent) => ({ name: agent.name, description: agent.description, type: agent.type })),
+    tools: [...new Set(factory.steps.flatMap((step) => [...step.tools, ...step.missing]))].sort(),
+    done: factory.done,
+    files: Object.keys(bundle),
+    sha256: await bundleHash(bundle),
+    ...(ok ? { inputSchema: inputSchema(factory) } : {}),
+  };
+}
+
+/** Keeps the entries whose words contain every word of the query. */
+export function matches(entry, query) {
+  const words = String(query || '').toLowerCase().split(/\s+/).filter(Boolean);
+  if (!words.length) return true;
+  const text = [entry.id, entry.name, entry.title, entry.description, ...(entry.tags || [])].join(' ').toLowerCase();
+  return words.every((word) => text.includes(word));
+}

package/packages/engine/lib/hub.mjs

@@ -0,0 +1,71 @@
+// A client for the public read API of the factoryhub site.
+//
+//   GET {base}/api/factories     the published catalogue
+//   GET {base}/f/{id}.json       one factory as a transfer bundle, each file with its SHA-256
+//
+// While the site is in private preview it answers only requests that carry
+// the preview access key in the `x-hub-access-key` header. Everyone else
+// gets 404. Set FACTORYHUB_ACCESS_KEY to send it.
+import { fromEnvelope } from '../src/factory-engine.mjs';
+import { matches } from './catalog.mjs';
+
+export const DEFAULT_HUB = 'https://factory.mindburn.org';
+export const ACCESS_HEADER = 'x-hub-access-key';
+const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export class HubError extends Error {
+  constructor(message, { status, preview = false } = {}) {
+    super(message);
+    this.status = status;
+    this.preview = preview;
+  }
+}
+
+export function hubClient({ baseUrl, accessKey, env = process.env, fetchImpl = fetch } = {}) {
+  const base = String(baseUrl || env.FACTORYHUB_BASE_URL || DEFAULT_HUB).replace(/\/+$/, '');
+  const key = accessKey ?? env.FACTORYHUB_ACCESS_KEY ?? '';
+  const headers = { accept: 'application/json', ...(key ? { [ACCESS_HEADER]: key } : {}) };
+
+  async function getJson(path) {
+    let response;
+    try {
+      response = await fetchImpl(`${base}${path}`, { headers, signal: AbortSignal.timeout(30000) });
+    } catch (error) {
+      throw new HubError(`Could not reach ${base}: ${error.message}`);
+    }
+    const text = await response.text();
+    if (response.status === 404 && /private preview/i.test(text)) {
+      throw new HubError(`${base} is in private preview and answers only with an access key. ${key ? 'The FACTORYHUB_ACCESS_KEY you set was not accepted.' : 'Set FACTORYHUB_ACCESS_KEY to the key you were given.'}`, { status: 404, preview: true });
+    }
+    let body = null;
+    try { body = JSON.parse(text); } catch { /* reported below */ }
+    if (!response.ok) throw new HubError(body?.message || `${base}${path} answered with status ${response.status}.`, { status: response.status });
+    if (!body || typeof body !== 'object') throw new HubError(`${base}${path} did not answer with JSON.`, { status: response.status });
+    return body;
+  }
+
+  return {
+    base,
+    /** Every published factory in the catalogue. */
+    async list() {
+      const body = await getJson('/api/factories');
+      if (!Array.isArray(body.factories)) throw new HubError('The catalogue answer has no factories list.');
+      return body.factories;
+    },
+    /** Published factories whose id, title, description or tags contain every word of `query`. */
+    async search(query) {
+      return (await this.list()).filter((entry) => matches(entry, query));
+    },
+    /** One factory's files, each checked against its recorded SHA-256. */
+    async get(id) {
+      if (!ID.test(String(id || ''))) throw new HubError(`"${id}" is not a factory id. Ids are lowercase words joined by hyphens.`);
+      const envelope = await getJson(`/f/${id}.json`);
+      const read = await fromEnvelope(envelope);
+      if (read.problems.length) throw new HubError(`The bundle for ${id} did not pass its checks:\n${read.problems.map((item) => `  - ${item}`).join('\n')}`);
+      return { id, files: read.files, leftOut: read.leftOut, source: envelope.source?.url || `${base}/f/${id}` };
+    },
+    sourceUrl(id) {
+      return `${base}/f/${id}`;
+    },
+  };
+}

package/packages/engine/lib/node.mjs

@@ -0,0 +1,114 @@
+// Node.js helpers around the engine: read a factory from a folder, a bundle
+// file or an address, and write one back to disk. The engine itself stays
+// free of file system access so the same code runs in a browser.
+import { readFile, writeFile, readdir, mkdir, lstat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative, resolve, dirname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ALLOWED_PATH, fromEnvelope, normalizeFiles } from '../src/factory-engine.mjs';
+
+// The folders a factory's companion files may live in. Only these are walked,
+// so a factory kept inside a project never pulls in node_modules or the like.
+export const SOURCE_FOLDERS = new Set(['agents', 'automations', 'scorers', 'runners', 'routers', 'webhooks', 'benchmarks', 'skills', 'self-improvement',
+  'profiles', 'flows', 'schemas', 'prompts', 'assets', 'examples', 'checks', 'fixtures', 'capabilities', 'policies', 'adapters', 'ui']);
+
+// Files the runner and packer put next to a factory. They are never source.
+const GENERATED = new Set(['RUNNING.md', 'run.mjs', 'factory-engine.mjs', 'author-tests.mjs', 'INPUTS.schema.json', 'FACTORY-HUB.json']);
+
+/** The house factories that ship in this repository. */
+export const HOUSE_FACTORIES = resolve(dirname(fileURLToPath(import.meta.url)), '../../../factories');
+
+/**
+ * Reads the files of a factory folder, as the engine admits them.
+ * `skipped` lists files that look meant for the factory but are not part of it.
+ */
+export async function readFolder(root) {
+  const files = {};
+  const skipped = [];
+  const walk = async (dir) => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const { name } = entry;
+      if (name.startsWith('.')) continue;
+      const path = join(dir, name);
+      const rel = relative(root, path).split(sep).join('/');
+      if (entry.isSymbolicLink()) {
+        if (dir !== root || SOURCE_FOLDERS.has(name) || ALLOWED_PATH.test(rel)) throw new Error(`Factory source cannot contain a symbolic link: ${rel}`);
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (SOURCE_FOLDERS.has(name) || dir !== root) await walk(path);
+        continue;
+      }
+      if (dir === root && GENERATED.has(name)) continue;
+      if (ALLOWED_PATH.test(rel)) files[rel] = await readFile(path, 'utf8');
+      else if (dir !== root || /\.(md|ya?ml)$/i.test(name)) skipped.push(rel);
+    }
+  };
+  await walk(root);
+  return { files: normalizeFiles(files), skipped };
+}
+
+const isUrl = (value) => /^https?:\/\//i.test(String(value));
+
+/**
+ * Resolves what a person typed to a factory: a folder, a bundle `.json` file,
+ * an http(s) address of a bundle, or the id of a house factory.
+ * Returns { files, leftOut, source: { kind, location, id } }.
+ */
+export async function readFactory(target, { cwd = process.cwd(), fetchImpl = fetch, headers = {}, houseDir = HOUSE_FACTORIES } = {}) {
+  if (!target) throw usage('Name a factory: a folder, a bundle .json file, an address, or a house factory id.');
+  if (isUrl(target)) {
+    const response = await fetchImpl(target, { headers: { accept: 'application/json', ...headers } });
+    if (!response.ok) throw new Error(`${target} answered with status ${response.status}.`);
+    const read = await fromEnvelope(await response.json());
+    if (read.problems.length) throw new Error(`That bundle could not be read:\n${read.problems.map((problem) => `  - ${problem}`).join('\n')}`);
+    return { files: read.files, leftOut: read.leftOut, source: { kind: 'url', location: target } };
+  }
+  const path = resolve(cwd, target);
+  if (existsSync(path) && (await lstat(path)).isFile()) {
+    if (!path.endsWith('.json')) throw usage(`${target} is a file. Point at a factory folder or a bundle .json file.`);
+    const read = await fromEnvelope(JSON.parse(await readFile(path, 'utf8')));
+    if (read.problems.length) throw new Error(`That bundle could not be read:\n${read.problems.map((problem) => `  - ${problem}`).join('\n')}`);
+    return { files: read.files, leftOut: read.leftOut, source: { kind: 'bundle', location: path } };
+  }
+  if (existsSync(path)) {
+    if (!existsSync(join(path, 'factory.yaml'))) throw usage(`No factory.yaml in ${target}.`);
+    const { files, skipped } = await readFolder(path);
+    return { files, leftOut: skipped, source: { kind: 'folder', location: path } };
+  }
+  if (/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(target) && existsSync(join(houseDir, target, 'factory.yaml'))) {
+    const location = join(houseDir, target);
+    const { files, skipped } = await readFolder(location);
+    return { files, leftOut: skipped, source: { kind: 'house', location, id: target } };
+  }
+  throw usage(`No factory at ${target}. Use a folder with a factory.yaml, a bundle .json file, an address, or one of: ${(await listFactoryDirs(houseDir)).join(', ')}.`);
+}
+
+/** The ids of the factory folders directly inside `dir`, sorted. */
+export async function listFactoryDirs(dir = HOUSE_FACTORIES) {
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory() && existsSync(join(dir, entry.name, 'factory.yaml'))).map((entry) => entry.name).sort();
+}
+
+/**
+ * Writes bundle files under `dir`. Every path must be one the engine admits,
+ * so a bundle from elsewhere cannot write outside its folder.
+ */
+export async function writeFiles(dir, files, { allow = (path) => ALLOWED_PATH.test(path) } = {}) {
+  const root = resolve(dir);
+  for (const [path, content] of Object.entries(files)) {
+    if (!allow(path)) throw new Error(`Refusing to write "${path}": it is not a factory file.`);
+    const target = resolve(root, path);
+    if (!target.startsWith(root + sep)) throw new Error(`Refusing to write outside ${root}: ${path}`);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, content);
+  }
+}
+
+/** An error that means the person asked for something unclear: exit code 2. */
+export function usage(message) {
+  return Object.assign(new Error(message), { usage: true });
+}

package/packages/engine/lib/providers.mjs

@@ -0,0 +1,52 @@
+// Chooses the model a run uses, from the person's own key or a local server.
+// Nothing here has a key of its own: every call is billed to whoever runs it.
+import { anthropicProvider, openaiProvider } from '../src/factory-engine.mjs';
+
+export const PROVIDERS = ['anthropic', 'openai', 'openrouter', 'ollama', 'openai-compatible'];
+export const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+export const OLLAMA_BASE_URL = 'http://localhost:11434/v1';
+/** Where each hosted provider's key may go. Any other address is a custom server. */
+export const OFFICIAL = { anthropic: 'https://api.anthropic.com', openai: 'https://api.openai.com/v1', openrouter: OPENROUTER_BASE_URL };
+const KEY_OF = { anthropic: 'ANTHROPIC_API_KEY', openai: 'OPENAI_API_KEY', openrouter: 'OPENROUTER_API_KEY' };
+const DEFAULT_MODELS = { anthropic: 'claude-sonnet-5-5', openai: 'gpt-5', openrouter: 'openrouter/auto' };
+
+const problem = (message) => Object.assign(new Error(message), { usage: true });
+const trim = (url) => String(url).replace(/\/+$/, '');
+
+/**
+ * Picks a provider.
+ *
+ * - `provider` names one of PROVIDERS. Without it: a `baseUrl` means an
+ *   OpenAI-compatible server, otherwise the first key found among
+ *   ANTHROPIC_API_KEY, OPENAI_API_KEY and OPENROUTER_API_KEY decides.
+ * - A key from the environment goes only to its provider's own address. Any
+ *   other `baseUrl` receives a key only from the variable named in
+ *   `apiKeyEnv`, whichever provider is named, so a changed address can never
+ *   carry a provider key away.
+ * - `model` falls back to FACTORYHUB_MODEL, then to a default for hosted
+ *   providers. Local servers need a model name.
+ */
+export function chooseProvider({ provider, model, baseUrl, apiKeyEnv, env = process.env, fetchImpl = fetch } = {}) {
+  let kind = provider ? String(provider).toLowerCase() : null;
+  if (kind && !PROVIDERS.includes(kind)) throw problem(`Unknown provider "${provider}". Use one of: ${PROVIDERS.join(', ')}.`);
+  if (!kind) {
+    if (baseUrl) kind = 'openai-compatible';
+    else if (env.ANTHROPIC_API_KEY) kind = 'anthropic';
+    else if (env.OPENAI_API_KEY) kind = 'openai';
+    else if (env.OPENROUTER_API_KEY) kind = 'openrouter';
+  }
+  if (!kind) throw problem('No model configured. Set ANTHROPIC_API_KEY, OPENAI_API_KEY or OPENROUTER_API_KEY, or use a server on your machine: provider "ollama" with a model name, or an OpenAI-compatible base URL with a model name.');
+  const chosen = model || env.FACTORYHUB_MODEL || DEFAULT_MODELS[kind];
+  if (!chosen) throw problem(`Name the model to use with ${kind}.`);
+  const keyFrom = (name) => {
+    const value = env[name];
+    if (!value) throw problem(`${name} is not set.`);
+    return value;
+  };
+  const address = baseUrl ? trim(baseUrl) : OFFICIAL[kind] || (kind === 'ollama' ? OLLAMA_BASE_URL : null);
+  if (!address) throw problem('An OpenAI-compatible server needs a base URL.');
+  // The provider's own key for its own address; otherwise only a key the person named.
+  const apiKey = apiKeyEnv ? keyFrom(apiKeyEnv) : KEY_OF[kind] && address === OFFICIAL[kind] ? keyFrom(KEY_OF[kind]) : '';
+  if (kind === 'anthropic') return anthropicProvider({ apiKey, model: chosen, fetchImpl, baseUrl: address });
+  return openaiProvider({ apiKey, model: chosen, fetchImpl, baseUrl: address });
+}

package/packages/engine/lib/run.mjs

@@ -0,0 +1,131 @@
+// Runs a factory on this machine: the host the engine needs (model, web
+// reading, events) and the start, decide and resume steps that the CLI and
+// the MCP server share. The engine decides nothing for the person: a run
+// that reaches an approval step waits until someone answers.
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { parseBundle, checkInputs, newRun, runToEnd, resume, decisionProblem, ensureApprovalIdentity, isPublicAddress, htmlToText, DEFAULT_LIMITS, sha256 } from '../src/factory-engine.mjs';
+import { canonicalFiles } from './catalog.mjs';
+
+export const USER_AGENT = 'Mozilla/5.0 (compatible; FactoryRunner/1.0)';
+
+const v4 = (ip) => ip.split('.').map(Number);
+/** True for loopback, private, link-local, shared, reserved and multicast addresses. */
+export function isPrivateIp(ip) {
+  if (isIP(ip) === 4) {
+    const [a, b] = v4(ip);
+    return a === 0 || a === 10 || a === 127 || a >= 224 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254)
+      || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 192 && b === 0) || (a === 198 && (b === 18 || b === 19));
+  }
+  const low = ip.toLowerCase();
+  const mapped = low.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped) return isPrivateIp(mapped[1]);
+  return low === '::' || low === '::1' || /^f[cd]/.test(low) || /^fe[89ab]/.test(low) || /^ff/.test(low) || low.startsWith('64:ff9b:');
+}
+
+/**
+ * The host object the engine runs against. `fetchImpl` reads web pages.
+ * Only public http(s) addresses are read: the engine's check on the address
+ * text, and here also every address the host name resolves to, so a public
+ * looking name that points at this machine or its network is refused. Every
+ * redirect is checked again. The check happens before the request; a name
+ * whose answer changes in between is not caught.
+ */
+export function nodeHost({ provider, emit = () => {}, fetchImpl = fetch, resolve = (host) => lookup(host, { all: true, verbatim: true }), limits = DEFAULT_LIMITS, now = () => Date.now() }) {
+  return {
+    provider,
+    limits,
+    now,
+    async fetchPage(address) {
+      let url = address;
+      for (let hop = 0; hop < 6; hop += 1) {
+        if (!isPublicAddress(url)) throw new Error('that is not a public web address');
+        let answers;
+        try { answers = await resolve(new URL(url).hostname); } catch { throw new Error('the address could not be found'); }
+        if (!answers.length || answers.some((answer) => isPrivateIp(answer.address))) throw new Error('that address points at a private network');
+        const response = await fetchImpl(url, { redirect: 'manual', headers: { 'user-agent': USER_AGENT, accept: 'text/html,*/*;q=0.5' }, signal: AbortSignal.timeout(20000) });
+        if (response.status >= 300 && response.status < 400) { url = new URL(response.headers.get('location') || '', url).href; continue; }
+        if (!response.ok) throw new Error(`the site answered with status ${response.status}`);
+        return `Address: ${url}\n\n${htmlToText(await response.text(), url)}`;
+      }
+      throw new Error('the page redirects too many times');
+    },
+    emit,
+  };
+}
+
+/**
+ * Prepares a run: parses the factory, refuses one that cannot run here, and
+ * checks the inputs before any model is called.
+ */
+export function prepareRun({ files, inputs = {}, id, runner = { mode: 'local' } }) {
+  const parsed = parseBundle(canonicalFiles(files));
+  if (!parsed.ok) return { ok: false, problems: parsed.errors };
+  if (!parsed.factory.runnable) {
+    return { ok: false, problems: parsed.factory.blockers.length ? parsed.factory.blockers : ['This factory has no flow.yaml, so there are no steps to run. Follow agents/foreman/agent.md in an agent instead.'] };
+  }
+  const checked = checkInputs(parsed.factory, inputs);
+  if (!checked.ok) return { ok: false, problems: checked.problems, factory: parsed.factory };
+  const state = newRun({ id: id || `local-${Date.now().toString(36)}`, factory: parsed.factory, inputs: checked.inputs, runner });
+  return { ok: true, state, factory: parsed.factory };
+}
+
+/**
+ * Runs until the factory is done, fails, is stopped by the person, or waits
+ * at an approval step. `onApproval` may answer decisions; without it the run
+ * is returned waiting.
+ */
+export async function continueRun(state, host, onApproval) {
+  await runToEnd(state, host, onApproval);
+  await ensureApprovalIdentity(state);
+  return state;
+}
+
+/** What a person must see to decide, and the values a decision must name. */
+export async function pendingDecision(state) {
+  if (state.status !== 'waiting' || !state.approval) return null;
+  await ensureApprovalIdentity(state);
+  const text = state.artifacts[state.approval.artifact] || '';
+  return {
+    step: state.approval.step,
+    title: state.approval.title,
+    ask: state.approval.ask,
+    shows: state.approval.artifact,
+    text,
+    seen_sha256: await sha256(text),
+    approval_id: state.approval.id,
+    revisions_left: state.approval.revisionsLeft,
+  };
+}
+
+/**
+ * Records a person's decision on a waiting run. Returns '' when accepted, or
+ * the engine's reason when not: not_waiting, bad_action, unseen, stale or
+ * no_revisions.
+ */
+export function decide(state, { action, note = '', seen, approvalId }) {
+  const decision = { action, note, seen, approvalId };
+  const why = decisionProblem(state, decision);
+  if (why) return why;
+  resume(state, decision);
+  return '';
+}
+
+/**
+ * A run restored from JSON is read again from its own files, so its steps
+ * always match the source it carries.
+ */
+export function restoreRun(saved) {
+  if (!saved || typeof saved !== 'object' || !saved.factory?.files || typeof saved.factory.files !== 'object') throw new Error('This is not a saved factory run.');
+  const parsed = parseBundle(saved.factory.files);
+  if (!parsed.ok || !parsed.factory.runnable) throw new Error('The saved run carries a factory that cannot run here.');
+  return { ...saved, factory: parsed.factory };
+}
+
+/** A short account of how a run ended, for people and for tool results. */
+export function outcome(state) {
+  if (state.status === 'done') return { status: 'done', deliverable: state.deliverable, review: state.receipt?.deliverable_review?.status, flags: state.receipt?.flags || [] };
+  if (state.status === 'waiting') return { status: 'waiting', step: state.approval?.step };
+  if (state.status === 'stopped') return { status: 'stopped', step: state.stopped?.step, note: state.stopped?.note || '' };
+  return { status: state.status, error: state.error, failure: state.failure };
+}