create-walle 0.10.1 → 0.10.2

package/template/wall-e/lib/helper-rules/lead-call-hook.js

@@ -0,0 +1,522 @@
+'use strict';
+
+// Lead-cost routing WP-5b (design §6.7, contract §2/S-11..S-18): the ONE place a lead's
+// Wall-E tool call is remembered, and the only writer of wait-watch / explore outcomes
+// outside WP-5a's store.
+//
+// The MCP dispatch (mcp-server.js) calls recordLeadToolCall(...) once per lead-tool call --
+// one line per site, because that file is at its frozen size ceiling. Everything the rules
+// need is derived here:
+//
+//   1. a ring buffer of the lead's last CALL_RING calls, so "what did the lead do next?"
+//      is answerable without ever reading the lead's transcript (the hook has no fs import);
+//   2. a bounded map of the workers the lead launched (ctm_session_id → route/agent/
+//      invocation/profile), which is what turns a worker id into the wait-watch cell key;
+//   3. the outcome rows themselves: a watcher wake or silent tick is opened as a PENDING wait
+//      outcome by the WAIT call that produced it and labelled by the lead's NEXT call
+//      (label.js's pure functions); an exploration hand-off is opened by the delegate call and
+//      closed by the status/wait call that reports it terminal.
+//
+// Every write goes through loops/brain-write (the owner-routing seam): the loop process holds
+// a read-write brain, the scheduler/MCP worker routes the same call to the brain owner. It is
+// required lazily, per write, for two reasons: lib/ must not hold a module-top reference into
+// loops/ (the shared-walle dependency ladder), and a test can then substitute its own writer
+// by seeding require.cache for loops/brain-write.
+//
+// Nothing here is allowed to fail a lead's tool call: every write is fire-and-forget with a
+// reporter that warns at most once a minute, and the recordLeadToolCall body is guarded.
+
+const {
+  LABEL_VERSION,
+  factsFromPayload,
+  labelFromFacts,
+  labelLateEnd,
+  workerPayloadOf,
+} = require('./label');
+const { leadAgentFromClientInfo } = require('./cell-state');
+const { gradeHandoff, gradeToJson, readGraderModel, shouldGrade } = require('./grade');
+
+const ANONYMOUS_LEAD = 'anonymous';
+const CALL_RING = 8;
+const MAP_MAX = 256;
+const WARN_THROTTLE_MS = 60000;
+// §6.7: a pending outcome whose lead never called back is not evidence -- 10 minutes is the
+// point where "the wake bought nothing" is the honest reading (the wait it belongs to has
+// long since returned).
+const PENDING_TTL_MS = 10 * 60 * 1000;
+
+// The two tools that park on a worker. Their results carry watcher_decisions / woke_on.
+const WAIT_TOOLS = new Set(['walle_worker_wait', 'walle_worker_status']);
+// A worker status that means the hand-off is over (report_ready is CTM's terminal-with-report).
+const TERMINAL_STATUSES = new Set(['report_ready', 'failed', 'exited']);
+
+let callsByLead = new Map(); // lead key -> [ { tool, at, args } ] (last CALL_RING)
+let workerRoutes = new Map(); // ctm_session_id -> { route, agent, invocation_id, profile }
+let workerLeads = new Map(); // ctm_session_id -> lead key (owner of the delegation)
+let pending = []; // wait-watch outcomes waiting for the lead's next call
+let lastDecisionByWorker = new Map(); // worker_id -> the last decision the watcher recorded
+let openHandoffs = new Map(); // ctm_session_id -> { id, opened_at, brief_path } (best-effort cache; D-5)
+// D-5/S-5: every worker id this process already sent a close for. A close is keyed on the row's
+// worker_id (the store resolves it), so a restart cannot orphan it -- this set is only what keeps
+// repeated terminal reads of one worker from re-sending the same close.
+let closedWorkers = new Set();
+let lastWarnAt = 0;
+
+// --- small helpers -----------------------------------------------------------------
+
+function _leadKey(agentSessionId) {
+  const value = typeof agentSessionId === 'string' ? agentSessionId.trim() : '';
+  return value || ANONYMOUS_LEAD;
+}
+
+function _atMs(at) {
+  const value = at == null ? Date.now() : at;
+  if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.getTime() : Date.now();
+  if (typeof value === 'number') return Number.isFinite(value) ? value : Date.now();
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}
+
+function _stamp(ms) {
+  return new Date(ms).toISOString();
+}
+
+function _string(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+function _evict(map, extraMap) {
+  while (map.size > MAP_MAX) {
+    const oldest = map.keys().next().value;
+    map.delete(oldest);
+    if (extraMap) extraMap.delete(oldest);
+  }
+}
+
+// The owner-routing write seam (see the header). Never throws: a missing/unreachable brain is
+// a warning, not a failed tool call.
+function _warn(message) {
+  const now = Date.now();
+  if (now - lastWarnAt < WARN_THROTTLE_MS) return;
+  lastWarnAt = now;
+  console.warn(`[helper-rules] ${message}`);
+}
+
+function _write(method, ...args) {
+  const fail = (err) => _warn(`${method} failed: ${err && err.message ? err.message : err}`);
+  try {
+    Promise.resolve(require('../../loops/brain-write').brainWrite(method, ...args)).catch(fail);
+  } catch (err) {
+    fail(err); // REPORT: the write seam itself is unavailable -- the tool call still succeeds
+  }
+}
+
+// Same seam and the same never-throw contract as _write, but the resolved result is handed to
+// `onResult` (WP-6: the close write is what returns the row's `seq`, the grader's sampling
+// counter). A throw from `onResult` is reported like any other failure -- never propagated.
+function _writeThen(method, args, onResult) {
+  const fail = (err) => _warn(`${method} failed: ${err && err.message ? err.message : err}`);
+  try {
+    Promise.resolve(require('../../loops/brain-write').brainWrite(method, ...args))
+      .then((result) => onResult(result))
+      .catch(fail);
+  } catch (err) {
+    fail(err); // REPORT: the write seam itself is unavailable -- the tool call still succeeds
+  }
+}
+
+// --- reads the wait path and the panel use ------------------------------------------
+
+/** The delegation record of one worker, or null. Never throws. */
+function workerRouteOf(ctmSessionId) {
+  const entry = workerRoutes.get(_string(ctmSessionId));
+  return entry ? { ...entry } : null;
+}
+
+/** Every worker this lead launched, oldest first (the whole-set wait's mode is over these). */
+function leadWorkersOf(agentSessionId) {
+  const lead = _leadKey(agentSessionId);
+  const out = [];
+  for (const [ctmSessionId, entry] of workerRoutes) {
+    if (workerLeads.get(ctmSessionId) === lead) out.push({ ctm_session_id: ctmSessionId, ...entry });
+  }
+  return out;
+}
+
+/** Test seam: empties every buffer this module keeps (no clock, no db, no other side effect). */
+function _resetForTests() {
+  callsByLead = new Map();
+  workerRoutes = new Map();
+  workerLeads = new Map();
+  pending = [];
+  lastDecisionByWorker = new Map();
+  openHandoffs = new Map();
+  closedWorkers = new Set();
+  lastWarnAt = 0;
+}
+
+// --- the classification of one watcher decision --------------------------------------
+
+// 'wake' = a non-silent WAKE_LEAD the wait result reports as the reason it returned;
+// 'silent' = a silent WAKE_LEAD (mode 'silent' keeps collecting, D-16); null = nothing to
+// store. A KEEP_WAITING tick, silent or not, is never an outcome row: precision (and silent
+// precision) is the share of WAKES the lead's next call confirmed, and the missed wakes are
+// caught by the late-end positive control below -- lead review, WP-5b.
+function _pendingClass(decision, wokeOn) {
+  if (decision.decision !== 'WAKE_LEAD') return null;
+  if (decision.silent === true) return 'silent';
+  return wokeOn === 'watcher' ? 'wake' : null;
+}
+
+function _argsOf(call) {
+  return call && call.args && typeof call.args === 'object' ? call.args : {};
+}
+
+/** §6.4: the wait-watch facts of one outcome row (labelFromFacts('wait-watch', …) reads these). */
+function _waitWatchFacts(item, nextCall) {
+  const namesWorker = Boolean(item.workerId) && _argsOf(nextCall).ctm_session_id === item.workerId;
+  return {
+    decision: item.decision,
+    silent: item.silent === true,
+    woke_on: item.wokeOn == null ? null : item.wokeOn,
+    worker_id: item.workerId,
+    next_call: nextCall ? { tool: typeof nextCall.tool === 'string' ? nextCall.tool : '', names_worker: namesWorker } : null,
+    terminal_status: item.terminalStatus == null ? null : item.terminalStatus,
+    dropped: item.dropped === true,
+    late: item.late === true,
+  };
+}
+
+// §6.4: every wait-watch row stores its facts and its label_version; the label is derived here
+// by the one pure rule, never passed in by a caller.
+function _reportOutcome(item, nextCall) {
+  const facts = _waitWatchFacts(item, nextCall);
+  _write('helperRulesRecordOutcome', {
+    id: item.id,
+    cell_key: item.cellKey,
+    kind: 'wait-watch',
+    label: labelFromFacts('wait-watch', facts).label,
+    decision: item.decision,
+    worker_id: item.workerId,
+    facts_json: JSON.stringify(facts),
+    label_version: LABEL_VERSION,
+  });
+}
+
+// S-4 (round 2): both reads go through the one payload accessor; a `worker`-nested result is the
+// no-id wait's shape, and an id-less wait still falls back to the call's own args.
+function _workerIdOf(call, res) {
+  const payload = workerPayloadOf(res);
+  const direct = payload ? _string(payload.ctm_session_id) : '';
+  if (direct) return direct;
+  return _string(call.args.ctm_session_id);
+}
+
+function _statusOf(res) {
+  const payload = workerPayloadOf(res);
+  return payload ? _string(payload.status) : '';
+}
+
+// session-stops-followups-2026-10-24.html D-3: a `report_ready` whose report_provisional is true
+// is a live worker's interim report, not its final one -- it must not close or grade the hand-off.
+function _provisionalOf(res) {
+  const payload = workerPayloadOf(res);
+  return !!(payload && payload.report_provisional === true);
+}
+
+// --- the three pending/labelling steps ------------------------------------------------
+
+// §6.7: a pending outcome with no next call is labelled empty / silent_empty by the NEXT hook
+// invocation, whatever lead it belongs to.
+function _expirePending(nowMs) {
+  if (!pending.length) return;
+  const open = [];
+  for (const item of pending) {
+    if (nowMs - item.at >= PENDING_TTL_MS) _reportOutcome(item, null);
+    else open.push(item);
+  }
+  pending = open;
+}
+
+// The lead's next call IS the label for every wake it was left holding: a silent wake is
+// judged by the same rule with the silent prefix (would the lead have wanted it?).
+function _labelPendingForLead(lead, nextCall) {
+  if (!pending.length) return;
+  const open = [];
+  for (const item of pending) {
+    if (item.lead !== lead) {
+      open.push(item);
+      continue;
+    }
+    _reportOutcome(item, nextCall);
+  }
+  pending = open;
+}
+
+function _openWatcherOutcomes(lead, call, res, nowMs) {
+  if (!WAIT_TOOLS.has(call.tool) || !res || !Array.isArray(res.watcher_decisions)) return;
+  const wokeOn = _string(res.woke_on);
+  const stamp = _stamp(nowMs);
+  res.watcher_decisions.forEach((decision, index) => {
+    if (!decision || typeof decision !== 'object') return;
+    const workerId = _string(decision.worker_id);
+    if (workerId) {
+      lastDecisionByWorker.set(workerId, _string(decision.decision));
+      _evict(lastDecisionByWorker, null);
+    }
+    const kind = _pendingClass(decision, wokeOn);
+    if (!kind) return;
+    const entry = workerRoutes.get(workerId);
+    if (!workerId || !entry || !entry.route) return; // unknown route -> no cell to write
+    // S-7 (round 2): a wake the bounded buffer pushes out is still recorded -- as a dropped
+    // (empty) row -- instead of vanishing silently.
+    if (pending.length >= MAP_MAX) {
+      const dropped = pending.shift();
+      _reportOutcome({ ...dropped, dropped: true }, null);
+    }
+    pending.push({
+      id: `${stamp}:${workerId}:${index}`,
+      lead,
+      cellKey: `wait-watch|default|${entry.route}`,
+      workerId,
+      decision: _string(decision.decision),
+      silent: kind === 'silent',
+      wokeOn: wokeOn || null,
+      at: nowMs,
+    });
+  });
+}
+
+// The positive control (§6.7): a worker that only ended failed after the watcher last chose to
+// keep waiting was a wake the watcher missed.
+function _recordLateEnd(call, res, nowMs) {
+  if (!WAIT_TOOLS.has(call.tool) || !res || _string(res.woke_on) !== 'terminal') return;
+  // D-2: an error body is not evidence -- no late row, no close, nothing written for it.
+  const payload = workerPayloadOf(res);
+  if (!payload || payload.error) return;
+  const workerId = _workerIdOf(call, res);
+  if (!workerId) return;
+  const entry = workerRoutes.get(workerId);
+  if (!entry || !entry.route) return;
+  const terminalStatus = _statusOf(res);
+  const label = labelLateEnd({
+    lastDecision: lastDecisionByWorker.get(workerId),
+    terminalStatus,
+  });
+  if (!label) return;
+  _reportOutcome({
+    id: `${_stamp(nowMs)}:${workerId}:late`,
+    cellKey: `wait-watch|default|${entry.route}`,
+    workerId,
+    decision: 'KEEP_WAITING',
+    silent: false,
+    wokeOn: _string(res.woke_on) || null,
+    terminalStatus,
+    late: true,
+  }, null);
+}
+
+// --- the delegation record and the exploration hand-off --------------------------------
+
+function _rememberDelegation(lead, call, res) {
+  if (call.tool !== 'walle_delegate_implementation' || !res) return;
+  const ctmSessionId = _string(res.ctm_session_id).trim();
+  if (!ctmSessionId) return;
+  workerRoutes.set(ctmSessionId, {
+    route: _string(res.route),
+    agent: _string(res.agent),
+    invocation_id: _string(res.delegation_invocation_id),
+    profile: _string(res.worker_profile),
+  });
+  workerLeads.set(ctmSessionId, lead);
+  _evict(workerRoutes, workerLeads);
+}
+
+// The lead's own agent (the cell is `explore|default|<lead provider>`). Client info is only
+// available to a caller that has it (the initialize path); the delegate's own `agent` is the
+// documented fallback.
+function _leadAgent(args, clientInfo) {
+  if (clientInfo && typeof clientInfo === 'object') return leadAgentFromClientInfo(clientInfo);
+  const agent = _string(args.agent);
+  return agent === 'codex' || agent === 'claude' ? agent : 'claude';
+}
+
+/** The wait/status variant, for the row's facts (§6.4): the recommended no-id wait has no id. */
+function _waitVariant(call) {
+  if (call.tool === 'walle_worker_status') return 'status_by_id';
+  return _string(call.args.ctm_session_id) ? 'wait_by_id' : 'wait_no_id';
+}
+
+// "The paths a tool touched are not in the status payload, so the per-tool count is the honest
+// stand-in for the log -- the card says how much of each tool the worker used, not where."
+function _toolLogOf(payload) {
+  const counts = payload && payload.tool_counts && typeof payload.tool_counts === 'object' ? payload.tool_counts : {};
+  return Object.entries(counts).map(([tool, count]) => ({ tool, path: String(count) }));
+}
+
+function _trackHandoff(call, res, clientInfo, nowMs) {
+  if (!res) return;
+  if (call.tool === 'walle_delegate_implementation') {
+    const ctmSessionId = _string(res.ctm_session_id).trim();
+    const id = _string(res.delegation_invocation_id);
+    if (!ctmSessionId || res.worker_profile !== 'review' || !id || openHandoffs.has(ctmSessionId)) return;
+    // WP-6 grades the card from the brief the helper was given. This module has no fs access (see
+    // AC-5e's source check), so it parks the delegation's `rendered_brief_path`; grade.js reads the
+    // text, bounded, when the sample is drawn. The report and the tool log arrive with the
+    // terminal read.
+    openHandoffs.set(ctmSessionId, { id, opened_at: nowMs, brief_path: _string(res.rendered_brief_path) });
+    _evict(openHandoffs, null);
+    // S-6 (round 2): the open row is addressable by worker_id and carries its facts + version, so
+    // the close path can resolve it after a restart (D-5).
+    _write('helperRulesRecordOutcome', {
+      id,
+      cell_key: `explore|default|${_leadAgent(call.args, clientInfo)}`,
+      kind: 'explore',
+      decision: 'open',
+      worker_id: ctmSessionId,
+      facts_json: JSON.stringify({
+        opened_at: nowMs,
+        harness: res.harness == null ? null : res.harness,
+        brief_path: res.rendered_brief_path || null,
+      }),
+      label_version: LABEL_VERSION,
+    });
+    return;
+  }
+  if (!WAIT_TOOLS.has(call.tool)) return;
+  // D-2: a payload with an `error` key is not terminal evidence -- it closes nothing. The route
+  // wait (no worker payload at all) has no status, so it falls through here too.
+  const payload = workerPayloadOf(res);
+  if (!payload || payload.error) return;
+  const status = _string(payload.status);
+  // D-3 (session-stops-followups-2026-10-24.html): a provisional report_ready is a live worker's
+  // interim report, not its final one -- it closes and grades nothing.
+  if (!TERMINAL_STATUSES.has(status) || _provisionalOf(res)) return;
+  const workerId = _string(payload.ctm_session_id) || _string(call.args.ctm_session_id);
+  if (!workerId || closedWorkers.has(workerId)) return;
+  // D-5: the cache is a best-effort source of opened_at/brief_path; the close itself is keyed on
+  // worker_id, so a cache miss (a restart, or eviction) still closes the row.
+  const handoff = openHandoffs.get(workerId) || null;
+  if (handoff) openHandoffs.delete(workerId);
+  closedWorkers.add(workerId);
+  _evict(closedWorkers, null);
+  const facts = factsFromPayload(payload, {
+    opened_at: handoff ? handoff.opened_at : null,
+    terminal_at: nowMs,
+    wait_variant: _waitVariant(call),
+    woke_on: _string(res.woke_on) || null,
+  });
+  // The grade card is built HERE, while the terminal payload is in scope; the grade itself waits
+  // for the row's seq, which only the close write can return.
+  const toolLog = _toolLogOf(payload);
+  _writeThen('helperRulesCloseOutcomeByWorker', [workerId, { facts }], (result) => _gradeIfSampled(result, facts, toolLog));
+}
+
+// --- the 1-in-5 spot check (WP-6, §6.5/D-19) -------------------------------------------
+
+// llm/ and brain.js are reached lazily and only from here, for the same reason the write seam
+// is: lib/ must not hold a module-top reference into llm/ or brain.js, and a test substitutes
+// them by seeding require.cache. No brain (a bare call) reads as "no pin", never as "grade
+// with whatever is cheap" (D-0).
+function _gradeDeps() {
+  const { completeForRole } = require('../../llm/model-roles');
+  let db = null;
+  let brain = null;
+  try {
+    const events = require('../brain-events');
+    db = events.getDb();
+    brain = events.getBrainCapabilities();
+  } catch {
+    // expected: no brain in this process -- readGraderModel(null) is '' -> the sample is unavailable
+    db = null;
+    brain = null;
+  }
+  return { completeForRole, db, brain };
+}
+
+// Fire-and-forget: the close already landed, so a grader outage costs a sample, never the write.
+// S-3 (round 2): the store derives the label and returns it, so "was this a hand-off?" is read
+// from `result.labelled`, and the card carries the report/log PATHS (grade.js reads them).
+function _gradeIfSampled(result, facts, toolLog) {
+  if (!result || result.closed !== true) return;
+  if (!result.labelled || result.labelled.decision !== 'handoff') return; // only an accepted hand-off
+  if (!shouldGrade(result.seq)) return; // D-12: every EXPLORE_GRADE_EVERY-th, in every cell state
+  const merged = result.facts && typeof result.facts === 'object' ? result.facts : (facts || {});
+  const card = {
+    brief_path: merged.brief_path || '',
+    report_path: merged.report_path == null ? null : merged.report_path,
+    last_message_path: merged.last_message_path == null ? null : merged.last_message_path,
+    toolLog,
+  };
+  const id = result.id;
+  let deps;
+  try {
+    deps = _gradeDeps();
+  } catch (err) {
+    // REPORT: the grade is advisory -- a missing dependency costs a sample, never the tool call.
+    _warn(`grade deps failed: ${err && err.message ? err.message : err}`);
+    return;
+  }
+  // REPORT: gradeHandoff turns a failed call into an unavailable sample, so the tail below only
+  // covers a throw from the write itself -- both are fire-and-forget by contract.
+  gradeHandoff(card, { completeForRole: deps.completeForRole, graderModel: readGraderModel(deps.db), brain: deps.brain })
+    .then((grade) => _write('helperRulesSetGrade', id, gradeToJson(grade)))
+    .catch((err) => _warn(`helperRulesSetGrade failed: ${err && err.message ? err.message : err}`));
+}
+
+// --- the entry point ------------------------------------------------------------------
+
+function _record(options) {
+  const { agentSessionId, tool, args, result, at, clientInfo } = options;
+  const lead = _leadKey(agentSessionId);
+  const nowMs = _atMs(at);
+  const call = {
+    tool: _string(tool),
+    args: args && typeof args === 'object' ? args : {},
+    at: nowMs,
+  };
+  const res = result && typeof result === 'object' ? result : null;
+
+  _expirePending(nowMs);
+  _labelPendingForLead(lead, call);
+  _rememberDelegation(lead, call, res);
+  _openWatcherOutcomes(lead, call, res, nowMs);
+  _recordLateEnd(call, res, nowMs);
+  _trackHandoff(call, res, clientInfo, nowMs);
+
+  const ring = callsByLead.get(lead) || [];
+  ring.push(call);
+  while (ring.length > CALL_RING) ring.shift();
+  callsByLead.set(lead, ring);
+  _evict(callsByLead, null);
+  return call;
+}
+
+/**
+ * Remember one lead tool call and label whatever the previous one left pending.
+ * @param {{agentSessionId?:string, tool:string, args?:object, result?:object, at?:number|string|Date,
+ *          clientInfo?:object}} options agentSessionId is the injected parent_agent_session_id;
+ *          clientInfo is optional (the initialize path) and only decides the explore cell's agent.
+ * @returns {void} never throws -- a labelling side path may not fail the lead's tool call.
+ */
+function recordLeadToolCall(options = {}) {
+  try {
+    _record(options);
+  } catch (err) {
+    // REPORT: see above -- the call itself already succeeded by the time this runs.
+    _warn(`recordLeadToolCall failed: ${err && err.message ? err.message : err}`);
+  }
+}
+
+module.exports = {
+  ANONYMOUS_LEAD,
+  CALL_RING,
+  PENDING_TTL_MS,
+  TERMINAL_STATUSES,
+  WAIT_TOOLS,
+  WARN_THROTTLE_MS,
+  _resetForTests,
+  leadWorkersOf,
+  recordLeadToolCall,
+  workerRouteOf,
+};