weftens 0.0.1 → 0.1.0

package/content-org/test.mjs

@@ -0,0 +1,110 @@
+// content-org — no-dependency test script (plain node, no vitest).
+// Run: npm test
+// Covers: (1) seat schema validation for all 10 seats in dry-run,
+//         (2) single-seat CLI mode, (3) review/publish queue round-trip.
+// The queue round-trip runs in a scratch dir so it never touches the real queue/.
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, readFileSync, rmSync, mkdtempSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { SEATS, stub } from "./orchestrator.mjs";
+import { SEAT_MODEL, MODELS } from "./config.mjs";
+
+const ROOT = dirname(fileURLToPath(import.meta.url));
+let pass = 0, fail = 0;
+function check(name, ok, detail = "") {
+  if (ok) { pass++; console.log(`  ok  ${name}`); }
+  else { fail++; console.error(`FAIL  ${name}${detail ? " — " + detail : ""}`); }
+}
+
+// Minimal validator for the subset of JSON Schema the seats use.
+function validate(value, schema, path = "$") {
+  const errs = [];
+  if (schema.type === "string") { if (typeof value !== "string") errs.push(`${path}: not a string`); return errs; }
+  if (schema.type === "boolean") { if (typeof value !== "boolean") errs.push(`${path}: not a boolean`); return errs; }
+  if (schema.type === "number") { if (typeof value !== "number") errs.push(`${path}: not a number`); return errs; }
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) { errs.push(`${path}: not an array`); return errs; }
+    value.forEach((v, i) => errs.push(...validate(v, schema.items, `${path}[${i}]`)));
+    return errs;
+  }
+  if (schema.type === "object") {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) { errs.push(`${path}: not an object`); return errs; }
+    for (const req of schema.required || []) if (!(req in value)) errs.push(`${path}.${req}: missing (required)`);
+    for (const [k, v] of Object.entries(value)) {
+      if (!schema.properties[k]) { if (schema.additionalProperties === false) errs.push(`${path}.${k}: unexpected property`); continue; }
+      errs.push(...validate(v, schema.properties[k], `${path}.${k}`));
+    }
+    return errs;
+  }
+  errs.push(`${path}: unknown schema type ${schema.type}`);
+  return errs;
+}
+
+// --- 1) All 9 seats: dry-run stub output conforms to each seat's own schema ------------
+console.log("\n[1] seat schemas (dry-run stubs) — 10 seats");
+const EXPECTED_SEATS = ["showrunner", "strategy", "ideator", "research", "script", "editor", "cut", "feed", "qc", "growth"];
+check("all 10 seats registered", EXPECTED_SEATS.every((k) => SEATS[k]) && Object.keys(SEATS).length === 10,
+  `have: ${Object.keys(SEATS).join(",")}`);
+for (const key of EXPECTED_SEATS) {
+  const seat = SEATS[key];
+  if (!seat) { check(`seat ${key}`, false, "missing"); continue; }
+  const out = stub(seat.schema, key);
+  const errs = validate(out, seat.schema);
+  check(`stub(${key}) matches schema`, errs.length === 0, errs.join("; "));
+  check(`${key} routes to a real model`, !!MODELS[SEAT_MODEL[key]], `SEAT_MODEL.${key}=${SEAT_MODEL[key]}`);
+}
+
+// --- 2) Single-seat CLI mode (dry-run, no API key needed) ------------------------------
+console.log("\n[2] single-seat CLI mode");
+for (const key of ["showrunner", "qc"]) {
+  let out, parsed = null, errs = ["did not run"];
+  try {
+    out = execFileSync(process.execPath, ["orchestrator.mjs", "--seat", key, "--input", '{"format":"scam-reveal"}', "--dry-run"],
+      { cwd: ROOT, encoding: "utf8" });
+    parsed = JSON.parse(out);
+    errs = validate(parsed, SEATS[key].schema);
+  } catch (e) { errs = [e.message]; }
+  check(`--seat ${key} --dry-run emits schema-valid JSON`, parsed !== null && errs.length === 0, errs.join("; "));
+}
+// unknown seat must exit non-zero
+let badExit = false;
+try { execFileSync(process.execPath, ["orchestrator.mjs", "--seat", "nope", "--input", "x", "--dry-run"], { cwd: ROOT, stdio: "pipe" }); }
+catch { badExit = true; }
+check("--seat with unknown key exits non-zero", badExit);
+
+// --- 3) review/publish queue round-trip (scratch dir; real queue/ untouched) -----------
+console.log("\n[3] review/publish queue round-trip");
+const scratch = mkdtempSync(join(tmpdir(), "content-org-test-"));
+try {
+  const slug = "test-piece";
+  mkdirSync(join(scratch, "queue", slug), { recursive: true });
+  const manifest = {
+    slug, format: "nostalgia", client: "testco", tier: "starter",
+    approval: "auto", reel: `${slug}.mp4`, status: "ready-for-approval",
+    qc: { blockers: [] }, feed: { caption: "test caption" },
+  };
+  writeFileSync(join(scratch, "queue", slug, "manifest.json"), JSON.stringify(manifest, null, 2));
+
+  const reviewOut = execFileSync(process.execPath, [join(ROOT, "review.mjs")], { cwd: scratch, encoding: "utf8" });
+  check("review.mjs lists the queued piece", reviewOut.includes(slug) && reviewOut.includes("1 in queue"));
+  check("review.mjs shows auto approval", /auto/.test(reviewOut));
+
+  execFileSync(process.execPath, [join(ROOT, "publish.mjs"), slug], { cwd: scratch, encoding: "utf8" });
+  const log = readFileSync(join(scratch, "published", "log.jsonl"), "utf8").trim().split("\n").map((l) => JSON.parse(l));
+  check("publish.mjs appends to published/log.jsonl", log.length === 1 && log[0].slug === slug);
+  check("published entry carries caption + reel", log[0].caption === "test caption" && log[0].reel === `${slug}.mp4`);
+  check("published entry marks Meta post as not wired", /not wired/.test(log[0].note || ""));
+
+  // 'auto' mode publishes only clean auto-approved pieces
+  execFileSync(process.execPath, [join(ROOT, "publish.mjs"), "auto"], { cwd: scratch, encoding: "utf8" });
+  const log2 = readFileSync(join(scratch, "published", "log.jsonl"), "utf8").trim().split("\n");
+  check("publish.mjs auto mode picks up the auto-approved piece", log2.length === 2);
+} finally {
+  rmSync(scratch, { recursive: true, force: true });
+}
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/index.js

