@chatpanel/gateway 0.6.87 → 0.6.91

package/src/engine.js

@@ -0,0 +1,132 @@
+// VENDORED from @chatpanel/events/engine.js — edit there, then copy over.
+// An ENGINE — what actually runs an agent's turns — as a declaration, and its one-line label.
+//
+// The model is a variable, not a constant (architecture-pillars.md §13). An agent card names
+// the engine it runs on, and there are four ways to say it:
+//
+//   { kind: 'model',     providerId?, model }   an endpoint the client calls; `providerId` is
+//                                               the endpoint / gateway destination, because the
+//                                               same model at two providers is two engines
+//   { kind: 'harness',   harnessId, model? }    a CLI coding agent the bridge runs (Claude
+//                                               Code, Codex, …) — ChatPanel delegates a whole
+//                                               task to it; `model` is what it was asked to run
+//   { kind: 'auto',      policy }               the recruiter picks, by policy, from the
+//                                               engine cards (§13.4) — the default
+//   { kind: 'assistant' }                       the built-in Assistant: whatever model the chat
+//                                               is on right now (`engineOf` resolves it)
+//
+// The RECORD keeps a flatter shape — `{ kind: 'model'|'harness', id, model? }`, see
+// scorecard.js `normalizeEngine` — because a record says what DID run, and `auto` and
+// `assistant` never run anything themselves. `engineRef` maps a spec to that shape once a
+// choice was made, so the scorecard's `byEngine` and the model ledger key the same way.
+//
+// Pure, dependency-free; team.js and agent.js both import from here, never from each other.
+
+export const ENGINE_KINDS = Object.freeze(['model', 'harness', 'auto', 'assistant']);
+export const ROUTE_PREFERS = Object.freeze(['cheapest-that-clears', 'best-quality', 'fastest', 'balanced']);
+export const HARNESS_ID_RE = /^[a-zA-Z0-9_.:@+-]{1,120}$/;
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const str = (v, n = 200) => (v == null || v === '' ? undefined : String(v).trim().slice(0, n) || undefined);
+const num = (v) => { const n = Number(v); return v === '' || v == null || !Number.isFinite(n) ? undefined : n; };
+const refs = (xs) => (Array.isArray(xs) ? [...new Set(xs.map((x) => str(typeof x === 'string' ? x : engineKeyOf(x), 200)).filter(Boolean))] : undefined);
+
+/** A routing policy, normalized: an unknown preference is `balanced`; floors and ceilings are numbers or absent. */
+export function normalizePolicy(p) {
+  const src = isRecord(p) ? p : {};
+  const floor = {}; const ceiling = {};
+  const q = num(src.floor?.quality); if (q !== undefined) floor.quality = Math.max(0, Math.min(1, q));
+  const av = num(src.floor?.availability); if (av !== undefined) floor.availability = Math.max(0, Math.min(1, av));
+  const c = num(src.ceiling?.costPerTask); if (c !== undefined && c >= 0) ceiling.costPerTask = c;
+  const l = num(src.ceiling?.latencyMs); if (l !== undefined && l >= 0) ceiling.latencyMs = Math.round(l);
+  const allow = refs(src.allow); const deny = refs(src.deny);
+  return {
+    prefer: ROUTE_PREFERS.includes(src.prefer) ? src.prefer : 'balanced',
+    ...(Object.keys(floor).length ? { floor } : {}),
+    ...(Object.keys(ceiling).length ? { ceiling } : {}),
+    ...(allow?.length ? { allow } : {}),
+    ...(deny?.length ? { deny } : {}),
+  };
+}
+
+/**
+ * An engine spec as stored. A string is read the obvious way — `assistant`, `auto`, a
+ * `harness:<id>` / `model:<id>` prefix, or a bare model id — because a person types these
+ * and a model proposes them in prose. Anything unreadable is `auto`, the honest default.
+ */
+export function normalizeEngineSpec(e) {
+  if (e == null || e === '') return { kind: 'auto', policy: normalizePolicy() };
+  if (typeof e === 'string') {
+    const s = e.trim();
+    if (s === 'assistant' || s === 'auto') return s === 'assistant' ? { kind: 'assistant' } : { kind: 'auto', policy: normalizePolicy() };
+    const m = /^(model|harness):(.+)$/.exec(s);
+    if (m) return m[1] === 'harness' ? { kind: 'harness', harnessId: m[2].trim() } : { kind: 'model', model: m[2].trim() };
+    return { kind: 'model', model: s };
+  }
+  if (!isRecord(e)) return { kind: 'auto', policy: normalizePolicy() };
+  const kind = ENGINE_KINDS.includes(e.kind) ? e.kind : (e.harnessId ? 'harness' : e.model ? 'model' : e.policy ? 'auto' : 'auto');
+  if (kind === 'assistant') return { kind };
+  if (kind === 'auto') return { kind, policy: normalizePolicy(e.policy) };
+  if (kind === 'harness') {
+    const harnessId = str(e.harnessId || e.id, 120);
+    if (!harnessId) return { kind: 'auto', policy: normalizePolicy() };
+    const model = str(e.model, 200);
+    return { kind, harnessId, ...(model ? { model } : {}) };
+  }
+  const model = str(e.model || e.id, 200);
+  if (!model) return { kind: 'auto', policy: normalizePolicy() };
+  const providerId = str(e.providerId || e.destination || e.endpointId, 120);
+  return { kind: 'model', ...(providerId ? { providerId } : {}), model };
+}
+
+/** Is this a spec a validator should accept? Returns the errors, with a prefix. */
+export function validateEngineSpec(e, where = 'engine') {
+  const errors = [];
+  if (e == null || e === '') return errors;
+  if (typeof e === 'string') return errors; // every string reads as something
+  if (!isRecord(e)) return [`${where}: a string or an object`];
+  if (e.kind !== undefined && !ENGINE_KINDS.includes(e.kind)) errors.push(`${where}.kind: one of ${ENGINE_KINDS.join(', ')}`);
+  if (e.kind === 'harness' && !str(e.harnessId || e.id)) errors.push(`${where}.harnessId: which harness`);
+  if (e.kind === 'harness' && str(e.harnessId || e.id) && !HARNESS_ID_RE.test(String(e.harnessId || e.id).trim())) errors.push(`${where}.harnessId: a short identifier`);
+  if (e.kind === 'model' && !str(e.model || e.id)) errors.push(`${where}.model: which model`);
+  if (e.kind === 'auto' && e.policy !== undefined && !isRecord(e.policy)) errors.push(`${where}.policy: an object`);
+  if (e.kind === 'auto' && isRecord(e.policy) && e.policy.prefer !== undefined && !ROUTE_PREFERS.includes(e.policy.prefer)) errors.push(`${where}.policy.prefer: one of ${ROUTE_PREFERS.join(', ')}`);
+  return errors;
+}
+
+/**
+ * The record's shape for a spec that names something concrete — `{ kind, id, model? }`,
+ * the same fields scorecard.js keys `byEngine` on and the model ledger is keyed by. `auto`
+ * and `assistant` have no ref: nothing ran yet.
+ */
+export function engineRef(spec) {
+  const s = normalizeEngineSpec(spec);
+  if (s.kind === 'harness') return { kind: 'harness', id: s.harnessId, ...(s.model ? { model: s.model } : {}) };
+  if (s.kind === 'model') return s.providerId ? { kind: 'model', id: s.providerId, model: s.model } : { kind: 'model', id: s.model };
+  return null;
+}
+
+/** The ledger key of a spec, or null when it names nothing concrete. Same key as `engineKey` in scorecard.js. */
+export function engineKeyOf(spec) {
+  const r = engineRef(spec);
+  return r ? `${r.kind}:${r.id}${r.model && r.model !== r.id ? `/${r.model}` : ''}` : null;
+}
+
+/** One phrase a person reads on a card: "Claude Code", "gpt-4o at openrouter", "auto · cheapest that clears", "the chat's model". */
+export function describeEngine(spec, { harnessName = (id) => id, providerName = (id) => id } = {}) {
+  const s = normalizeEngineSpec(spec);
+  if (s.kind === 'assistant') return 'the chat’s model';
+  if (s.kind === 'auto') return `auto · ${s.policy.prefer.replace(/-/g, ' ')}`;
+  if (s.kind === 'harness') return `${harnessName(s.harnessId)}${s.model ? ` (${s.model})` : ''}`;
+  return `${s.model}${s.providerId ? ` at ${providerName(s.providerId)}` : ''}`;
+}
+
+/**
+ * The role tier today's appointers understand (`cheap` / `balanced` / `strong`) for a spec:
+ * the bridge to `prefer` until the recruiter routes by card (§13.4, step 5).
+ */
+export function tierOf(spec) {
+  const s = normalizeEngineSpec(spec);
+  if (s.kind !== 'auto') return 'balanced';
+  return { 'best-quality': 'strong', 'cheapest-that-clears': 'cheap', fastest: 'cheap', balanced: 'balanced' }[s.policy.prefer] || 'balanced';
+}

