factoryhub 0.0.0-stage → 0.1.1

package/packages/cli/src/commands/pull.mjs

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { engine, out, err, json, styles, usage, connect, plural, BASE_URL_HELP } from '../util.mjs';
+import { writePulled, PULL_MANIFEST } from '../../../engine/lib/node.mjs';
+
+export default {
+  name: 'pull',
+  usage: `Usage: factoryhub pull <id> [--out dir] [--force] [--partial] [--base-url url] [--json]
+
+Downloads the factory's transfer bundle, checks every file against its
+SHA-256 and the files together against the bundle hash in the same answer,
+and writes them to <dir>/<id>/. A bundle that fails a check writes nothing.
+The hashes prove the files arrived as the hub sent them; they are not a
+signature, so they do not prove who wrote the factory.
+
+A bundle that cannot be checked whole, because it has no bundle hash or
+leaves out files it names, is refused unless you pass --partial.
+
+Logged in with the factories:read scope, it also pulls your private
+factories. Without a login it pulls published and unlisted ones.
+
+Options:
+  --out       the parent folder (default: the current folder)
+  --force     replace an earlier pull in that folder: files the earlier pull
+              wrote (listed in its ${PULL_MANIFEST}) that the new version
+              no longer has are removed; no other file is touched
+  --partial   accept a bundle that cannot be checked whole, and say so
+  --base-url  ${BASE_URL_HELP}
+  --json      print what was written as JSON`,
+  options: { boolean: ['force', 'partial', 'json'], string: ['out', 'base-url'] },
+  async run({ positional, flags }, io) {
+    const [id, ...rest] = positional;
+    if (!id || rest.length) throw usage('Name the factory to pull: factoryhub pull <id>');
+    const folder = resolve(io.cwd, flags.out || '.', id);
+    if (existsSync(folder) && !flags.force) throw usage(`${relative(io.cwd, folder) || folder} already exists. Pass --force to write into it.`);
+    const { hub } = await connect(flags, io);
+    const factory = await hub.pull(id, { partial: Boolean(flags.partial) });
+    const { removed } = await writePulled(folder, factory.files, { replace: Boolean(flags.force), record: { id, sha256: factory.sha256, source: factory.source, partial: factory.partial } });
+    const parsed = engine.parseBundle(factory.files);
+    const where = relative(io.cwd, folder) || folder;
+    if (flags.json) {
+      json(io, { id, folder: where, files: Object.keys(factory.files), removed, sha256: factory.sha256, partial: factory.partial, unchecked: factory.unchecked, valid: parsed.ok, runnable: parsed.ok && parsed.factory.runnable, source: factory.source, leftOut: factory.leftOut });
+      return parsed.ok ? 0 : 1;
+    }
+    const s = styles(io);
+    const state = !parsed.ok ? s.red('invalid') : parsed.factory.runnable ? s.green('runs here') : s.yellow('does not run here');
+    out(io, `${s.green('saved')}  ${where}/  ${parsed.factory.title} v${parsed.factory.version}, ${plural(Object.keys(factory.files).length, 'file')}, ${state}`);
+    if (factory.partial) {
+      err(io, s.yellow(`Partial, as --partial allowed: every file written matched its SHA-256, but the files were not checked as a whole.\n${factory.unchecked.map((item) => `  - ${item}`).join('\n')}`));
+    } else {
+      out(io, s.dim(`Every file matched its SHA-256, and together they match the bundle hash ${factory.sha256.slice(0, 12)} in the hub's answer.`));
+    }
+    if (removed.length) out(io, `Removed, from the earlier pull: ${removed.join(', ')}`);
+    if (factory.leftOut.length) out(io, `Not part of the factory, so not written: ${factory.leftOut.join(', ')}`);
+    out(io, `Source: ${factory.source}`);
+    if (parsed.ok && parsed.factory.runnable) out(io, `\nNext: ${s.bold(`factoryhub run ${where}`)} runs it here with your own model.`);
+    return parsed.ok ? 0 : 1;
+  },
+};

package/packages/cli/src/commands/push.mjs