@@ -0,0 +1,32 @@
+// Weftens SDK — the programmatic front door. The same deterministic routing and invoke
+// the CLI uses, exposed as an importable API so Weftens can be embedded in other code.
+//
+//   import { weftens, route, invoke, REGISTRY } from "weftens";
+//
+//   // one call: route a request and run the chosen agent
+//   const { decision, outcome } = await weftens("audit our facebook ads", { inputFile: "meta.csv" });
+//
+//   // or drive the pieces yourself
+//   const decision = route({ text: "who are the funders for this grant" });
+//   const outcome  = await invoke(decision.agent, { text: "..." });
+
+import { route } from "./src/agent-router.js";
+import { invoke } from "./src/invoke.js";
+import { REGISTRY, agentByName, dispatchableAgents } from "./src/registry.js";
+import { complete, loadProviders } from "./src/provider.js";
+
+export { route, invoke, REGISTRY, agentByName, dispatchableAgents, complete, loadProviders };
+
+/**
+ * Route a request and run the chosen agent — the one-call front door.
+ * @param request  a string (free text) or { text?, agent? } (agent = direct address)
+ * @param opts     { inputFile?, provider?, dry? } — passed through to invoke
+ * @returns { decision, outcome }  outcome is null when nothing routed
+ */
+export async function weftens(request, opts = {}) {
+  const req = typeof request === "string" ? { text: request } : request;
+  const decision = route(req);
+  if (!decision.agent) return { decision, outcome: null };
+  const outcome = await invoke(decision.agent, { text: req.text, ...opts });
+  return { decision, outcome };
+}

