factoryhub 0.1.0 → 0.1.1

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

@@ -0,0 +1,62 @@
+import { out, json, styles, usage, connect, BASE_URL_HELP } from '../util.mjs';
+
+/** The reasons a refused submission carries, as lines for a person. */
+export function refusalLines(details) {
+  if (!details) return [];
+  const lines = [];
+  for (const blocker of details.blockers || []) lines.push(`  - ${blocker}`);
+  const tests = details.tests;
+  if (tests && typeof tests === 'object') {
+    lines.push(`  - Declared examples: ${tests.status || 'not run'}${Number.isFinite(tests.passed) && Number.isFinite(tests.total) ? ` (${tests.passed} of ${tests.total} passed)` : ''}`);
+    for (const failure of (tests.failures || tests.cases || []).filter((item) => item && item.status && item.status !== 'passed').slice(0, 5)) lines.push(`      ${failure.id || failure.name || 'case'}: ${failure.status}`);
+  }
+  const scan = details.scan;
+  if (scan && typeof scan === 'object') {
+    lines.push(`  - Archive check: ${scan.status || 'not run'}${scan.summary ? `. ${scan.summary}` : ''}`);
+    for (const concern of (scan.concerns || scan.findings || []).slice(0, 5)) lines.push(`      ${typeof concern === 'string' ? concern : concern.summary || concern.title || JSON.stringify(concern)}`);
+  }
+  return lines;
+}
+
+export default {
+  name: 'publish',
+  usage: `Usage: factoryhub publish <id> [--note text] [--base-url url] [--json]
+
+Publishes a factory you pushed. factoryhub runs the checks the site runs
+first (for example, that it runs), and refuses with the reasons when one
+fails. Publishing again changes nothing.
+
+Needs a login with the opt-in factories:publish scope:
+  factoryhub login --scopes factories:read,factories:write,factories:publish
+
+Options:
+  --note      a note recorded with this publication
+  --base-url  ${BASE_URL_HELP}
+  --json      print the hub's answer as JSON`,
+  options: { boolean: ['json'], string: ['note', 'base-url'] },
+  async run({ positional, flags }, io) {
+    const [id, ...rest] = positional;
+    if (!id || rest.length) throw usage('Name the factory to publish: factoryhub publish <id>   ("factoryhub push" prints the id.)');
+    const { hub } = await connect(flags, io, { needToken: true });
+    let answer;
+    try {
+      answer = await hub.publish(id, { note: flags.note || '' });
+    } catch (error) {
+      const lines = refusalLines(error.details);
+      if (lines.length || error.status === 409 || error.status === 422) error.message = [`Not published: ${error.message}`, ...lines].join('\n');
+      throw error;
+    }
+    if (flags.json) { json(io, answer); return 0; }
+    const s = styles(io);
+    // The hub says what state the factory is in; nothing is assumed here.
+    const factory = answer.factory || {};
+    const url = factory.url || hub.sourceUrl(factory.id || id);
+    if (factory.visibility === 'public') {
+      out(io, `${answer.already ? s.dim('Already published:') : s.green('Published:')} ${s.bold(factory.id || id)} is live at ${url}`);
+    } else {
+      out(io, `${s.bold(factory.id || id)}: ${factory.visibility || 'unknown state'}. ${answer.message || ''}`.trim());
+    }
+    if (factory.safety) out(io, s.dim(`Safety check: ${typeof factory.safety === 'string' ? factory.safety : factory.safety.status || 'unknown'}`));
+    return 0;
+  },
+};

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

@@ -14,7 +14,6 @@ const REASONS = {
 
 export default {
   name: 'resume',
-  summary: 'Continue a saved run with the person\'s decision.',
   usage: `Usage: factoryhub resume <run.json> --decision approve|revise|reject --seen <sha256> [--note text]
        factoryhub resume <run.json> --show
 

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

@@ -4,6 +4,18 @@ 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) {
@@ -23,29 +35,43 @@ export function lineReader(io) {
 
 /** The provider a saved run continues with: the same settings, the key from this environment. */
 export function providerFor(settings, io) {
-  return chooseProvider({ provider: settings.provider || undefined, model: settings.model, baseUrl: settings.baseUrl || undefined, apiKeyEnv: settings.apiKeyEnv || undefined, env: io.env, fetchImpl: io.fetch });
+  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 }) {
+export async function drive(state, { provider, flags, io, reader, saveTo, toolSources = null }) {
   const s = styles(io);
-  const say = (text = '') => io.stderr.write(`${text}\n`);
+  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' : 'reading'} ${event.target}`));
+      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')}: ${event.error}`);
+      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);
@@ -77,7 +103,8 @@ export async function drive(state, { provider, flags, io, reader, saveTo }) {
     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 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.`);
+    } 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') {
@@ -86,7 +113,14 @@ export async function drive(state, { provider, flags, io, reader, saveTo }) {
     return 1;
   }
   if (state.status !== 'done') {
-    if (flags.json) json(io, { status: state.status, error: state.error, failure: state.failure });
+    // 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, '');
@@ -105,8 +139,8 @@ export async function drive(state, { provider, flags, io, reader, saveTo }) {
 
 export default {
   name: 'run',
-  summary: 'Run a factory with your own model key or a local model. Stops at every decision.',
   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,
@@ -130,6 +164,18 @@ 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).
 
@@ -139,22 +185,88 @@ Options:
   --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`,
-  options: { boolean: ['yes', 'json'], string: ['provider', 'model', 'base-url', 'api-key-env', 'out', 'save'], repeat: ['input'], alias: { i: 'input', y: 'yes' } },
+  --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 });
-    const parsed = engine.parseBundle(canonicalFiles(read.files));
-    if (!parsed.ok) throw new Error(`This is not a valid factory:\n${parsed.errors.map((error) => `  - ${error}`).join('\n')}`);
-    if (!parsed.factory.runnable) throw new Error(parsed.factory.blockers.join('\n') || 'This factory has no flow.yaml, so there are no steps to run.');
+    // 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 };
+    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;
 
