factoryhub 0.0.0-stage → 0.1.0

package/packages/engine/lib/skill.mjs

@@ -0,0 +1,229 @@
+// Exports a factory as an Agent Skill folder, following spec/skill-export.md.
+// The factoryhub site implements the same mapping; the golden files in
+// spec/skill-export/, one per house factory, keep the two identical.
+//
+//   <id>/SKILL.md          frontmatter + instructions written from the flow
+//   <id>/factory/...       the canonical bundle, byte for byte
+import { parseBundle, parseYaml, bundleHash, finalStep, isGeneratedForeman } from '../src/factory-engine.mjs';
+import { canonicalFiles } from './catalog.mjs';
+import { DEFAULT_HUB } from './hub.mjs';
+
+export const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const MAX_NAME = 64;
+export const MAX_DESCRIPTION = 1024;
+export const SKILL_SECTIONS = ['## What it produces', '## Inputs to collect', '## Steps', '## Run it with the factoryhub CLI', '## Follow it by hand'];
+export const DECISION_LINE = 'Stop and ask the person to approve';
+// The Agent Skills spec makes `metadata` a map from strings to strings, so the
+// factoryhub fields are flat keys with a `factoryhub-` prefix, in this order.
+export const METADATA_KEYS = ['factoryhub-id', 'factoryhub-version', 'factoryhub-source', 'factoryhub-sha256', 'factoryhub-author'];
+
+const q = (text) => JSON.stringify(String(text));
+const indent = (text, pad = '   ') => String(text).trim().split('\n').map((line) => (line.trim() ? `${pad}${line}` : '')).join('\n');
+const times = (n) => (n === 1 ? 'once' : `up to ${n} times`);
+
+/** The skill description: the factory's own, plus a "Use when" sentence when it has none. */
+export function skillDescription(factory) {
+  const base = String(factory.description || '').replace(/\s+/g, ' ').trim();
+  const tail = /\buse when\b/i.test(base) ? '' : ` Use when the person wants to run the “${factory.title}” factory.`;
+  if (base.length + tail.length <= MAX_DESCRIPTION) return `${base}${tail}`;
+  const room = MAX_DESCRIPTION - tail.length - 1;
+  const cut = base.slice(0, room).replace(/\s+\S*$/, '');
+  return `${cut}…${tail}`;
+}
+
+function frontmatter({ id, factory, sha256, source }) {
+  // Every value is quoted, so a name such as `no` or `2024` stays text in any YAML reader.
+  const lines = ['---', `name: ${q(id)}`, `description: ${q(skillDescription(factory))}`];
+  if (factory.license) lines.push(`license: ${q(factory.license)}`);
+  lines.push('metadata:', `  factoryhub-id: ${q(id)}`, `  factoryhub-version: ${q(factory.version)}`, `  factoryhub-source: ${q(source)}`, `  factoryhub-sha256: ${q(sha256)}`);
+  if (factory.author) lines.push(`  factoryhub-author: ${q(factory.author)}`);
+  lines.push('---');
+  return lines.join('\n');
+}
+
+function produces(factory) {
+  const last = finalStep(factory);
+  const lines = [];
+  if (factory.outputs) {
+    lines.push('The deliverable joins these results, in this order, without rewriting them:', '', ...factory.outputs.map((output) => `- **${output.title}**, from the step "${titleOf(factory, output.step)}"`));
+  } else if (last) {
+    lines.push(`The deliverable is the result of the step **${last.title}**, written by the \`${last.agent}\` agent.`);
+  } else {
+    lines.push('This factory declares no step that produces a result.');
+  }
+  if (factory.done.length) lines.push('', 'It is done when:', '', ...factory.done.map((line) => `- ${line}`));
+  return lines.join('\n');
+}
+
+function inputs(factory) {
+  if (!factory.inputs.length) return 'This factory takes no inputs.';
+  const required = factory.inputs.filter((input) => input.required).length;
+  return [
+    `Ask the person for these before the first step. ${required ? `${required} ${required === 1 ? 'is' : 'are'} required.` : 'All are optional.'}`,
+    '',
+    ...factory.inputs.map((input) => `- **${input.key}** (${input.type}, ${input.required ? 'required' : 'optional'})${input.help ? `: ${input.help}` : ''}`),
+    '',
+    'A `text` or `url` input holds up to 2,000 characters and a `longtext` input up to 40,000; all inputs together hold up to 80,000. Never invent a missing input: ask for it, or leave an optional one empty.',
+  ].join('\n');
+}
+
+const titleOf = (factory, id) => factory.steps.find((step) => step.id === id)?.title || id;
+
+function steps(factory) {
+  if (!factory.steps.length) return 'This factory has no flow, so it declares no steps. Follow `factory/agents/foreman/agent.md` if it has one.';
+  const parallel = factory.steps.some((step) => factory.steps.some((other) => other.id !== step.id && other.needs.length && other.needs.join() === step.needs.join()));
+  const head = `Do the steps in this order. A step starts only when the steps it needs are finished.${parallel ? ' Steps that need the same earlier steps can run at the same time.' : ''}`;
+  const items = factory.steps.map((step, index) => {
+    const needs = step.needs.length ? step.needs.map((id) => `"${titleOf(factory, id)}"`).join(', ') : 'nothing earlier';
+    const agent = factory.agents[step.agent];
+    const who = `the \`${step.agent}\` agent${agent?.description ? ` (${agent.description.replace(/\.$/, '')})` : ''}`;
+    if (step.kind === 'approve') {
+      return [
+        `${index + 1}. **${step.title}** (a decision). Who: the person. Needs: ${needs}.`,
+        '',
+        indent(`${DECISION_LINE} the result of "${titleOf(factory, step.target)}". Show it to them in full.${step.task ? ` ${step.task.replace(/\s+/g, ' ').trim()}` : ''}`),
+        '',
+        indent(`If they approve, continue. ${step.rounds ? `If they ask for changes, redo "${titleOf(factory, step.target)}" with their note, ${times(step.rounds)}, and redo every step that used it. ` : 'This decision allows no changes: they approve or reject. '}If they reject it, stop: the run has no result. Never decide for them.`),
+      ].join('\n');
+    }
+    if (step.kind === 'check') {
+      return [
+        `${index + 1}. **${step.title}** (a check). Who: ${who}. Needs: ${needs}.`,
+        '',
+        indent(`Check the result of "${titleOf(factory, step.target)}" against these criteria:`),
+        '',
+        indent(step.task || 'The result does what its step was asked to do, with no invented facts.', '   > '),
+        '',
+        indent(step.rounds ? `If it fails, send it back to be redone ${times(step.rounds)} with the reasons, and redo every step that used it. If it still fails, carry on and tell the person the check failed.` : 'If it fails, do not redo it: carry on and tell the person the check failed.'),
+      ].join('\n');
+    }
+    const tools = [...step.tools, ...step.missing];
+    return [
+      `${index + 1}. **${step.title}** (${step.kind === 'deliver' ? 'writes the deliverable' : 'work'}). Who: ${who}. Needs: ${needs}.${tools.length ? ` Tools: ${tools.map((tool) => `\`${tool}\``).join(', ')}.` : ''}`,
+      '',
+      indent(step.task),
+    ].join('\n');
+  });
+  return [head, '', items.join('\n\n')].join('\n');
+}
+
+function cliRun(factory) {
+  const example = factory.inputs.filter((input) => input.required).map((input) => ` --input ${input.key}="..."`).join('');
+  return [
+    'The factoryhub CLI runs these steps exactly as written, stops at every decision to ask the person, and writes the deliverable with a receipt of every step. It calls the model with your own key.',
+    '',
+    '```sh',
+    'git clone https://github.com/Mindburn-Labs/factoryhub',
+    'cd factoryhub && npm ci',
+    'export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY or OPENROUTER_API_KEY',
+    `npx factoryhub run /path/to/this/skill/factory${example}`,
+    '```',
+    '',
+    'A model on your own machine works too: add `--provider ollama --model <name>`, or `--base-url <url> --model <name>` for any OpenAI-compatible server.',
+  ].join('\n');
+}
+
+function byHand(factory) {
+  const agents = [...new Set(factory.steps.map((step) => step.agent).filter((name) => name && name !== 'owner'))];
+  const last = finalStep(factory);
+  return [
+    'Without the CLI, follow the factory from its files:',
+    '',
+    '1. Read `factory/agents/foreman/agent.md`. It describes the whole workflow in prose.',
+    `2. For each step above, take on the role in its agent file (${agents.map((name) => `\`factory/agents/${name}/agent.md\``).join(', ') || 'none'}) and do the task. Use only the inputs, the results of earlier steps and pages you actually read. Say plainly when something could not be found.`,
+    `3. At every decision, ${DECISION_LINE.charAt(0).toLowerCase()}${DECISION_LINE.slice(1)}. Wait for their answer.`,
+    `4. ${factory.outputs ? 'Give the person the declared outputs, in order and unchanged.' : last ? `Give the person the result of "${last.title}", unchanged, as the deliverable.` : 'There is no deliverable step.'}`,
+    '',
+    'Following the files by hand does not reproduce the runner\'s enforced checks or its receipt. Use the CLI when those matter.',
+  ].join('\n');
+}
+
+/**
+ * Builds the skill folder for a factory. Returns { id, sha256, files } where
+ * `files` maps paths inside the `<id>/` folder to their text.
+ */
+export async function exportSkill(sourceFiles, { id, source, hub = DEFAULT_HUB } = {}) {
+  const bundle = canonicalFiles(sourceFiles);
+  const { ok, errors, factory } = parseBundle(bundle);
+  if (!ok) throw new Error(`This factory is not valid, so it cannot be exported:\n${errors.map((error) => `  - ${error}`).join('\n')}`);
+  const name = id || factory.name;
+  if (!SKILL_NAME.test(name) || name.length > MAX_NAME) throw new Error(`"${name}" cannot be a skill name: use lowercase letters, digits and single hyphens, at most ${MAX_NAME} characters.`);
+  const sha256 = await bundleHash(bundle);
+  const url = source || `${hub.replace(/\/+$/, '')}/f/${name}`;
+  const body = [
+    `# ${factory.title}`,
+    '',
+    factory.description,
+    '',
+    // Read from the canonical bundle alone, so a bundle that already carries the
+    // foreman the engine writes exports to the same bytes as one without it.
+    `This skill was exported from the factory \`${name}\`, version ${factory.version}. \`factory/\` holds the factory's own files, unchanged, ${isGeneratedForeman(bundle['agents/foreman/agent.md']) ? 'plus a foreman written from the flow' : 'with nothing added'}. Source: ${url}`,
+    '',
+    '## What it produces', '', produces(factory), '',
+    '## Inputs to collect', '', inputs(factory), '',
+    '## Steps', '', steps(factory), '',
+    '## Run it with the factoryhub CLI', '', cliRun(factory), '',
+    '## Follow it by hand', '', byHand(factory), '',
+  ].join('\n');
+  const files = { 'SKILL.md': `${frontmatter({ id: name, factory, sha256, source: url })}\n\n${body}` };
+  for (const [path, content] of Object.entries(bundle)) files[`factory/${path}`] = content;
+  return { id: name, sha256, files };
+}
+
+/** Splits a SKILL.md into its frontmatter text and body. */
+export function splitSkill(text) {
+  const match = String(text).match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  return match ? { head: match[1], body: match[2] } : null;
+}
+
+/**
+ * Checks an exported skill folder (paths relative to the `<id>/` folder).
+ * Returns a list of problems; empty means it passes.
+ */
+export async function checkSkill(files, { folder, hub = DEFAULT_HUB } = {}) {
+  const problems = [];
+  const text = files['SKILL.md'];
+  if (typeof text !== 'string') return ['SKILL.md is missing.'];
+  const parts = splitSkill(text);
+  if (!parts) return ['SKILL.md needs YAML frontmatter between --- lines at the top.'];
+  let meta;
+  try { meta = parseYaml(parts.head); } catch (error) { return [`The frontmatter is not valid YAML: ${error.message}`]; }
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return ['The frontmatter must be a mapping.'];
+  const known = ['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools'];
+  for (const key of Object.keys(meta)) if (!known.includes(key)) problems.push(`Unknown frontmatter field "${key}".`);
+  const name = meta.name;
+  if (typeof name !== 'string' || !SKILL_NAME.test(name) || name.length > MAX_NAME) problems.push('name must be lowercase letters, digits and single hyphens, at most 64 characters.');
+  if (folder && name !== folder) problems.push(`name "${name}" must match the folder name "${folder}".`);
+  if (typeof meta.description !== 'string' || !meta.description.trim() || meta.description.length > MAX_DESCRIPTION) problems.push(`description must be 1 to ${MAX_DESCRIPTION} characters.`);
+  else if (!/\buse when\b/i.test(meta.description)) problems.push('description must say when to use the skill ("Use when ...").');
+  if (meta.license !== undefined && (typeof meta.license !== 'string' || !meta.license.trim())) problems.push('license must be text.');
+  const metadata = meta.metadata;
+  let info = null;
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) problems.push('metadata is missing: it must be a map with the factoryhub-* fields.');
+  else {
+    for (const [key, value] of Object.entries(metadata)) if (typeof value !== 'string') problems.push(`metadata.${key} must be text: the Agent Skills spec allows only string values.`);
+    info = { id: metadata['factoryhub-id'], version: metadata['factoryhub-version'], source: metadata['factoryhub-source'], sha256: metadata['factoryhub-sha256'], author: metadata['factoryhub-author'] };
+    if (info.id !== name) problems.push('metadata.factoryhub-id must equal name.');
+    if (typeof info.version !== 'string' || !info.version) problems.push('metadata.factoryhub-version must be text.');
+    if (typeof info.source !== 'string' || !/^https:\/\/\S+\/f\/[a-z0-9-]+$/.test(info.source)) problems.push('metadata.factoryhub-source must be the factory\'s https address.');
+    else if (info.source !== `${hub.replace(/\/+$/, '')}/f/${name}`) problems.push(`metadata.factoryhub-source must be ${hub}/f/${name}.`);
+    if (typeof info.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(info.sha256)) problems.push('metadata.factoryhub-sha256 must be a SHA-256 hex digest.');
+  }
+  for (const heading of SKILL_SECTIONS) if (!parts.body.includes(`\n${heading}\n`)) problems.push(`The body is missing the section "${heading}".`);
+  const bundle = {};
+  for (const [path, content] of Object.entries(files)) {
+    if (path === 'SKILL.md') continue;
+    if (!path.startsWith('factory/')) { problems.push(`Unexpected file ${path}: a skill export holds SKILL.md and factory/ only.`); continue; }
+    bundle[path.slice('factory/'.length)] = content;
+  }
+  const parsed = parseBundle(bundle);
+  if (!parsed.ok) problems.push(`factory/ is not a valid factory: ${parsed.errors.join(' ')}`);
+  else {
+    if (parsed.factory.name !== name && !info?.source) problems.push('factory/ holds a different factory.');
+    if (info && (await bundleHash(bundle)) !== info.sha256) problems.push('factory/ does not match metadata.factoryhub-sha256.');
+    const decisions = parsed.factory.steps.filter((step) => step.kind === 'approve').length;
+    const asked = parts.body.split(`${DECISION_LINE} the result of`).length - 1;
+    if (asked !== decisions) problems.push(`The flow has ${decisions} decision steps but the body asks the person ${asked} times.`);
+  }
+  return problems;
+}