package/package.json

@@ -1,10 +1,49 @@
-{
-  "name": "weftens",
-  "version": "0.0.1",
-  "description": "Weftens — one front door that routes a marketing, SEO, ads and representation request to the right agent and runs it on your own AI subscription. Placeholder release; the working version follows.",
-  "license": "MIT",
-  "author": "Kayla Cardillo",
-  "keywords": ["cli", "agents", "marketing", "seo", "advertising", "audit"],
-  "engines": { "node": ">=22" },
-  "files": ["README.md", "LICENSE"]
-}
+{
+  "name": "weftens",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Weftens \u2014 one front door that routes a marketing/representation request to the right agent and runs it on your own AI subscription (bring-your-own-model). Usable as a CLI or an SDK.",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./cli": "./bin/weftens.js"
+  },
+  "bin": {
+    "weftens": "bin/weftens.js"
+  },
+  "license": "MIT",
+  "files": [
+    "bin",
+    "src",
+    "agents",
+    "agent-cores",
+    "content-org",
+    "index.js",
+    "providers.json.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "npm run test:unit && npm run test:cores",
+    "test:unit": "vitest run",
+    "test:cores": "node --test \"agent-cores/**/test/*.test.mjs\" \"agent-cores/**/test/*.test.js\"",
+    "start": "node bin/weftens.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.110.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Weftens/weftens.git"
+  },
+  "homepage": "https://github.com/Weftens/weftens#readme",
+  "bugs": {
+    "url": "https://github.com/Weftens/weftens/issues"
+  }
+}

package/providers.json.example

@@ -0,0 +1,9 @@
+{
+  "_comment": "Copy this to providers.json and edit. Each entry maps a provider name to the CLI that runs it (a tool you already have installed and are logged into — your own subscription). Pick the active one with the WEFTENS_PROVIDER env var; default is 'claude'. The prompt is piped to the CLI on stdin, so 'args' holds only flags.",
+  "providers": {
+    "claude": { "cmd": "claude", "args": ["-p"] },
+    "gemini": { "cmd": "gemini", "args": ["-p"] },
+    "codex": { "cmd": "codex", "args": ["exec"] },
+    "grok": { "cmd": "grok", "args": [] }
+  }
+}

package/src/agent-router.js

