total-recall-brain 3.40.6 → 3.41.0

package/src/core/testing/plugin-fixture.mjs

@@ -0,0 +1,69 @@
+/**
+ * Fixture manifests for specs that exercise plumbing rather than card design.
+ *
+ * Every real plugin has a bespoke card face declared in `ui.elements[]`, and the
+ * validator enforces it. Specs that install, copy, vendor, discover or compile a
+ * plugin still need a manifest that satisfies that contract, or they fail on a
+ * rule they are not testing. This module supplies the smallest honest face so
+ * those specs keep asserting what they mean to assert.
+ *
+ * The face here is deliberately generic and exists only in tests. Production
+ * plugin UI is always hand-authored per plugin (invariants-b6e8fcac).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const nodeFs = fs;
+const nodePath = path;
+
+/** The smallest valid card face. Declared once, as every plugin declares one. */
+export const FIXTURE_CARD_FACE = Object.freeze({
+  design_tokens: 'ui/DESIGN.md',
+  elements: [
+    {
+      id: 'card',
+      kind: 'card',
+      tag: 'tr-fixture-card',
+      module: 'ui/card.js',
+      description: 'Fixture card face',
+    },
+  ],
+});
+
+/** Source of the element module referenced by FIXTURE_CARD_FACE. */
+export const FIXTURE_CARD_SOURCE = 'export const tag = "tr-fixture-card";\n';
+
+/**
+ * Merge a bespoke face into a fixture manifest.
+ *
+ * Pass `ui: null` to omit the face deliberately, e.g. when asserting that a
+ * plugin without one is rejected.
+ */
+export function withFixtureFace(manifest = {}) {
+  if (manifest.ui === null) {
+    const { ui: _omitted, ...rest } = manifest;
+    return rest;
+  }
+  return { ...manifest, ui: manifest.ui ?? { ...FIXTURE_CARD_FACE } };
+}
+
+/**
+ * Write `plugin.json` for a fixture plugin, declaring a face unless the manifest
+ * explicitly opts out with `ui: null`.
+ *
+ * Returns the manifest that was written.
+ */
+export function writeFixturePlugin(pluginDir, manifest, { fs = nodeFs, path = nodePath } = {}) {
+  const written = withFixtureFace(manifest);
+  nodeFs.writeFileSync(
+    nodePath.join(pluginDir, 'plugin.json'),
+    JSON.stringify(written, null, 2),
+  );
+  if (written.ui?.elements?.length) {
+    const uiDir = nodePath.join(pluginDir, 'ui');
+    nodeFs.mkdirSync(uiDir, { recursive: true });
+    nodeFs.writeFileSync(nodePath.join(uiDir, 'card.js'), FIXTURE_CARD_SOURCE);
+    nodeFs.writeFileSync(nodePath.join(uiDir, 'DESIGN.md'), '# Fixture card\n');
+  }
+  return written;
+}

package/src/core/vault-files.mjs

@@ -0,0 +1,13 @@
+/** Pure filesystem helpers. Importing these must not load auth or configuration. */
+import fs from 'node:fs';
+
+export function isSafeVaultName(name) {
+  const value = String(name);
+  return /^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/.test(value) && !value.includes('..');
+}
+
+export function atomicWrite(filePath, content) {
+  const tmpPath = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpPath, content, 'utf8');
+  fs.renameSync(tmpPath, filePath);
+}

package/src/core/vault.mjs

@@ -2,37 +2,11 @@ import fs from 'fs';
 import path from 'path';
 import matter from './frontmatter.mjs';
 import { logger } from './logger.mjs';
+export { atomicWrite, isSafeVaultName } from './vault-files.mjs';
+import { atomicWrite, isSafeVaultName } from './vault-files.mjs';
 
