@chatpanel/gateway 0.6.87 → 0.6.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.87",
+  "version": "0.6.90",
   "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/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 };

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,149 @@
+// 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 = {} } = {}) {
+  const now = Date.now();
+  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, fit: f.score, reasons: f.reasons, pitch: '', at: now }; })
+    .sort((x, y) => 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 };
+}