@chatpanel/events 0.85.0 → 0.89.0

package/agent.js

@@ -0,0 +1,249 @@
+// 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/attribution.js

@@ -0,0 +1,132 @@
+// AUTHORSHIP — who wrote which run of a document, and the versions you can go back to.
+//
+// Moved here from the extension's `notes-provenance.js` unchanged in behaviour. It was
+// always platform-free: a run-list `[{ len, author, at }]` that sums to the body length and
+// shifts naturally as text is inserted or deleted, with no absolute offsets to fix up. The
+// desktop needed exactly the same answers, and a second implementation of "who wrote this"
+// would have disagreed with the first on precisely the edits that matter.
+//
+// WHY RUNS AND NOT OFFSETS. An offset-based ledger has to be repaired after every edit, and
+// the repair is where the bugs live. A run-list is repaired BY the edit: replacing [s,e)
+// with n characters is a splice, and everything after it moves without being touched.
+//
+// The versioning half is new here and belongs beside it, because a version snapshot carries
+// its ledger — restoring a body without its attribution would silently reattribute an
+// agent's paragraphs to the person who pressed Restore.
+
+export const HUMAN = 'You';
+
+export function blankAttribution(len, author = HUMAN, at = 0) {
+  return len > 0 ? [{ len, author, at }] : [];
+}
+
+// The minimal replaced range: [start,end) of `prev` became `insLen` new chars in `next`.
+export function diffRange(prev, next) {
+  const max = Math.min(prev.length, next.length);
+  let s = 0; while (s < max && prev[s] === next[s]) s++;
+  let e = 0; while (e < max - s && prev[prev.length - 1 - e] === next[next.length - 1 - e]) e++;
+  return { start: s, end: prev.length - e, insLen: next.length - s - e };
+}
+
+export function mergeRuns(runs) {
+  const out = [];
+  for (const r of runs) {
+    if (!r.len) continue;
+    const last = out[out.length - 1];
+    if (last && last.author === r.author && last.at === r.at) last.len += r.len;
+    else out.push({ len: r.len, author: r.author, at: r.at });
+  }
+  return out;
+}
+
+export function spliceAttribution(runs, start, end, insLen, author, at) {
+  const before = [], after = [];
+  let pos = 0;
+  for (const r of runs) {
+    const rStart = pos, rEnd = pos + r.len;
+    if (rEnd <= start) before.push(r);
+    else if (rStart >= end) after.push(r);
+    else {
+      if (rStart < start) before.push({ len: start - rStart, author: r.author, at: r.at });
+      if (rEnd > end) after.push({ len: rEnd - end, author: r.author, at: r.at });
+    }
+    pos = rEnd;
+  }
+  return mergeRuns([...before, ...(insLen ? [{ len: insLen, author, at }] : []), ...after]);
+}
+
+// Attribute the diff prev→next to `author`. Returns the updated run-list (unchanged
+// reference-wise only when there was no change).
+export function applyAttribution(runs, prev, next, author, at) {
+  const cur = Array.isArray(runs) && runs.length ? runs : blankAttribution(prev.length);
+  const { start, end, insLen } = diffRange(prev, next);
+  if (start === end && !insLen) return cur; // no change
+  return spliceAttribution(cur, start, end, insLen, author, at);
+}
+
+export function attributionSummary(runs) {
+  const by = new Map();
+  let total = 0;
+  for (const r of runs || []) { by.set(r.author, (by.get(r.author) || 0) + r.len); total += r.len; }
+  return {
+    by: [...by.entries()].map(([author, chars]) => ({ author, chars })).sort((a, b) => b.chars - a.chars),
+    total,
+  };
+}
+
+// Adopt a stored ledger only if it still matches the body length (a note edited by an
+// older build, or imported, won't have one) — otherwise seed the whole body as You.
+export function normalizeAttribution(runs, bodyLen, at) {
+  if (Array.isArray(runs) && runs.length && runs.reduce((n, r) => n + (r.len || 0), 0) === bodyLen) return mergeRuns(runs);
+  return blankAttribution(bodyLen, HUMAN, at);
+}
+
+// ---------------------------------------------------------------------------
+// Versions — the snapshots you can go back to
+// ---------------------------------------------------------------------------
+
+/** Forty is what the extension keeps. Enough to undo an afternoon, bounded enough to store. */
+export const MAX_VERSIONS = 40;
+
+/**
+ * Append a snapshot of `body` and its ledger, and return the new list.
+ *
+ * Two rules, both about not filling the list with noise:
+ *   · a body identical to the newest snapshot is not a new version;
+ *   · a ledger that does not sum to this body's length is not this body's ledger, so it is
+ *     seeded blank rather than carried across — a mismatched ledger would make a later
+ *     restore attribute the wrong spans to the wrong authors.
+ */
+export function pushVersion(versions, { body, attribution = null, by = HUMAN, label = '', at = Date.now() } = {}) {
+  const list = Array.isArray(versions) ? versions : [];
+  const text = String(body ?? '');
+  const last = list[list.length - 1];
+  if (last && last.body === text) return list;
+  const ledger = (Array.isArray(attribution) && attribution.reduce((n, r) => n + (r.len || 0), 0) === text.length)
+    ? attribution
+    : blankAttribution(text.length, by, at);
+  return [...list, { body: text, attribution: ledger, at, by, label: label || by }].slice(-MAX_VERSIONS);
+}
+
+/**
+ * Restore version `index`, keeping the current draft as a snapshot first so the restore is
+ * itself undoable.
+ *
+ * The guard against re-snapshotting matters more than it looks: flipping between two
+ * versions (A→B→A→B) would otherwise push an identical "Before restore" row every time and
+ * push the version you were trying to reach off the end of a bounded list.
+ */
+export function restoreVersion(versions, index, { currentBody, currentAttribution = null, at = Date.now(), label = 'Before restore' } = {}) {
+  const list = Array.isArray(versions) ? versions : [];
+  const target = list[index];
+  if (!target) return null;
+  const draft = String(currentBody ?? '');
+  const next = list.some((v) => v.body === draft)
+    ? list
+    : pushVersion(list, { body: draft, attribution: currentAttribution, by: HUMAN, label, at });
+  return {
+    body: target.body,
+    attribution: normalizeAttribution(target.attribution, target.body.length, target.at || at),
+    versions: next,
+  };
+}