package/src/gate.js

@@ -0,0 +1,75 @@
+// VENDORED from @chatpanel/events/gate.js — edit there, then copy over.
+// The gate — how far a team may go without a person, as data an organisation configures.
+//
+// ChatPanel's own gate is the strictest setting; an organisation that trusts its pool more
+// flips a flag. Nothing in the runner changes: project-run.js reads the gate at every step
+// where it would otherwise ask, and `gateAllows` is the one question it asks. Lives in
+// `.chatpanel/gate.json` in the org repo (pillars §14.3), optionally overridden per project.
+
+export const AUTONOMY = Object.freeze(['propose', 'push', 'merge']);
+export const HUMAN_FLAGS = Object.freeze(['merge', 'push', 'publish', 'budgetRaise', 'newAgent', 'newTool', 'writeBack', 'recruit']);
+export const CHECKS = Object.freeze(['guard', 'review', 'tester', 'scan']);
+
+/** ChatPanel's own: a branch push is not a release; everything else waits for a person. */
+export const DEFAULT_GATE = Object.freeze({
+  autonomy: 'push',
+  human: Object.freeze({ merge: true, push: false, publish: true, budgetRaise: true, newAgent: true, newTool: true, writeBack: true, recruit: false }),
+  requiredBeforeMerge: Object.freeze(['guard', 'review', 'tester']),
+  branches: Object.freeze({ base: 'main', protected: Object.freeze(['main']) }),
+  budget: Object.freeze({ perProjectCap: null, perJobCap: null }),
+});
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+export function validateGate(g, { partial = false } = {}) {
+  const errors = [];
+  if (!isRecord(g)) return { ok: false, errors: ['gate must be an object'] };
+  if (g.autonomy !== undefined && !AUTONOMY.includes(g.autonomy)) errors.push(`autonomy: one of ${AUTONOMY.join(', ')}`);
+  if (g.human !== undefined) {
+    if (!isRecord(g.human)) errors.push('human: an object of flags');
+    else for (const [k, v] of Object.entries(g.human)) { if (!HUMAN_FLAGS.includes(k)) errors.push(`human.${k}: unknown flag`); else if (typeof v !== 'boolean') errors.push(`human.${k}: true or false`); }
+  }
+  if (g.requiredBeforeMerge !== undefined && (!Array.isArray(g.requiredBeforeMerge) || g.requiredBeforeMerge.some((c) => !CHECKS.includes(c)))) errors.push(`requiredBeforeMerge: a list of ${CHECKS.join(', ')}`);
+  if (g.branches !== undefined && (!isRecord(g.branches) || (g.branches.protected !== undefined && !Array.isArray(g.branches.protected)))) errors.push('branches: { base, protected[] }');
+  if (g.budget !== undefined && !isRecord(g.budget)) errors.push('budget: { perProjectCap, perJobCap }');
+  if (!partial && g.autonomy === undefined) errors.push('autonomy: required');
+  return { ok: errors.length === 0, errors };
+}
+
+/** A gate over the default: a partial gate fills in from ChatPanel's own; a full one stands alone. */
+export function normalizeGate(g, { partial = false, base = DEFAULT_GATE } = {}) {
+  const v = validateGate(g || {}, { partial: true });
+  if (!v.ok) throw new Error(`gate: ${v.errors.join('; ')}`);
+  const src = g || {};
+  const b = partial ? base : DEFAULT_GATE;
+  return {
+    autonomy: AUTONOMY.includes(src.autonomy) ? src.autonomy : b.autonomy,
+    human: { ...b.human, ...(isRecord(src.human) ? src.human : {}) },
+    requiredBeforeMerge: Array.isArray(src.requiredBeforeMerge) ? [...new Set(src.requiredBeforeMerge)] : [...b.requiredBeforeMerge],
+    branches: { base: String(src.branches?.base || b.branches.base), protected: Array.isArray(src.branches?.protected) ? [...new Set(src.branches.protected.map(String))] : [...b.branches.protected] },
+    budget: { perProjectCap: src.budget?.perProjectCap ?? b.budget.perProjectCap, perJobCap: src.budget?.perJobCap ?? b.budget.perJobCap },
+  };
+}
+
+/** The org's gate with a project's partial one over it. */
+export function effectiveGate(orgGate = null, projectGate = null) {
+  const org = normalizeGate(orgGate || {}, { partial: true });
+  return projectGate ? normalizeGate(projectGate, { partial: true, base: org }) : org;
+}
+
+/**
+ * The one question the executive loop asks: may a team do `action` on its own?
+ *   push · merge · publish · budgetRaise · newAgent · newTool · writeBack · recruit
+ * Returns `{ allowed, reason }`; a false answer is where the loop asks a person instead.
+ */
+export function gateAllows(gate, action, { branch = null } = {}) {
+  const g = normalizeGate(gate || {}, { partial: true });
+  if (action === 'push' || action === 'merge') {
+    if (branch && g.branches.protected.includes(branch)) return { allowed: false, reason: `${branch} is protected — a person merges` };
+    const far = AUTONOMY.indexOf(g.autonomy);
+    if (action === 'push' && far < AUTONOMY.indexOf('push')) return { allowed: false, reason: 'the gate allows proposing only' };
+    if (action === 'merge' && far < AUTONOMY.indexOf('merge')) return { allowed: false, reason: `the gate allows up to ${g.autonomy}` };
+  }
+  if (HUMAN_FLAGS.includes(action) && g.human[action]) return { allowed: false, reason: `a person decides ${action}` };
+  return { allowed: true, reason: `the gate allows ${action}` };
+}

