total-recall-brain 3.41.4 → 3.41.6

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate-adapters/openclaw.mjs

@@ -0,0 +1,173 @@
+/**
+ * OpenClaw Messaging Bridge hook adapter.
+ * Official doc: https://docs.openclaw.ai/plugins/hooks
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const ACK_COMMAND = 'total-recall tr-preflight --ack --task "<task>" --action read,edit,test';
+
+export const openclawAdapter = {
+  id: 'openclaw',
+  level: 'enforced',
+  source: {
+    url: 'https://docs.openclaw.ai/plugins/hooks',
+    retrieved: '2026-11-04',
+    note: 'OpenClaw before_tool_call plugin hooks with fail-closed timeout'
+  },
+  limits: [
+    'OpenClaw before_tool_call fails closed on timeout or exception',
+    'Returns { block: true, blockReason: reason } on deny'
+  ],
+
+  parse(input = {}) {
+    const event = input.event || 'before_tool_call';
+    const toolName = input.toolName || input.tool_name || input.tool || '';
+    const params = input.params || input.args || {};
+    const cwd = input.cwd || process.cwd();
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (toolName === 'execute' || toolName === 'Bash' || toolName === 'shell') {
+      tool = 'shell';
+      command = params.command || params.cmd || '';
+    } else if (toolName === 'write' || toolName === 'edit' || toolName === 'Edit' || toolName === 'Write') {
+      tool = 'write';
+      filePath = params.path || params.file_path || '';
+    } else if (toolName === 'read' || toolName === 'Read') {
+      tool = 'read';
+      filePath = params.path || params.file_path || '';
+    }
+
+    return {
+      event,
+      tool,
+      command,
+      path: filePath,
+      cwd,
+      raw: input
+    };
+  },
+
+  emit(decision, event, cwd = process.cwd()) {
+    if (decision?.decision === 'allow') {
+      const payload = { block: false };
+      return { stdout: `${JSON.stringify(payload)}\n`, exitCode: 0 };
+    }
+
+    const reason = decision?.reason || `TR-PREFLIGHT gate: action denied. Run: ${decision?.fix || ACK_COMMAND}`;
+    const payload = {
+      block: true,
+      blockReason: reason,
+      fix: decision?.fix || ACK_COMMAND
+    };
+    return { stdout: `${JSON.stringify(payload)}\n`, exitCode: 2 };
+  },
+
+  async run({ stdin, decideWith }) {
+    const parsed = this.parse(stdin);
+    const decision = decideWith({
+      tool: parsed.tool,
+      command: parsed.command,
+      path: parsed.path,
+      cwd: parsed.cwd
+    });
+    return this.emit(decision, parsed.event, parsed.cwd);
+  },
+
+  install({ home = os.homedir(), dryRun = false, remove = false, off = false } = {}) {
+    const isRemove = remove || off;
+    const openclawDir = path.join(home, '.openclaw');
+    const hooksPath = path.join(openclawDir, 'hooks.json');
+    const added = [];
+    const removed = [];
+
+    let hooksConfig = { hooks: {} };
+    if (fs.existsSync(hooksPath)) {
+      try {
+        hooksConfig = JSON.parse(fs.readFileSync(hooksPath, 'utf8') || '{}');
+      } catch (err) {
+        throw new Error(`${hooksPath} is not valid JSON; fix it before installing hooks: ${err.message}`);
+      }
+    }
+    hooksConfig.hooks = hooksConfig.hooks || {};
+    hooksConfig.hooks.before_tool_call = hooksConfig.hooks.before_tool_call || [];
+
+    if (isRemove) {
+      const beforeLen = hooksConfig.hooks.before_tool_call.length;
+      hooksConfig.hooks.before_tool_call = hooksConfig.hooks.before_tool_call.filter(e =>
+        !String(e.command || '').includes('preflight')
+      );
+      if (hooksConfig.hooks.before_tool_call.length < beforeLen) {
+        removed.push('managed before_tool_call gate');
+      }
+      if (!dryRun && fs.existsSync(hooksPath)) {
+        fs.writeFileSync(hooksPath, `${JSON.stringify(hooksConfig, null, 2)}\n`);
+      }
+      return { settings: hooksPath, added: [], removed };
+    }
+
+    const gateCommand = 'total-recall preflight gate --harness openclaw';
+    const hasPreTool = hooksConfig.hooks.before_tool_call.some(e =>
+      String(e.command || '').includes('preflight gate --harness openclaw')
+    );
+
+    if (!hasPreTool) {
+      hooksConfig.hooks.before_tool_call.push({
+        matcher: '*',
+        command: gateCommand,
+        timeout: 10
+      });
+      added.push('managed before_tool_call gate');
+    }
+
+    if (!dryRun && added.length) {
+      fs.mkdirSync(openclawDir, { recursive: true });
+      if (fs.existsSync(hooksPath)) {
+        fs.copyFileSync(hooksPath, `${hooksPath}.bak-total-recall`);
+      }
+      fs.writeFileSync(hooksPath, `${JSON.stringify(hooksConfig, null, 2)}\n`);
+    }
+
+    return { settings: hooksPath, added };
+  },
+
+  verify({ home = os.homedir() } = {}) {
+    const hooksPath = path.join(home, '.openclaw', 'hooks.json');
+    let installed = false;
+    if (fs.existsSync(hooksPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(hooksPath, 'utf8') || '{}');
+        const preHooks = config.hooks?.before_tool_call || [];
+        installed = preHooks.some(e => String(e.command || '').includes('preflight gate --harness openclaw'));
+      } catch { /* unparseable */ }
+    }
+
+    const syntheticDeniedCall = {
+      event: 'before_tool_call',
+      toolName: 'execute',
+      params: { command: 'rm -rf /tmp/foo' },
+      cwd: '/nonexistent-directory-without-receipt'
+    };
+
+    const out = this.emit(
+      { decision: 'deny', reason: 'receipt missing', fix: ACK_COMMAND },
+      'before_tool_call',
+      syntheticDeniedCall.cwd
+    );
+
+    const exercised = out.exitCode === 2 && out.stdout.includes('"block":true');
+
+    return {
+      installed,
+      exercised,
+      level: 'enforced',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default openclawAdapter;

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate-adapters/pi.mjs

@@ -0,0 +1,129 @@
+/**
+ * Pi Coding Agent extension hook adapter.
+ * Official doc: https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/docs/extensions.md
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const ACK_COMMAND = 'total-recall tr-preflight --ack --task "<task>" --action read,edit,test';
+
+export const piAdapter = {
+  id: 'pi',
+  level: 'enforced (unverified live)',
+  source: {
+    url: 'https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/docs/extensions.md',
+    retrieved: '2026-11-04',
+    note: 'Pi Coding Agent tool_call extensions in ~/.pi/agent/extensions/'
+  },
+  limits: [
+    'Pi loaded extensions must fail closed explicitly',
+    'Returns { block: true, reason } on denied calls'
+  ],
+
+  parse(input = {}) {
+    const event = input.event || 'tool_call';
+    const toolName = input.toolName || input.tool || '';
+    const toolInput = input.input || input.params || {};
+    const cwd = input.cwd || process.cwd();
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (toolName === 'execute' || toolName === 'Bash' || toolName === 'shell') {
+      tool = 'shell';
+      command = toolInput.command || toolInput.cmd || '';
+    } else if (toolName === 'edit' || toolName === 'write' || toolName === 'patch') {
+      tool = 'write';
+      filePath = toolInput.path || toolInput.file || '';
+    } else if (toolName === 'read') {
+      tool = 'read';
+      filePath = toolInput.path || toolInput.file || '';
+    }
+
+    return {
+      event,
+      tool,
+      command,
+      path: filePath,
+      cwd,
+      raw: input
+    };
+  },
+
+  emit(decision, event, cwd = process.cwd()) {
+    if (decision?.decision === 'allow') {
+      const payload = { block: false };
+      return { stdout: `${JSON.stringify(payload)}\n`, exitCode: 0 };
+    }
+
+    const reason = decision?.reason || `TR-PREFLIGHT gate: action denied. Run: ${decision?.fix || ACK_COMMAND}`;
+    const payload = {
+      block: true,
+      reason,
+      fix: decision?.fix || ACK_COMMAND
+    };
+    return { stdout: `${JSON.stringify(payload)}\n`, exitCode: 2 };
+  },
+
+  async run({ stdin, decideWith }) {
+    const parsed = this.parse(stdin);
+    const decision = decideWith({
+      tool: parsed.tool,
+      command: parsed.command,
+      path: parsed.path,
+      cwd: parsed.cwd
+    });
+    return this.emit(decision, parsed.event, parsed.cwd);
+  },
+
+  install({ home = os.homedir(), dryRun = false } = {}) {
+    const piDir = path.join(home, '.pi', 'agent', 'extensions');
+    const hookPath = path.join(piDir, 'total-recall-preflight.json');
+    const added = [];
+
+    const hookDef = {
+      name: 'total-recall-preflight',
+      command: 'total-recall preflight gate --harness pi',
+      timeout: 5
+    };
+
+    if (!dryRun) {
+      fs.mkdirSync(piDir, { recursive: true });
+      fs.writeFileSync(hookPath, `${JSON.stringify(hookDef, null, 2)}\n`);
+      added.push('managed Pi extension gate');
+    }
+
+    return { settings: hookPath, added };
+  },
+
+  verify({ home = os.homedir() } = {}) {
+    const hookPath = path.join(home, '.pi', 'agent', 'extensions', 'total-recall-preflight.json');
+    const installed = fs.existsSync(hookPath);
+
+    const syntheticDeniedCall = {
+      event: 'tool_call',
+      toolName: 'execute',
+      input: { command: 'rm -rf /tmp/foo' },
+      cwd: '/nonexistent-directory-without-receipt'
+    };
+
+    const out = this.emit(
+      { decision: 'deny', reason: 'receipt missing', fix: ACK_COMMAND },
+      'tool_call',
+      syntheticDeniedCall.cwd
+    );
+
+    const exercised = out.exitCode === 2 && out.stdout.includes('"block":true');
+
+    return {
+      installed,
+      exercised,
+      level: 'enforced (unverified live)',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default piAdapter;

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate.mjs

@@ -0,0 +1,12 @@
+/** Run the repository's own quality gates through the code-quality plugin. No configured gate is not a pass. */
+import { spawnSync } from 'node:child_process';
+
+export function runQualityGate(directory, { tier = 'fast', runner = spawnSync, timeoutMs = 600000 } = {}) {
+  const result = runner(process.env.TOTAL_RECALL_BIN || 'total-recall', ['code-quality-check', '--tier', tier, '--json'], { cwd: directory, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`.trim();
+  if (result.error || result.status === null) return { status: 'unavailable', passed: false, tier, summary: `The gate did not run: ${result.error?.message || 'terminated'}` };
+  let report = null;
+  try { report = JSON.parse(result.stdout); } catch { /* a text report */ }
+  if (/No code-quality state/.test(report?.error || output)) return { status: 'unconfigured', passed: false, tier, summary: String(report?.error || output).slice(0, 500) };
+  return { status: result.status === 0 ? 'passed' : 'failed', passed: result.status === 0, tier, summary: output.slice(-2000), report };
+}

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/json-reply.mjs

@@ -0,0 +1,22 @@
+/** Agents wrap their answer in prose and code. Find the last well-formed object that carries the expected key. */
+export function lastJsonWith(text, key) {
+  const source = String(text || '');
+  for (let start = source.lastIndexOf('{'); start >= 0; start = source.lastIndexOf('{', start - 1)) {
+    let depth = 0, inString = false;
+    for (let i = start; i < source.length; i += 1) {
+      const c = source[i];
+      if (inString) { if (c === '\\') i += 1; else if (c === '"') inString = false; continue; }
+      if (c === '"') inString = true;
+      else if (c === '{') depth += 1;
+      else if (c === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          try { const value = JSON.parse(source.slice(start, i + 1)); if (value && Object.hasOwn(value, key)) return value; } catch { /* keep looking */ }
+          break;
+        }
+      }
+    }
+    if (start === 0) break;
+  }
+  return null;
+}

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/learner.mjs

@@ -1,90 +1,92 @@
 /**
- * Meta Harness Self-Learning Subsystem
- * Ingests run execution receipts, updates the empirical scorecard,
- * and proposes friction-reducing rule/memory proposals.
+ * Execution receipts and the learning loop.
+ * Receipts are an append-only SSSS ledger. Scorecards, quota walls and proposals fold from it.
  */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
+import { spawnSync } from 'node:child_process';
 import { computeEmpiricalScorecard } from '../capability/index.mjs';
+import { receiptsFile } from './paths.mjs';
 
-function getLedgerPath() {
-  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
-  const baseDir = path.join(home, '.agent', 'skills', 'total-recall');
-  fs.mkdirSync(baseDir, { recursive: true });
-  return path.join(baseDir, 'meta-harness-runs.json');
+async function store() {
+  const { PluginStateStore } = await import('./ssss-store.mjs');
+  return new PluginStateStore(receiptsFile(), 'meta-harness');
 }
+export const readReceipts = async () => (await store()).read([]);
 
-/**
- * Record a run execution receipt
- */
-export function recordRunReceipt(receipt = {}) {
-  const ledgerPath = getLedgerPath();
-  let entries = [];
-  if (fs.existsSync(ledgerPath)) {
-    try {
-      entries = JSON.parse(fs.readFileSync(ledgerPath, 'utf8'));
-    } catch {
-      entries = [];
-    }
-  }
-
+export async function recordRunReceipt(receipt = {}) {
+  if (!receipt.harness) throw new Error('A run receipt must name its harness');
   const entry = {
-    id: receipt.id || `run-${Date.now()}`,
+    id: receipt.id || `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
     timestamp: new Date().toISOString(),
-    harness: receipt.harness || 'agy',
-    task: receipt.task || '',
-    complexityScore: receipt.complexityScore || 50,
-    success: receipt.success !== false,
+    harness: receipt.harness,
+    role: receipt.role || null,
+    node: receipt.node || 'local',
+    task: String(receipt.task || '').slice(0, 300),
+    complexityScore: receipt.complexityScore ?? null,
+    success: receipt.success === true,
     durationMs: receipt.durationMs || 0,
+    failureKind: receipt.failureKind || null,
+    error: receipt.error ? String(receipt.error).slice(0, 500) : null,
+    resetsAt: receipt.resetsAt || null,
+    gate: receipt.gate || null,
     escalatedFrom: receipt.escalatedFrom || null,
-    failures: receipt.failures || {}
   };
-
-  entries.push(entry);
-  // Keep last 1,000 runs
-  if (entries.length > 1000) {
-    entries = entries.slice(-1000);
-  }
-
-  fs.writeFileSync(ledgerPath, JSON.stringify(entries, null, 2), 'utf8');
-  return { ok: true, recorded: entry.id, totalRuns: entries.length };
+  (await store()).append(entry);
+  return entry;
 }
 
-/**
- * Read learning summary and generate memory/friction proposals
- */
-export function learnFromHistory() {
-  const ledgerPath = getLedgerPath();
-  let entries = [];
-  if (fs.existsSync(ledgerPath)) {
-    try {
-      entries = JSON.parse(fs.readFileSync(ledgerPath, 'utf8'));
-    } catch {
-      entries = [];
-    }
+/** A harness is walled from its last quota failure until the reported reset, or until a later success proves it clear. */
+export function activeQuotaWalls(entries = [], now = Date.now(), unknownResetMs = 60 * 60 * 1000) {
+  const latest = new Map();
+  for (const run of entries) {
+    if (run.success || run.failureKind === 'quota') latest.set(run.harness, run);
   }
+  const walls = {};
+  for (const [harness, run] of latest) {
+    if (run.success) continue;
+    const observed = Date.parse(run.timestamp);
+    const until = run.resetsAt ? Date.parse(run.resetsAt) : observed + unknownResetMs;
+    if (until > now) walls[harness] = { until: new Date(until).toISOString(), resetReported: Boolean(run.resetsAt), observedAt: run.timestamp, message: run.error };
+  }
+  return walls;
+}
 
-  const scorecard = computeEmpiricalScorecard(entries);
+export function proposalsFrom(scorecard, entries = []) {
   const proposals = [];
-
-  // Identify harnesses with elevated failure rates (>25%)
   for (const [harness, stats] of Object.entries(scorecard)) {
-    if (stats.total >= 3 && stats.passRate < 75) {
-      proposals.push({
-        id: `proposal-deprecate-or-escalate-${harness}`,
-        targetHarness: harness,
-        reason: `Pass rate for ${harness} is ${stats.passRate}% over ${stats.total} runs.`,
-        recommendation: `Auto-escalate ${harness} to frontier model or apply strict preflight gate.`
-      });
-    }
+    if (stats.total >= 3 && stats.passRate < 75) proposals.push({
+      id: `meta-harness-low-pass-${harness}`, targetHarness: harness,
+      reason: `${harness} passed ${stats.passRate}% of ${stats.total} attributable runs.`,
+      recommendation: `Route complex work away from ${harness}, or require a gate before accepting its output.`,
+    });
   }
+  const gateFailures = new Map();
+  for (const run of entries) if (run.failureKind === 'gate') gateFailures.set(run.harness, (gateFailures.get(run.harness) || 0) + 1);
+  for (const [harness, count] of gateFailures) if (count >= 3) proposals.push({
+    id: `meta-harness-gate-failures-${harness}`, targetHarness: harness,
+    reason: `${harness} output failed quality gates ${count} times.`,
+    recommendation: `Review recent ${harness} branches for a recurring defect and record the rule that prevents it.`,
+  });
+  return proposals;
+}
 
-  return {
-    ok: true,
-    totalHistoryRuns: entries.length,
-    scorecard,
-    proposals
-  };
+/** A harness whose last run failed for a missing login or key stays out of the pool for an hour, then gets another chance. */
+export function activeCredentialBlocks(entries = [], now = Date.now(), holdMs = 60 * 60 * 1000) {
+  const latest = new Map();
+  for (const run of entries) if (run.success || run.failureKind === 'auth') latest.set(run.harness, run);
+  const blocks = {};
+  for (const [harness, run] of latest) if (!run.success && Date.parse(run.timestamp) + holdMs > now) blocks[harness] = { observedAt: run.timestamp, message: run.error };
+  return blocks;
+}
+
+/** With `emit`, proposals are written through the memory owner. A failed write is reported, never hidden. */
+export async function learnFromHistory({ emit = false, runner = spawnSync } = {}) {
+  const entries = await readReceipts();
+  const scorecard = computeEmpiricalScorecard(entries);
+  const proposals = proposalsFrom(scorecard, entries);
+  const emitted = [];
+  if (emit) for (const proposal of proposals) {
+    const result = runner(process.env.TOTAL_RECALL_BIN || 'total-recall', ['remember', 'facts', `${proposal.reason} ${proposal.recommendation}`, '--project', '--tags', `meta-harness,${proposal.id}`], { encoding: 'utf8', timeout: 30000 });
+    emitted.push({ id: proposal.id, ok: result.status === 0, error: result.status === 0 ? undefined : String(result.stderr || result.error || 'remember failed').slice(0, 300) });
+  }
+  return { ok: emitted.every(row => row.ok), totalHistoryRuns: entries.length, scorecard, walls: activeQuotaWalls(entries), credentialBlocks: activeCredentialBlocks(entries), proposals, ...(emit ? { emitted } : {}) };
 }