total-recall-brain 3.44.0 → 3.45.0

package/scaffold/.agent/skills/total-recall/plugins/automations/cli.mjs

@@ -0,0 +1,121 @@
+import { meshAutomationInventory, filterInventory } from './inventory.mjs';
+import { cancelAutomation, SOURCES } from './adapters.mjs';
+import { spawnSync } from 'node:child_process';
+
+export const HELP = `Usage: total-recall automations <command> [options]
+
+Commands:
+  list                 List automation records and source coverage across the mesh
+  status               Report node/source coverage and observed automation states
+  show <id>            Inspect one source-owned automation record
+  cancel <id>          Cancel a pending local durable task through its owner
+  dream --all-brains   Run dream, including decay, for every brain on this node
+
+Options:
+  --local              Inspect this node only (also used by authenticated peers)
+  --node <id|hostname>  Select one known mesh node
+  --source <source>    Filter records by source
+  --trigger <kind>     Filter records by trigger kind
+  --state <state>      Filter records by observed state
+  --json               Machine-readable output (also the default)
+  --help, -h           Show this help
+
+Sources: ${SOURCES.join(', ')}
+Declarations, runner availability and observed outcomes remain separate.
+Unsupported or failed sources are reported explicitly; they are never empty success.`;
+
+export function parseArgs(argv) {
+  const args = argv[2] === 'automations' ? argv.slice(3) : [...argv];
+  if (!args.length || args.includes('--help') || args.includes('-h')) return { help: true };
+  const command = args.shift();
+  if (!['list', 'status', 'show', 'cancel', 'dream'].includes(command)) throw new Error(`Unknown command: ${command}`);
+  if (command === 'dream') {
+    if (args.filter(arg => arg === '--all-brains').length !== 1 || args.some(arg => !['--all-brains', '--json'].includes(arg))) {
+      throw new Error('dream requires --all-brains and accepts only --json');
+    }
+    return { command };
+  }
+  const result = { command, filters: {}, localOnly: false };
+  if (['show', 'cancel'].includes(command)) {
+    result.id = args.shift(); if (!result.id || !/^[a-z-]+:[a-f0-9]{20}$/.test(result.id)) throw new Error('A valid automation id is required');
+  }
+  while (args.length) {
+    const flag = args.shift();
+    if (flag === '--json') continue;
+    if (flag === '--local') { result.localOnly = true; continue; }
+    const name = { '--node': 'node', '--source': 'source', '--trigger': 'trigger', '--state': 'state' }[flag];
+    if (!name) throw new Error(`Unknown option: ${flag}`);
+    const value = args.shift(); if (!value || value.startsWith('-')) throw new Error(`Missing value for ${flag}`);
+    if (result.filters[name]) throw new Error(`Duplicate option: ${flag}`);
+    result.filters[name] = value;
+  }
+  if (result.filters.source && !SOURCES.includes(result.filters.source)) throw new Error('Unknown source');
+  if (command === 'cancel' && (Object.keys(result.filters).length || result.localOnly)) throw new Error('cancel accepts only a local automation id and --json');
+  return result;
+}
+
+/** Core owns dream execution. Check support before an old core can ignore the flag. */
+export function runDream(spawn = spawnSync) {
+  const options = { shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024, windowsHide: true };
+  const failure = (error, child = {}, results = []) => ({
+    ok: false, exit_code: Number.isInteger(child.status) && child.status !== 0 ? child.status : 1,
+    child_exit_code: child.status ?? null, signal: child.signal || null, results, error,
+  });
+  try {
+    const help = spawn('total-recall', ['dream', '--help'], options);
+    if (help.error || help.signal || help.status !== 0) return failure(`Cannot check core dream support: ${help.error?.message || help.stderr || help.signal || 'help failed'}`, help);
+    if (!String(help.stdout).includes('--all-brains')) return failure('Core dream does not support --all-brains. Update Total Recall before this task can run.', help);
+    const child = spawn('total-recall', ['dream', '--all-brains', '--json'], { ...options, timeout: 1800000 });
+    if (child.error || child.signal) return failure(`Core dream did not complete: ${child.error?.message || child.signal}`, child);
+    let report;
+    try {
+      report = JSON.parse(child.stdout);
+    } catch {
+      // Core log lines may surround one JSON report.
+      const reports = String(child.stdout || '').split('\n').flatMap(line => {
+        try { const value = JSON.parse(line); return Array.isArray(value) || Array.isArray(value?.results) || Array.isArray(value?.brains) ? [value] : []; } catch { return []; }
+      });
+      if (reports.length === 1) report = reports[0];
+    }
+    const results = Array.isArray(report) ? report : report?.results ?? report?.brains;
+    if (!Array.isArray(results) || !results.length || results.some(result => !result || typeof result !== 'object' || Array.isArray(result)
+      || !(typeof result.ok === 'boolean' || typeof result.success === 'boolean' || ['ok', 'success', 'completed', 'failed', 'error', 'skipped'].includes(result.status) || ['ok', 'success', 'completed', 'failed', 'error', 'skipped'].includes(result.state)))) {
+      return failure(`Core dream returned no per-brain results (exit ${child.status}). Update Total Recall if --all-brains is unavailable. ${String(child.stderr || '').trim()}`.trim(), child);
+    }
+    if (child.status !== 0 || report?.ok === false || report?.success === false || results.some(result => result.ok === false || result.success === false || result.error
+      || (Number.isInteger(result.exit_code) && result.exit_code !== 0) || ['failed', 'error'].includes(result.status) || ['failed', 'error'].includes(result.state))) {
+      return failure(`Core dream failed (exit ${child.status}). ${String(child.stderr || '').trim()}`.trim(), child, results);
+    }
+    return { ok: true, exit_code: 0, child_exit_code: 0, results };
+  } catch (error) {
+    return failure(`Cannot run core dream: ${error.message}`);
+  }
+}
+
+export async function run(argv = [], dependencies = {}) {
+  const parsed = parseArgs(argv), write = dependencies.write || (output => process.stdout.write(output));
+  if (parsed.help) { write(`${HELP}\n`); return; }
+  if (parsed.command === 'dream') {
+    const result = runDream(dependencies.spawnSync);
+    write(`${JSON.stringify(result)}\n`);
+    if (!result.ok) (dependencies.setExitCode || (code => { process.exitCode = code; }))(result.exit_code);
+    return result;
+  }
+  const root = dependencies.packageRoot || process.env.TR_PACKAGE_ROOT;
+  if (!root) throw new Error('TR_PACKAGE_ROOT is required');
+  if (parsed.command === 'cancel') {
+    const result = await (dependencies.cancel || cancelAutomation)(root, parsed.id);
+    write(`${JSON.stringify(result)}\n`); return result;
+  }
+  let inventory = await (dependencies.inventory || meshAutomationInventory)(root, { localOnly: parsed.localOnly });
+  inventory = filterInventory(inventory, parsed.filters);
+  let result = inventory;
+  if (parsed.command === 'show') {
+    const records = inventory.nodes.flatMap(node => node.automations).filter(record => record.id === parsed.id);
+    if (records.length !== 1) throw new Error(records.length ? 'Automation id is ambiguous' : 'Automation not found');
+    result = { schema_version: 1, checked_at: inventory.checked_at, automation: records[0] };
+  }
+  if (parsed.command === 'status') result = { ...inventory, nodes: inventory.nodes.map(node => ({ ...node, counts: node.automations.reduce((counts, record) => ({ ...counts, [record.state]: (counts[record.state] || 0) + 1 }), {}), automations: undefined })) };
+  write(`${JSON.stringify(result)}\n`); return result;
+}
+export default run;