-// Slug allowlist shared with validated-write.mjs — a slug is a filename, so it
-// must not be able to escape its category directory.
-//
-// Dots are permitted in the interior because repository names legitimately
-// contain them — any domain-style name (`example.com`) produces a slug with a
-// dot on ingest, and the stricter rule rejected thousands of real nodes over an
-// ordinary character. What enables traversal is a path separator or `..`, and
-// neither is reachable here — separators are outside the character class, a
-// leading dot or dash is excluded by the first-character rule, and `..` is
-// rejected outright below.
-const SAFE_NAME = /^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/;
-
-/**
- * True when `name` is safe to use as a path segment.
- */
-export function isSafeVaultName(name) {
-  const value = String(name);
-  if (!SAFE_NAME.test(value)) return false;
-  if (value.includes('..')) return false;
-  return true;
-}
-
-/**
- * Atomic file write using write-then-rename to prevent partial corruption.
- */
-export function atomicWrite(filePath, content) {
-  const tmpPath = `${filePath}.tmp.${process.pid}`;
-  fs.writeFileSync(tmpPath, content, 'utf8');
-  fs.renameSync(tmpPath, filePath);
-}
+// Re-export pure path/atomic-write helpers for existing callers. Local retrieval
+// imports vault-files directly so it never loads logger/configuration/auth.
 
 /**
  * Deep-strip undefined values from an object so js-yaml (via gray-matter)

package/src/server/index.mjs

@@ -289,7 +289,7 @@ app.get('/health', requireAuthOrLocal, async (req, res) => {
   // No agent CLIs on PATH is normal for a headless server brain (a droplet has
   // none), so it is reported in cli_agents but does not make the brain
   // "degraded" — that status is for things that break memory itself.
-  const hasCriticalIssue = emergencyAlerts.length > 0 || daemonStatus === 'dead'
+  const hasCriticalIssue = emergencyAlerts.length > 0 || ['dead', 'conflict', 'unknown'].includes(daemonStatus)
     || unembeddedBrains.length > 0;
 
   // Check Caddy and Cloudflare status
@@ -402,6 +402,18 @@ try {
 
 // ─── API Routes (/v1/chat/completions) ──────────────────────────────────────────
 
+// The single agent entry point. Mounted separately from apiRouter so a failure
+// in one surface cannot leave the other dark.
+try {
+  const { invokeRouter } = await import('./routes/invoke.mjs');
+  if (invokeRouter) {
+    app.use(invokeRouter);
+    logger.info('server', 'Agent invoke endpoint mounted at /v1/invoke');
+  }
+} catch (err) {
+  logger.error('server', `invoke router failed to load; /v1/invoke left unmounted: ${err.message}`);
+}
+
 try {
   const { apiRouter } = await import('./api.mjs');
   if (apiRouter) {

package/src/server/invoke-decision-child.mjs

@@ -0,0 +1,49 @@
+/** Full developer adapter: provider/credential work lives in a cancellable group. */
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Keep dependency diagnostics out of the structured result pipe. The parent
+// never returns diagnostics, including those emitted by installed owner code.
+console.log = console.info = console.debug = (...args) => console.error(...args);
+
+try {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+    if (Buffer.byteLength(input) > 32768) throw new Error('Input limit');
+  }
+  const { operation, params, brain, timeoutMs } = JSON.parse(input);
+  if (!['decision.run', 'decision.predict'].includes(operation)) throw new Error('Unknown operation');
+  const plugin = path.join(brain, 'plugins/decision');
+  const client = await import(pathToFileURL(path.join(plugin, 'src/client.mjs')).href);
+  const auth = await import(pathToFileURL(path.join(plugin, 'auth-client.mjs')).href);
+  const apiKey = auth.readAuthSecret('OPENROUTER_API_KEY');
+  if (!apiKey) {
+    process.stdout.write(JSON.stringify({ ok: false, error: 'credential-unavailable' }));
+  } else {
+    let result;
+    if (operation === 'decision.run') {
+      const d = await client.requestDecision({ apiKey, model: params.model || client.DEFAULT_MODEL,
+        endpoint: client.DEFAULT_ENDPOINT, timeoutMs, state: params.state || {}, questions: params.questions });
+      if (d) {
+        const answers = Object.fromEntries(Object.entries(params.questions).map(([key, question]) => [key,
+          question?.type === 'noul' ? d.noul(key) : question?.type === 'score' ? d.score(key) : d.choice(key)]));
+        result = { answered: true, answers, model: d.modelVersion, cost_usd: d.cost, latency_ms: d.latencyMs };
+      }
+    } else {
+      const { predictNextAction } = await import('../core/action-predictor.mjs');
+      result = await predictNextAction(params.intent || '', {
+        state: params.state || {}, apiKey, requestDecision: client.requestDecision,
+        derivedDir: path.join(brain, 'memory-derived'), projectRoot: process.cwd(),
+        model: client.DEFAULT_MODEL, endpoint: client.DEFAULT_ENDPOINT, timeoutMs,
+        limit: Math.max(5, Math.min(40, Number(params.limit) || 20)),
+      });
+      if (result?.ok === false && result.reason === 'no-decision') result = null;
+    }
+    process.stdout.write(JSON.stringify(result ? { ok: true, result } : { ok: false, error: 'provider-failed' }));
+  }
+} catch {
+  // Exception text can contain provider payloads, credentials or private paths.
+  process.stdout.write(JSON.stringify({ ok: false, error: 'decision-failed' }));
+  process.exitCode = 1;
+}

