@chatpanel/gateway 0.6.87 → 0.6.91

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.87",
+  "version": "0.6.91",
   "description": "Local privacy gateway \u2014 redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -0,0 +1,250 @@
+// VENDORED from @chatpanel/events/agent.js — edit there, then copy over.
+// An AGENT, as data — the pool an org recruits from. Nothing runs here.
+//
+// A team's roles were inlined: each carried its own prompt, tier and grants, so the same
+// "researcher" existed once per team and an edit landed in one of them. An agent is the role
+// definition promoted out of the team (F8 §8 A1, architecture-pillars.md §9): a persistent
+// identity — name, purpose, prompt, skills, grants, egress class, ENGINE, memory namespace —
+// with a scorecard the runner writes and the store attests (scorecard.js). One agent stands
+// in many teams; a team's role says `agent: <id>` and `resolveTeam` fills the role from the
+// pool at run time, so the runner (team-run.js) is unchanged.
+//
+// The engine is a field on the card, never a nav item: `model` / `harness` / `auto` /
+// `assistant` (engine.js). The built-in ASSISTANT is the agent behind every plain chat: its
+// engine is whichever model the chat is on, which is why `engineOf` takes the chat's model.
+//
+// Trust is derived, never declared (the team.js rule): `builtin` only when the host says so.
+// Grants are the team's vocabulary (team.js GRANT_RE), including the work grants a harness
+// engine may hold; `page` is never grantable. The pool is shared through the client-prefs
+// document (`agents` section) like teams, skills and recipes.
+
+import { normalizeGrants, GRANT_RE, TeamError, normalizeTeam, slugTeamName } from './team.js';
+import { normalizeEngineSpec, validateEngineSpec, describeEngine, engineRef, tierOf } from './engine.js';
+
+export const AGENT_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+export const APPLIES_TO = Object.freeze(['jobs', 'meetings', 'notes']);
+export const EGRESS_CLASSES = Object.freeze(['redacted', 'delegated']);
+export const MAX_SKILLS = 32;
+export const ASSISTANT_ID = 'assistant';
+
+export class AgentError extends Error {
+  constructor(code, message) { super(message); this.name = 'AgentError'; this.code = code; }
+}
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const list = (xs, n, max) => [...new Set((Array.isArray(xs) ? xs : typeof xs === 'string' ? xs.split(/[,\s]+/) : []).map((x) => String(x || '').trim().slice(0, n)).filter(Boolean))].slice(0, max);
+
+export function validateAgent(agent) {
+  const errors = [];
+  if (!isRecord(agent)) return { ok: false, errors: ['agent must be an object'] };
+  if (!AGENT_ID_RE.test(String(agent.id || ''))) errors.push('id: a short identifier (letters, digits, _ -)');
+  if (!String(agent.name || agent.id || '').trim()) errors.push('name: what to call it');
+  if (!String(agent.prompt || '').trim() && String(agent.id) !== ASSISTANT_ID) errors.push('prompt: what this agent does');
+  errors.push(...validateEngineSpec(agent.engine, 'engine'));
+  const bad = (Array.isArray(agent.grants) ? agent.grants : []).filter((g) => !GRANT_RE.test(String(g)));
+  if (bad.length) errors.push(`grants: not grantable: ${bad.join(', ')}${bad.some((g) => /^page/.test(String(g))) ? ' (a tab is one person\'s; an agent may not act on it)' : ''}`);
+  if (agent.egress !== undefined && agent.egress !== null && !EGRESS_CLASSES.includes(agent.egress)) errors.push(`egress: one of ${EGRESS_CLASSES.join(', ')}`);
+  if (agent.appliesTo !== undefined && (!Array.isArray(agent.appliesTo) || agent.appliesTo.some((a) => !APPLIES_TO.includes(a)))) errors.push(`appliesTo: a list of ${APPLIES_TO.join(', ')}`);
+  if (agent.skills !== undefined && !Array.isArray(agent.skills) && typeof agent.skills !== 'string') errors.push('skills: a list of skill names');
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * The stored form. Defaults filled, grants normalized, engine normalized, trust derived. The
+ * memory namespace defaults to the agent's own (`agent:<id>`); a team may point several
+ * agents at one shared namespace by naming it.
+ */
+export function normalizeAgent(agent, { builtin = false } = {}) {
+  const v = validateAgent(agent);
+  if (!v.ok) throw new AgentError('INVALID', v.errors.join('; '));
+  const id = String(agent.id);
+  return {
+    id,
+    name: String(agent.name || id).trim().slice(0, 60),
+    purpose: String(agent.purpose || '').trim().slice(0, 300),
+    prompt: String(agent.prompt || '').trim().slice(0, 8000),
+    skills: list(agent.skills, 80, MAX_SKILLS),
+    grants: normalizeGrants(agent.grants),
+    engine: normalizeEngineSpec(agent.engine),
+    ...(EGRESS_CLASSES.includes(agent.egress) ? { egress: agent.egress } : {}),
+    appliesTo: Array.isArray(agent.appliesTo) && agent.appliesTo.length ? [...new Set(agent.appliesTo.filter((a) => APPLIES_TO.includes(a)))] : ['jobs'],
+    memoryScope: String(agent.memoryScope || '').trim().slice(0, 120) || `agent:${id}`,
+    ...(agent.workdir ? { workdir: String(agent.workdir).trim().slice(0, 400) } : {}),
+    createdBy: String(agent.createdBy || 'person').slice(0, 80),
+    enabled: agent.enabled !== false,
+    ...(agent.origin && isRecord(agent.origin) ? { origin: { ...agent.origin } } : {}),
+    ...(builtin ? { builtin: true } : {}),
+    ...(agent.createdAt ? { createdAt: agent.createdAt } : {}),
+  };
+}
+
+export function defineAgent(agent, opts) { return Object.freeze(normalizeAgent(agent, opts)); }
+
+/**
+ * The built-in Assistant — the agent behind every plain chat. Its engine is the chat's model
+ * (`engineOf` resolves it); its grants are whatever the chat has; it applies everywhere.
+ */
+export function assistantAgent({ grants = ['data', 'web', 'history', 'mcp'] } = {}) {
+  return defineAgent({
+    id: ASSISTANT_ID, name: 'Assistant', purpose: 'The chat itself: answers, uses the tools you connected, remembers what you tell it.',
+    prompt: '', engine: 'assistant', grants, appliesTo: ['jobs', 'meetings', 'notes'], createdBy: 'chatpanel',
+  }, { builtin: true });
+}
+
+/**
+ * WHAT RUNS this agent's turns, resolved: the Assistant's engine is the chat's model (the
+ * host passes `chatModel` as `{ providerId?, model }` or a string), which is why the
+ * Assistant has no engine of its own. Everything else returns its normalized spec. A legacy
+ * role (no `engine`) reads as `model` when it pins one, else `auto` at its tier.
+ */
+export function engineOf(agentOrRole, { chatModel = null } = {}) {
+  const a = agentOrRole || {};
+  if (a.engine !== undefined && a.engine !== null) {
+    const s = normalizeEngineSpec(a.engine);
+    if (s.kind !== 'assistant') return s;
+    if (chatModel) return normalizeEngineSpec(typeof chatModel === 'string' ? chatModel : { kind: 'model', providerId: chatModel.providerId, model: chatModel.model || chatModel.id });
+    return { kind: 'auto', policy: { prefer: 'balanced' } };
+  }
+  if (a.model) return normalizeEngineSpec({ kind: 'model', model: a.model });
+  const prefer = { cheap: 'cheapest-that-clears', strong: 'best-quality', balanced: 'balanced' }[a.prefer] || 'balanced';
+  return { kind: 'auto', policy: { prefer } };
+}
+
+/** The capability strip's first column (§8): what kind of thing this agent is, in a word. */
+export function describeAgent(agent, opts) {
+  const a = agent || {};
+  return `${a.name || a.id} — ${describeEngine(a.engine, opts)} · tools: ${(a.grants || ['none']).join(', ')}${a.skills?.length ? ` · skills: ${a.skills.join(', ')}` : ''}`;
+}
+
+export function slugAgentId(name) { return slugTeamName(name); }
+
+/**
+ * A team as the runner needs it: every role that says `agent` is filled from the pool —
+ * prompt, grants, skills, engine, working directory — and the role's own fields narrow it.
+ *
+ *   • prompt   the agent's, then the role's ("In this team: …") when the role adds one
+ *   • grants   the agent's, narrowed to the role's when the role lists any (a team may not
+ *              widen an agent; it may lend less)
+ *   • engine   the role's override when it has one, else the agent's, with the Assistant
+ *              resolved to `chatModel`; `prefer` follows for today's appointers
+ *   • model    what `callModel` is handed — `targetFor(engine)` when the host maps engines
+ *              to its target ids (the extension's endpoint ids, the desktop's gateway ids),
+ *              else the harness id or the model name
+ *
+ * A role naming an agent not in the pool throws NO_AGENT: a team is not run with a hole in
+ * it. Returns the normalized team plus `agents` — the resolved cards, by role id.
+ */
+export function resolveTeam(team, pool = [], { chatModel = null, targetFor = null } = {}) {
+  const t = normalizeTeam(team);
+  const byId = new Map((Array.isArray(pool) ? pool : []).filter((a) => a && a.id).map((a) => [String(a.id), a]));
+  const agents = {};
+  const roles = t.roles.map((r) => {
+    if (!r.agent) return r;
+    const raw = byId.get(r.agent) || (r.agent === ASSISTANT_ID ? assistantAgent() : null);
+    if (!raw) throw new TeamError('NO_AGENT', `role "${r.id}" names agent "${r.agent}", which is not in the pool`);
+    const a = normalizeAgent(raw, { builtin: !!raw.builtin });
+    if (a.enabled === false) throw new TeamError('NO_AGENT', `agent "${a.id}" is disabled`);
+    agents[r.id] = a;
+    const engine = engineOf(r.engine ? { engine: r.engine } : a, { chatModel });
+    const ref = engineRef(engine);
+    const target = ref ? (targetFor ? targetFor(engine, a) : (engine.kind === 'harness' ? engine.harnessId : engine.model)) : null;
+    const grants = !Array.isArray(r.grants) ? a.grants
+      : a.grants.includes('none') ? ['none']
+        : normalizeGrants(r.grants.filter((g) => a.grants.includes(g) || (g.startsWith('mcp:') && a.grants.includes('mcp'))));
+    const prompt = [a.prompt, r.prompt ? `In this team: ${r.prompt}` : ''].filter(Boolean).join('\n\n').slice(0, 8000);
+    return {
+      ...r,
+      name: r.name === r.id ? a.name : r.name,
+      prompt,
+      grants,
+      engine,
+      prefer: engine.kind === 'auto' ? tierOf(engine) : r.prefer,
+      ...(target ? { model: r.model || target } : {}),
+      ...(a.skills.length ? { skills: [...a.skills] } : {}),
+      ...(a.workdir ? { workdir: a.workdir } : {}),
+      ...(a.egress ? { egress: a.egress } : {}),
+      ...(a.memoryScope ? { memoryScope: a.memoryScope } : {}),
+    };
+  });
+  return { ...t, roles, agents };
+}
+
+// ── The standing org and the editor's form ────────────────────────────────────────────────
+//
+// "ChatPanel Engineering" (architecture-pillars.md §12.2) — the first standing agents,
+// offered as starters the way `research` and `review` are for teams. Every Implementer is
+// this ONE card with a different working directory: the org repo's `agents/*.json` (§14.3)
+// is where a company keeps one per repo. Engines are `auto` / `harness:<id>` so a starter
+// does not name a provider a person may not have; the Harness engines say `claude` because
+// that is the bridge's id for Claude Code and the pilot's choice — change it on the card.
+
+export const STARTER_AGENTS = Object.freeze([
+  { id: 'architect', name: 'Architect', purpose: 'Reads the docs and the repos; writes the project page and the jobs.',
+    prompt: 'You are the Architect. Read the feature doc, ROADMAP.md, naming-revamp.md and architecture-pillars.md before deciding anything. Write the project page (goal, done-when, budget) and post one job per repo that must change, saying which repo and what the guard is. Propose a new agent type only when no one in the pool fits. Never run a shell.',
+    skills: [], grants: ['data', 'history'], engine: { kind: 'auto', policy: { prefer: 'best-quality' } }, appliesTo: ['jobs'] },
+  { id: 'implementer', name: 'Implementer', purpose: 'Builds one job on a branch in one repo; runs the guard; posts on the thread. Never pushes to main, never publishes.',
+    prompt: 'You are an Implementer. Work only in the repository you were given, on the branch named for this job. Read the job thread first. Make the change, run the repository\'s guard (tools/test-*.mjs or npm test) until it passes, commit with a message that says what and why, and post a summary with the diff stat on the job thread. Do not push to main, do not publish, do not touch another repository.',
+    skills: [], grants: ['shell', 'fs:write', 'scm:read', 'scm:push', 'scm:pr'], engine: { kind: 'harness', harnessId: 'claude' }, appliesTo: ['jobs'] },
+  { id: 'reviewer', name: 'Reviewer', purpose: 'Reads the branch diff; posts findings on the thread. Approve or reject is a person\'s.',
+    prompt: 'You are the Reviewer. Read the diff of the job\'s branch against its base. Post each finding as a reply on the job thread: what, where (file:line), why it matters, what to do instead. Do not edit files. Do not approve or reject — say what you found and let a person decide.',
+    skills: ['review'], grants: ['shell', 'scm:read'], engine: { kind: 'harness', harnessId: 'claude' }, appliesTo: ['jobs'] },
+  { id: 'tester', name: 'Tester', purpose: 'Runs the repository\'s guard on the branch; reports the result. No writes.',
+    prompt: 'You are the Tester. Check out the job\'s branch in its worktree and run the repository\'s guard (tools/test-*.mjs, npm test, the build). Report pass/fail with the failing output verbatim. Do not change any file.',
+    skills: [], grants: ['shell', 'scm:read'], engine: { kind: 'harness', harnessId: 'claude' }, appliesTo: ['jobs'] },
+  { id: 'librarian', name: 'Librarian', purpose: 'Before every job: what was already done for this, and where.',
+    prompt: 'You are the Librarian. Before a job starts, search the runs, boards, briefs and docs for work that already covers it. Reply on the job thread with "already done in …" pointers and what could be reused or extended. Never do the job yourself.',
+    skills: [], grants: ['data', 'history'], engine: { kind: 'auto', policy: { prefer: 'cheapest-that-clears' } }, appliesTo: ['jobs'] },
+  { id: 'scribe', name: 'Scribe', purpose: 'Writes what the run taught into the roadmap and the status row — proposed, a person lands it.',
+    prompt: 'You are the Scribe. From the run\'s board and scorecards, write the "what this run taught" paragraph for the feature doc, the ROADMAP.md entry and the IMPLEMENTATION-STATUS.md row. Post them as a proposal on the thread; a person lands them. Say plainly what did not work.',
+    skills: [], grants: ['data', 'history'], engine: { kind: 'auto', policy: { prefer: 'balanced' } }, appliesTo: ['jobs', 'notes'] },
+  { id: 'release', name: 'Release', purpose: 'Version bump and changelog on the merged branch; asks before publish or push.',
+    prompt: 'You are Release. On the merged branch: bump the version, write the changelog line, run the guard. Before `npm publish` or any `git push`, stop and ask on the thread — a person answers. Never publish or push without that answer.',
+    skills: [], grants: ['shell', 'fs:write', 'scm:read', 'scm:push'], engine: { kind: 'harness', harnessId: 'claude' }, appliesTo: ['jobs'] },
+]);
+
+/** Fresh copies — a starter is a template, never the stored record. */
+export function starterAgents() {
+  return STARTER_AGENTS.map((a) => JSON.parse(JSON.stringify(a)));
+}
+
+/** A blank agent for the editor. */
+export function blankAgent() {
+  return { id: '', name: '', purpose: '', prompt: '', skills: [], grants: ['none'], engine: { kind: 'auto', policy: { prefer: 'balanced' } }, appliesTo: ['jobs'], memoryScope: '' };
+}
+
+/**
+ * The editor's form → an agent, or the errors. Grants and skills come as text ("web, data",
+ * "review, graphify"); the engine as the form's own shape (`{ kind, model, providerId,
+ * harnessId, prefer }`) or a string; a blank id is slugged from the name.
+ */
+export function agentFromForm(form) {
+  const f = form || {};
+  const id = String(f.id || '').trim() || slugAgentId(f.name);
+  const engine = isRecord(f.engine)
+    ? (f.engine.kind === 'auto' ? { kind: 'auto', policy: { prefer: f.engine.prefer || f.engine.policy?.prefer || 'balanced', ...(f.engine.policy || {}) } } : f.engine)
+    : f.engine;
+  const agent = {
+    id,
+    name: String(f.name || '').trim() || id,
+    purpose: String(f.purpose || '').trim(),
+    prompt: String(f.prompt || ''),
+    skills: list(f.skills, 80, MAX_SKILLS),
+    grants: list(f.grants, 80, 32).length ? list(f.grants, 80, 32) : ['none'],
+    engine,
+    ...(f.egress ? { egress: f.egress } : {}),
+    appliesTo: Array.isArray(f.appliesTo) && f.appliesTo.length ? f.appliesTo : ['jobs'],
+    ...(f.memoryScope ? { memoryScope: f.memoryScope } : {}),
+    ...(f.workdir ? { workdir: f.workdir } : {}),
+    createdBy: f.createdBy || 'person',
+    enabled: f.enabled !== false,
+    ...(f.origin && isRecord(f.origin) ? { origin: f.origin } : {}),
+    ...(f.createdAt ? { createdAt: f.createdAt } : {}),
+  };
+  const v = validateAgent(agent);
+  return v.ok ? { ok: true, agent: normalizeAgent(agent) } : { ok: false, errors: v.errors };
+}
+
+/** Which agents apply to jobs — the pool a job board recruits from. */
+export function poolFor(agents, surface = 'jobs') {
+  return (Array.isArray(agents) ? agents : []).filter((a) => a && a.enabled !== false && (Array.isArray(a.appliesTo) ? a.appliesTo : ['jobs']).includes(surface));
+}

package/src/budget.js

@@ -0,0 +1,117 @@
+// VENDORED from @chatpanel/events/budget.js — edit there, then copy over.
+// A budget — the number a run may not exceed, and the record of what it spent.
+//
+// There was no spend cap anywhere. A live monitor is declared class C and starts model turns
+// for the length of a meeting; a spoken "keep an eye on X" arms that with nothing bounding
+// it; `jobs.js` caps a per-day job COUNT, not spend. The class declarations on every intent
+// and rule were made for exactly this, and nothing read them.
+//
+// A budget is a VALUE: declared on the thing that spends (a team, a schedule, a monitor),
+// charged by whatever runs it, and carried on the run record so the ledger can say what a
+// run cost in the same units it was capped in. Four dimensions, because the expensive thing
+// differs by executor: tokens and calls for a model, wall time for an agent that thinks for
+// minutes, cost when the gateway can report it. Any dimension may be absent; an absent one is
+// not enforced. A budget with NO dimension is not a budget — `validateBudget` refuses it, and
+// a team without one does not run (F8, O1).
+//
+// Pure. `now` is injected so a wall-time cap is testable.
+
+export const BUDGET_DIMENSIONS = Object.freeze(['tokens', 'calls', 'ms', 'usd']);
+
+export class BudgetError extends Error {
+  constructor(code, message) { super(message); this.name = 'BudgetError'; this.code = code; }
+}
+
+/** `{ ok, errors }` — a budget must cap at least one thing, and every cap must be a positive number. */
+export function validateBudget(b) {
+  const errors = [];
+  if (!b || typeof b !== 'object') return { ok: false, errors: ['budget must be an object'] };
+  let any = false;
+  for (const k of BUDGET_DIMENSIONS) {
+    if (b[k] === undefined || b[k] === null) continue;
+    const n = Number(b[k]);
+    if (!Number.isFinite(n) || n <= 0) errors.push(`${k}: a positive number`);
+    else any = true;
+  }
+  for (const k of Object.keys(b)) if (!BUDGET_DIMENSIONS.includes(k)) errors.push(`${k}: not a budget dimension (${BUDGET_DIMENSIONS.join(', ')})`);
+  if (!any) errors.push('a budget must cap at least one of tokens, calls, ms, usd');
+  return { ok: errors.length === 0, errors };
+}
+
+/** Only the declared dimensions, as numbers. */
+export function normalizeBudget(b) {
+  const out = {};
+  for (const k of BUDGET_DIMENSIONS) {
+    const n = Number(b?.[k]);
+    if (Number.isFinite(n) && n > 0) out[k] = n;
+  }
+  return out;
+}
+
+/**
+ * The usage a model call reports, in the shapes the providers use, as one record:
+ * `{ tokens, calls, usd }`. `ms` is measured by the budget itself.
+ */
+export function usageOf(u = {}) {
+  const tokens = Number(u.tokens ?? u.total_tokens ?? ((Number(u.input_tokens ?? u.prompt_tokens) || 0) + (Number(u.output_tokens ?? u.completion_tokens) || 0)));
+  return { tokens: Number.isFinite(tokens) ? tokens : 0, calls: Number(u.calls ?? 1) || 0, usd: Number(u.usd ?? u.cost) || 0 };
+}
+
+/**
+ * A live budget for one run.
+ *
+ *   charge(usage)        add a model call's usage; returns what is left
+ *   canAfford(estimate)  false when an estimated call would cross a cap — ask BEFORE calling
+ *   exhausted()          the dimension that ran out, or null
+ *   snapshot()           { cap, spent, remaining, exhausted } for the run record and the meter
+ */
+export function createBudget(declared, { now = () => Date.now() } = {}) {
+  const v = validateBudget(declared);
+  if (!v.ok) throw new BudgetError('INVALID', v.errors.join('; '));
+  const cap = { ...normalizeBudget(declared) };
+  const startedAt = now();
+  const spent = { tokens: 0, calls: 0, usd: 0 };
+  const elapsed = () => now() - startedAt;
+  const remaining = () => {
+    const out = {};
+    for (const k of BUDGET_DIMENSIONS) {
+      if (cap[k] === undefined) continue;
+      out[k] = Math.max(0, cap[k] - (k === 'ms' ? elapsed() : spent[k]));
+    }
+    return out;
+  };
+  const exhausted = () => {
+    for (const k of BUDGET_DIMENSIONS) {
+      if (cap[k] === undefined) continue;
+      if ((k === 'ms' ? elapsed() : spent[k]) >= cap[k]) return k;
+    }
+    return null;
+  };
+  return {
+    cap,
+    charge(usage) {
+      const u = usageOf(usage);
+      spent.tokens += u.tokens; spent.calls += u.calls; spent.usd += u.usd;
+      return remaining();
+    },
+    canAfford(estimate = {}) {
+      if (exhausted()) return false;
+      const e = usageOf({ calls: 1, ...estimate });
+      for (const k of ['tokens', 'calls', 'usd']) {
+        if (cap[k] !== undefined && spent[k] + e[k] > cap[k]) return false;
+      }
+      return true;
+    },
+    remaining,
+    exhausted,
+    /** A person raised the cap mid-run (a budget ask answered "allow"): by a factor, once. */
+    raise(factor = 1.5) {
+      const f = Math.max(1, Number(factor) || 1);
+      for (const k of Object.keys(cap)) if (cap[k] !== undefined) cap[k] = Math.ceil(cap[k] * f);
+      return { ...cap };
+    },
+    snapshot() {
+      return { cap, spent: { ...spent, ms: elapsed() }, remaining: remaining(), exhausted: exhausted() };
+    },
+  };
+}

package/src/engine-ledger-store.js

@@ -0,0 +1,150 @@
+// The engines' ledgers — every fact the runner and a host observed about a MODEL or a
+// HARNESS, chained and attested here (model-ledger.js), one chain per engine key.
+//
+// The scorecard store's twin. A scorecard says what an AGENT did; a ledger says how an
+// ENGINE behaved while doing it — did it answer, how fast, how much, was the JSON valid, was
+// the verdict good. The facts come from the run store's fold (a finished task is a `call`,
+// a re-appointment is a `declined` on the engine that was left, a hand-off a
+// `rotated-from`), from a host that timed its own chat calls (`POST /v1/engines/:key/entries`),
+// and from a person (a rating on a task lands on the engine that served it; a price they
+// typed). Nothing is ever edited. The same store key attests both stores, under its own
+// label, so a scorecard's mark cannot be replayed as a ledger's.
+//
+// Read: `GET /v1/engines` (every card), `GET /v1/engines/:key/card` (the card, the chain
+// on request, whether it verifies). The card is what a client feeds `applyCard` — observed
+// quality, latency and cost over the name-based guess once there is enough history.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import os from 'node:os';
+import { createHmac, webcrypto } from 'node:crypto';
+import { makeLedgerEntry, verifyChain, attest, verifyAttested, summarizeEngine, ledgerKey, LEDGER_ENTRY_KINDS, DECLINE_REASONS } from './model-ledger.js';
+import { normalizeEngine } from './scorecard.js';
+
+const DIR = join(os.homedir(), '.chatpanel');
+const STORE_PATH = process.env.CHATPANEL_ENGINES_STORE || join(DIR, 'engines.json');
+const MAX_ENTRIES_PER_ENGINE = 20000;
+
+/** Why an engine declined, read from the error the runner recorded. */
+export function declineReasonOf(error) {
+  const m = String(error || '');
+  if (/rate|429|overloaded|capacity|too many/i.test(m)) return 'rate';
+  if (/401|403|unauthori[sz]ed|no api key|invalid.*key|forbidden|not configured/i.test(m)) return 'auth';
+  if (/credit|quota|billing|insufficient|402/i.test(m)) return 'credits';
+  if (/timed? ?out|ETIMEDOUT|deadline/i.test(m)) return 'timeout';
+  if (/context|too long|maximum.*tokens|token limit/i.test(m)) return 'context';
+  if (/not[_ ]found|404|not deployed|unavailable|does not exist|unknown model|ECONNREFUSED|could ?n.t reach|closed the connection|exited|502|503|500/i.test(m)) return 'unavailable';
+  return 'other';
+}
+
+export class EngineLedgerStore {
+  constructor({ storePath = STORE_PATH, key = null, now = () => Date.now() } = {}) {
+    this.path = storePath;
+    this.now = now;
+    this._mark = key ? createHmac('sha256', key).update('chatpanel:engine-ledger:attest:v1').digest() : null;
+    this.chains = new Map(); // key -> [entries]
+    this._routed = new Map(); // `${runId}/${taskId}` -> the engine last routed to (for declines and rotations)
+    this._queue = Promise.resolve();
+  }
+  load() {
+    try {
+      if (existsSync(this.path)) {
+        const doc = JSON.parse(readFileSync(this.path, 'utf8'));
+        for (const [k, entries] of Object.entries(doc?.chains || {})) if (Array.isArray(entries)) this.chains.set(k, entries);
+      }
+    } catch { this.chains = new Map(); }
+    return this;
+  }
+  save() {
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    const tmp = `${this.path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ v: 1, chains: Object.fromEntries(this.chains) }), { mode: 0o600 });
+    renameSync(tmp, this.path);
+  }
+  /** Append one fact to an engine's chain: made, chained, attested, saved. Serialised per store. */
+  append(fact) {
+    const run = async () => {
+      const engine = normalizeEngine(fact?.engine);
+      if (!engine) throw new Error('model-ledger: engine required');
+      if (!LEDGER_ENTRY_KINDS.includes(fact?.kind)) throw new Error(`model-ledger: kind must be one of ${LEDGER_ENTRY_KINDS.join(', ')}`);
+      const key = ledgerKey(engine);
+      const chain = this.chains.get(key) || [];
+      if (chain.length >= MAX_ENTRIES_PER_ENGINE) throw new Error('model-ledger: chain is full');
+      let entry = await makeLedgerEntry({ ...fact, engine, at: fact.at || this.now() }, chain.at(-1) || null, { now: this.now, subtle: webcrypto.subtle });
+      if (this._mark) entry = await attest(entry, this._mark, { subtle: webcrypto.subtle });
+      chain.push(entry);
+      this.chains.set(key, chain);
+      this.save();
+      return entry;
+    };
+    const p = this._queue.then(run, run);
+    this._queue = p.catch(() => {});
+    return p;
+  }
+  /** The card, and on request the chain and whether it verifies. */
+  async get(key, { entries = false, minCalls, now } = {}) {
+    const chain = this.chains.get(String(key || '')) || [];
+    const out = { key: String(key || ''), card: summarizeEngine(chain, { minCalls, now: now || this.now() }) };
+    if (entries) {
+      out.entries = chain;
+      out.verified = await verifyChain(chain, { subtle: webcrypto.subtle });
+      out.attested = this._mark ? await verifyAttested(chain, this._mark, { subtle: webcrypto.subtle }) : { ok: false, attested: 0, of: chain.length };
+    }
+    return out;
+  }
+  /** Every engine's card, without the chains. */
+  list({ minCalls, now } = {}) {
+    return [...this.chains.entries()].map(([key, chain]) => summarizeEngine(chain, { minCalls, now: now || this.now() })).filter((c) => c.key);
+  }
+  /**
+   * A run store event, as the fold sees it. `task.routed` is remembered per task; a later
+   * `task.reappointed` is a decline on what was routed before it, `task.handoff` a rotation,
+   * and `task.scored` the call itself (the harness's or the model's whole task).
+   */
+  fromRunEvent(ev, run) {
+    const type = String(ev?.type || '');
+    const p = ev?.payload && typeof ev.payload === 'object' ? ev.payload : {};
+    const runId = run?.id || p.runId || '';
+    const slot = `${runId}/${p.taskId || ''}`;
+    if (type === 'task.routed') {
+      const engine = normalizeEngine(p.engine);
+      if (engine) this._routed.set(slot, engine);
+      return null;
+    }
+    if (type === 'task.reappointed' || type === 'task.handoff') {
+      const from = this._routed.get(slot);
+      if (!from) return null;
+      const fact = type === 'task.reappointed'
+        ? { engine: from, kind: 'declined', at: ev.at, runId, taskId: p.taskId, declined: { reason: declineReasonOf(p.error), error: p.error } }
+        : { engine: from, kind: 'rotated-from', at: ev.at, runId, taskId: p.taskId, rotated: { to: p.to ? { id: p.to } : undefined, reason: p.reason || `handed off by ${p.by || 'a person'}` } };
+      return this.append(fact).catch(() => null);
+    }
+    if (type === 'task.scored') {
+      const engine = normalizeEngine(p.engine);
+      if (!engine) return null;
+      const ok = p.outcome !== 'task.failed';
+      return this.append({
+        engine, kind: 'call', at: ev.at, runId, taskId: p.taskId, agentId: p.agentId,
+        call: { ok, totalMs: p.size?.ms, tokens: p.size?.tokens || undefined, empty: !ok && /no answer|did not answer|returned nothing|empty/i.test(String(p.error || '')) },
+        refs: p.refs,
+      }).catch(() => null);
+    }
+    return null;
+  }
+  /**
+   * A rating a person gave an AGENT'S task (scorecard-store.js) lands on the engine that
+   * served it too: `chain` is the agent's scorecard, `entry` the rating just appended.
+   */
+  fromRating(chain, entry) {
+    if (!entry?.rating || !Array.isArray(chain)) return null;
+    const r = entry.rating;
+    const task = r.about != null ? chain.find((e) => e.seq === r.about)
+      : entry.taskId ? chain.find((e) => (e.kind === 'task.done' || e.kind === 'task.failed') && e.taskId === entry.taskId && (!entry.runId || e.runId === entry.runId))
+        : entry.runId ? (() => { const xs = chain.filter((e) => (e.kind === 'task.done' || e.kind === 'task.failed') && e.runId === entry.runId); return xs.length === 1 ? xs[0] : null; })() : null;
+    if (!task?.engine) return null;
+    return this.append({ engine: task.engine, kind: 'rating', at: entry.at, runId: task.runId, taskId: task.taskId, agentId: entry.agentId, rating: { by: r.by, score: r.score, jobKind: entry.jobKind, agentId: entry.agentId } }).catch(() => null);
+  }
+}
+
+export function createEngineLedgerStore(opts) { return new EngineLedgerStore(opts).load(); }
+export { DECLINE_REASONS };