package/packages/engine/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@factoryhub/engine",
+  "version": "0.1.0",
+  "description": "The factory engine: parses factory bundles, runs their flows with your model, and writes and verifies receipts. No dependencies.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "private": true,
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mindburn-Labs/factoryhub.git",
+    "directory": "packages/engine"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./factory-engine": "./src/factory-engine.mjs",
+    "./author-tests": "./src/author-tests.mjs",
+    "./compose": "./src/compose.mjs",
+    "./cost": "./src/cost.mjs",
+    "./diagnostics": "./src/diagnostics.mjs",
+    "./markdown": "./src/markdown.mjs",
+    "./package": "./src/package.mjs",
+    "./node": "./lib/node.mjs",
+    "./skill": "./lib/skill.mjs",
+    "./hub": "./lib/hub.mjs",
+    "./catalog": "./lib/catalog.mjs",
+    "./run": "./lib/run.mjs",
+    "./providers": "./lib/providers.mjs"
+  },
+  "files": [
+    "src",
+    "lib"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  }
+}

package/packages/engine/src/author-tests.mjs

@@ -0,0 +1,78 @@
+// Portable, declarative examples. No code, regular expressions or extra grader.
+import { parseBundle, parseYaml, checkInputs, sha256 } from './factory-engine.mjs';
+
+export const AUTHOR_TEST_VERSION = 1;
+export const AUTHOR_TEST_FILE = 'mindburn.tests.yaml';
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const unknown = (value, allowed) => Object.keys(value).filter(key => !allowed.includes(key));
+
+export function readAuthorTests(files) {
+  if (!Object.hasOwn(files, AUTHOR_TEST_FILE)) return { declared: false, ok: true, cases: [], errors: [] };
+  const errors = [], cases = [];
+  try {
+    const spec = parseYaml(files[AUTHOR_TEST_FILE]);
+    if (!object(spec) || spec.version !== 1 || unknown(spec, ['version', 'cases']).length
+      || !object(spec.cases) || !Object.keys(spec.cases).length || Object.keys(spec.cases).length > 8) {
+      throw new Error('Use version: 1 and a cases mapping with 1–8 examples.');
+    }
+    const { factory } = parseBundle(files);
+    for (const [id, entry] of Object.entries(spec.cases)) {
+      if (!/^[a-z][a-z0-9_-]{0,63}$/.test(id) || !object(entry) || unknown(entry, ['name', 'inputs', 'expect']).length) throw new Error(`Invalid example: ${id.slice(0, 64)}.`);
+      const name = entry.name === undefined ? id.replaceAll('_', ' ') : entry.name;
+      if (typeof name !== 'string' || !name.trim() || name.length > 100) throw new Error(`Give ${id} a name of at most 100 characters.`);
+      if (!object(entry.inputs)) throw new Error(`${id} needs an inputs mapping.`);
+      const inputs = checkInputs(factory, entry.inputs);
+      if (!inputs.ok) throw new Error(`${id}: ${inputs.problems.join(' ')}`);
+      const expect = entry.expect;
+      if (!object(expect) || unknown(expect, ['contains', 'excludes', 'min_length', 'max_length']).length) throw new Error(`${id} needs supported expected-result checks.`);
+      let checks = 0;
+      for (const key of ['contains', 'excludes']) {
+        if (expect[key] === undefined) continue;
+        if (!Array.isArray(expect[key]) || !expect[key].length || expect[key].length > 50
+          || expect[key].some(value => typeof value !== 'string' || !value.trim() || value.length > 500)) throw new Error(`${id}.${key} needs 1–50 nonempty text values of at most 500 characters.`);
+        checks += expect[key].length;
+      }
+      for (const key of ['min_length', 'max_length']) {
+        if (expect[key] === undefined) continue;
+        if (!Number.isInteger(expect[key]) || expect[key] < 0 || expect[key] > 100000) throw new Error(`${id}.${key} must be an integer from 0 to 100000.`);
+        checks += 1;
+      }
+      if (!checks || (expect.min_length !== undefined && expect.max_length !== undefined && expect.min_length > expect.max_length)) throw new Error(`${id} needs at least one consistent expected-result check.`);
+      cases.push({ id, name: name.trim(), inputs: inputs.inputs, expect, checks });
+    }
+  } catch (error) { errors.push(String(error.message).slice(0, 1200)); }
+  return { declared: true, ok: errors.length === 0, cases: errors.length ? [] : cases, errors };
+}
+
+export async function evaluateAuthorTest(example, run) {
+  const total = example.checks;
+  if (run.status !== 'done') return { status: 'failed', total, passed: 0, failures: ['The run did not finish with a result.'], models: [] };
+  const output = String(run.deliverable || '');
+  const normalize = text => text.normalize('NFKC').toLowerCase().replace(/\s+/g, ' ').trim();
+  const folded = normalize(output), checks = [];
+  for (const value of example.expect.contains || []) checks.push([`Contains “${value}”`, folded.includes(normalize(value))]);
+  for (const value of example.expect.excludes || []) checks.push([`Excludes “${value}”`, !folded.includes(normalize(value))]);
+  const length = [...output].length;
+  if (example.expect.min_length !== undefined) checks.push([`At least ${example.expect.min_length} characters`, length >= example.expect.min_length]);
+  if (example.expect.max_length !== undefined) checks.push([`At most ${example.expect.max_length} characters`, length <= example.expect.max_length]);
+  const failures = checks.filter(([, passed]) => !passed).map(([name]) => name);
+  return { status: failures.length ? 'failed' : 'passed', total, passed: total - failures.length, failures,
+    outputSha256: await sha256(output), models: [...new Set((run.receipt?.usage?.metering?.calls || []).map(call => call.model).filter(Boolean))] };
+}
+
+export function authorTestSummary(definition, records = [], includeRuns = false) {
+  if (!definition.declared) return { status: 'not-verified', declared: false, total: 0, passed: 0, cases: [] };
+  if (!definition.ok) return { status: 'invalid', declared: true, total: 0, passed: 0, cases: [], errors: definition.errors };
+  const cases = definition.cases.map(example => {
+    const record = records.find(item => item?.caseId === example.id);
+    return { id: example.id, name: example.name, total: example.checks, passed: record?.passed || 0,
+      status: record?.status || 'not-run', failures: record?.failures || [],
+      ...(includeRuns && record?.runId ? { runId: record.runId } : {}) };
+  });
+  const status = cases.some(item => item.status === 'running') ? 'running'
+    : cases.some(item => item.status === 'failed') ? 'failed'
+      : cases.every(item => item.status === 'passed') ? 'passed' : 'not-run';
+  return { version: AUTHOR_TEST_VERSION, declared: true, status, total: cases.reduce((sum, item) => sum + item.total, 0),
+    passed: cases.reduce((sum, item) => sum + item.passed, 0), cases,
+    models: [...new Set(records.flatMap(record => record?.models || []))], provenance: 'hub-run-tests' };
+}