package/src/job.js

@@ -0,0 +1,150 @@
+// VENDORED from @chatpanel/events/job.js — edit there, then copy over.
+// A job — a posting on a project's board that the pool applies to.
+//
+// The executive posts the first jobs; a recruited agent posts more when the work needs more
+// hands, a skill or a tool it does not have; a person posts one by hand. A job says what it
+// needs (skills, tools, grants), what it may cost (carved from the project's budget), and
+// where the work happens (a repo and a base branch — the bridge gives it a worktree). Agents
+// in the pool APPLY by construction (recruit.js scores every type at once); an evaluator
+// picks; the pick is recruited with a budget and the job becomes a role on a run.
+//
+// A job's status is a machine: open → evaluating → recruited → in-progress → done | failed,
+// with withdrawn from any of the first three. Every move is an event on the project's
+// record (project.js foldProject: `job.posted`, `job.updated`).
+
+import { validateBudget, normalizeBudget } from './budget.js';
+import { GRANT_RE } from './team.js';
+
+export const JOB_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+export const JOB_STATUSES = Object.freeze(['open', 'evaluating', 'recruited', 'in-progress', 'done', 'failed', 'withdrawn']);
+const NEXT = Object.freeze({
+  open: ['evaluating', 'recruited', 'withdrawn'], evaluating: ['recruited', 'open', 'withdrawn'], recruited: ['in-progress', 'open', 'withdrawn'],
+  'in-progress': ['done', 'failed', 'open'], done: [], failed: ['open'], withdrawn: ['open'],
+});
+export const MAX_NEEDS = 24;
+export const MAX_APPLICATIONS = 64;
+
+export class JobError extends Error {
+  constructor(code, message) { super(message); this.name = 'JobError'; this.code = code; }
+}
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const clip = (s, n) => String(s || '').trim().slice(0, n);
+const list = (xs, n, max) => [...new Set((Array.isArray(xs) ? xs : typeof xs === 'string' ? xs.split(/[,\s]+/) : []).map((x) => clip(x, n)).filter(Boolean))].slice(0, max);
+
+export function validateJob(j) {
+  const errors = [];
+  if (!isRecord(j)) return { ok: false, errors: ['job must be an object'] };
+  if (!JOB_ID_RE.test(String(j.id || ''))) errors.push('id: a short identifier (letters, digits, _ -)');
+  if (!JOB_ID_RE.test(String(j.projectId || ''))) errors.push('projectId: the project this job belongs to');
+  if (!clip(j.title, 200)) errors.push('title: what the job is');
+  if (!clip(j.brief, 8000)) errors.push('brief: what to do, what done looks like');
+  if (j.needs !== undefined) {
+    if (!isRecord(j.needs)) errors.push('needs: { skills[], tools[], grants[] }');
+    else {
+      const badGrants = (Array.isArray(j.needs.grants) ? j.needs.grants : []).filter((g) => !GRANT_RE.test(String(g)));
+      if (badGrants.length) errors.push(`needs.grants: not grantable: ${badGrants.join(', ')}`);
+    }
+  }
+  if (j.budget !== undefined) { const b = validateBudget(j.budget); if (!b.ok) errors.push(...b.errors.map((e) => `budget: ${e}`)); }
+  if (j.status !== undefined && !JOB_STATUSES.includes(j.status)) errors.push(`status: one of ${JOB_STATUSES.join(', ')}`);
+  if (j.dependsOn !== undefined && !Array.isArray(j.dependsOn)) errors.push('dependsOn: a list of job ids');
+  if (j.workspace !== undefined && j.workspace !== null && !isRecord(j.workspace)) errors.push('workspace: { repoId, base, branch? }');
+  if (j.deadline !== undefined && j.deadline !== null && !Number.isFinite(Number(j.deadline))) errors.push('deadline: a time');
+  return { ok: errors.length === 0, errors };
+}
+
+export function normalizeJob(j) {
+  const v = validateJob(j);
+  if (!v.ok) throw new JobError('INVALID', v.errors.join('; '));
+  return {
+    id: String(j.id),
+    projectId: String(j.projectId),
+    title: clip(j.title, 200),
+    brief: clip(j.brief, 8000),
+    needs: {
+      skills: list(j.needs?.skills, 80, MAX_NEEDS),
+      tools: list(j.needs?.tools, 120, MAX_NEEDS),
+      grants: list(j.needs?.grants, 64, MAX_NEEDS).filter((g) => GRANT_RE.test(g)),
+    },
+    ...(j.budget ? { budget: normalizeBudget(j.budget) } : {}),
+    size: { steps: Math.max(0, Math.round(Number(j.size?.steps) || 0)) },
+    status: JOB_STATUSES.includes(j.status) ? j.status : 'open',
+    postedBy: clip(j.postedBy, 80) || 'person',
+    postedAt: Number(j.postedAt) || Date.now(),
+    ...(j.deadline ? { deadline: Number(j.deadline) } : {}),
+    dependsOn: list(j.dependsOn, 64, 32).filter((d) => d !== j.id),
+    ...(j.workspace ? { workspace: { repoId: clip(j.workspace.repoId, 120), base: clip(j.workspace.base, 120) || 'main', ...(j.workspace.branch ? { branch: clip(j.workspace.branch, 200) } : {}), ...(j.workspace.worktreePath ? { worktreePath: clip(j.workspace.worktreePath, 400) } : {}) } } : {}),
+    applications: Array.isArray(j.applications) ? j.applications.slice(0, MAX_APPLICATIONS).map(normalizeApplication).filter(Boolean) : [],
+    ...(j.recruited ? { recruited: normalizeRecruit(j.recruited) } : {}),
+    ...(j.runId ? { runId: String(j.runId) } : {}),
+    ...(j.result ? { result: { text: clip(j.result.text, 8000), by: clip(j.result.by, 80), at: Number(j.result.at) || Date.now(), ...(Array.isArray(j.result.refs) ? { refs: j.result.refs.slice(0, 12) } : {}) } } : {}),
+    ...(j.origin && isRecord(j.origin) ? { origin: { ...j.origin } } : {}),
+  };
+}
+
+function normalizeApplication(a) {
+  if (!isRecord(a) || !a.agentId) return null;
+  return { agentId: String(a.agentId), ...(a.engine ? { engine: a.engine } : {}), fit: Math.max(0, Math.min(1, Number(a.fit) || 0)), reasons: Array.isArray(a.reasons) ? a.reasons.map((r) => clip(r, 200)).slice(0, 8) : [], pitch: clip(a.pitch, 600), at: Number(a.at) || Date.now() };
+}
+function normalizeRecruit(r) {
+  return { agentId: String(r.agentId), ...(r.engine ? { engine: r.engine } : {}), ...(r.budget ? { budget: normalizeBudget(r.budget) } : {}), by: clip(r.by, 80) || 'evaluator', at: Number(r.at) || Date.now(), ...(r.why ? { why: clip(r.why, 600) } : {}) };
+}
+
+export function defineJob(j) { return Object.freeze(normalizeJob(j)); }
+
+/** May the job move from `from` to `to`? */
+export function canTransition(from, to) { return (NEXT[from] || []).includes(to); }
+
+/** Applications are computed, not asked for: every eligible type in the pool applies at once. */
+export function applyAll(job, pool, fitFn, { cards = {}, now = Date.now() } = {}) {
+  // A fit function may also say which ENGINE the agent would run on (recruit.js does); an
+  // application without one is not recruitable right now and sorts after those that are.
+  return (pool || [])
+    .filter((a) => a && a.enabled !== false && (a.appliesTo || ['jobs']).includes('jobs'))
+    .map((a) => { const f = fitFn(job, a, cards[a.id] || null); return { agentId: a.id, ...(f.engine ? { engine: f.engine } : {}), fit: f.score, reasons: f.reasons, pitch: '', at: now }; })
+    .sort((x, y) => (!!y.engine - !!x.engine) || (y.fit - x.fit))
+    .slice(0, MAX_APPLICATIONS);
+}
+
+/** A recruited job as the role a run gives the agent: the brief is the prompt, the needs are the grants. */
+export function jobToRole(job, agent) {
+  return {
+    id: agent?.id || job.id,
+    agent: agent?.id,
+    name: agent?.name || job.title,
+    prompt: [agent?.prompt, `Job: ${job.title}\n\n${job.brief}`].filter(Boolean).join('\n\n'),
+    grants: (job.needs?.grants?.length ? job.needs.grants : agent?.grants) || ['none'],
+    ...(job.dependsOn?.length ? { dependsOn: job.dependsOn } : {}),
+    ...(job.workspace ? { workspace: job.workspace } : {}),
+  };
+}
+
+/** The jobs that may run now: every dependency done, and not already taken. */
+export function readyJobs(jobs) {
+  const byId = new Map((jobs || []).map((j) => [j.id, j]));
+  return (jobs || []).filter((j) => j.status === 'open' && (j.dependsOn || []).every((d) => byId.get(d)?.status === 'done'));
+}
+
+/** A blank posting for the form. */
+export function blankJob(projectId = '') {
+  return { id: '', projectId, title: '', brief: '', needs: { skills: [], tools: [], grants: [] }, budget: { tokens: 40000, ms: 900000 }, status: 'open', dependsOn: [] };
+}
+
+export function jobFromForm(form) {
+  const budget = {};
+  for (const k of ['tokens', 'calls', 'ms', 'usd']) {
+    const v = Number(form?.budget?.[k]);
+    if (form?.budget?.[k] !== '' && form?.budget?.[k] != null && Number.isFinite(v) && v > 0) budget[k] = v;
+  }
+  const j = {
+    id: String(form?.id || '').trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[^a-z]+/, '').replace(/-+$/, '').slice(0, 64),
+    projectId: form?.projectId, title: form?.title, brief: form?.brief,
+    needs: { skills: form?.needs?.skills, tools: form?.needs?.tools, grants: form?.needs?.grants },
+    ...(Object.keys(budget).length ? { budget } : {}),
+    status: form?.status || 'open', postedBy: form?.postedBy || 'person', dependsOn: form?.dependsOn,
+    ...(form?.workspace?.repoId ? { workspace: form.workspace } : {}), ...(form?.size ? { size: form.size } : {}),
+  };
+  const v = validateJob(j);
+  return v.ok ? { ok: true, job: normalizeJob(j) } : { ok: false, errors: v.errors };
+}