package/client-prefs.js

@@ -22,7 +22,16 @@ export const PREF_SECTIONS = Object.freeze([
   { id: 'skills', label: 'Skills', path: ['skills'], kind: 'array' },
   { id: 'skillDirs', label: 'Skill folders', path: ['ui', 'skillDirs'], kind: 'array' },
   { id: 'recipes', label: 'Recipes', path: ['recipes'], kind: 'array' },
-  { id: 'teams', label: 'Agent teams', path: ['teams'], kind: 'array' },
+  { id: 'teams', label: 'Teams', path: ['teams'], kind: 'array' },
+  // The agent pool (agent.js). NOT `settings.agents` — that key is the extension's harness
+  // list (its bridge "agents"), which the naming rule keeps; the pool lives beside it.
+  { id: 'agents', label: 'Agents', path: ['agentPool'], kind: 'array' },
+  // SCM connections (scm-connection.js): kind, host, secret REF — never the token, which
+  // stays in the machine's keychain / the bridge's secret store and does not travel.
+  { id: 'connections', label: 'Connections', path: ['connections'], kind: 'array' },
+  // The project pages (F8 §12): the goal, its stakeholder, budget, repos, gate. Jobs and runs
+  // fold on the gateway's project record, not here.
+  { id: 'projects', label: 'Projects', path: ['projects'], kind: 'array' },
   { id: 'webSearch', label: 'Web search', path: ['ui', 'webSearch'], kind: 'object' },
   { id: 'tools', label: 'Tools', path: null, kind: 'object', keys: ['mcpToolsMode', 'maxToolsPerTurn', 'historyTools', 'historyContextMode', 'dataDispatch', 'toolResultMaxChars'] },
   { id: 'suggestions', label: 'Smart suggestions', path: ['ui', 'suggestions'], kind: 'object' },

package/engine.js

@@ -0,0 +1,131 @@
+// 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/gate.js

@@ -0,0 +1,74 @@
+// 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/index.js

@@ -192,13 +192,24 @@ export { recipeToolProvider, recipeToolSpec, describeRecipeForApproval, RECIPE_T
 // Agent teams (F8): a team is data, a run is a turn of turns under a budget, members talk
 // through a typed board, nothing lands without a person.
 export { createBudget, validateBudget, normalizeBudget, usageOf, BudgetError, BUDGET_DIMENSIONS } from './budget.js';
-export { defineTeam, validateTeam, normalizeTeam, normalizeGrants, grantAllows, describeRole, TeamError, ROLE_MODES, MERGE_POLICIES, PLAN_MODES, GRANTABLE, STARTER_TEAMS, starterTeams, blankTeam, teamFromForm, slugTeamName } from './team.js';
+export { defineTeam, validateTeam, normalizeTeam, normalizeGrants, grantAllows, scmAllows, describeRole, TeamError, ROLE_MODES, MERGE_POLICIES, PLAN_MODES, GRANTABLE, WORK_GRANTS, GRANT_RE, AGENT_REF_RE, STARTER_TEAMS, starterTeams, blankTeam, teamFromForm, slugTeamName } from './team.js';
 export { fixedPlan, parsePlan, plannerPrompt, waves, breakCycles, TEAM_PLAN_SCHEMA } from './team-plan.js';
 export { createBoard, parseFindings, boardText, findingsInstruction, toBriefClaims, FINDINGS_SCHEMA, FINDING_KINDS, THREAD_KINDS, THREAD_STATUSES, POST_KINDS, POST_STATUSES, ASK_TYPES, emptyBoardState, foldBoard, findingsOf } from './team-board.js';
 export { boardToolProvider, boardToolSpec, createAnswerBox, withBoardTool, BOARD_TOOL_NAME, DEFAULT_ASK_TIMEOUT_MS } from './board-tool.js';
 export { createRunCache, withRunCache } from './team-cache.js';
 export { emptyRun, foldRun, runFromEvents, checkpointFrom, isResumable, LIVE_RUN_STATUSES, RESUMABLE_RUN_STATUSES } from './team-record.js';
-export { canonical, sha256, makeEntry, verifyChain, attest, verifyAttested, summarize, fit, SCORECARD_ENTRY_KINDS, ROLE_KINDS, SCORECARD_VERSION } from './scorecard.js';
+export { validateProject, normalizeProject, defineProject, canTransition as canProjectTransition, blankProject, projectFromForm, emptyProjectRecord, foldProject, projectProgress, ProjectError, PROJECT_STATUSES, PROJECT_ID_RE } from './project.js';
+// Job POSTINGS (F8 §12) — `jobs.js` is the scheduler and keeps `defineJob`; a posting is a JobPost here.
+export { validateJob as validateJobPost, normalizeJob as normalizeJobPost, defineJob as defineJobPost, canTransition as canJobPostTransition, applyAll, jobToRole, readyJobs, blankJob as blankJobPost, jobFromForm as jobPostFromForm, JobError as JobPostError, JOB_STATUSES as JOB_POST_STATUSES, JOB_ID_RE as JOB_POST_ID_RE } from './job.js';
+export { validateGate, normalizeGate, effectiveGate, gateAllows, DEFAULT_GATE, AUTONOMY, HUMAN_FLAGS, CHECKS } from './gate.js';
+export { canonical, sha256, makeEntry, verifyChain, attest, verifyAttested, summarize, fit, adjustSummary, normalizeEngine, engineKey, normalizeScm, SCORECARD_ENTRY_KINDS, ROLE_KINDS, SCORECARD_VERSION, ENGINE_KINDS as RECORD_ENGINE_KINDS } from './scorecard.js';
+export { ENGINE_KINDS as ENGINE_SPEC_KINDS, ROUTE_PREFERS, normalizePolicy, normalizeEngineSpec, validateEngineSpec, engineRef, engineKeyOf, describeEngine, tierOf } from './engine.js';
+export { AGENT_ID_RE, APPLIES_TO, EGRESS_CLASSES, ASSISTANT_ID, AgentError, validateAgent, normalizeAgent, defineAgent, assistantAgent, engineOf, describeAgent, slugAgentId, resolveTeam, STARTER_AGENTS, starterAgents, blankAgent, agentFromForm, poolFor } from './agent.js';
+export { LEDGER_VERSION, LEDGER_ENTRY_KINDS, DECLINE_REASONS, WITHDRAW_AFTER, ledgerKey, normalizeCall, makeLedgerEntry, summarizeEngine } from './model-ledger.js';
+// Recruiting (F8 §12.2.4, pillars §13.4): the pool applies at once; an (agent, engine) pair is recruited; the evaluator is one optional structured call.
+export { RECRUIT_SCHEMA, MIN_FIT, engineRow, engineRows, needForJob, routeFor, engineWorth, applications as jobApplications, evaluatorPrompt, parseEvaluation, decide as decideRecruit, proposalFromNeeds, proposalToAgent, carveBudget, recruitEvents, recruitJob } from './recruit.js';
+export { DEFAULT_MIN_CALLS, cardOverride, applyCard } from './model-candidates.js';
+export { SCM_KINDS, validateConnection, normalizeConnection, parseRemote, connectionFor, branchFor, worktreeDirFor, credentialEnv, describeConnection, blankConnection, connectionFromForm } from './scm-connection.js';
 export { messagesFor, mergeTranscript, clipTranscript, clipMessage, newSteps, continuationNote, createControl, STEP_MAX_CHARS, TASK_TRANSCRIPT_MAX_CHARS } from './team-task.js';
 export { runTeam, resumeTeam, dryRunTeam, isModelUnavailable, TeamRunError, RUN_STATUSES } from './team-run.js';
 export { teamToolProvider, teamToolSpec, describeTeamForApproval, TEAM_TOOL_NAME } from './team-tool.js';