package/src/server/invoke-execution.mjs

@@ -0,0 +1,87 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+export const INVOKE_LIMITS = Object.freeze({ timeoutMs: 60000, outputBytes: 262144, concurrency: 4, perKey: 1 });
+
+export class InvokeError extends Error {
+  constructor(status, code, message, result = null) {
+    super(message); this.status = status; this.code = code; this.result = result;
+  }
+}
+
+/** Deliberate allowlist: no tokens, NODE_OPTIONS, preload hooks or secret-store selectors. */
+export function invokeEnvironment(full, source = process.env) {
+  const env = { FORCE_COLOR: '0', NO_COLOR: '1' };
+  for (const name of ['PATH', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR', 'SystemRoot']) {
+    if (source[name]) env[name] = source[name];
+  }
+  // Full mode is intentionally trusted host administration, including the auth
+  // owner's credential resolution. Ambient API keys still are not inherited.
+  if (full) for (const name of ['HOME', 'USER', 'AGENT_DIR', 'TR_SECRETS_BRAIN', 'TR_SECRETS_PASSWORD']) {
+    if (source[name]) env[name] = source[name];
+  }
+  return env;
+}
+
+/** Bounded direct-argv child; cancellation kills its POSIX process group. */
+export async function executeInvokeChild({ entry, args = [], cwd, env, input, timeoutMs, signal,
+  limits = INVOKE_LIMITS, nodeArgs = [] }) {
+  if (process.platform === 'win32') throw new InvokeError(503, 'unsupported-platform', 'Process-group enforcement is unavailable on this platform.');
+  const timeout = timeoutMs === undefined ? limits.timeoutMs : Number(timeoutMs);
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new InvokeError(400, 'invalid-timeout', 'timeoutMs must be positive and finite.');
+  if (signal?.aborted) throw new InvokeError(403, 'authority-ended', 'Caller authority ended before execution.');
+  return await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [...nodeArgs, entry, ...args], {
+      cwd, env, shell: false, detached: true, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const chunks = { stdout: [], stderr: [] };
+    let bytes = 0, reason = null;
+    const kill = why => {
+      reason ||= why;
+      if (child.pid) try { process.kill(-child.pid, 'SIGKILL'); } catch (err) {
+        if (err.code !== 'ESRCH') child.kill('SIGKILL');
+      }
+    };
+    const abort = () => kill('authority-ended');
+    const timer = setTimeout(() => kill('timeout'), Math.min(timeout, limits.timeoutMs));
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) abort();
+    for (const channel of ['stdout', 'stderr']) child[channel].on('data', chunk => {
+      const remaining = Math.max(0, limits.outputBytes - bytes);
+      if (remaining) chunks[channel].push(chunk.subarray(0, remaining));
+      bytes += chunk.length;
+      if (bytes > limits.outputBytes) kill('output-limit');
+    });
+    child.stdin.on('error', () => {}); // An early exit may close stdin first.
+    child.stdin.end(input || '');
+    child.once('error', () => {
+      clearTimeout(timer); signal?.removeEventListener('abort', abort);
+      reject(new InvokeError(503, 'spawn-failed', 'Execution could not start.'));
+    });
+    child.once('close', (code, terminationSignal) => {
+      // Also retire descendants after a normally exiting parent.
+      if (child.pid) try { process.kill(-child.pid, 'SIGKILL'); } catch {}
+      clearTimeout(timer); signal?.removeEventListener('abort', abort);
+      resolve({ exit_code: code, signal: terminationSignal, stdout: Buffer.concat(chunks.stdout).toString(),
+        stderr: Buffer.concat(chunks.stderr).toString(), truncated: bytes > limits.outputBytes,
+        timed_out: reason === 'timeout', termination_reason: reason });
+    });
+  });
+}
+
+export function requireSuccessfulRun(run) {
+  if (run.exit_code !== 0 || run.termination_reason || run.truncated) {
+    const code = run.termination_reason || 'nonzero-exit';
+    throw new InvokeError(code === 'timeout' ? 504 : code === 'authority-ended' ? 403 : 422,
+      code, 'Execution did not complete successfully.', run);
+  }
+  return run;
+}
+
+export function absoluteTarget(target, fallback) {
+  if (target === undefined) return fallback;
+  if (typeof target !== 'string' || !path.isAbsolute(target) || target.includes('\0')) {
+    throw new InvokeError(400, 'invalid-target', 'Full developer target must be an absolute working directory.');
+  }
+  return target;
+}