package/{src/core/plugin-cron.mjs → scaffold/.agent/skills/total-recall/plugins/automations/cron.mjs}

@@ -1,4 +1,4 @@
-/** Pure cron parsing shared by plugin authoring and scheduling. */
+/** Five-field cron parsing and matching for manifest plugin tasks. */
 const FIELD_RANGES = [
   [0, 59], // minute
   [0, 23], // hour
@@ -53,5 +53,3 @@ export function cronMatches(cron, date) {
   if (cron.dowStar) return domOk;
   return domOk || dowOk;
 }
-
-

package/scaffold/.agent/skills/total-recall/plugins/automations/inventory.mjs

@@ -0,0 +1,88 @@
+import os from 'node:os';
+import { collectLocalAutomations, coreModule, SOURCES, scheduledTasks, recordId } from './adapters.mjs';
+export { scheduledTasks } from './adapters.mjs';
+
+const MAX_PEER_BYTES = 4 * 1024 * 1024;
+export function parseInventoryOutput(output) {
+  if (typeof output !== 'string' || Buffer.byteLength(output) > MAX_PEER_BYTES) throw new Error('Invalid inventory output');
+  try { return JSON.parse(output); } catch {
+    // Host logs may surround command output. Accept one versioned inventory,
+    // never guess between multiple command results or parse a logger payload.
+    const values = output.trim().split('\n').flatMap(line => { try { const value = JSON.parse(line); return value?.schema_version === 1 && Array.isArray(value.nodes) ? [value] : []; } catch { return []; } });
+    if (values.length !== 1) throw new Error('Expected one versioned inventory result');
+    return values[0];
+  }
+}
+const unavailableCoverage = (status, checked_at) => SOURCES.map(source => ({ source, status, checked_at }));
+function verifyLocalResult(value) {
+  if (!value || !Array.isArray(value.automations) || !Array.isArray(value.coverage)) throw new Error('Invalid local inventory');
+  if (value.automations.length > 10000 * SOURCES.length) throw new Error('Peer inventory exceeds record limit');
+  const statuses = new Set(['ok', 'partial', 'unsupported', 'disabled', 'error', 'unauthorized', 'offline']);
+  for (const coverage of value.coverage) if (!SOURCES.includes(coverage.source) || !statuses.has(coverage.status)) throw new Error('Invalid peer coverage');
+  for (const record of value.automations) if (typeof record.id !== 'string' || !SOURCES.includes(record.source) || typeof record.name !== 'string') throw new Error('Invalid peer automation');
+  return value;
+}
+function nodeResult(base, value) {
+  const missing = SOURCES.filter(source => !value.coverage.some(item => item.source === source));
+  const coverage = [...value.coverage, ...missing.map(source => ({ source, status: 'unsupported', checked_at: base.checked_at, error: 'Peer did not report this source' }))];
+  // Remote mutation is never advertised through a local-only control.
+  const automations = value.automations.map(record => ({ ...record, node_id: base.node_id, actions: base.self ? record.actions || [] : [] }));
+  return { ...base, status: coverage.every(source => ['ok', 'disabled'].includes(source.status)) ? 'ok' : 'partial', automations, coverage };
+}
+
+/** The plugin owns composition; every source and peer failure remains visible. */
+export async function meshAutomationInventory(packageRoot, options = {}) {
+  const checked_at = new Date().toISOString();
+  const mesh = options.mesh || await coreModule(packageRoot, 'mesh');
+  const self = options.self || mesh.getMeshSelf?.() || { hostname: os.hostname(), self: true };
+  const selfId = self.ip || self.hostname || os.hostname();
+  let nodes = options.localOnly ? [{ ...self, self: true }] : options.nodes || mesh.listEnrichedMeshNodes();
+  if (!nodes.some(node => node.self || (node.ip && node.ip === self.ip))) nodes = [{ ...self, self: true }, ...nodes];
+  nodes = [...new Map(nodes.map(node => [node.ip || node.hostname, node])).values()];
+  const local = options.local || await collectLocalAutomations(packageRoot, { ...options, node_id: selfId });
+  const execPeer = options.execPeer || mesh.execMeshCommand;
+  let authorization = options.authorization;
+  if (!options.localOnly && authorization === undefined) {
+    try { authorization = await (await coreModule(packageRoot, 'mesh-auth')).getMeshSyncAuthorization(); } catch { authorization = null; }
+  }
+  const peerUrl = options.peerUrl || (await coreModule(packageRoot, 'plugin-peers')).meshPeerUrl;
+  const fetchImpl = options.fetchImpl || (await coreModule(packageRoot, 'throttled-fetch')).throttledFetch;
+  const records = await Promise.all(nodes.map(async node => {
+    const node_id = node.ip || node.hostname;
+    const base = { node_id, hostname: node.hostname, ip: node.ip, self: Boolean(node.self || node_id === selfId), online: Boolean(node.self || node.online), checked_at, automations: [], coverage: [] };
+    if (base.self) return nodeResult(base, verifyLocalResult(local));
+    const unavailable = (status, error) => ({ ...base, status, ...(error ? { error } : {}), coverage: unavailableCoverage(status === 'unreachable' ? 'error' : status, checked_at) });
+    if (!node.online) return unavailable('offline');
+    const port = node.brain_port || Number(process.env.TR_SERVER_PORT || process.env.PORT || 3000);
+    try {
+      if (execPeer) {
+        try {
+          // Mesh owns the authenticated transport. The command is fixed and read-only.
+          // A mesh-sync token is not a PAT for the generic plugin-run HTTP route.
+          const result = await execPeer(node_id, 'total-recall automations list --local --json', { timeoutMs: 15000 });
+          if (result.success && result.exitCode === 0) {
+            const inventory = parseInventoryOutput(result.stdout);
+            if (inventory.schema_version !== 1 || !Array.isArray(inventory.nodes) || inventory.nodes.length !== 1 || inventory.nodes[0].self !== true) throw new Error('Unsupported peer inventory');
+            return nodeResult(base, verifyLocalResult(inventory.nodes[0]));
+          }
+        } catch { /* Retain metadata through its separate mesh-auth contract below. */ }
+      }
+      if (!authorization) return unavailable('unauthorized', 'Full peer inventory is unavailable; mesh metadata authorization is unavailable');
+      // Old or unreachable CLI hosts may still expose plugin declarations.
+      const fallback = await fetchImpl(peerUrl(node.ip, '/api/mesh/plugins/installed', port), { headers: { Authorization: authorization } }, 5000);
+      if (!fallback.ok) return unavailable(fallback.status === 404 ? 'unsupported' : [401, 403].includes(fallback.status) ? 'unauthorized' : 'error', `HTTP ${fallback.status}`);
+      const data = await fallback.json();
+      if (!Array.isArray(data.plugins)) throw new Error('Invalid legacy peer response');
+      return nodeResult(base, { automations: scheduledTasks(data.plugins, { node_id }), coverage: SOURCES.map(source => ({ source, status: source === 'plugin-tasks' ? 'partial' : 'unsupported', checked_at,
+        error: source === 'plugin-tasks' ? 'Peer metadata reports declarations only; placement and outcome evidence may be missing' : 'Full peer inventory is unavailable' })) });
+    } catch (error) { return unavailable('unreachable', error.name === 'SyntaxError' ? 'Invalid peer JSON' : error.message); }
+  }));
+  return { schema_version: 1, checked_at, complete: records.every(node => node.status === 'ok'), nodes: records };
+}
+
+export function filterInventory(inventory, filters = {}) {
+  let nodes = inventory.nodes;
+  if (filters.node) nodes = nodes.filter(node => [node.node_id, node.hostname, node.ip].includes(filters.node));
+  if (filters.node && !nodes.length) throw new Error('Unknown node');
+  return { ...inventory, nodes: nodes.map(node => ({ ...node, automations: node.automations.filter(record => (!filters.source || record.source === filters.source) && (!filters.trigger || record.trigger?.kind === filters.trigger) && (!filters.state || record.state === filters.state)) })) };
+}