@@ -0,0 +1,124 @@
+// Registry routing — the front door's decision of WHICH agent answers a request.
+// This scales router.js's two-domain keyword classifier to the whole registry, and
+// keeps its core commitment: routing is deterministic and EXPLAINABLE. A request
+// matches an agent by how many of that agent's declared routeHints appear in it;
+// the reason is always the concrete hints that matched, so a customer (or the operator)
+// can see why it went where it did. No model call to route.
+//
+// Two ways in:
+//   - Direct address: the caller names an agent -> that agent, reason "named".
+//     Works for ANY agent, including the evaluation seats.
+//   - Auto-dispatch: score the free-text request across all dispatchable agents,
+//     pick the highest; ties and no-match are surfaced, never silently guessed.
+
+import { REGISTRY, agentByName, dispatchableAgents } from "./registry.js";
+
+// A hint matches only as a whole word/phrase, bounded by non-alphanumerics — NOT a raw
+// substring. A substring test routes "research" to a `search` hint and "cooperation" to
+// `operation`, then prints those as the explanation; since routing is meant to be
+// explainable, a confident-wrong reason is worse than no match. The [^a-z0-9] boundary
+// still lets "check-in"/"follow-up" match across the hyphen.
+// The `(?:s|es)?` allows the plain plural ("funder" matches "funders") without
+// opening the door back to arbitrary substrings — "search" still can't match inside
+// "research", because the leading boundary requires a non-alphanumeric before it.
+const HINT_RE = new Map();
+function hintRegex(hint) {
+  let re = HINT_RE.get(hint);
+  if (!re) {
+    const escaped = hint.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    re = new RegExp(`(^|[^a-z0-9])${escaped}(?:s|es)?([^a-z0-9]|$)`, "i");
+    HINT_RE.set(hint, re);
+  }
+  return re;
+}
+
+// Some single-word hints are legitimate signals for their agent but carry almost no
+// meaning on their own in ordinary English. On a lone hit they produced confident,
+// explainable, WRONG routes — the worst failure a "say what you need in plain language"
+// door can have, because it happens in front of someone:
+//   "opposite site"          -> richy   (matched: site)
+//   "grantham road listing"  -> richy   (matched: listing)
+//   "we need people ops"     -> pio     (matched: people)
+// They still count, at a third of a point, so a request with real signal alongside them
+// routes as before — but a lone weak hit can no longer clear the confidence floor.
+const WEAK_HINTS = new Set([
+  "site", "online", "listing", "people", "post", "content", "brief", "topic", "entity",
+  "profile", "record", "page", "search", "report", "data", "review",
+]);
+
+// A route must earn at least this much to be dispatched confidently. One ordinary hint
+// (1) clears it; one weak hint (0.34) does not; two weak hints do.
+const CONFIDENCE_FLOOR = 1;
+
+// Longer (multi-word) hints weigh more — "made for advertising" is a far stronger
+// signal than a bare "seo" — so specific phrases beat generic single words.
+function scoreAgent(agent, text) {
+  const matched = [];
+  const weak = [];
+  let score = 0;
+  for (const hint of agent.routeHints) {
+    if (hintRegex(hint).test(text)) {
+      if (hint.includes(" ")) { matched.push(hint); score += 3; }
+      else if (WEAK_HINTS.has(hint)) { weak.push(hint); score += 0.34; }
+      else { matched.push(hint); score += 1; }
+    }
+  }
+  return { score: Math.round(score * 100) / 100, matched, weak };
+}
+
+/**
+ * Route a request to one agent.
+ * @param request { text: string, agent?: string }  // agent = explicit name (direct address)
+ * @returns { agent, reason, confident, matched, alternatives }
+ *   agent        the chosen registry entry, or null if nothing matched
+ *   reason       "named" | "matched: <hints>" | "no confident match"
+ *   confident    true unless nothing matched or the top two tied
+ *   alternatives other agents that also scored (for the ambiguous case)
+ */
+export function route(request = {}) {
+  const text = String(request.text ?? "").toLowerCase();
+
+  // Direct address always wins — an explicit choice is never overridden by inference.
+  if (request.agent) {
+    const named = agentByName(request.agent);
+    if (!named) return { agent: null, reason: `unknown agent: ${request.agent}`, confident: false, matched: [], alternatives: [] };
+    return { agent: named, reason: "named", confident: true, matched: [], alternatives: [] };
+  }
+
+  const scored = dispatchableAgents()
+    .map((agent) => ({ agent, ...scoreAgent(agent, text) }))
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  if (scored.length === 0) {
+    return { agent: null, reason: "no confident match — name an agent or rephrase", confident: false, matched: [], alternatives: [] };
+  }
+
+  const top = scored[0];
+
+  // Only weak signal in the whole request: say so and stop. Refusing to guess is the
+  // point — a wrong confident answer in front of a stranger costs more than a reprompt.
+  if (top.score < CONFIDENCE_FLOOR) {
+    const seen = [...new Set(scored.flatMap((r) => r.weak))].join(", ");
+    return {
+      agent: null,
+      reason: `only weak signal (${seen}) — name an agent or say more about what you need`,
+      confident: false,
+      matched: [],
+      alternatives: scored.slice(0, 3).map((r) => ({ name: r.agent.name, score: r.score, matched: [...r.matched, ...r.weak] })),
+    };
+  }
+
+  const tied = scored.filter((r) => r.score === top.score);
+  const confident = tied.length === 1;
+  return {
+    agent: top.agent,
+    reason: `matched: ${[...top.matched, ...top.weak].join(", ")}`,
+    confident,
+    matched: top.matched,
+    // When tied, surface the co-leaders so the ambiguity is visible, not hidden.
+    alternatives: (confident ? scored.slice(1, 4) : tied.slice(1)).map((r) => ({ name: r.agent.name, score: r.score, matched: r.matched })),
+  };
+}
+
+export { REGISTRY };