package/src/server/invoke-policy.mjs

@@ -0,0 +1,64 @@
+import { InvokeError } from './invoke-execution.mjs';
+import { validateConfinedFact } from '../core/confined-memory.mjs';
+
+/** Resolve fresh key AND ancestors through the shared auth owner on each check. */
+export function invokeAuthority(req, { loadKeys, keyHasScope }) {
+  try { return resolveAuthority(req, { loadKeys, keyHasScope }); }
+  catch (err) {
+    if (err instanceof InvokeError) throw err;
+    throw new InvokeError(503, 'authority-unavailable', 'Shared auth authority is unavailable.');
+  }
+}
+
+function resolveAuthority(req, { loadKeys, keyHasScope }) {
+  if (req.auth?.type !== 'pat' || !req.auth.id) {
+    throw new InvokeError(403, 'explicit-key-required', 'Invoke requires a named PAT with an explicit invoke mode.');
+  }
+  const keys = loadKeys();
+  const chain = [], seen = new Set();
+  let key = keys.find(k => k.id === req.auth.id);
+  while (key) {
+    if (seen.has(key.id) || !keyHasScope(key, null)) throw new InvokeError(403, 'authority-ended', 'Key or issuer is expired, revoked or invalid.');
+    seen.add(key.id); chain.push(key);
+    if (key.issued_by === 'local-operator' || !key.issued_by) break;
+    key = keys.find(k => k.id === key.issued_by);
+    if (!key) throw new InvokeError(403, 'authority-ended', 'Issuer is unavailable.');
+  }
+  if (!chain.length) throw new InvokeError(403, 'authority-ended', 'Key is unavailable.');
+  const allows = scope => chain.every(k => keyHasScope(k, scope));
+  // The leaf must carry a literal mode. A historical wildcard does not opt in.
+  const full = chain.every(k => k.scopes?.includes('invoke:full')) && allows('invoke:full');
+  const restricted = chain[0].scopes?.includes('invoke:restricted') && allows('invoke:restricted');
+  if (!full && !restricted) throw new InvokeError(403, 'invoke-grant-required', 'Explicit invoke:full or invoke:restricted grant required; legacy keys are not migrated automatically.');
+  return { id: chain[0].id, scopes: chain[0].scopes, mode: full ? 'full' : 'restricted', allows };
+}
+
+export function operationAllowed(authority, operation, scope, targets = ['server']) {
+  if (scope && !authority.allows(scope)) return false;
+  if (operation === 'capabilities') return true;
+  if (authority.mode === 'full') return true;
+  return ['ssss.read', 'ssss.write'].includes(operation) && targets.some(target =>
+    authority.allows(target === 'server' ? 'brain:server' : `brain:project-${target.slice('project:'.length)}`));
+}
+
+export function authorizeInvoke(authority, operation, scope, params, targets = ['server']) {
+  if (scope && !authority.allows(scope)) throw new InvokeError(403, 'insufficient-scope', `Operation requires scope '${scope}'.`);
+  if (!operationAllowed(authority, operation, scope, targets)) {
+    throw new InvokeError(403, 'unsupported-restricted-operation', 'No confined owner adapter is available for this operation.');
+  }
+  if (authority.mode === 'restricted') {
+    if (operation === 'capabilities') return;
+    if (!targets.includes(params.target ?? 'server') || params.scope !== undefined) {
+      throw new InvokeError(403, 'target-denied', 'Restricted memory requires an available granted brain target.');
+    }
+    if (operation === 'ssss.write') {
+      try { validateConfinedFact({ ...params, target: 'server' }); }
+      catch { throw new InvokeError(400, 'invalid-fact', 'Restricted writes accept only fact content, optional title and plain tags.'); }
+      return;
+    }
+    const allowed = new Set(['query', 'category', 'limit', 'target', 'timeoutMs']);
+    if (Object.keys(params).some(k => !allowed.has(k))) {
+      throw new InvokeError(400, 'unknown-parameter', 'Unsupported restricted retrieval parameter.');
+    }
+  }
+}

package/src/server/invoke-read-child.mjs