package/src/model-ledger.js

@@ -0,0 +1,229 @@
+// VENDORED from @chatpanel/events/model-ledger.js — edit there, then copy over.
+// The MODEL LEDGER — an engine's record, the scorecard pattern applied to engines
+// (architecture-pillars.md §13.2).
+//
+// One chained, store-attested ledger per ENGINE — keyed like the scorecard's `byEngine`
+// (`model:<provider>/<model>`, `harness:<id>`), because the same model at two providers is
+// two records: availability, cost and latency are the provider's, not the model's. Entries
+// are FACTS the runner and the gateway observe, never claims:
+//
+//   call          one turn: time to first token, total, tokens in/out, cost when priced, was
+//                 the JSON valid, were the tool calls valid, did it come back empty / refused
+//                 / truncated, did it succeed
+//   declined      it did not answer, and why (unavailable · auth · rate · credits · timeout ·
+//                 context) — the availability signal
+//   rotated-from  a task left it for another engine mid-run
+//   rating        a task's verdict, attributed to the engine that served it (and to the agent)
+//   capability    a proof: it was asked for X and it did / did not deliver
+//   price         what a token costs here — from the provider's list or typed by a person
+//
+// `summarizeEngine(entries)` → the ENGINE CARD: availability, reliability, latency, cost,
+// capability proofs (a capability with three failed proofs is WITHDRAWN until a person
+// re-enables it), quality by job kind, the last refs. model-candidates.js `applyCard` hands
+// the card to `applyOverride`: observed quality / latency / cost replace the name-based
+// guess wherever there is enough history (≥ `minCalls`), the guess stays as the prior until
+// then, and the result says which it used (`observed[]`). Reach is never learned, only
+// typed — a ledger cannot move a model closer than the URL says.
+//
+// Hashing, attestation and chain verification are scorecard.js's, unchanged: the same store
+// marks both, the same `verifyChain` checks both.
+
+import { canonical, sha256, engineKey, normalizeEngine } from './scorecard.js';
+export { verifyChain, attest, verifyAttested } from './scorecard.js';
+
+export const LEDGER_VERSION = 1;
+export const LEDGER_ENTRY_KINDS = Object.freeze(['call', 'declined', 'rotated-from', 'rating', 'capability', 'price']);
+export const DECLINE_REASONS = Object.freeze(['unavailable', 'auth', 'rate', 'credits', 'timeout', 'context', 'other']);
+export const STRUCTURED = Object.freeze(['ok', 'bad', 'n/a']);
+/** Failed proofs before a capability leaves the card. */
+export const WITHDRAW_AFTER = 3;
+/** Calls before an observed number outranks the name-based guess. Small; configurable. */
+export const DEFAULT_MIN_CALLS = 5;
+
+const n0 = (v) => Math.max(0, Math.round(Number(v) || 0));
+const money = (v) => (v == null || v === '' || !Number.isFinite(Number(v)) ? undefined : Math.max(0, Number(v)));
+const clamp01 = (n) => Math.max(0, Math.min(1, Number(n) || 0));
+const bool = (v) => v === true;
+const str = (v, n = 120) => (v == null || v === '' ? undefined : String(v).slice(0, n));
+const strip = (o) => { for (const k of Object.keys(o)) if (o[k] === undefined) delete o[k]; return o; };
+
+/** The ledger's key for an engine — the scorecard's `engineKey`, so the two join. */
+export function ledgerKey(engine) { return engineKey(engine); }
+
+/** A call fact, normalized. Rates are computed later; here every field is a plain observation. */
+export function normalizeCall(c) {
+  const src = c && typeof c === 'object' ? c : {};
+  return strip({
+    ok: src.ok !== false,
+    ttftMs: src.ttftMs != null ? n0(src.ttftMs) : undefined,
+    totalMs: src.totalMs != null ? n0(src.totalMs) : undefined,
+    tokensIn: src.tokensIn != null ? n0(src.tokensIn) : undefined,
+    tokensOut: src.tokensOut != null ? n0(src.tokensOut) : undefined,
+    // The total when the split is unknown (a harness reports one number, or none).
+    tokens: src.tokens != null && src.tokensIn == null && src.tokensOut == null ? n0(src.tokens) : undefined,
+    cost: money(src.cost),
+    structured: STRUCTURED.includes(src.structured) ? src.structured : 'n/a',
+    toolCalls: src.toolCalls && typeof src.toolCalls === 'object' ? { asked: n0(src.toolCalls.asked), valid: Math.min(n0(src.toolCalls.asked), n0(src.toolCalls.valid)) } : undefined,
+    empty: bool(src.empty) || undefined,
+    refused: bool(src.refused) || undefined,
+    truncated: bool(src.truncated) || undefined,
+  });
+}
+
+/**
+ * A new entry chained onto `prev`. `fact.engine` is required and keyed; the rest is by kind.
+ * Pure apart from the digest; the store attests.
+ */
+export async function makeLedgerEntry(fact, prev, { now = () => Date.now(), subtle } = {}) {
+  if (!fact || typeof fact !== 'object') throw new Error('model-ledger: an entry needs a fact');
+  if (!LEDGER_ENTRY_KINDS.includes(fact.kind)) throw new Error(`model-ledger: kind must be one of ${LEDGER_ENTRY_KINDS.join(', ')}`);
+  const engine = normalizeEngine(fact.engine);
+  if (!engine) throw new Error('model-ledger: engine required');
+  const key = engineKey(engine);
+  if (prev && prev.key !== key) throw new Error(`model-ledger: entry for ${key} chained onto ${prev.key}`);
+  const e = strip({
+    v: LEDGER_VERSION,
+    seq: prev ? prev.seq + 1 : 0,
+    key,
+    engine,
+    kind: fact.kind,
+    at: Number(fact.at) || now(),
+    runId: str(fact.runId), taskId: str(fact.taskId), agentId: str(fact.agentId), jobKind: str(fact.jobKind, 60),
+    call: fact.kind === 'call' ? normalizeCall(fact.call) : undefined,
+    declined: fact.kind === 'declined' ? { reason: DECLINE_REASONS.includes(fact.declined?.reason) ? fact.declined.reason : 'other', ...(fact.declined?.error ? { error: String(fact.declined.error).slice(0, 300) } : {}) } : undefined,
+    rotated: fact.kind === 'rotated-from' ? strip({ to: engineKey(fact.rotated?.to) || undefined, reason: str(fact.rotated?.reason, 300) }) : undefined,
+    rating: fact.kind === 'rating' ? strip({ by: String(fact.rating?.by || 'person').slice(0, 40), score: clamp01(fact.rating?.score), jobKind: str(fact.rating?.jobKind || fact.jobKind, 60), agentId: str(fact.rating?.agentId || fact.agentId) }) : undefined,
+    capability: fact.kind === 'capability' ? { id: String(fact.capability?.id || '').slice(0, 40), proved: bool(fact.capability?.proved) } : undefined,
+    price: fact.kind === 'price' ? strip({ per1kIn: money(fact.price?.per1kIn) ?? 0, per1kOut: money(fact.price?.per1kOut) ?? 0, source: fact.price?.source === 'user' ? 'user' : 'provider', currency: str(fact.price?.currency, 8) }) : undefined,
+    refs: Array.isArray(fact.refs) && fact.refs.length ? fact.refs.map(String).slice(0, 12) : undefined,
+    prev: prev ? prev.hash : null,
+  });
+  if (e.kind === 'capability' && !e.capability.id) throw new Error('model-ledger: capability.id required');
+  const { hash: _h, sig: _s, ...hashable } = e;
+  e.hash = await sha256(canonical(hashable), { subtle });
+  return e;
+}
+
+const percentile = (xs, p) => {
+  if (!xs.length) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.max(0, Math.ceil((p / 100) * s.length) - 1))];
+};
+const mean = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null);
+const rate = (n, of) => (of ? Math.round((n / of) * 1000) / 1000 : null);
+const r3 = (v) => (v == null ? null : Math.round(v * 1000) / 1000);
+
+/**
+ * The engine card. `minCalls` marks it `observed` once there is enough history; `now`
+ * bounds the by-hour availability band (the last 24 h) and the "declining right now" check.
+ */
+export function summarizeEngine(entries, { minCalls = DEFAULT_MIN_CALLS, now = Date.now(), recent = 5 } = {}) {
+  const list = (entries || []).filter((e) => e && e.kind);
+  const calls = list.filter((e) => e.kind === 'call');
+  const declines = list.filter((e) => e.kind === 'declined');
+  const attempts = calls.length + declines.length;
+  // Availability: declines over attempts, and the last 24 hours in bands of one.
+  const byHour = Array.from({ length: 24 }, () => ({ calls: 0, declines: 0 }));
+  for (const e of [...calls, ...declines]) {
+    const h = Math.floor((now - e.at) / 3600000);
+    if (h >= 0 && h < 24) byHour[23 - h][e.kind === 'call' ? 'calls' : 'declines'] += 1;
+  }
+  const declinesBy = {};
+  for (const e of declines) declinesBy[e.declined.reason] = (declinesBy[e.declined.reason] || 0) + 1;
+  // Declining right now: the last three attempts all declined, within the last hour.
+  const lastThree = [...calls, ...declines].sort((a, b) => a.at - b.at).slice(-3);
+  const decliningNow = lastThree.length === 3 && lastThree.every((e) => e.kind === 'declined' && now - e.at < 3600000);
+  // Reliability: each a rate over the calls it applies to.
+  const withJson = calls.filter((e) => e.call.structured !== 'n/a');
+  const withTools = calls.filter((e) => e.call.toolCalls?.asked);
+  const reliability = {
+    failRate: rate(calls.filter((e) => !e.call.ok).length, calls.length),
+    empty: rate(calls.filter((e) => e.call.empty).length, calls.length),
+    refused: rate(calls.filter((e) => e.call.refused).length, calls.length),
+    truncated: rate(calls.filter((e) => e.call.truncated).length, calls.length),
+    badJson: rate(withJson.filter((e) => e.call.structured === 'bad').length, withJson.length),
+    badToolCall: rate(withTools.reduce((n, e) => n + (e.call.toolCalls.asked - e.call.toolCalls.valid), 0), withTools.reduce((n, e) => n + e.call.toolCalls.asked, 0)),
+  };
+  // Latency.
+  const ttft = calls.map((e) => e.call.ttftMs).filter((v) => v != null);
+  const total = calls.map((e) => e.call.totalMs).filter((v) => v != null);
+  const latency = { ttft: { p50: percentile(ttft, 50), p95: percentile(ttft, 95), n: ttft.length }, total: { p50: percentile(total, 50), p95: percentile(total, 95), n: total.length } };
+  // Cost: the latest price entry prices every call that reported tokens; a call that
+  // reported its own cost is taken as is; otherwise the mean tokens per call stands in.
+  const price = list.filter((e) => e.kind === 'price').at(-1)?.price || null;
+  const costs = calls.map((e) => (e.call.cost != null ? e.call.cost : price && (e.call.tokensIn != null || e.call.tokensOut != null) ? ((e.call.tokensIn || 0) * price.per1kIn + (e.call.tokensOut || 0) * price.per1kOut) / 1000 : null)).filter((v) => v != null);
+  const tokens = calls.map((e) => (e.call.tokensIn || 0) + (e.call.tokensOut || 0) + (e.call.tokens || 0)).filter((v) => v > 0);
+  const cost = { perTask: r3(mean(costs)), priced: costs.length, tokensPerTask: tokens.length ? Math.round(mean(tokens)) : null, ...(price ? { per1kIn: price.per1kIn, per1kOut: price.per1kOut, source: price.source } : {}) };
+  // Capability proofs: asked vs proved; withdrawn after WITHDRAW_AFTER failures unless a
+  // later proof succeeded (a person re-enabling it is a proof they record).
+  const proofs = {};
+  for (const e of list.filter((x) => x.kind === 'capability')) {
+    const p = proofs[e.capability.id] || (proofs[e.capability.id] = { asked: 0, proved: 0, failedSince: 0 });
+    p.asked += 1;
+    if (e.capability.proved) { p.proved += 1; p.failedSince = 0; } else p.failedSince += 1;
+  }
+  const capabilities = {
+    proved: Object.keys(proofs).filter((id) => proofs[id].proved > 0 && proofs[id].failedSince < WITHDRAW_AFTER).sort(),
+    withdrawn: Object.keys(proofs).filter((id) => proofs[id].failedSince >= WITHDRAW_AFTER).sort(),
+    proofs: Object.fromEntries(Object.entries(proofs).map(([id, p]) => [id, { asked: p.asked, proved: p.proved }])),
+  };
+  // Quality: mean rating, overall and by job kind.
+  const ratings = list.filter((e) => e.kind === 'rating');
+  const byJobKind = {};
+  for (const e of ratings) { const k = e.rating.jobKind || 'any'; (byJobKind[k] = byJobKind[k] || []).push(e.rating.score); }
+  const quality = {
+    overall: { avg: r3(mean(ratings.map((e) => e.rating.score))), count: ratings.length },
+    byJobKind: Object.fromEntries(Object.entries(byJobKind).map(([k, xs]) => [k, { avg: r3(mean(xs)), count: xs.length }])),
+  };
+  const rotatedFrom = list.filter((e) => e.kind === 'rotated-from').length;
+  return {
+    key: list[0]?.key || null,
+    engine: list[0]?.engine || null,
+    entries: list.length,
+    calls: calls.length,
+    declines: declines.length,
+    observed: calls.length >= minCalls,
+    availability: { rate: attempts ? r3(1 - declines.length / attempts) : null, attempts, declinesBy, byHour, decliningNow },
+    reliability,
+    latency,
+    cost,
+    capabilities,
+    quality,
+    rotatedFrom,
+    refs: [...new Set(list.flatMap((e) => e.refs || []))].slice(-recent),
+    since: list[0]?.at || null,
+    last: list.at(-1)?.at || null,
+    head: list.at(-1)?.hash || null,
+  };
+}
+
+/**
+ * The override a card yields for model-candidates.js `applyOverride` — only the fields it
+ * has enough history for. `quality` is the mean rating (for `jobKind` when the card has
+ * ratings for it, else overall); `latencyMs` the observed p50 to first token (total when no
+ * ttft was recorded); `costPer1k` from the price when one is known; `available: false`
+ * only while it is declining right now. Returns `{ override, observed }`.
+ *
+ * Lives here, beside the card it reads, so recruit.js and a store without a router can use
+ * it; `applyCard` (the override over the guess) stays in model-candidates.js beside
+ * `applyOverride`, the seam it feeds.
+ */
+export function cardOverride(card, { minCalls = DEFAULT_MIN_CALLS, jobKind = null } = {}) {
+  const override = {}; const observed = [];
+  if (!card) return { override, observed };
+  const q = (jobKind && card.quality?.byJobKind?.[jobKind]?.count >= minCalls) ? card.quality.byJobKind[jobKind] : card.quality?.overall;
+  if (q && q.count >= minCalls && q.avg != null) { override.quality = q.avg; observed.push('quality'); }
+  const lat = card.latency?.ttft?.n >= minCalls ? card.latency.ttft.p50 : card.latency?.total?.n >= minCalls ? card.latency.total.p50 : null;
+  if (lat != null) { override.latencyMs = lat; observed.push('latencyMs'); }
+  // Six places, not three: a per-1k price is often 0.0004, and rounding it to 0 made a paid model read as free.
+  if (card.cost?.per1kIn != null && card.cost?.per1kOut != null) { override.costPer1k = Math.round(((card.cost.per1kIn + card.cost.per1kOut) / 2) * 1e6) / 1e6; observed.push('costPer1k'); }
+  if (card.availability?.decliningNow) { override.available = false; observed.push('available'); }
+  return { override, observed };
+}
+
+// `applyCard` — the card over the name-based guess — lives in model-candidates.js beside
+// `applyOverride`, the seam it feeds; this module stays importable by a store that has no
+// router (the gateway vendors it with scorecard.js only).
+// Agent scores normalised by engine (§13.3) live beside the card they adjust: scorecard.js
+// `adjustSummary` and `fit(job, type, summary, { qualityOf })`.
+export { adjustSummary } from './scorecard.js';