package/packages/engine/src/compose.mjs

@@ -0,0 +1,150 @@
+// Deterministic composition. The resulting ordinary bundle is execution truth;
+// no member definition or registry is consulted when it runs.
+import { parseBundle, parseYaml, toYaml, normalizeFiles, ancestorsOf, finalStep, bundleHash, canonical, withForeman, isGeneratedForeman, parseFrontmatter, INPUT_TYPES } from './factory-engine.mjs';
+
+export const COMPILER_VERSION = 'mindburn.compose/v1';
+const fail = (message) => { throw new Error(message); };
+const map = (value) => value && typeof value === 'object' && !Array.isArray(value);
+const keys = (value, allowed, label) => {
+  if (!map(value)) fail(`${label} must be a map.`);
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) fail(`${label} has unsupported semantics: ${unknown.join(', ')}.`);
+};
+const namespace = (member, id) => {
+  const result = `${member}_${id}`;
+  if (!/^[a-z][a-z0-9_]{0,40}$/.test(result)) fail(`The namespaced name "${result}" exceeds the portable name limit.`);
+  return result;
+};
+
+const agentName = (member, name) => namespace(member, name.replaceAll('-', '_')).replaceAll('_', '-');
+
+export async function composeFactories(spec) {
+  keys(spec, ['name', 'title', 'description', 'intent', 'inputs', 'members', 'outputs', 'unmetCapabilities'], 'Composition');
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(spec.name || '') || typeof spec.title !== 'string' || !spec.title.trim() || typeof spec.intent !== 'string' || !spec.intent.trim() || spec.intent.length > 2000) fail('Composition needs a name, title and original intent.');
+  if (!Array.isArray(spec.members) || !spec.members.length || spec.members.length > 8) fail('Compose between 1 and 8 pinned factories.');
+  if (!map(spec.inputs) || Object.keys(spec.inputs).length > 8) fail('Composition needs at most 8 shared inputs.');
+  for (const [id, input] of Object.entries(spec.inputs)) {
+    if (!/^[a-z][a-z0-9_]{0,63}$/.test(id)) fail(`Invalid shared input "${id}".`);
+    keys(input, ['type', 'label', 'help', 'optional', 'required', 'visibility'], `Input ${id}`);
+    if (input.type !== undefined && !INPUT_TYPES.includes(input.type)) fail(`Unknown input type for ${id}.`);
+  }
+  const unmet = spec.unmetCapabilities === undefined ? [] : Array.isArray(spec.unmetCapabilities) ? [...spec.unmetCapabilities] : spec.unmetCapabilities;
+  if (!Array.isArray(unmet) || unmet.some((item) => typeof item !== 'string' || !item.trim())) fail('Unmet capabilities must be explicit text requirements.');
+  const members = new Map();
+  let defaults;
+  for (const member of spec.members) {
+    keys(member, ['id', 'files', 'sha256', 'inputs', 'public'], 'Member');
+    if (!/^[a-z][a-z0-9_]{0,15}$/.test(member.id || '') || members.has(member.id)) fail('Each member needs a unique short name.');
+    if (!/^[a-f0-9]{64}$/.test(member.sha256 || '') || await bundleHash(member.files) !== member.sha256) fail(`Pinned factory "${member.id}" does not match its bundle hash.`);
+    const parsed = parseBundle(member.files);
+    if (!parsed.ok || !parsed.factory.runnable) fail(`Factory "${member.id}" cannot run: ${[...parsed.errors, ...parsed.factory.blockers].join(' ')}`);
+    if (member.public !== undefined && typeof member.public !== 'boolean') fail('Member public scope must be boolean.');
+    const flow = parseYaml(member.files['flow.yaml']);
+    for (const input of Object.values(flow.inputs || {})) {
+      keys(input, ['type', 'label', 'help', 'optional', 'required', 'visibility'], 'Member input');
+      if (input.type !== undefined && !INPUT_TYPES.includes(input.type)) fail('Unsupported member input type.');
+    }
+    keys(flow, ['flow', 'requires', 'title', 'author', 'version', 'license', 'tags', 'time', 'inputs', 'steps', 'done', 'outputs', 'composition'], `Factory ${member.id}`);
+    if (flow.flow && flow.flow !== 'mindburn.flow/v1') fail('Unsupported member flow version.');
+    const config = parseYaml(member.files['factory.yaml']);
+    keys(config, ['schemaVersion', 'name', 'description', 'repositories', 'agentDefaults'], `Configuration ${member.id}`);
+    if (config.schemaVersion !== 'v1alpha1' || (config.repositories && (!Array.isArray(config.repositories) || config.repositories.length))) fail('Repository execution is not supported by this compiler.');
+    if (config.agentDefaults) {
+      keys(config.agentDefaults, ['harness'], 'Agent defaults');
+      if (config.agentDefaults.harness) keys(config.agentDefaults.harness, ['type', 'model'], 'Harness');
+    }
+    const memberDefaults = config.agentDefaults || null;
+    if (!members.size) defaults = memberDefaults;
+    else if (canonical(defaults) !== canonical(memberDefaults)) fail('Member harness defaults differ. Choose compatible source revisions before connecting them.');
+    for (const [path, text] of Object.entries(member.files)) {
+      if (!['factory.yaml', 'flow.yaml', 'README.md'].includes(path) && !/^agents\/[a-z0-9][a-z0-9_-]{0,40}\/agent\.md$/.test(path)) fail(`Cannot compile required file "${path}".`);
+      if (path.startsWith('agents/')) keys(parseFrontmatter(text).meta, ['description', 'agentType'], 'Agent metadata');
+      if (path === 'agents/foreman/agent.md' && !isGeneratedForeman(text)) fail('An authored foreman needs an explicit flow translation before composition.');
+    }
+    if (!map(member.inputs) || canonical(Object.keys(member.inputs).sort()) !== canonical(parsed.factory.inputs.map((input) => input.key).sort())) fail(`Map every input of "${member.id}" exactly once.`);
+    for (const raw of Object.values(flow.steps)) {
+      keys(raw, ['title', 'agent', 'kind', 'needs', 'checks', 'shows', 'tools', 'task', 'rounds', 'context', 'criteria'], `Step in ${member.id}`);
+      if ((raw.checks !== undefined && raw.kind !== 'check') || (raw.shows !== undefined && raw.kind !== 'approve')) fail('checks and shows must belong to their matching step kinds.');
+      if (raw.rounds !== undefined && (!Number.isInteger(raw.rounds) || raw.rounds < 0 || raw.rounds > 5)) fail('Revision rounds exceed this runner’s limits.');
+    }
+    members.set(member.id, { ...member, factory: parsed.factory, flow });
+  }
+  const steps = {};
+  const files = {};
+  const provenance = [];
+  const sourceRef = (ref) => {
+    keys(ref, ['member', 'step'], 'Artifact');
+    const member = members.get(ref.member);
+    const step = member?.factory.steps.find((item) => item.id === ref.step && ['work', 'deliver'].includes(item.kind));
+    if (!step) fail('An artifact binding must name member work.');
+    return { id: namespace(ref.member, ref.step), member };
+  };
+  for (const member of members.values()) {
+    const scoped = {};
+    for (const [alias, binding] of Object.entries(member.inputs)) {
+      keys(binding, ['input', 'artifact'], `Binding ${alias}`);
+      if (Object.keys(binding).length !== 1) fail('A binding selects exactly one shared input or artifact.');
+      if (binding.input !== undefined) {
+        if (!Object.hasOwn(spec.inputs, binding.input)) fail(`Unknown shared input "${binding.input}".`);
+        const sourceInput = member.factory.inputs.find((input) => input.key === alias);
+        const shared = spec.inputs[binding.input];
+        if ((shared.type || 'text') !== sourceInput.type || (sourceInput.required && (shared.optional === true || shared.required === false))) fail(`Shared input "${binding.input}" weakens the required type or presence of "${alias}".`);
+        if (sourceInput.visibility === 'private' && shared.visibility === 'public') fail('A private source input cannot become public.');
+        scoped[alias] = { input: binding.input };
+      } else {
+        if (member.factory.inputs.find((input) => input.key === alias).type !== 'longtext') fail('An artifact binding requires a longtext input.');
+        scoped[alias] = { artifact: sourceRef(binding.artifact) };
+      }
+    }
+    for (const name of Object.keys(member.factory.agents)) {
+      if (name === 'foreman') continue;
+      const path = `agents/${agentName(member.id, name)}/agent.md`;
+      if (Object.hasOwn(files, path)) fail(`Generated agent name collides: ${path}. Choose different member names.`);
+      files[path] = member.files[`agents/${name}/agent.md`];
+    }
+    for (const step of member.factory.steps) {
+      const raw = member.flow.steps[step.id];
+      if (!raw) fail('Member step names must already use canonical identifiers.');
+      const context = { inputs: {}, artifacts: {}, ...(member.public === true || step.context?.public ? { public: true } : {}) };
+      const needs = new Set(step.needs.map((id) => namespace(member.id, id)));
+      for (const [alias, input] of Object.entries(step.context?.inputs || Object.fromEntries(member.factory.inputs.map((item) => [item.key, item.key])))) {
+        const binding = scoped[input];
+        if (binding.input !== undefined) context.inputs[alias] = binding.input;
+        else {
+          if (binding.artifact.member.id === member.id) fail('Member inputs cannot bind their own output.');
+          context.artifacts[alias] = binding.artifact.id;
+          // Wait for the upstream factory's checks and approvals as well as
+          // its text. Revision invalidation then reaches every consumer.
+          for (const terminal of binding.artifact.member.factory.steps.filter((item) => !binding.artifact.member.factory.steps.some((other) => other.needs.includes(item.id)))) needs.add(namespace(binding.artifact.member.id, terminal.id));
+          needs.add(binding.artifact.id);
+        }
+      }
+      for (const [alias, id] of Object.entries(step.context?.artifacts || Object.fromEntries(ancestorsOf(member.factory, step.id).filter((id) => ['work', 'deliver'].includes(member.factory.steps.find((item) => item.id === id).kind)).map((id) => [id, id])))) {
+        if (Object.hasOwn(context.inputs, alias) || Object.hasOwn(context.artifacts, alias)) fail(`Context binding "${alias}" collides in ${member.id}.`);
+        context.artifacts[alias] = namespace(member.id, id);
+      }
+      const compiled = { ...raw, agent: step.kind === 'approve' ? undefined : agentName(member.id, step.agent), needs: [...needs], context };
+      if (step.kind === 'check') compiled.checks = namespace(member.id, step.target);
+      if (step.kind === 'approve') compiled.shows = namespace(member.id, step.target);
+      if (step.id === finalStep(member.factory)?.id && !member.factory.outputs) compiled.criteria = step.criteria || member.factory.done;
+      const id = namespace(member.id, step.id);
+      if (Object.hasOwn(steps, id)) fail(`Generated step name collides: ${id}. Choose different member names.`);
+      steps[id] = compiled;
+    }
+    for (const requirement of member.factory.composition?.unmetCapabilities || []) if (!unmet.includes(requirement)) unmet.push(requirement);
+    provenance.push({ id: member.id, name: member.factory.name, version: member.factory.version, sha256: member.sha256 });
+  }
+  if (Object.keys(steps).length > 24 || Object.keys(files).length > 39) fail('Connected work exceeds the portable step or agent limit. Split it explicitly.');
+  if (!Array.isArray(spec.outputs) || !spec.outputs.length) fail('Declare the exact output artifacts.');
+  const outputs = spec.outputs.map((output) => {
+    keys(output, ['member', 'step', 'title'], 'Output');
+    return { step: sourceRef({ member: output.member, step: output.step }).id, title: output.title };
+  });
+  files['factory.yaml'] = toYaml({ schemaVersion: 'v1alpha1', name: spec.name, description: spec.description || 'Connected factories produce checked documents with an owner decision.', repositories: [], ...(defaults ? { agentDefaults: defaults } : {}) });
+  files['flow.yaml'] = toYaml({ flow: 'mindburn.flow/v1', requires: ['scoped-context', 'multiple-outputs'], title: spec.title, version: '1.0.0', inputs: spec.inputs, steps, outputs, composition: { compiler: COMPILER_VERSION, intent: spec.intent, sources: provenance, unmetCapabilities: unmet } });
+  const result = withForeman(normalizeFiles(files));
+  if (Object.values(result).reduce((sum, value) => sum + value.length, 0) > 400000) fail('Connected bundle exceeds the portable size limit.');
+  const parsed = parseBundle(result);
+  if (!parsed.ok || !parsed.factory.runnable) fail([...parsed.errors, ...parsed.factory.blockers].join(' '));
+  return { files: result, factory: parsed.factory, sha256: await bundleHash(result) };
+}