@@ -0,0 +1,115 @@
+import { existsSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { resolve, relative, join, dirname, basename } from 'node:path';
+import { engine, readFolder, canonicalFiles, out, err, json, styles, usage, connect, plural, BASE_URL_HELP } from '../util.mjs';
+
+/**
+ * The files git ignores in `folder`, by `git check-ignore`. Returns
+ * { ignored, checked }: `checked` is false when git could not say (no git, or
+ * not a repository), and then `gitignore` tells whether the folder has a
+ * .gitignore that was therefore not applied.
+ */
+export function gitIgnored(folder, paths) {
+  if (!paths.length) return { ignored: [], checked: true };
+  const answer = spawnSync('git', ['-C', folder, 'check-ignore', '--stdin', '-z'], { input: `${paths.join('\0')}\0`, encoding: 'utf8', timeout: 10000 });
+  // 0: some are ignored, 1: none are, anything else: git could not tell.
+  if (answer.error || ![0, 1].includes(answer.status)) return { ignored: [], checked: false, gitignore: existsSync(join(folder, '.gitignore')) };
+  const ignored = answer.stdout.split('\0').filter(Boolean).map((path) => path.replace(/\\/g, '/'));
+  return { ignored: paths.filter((path) => ignored.includes(path)), checked: true };
+}
+
+/**
+ * The files a push sends. A folder, or the factory.yaml inside one. A
+ * factory.yaml with no folder around it is a single-file factory: that
+ * format is read here once the engine has its parser.
+ */
+export async function readSource(target, io) {
+  const path = resolve(io.cwd, target || '.');
+  if (existsSync(path) && (await stat(path)).isFile()) {
+    if (!/\.ya?ml$/.test(path)) throw usage(`${target} is a file. Push a factory folder: factoryhub push <folder>`);
+    const folder = dirname(path);
+    if (basename(path) === 'factory.yaml' && existsSync(join(folder, 'flow.yaml'))) return { folder, files: (await readFolder(folder)).files };
+    throw usage(`${target} looks like a single-file factory. This version of factoryhub pushes factory folders; push the folder that holds it.`);
+  }
+  if (!existsSync(join(path, 'factory.yaml'))) throw usage(`${relative(io.cwd, path) || '.'} has no factory.yaml, so it is not a factory folder. Name the folder: factoryhub push <folder>`);
+  return { folder: path, files: (await readFolder(path)).files };
+}
+
+/**
+ * Reads a factory and refuses one the hub would refuse, before any request.
+ * Files git ignores in that folder are left out, and listed in `ignored`.
+ */
+export async function readForPush(target, io) {
+  const { folder, files: all } = await readSource(target, io);
+  const git = gitIgnored(folder, Object.keys(all));
+  const files = Object.fromEntries(Object.entries(all).filter(([path]) => !git.ignored.includes(path)));
+  if (git.ignored.includes('factory.yaml')) throw usage(`git ignores ${relative(io.cwd, join(folder, 'factory.yaml')) || 'factory.yaml'}, so this folder is not pushed. Push a folder git does not ignore.`);
+  if (!git.checked && git.gitignore) err(io, styles(io).yellow(`git could not check ${relative(io.cwd, folder) || '.'}/.gitignore, so it was not applied: look at the file list below before you push.`));
+  const parsed = engine.parseBundle(canonicalFiles(files));
+  if (!parsed.ok) throw new Error(`Not pushed: this is not a valid factory yet. Fix these, then push again:\n${parsed.errors.map((error) => `  - ${error}`).join('\n')}\nCheck with: factoryhub validate ${target || '.'}`);
+  return { folder, files, factory: parsed.factory, ignored: git.ignored };
+}
+
+const size = (text) => {
+  const bytes = new TextEncoder().encode(text).byteLength;
+  return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+};
+
+export default {
+  name: 'push',
+  usage: `Usage: factoryhub push [folder | folder/factory.yaml] [--parent id] [--dry-run] [--base-url url] [--json]
+
+Checks the folder with the same rules the site uses, lists the files it
+will send, then saves them to your account as a private factory and prints
+its id and address. Nobody else can see it until you run
+"factoryhub publish <id>". Only factory files are sent: files outside the
+format, files whose names start with a dot, and files git ignores in that
+folder are left out. With --dry-run, nothing is sent.
+
+With --parent, the push is a new revision of your own factory, or a private
+copy of another factory you can open, that names it as its parent. The same
+files as the parent save nothing new.
+
+Needs a login with the factories:write scope ("factoryhub login").
+
+Options:
+  --parent    the factory this revises or copies
+  --dry-run   list what would be sent, and send nothing
+  --base-url  ${BASE_URL_HELP}
+  --json      print the hub's answer as JSON`,
+  options: { boolean: ['json', 'dry-run'], string: ['parent', 'base-url'] },
+  async run({ positional, flags }, io) {
+    if (positional.length > 1) throw usage('Push one folder at a time: factoryhub push <folder>');
+    const { files, factory, ignored } = await readForPush(positional[0], io);
+    const s = styles(io);
+    const list = Object.keys(files);
+    if (flags['dry-run']) {
+      if (flags.json) { json(io, { dryRun: true, files: list, ignored }); return 0; }
+      out(io, `Would send ${plural(list.length, 'file')} for ${factory.title} v${factory.version}:`);
+      for (const path of list) out(io, `  ${path}  ${s.dim(size(files[path]))}`);
+      if (ignored.length) out(io, s.dim(`Left out, ignored by git: ${ignored.join(', ')}`));
+      out(io, s.dim('Nothing was sent (--dry-run).'));
+      return 0;
+    }
+    const { hub } = await connect(flags, io, { needToken: true });
+    if (!flags.json) {
+      err(io, `Sending ${plural(list.length, 'file')}: ${list.join(', ')}`);
+      if (ignored.length) err(io, s.dim(`Left out, ignored by git: ${ignored.join(', ')}`));
+    }
+    const answer = await hub.push(files, { parent: flags.parent });
+    if (flags.json) { json(io, answer); return 0; }
+    const saved = answer.factory || {};
+    if (answer.unchanged) {
+      out(io, `Nothing new: these files are exactly ${s.bold(saved.id)}.\n  Page  ${saved.url}`);
+      return 0;
+    }
+    out(io, `${s.green('Saved privately')} to your account: ${factory.title} v${factory.version}, ${plural(Object.keys(files).length, 'file')}.`);
+    out(io, `  ID    ${s.bold(saved.id)}`);
+    out(io, `  Page  ${saved.url}`);
+    if (answer.parent) out(io, `  From  ${answer.parent}`);
+    if (!factory.runnable) err(io, s.yellow(`It does not run yet: ${factory.blockers.join(' ')}`));
+    out(io, `\nOnly you can see it. Next: ${s.bold(`factoryhub publish ${saved.id}`)} makes it public.`);
+    return 0;
+  },
+};

package/packages/cli/src/commands/resume.mjs

@@ -0,0 +1,66 @@
+import { readFile, rm } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { usage } from '../util.mjs';
+import { restoreRun, decide, pendingDecision } from '../../../engine/lib/run.mjs';
+import { drive, lineReader, providerFor } from './run.mjs';
+
+const REASONS = {
+  not_waiting: 'This run is not waiting for a decision.',
+  bad_action: 'The decision must be approve, revise or reject.',
+  unseen: 'Pass --seen with the SHA-256 printed with the decision text.',
+  stale: '--seen does not match the text this run is waiting on. Show the person the current text (factoryhub resume <file> --show) and use its hash.',
+  no_revisions: 'This step has been sent back as often as the factory allows: approve or reject it.',
+};
+
+export default {
+  name: 'resume',
+  usage: `Usage: factoryhub resume <run.json> --decision approve|revise|reject --seen <sha256> [--note text]
+       factoryhub resume <run.json> --show
+
+Continues a run that "factoryhub run --save <run.json>" saved at a decision.
+The decision must be the person's own. --seen is the SHA-256 of the exact
+text they were shown, printed with it, so a decision cannot land on other
+text. The run continues with the same provider and model, using the key in
+this environment, until it is done or reaches the next decision, where it is
+saved to the same file again.
+
+Exit codes: as for "factoryhub run".
+
+Options:
+  --decision  approve, revise (with --note saying what to change) or reject
+  --seen      the SHA-256 of the text the person saw
+  --note      what to change, for revise
+  --show      print the waiting decision and its hash, change nothing
+  --out       where to save the deliverable
+  --yes, -y   approve every later decision without asking (recorded as
+              runner mode "cli --yes" in the receipt)
+  --json      print the outcome as JSON`,
+  options: { boolean: ['show', 'yes', 'json'], string: ['decision', 'seen', 'note', 'out'], alias: { y: 'yes' } },
+  async run({ positional, flags }, io) {
+    const [file] = positional;
+    if (!file) throw usage('Name the saved run: factoryhub resume run.json --decision approve --seen <sha256>');
+    const path = resolve(io.cwd, file);
+    const state = restoreRun(JSON.parse(await readFile(path, 'utf8')));
+    const pending = await pendingDecision(state);
+    if (flags.show) {
+      if (!pending) throw usage('This run is not waiting for a decision.');
+      io.stdout.write(flags.json ? `${JSON.stringify({ step: pending.step, title: pending.title, ask: pending.ask, text: pending.text, seen_sha256: pending.seen_sha256 }, null, 2)}\n` : `${pending.title}\n\n${pending.text}\n\n${pending.ask}\n\nseen: ${pending.seen_sha256}\n`);
+      return 0;
+    }
+    if (!['approve', 'revise', 'reject'].includes(flags.decision)) throw usage('Give the person\'s decision: --decision approve, revise or reject.');
+    if (flags.decision === 'revise' && !String(flags.note || '').trim()) throw usage('A revise decision needs --note saying what to change.');
+    const why = decide(state, { action: flags.decision, note: flags.note || '', seen: flags.seen, approvalId: state.approval?.id });
+    if (why) throw usage(REASONS[why] || why);
+    if (flags.yes) state.runner = { ...state.runner, mode: 'cli --yes' };
+    const provider = providerFor(state.cli || {}, io);
+    const reader = lineReader(io);
+    try {
+      const code = await drive(state, { provider, flags, io, reader, saveTo: path });
+      // A finished or stopped run has nothing left to resume.
+      if (code !== 3) await rm(path, { force: true });
+      return code;
+    } finally {
+      reader.close();
+    }
+  },
+};

package/packages/cli/src/commands/run.mjs

@@ -0,0 +1,352 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, relative, dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { engine, readFactory, canonicalFiles, out, json, styles, usage } from '../util.mjs';
+import { chooseProvider } from '../../../engine/lib/providers.mjs';
+import { nodeHost, prepareRun, continueRun, pendingDecision } from '../../../engine/lib/run.mjs';
+import { admitFactory, plannedCatalog, cleanTerminalText, displayLine, WRITE_REFUSED } from '../../../engine/src/tool-sources.mjs';
+import { toolSourcePlan, openToolSources, openThings, declaredPlan, consentText, checkDeclaredAddress } from '../tool-sources.mjs';
+import { declaredSources } from '../../../engine/src/flow-sources.mjs';
+import { DEFAULT_HUB } from '../../../engine/lib/hub.mjs';
+import { hostedRun } from '../hosted.mjs';
+
+// How much of a tool's input schema is printed before the first model call; the rest is counted.
+const SCHEMA_SHOWN = 1000;
+// What a model provider's failure is called when tool sources are on: its
+// own words could quote text from a tool's server, so they are not shown.
+const PROVIDER_FAILURES = { provider_request: 'refused the request', provider_auth: 'refused the request', provider_timeout: 'did not answer in time', provider_network: 'could not be reached', provider_unavailable: 'was unavailable', provider_response: 'returned an answer that could not be used' };
+const providerSentence = (failure) => `The model provider ${PROVIDER_FAILURES[failure.code]} (${failure.code}${failure.httpStatus ? `, HTTP ${failure.httpStatus}` : ''}). Its own words are not shown while tool sources are on, as they could quote text from a tool's server.`;
+
+/** Reads typed lines one at a time, keeping answers typed ahead. */
+export function lineReader(io) {
+  let reader = null;
+  return {
+    async ask(prompt) {
+      if (!io.interactive) return null;
+      reader ||= createInterface({ input: io.stdin, terminal: false });
+      reader.iterator ||= reader[Symbol.asyncIterator]();
+      io.stderr.write(prompt);
+      const { value, done } = await reader.iterator.next();
+      return done ? null : value;
+    },
+    close() { reader?.close(); },
+  };
+}
+
+/** The provider a saved run continues with: the same settings, the key from this environment. */
+export function providerFor(settings, io) {
+  const number = (value, name) => {
+    if (value == null) return undefined;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) throw usage(`--${name} needs a positive whole number, not "${value}".`);
+    return parsed;
+  };
+  const timeout = number(settings.timeout, 'timeout');
+  return chooseProvider({ provider: settings.provider || undefined, model: settings.model, baseUrl: settings.baseUrl || undefined, apiKeyEnv: settings.apiKeyEnv || undefined,
+    effort: settings.effort || undefined, maxOutput: number(settings.maxOutput, 'max-output'), timeoutMs: timeout ? timeout * 1000 : undefined, env: io.env, fetchImpl: io.fetch });
+}
+
+/**
+ * Runs a prepared or restored run to its end or to a decision nobody answered,
+ * then reports it. Shared by `run` and `resume`. Returns the exit code.
+ */
+export async function drive(state, { provider, flags, io, reader, saveTo, toolSources = null }) {
+  const s = styles(io);
+  const say = (text = '') => io.stderr.write(`${toolSources ? cleanTerminalText(text) : text}\n`);
+  const { factory } = state;
+  const titleOf = (id) => factory.steps.find((step) => step.id === id)?.title || id;
+  // With tool sources, a model provider's failure is shown by its class only.
+  const errorText = () => (toolSources && PROVIDER_FAILURES[state.failure?.code] ? providerSentence(state.failure) : state.error);
+  const host = nodeHost({
+    provider,
+    fetchImpl: io.fetch,
+    emit(event) {
+      if (event.type === 'step_started') say(`\n${s.bold(event.title)}  ${s.dim(event.agent)}${event.redo ? s.dim('  (redoing)') : ''}`);
+      else if (event.type === 'tool') say(s.dim(`   ${titleOf(event.step)}: ${event.tool === 'web_search' ? `searching ${event.target}` : event.tool === 'web_fetch' ? `reading ${event.target}` : `calling ${event.tool}`}`));
+      else if (event.type === 'step_done') say(s.dim(`   done, ${event.chars} characters`));
+      else if (event.type === 'check') say(`   ${event.pass ? s.green('passed') : event.status === 'sent_back' ? s.yellow('sent back') : s.red(event.status === 'unreviewed' ? 'unreviewed' : 'flagged')}  ${s.dim(event.note)}${event.pass ? '' : event.issues.map((issue) => `\n     - ${issue}`).join('')}`);
+      else if (event.type === 'run_failed') say(`\n${s.red('Stopped')}: ${errorText()}`);
+    },
+  });
+  // A check can use a different model from the work it checks.
+  const cli = state.cli || {};
+  if (cli.checkModel) host.checkProvider = providerFor({ ...cli, model: cli.checkModel, effort: cli.checkEffort || cli.effort }, io);
+  if (toolSources) host.toolSources = toolSources;
+
+  await continueRun(state, host, async (approval, text, problem) => {
+    const seen = await engine.sha256(text);
+    if (problem === 'no_revisions') say(s.dim('This step has been sent back as often as the factory allows: approve it or reject it.'));
+    else say(`\n${s.bold(approval.title)}  ${s.yellow('needs your decision')}\n\n${text}\n\n${s.dim(approval.ask)}`);
+    if (flags.yes) { say(s.dim('Approved by --yes.')); return { action: 'approve', seen, approvalId: approval.id }; }
+    if (!io.interactive) return null;
+    let answer = '';
+    // An empty line is not a decision. Closing the input leaves the run waiting.
+    while (!answer) {
+      const line = await reader.ask(`\nType ${s.bold('approve')} to continue, ${s.bold('reject')} to stop the run, or what to change:\n> `);
+      if (line === null) return null;
+      answer = line.trim();
+    }
+    if (/^(approve|a|yes|y)$/i.test(answer)) return { action: 'approve', seen, approvalId: approval.id };
+    if (/^(reject|stop|no|n)$/i.test(answer)) return { action: 'reject', seen, approvalId: approval.id };
+    return { action: 'revise', note: answer, seen, approvalId: approval.id };
+  });
+
+  if (state.status === 'waiting') {
+    const decision = await pendingDecision(state);
+    let saved = null;
+    if (saveTo) {
+      await mkdir(dirname(saveTo), { recursive: true });
+      await writeFile(saveTo, `${JSON.stringify(state)}\n`);
+      saved = relative(io.cwd, saveTo) || saveTo;
+    }
+    if (flags.json) json(io, { status: 'waiting', step: decision.step, title: decision.title, ask: decision.ask, text: decision.text, seen_sha256: decision.seen_sha256, state: saved });
+    if (saved) {
+      if (!flags.json) say(`\n${s.bold(decision.title)}  ${s.yellow('needs a decision')}\n\n${decision.text}\n\n${s.dim(decision.ask)}`);
+      say(`\nWaiting at "${decision.title}". Nothing was approved. The run is saved in ${saved}.\nShow the person the text above, then continue with their decision:\n  factoryhub resume ${saved} --decision approve --seen ${decision.seen_sha256}\n  factoryhub resume ${saved} --decision revise --note "what to change" --seen ${decision.seen_sha256}\n  factoryhub resume ${saved} --decision reject --seen ${decision.seen_sha256}`);
+    } else if (state.experimental?.length) say(`\nWaiting at "${decision.title}": nobody answered, so nothing was approved and no result was written.\nA run with experimental tool sources cannot be saved and resumed yet: run it at a terminal to decide, or pass --yes to approve every decision.`);
+    else say(`\nWaiting at "${decision.title}": nobody answered, so nothing was approved and no result was written.\nRun it at a terminal to decide, pass --save <file> to continue later with "factoryhub resume", or pass --yes to approve every decision.`);
+    return 3;
+  }
+  if (state.status === 'stopped') {
+    if (flags.json) json(io, { status: 'stopped', step: state.stopped.step });
+    say(`\nStopped at "${state.stopped.title}" by your decision. No result was made.`);
+    return 1;
+  }
+  if (state.status !== 'done') {
+    // A run with tool sources says which calls ran before it stopped: the
+    // tool, whether it completed, the class of a failure and the time. No
+    // text from a server.
+    const calls = state.experimental?.length || factory.steps.some((step) => step.sources?.length)
+      ? state.records.flatMap((record) => record.tools.filter((tool) => tool.source).map((tool) => ({ step: record.id, tool: tool.tool, ok: tool.ok === true, error: tool.error ?? null, ms: Number.isFinite(tool.ms) ? tool.ms : null })))
+      : null;
+    if (flags.json) json(io, { status: state.status, error: errorText(), failure: state.failure, ...(calls ? { tool_calls: calls } : {}) });
+    else if (calls?.length) say(`\nTool calls before the run stopped:\n${calls.map((call) => `  ${titleOf(call.step)}: ${call.tool} ${call.ok ? 'ok' : `failed (${call.error})`}${call.ms === null ? '' : `, ${call.ms} ms`}`).join('\n')}`);
+    return 1;
+  }
+  const stamp = new Date(state.finished).toISOString().slice(0, 16).replace(/[-:T]/g, '');
+  const file = resolve(io.cwd, flags.out || `${factory.name}-${stamp}.md`);
+  const receiptFile = `${file.replace(/\.md$/, '')}.receipt.json`;
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, state.deliverable);
+  await writeFile(receiptFile, `${JSON.stringify(state.receipt, null, 2)}\n`);
+  const review = state.receipt.deliverable_review.status;
+  if (flags.json) json(io, { status: 'done', deliverable: relative(io.cwd, file), receipt: relative(io.cwd, receiptFile), review, flags: state.receipt.flags, usage: { calls: state.usage.llmCalls, input: state.usage.input, output: state.usage.output } });
+  else out(io, state.deliverable);
+  say(s.dim(`\nSaved ${relative(io.cwd, file)} and its receipt. Final check: ${review}. ${state.usage.llmCalls} model calls, ${state.usage.input + state.usage.output} tokens.`));
+  if (state.receipt.flags.length) say(s.dim(`Note: ${state.receipt.flags.join('; ')}`));
+  return 0;
+}
+
+export default {
+  name: 'run',
+  usage: `Usage: factoryhub run <factory> [--input name=value ...] [options]
+       factoryhub run <id> --hosted [--input name=value ...] [--yes] [--out file]
+
+Runs the factory's steps in order on this machine. Steps that do not depend
+on each other run at the same time. At every approval step the run stops,
+shows you the text, and asks: approve, reject, or say what to change.
+
+The model is yours. The first of these that is set decides:
+  ANTHROPIC_API_KEY     Anthropic (default model claude-sonnet-5-5)
+  OPENAI_API_KEY        OpenAI (default model gpt-5)
+  OPENROUTER_API_KEY    OpenRouter (default model openrouter/auto)
+or a server on your machine:
+  --provider ollama --model <name>            Ollama at http://localhost:11434/v1
+  --base-url <url> --model <name>             any OpenAI-compatible server
+
+Web search needs an Anthropic model; with other models the agents read the
+pages they are given. Agents read public web pages only.
+
+When it finishes, the deliverable is printed and saved with a receipt of
+every step. Inputs are asked for when missing and you are at a terminal.
+
+With nobody at the terminal (a script, or an agent's shell) a decision is
+never taken for you: the run stops there. With --save <file> it is saved, and
+"factoryhub resume" continues it with the person's decision.
+
+With --hosted, factoryhub runs the factory with that id on its own model,
+on your account's daily allowance, and this command follows it. It needs a
+login with runs:start and runs:read ("factoryhub login"). Where the run
+waits for you, you decide here only with a token that holds the opt-in
+runs:decide scope and the whole text fits; otherwise decide on the run page,
+then read the result with "factoryhub runs <run-id>". The result is saved
+with its signed receipt, checked here: on factory.mindburn.org against the
+production keys pinned in this version of factoryhub, elsewhere against the
+keys that hub publishes; the receipt's issuer must be that hub. Options
+for a run on this machine, the experimental tool sources included, are
+refused with --hosted.
+
+Exit codes: 0 done, 1 failed or stopped by your decision, 2 usage,
+3 waiting for a decision (nothing was approved).
+
+Options:
+  --input, -i    name=value; name=@file reads the value from a file (repeatable)
+  --provider     anthropic, openai, openrouter, ollama or openai-compatible
+  --model        the model name (or set FACTORYHUB_MODEL)
+  --base-url     an OpenAI-compatible server address
+  --api-key-env  the environment variable holding the key for --base-url
+  --effort       anthropic only: low, medium, high, xhigh or max
+  --max-output   anthropic only: tokens each call may spend on thinking and
+                 its answer (default 32000)
+  --timeout      seconds one model call may take (default 300)
+  --check-model  the model that runs every check step (default: --model), on
+                 the same provider
+  --check-effort anthropic only: the effort for check steps (default: --effort)
+  --save         where to save the run when it waits for a decision
+  --yes, -y      approve every decision without asking; the receipt's runner
+                 mode then reads "cli --yes"
+  --out          where to save the deliverable (default: <name>-<time>.md)
+  --json         print the outcome as JSON instead of the deliverable
+  --hosted       run on factoryhub instead of this machine; <factory> is an id
+  --hub          the factoryhub address for --hosted (default:
+                 FACTORYHUB_BASE_URL or ${DEFAULT_HUB})
+
+Experimental tool sources. Off unless --experimental-tools is given; they
+will change with the RFC on tool sources (docs/experimental-tool-sources.md).
+A step that names a tool a source offers gets it. Only allowed tools that
+only read can run, and the receipt is marked experimental.
+  --experimental-tools  turn on the options below
+  --mcp          name=url: a remote MCP server over Streamable HTTP
+                 (repeatable)
+  --mcp-token-env name=VAR: send the value of VAR, at least 16
+                 characters, to that server as a bearer token
+  --allow-tool   name:tool[,tool]: a tool steps may use (repeatable); it runs
+                 only if its server marks it read-only
+  --read-only    name:tool[,tool]: allow a tool and declare that it only reads
+  --nango        integration[:tool,tool]: a short Nango agent session for
+                 those tools, with NANGO_API_KEY (repeatable). When the
+                 integration is not connected, prints the link to connect it
+                 and stops with exit code 1
+  --nango-user   the Nango end user whose connection is used (default
+                 local-dev-user)
+
+A flow may declare the sources it needs (requires: [tool-sources] and a
+sources block, the form RFC 0017 proposes). The run shows what it asks for
+and connects to a source only once you grant it: at a terminal you are asked
+source by source; otherwise grant each one with a flag. --yes never grants.
+  --grant        source: use the address the factory declares (repeatable)
+  --bind         source=nango:integration: serve it from a Nango agent
+                 session limited to the declared tools; or source=url: use
+                 another address (repeatable)
+  --target       source=value: the one target the run is limited to, for a
+                 source that declares one (repeatable)
+  --mcp-token-env and --read-only take a declared source's name too`,
+  options: { boolean: ['yes', 'json', 'hosted', 'experimental-tools'], string: ['provider', 'model', 'base-url', 'api-key-env', 'effort', 'max-output', 'timeout', 'check-model', 'check-effort', 'out', 'save', 'nango-user', 'hub'], repeat: ['input', 'mcp', 'mcp-token-env', 'allow-tool', 'read-only', 'nango', 'grant', 'bind', 'target'], alias: { i: 'input', y: 'yes' } },
+  async run({ positional, flags }, io) {
+    const [target] = positional;
+    if (!target) throw usage('Name the factory to run.');
+    if (flags.hosted) {
+      const reader = lineReader(io);
+      try { return await hostedRun(target, flags, io, reader); } finally { reader.close(); }
+    }
+    if (flags.hub) throw usage('--hub names the factoryhub address for --hosted runs.');
+    const s = styles(io);
+    const read = await readFactory(target, { cwd: io.cwd, fetchImpl: io.fetch });
+    // Experimental and opt-in: a flow may declare the sources it needs
+    // (requires: [tool-sources], RFC 0017); otherwise flags may name them.
+    const declarations = flags['experimental-tools'] ? declaredSources(canonicalFiles(read.files)) : { declared: false };
+    const features = declarations.declared ? ['tool-sources'] : [];
+    const legacyPlan = declarations.declared ? null : toolSourcePlan(flags, io.env);
+    const parsed = engine.parseBundle(canonicalFiles(read.files), features.length ? { features } : undefined);
+    if (!parsed.ok) throw new Error(`This is not a valid factory:\n${parsed.errors.map((error) => `  - ${flags['experimental-tools'] ? displayLine(error, 1000) : error}`).join('\n')}`);
+    if (declarations.declared && declarations.problems.length) throw new Error(`The sources this factory declares cannot be used:\n${declarations.problems.map((problem) => `  - ${problem}`).join('\n')}`);
+    const plan = declarations.declared ? declaredPlan(declarations, flags, io.env) : legacyPlan;
+    if (plan && flags.save) throw usage('--save does not work with --experimental-tools yet: a run that uses tool sources cannot be resumed.');
+    if (declarations.declared) for (const [capability, steps] of Object.entries(declarations.uses)) {
+      const [source, tool] = capability.split('/');
+      const effect = declarations.sources[source].tools[tool].effect;
+      if (effect !== 'read') {
+        const step = parsed.factory.steps.find((item) => item.id === steps[0]);
+        throw new Error(`The step "${displayLine(step?.title || steps[0], 100)}" needs \`${capability}\`, which the flow declares as ${effect}. ${WRITE_REFUSED}`);
+      }
+    }
+    // With tool sources, the tools a step names are checked by name before any session opens.
+    const runnable = plan ? admitFactory(parsed.factory, plannedCatalog(plan.sources), { checkEffects: false, exact: declarations.declared }).factory : parsed.factory;
+    if (!runnable.runnable) throw new Error(runnable.blockers.map((blocker) => plan ? displayLine(blocker, 1000) : blocker).join('\n') || 'This factory has no flow.yaml, so there are no steps to run.');
+    const { factory } = parsed;
+    const settings = { provider: flags.provider || null, model: flags.model || null, baseUrl: flags['base-url'] || null, apiKeyEnv: flags['api-key-env'] || null,
+      effort: flags.effort || null, maxOutput: flags['max-output'] || null, timeout: flags.timeout || null,
+      checkModel: flags['check-model'] || null, checkEffort: flags['check-effort'] || null };
+    const provider = providerFor(settings, io);
+    settings.model = provider.model;
+
+    const inputs = {};
+    for (const pair of flags.input) {
+      const at = pair.indexOf('=');
+      if (at < 1) throw usage(`--input needs name=value, not "${pair}".`);
+      const key = pair.slice(0, at);
+      const value = pair.slice(at + 1);
+      inputs[key] = value.startsWith('@') ? await readFile(resolve(io.cwd, value.slice(1)), 'utf8') : value;
+    }
+
+    const line = plan ? displayLine : (value) => value;
+    const say = (text = '') => io.stderr.write(`${plan ? cleanTerminalText(text) : text}\n`);
+    const reader = lineReader(io);
+    let stopListening = null;
+    let opened;
+    try {
+      if (declarations.declared) {
+        // The factory says what it needs; the person grants it, source by
+        // source, before anything is connected. --yes never grants.
+        say(`\n${consentText({ title: factory.title, version: factory.version, hash: await engine.bundleHash(factory.files), plan, provider: `${provider.name}, ${provider.model}` })}`);
+        for (const source of plan.sources) {
+          if (!source.binding && io.interactive && source.url) {
+            const answer = await reader.ask(`\nGrant the source "${source.name}" for this run? It will be reached at:\n  ${new URL(source.url).href}\nType yes to grant: `);
+            if (answer !== null && /^(y|yes)$/i.test(answer.trim())) source.binding = { kind: 'mcp', url: source.url, granted: 'declared' };
+          }
+          if (!source.binding) throw usage(`The factory asks for the source "${source.name}", and it was not granted, so nothing was connected or run. Grant it with --grant ${source.name}, or serve it from another place with --bind ${source.name}=nango:<integration> or --bind ${source.name}=<url>.`);
+          if (source.target && source.targetValue === undefined && io.interactive) {
+            const answer = await reader.ask(`\n${line(source.target.label, 40)} for "${source.name}"${source.target.help ? ` (${line(source.target.help, 200)})` : ''}: `);
+            if (answer !== null && answer.trim() && answer.length <= 500 && !/[\p{Cc}\p{Cf}]/u.test(answer)) source.targetValue = answer.trim();
+          }
+          if (source.target && source.targetValue === undefined) throw usage(`The source "${source.name}" is limited to one ${line(source.target.label, 40)}, and none was given, so nothing was connected or run. Give it with --target ${source.name}=<value>.`);
+        }
+        // Every grant and target is known before even a DNS lookup is made.
+        for (const source of plan.sources) {
+          if (source.binding.granted === 'declared') await checkDeclaredAddress(source, io.lookup ? { lookupImpl: io.lookup } : {});
+          Object.assign(source, { kind: source.binding.kind, url: source.binding.url, integration: source.binding.integration, granted: source.binding.granted });
+        }
+      }
+      // Ctrl+C ends what is open, from the moment the first source starts to open.
+      const open = plan ? openThings() : null;
+      stopListening = open ? io.onInterrupt?.(() => open.close()) || null : null;
+      opened = plan ? await openToolSources(plan, { env: io.env, fetchImpl: io.fetch, open }) : null;
+      if (opened?.needsConnection) {
+        const link = opened.needsConnection;
+        if (flags.json) json(io, { status: 'needs_connection', integration: link.integration, end_user: link.end_user_id, connect_url: link.connect_url, expires_at: link.expires_at });
+        say(`\n${link.integration} is not connected in Nango for "${link.end_user_id}", so nothing was run.\nOpen this link to connect it, then run the same command again:\n  ${link.connect_url}${link.expires_at ? `\n${s.dim(`The link works until ${link.expires_at}.`)}` : ''}`);
+        return 1;
+      }
+      say(`\n${s.bold(line(factory.title, 120))}  ${s.dim(`v${line(factory.version, 40)}, ${provider.name}, ${provider.model}`)}`);
+      say(line(factory.description, 2000));
+      if (opened) {
+        // Now the effects are known: a tool that may change data is refused before any model call.
+        const admitted = opened.sources.admit(parsed.factory, { exact: declarations.declared });
+        if (!admitted.factory.runnable) throw new Error(admitted.factory.blockers.map((blocker) => displayLine(blocker, 1000)).join('\n'));
+        say(s.dim(`Experimental tool sources: ${opened.sources.summary().map((source) => `${source.name} (${source.tools.map((tool) => `${tool.id.slice(source.name.length + 1)}: ${tool.effect}`).join(', ')})`).join('; ')}. The receipt says so.`));
+        // The person sees what the model will get of each definition, before any model does.
+        say(`\nTool definitions from the servers, pinned for this run, as the model gets them. Their text is the servers' own, not instructions:`);
+        for (const tool of opened.sources.describe()) {
+          const schema = JSON.stringify(tool.input_schema);
+          const cut = schema.length > SCHEMA_SHOWN ? ` (and ${schema.length - SCHEMA_SHOWN} more characters not shown here)` : '';
+          say(`  ${tool.id}  ${tool.effect} (${tool.effect_from})  sha256 ${tool.digest.slice(0, 12)}\n    ${tool.description ? tool.description.replace(/\n/g, '\n    ') : '(no description)'}\n    input schema: ${schema.slice(0, SCHEMA_SHOWN)}${cut}`);
+        }
+      }
+      for (const input of factory.inputs) {
+        if (inputs[input.key] !== undefined || !io.interactive) continue;
+        const answer = await reader.ask(`\n${s.bold(line(input.label, 120))}${input.required ? '' : s.dim(' (optional, Enter to skip)')}  ${s.dim(`${input.type}${input.type === 'longtext' ? ', or @file' : ''}`)}\n${s.dim(line(input.help, 500))}\n> `);
+        if (answer === null) break;
+        inputs[input.key] = answer.startsWith('@') ? await readFile(resolve(io.cwd, answer.slice(1).trim()), 'utf8') : answer;
+      }
+      // An unattended approval is recorded in the receipt's runner mode.
+      const prepared = prepareRun({ files: read.files, inputs, runner: { mode: flags.yes ? 'cli --yes' : 'cli', provider: provider.name, model: provider.model }, toolSources: opened?.sources || null, features });
+      if (!prepared.ok) throw usage(prepared.problems.join('\n'));
+      prepared.state.cli = settings;
+      return await drive(prepared.state, { provider, flags, io, reader, saveTo: flags.save ? resolve(io.cwd, flags.save) : null, toolSources: opened?.sources || null });
+    } finally {
+      reader.close();
+      stopListening?.();
+      await opened?.close?.();
+    }
+  },
+};