@@ -0,0 +1,26 @@
+/** Trusted read-only adapter: no CLI bootstrap, auth, plugins or provider imports. */
+import path from 'node:path';
+import { fastSearch } from '../core/fast-recall.mjs';
+
+try {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+    if (Buffer.byteLength(input) > 16384) throw new Error('Input limit exceeded');
+  }
+  const { brain, query, category, limit } = JSON.parse(input);
+  const nodes = fastSearch(query, {
+    vaultDir: path.join(brain, 'memory-vault'),
+    derivedDir: path.join(brain, 'memory-derived'),
+    top_k: limit, category, fullText: true,
+  });
+  if (nodes.stats.index !== 'local') throw new Error(`Local index ${nodes.stats.index}; compile the authorized brain first`);
+  process.stdout.write(JSON.stringify({ count: nodes.length, nodes: nodes.map(n => ({
+    slug: n.slug, category: n.category, title: n.title, status: n.status,
+    score: n.score, snippet: String(n.body || '').slice(0, 240),
+  })), freshness: nodes.stats.freshness }));
+} catch {
+  // Never include paths, memory payloads or parser input in the failure channel.
+  process.stderr.write('Authorized local retrieval failed; check its index.');
+  process.exitCode = 1;
+}

package/src/server/invoke-targets.mjs

@@ -0,0 +1,49 @@
+/** Resolve operator registrations; caller inputs are IDs, never host paths. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readRegisteredProjects, readBrainToggles } from '../core/brain-registry.mjs';
+import { readProjectId } from '../core/project-id.mjs';
+import { InvokeError } from './invoke-execution.mjs';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export const projectBrainScope = id => `brain:project-${id}`;
+
+function safeMemoryRoots(brain) {
+  for (const relative of ['memory-vault', 'memory-derived', 'memory-derived/local-search.json', 'memory-derived/memory-layers.jsonl']) {
+    const file = path.join(brain, relative);
+    try { if (fs.lstatSync(file).isSymbolicLink() || fs.realpathSync(file) !== file) return false; }
+    catch (err) { if (err.code !== 'ENOENT') return false; }
+  }
+  return true;
+}
+
+export function restrictedBrainTargets(authority, { serverBrain, registryBrain }) {
+  const targets = new Map();
+  if (authority.allows('brain:server')) targets.set('server', fs.realpathSync(serverBrain));
+  // A plain server grant does not require unrelated registry availability.
+  if (!authority.scopes?.some(scope => scope === '*' || scope === 'brain:*' || /^brain:project-/.test(scope))) return targets;
+  let rows, toggles;
+  try {
+    rows = readRegisteredProjects(registryBrain);
+    toggles = readBrainToggles(registryBrain, { strict: true });
+  } catch { throw new InvokeError(503, 'target-registry-unavailable', 'Project target metadata is unavailable.'); }
+  const seen = new Set();
+  for (const row of rows) {
+    const id = row.project_id;
+    if (typeof id !== 'string' || !UUID.test(id) || !authority.allows(projectBrainScope(id))) continue;
+    if (seen.has(id)) throw new InvokeError(503, 'ambiguous-project-target', 'A granted project identity is registered more than once.');
+    seen.add(id);
+    try {
+      if (typeof row.path !== 'string' || !path.isAbsolute(row.path) || typeof row.brainDir !== 'string' || !path.isAbsolute(row.brainDir)) continue;
+      const expected = path.join(fs.realpathSync(row.path), '.agent', 'skills', 'total-recall');
+      const brain = fs.realpathSync(row.brainDir);
+      // Nested links cannot substitute another project or global brain.
+      if (brain !== expected || fs.realpathSync(path.join(brain, 'config')) !== path.join(brain, 'config') ||
+        !fs.lstatSync(path.join(brain, 'config', 'brain.json')).isFile() ||
+        fs.lstatSync(path.join(brain, 'config', 'brain.json')).isSymbolicLink() || readProjectId(brain) !== id || !safeMemoryRoots(brain)) continue;
+      if (toggles[path.resolve(row.brainDir)] === false || toggles[brain] === false) continue;
+      targets.set(`project:${id}`, brain);
+    } catch { /* A missing, unsafe or mismatched registration grants nothing. */ }
+  }
+  return targets;
+}

package/src/server/invoke-write-child.mjs

@@ -0,0 +1,19 @@
+/** Structured trusted mutation entrypoint. Never accepts executable code. */
+import { createConfinedFact } from '../core/confined-memory.mjs';
+
+try {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+    if (Buffer.byteLength(input) > 16384) throw new Error('Input limit');
+  }
+  const { brain, params, caller } = JSON.parse(input);
+  try { process.stdout.write(JSON.stringify(await createConfinedFact(brain, params, caller))); }
+  catch (err) {
+    if (err.result) process.stdout.write(JSON.stringify(err.result));
+    throw err;
+  }
+} catch {
+  process.stderr.write('Confined fact creation did not complete; check committed/indexed status before retry.');
+  process.exitCode = 1;
+}