@@ -167,24 +279,74 @@ Options:
       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);
-    const say = (text = '') => io.stderr.write(`${text}\n`);
+    let stopListening = null;
+    let opened;
     try {
-      say(`\n${s.bold(factory.title)}  ${s.dim(`v${factory.version}, ${provider.name}, ${provider.model}`)}`);
-      say(factory.description);
+      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(input.label)}${input.required ? '' : s.dim(' (optional, Enter to skip)')}  ${s.dim(`${input.type}${input.type === 'longtext' ? ', or @file' : ''}`)}\n${s.dim(input.help)}\n> `);
+        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 } });
+      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 });
+      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?.();
     }
   },
 };

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

@@ -0,0 +1,52 @@
+import { out, json, table, styles, usage, connect, BASE_URL_HELP } from '../util.mjs';
+import { listRuns, finish } from '../hosted.mjs';
+import { FINISHED } from '../../../engine/lib/hosted.mjs';
+
+export default {
+  name: 'runs',
+  usage: `Usage: factoryhub runs [--limit n] [--base-url url] [--json]
+       factoryhub runs <run-id> [--out file] [--base-url url] [--json]
+
+With no run id, lists your recent hosted runs, newest first.
+
+With a run id, shows where that run is. A finished run's result is printed
+and saved with its signed receipt, which is 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. A run waiting for you names the step and the page
+where you decide.
+
+Needs a login with the runs:read scope.
+
+Exit codes with a run id: 0 done and verified, 1 failed, stopped or not
+verified, 3 waiting for a decision.
+
+Options:
+  --limit     how many runs to list, 1 to 30 (default 15)
+  --out       where to save the result (default: <factory>-<time>.md)
+  --base-url  ${BASE_URL_HELP}
+  --json      print the answer as JSON`,
+  options: { boolean: ['json'], string: ['limit', 'out', 'base-url'] },
+  async run({ positional, flags }, io) {
+    const [id, ...rest] = positional;
+    if (rest.length) throw usage('Show one run at a time: factoryhub runs <run-id>');
+    if (!id) {
+      if (flags.out) throw usage('--out saves one run\'s result: factoryhub runs <run-id> --out file.md');
+      const runs = await listRuns(flags, io);
+      if (flags.json) { json(io, runs); return 0; }
+      if (!runs.length) { out(io, 'No hosted runs yet. Start one with: factoryhub run <id> --hosted'); return 0; }
+      out(io, table([['ID', 'STATUS', 'STARTED', 'FACTORY'], ...runs.map((run) => [run.id, run.status, String(run.started || '').slice(0, 16).replace('T', ' '), run.title || run.factoryId])]));
+      out(io, styles(io).dim('\nShow one, and save its result: factoryhub runs <run-id>'));
+      return 0;
+    }
+    if (flags.limit) throw usage('--limit applies to the list of runs, not to one run.');
+    const { hub } = await connect(flags, io, { needToken: true });
+    const run = await hub.getRun(id);
+    if (!run.waiting && !FINISHED.has(run.status)) {
+      if (flags.json) json(io, { status: run.status, run: run.id, url: run.url });
+      else out(io, `${run.title || run.factoryId}: ${run.status}. Follow it on ${run.url}`);
+      return 0;
+    }
+    return finish(hub, run, { io, flags, name: run.factoryId || 'run' });
+  },
+};

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

@@ -7,7 +7,6 @@ and it is sent as the x-hub-access-key header.`;
 
 export default {
   name: 'search',
-  summary: 'Search the published factories on factoryhub (needs FACTORYHUB_ACCESS_KEY in preview).',
   usage: `Usage: factoryhub search [words ...] [--base-url url] [--json]
 
 Lists the published factories whose id, title, description or tags contain

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

@@ -4,7 +4,6 @@ import { engine, readFactory, out, json, plural, styles, usage, canonicalFiles }
 
 export default {
   name: 'validate',
-  summary: 'Check factories the way the engine reads them. No key, no model.',
   usage: `Usage: factoryhub validate [factory ...] [--json]
 
 Reads each factory with the engine's parser and lists every problem, every
@@ -20,8 +19,7 @@ Options:
   async run({ positional, flags }, io) {
     const targets = positional.length ? positional : existsSync(join(io.cwd, 'factory.yaml')) ? ['.'] : [];
     if (!targets.length) throw usage('Name a factory to validate, or run this inside a factory folder.');
-    const results = [];
-    for (const target of targets) results.push(await check(target, io));
+    const results = await Promise.all(targets.map((target) => check(target, io)));
     if (flags.json) json(io, results);
     else results.forEach((result, index) => { if (index) out(io); print(result, io); });
     return results.every((result) => result.runnable) ? 0 : 1;