package/packages/engine/src/cost.mjs

@@ -0,0 +1,41 @@
+// Published direct-API list prices, not an invoice or a spending allowance.
+// Source: https://platform.claude.com/docs/en/about-claude/pricing
+// Keep unknown models/tiers/usage unpriced rather than guessing a zero cost.
+const count = (value) => Number.isSafeInteger(value) && value >= 0;
+const round = (value) => Math.round(value * 1e9) / 1e9;
+
+function price(call) {
+  if (call?.provider !== 'anthropic' || call.billing !== 'anthropic-direct' || call.measured !== true
+    || call.serviceTier !== 'standard' || ![null, 'standard'].includes(call.speed)
+    || ![null, 'global', 'us'].includes(call.inferenceGeo)) return null;
+  const fields = ['input', 'output', 'uncachedInput', 'cacheReadInput', 'cacheWriteInput', 'cacheWrite5mInput', 'cacheWrite1hInput', 'searchRequests'];
+  if (!fields.every((key) => count(call[key])) || call.input !== call.uncachedInput + call.cacheReadInput + call.cacheWriteInput
+    || call.cacheWriteInput !== call.cacheWrite5mInput + call.cacheWrite1hInput) return null;
+  let input, output, cacheRead;
+  if (call.model === 'claude-haiku-5-5') {
+    [input, output, cacheRead] = call.input > 100000 ? [0.5, 2.5, 0.05] : [0.1, 0.5, 0.01];
+  } else if (call.model === 'claude-sonnet-5-5') [input, output, cacheRead] = [2, 10, 0.1];
+  else return null;
+  const tokens = (call.uncachedInput * input + call.output * output + call.cacheReadInput * cacheRead
+    + call.cacheWrite5mInput * input * 1.25 + call.cacheWrite1hInput * input * 2) / 1e6;
+  return tokens * (call.inferenceGeo === 'us' ? 1.1 : 1) + call.searchRequests * 0.01;
+}
+
+export function estimateRunCost(usage) {
+  const ledger = usage?.metering;
+  const unavailable = { currency: 'USD', estimatedUsd: null, recordedUsd: 0, pricedCalls: 0, unpricedCalls: count(usage?.llmCalls) ? usage.llmCalls : null, countersMatch: false };
+  if (ledger?.version !== 1 || !Array.isArray(ledger.calls) || !count(ledger.unrecorded)
+    || !count(usage.llmCalls) || ledger.calls.length + ledger.unrecorded !== usage.llmCalls) return unavailable;
+  let recorded = 0, pricedCalls = 0, unpricedCalls = ledger.unrecorded;
+  for (const call of ledger.calls) {
+    const cost = price(call);
+    if (cost === null) unpricedCalls += 1;
+    else { recorded += cost; pricedCalls += 1; }
+  }
+  // If the per-call ledger and run counters disagree, its subtotal is still
+  // useful but must not be presented as a price for the complete run.
+  const matches = ['input', 'output'].every((key) => count(usage[key]) && ledger.calls.every((call) => count(call?.[key]))
+    && ledger.calls.reduce((sum, call) => sum + call[key], 0) === usage[key]);
+  return { currency: 'USD', estimatedUsd: !unpricedCalls && matches ? round(recorded) : null,
+    recordedUsd: round(recorded), pricedCalls, unpricedCalls, countersMatch: matches };
+}

