factoryhub 0.1.0 → 0.1.1

package/packages/engine/src/factory-engine.mjs

@@ -267,7 +267,10 @@ export function dependentsOf(factory, id) {
   return factory.steps.filter((step) => step.id !== id && ancestorsOf(factory, step.id).includes(id)).map((step) => step.id);
 }
 
-export function parseBundle(input) {
+// `features`: execution features a caller opts in to beyond REQUIRED_FEATURES
+// (the experimental tool sources pass `tool-sources`). Without it, nothing
+// changes: a flow that requires an unknown feature is refused.
+export function parseBundle(input, { features = [] } = {}) {
   const files = normalizeFiles(input);
   const errors = [];
   const warnings = [];
@@ -322,7 +325,7 @@ export function parseBundle(input) {
   }
 
   if (flow && typeof flow === 'object') {
-    if (flow.requires !== undefined && (!Array.isArray(flow.requires) || flow.requires.some((feature) => !REQUIRED_FEATURES.includes(feature)))) errors.push('This flow requires unsupported execution features. Use a compatible runner.');
+    if (flow.requires !== undefined && (!Array.isArray(flow.requires) || flow.requires.some((feature) => !REQUIRED_FEATURES.includes(feature) && !features.includes(feature)))) errors.push('This flow requires unsupported execution features. Use a compatible runner.');
     factory.title = String(flow.title || '');
     factory.author = String(flow.author || '');
     factory.version = String(flow.version ?? '1.0.0');
@@ -692,32 +695,229 @@ function decodeEntities(text) {
     .replace(/&([a-z]+);/gi, (whole, name) => ENTITIES[name.toLowerCase()] ?? whole);
 }
 
+// Pages are read only this far: past it the text is cut, and the reader is told.
+const PAGE_CHARS = 2000000;
+
+// Sorted start positions of every match of a global pattern.
+const startsOf = (text, pattern) => Array.from(text.matchAll(pattern), (match) => match.index);
+
+// The index of the first number in a sorted list that is at least `at`.
+function indexFrom(list, at) {
+  let low = 0;
+  let high = list.length;
+  while (low < high) {
+    const middle = (low + high) >> 1;
+    if (list[middle] < at) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+}
+// The first number in a sorted list that is at least `at`, or -1.
+const firstFrom = (list, at) => list[indexFrom(list, at)] ?? -1;
+
+// Applies a pattern that ends at the next ">", such as /<li[^>]*>/gi, to the
+// text up to its last ">". No match can start after it, and leaving that part
+// out keeps the scan linear: on a page of "<li" with no ">" the plain replace
+// tries every "<li" to the end of the page.
+function beforeLastGt(text, pattern, replacement) {
+  const end = text.lastIndexOf('>') + 1;
+  return text.slice(0, end).replace(pattern, replacement) + text.slice(end);
+}
+const stripTags = (text) => beforeLastGt(text, /<[^>]+>/g, ' ');
+
+// The passes below find the same matches as the regular expressions in their
+// comments, in time linear in the page. Those expressions search to the end
+// of the page from every open tag that is never closed, and the link and meta
+// ones backtrack over every attribute as well: 25 KB of such tags took seconds.
+// An end tag is looked up in a sorted list of positions, and once an open tag
+// cannot match, no later one inside the same tag is tried.
+
+// The first match of /<title[^>]*>([\s\S]*?)<\/title>/i, or ''. Only the first
+// "<title" can match: a later one ends at the same or a later ">".
+function pageTitle(page) {
+  const open = page.search(/<title/i);
+  if (open < 0) return '';
+  const end = page.indexOf('>', open + 6);
+  if (end < 0) return '';
+  const close = /<\/title>/gi;
+  close.lastIndex = end + 1;
+  const found = close.exec(page);
+  return found ? page.slice(end + 1, found.index) : '';
+}
+
+// The first match of either expression, or '':
+//   /<meta[^>]+name=["']description["'][^>]*content=["']([^"']*)["']/i
+//   /<meta[^>]+content=["']([^"']*)["'][^>]*name=["']description["']/i
+// "[^>]+" is greedy, so the expressions take the last attribute that fits
+// before the tag's first ">"; a content value may itself contain ">".
+function pageDescription(page) {
+  const metas = startsOf(page, /<meta/gi);
+  if (!metas.length) return '';
+  const names = startsOf(page, /name=["']description["']/gi);
+  const contents = startsOf(page, /content=["']/gi);
+  const gts = startsOf(page, />/g);
+  const quotes = startsOf(page, /["']/g);
+  // Calls `each` on the listed positions in [from, to), last first, until it
+  // returns something other than null.
+  const lastFirst = (list, from, to, each) => {
+    for (let index = indexFrom(list, to) - 1; index >= 0 && list[index] >= from; index -= 1) {
+      const value = each(list[index]);
+      if (value !== null) return value;
+    }
+    return null;
+  };
+  // The first <meta that matches. One that does not match is followed by
+  // none that starts inside the same tag.
+  const firstMeta = (match) => {
+    let skip = -1;
+    for (const meta of metas) {
+      if (meta < skip) continue;
+      const gt = firstFrom(gts, meta + 5);
+      const value = match(meta, gt < 0 ? page.length : gt);
+      if (value !== null) return value;
+      if (gt < 0) return null;
+      skip = gt;
+    }
+    return null;
+  };
+  // name, then content: the last name with a content after it, then the last
+  // such content whose value a quote closes.
+  const nameFirst = firstMeta((meta, end) => lastFirst(names, meta + 6, end, (name) => lastFirst(contents, name + 18, end, (content) => {
+    const quote = firstFrom(quotes, content + 9);
+    return quote < 0 ? null : page.slice(content + 9, quote);
+  })));
+  if (nameFirst) return nameFirst;
+  // content, then name: the last content whose value is followed, before the
+  // next ">", by name="description".
+  return firstMeta((meta, end) => lastFirst(contents, meta + 6, end, (content) => {
+    const quote = firstFrom(quotes, content + 9);
+    if (quote < 0) return null;
+    const gt = firstFrom(gts, quote + 1);
+    const name = firstFrom(names, quote + 1);
+    return name >= 0 && (gt < 0 || name < gt) ? page.slice(content + 9, quote) : null;
+  })) || '';
+}
+
+// /<!--[\s\S]*?-->/g, replaced by a space.
+function dropComments(page) {
+  let out = '';
+  let at = 0;
+  for (;;) {
+    const open = page.indexOf('<!--', at);
+    if (open < 0) break;
+    const close = page.indexOf('-->', open + 4);
+    if (close < 0) break;
+    out += `${page.slice(at, open)} `;
+    at = close + 3;
+  }
+  return out + page.slice(at);
+}
+
+// /<(script|style|noscript|svg|template|iframe|canvas)\b[\s\S]*?<\/\1>/gi,
+// replaced by a space.
+function dropRawText(page) {
+  const closes = {};
+  for (const match of page.matchAll(/<\/(script|style|noscript|svg|template|iframe|canvas)>/gi)) (closes[match[1].toLowerCase()] ||= []).push(match.index);
+  const open = /<(script|style|noscript|svg|template|iframe|canvas)\b/gi;
+  let out = '';
+  let at = 0;
+  for (let match; (match = open.exec(page));) {
+    const name = match[1].toLowerCase();
+    const close = firstFrom(closes[name] || [], match.index + match[0].length);
+    if (close < 0) continue;
+    out += `${page.slice(at, match.index)} `;
+    at = close + name.length + 3;
+    open.lastIndex = at;
+  }
+  return out + page.slice(at);
+}
+
+// /<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi, written as a Markdown heading.
+function markHeadings(page) {
+  const closes = [[], [], [], [], [], [], []];
+  for (const match of page.matchAll(/<\/h([1-6])>/gi)) closes[match[1]].push(match.index);
+  const gts = startsOf(page, />/g);
+  const open = /<h([1-6])/gi;
+  let out = '';
+  let at = 0;
+  for (let match; (match = open.exec(page));) {
+    const end = firstFrom(gts, match.index + 3);
+    if (end < 0) break;
+    const level = Number(match[1]);
+    const close = firstFrom(closes[level], end + 1);
+    if (close < 0) continue;
+    out += `${page.slice(at, match.index)}\n\n${'#'.repeat(level)} ${stripTags(page.slice(end + 1, close))}\n\n`;
+    at = close + 5;
+    open.lastIndex = at;
+  }
+  return out + page.slice(at);
+}
+
+function linkText(href, inner, baseUrl) {
+  const label = stripTags(inner).replace(/\s+/g, ' ').trim();
+  if (!label) return ' ';
+  let target = href;
+  try { target = new URL(href, baseUrl).href; } catch { /* keep as written */ }
+  return /^https?:/.test(target) ? ` [${label}](${target}) ` : ` ${label} `;
+}
+
+// /<a\b[^>]*href=["']([^"'#][^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi, written as a
+// Markdown link. "[^>]*" is greedy, so the last fitting href before the tag's
+// first ">" is tried first; its value may contain ">" and so end the tag later.
+// Every other href ends at that first ">", so at most two are ever tried.
+function markLinks(page, baseUrl) {
+  const closes = startsOf(page, /<\/a>/gi);
+  const hrefs = startsOf(page, /href=/gi);
+  const gts = startsOf(page, />/g);
+  const quotes = startsOf(page, /["']/g);
+  const open = /<a\b/gi;
+  let out = '';
+  let at = 0;
+  for (let match; (match = open.exec(page));) {
+    const start = match.index;
+    const gt = firstFrom(gts, start + 2);
+    const end = gt < 0 ? page.length : gt;
+    let found = null;
+    for (let index = indexFrom(hrefs, end) - 1; index >= 0 && hrefs[index] >= start + 2; index -= 1) {
+      const href = hrefs[index];
+      if (!`"'`.includes(page[href + 5] || 'x') || `"'#`.includes(page[href + 6] ?? '"')) continue;
+      const quote = firstFrom(quotes, href + 7);
+      if (quote < 0) continue;
+      const tagEnd = firstFrom(gts, quote + 1);
+      if (tagEnd < 0) continue;
+      const close = firstFrom(closes, tagEnd + 1);
+      if (close >= 0) { found = { href: page.slice(href + 6, quote), tagEnd, close }; break; }
+      if (tagEnd === gt) break;
+    }
+    if (!found) {
+      if (gt < 0) break;
+      open.lastIndex = gt;
+      continue;
+    }
+    out += page.slice(at, start) + linkText(found.href, page.slice(found.tagEnd + 1, found.close), baseUrl);
+    at = found.close + 4;
+    open.lastIndex = at;
+  }
+  return out + page.slice(at);
+}
+
 // Turns a web page into the text a reader would see, with headings and links
 // kept, so a station can quote and cite it.
 export function htmlToText(html, baseUrl, limit = 14000) {
   let page = String(html || '');
-  const title = decodeEntities((page.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] || '').trim());
-  const description = decodeEntities(page.match(/<meta[^>]+name=["']description["'][^>]*content=["']([^"']*)["']/i)?.[1]
-    || page.match(/<meta[^>]+content=["']([^"']*)["'][^>]*name=["']description["']/i)?.[1] || '');
-  page = page
-    .replace(/<!--[\s\S]*?-->/g, ' ')
-    .replace(/<(script|style|noscript|svg|template|iframe|canvas)\b[\s\S]*?<\/\1>/gi, ' ')
-    .replace(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi, (_, level, inner) => `\n\n${'#'.repeat(Number(level))} ${inner.replace(/<[^>]+>/g, ' ')}\n\n`)
-    .replace(/<a\b[^>]*href=["']([^"'#][^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi, (_, href, inner) => {
-      const label = inner.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
-      if (!label) return ' ';
-      let target = href;
-      try { target = new URL(href, baseUrl).href; } catch { /* keep as written */ }
-      return /^https?:/.test(target) ? ` [${label}](${target}) ` : ` ${label} `;
-    })
-    .replace(/<li[^>]*>/gi, '\n- ')
-    .replace(/<(br|\/p|\/div|\/tr|\/section|\/article|\/header|\/footer|\/li|\/ul|\/ol|\/table)\b[^>]*>/gi, '\n')
-    .replace(/<\/t[dh]>/gi, ' | ')
-    .replace(/<[^>]+>/g, ' ');
-  page = decodeEntities(page).replace(/[ \t\f\v ]+/g, ' ').replace(/ ?\n ?/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
+  const cut = page.length > PAGE_CHARS;
+  if (cut) page = page.slice(0, PAGE_CHARS);
+  const title = decodeEntities(pageTitle(page).trim());
+  const description = decodeEntities(pageDescription(page));
+  page = markLinks(markHeadings(dropRawText(dropComments(page))), baseUrl);
+  page = beforeLastGt(page, /<li[^>]*>/gi, '\n- ');
+  page = beforeLastGt(page, /<(br|\/p|\/div|\/tr|\/section|\/article|\/header|\/footer|\/li|\/ul|\/ol|\/table)\b[^>]*>/gi, '\n');
+  page = stripTags(page.replace(/<\/t[dh]>/gi, ' | '));
+  page = decodeEntities(page).replace(/[ \t\f\v\u00a0]+/g, ' ').replace(/ ?\n ?/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
   const head = [title && `Title: ${title}`, description && `Description: ${decodeEntities(description)}`].filter(Boolean).join('\n');
   const text = `${head}\n\n${page}`.trim();
-  return text.length > limit ? `${text.slice(0, limit)}\n\n[Page cut here: ${text.length - limit} more characters not shown]` : text;
+  if (text.length > limit) return `${text.slice(0, limit)}\n\n[Page cut here: ${text.length - limit} more characters not shown]`;
+  return cut ? `${text}\n\n[Page cut here: only the first ${PAGE_CHARS.toLocaleString('en-US')} characters of the page were read]` : text;
 }
 
 export function normalizeUrl(value) {
@@ -813,16 +1013,24 @@ function providerUsage(payload, anthropic) {
 }
 
 // Anthropic Messages API. Messages stay in this block format inside the engine.
-export function anthropicProvider({ apiKey, model, workspaceId, fetchImpl = fetch, browser = false, baseUrl = 'https://api.anthropic.com', timeoutMs = MODEL_TIMEOUT_MS }) {
+export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
+// Current Claude models think before they answer, and thinking counts toward
+// max_tokens, so every call leaves this much room beyond the step's own budget.
+export const ANTHROPIC_MAX_OUTPUT = 32000;
+
+export function anthropicProvider({ apiKey, model, workspaceId, fetchImpl = fetch, browser = false, baseUrl = 'https://api.anthropic.com', timeoutMs = MODEL_TIMEOUT_MS, effort = null, maxOutput = ANTHROPIC_MAX_OUTPUT }) {
+  if (effort != null && !EFFORTS.includes(effort)) throw new Error(`Unknown effort "${effort}". Use one of: ${EFFORTS.join(', ')}.`);
   return {
     name: 'anthropic',
     billing: baseUrl.replace(/\/$/, '') === 'https://api.anthropic.com' ? 'anthropic-direct' : null,
     model,
+    effort,
     serverSearch: true,
     async call({ system, messages, tools = [], search = 0, forceTool, maxTokens = 4096 }) {
       const toolList = tools.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.input_schema }));
       if (search > 0) toolList.push({ type: 'web_search_20250305', name: 'web_search', max_uses: search });
-      const body = { model, max_tokens: maxTokens, system, messages };
+      const body = { model, max_tokens: Math.max(maxTokens, maxOutput || 0), system, messages };
+      if (effort) body.output_config = { effort };
       if (toolList.length) body.tools = toolList;
       if (forceTool) body.tool_choice = { type: 'tool', name: forceTool };
       const headers = { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' };
@@ -1369,6 +1577,16 @@ async function callModel(state, host, request, provider = host.provider) {
   return response;
 }
 
+// How many pages one model turn reads at the same time.
+const PAGES_AT_ONCE = 4;
+
+// Runs `work` on every item, at most `limit` at a time. `work` must not throw.
+async function eachLimited(items, limit, work) {
+  let next = 0;
+  const lane = async () => { while (next < items.length) await work(items[next++]); };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, lane));
+}
+
 async function doWork(state, step, host, record) {
   const feedback = state.steps[step.id].feedback;
   const context = resolveContext(state, step);
@@ -1382,9 +1600,16 @@ async function doWork(state, step, host, record) {
   }
   const messages = [{ role: 'user', content: [{ type: 'text', text: parts.filter(Boolean).join('\n\n') }] }];
   const tools = step.tools.includes('web_fetch') ? [FETCH_TOOL] : [];
+  // Experimental tool sources (opt-in, tool-sources.mjs): only a run admitted
+  // with them has steps with `sources`, checked against their pinned digests.
+  if (step.sources?.length) {
+    if (!host.toolSources) throw failure('tools', `The step "${step.title}" needs tool sources that this runner was not given.`);
+    await host.toolSources.verify(step);
+    tools.push(...host.toolSources.toolsFor(step));
+  }
   const search = step.tools.includes('web_search') && host.provider.serverSearch ? host.limits.searchesPerStep : 0;
   if (step.tools.includes('web_search') && !host.provider.serverSearch) record.limitations.push('Web search was unavailable on this runner.');
-  const system = agentSystem(state, step, host);
+  const system = [agentSystem(state, step, host), step.sources?.length ? host.toolSources.instructions(step) : ''].filter(Boolean).join('\n\n');
   const maxTokens = step.kind === 'deliver' ? 8000 : 5000;
 
   let searched = 0;
@@ -1398,37 +1623,52 @@ async function doWork(state, step, host, record) {
       await host.emit({ type: 'tool', step: step.id, tool: 'web_search', target: query });
     }
     if (last && (response.stop === 'pause_turn' || response.toolCalls.length)) throw new Error('The model did not finish within this step’s turn limit.');
-    if (response.stop !== 'pause_turn' && !response.toolCalls.length) return finalText(response.content);
+    if (response.stop !== 'pause_turn' && !response.toolCalls.length) {
+      // A tool whose definition changed while the step ran stops it before its result is accepted.
+      if (step.sources?.length) await host.toolSources.verify(step);
+      return finalText(response.content);
+    }
     messages.push({ role: 'assistant', content: response.content });
     if (response.stop === 'pause_turn') continue;
-    const results = [];
+    // The pages a turn asks for are counted against the budget in the order
+    // asked, then read at the same time, at most four at once. Their results,
+    // tools and limitations are recorded in the order asked.
+    const asked = [];
     for (const call of response.toolCalls) {
-      let output;
-      if (call.name !== 'web_fetch') {
-        output = 'That tool does not exist in this factory.';
+      if (step.sources?.length && host.toolSources.offers(step, call.name)) {
+        // A tool source is called in its turn below: it writes its own record.
+        asked.push({ call, source: true });
+      } else if (call.name !== 'web_fetch') {
+        asked.push({ call, output: 'That tool does not exist in this factory.' });
       } else if (state.usage.fetches >= host.limits.fetches) {
-        output = 'The page budget for this run is used up. Work with what you have.';
-        record.limitations.push(output);
+        const output = 'The page budget for this run is used up. Work with what you have.';
+        asked.push({ call, output, limitation: output });
       } else {
         const url = normalizeUrl(call.input?.url);
         state.usage.fetches += 1;
         await host.emit({ type: 'tool', step: step.id, tool: 'web_fetch', target: url || String(call.input?.url || '') });
-        if (!url) {
-          output = 'That is not a public web address.';
-          record.limitations.push('A requested page address was invalid.');
-        } else {
-          try {
-            output = await host.fetchPage(url);
-            if (/\[Page cut here:/.test(output)) record.limitations.push(`Only part of ${url} was available to read.`);
-            record.tools.push({ tool: 'web_fetch', target: url, ok: true });
-          } catch (error) {
-            output = `The page could not be read: ${error.message}`;
-            record.limitations.push(`The page ${url} could not be read.`);
-            record.tools.push({ tool: 'web_fetch', target: url, ok: false });
-          }
-        }
+        asked.push(url ? { call, url } : { call, output: 'That is not a public web address.', limitation: 'A requested page address was invalid.' });
+      }
+    }
+    await eachLimited(asked.filter((item) => item.url), PAGES_AT_ONCE, async (item) => {
+      try {
+        item.output = await host.fetchPage(item.url);
+        item.ok = true;
+      } catch (error) {
+        item.output = `The page could not be read: ${error.message}`;
+        item.ok = false;
+      }
+    });
+    const results = [];
+    for (const item of asked) {
+      if (item.source) item.output = await host.toolSources.call(host, step, item.call, record);
+      if (item.limitation) record.limitations.push(item.limitation);
+      if (item.url) {
+        if (!item.ok) record.limitations.push(`The page ${item.url} could not be read.`);
+        else if (/\[Page cut here:/.test(item.output)) record.limitations.push(`Only part of ${item.url} was available to read.`);
+        record.tools.push({ tool: 'web_fetch', target: item.url, ok: item.ok });
       }
-      results.push({ type: 'tool_result', tool_use_id: call.id, content: output });
+      results.push({ type: 'tool_result', tool_use_id: item.call.id, content: item.output });
     }
     messages.push({ role: 'user', content: results });
   }
@@ -1478,13 +1718,14 @@ async function doCheck(state, step, host, record) {
     } catch { return null; }
   };
   const messages = [{ role: 'user', content: [{ type: 'text', text }] }];
-  const request = { system, messages, tools: [VERDICT_TOOL], forceTool: 'verdict', maxTokens: 1500 };
+  // A reviewer that must quote the result and its source side by side needs room for both.
+  const request = { system, messages, tools: [VERDICT_TOOL], forceTool: 'verdict', maxTokens: 4000 };
   record.review.context_sha256 = await sha256(canonical(request));
   const first = await callModel(state, host, request, reviewer);
   let verdict = read(first);
   if (!verdict) {
     // A reviewer that wrote prose instead of a verdict is asked once more.
-    const retryRequest = { system, messages: [...messages, { role: 'assistant', content: [{ type: 'text', text: finalText(first.content) || 'I have reviewed the result.' }] }, { role: 'user', content: [{ type: 'text', text: 'Now give your verdict as JSON only, with no other text: {"pass": true or false, "issues": ["one sentence per clear breach"], "note": "one sentence"}' }] }], maxTokens: 1000 };
+    const retryRequest = { system, messages: [...messages, { role: 'assistant', content: [{ type: 'text', text: finalText(first.content) || 'I have reviewed the result.' }] }, { role: 'user', content: [{ type: 'text', text: 'Now give your verdict as JSON only, with no other text: {"pass": true or false, "issues": ["one sentence per clear breach"], "note": "one sentence"}' }] }], maxTokens: 2500 };
     record.review.context_sha256 = await sha256(canonical(retryRequest));
     const again = await callModel(state, host, retryRequest, reviewer);
     verdict = read(again);
@@ -1542,33 +1783,45 @@ async function runStep(state, step, host) {
   return outcome;
 }
 
-// Moves the factory forward by one round: every step that is ready runs, in
-// parallel. `host` supplies: provider, fetchPage(url), emit(event), now(), limits.
-export async function advance(state, host) {
-  if (state.status !== 'running') return state;
+// The checks made before any step starts. Returns false when the run cannot
+// go on: it was not running, or it has just been failed.
+async function admit(state, host) {
+  if (state.status !== 'running') return false;
   // Re-read preserved source even for restored runs parsed by an older engine.
   // UI admission and a cached runnable flag are not execution boundaries.
-  const source = parseBundle(state.factory.files);
-  if (!source.ok) return fail(state, host, null, source.errors.join(' '), { code: 'invalid_factory' });
+  // A run admitted with experimental tool sources reads its flow as it was admitted.
+  const source = parseBundle(state.factory.files, state.experimental?.includes('tool-sources') ? { features: ['tool-sources'] } : undefined);
+  if (!source.ok) { await fail(state, host, null, source.errors.join(' '), { code: 'invalid_factory' }); return false; }
   if (!state.started) {
     state.started = host.now();
     await host.emit({ type: 'run_started', factory: state.factory.name, steps: state.factory.steps.length });
     const checked = checkInputs(state.factory, state.inputs);
-    if (!checked.ok) return fail(state, host, null, checked.problems.join(' '), { code: 'inputs' });
+    if (!checked.ok) { await fail(state, host, null, checked.problems.join(' '), { code: 'inputs' }); return false; }
     state.inputs = checked.inputs;
     // Checked again here, whoever started the run: a factory that asks for a
     // tool this runner lacks is not run at all, since without it the run
     // would be a different factory from the one its author wrote.
     const lacking = state.factory.steps.find((step) => step.missing?.length);
-    if (lacking) return fail(state, host, lacking.id, `The step "${lacking.title}" needs ${lacking.missing.join(' and ')}, which this runner does not have. Nothing was run.`, { code: 'tools' });
-  }
-  if (source.factory.unsupportedRequirements.length) return fail(state, host, null, source.factory.blockers.join(' '), { code: 'requirements' });
-  const { steps } = state.factory;
-  const ready = steps.filter((step) => state.steps[step.id].status === 'pending' && step.needs.every((need) => state.steps[need].status === 'done'));
-  if (!ready.length) {
-    if (steps.every((step) => state.steps[step.id].status === 'done')) return finish(state, host);
-    return fail(state, host, null, 'The flow cannot continue: a step is waiting on work that will never finish.', { code: 'flow' });
+    if (lacking) { await fail(state, host, lacking.id, `The step "${lacking.title}" needs ${lacking.missing.join(' and ')}, which this runner does not have. Nothing was run.`, { code: 'tools' }); return false; }
   }
+  if (source.factory.unsupportedRequirements.length) { await fail(state, host, null, source.factory.blockers.join(' '), { code: 'requirements' }); return false; }
+  return true;
+}
+
+const readySteps = (state) => state.factory.steps.filter((step) => state.steps[step.id].status === 'pending' && step.needs.every((need) => state.steps[need].status === 'done'));
+
+// With nothing ready the run is either finished or stuck.
+function finishOrStuck(state, host) {
+  if (state.factory.steps.every((step) => state.steps[step.id].status === 'done')) return finish(state, host);
+  return fail(state, host, null, 'The flow cannot continue: a step is waiting on work that will never finish.', { code: 'flow' });
+}
+
+// Moves the factory forward by one round: every step that is ready runs, in
+// parallel. `host` supplies: provider, fetchPage(url), emit(event), now(), limits.
+export async function advance(state, host) {
+  if (!(await admit(state, host))) return state;
+  const ready = readySteps(state);
+  if (!ready.length) return finishOrStuck(state, host);
 
   const working = ready.filter((step) => step.kind !== 'approve').slice(0, host.limits.parallel || 4);
   if (working.length) {
@@ -1580,8 +1833,11 @@ export async function advance(state, host) {
     for (const outcome of outcomes) if (outcome.sendBack) { state.steps[outcome.step.id].status = 'pending'; sendBack(state, outcome.sendBack.target, outcome.sendBack); }
     return state;
   }
+  return approvalStep(state, host, ready[0]);
+}
 
-  const step = ready[0];
+// An approval step: asks the person, or applies the decision they gave.
+async function approvalStep(state, host, step) {
   const slot = state.steps[step.id];
   const decision = state.approval && state.approval.step === step.id ? state.approval.decision : null;
   if (!decision) {
@@ -1693,6 +1949,8 @@ export async function buildReceipt(state) {
   const flags = current.filter((record) => record.status === 'flagged' || record.status === 'unreviewed').map((record) => `${record.title}: ${record.status === 'flagged' ? 'the check still failed after the allowed redo' : 'the reviewer returned no valid verdict'}`);
   flags.push(...new Set(current.flatMap((record) => [...(record.limitations || []), ...(record.review?.limitations || [])])));
   if (reviewStatus === 'not_checked') flags.push('The final deliverable was not checked.');
+  // Experimental features in use: named by the run, or a step admitted with tool sources.
+  const experimental = [...new Set([...(state.experimental || []), ...(state.factory.steps.some((step) => step.sources?.length) ? ['tool-sources'] : [])])];
   return {
     v: 2,
     kind: 'factory-run-receipt',
@@ -1710,7 +1968,8 @@ export async function buildReceipt(state) {
       kind: record.kind,
       attempt: record.attempt,
       status: record.status,
-      tools: record.tools.map((tool) => ({ tool: tool.tool, target: tool.target })),
+      // A run with experimental features keeps every call's details, `ok` included.
+      tools: record.tools.map((tool) => (experimental.length ? { ...tool } : { tool: tool.tool, target: tool.target })),
       note: record.verdict?.note,
       verdict: record.verdict,
       review: record.review,
@@ -1727,9 +1986,96 @@ export async function buildReceipt(state) {
     deliverable_review: { status: reviewStatus, sha256: deliveredHash, checks: outputs ? outputs.flatMap((output) => output.review.checks) : checks.map((record) => ({ id: record.id, attempt: record.attempt })) },
     deliverable_sha256: deliveredHash,
     usage: { ...state.usage },
+    ...(experimental.length ? { experimental, ...(Array.isArray(state.toolSourceRecords) ? { tool_sources: state.toolSourceRecords } : {}) } : {}),
   };
 }
 
+// How many rounds runToEnd allows before it gives up, and so how many step
+// starts: a round starts at most `limits.parallel` steps.
+const MAX_ROUNDS = 120;
+
+// Applies the result of a step that ran without error. A check that failed its
+// subject sends the subject back. A step that was itself sent back while it
+// ran stays pending: it was built on work that is being redone.
+function settle(state, outcome) {
+  const slot = state.steps[outcome.step.id];
+  if (outcome.sendBack) { slot.status = 'pending'; sendBack(state, outcome.sendBack.target, outcome.sendBack); }
+  else if (slot.status === 'running') slot.status = 'done';
+}
+
+// Whether a ready step waits for steps already in flight. Work that was sent
+// back waits until the runs built on it have ended, so every reviewer's
+// reasons reach the same redo. A step built on work under review waits for
+// that review, so it never runs on a result that is about to be sent back.
+// Steps that become ready together start together, as in a round.
+function mustWait(state, step, inFlight) {
+  if (!inFlight.length) return false;
+  const ancestors = ancestorsOf(state.factory, step.id);
+  return inFlight.some((id) => {
+    const other = state.factory.steps.find((item) => item.id === id);
+    return ancestorsOf(state.factory, id).includes(step.id) || (other.kind === 'check' && ancestors.includes(other.target));
+  });
+}
+
+// Runs the factory by dataflow: a step starts as soon as its own needs are
+// done, up to `limits.parallel` at once, instead of when the slowest step of
+// its round ends. Returns when the run ends or only an approval is left: the
+// person is asked only when nothing is in flight. advance() keeps the rounds.
+async function runReady(state, host, budget) {
+  if (!(await admit(state, host))) return state;
+  const limit = host.limits.parallel || 4;
+  const running = new Map();
+  // Records keep the order their steps started in, whatever order the steps
+  // end in: each record's place is reserved by its start number. A record is
+  // in state.records as soon as its step ends, because later steps read it.
+  const from = state.records.length;
+  const places = [];
+  let failed = null;
+  let exhausted = false;
+  let held = [];
+  for (;;) {
+    if (!failed) {
+      const inFlight = [...running.keys()];
+      for (const step of readySteps(state)) {
+        if (running.size >= limit) break;
+        if (step.kind === 'approve' || running.has(step.id) || mustWait(state, step, inFlight)) continue;
+        if (budget.starts >= MAX_ROUNDS * limit) { exhausted = true; break; }
+        const place = budget.starts;
+        budget.starts += 1;
+        running.set(step.id, runStep(state, step, host).then((outcome) => ({ outcome, place })));
+      }
+    }
+    if (!running.size) break;
+    const { outcome, place } = await Promise.race(running.values());
+    running.delete(outcome.step.id);
+    let at = places.length;
+    while (at > 0 && places[at - 1] > place) at -= 1;
+    places.splice(at, 0, place);
+    state.records.splice(from + at, 0, outcome.record);
+    // After a failure nothing new starts; the steps in flight end first.
+    if (outcome.error) failed ||= outcome;
+    else if (!failed) held.push(outcome);
+    if (failed) continue;
+    // Reviewers of the same work end at different moments. A review that
+    // sends the work back waits for the others still reviewing it, and they
+    // are applied in the order the flow lists them: the redo then reads their
+    // reasons in the same order on every run, as it does in a round.
+    const reviewed = new Set([...running.keys()].map((id) => state.factory.steps.find((item) => item.id === id)).filter((item) => item.kind === 'check').map((item) => item.target));
+    const due = held.filter((item) => !(item.sendBack && reviewed.has(item.sendBack.target)));
+    held = held.filter((item) => !due.includes(item));
+    for (const item of due.sort((a, b) => state.factory.steps.indexOf(a.step) - state.factory.steps.indexOf(b.step))) settle(state, item);
+  }
+  if (failed) return fail(state, host, failed.step.id, failed.error, failed.failure);
+  if (exhausted) {
+    state.status = 'failed';
+    state.error = 'The factory did not finish within its step budget.';
+    return state;
+  }
+  const ready = readySteps(state);
+  if (!ready.length) return finishOrStuck(state, host);
+  return approvalStep(state, host, ready[0]);
+}
+
 // Runs a factory until it ends or needs a person. `onApproval(approval,
 // artifactText, problem)` resolves to { action: 'approve' | 'revise' |
 // 'reject', note?, seen, approvalId } where approvalId is approval.id and
@@ -1739,8 +2085,9 @@ export async function buildReceipt(state) {
 // onApproval, or an answer that is not a decision, the run is returned still
 // waiting. A refused decision is asked again with the reason.
 export async function runToEnd(state, host, onApproval) {
-  for (let guard = 0; guard < 120; guard += 1) {
-    await advance(state, host);
+  const budget = { starts: 0 };
+  for (let guard = 0; guard < MAX_ROUNDS; guard += 1) {
+    await runReady(state, host, budget);
     if (state.status === 'waiting') {
       await ensureApprovalIdentity(state);
       if (!onApproval) return state;