package/src/agent.js

@@ -0,0 +1,123 @@
+// Weftens — the real agent. A Claude-driven loop where the model converses with
+// the operator and decides when to consult the two specialists, exposed as tools:
+// representation_check (Richy) and operations_summary (PIO). The deterministic
+// synthesizer stays available to the model as grounding, so numeric claims trace
+// to signals rather than generation. The SDK's tool runner drives the loop.
+
+import Anthropic from "@anthropic-ai/sdk";
+import { betaTool } from "@anthropic-ai/sdk/helpers/beta/json-schema";
+import { synthesize } from "./synthesize.js";
+
+export const WEFTENS_MODEL = "claude-opus-4-8";
+
+// Stable system prompt — kept frozen so prompt caching holds across turns.
+export const WEFTENS_SYSTEM = `You are Weftens. You help an organization's operator understand and improve two things that form one loop: how the organization LOOKS online (its representation — what a funder, partner, or customer sees when they search it) and how it RUNS (its operations — programs, events, participants, follow-ups).
+
+You have two specialists you can consult as tools:
+- representation_check — Richy, a read-only audit of the org's public website and presence lanes. Call it when the question touches how the org appears online, its website, reviews, listings, search, or reputation.
+- operations_summary — PIO, the org's operations workspace. Call it when the question touches events, participants, attendance, programs, grants, or follow-ups. It returns counts and status only — participant personal data never crosses this wire, and you must never ask for or speculate about individuals' personal details.
+
+Working rules:
+- Consult a specialist before making claims in its domain; never invent scores or counts. If a tool is unavailable or returns sample data, say so plainly — a sample is an illustration, never a finding about the real org.
+- The valuable answer usually JOINS the two domains: attention generated (events, participants) versus conversion captured (representation quality, follow-ups). When you have both sides, say what the relationship implies and give one concrete next step.
+- Speak in plain operator language. No internal jargon (tenant, scopeId, artifact, audit-envelope). Be direct and honest; if the data is thin, say what's missing rather than padding.
+- Keep answers short: the read, the one insight, the one recommendation.
+
+Voice — write like a sharp colleague, not a consultant deck:
+- Plain paragraphs. No bold section headers, no bullet-listicle formatting, no "Here's the honest read" style framing lines.
+- No coined slogans or aphorisms ("attention created, conversion leaking"). Say the plain thing instead.
+- Do not end with an offer-question ("Want me to…?"). End on the recommendation. If a follow-up genuinely needs the operator's input, ask it as a real question mid-answer, once.`;
+
+export function buildAgentTools(agents = {}) {
+  const tools = [];
+
+  if (agents.richy) {
+    tools.push(
+      betaTool({
+        name: "representation_check",
+        description:
+          "Run a read-only audit of how the organization appears online: website readiness score, top fixes, and which presence lanes (reviews, business profile, local listings, AI answers, social) are covered. Call this whenever the operator asks how the org looks, its website quality, reputation, search presence, or what a funder would see.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Organization display name" },
+            website: { type: "string", description: "The org's public website URL, if known" },
+          },
+          required: ["name"],
+          additionalProperties: false,
+        },
+        run: async (input) => JSON.stringify(await agents.richy.representationCheck(input)),
+      }),
+    );
+  }
+
+  if (agents.pio) {
+    tools.push(
+      betaTool({
+        name: "operations_summary",
+        description:
+          "Fetch the organization's operations summary from its workspace: counts of programs, events, participants, attendance, and follow-ups (sanitized — no personal data). Call this whenever the operator asks about events, attendance, participants, programs, grants, or follow-up status.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Organization display name" },
+          },
+          required: ["name"],
+          additionalProperties: false,
+        },
+        run: async (input) => JSON.stringify(await agents.pio.operationsSummary(input)),
+      }),
+    );
+  }
+
+  tools.push(
+    betaTool({
+      name: "join_domains",
+      description:
+        "Deterministically join a representation result and an operations result into a grounded cross-domain read (headline, insight, recommendation). Use it after you have BOTH a representation_check and an operations_summary for the same org, to ground your joined answer in the signals.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          representation: { type: "object", description: "The representation_check result" },
+          operations: { type: "object", description: "The operations_summary result" },
+        },
+        required: ["representation", "operations"],
+        additionalProperties: false,
+      },
+      run: async ({ representation, operations }) => JSON.stringify(synthesize({ representation, operations })),
+    }),
+  );
+
+  return tools;
+}
+
+/**
+ * One agent turn (or a continued conversation): Claude decides which specialists
+ * to consult and answers in operator language. Returns { text, messages } so a
+ * caller can hold a multi-turn conversation by passing messages back in.
+ */
+export async function askWeftens({ question, history = [], agents = {}, client = null, maxTokens = 16000 }) {
+  const anthropic = client ?? new Anthropic();
+  const messages = [...history, { role: "user", content: question }];
+
+  const runner = anthropic.beta.messages.toolRunner({
+    model: WEFTENS_MODEL,
+    max_tokens: maxTokens,
+    thinking: { type: "adaptive" },
+    system: [{ type: "text", text: WEFTENS_SYSTEM, cache_control: { type: "ephemeral" } }],
+    tools: buildAgentTools(agents),
+    messages,
+    max_iterations: 8,
+  });
+
+  const finalMessage = await runner;
+  const text = finalMessage.content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text)
+    .join("\n");
+
+  return {
+    text,
+    messages: [...messages, { role: "assistant", content: finalMessage.content }],
+  };
+}