package/packages/engine/src/diagnostics.mjs

@@ -0,0 +1,21 @@
+// Safe operational evidence. Never include provider messages, user text,
+// artifact names, credentials or request headers in logs and CI output.
+import { failureDetails } from './factory-engine.mjs';
+import { estimateRunCost } from './cost.mjs';
+
+export function runDiagnostic(run) {
+  const status = ['running', 'waiting', 'done', 'failed', 'stopped'].includes(run?.status) ? run.status : 'unavailable';
+  const usage = Object.fromEntries(['input', 'output', 'llmCalls', 'fetches', 'searches'].map((key) => [key, Number.isSafeInteger(run?.usage?.[key]) && run.usage[key] >= 0 ? run.usage[key] : null]));
+  const failure = run?.failure;
+  const kind = run?.factory?.steps?.find((step) => step.id === failure?.step)?.kind;
+  return {
+    id: /^[A-Za-z0-9_-]{10,64}$/.test(run?.id || '') ? run.id : null,
+    status,
+    ...(status === 'failed' ? { failure: {
+      ...failureDetails({ code: failure?.code, status: failure?.httpStatus }),
+      stage: ['work', 'check', 'deliver', 'approve'].includes(kind) ? kind : null,
+    } } : {}),
+    usage,
+    ...(run?.usage?.metering ? { costEstimate: estimateRunCost(run.usage) } : {}),
+  };
+}