package/src/invoke.js

@@ -0,0 +1,129 @@
+// Invoke — run one routed agent and return its result. Three paths:
+//
+//   core-in-the-loop : the agent has a deterministic agent-cores package; that code runs
+//                      on the input and produces a checkable result. No model, no key.
+//   content-pipeline : the Content lead runs the content-org pipeline as one node.
+//   model-produce    : a seat with no core produces via the model — its .md is the system
+//                      prompt, run through whichever CLI the user chose (their own
+//                      subscription, no API key). See provider.js.
+//
+// richy/pio (tier 1) are NOT invoked here — they answer through the existing orchestrator
+// (weftens.js) over their frozen wire contracts. When a step can't run (no input for a
+// core, provider CLI missing), invoke returns a plain note — it never fabricates output.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { complete } from "./provider.js";
+
+const execFileP = promisify(execFile);
+
+// One home: the cores (agent-cores/) and content-org/ live inside this repo. No sibling
+// checkout, no fallback — one canonical copy of everything. Override the base with WEFTENS_HOME.
+const REPO = process.env.WEFTENS_HOME || resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// Run a core by shelling its real CLI — the CLI already does the core's own
+// parse+analyze+format, so we don't reimplement any core logic here. Every agent-cores
+// package exposes src/cli.mjs and takes its input as a positional arg (a file path, or
+// a URL for seo-technical); the one exception, paid-search, takes --search-terms <csv>,
+// so an entry may set coreInputFlag to override the positional default.
+async function runCoreCli(agent, input) {
+  const bin = join(REPO, ...agent.core.split("/"), ...(agent.coreBin ?? "src/cli.mjs").split("/"));
+  const args = agent.coreInputFlag ? [bin, agent.coreInputFlag, input, "--pretty"] : [bin, input, "--pretty"];
+  const { stdout } = await execFileP("node", args, { maxBuffer: 8_000_000 });
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return stdout.trim();
+  }
+}
+
+// A missing file, a non-zero core exit, or a core that isn't on disk should degrade
+// to a plain note, not throw raw out of the front door — the rest of this stack
+// (richy-client, weftens) fails soft, and the router must match that.
+async function tryCore(agent, inputFile) {
+  try {
+    return { ok: true, result: await runCoreCli(agent, inputFile) };
+  } catch (error) {
+    const reason = error?.code === "ENOENT" ? "core CLI not found on disk" : (error?.stderr?.trim() || error?.message || "core failed");
+    return { ok: false, reason };
+  }
+}
+
+/**
+ * @param agent   registry entry (from route().agent)
+ * @param opts    { text?: string, inputFile?: string }
+ * @returns { agent, path, result?, note }
+ */
+export async function invoke(agent, opts = {}) {
+  if (!agent) return { agent: null, path: "none", note: "no agent to invoke" };
+
+  if (agent.tier === 1 && agent.wire) {
+    return {
+      agent: agent.name, path: "orchestrator",
+      note: `${agent.name} runs through the Weftens orchestrator over its wire contract (use the orchestrate() path); not invoked as a leaf`,
+    };
+  }
+
+  // Content lead: owns the 10-seat pipeline. Delegate to content-org/lead.js. The
+  // pipeline runs by FORMAT (scam-reveal, …) + count, chosen with --format/--count —
+  // it does not yet take a free-text brief, so a request's prose is not used to steer
+  // it. Say that plainly rather than implying the request drove the run. Defaults to
+  // dry-run: a real run is gated on the owner's open content decisions.
+  if (agent.tier === 1 && agent.leads === "content-org") {
+    const leadPath = join(REPO, "content-org", "lead.js");
+    if (!existsSync(leadPath)) {
+      return { agent: agent.name, path: "content-pipeline", note: "content pipeline not installed — clone content-org beside this repo to enable it" };
+    }
+    const mod = await import(pathToFileURL(leadPath).href);
+    const dry = opts.dry !== false; // real run only when explicitly asked
+    const out = await mod.runContent({ dry });
+    return {
+      agent: agent.name, path: "content-pipeline", result: out.result,
+      note: `ran content-org pipeline (${out.format} x${out.count}, ${dry ? "dry-run — no model, Phase-0 gated" : "live"}) — ${out.result.length} packet(s)`,
+    };
+  }
+
+  if (agent.core) {
+    // seo-technical takes a URL and live-fetches; the rest take a file path. Either
+    // arrives as opts.input. Without it, there's nothing to run — say so.
+    const input = opts.input ?? opts.inputFile;
+    if (!input) {
+      const what = agent.name === "seo-technical" ? "<url>" : "<file>";
+      return {
+        agent: agent.name, path: "core",
+        note: `deterministic core available (${agent.core}) — run with --input ${what} to execute it`,
+      };
+    }
+    const run = await tryCore(agent, input);
+    if (!run.ok) {
+      return { agent: agent.name, path: "core", note: `core ${agent.core} could not run on ${input}: ${run.reason}` };
+    }
+    return {
+      agent: agent.name, path: "core", result: run.result,
+      note: `ran ${agent.core} on ${input} — deterministic, no model`,
+    };
+  }
+
+  // model-produce path — bring-your-own-model. The seat .md is the system prompt; the
+  // request is the user turn. Run it through whichever CLI the user chose (their own
+  // subscription, no API key). Degrades to a plain note if the seat can't be read or the
+  // provider CLI isn't there — never a fabricated answer.
+  let seatText;
+  try {
+    seatText = readFileSync(agent.seatFile, "utf8");
+  } catch {
+    return { agent: agent.name, path: "model", note: `seat file not found (${agent.seatFile}); can't produce` };
+  }
+  const prompt = `${seatText}\n\n---\nRequest: ${opts.text ?? ""}`;
+  const res = await complete(prompt, { provider: opts.provider });
+  if (!res.ok) {
+    return { agent: agent.name, path: "model", note: `couldn't produce via ${res.provider}: ${res.reason}` };
+  }
+  return {
+    agent: agent.name, path: "model", result: res.text,
+    note: `produced via ${res.provider} — the user's own subscription, no API key`,
+  };
+}