total-recall-brain 3.41.4 → 3.41.6

package/scaffold/.agent/skills/total-recall/plugins/openwiki/src/mesh-vaults.mjs

@@ -0,0 +1,261 @@
+/**
+ * Multi-Vault and Mesh Discovery Engine for OpenWiki.
+ *
+ * Uses the Total Recall Mesh plugin dynamically (zero hardcoded hosts/IPs/devices).
+ * Discovers local vaults, registered project vaults, and live online mesh peers.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readProjects } from './refresh.mjs';
+
+/**
+ * Returns the path to the global vault directory.
+ */
+export function getGlobalVaultPath(home = os.homedir()) {
+  return path.join(home, '.agent', 'skills', 'total-recall', 'memory-vault');
+}
+
+/**
+ * Discovers all active vault roots on the current machine dynamically:
+ * - Global memory vault
+ * - Every registered project repository's memory vault
+ * - Every registered project repository's openwiki projection directory
+ */
+export function discoverLocalVaults({ home = os.homedir() } = {}) {
+  const vaults = [];
+
+  // 1. Global Vault
+  const globalVault = getGlobalVaultPath(home);
+  if (fs.existsSync(globalVault)) {
+    vaults.push({
+      type: 'global',
+      name: 'global-vault',
+      root: globalVault,
+      isVault: true,
+      hasOpenWikiDir: fs.existsSync(path.join(globalVault, 'openwiki-articles')) ||
+                      fs.existsSync(path.join(globalVault, 'openwiki-hubs')),
+    });
+  }
+
+  // 2. Project Vaults & Repositories from project-registry
+  let projects = [];
+  try {
+    projects = readProjects();
+  } catch {
+    projects = [];
+  }
+
+  for (const proj of projects) {
+    const projectVault = path.join(proj.root, '.agent', 'skills', 'total-recall', 'memory-vault');
+    const projectOpenWiki = path.join(proj.root, 'openwiki');
+    vaults.push({
+      type: 'project',
+      name: proj.name,
+      root: proj.root,
+      vaultPath: fs.existsSync(projectVault) ? projectVault : null,
+      openwikiPath: fs.existsSync(projectOpenWiki) ? projectOpenWiki : null,
+      hasOpenWikiDir: fs.existsSync(projectOpenWiki),
+      isVault: fs.existsSync(projectVault),
+    });
+  }
+
+  return vaults;
+}
+
+/**
+ * Dynamically queries the mesh plugin for live mesh peers.
+ * Zero hardcoded hostnames, IPs, or personal user configurations.
+ */
+export function getMeshNodes() {
+  try {
+    const stdout = execFileSync('total-recall', ['mesh', 'status'], {
+      encoding: 'utf8',
+      timeout: 6000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+
+    const lines = stdout.split('\n');
+    const jsonLine = lines.find((l) => l.trim().startsWith('{') && l.includes('"nodes"'));
+    if (!jsonLine) return [];
+
+    const parsed = JSON.parse(jsonLine);
+    if (!Array.isArray(parsed.nodes)) return [];
+
+    return parsed.nodes
+      .filter((n) => n && n.ip && typeof n.ip === 'string')
+      .map((n) => ({
+        hostname: n.os_hostname || n.hostname || n.title || n.ip,
+        ip: n.ip,
+        ips: Array.isArray(n.ips) ? n.ips : [n.ip],
+        self: Boolean(n.self),
+        online: Boolean(n.online),
+        os: n.os || 'unknown',
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Execute a command on a remote mesh node via Total Recall mesh plugin.
+ * Guarded against self-execution (never ssh a machine into itself).
+ */
+export function execOnMeshNode(nodeTarget, commandStr, { timeoutMs = 25000 } = {}) {
+  if (!nodeTarget || typeof nodeTarget !== 'string') {
+    throw new Error('A valid mesh node identifier or IP is required');
+  }
+
+  // Verify against dynamic mesh self status
+  const nodes = getMeshNodes();
+  const matched = nodes.find(
+    (n) => n.ip === nodeTarget || n.hostname.toLowerCase() === nodeTarget.toLowerCase()
+  );
+
+  if (matched?.self) {
+    throw new Error(`Target node '${nodeTarget}' is the local host. Do not mesh exec into self.`);
+  }
+
+  const result = spawnSync('total-recall', ['mesh', 'exec', nodeTarget, commandStr], {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+  });
+
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error ? result.error.message : null,
+  };
+}
+
+/**
+ * Scans a directory for OpenWiki markdown hub files.
+ */
+export function scanDirectoryHubs(targetDir, { label = '', repoName = '' } = {}) {
+  const hubs = [];
+  if (!fs.existsSync(targetDir)) return hubs;
+
+  try {
+    const entries = fs.readdirSync(targetDir, { withFileTypes: true });
+    for (const ent of entries) {
+      if (ent.isFile() && ent.name.endsWith('.md')) {
+        const fullPath = path.join(targetDir, ent.name);
+        try {
+          const content = fs.readFileSync(fullPath, 'utf8');
+          const titleMatch = content.match(/^#\s+(.+)$/m);
+          const title = titleMatch ? titleMatch[1].trim() : ent.name.replace(/\.md$/, '');
+          const lines = content.split('\n').length;
+          hubs.push({
+            title,
+            fileName: ent.name,
+            path: fullPath,
+            repoName: repoName || path.basename(path.dirname(targetDir)),
+            sourceType: label || 'openwiki',
+            lines,
+            size_bytes: Buffer.byteLength(content, 'utf8'),
+          });
+        } catch {
+          // ignore unreadable files
+        }
+      }
+    }
+  } catch {
+    // directory read error
+  }
+
+  return hubs;
+}
+
+/**
+ * Universal Hubs Discovery across:
+ * - Current cwd `./openwiki`
+ * - All registered project vaults (`--all-vaults`)
+ * - Global memory vault (`openwiki-*` categories)
+ * - Remote mesh node (`--node <target>`)
+ */
+export async function discoverAllHubs({
+  allVaults = false,
+  node = null,
+  cwd = process.cwd(),
+} = {}) {
+  // If target is a remote mesh node, delegate through mesh
+  if (node && node !== 'local' && node !== 'self') {
+    const nodes = getMeshNodes();
+    const selfNode = nodes.find((n) => n.self);
+    const isSelf = selfNode && (selfNode.ip === node || selfNode.hostname.toLowerCase() === node.toLowerCase());
+
+    if (!isSelf) {
+      const meshRes = execOnMeshNode(node, `total-recall openwiki hubs ${allVaults ? '--all-vaults' : ''} --json`);
+      if (meshRes.ok) {
+        try {
+          const parsed = JSON.parse(meshRes.stdout);
+          return {
+            node,
+            isRemote: true,
+            hubs: parsed.hubs || [],
+            count: parsed.count || (parsed.hubs ? parsed.hubs.length : 0),
+          };
+        } catch {
+          throw new Error(`Invalid JSON response from mesh node ${node}: ${meshRes.stdout}`);
+        }
+      } else {
+        throw new Error(`Mesh exec failed on node ${node}: ${meshRes.stderr || meshRes.error}`);
+      }
+    }
+  }
+
+  const allHubs = [];
+
+  // 1. Current working directory openwiki
+  const localOpenWiki = path.resolve(cwd, 'openwiki');
+  const localHubs = scanDirectoryHubs(localOpenWiki, {
+    label: 'current-workspace',
+    repoName: path.basename(cwd),
+  });
+  allHubs.push(...localHubs);
+
+  // If not all vaults requested, return local hubs
+  if (!allVaults) {
+    return {
+      node: 'local',
+      isRemote: false,
+      hubs: allHubs,
+      count: allHubs.length,
+      scope: 'workspace',
+    };
+  }
+
+  // 2. Scan all project vaults across the machine
+  const localVaults = discoverLocalVaults();
+  for (const vault of localVaults) {
+    if (vault.type === 'project' && vault.openwikiPath) {
+      if (path.resolve(vault.openwikiPath) === path.resolve(localOpenWiki)) continue;
+      const projHubs = scanDirectoryHubs(vault.openwikiPath, {
+        label: 'project-openwiki',
+        repoName: vault.name,
+      });
+      allHubs.push(...projHubs);
+    } else if (vault.type === 'global') {
+      const gHubsDir = path.join(vault.root, 'openwiki-hubs');
+      const gArticlesDir = path.join(vault.root, 'openwiki-articles');
+      if (fs.existsSync(gHubsDir)) {
+        allHubs.push(...scanDirectoryHubs(gHubsDir, { label: 'global-vault-hubs', repoName: 'global-vault' }));
+      }
+      if (fs.existsSync(gArticlesDir)) {
+        allHubs.push(...scanDirectoryHubs(gArticlesDir, { label: 'global-vault-articles', repoName: 'global-vault' }));
+      }
+    }
+  }
+
+  return {
+    node: 'local',
+    isRemote: false,
+    hubs: allHubs,
+    count: allHubs.length,
+    scope: 'all-vaults',
+    vaultsScanned: localVaults.length,
+  };
+}

package/scaffold/.agent/skills/total-recall/plugins/openwiki/src/refresh.mjs

@@ -4,8 +4,8 @@
  * The generated `openwiki/` pages are a per-repository projection: they are
  * written into <repo>/openwiki/ and describe that repository's code. They rot
  * silently, because nothing in the repository is obliged to regenerate them —
- * festech-modular, festech.live and ultrachat-ai-powered each carried pages
- * three months and 78-149 commits out of date while still looking authoritative.
+ * repositories have carried pages three months and 78-149 commits out of date
+ * while still looking authoritative.
  *
  * The driver belongs here rather than in every repository: the plugin is one of
  * the bundled defaults served from the shared brain, so one implementation
@@ -21,7 +21,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { loadOpenWikiConfig } from './config.mjs';
 
 const PLUGIN_ROOT = fileURLToPath(new URL('..', import.meta.url));
@@ -82,7 +82,16 @@ export function hasWiki(root) {
  * since the recorded generation, which is the same measure the per-repo driver
  * used. Uncommitted work is not counted, so an open edit does not read as drift.
  */
+export function isGitRepo(root, { git = spawnSync } = {}) {
+  if (fs.existsSync(path.join(root, '.git'))) return true;
+  const res = git('git', ['-C', root, 'rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' });
+  return !res.error && res.status === 0;
+}
+
 export function staleness(root, { git = spawnSync } = {}) {
+  if (!isGitRepo(root, { git })) {
+    return { root, head: '', generatedAt: null, generatedStatus: null, files: null, lastCodeChange: null, commitsSince: 0, stale: false };
+  }
   const marker = path.join(root, 'openwiki', '.last-update.json');
   let head = '';
   const headRun = git('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
@@ -171,11 +180,19 @@ export function resolveKey({ provider = null, keys = null, run = spawnSync } = {
 export function resolveGenerator({ pluginRoot = null, run = spawnSync, env = process.env, home = os.homedir(), targetVersion = null } = {}) {
   const root = pluginRoot !== null ? pluginRoot : PLUGIN_ROOT;
   if (root) {
+    const bundled = path.join(root, 'vendor', 'openwiki.mjs');
+    if (fs.existsSync(bundled)) {
+      return { command: process.execPath, args: [bundled], via: 'bundled plugin generator' };
+    }
     const candidate = path.join(root, 'node_modules', '.bin', 'openwiki');
     if (fs.existsSync(candidate)) return { command: candidate, args: [], via: 'plugin local node_modules/.bin' };
   }
 
   if (pluginRoot === null) {
+    const localBundled = path.join(process.cwd(), 'vendor', 'openwiki.mjs');
+    if (fs.existsSync(localBundled)) {
+      return { command: process.execPath, args: [localBundled], via: 'bundled plugin generator' };
+    }
     const local = path.join(process.cwd(), 'node_modules', '.bin', 'openwiki');
     if (fs.existsSync(local)) return { command: local, args: [], via: 'local node_modules/.bin' };
   }
@@ -235,6 +252,9 @@ export function stillGenerating(root) {
 export function refreshProject(project, {
   key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, run = spawnSync, now = Date.now(), targetVersion = null, pluginRoot = PLUGIN_ROOT,
 } = {}) {
+  if (!isGitRepo(project.root, { git: run })) {
+    return { ...project, action: 'skipped', reason: 'not a git repository' };
+  }
   const before = staleness(project.root, { git: run });
   const uninitialized = !hasWiki(project.root);
 
@@ -247,7 +267,7 @@ export function refreshProject(project, {
     ({ command, args, via } = resolved);
   }
 
-  const config = typeof loadOpenWikiConfig === 'function' ? loadOpenWikiConfig() : { model: 'deepseek/deepseek-v4.1-flash', provider: 'openrouter' };
+  const config = typeof loadOpenWikiConfig === 'function' ? loadOpenWikiConfig() : { model: 'deepseek/deepseek-chat', provider: 'openrouter' };
   const selectedModel = model || config.model;
   const selectedProvider = provider || config.provider;
 
@@ -336,8 +356,135 @@ export function refreshProject(project, {
   return { ...project, action: uninitialized ? 'initialized' : 'refreshed', from: before.generatedAt, to: after.generatedAt, durationMs: Date.now() - startedAt, via, ...after };
 }
 
+export async function refreshProjectAsync(project, {
+  key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, now = Date.now(), targetVersion = null, pluginRoot = PLUGIN_ROOT,
+} = {}) {
+  if (!isGitRepo(project.root, { git: spawnSync })) {
+    return { ...project, action: 'skipped', reason: 'not a git repository' };
+  }
+  const before = staleness(project.root, { git: spawnSync });
+  const uninitialized = !hasWiki(project.root);
+  let command = binary, args = binaryArgs, via = binary ? 'explicit' : null;
+  if (!command) {
+    const resolved = resolveGenerator({ run: spawnSync, targetVersion, pluginRoot });
+    if (!resolved.command) {
+      return { ...project, action: 'failed', reason: 'no openwiki generator available (no local .bin, no PATH entry, no npx)', ...before };
+    }
+    ({ command, args, via } = resolved);
+  }
+
+  const config = typeof loadOpenWikiConfig === 'function' ? loadOpenWikiConfig() : { model: 'deepseek/deepseek-chat', provider: 'openrouter' };
+  const selectedModel = model || config.model;
+  const selectedProvider = provider || config.provider;
+
+  const modeFlag = uninitialized ? '--init' : '--update';
+  const cmdArgs = [...args, modeFlag, '-p'];
+  if (selectedModel) {
+    cmdArgs.push('--modelId', selectedModel);
+  }
+
+  if (uninitialized) {
+    const runFile = path.join(project.root, 'openwiki', '.run.json');
+    if (fs.existsSync(runFile)) {
+      try { fs.unlinkSync(runFile); } catch {}
+    }
+  }
+
+  const childEnv = { ...process.env };
+  if (selectedProvider === 'google') {
+    childEnv.GOOGLE_API_KEY = key;
+    childEnv.GEMINI_API_KEY = key;
+    childEnv.OPENWIKI_PROVIDER = 'gemini';
+    delete childEnv.OPENAI_API_KEY;
+    delete childEnv.OPENROUTER_API_KEY;
+  } else {
+    childEnv.OPENROUTER_API_KEY = key;
+    childEnv.OPENWIKI_PROVIDER = 'openrouter';
+    if (config.max_tokens) {
+      childEnv.OPENWIKI_OPENROUTER_MAX_TOKENS = String(config.max_tokens);
+      childEnv.OPENWIKI_MAX_OUTPUT_TOKENS = String(config.max_tokens);
+    }
+    delete childEnv.OPENAI_API_KEY;
+  }
+
+  const startedAt = now;
+  const result = await new Promise((resolve) => {
+    const proc = spawn(command, cmdArgs, {
+      cwd: project.root,
+      env: childEnv,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+    });
+    let stdout = '', stderr = '';
+    proc.stdout?.on('data', (d) => { stdout += d; });
+    proc.stderr?.on('data', (d) => { stderr += d; });
+    proc.on('error', (err) => resolve({ error: err, status: 1, stdout, stderr }));
+    proc.on('close', (status) => resolve({ status: status ?? 0, stdout, stderr }));
+  });
+
+  // OpenWiki generator may drop GitHub workflow files; our system strictly forbids GitHub Actions.
+  const workflowDir = path.join(project.root, '.github', 'workflows');
+  const workflowFile = path.join(workflowDir, 'openwiki-update.yml');
+  if (fs.existsSync(workflowFile)) {
+    try { fs.unlinkSync(workflowFile); } catch {}
+  }
+  if (fs.existsSync(workflowDir)) {
+    try {
+      const remaining = fs.readdirSync(workflowDir);
+      if (remaining.length === 0) fs.rmdirSync(workflowDir);
+    } catch {}
+  }
+
+  const after = staleness(project.root, { git: spawnSync });
+  const exitCode = result.error ? (result.error.code || 1) : result.status;
+  const advanced = after.generatedAt !== before.generatedAt || (uninitialized && hasWiki(project.root));
+  const wrote = pagesWritten(before, after) || (uninitialized && hasWiki(project.root) ? 1 : 0);
+
+  const outcome = after.generatedStatus === 'interrupted' || stillGenerating(project.root)
+    ? 'partial'
+    : (advanced ? (uninitialized ? 'initialized' : 'refreshed') : 'unchanged');
+
+  const extractReason = (rawErr, rawOut) => {
+    if (result.error?.message) return result.error.message;
+    const combined = `${rawErr || ''}\n${rawOut || ''}`.trim();
+    if (!combined) return `exit ${exitCode}`;
+    const lines = combined.split('\n').map((l) => l.trim()).filter(Boolean);
+    const diag = lines.find((l) => l.includes('Error Diagnostics') || l.includes('exited without') || l.includes('Could not restore') || l.includes('Provider returned error') || l.includes('fetch failed'));
+    if (diag) return diag.replace(/^\[ERR\]\s*/, '');
+    const last = lines[lines.length - 1];
+    return last ? last.replace(/^\[ERR\]\s*/, '') : `exit ${exitCode}`;
+  };
+  const failReason = extractReason(result.stderr, result.stdout);
+
+  if (exitCode !== 0 && !wrote) {
+    return { ...project, action: 'failed', reason: failReason, exitCode, ...after };
+  }
+  if (!advanced && !wrote) {
+    return { ...project, action: 'failed', reason: failReason || `command exited ${exitCode} and no page changed`, exitCode, ...after };
+  }
+  if (outcome === 'partial') {
+    return {
+      ...project,
+      action: 'partial',
+      reason: `${wrote} page(s) rewritten, but the run did not finish (the generator was cut off); it resumes on the next refresh`,
+      exitCode,
+      from: before.generatedAt,
+      to: after.generatedAt,
+      via,
+      ...after,
+    };
+  }
+  if (exitCode !== 0) {
+    return { ...project, action: 'failed', reason: failReason, exitCode, ...after };
+  }
+  return { ...project, action: uninitialized ? 'initialized' : 'refreshed', from: before.generatedAt, to: after.generatedAt, durationMs: Date.now() - startedAt, via, ...after };
+}
+
 /** Is a refresh due for this project under the configured interval? */
 export function isDue(project, { lockMs = DEFAULT_LOCK_MS, now = Date.now(), git = spawnSync } = {}) {
+  if (!isGitRepo(project.root, { git })) {
+    return { due: false, skipped: true, reason: 'not a git repository' };
+  }
   const state = staleness(project.root, { git });
   if (!hasWiki(project.root)) {
     return { due: true, uninitialized: true, reason: 'uninitialized (missing openwiki/ pages)', ...state };

package/scaffold/.agent/skills/total-recall/plugins/openwiki/src/search.mjs

@@ -0,0 +1,114 @@
+/**
+ * OpenWiki Evidence Search & Query Engine.
+ *
+ * Searches knowledge hubs across local workspace, all registered project vaults,
+ * or remote mesh nodes. Extracts evidence passages and linked concepts.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { discoverAllHubs, execOnMeshNode } from './mesh-vaults.mjs';
+
+/**
+ * Searches for query terms across markdown files.
+ */
+export async function searchWikiHubs(query, {
+  allVaults = false,
+  node = null,
+  limit = 20,
+  cwd = process.cwd(),
+} = {}) {
+  if (!query || typeof query !== 'string' || !query.trim()) {
+    throw new Error('Search query must be a non-empty string');
+  }
+
+  // If remote mesh node specified, dispatch via mesh
+  if (node && node !== 'local' && node !== 'self') {
+    const escapedQuery = query.replace(/"/g, '\\"');
+    const meshRes = execOnMeshNode(
+      node,
+      `total-recall openwiki search "${escapedQuery}" ${allVaults ? '--all-vaults' : ''} --json`
+    );
+    if (meshRes.ok) {
+      try {
+        return JSON.parse(meshRes.stdout);
+      } catch {
+        throw new Error(`Invalid JSON from mesh node ${node}: ${meshRes.stdout}`);
+      }
+    } else {
+      throw new Error(`Mesh search failed on node ${node}: ${meshRes.stderr || meshRes.error}`);
+    }
+  }
+
+  const hubsResult = await discoverAllHubs({ allVaults, cwd });
+  const rawTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const terms = rawTerms.map((t) => t.replace(/[^\w-]/g, ''));
+
+  const matches = [];
+
+  for (const hub of hubsResult.hubs) {
+    let content;
+    try {
+      content = fs.readFileSync(hub.path, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lines = content.split('\n');
+    let currentHeading = hub.title;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const headingMatch = line.match(/^#{1,6}\s+(.+)$/);
+      if (headingMatch) {
+        currentHeading = headingMatch[1].trim();
+      }
+
+      const lowerLine = line.toLowerCase();
+      let termHits = 0;
+      for (const term of terms) {
+        if (lowerLine.includes(term)) termHits++;
+      }
+
+      if (termHits > 0) {
+        // Build surrounding snippet (1 line before, matched line, 1 line after)
+        const start = Math.max(0, i - 1);
+        const end = Math.min(lines.length, i + 2);
+        const snippetLines = lines.slice(start, end).map((l) => l.trim()).filter(Boolean);
+        const snippet = snippetLines.join(' ');
+
+        // Score: exact full phrase match bonus, heading bonus, multiple term bonus
+        let score = termHits * 10;
+        if (lowerLine.includes(query.toLowerCase())) score += 30;
+        if (headingMatch) score += 20;
+
+        matches.push({
+          title: hub.title,
+          section: currentHeading,
+          fileName: hub.fileName,
+          repoName: hub.repoName,
+          path: hub.path,
+          line: i + 1,
+          snippet: snippet.length > 280 ? snippet.slice(0, 277) + '...' : snippet,
+          score,
+        });
+
+        // Skip forward so overlapping lines don't spam identical snippets
+        i += 1;
+      }
+    }
+  }
+
+  // Sort descending by relevance score
+  matches.sort((a, b) => b.score - a.score);
+  const truncated = matches.slice(0, limit);
+
+  return {
+    ok: true,
+    query,
+    scope: hubsResult.scope,
+    totalHubsScanned: hubsResult.count,
+    count: truncated.length,
+    totalHits: matches.length,
+    results: truncated,
+  };
+}

package/scaffold/.agent/skills/total-recall/plugins/openwiki/src/token.mjs

@@ -0,0 +1,96 @@
+/**
+ * OpenWiki Token & Secret Management.
+ *
+ * Implements [invariants-473efe83]:
+ * Directly checks and sets credentials in Total Recall auth secrets store.
+ * Never echoes raw secrets to stdout/stderr.
+ */
+import { spawnSync } from 'node:child_process';
+
+const PROVIDER_KEY_MAP = {
+  openrouter: 'OPENROUTER_API_KEY',
+  google: 'GOOGLE_API_KEY',
+};
+
+/**
+ * Checks token readiness across supported providers.
+ */
+export function getTokenStatus() {
+  const result = spawnSync('total-recall', ['auth', 'secret', 'list', '--json'], {
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+
+  const configured = {
+    openrouter: false,
+    google: false,
+  };
+
+  if (result.status === 0 && result.stdout) {
+    try {
+      const parsed = JSON.parse(result.stdout);
+      const keys = Array.isArray(parsed)
+        ? parsed.map((k) => (typeof k === 'string' ? k : k.key || k.name))
+        : (parsed.keys || []);
+
+      configured.openrouter = keys.includes('OPENROUTER_API_KEY') || Boolean(process.env.OPENROUTER_API_KEY);
+      configured.google = keys.includes('GOOGLE_API_KEY') || Boolean(process.env.GOOGLE_API_KEY);
+    } catch {
+      configured.openrouter = Boolean(process.env.OPENROUTER_API_KEY);
+      configured.google = Boolean(process.env.GOOGLE_API_KEY);
+    }
+  } else {
+    configured.openrouter = Boolean(process.env.OPENROUTER_API_KEY);
+    configured.google = Boolean(process.env.GOOGLE_API_KEY);
+  }
+
+  return {
+    ok: true,
+    tokens: {
+      openrouter: {
+        key: 'OPENROUTER_API_KEY',
+        configured: configured.openrouter,
+        status: configured.openrouter ? 'configured' : 'missing',
+      },
+      google: {
+        key: 'GOOGLE_API_KEY',
+        configured: configured.google,
+        status: configured.google ? 'configured' : 'missing',
+      },
+    },
+  };
+}
+
+/**
+ * Securely writes a token into Total Recall auth secrets store using --stdin.
+ */
+export function setTokenValue(provider, secretValue) {
+  const keyName = PROVIDER_KEY_MAP[provider?.toLowerCase()] || provider;
+  if (!keyName) {
+    throw new Error(`Unsupported token provider '${provider}'. Allowed: openrouter, google`);
+  }
+
+  if (!secretValue || typeof secretValue !== 'string' || !secretValue.trim()) {
+    throw new Error(`Token value for ${keyName} must be a non-empty string`);
+  }
+
+  const trimmed = secretValue.trim();
+
+  // Pipe into total-recall auth secret set <KEY> --stdin
+  const child = spawnSync('total-recall', ['auth', 'secret', 'set', keyName, '--stdin'], {
+    input: trimmed,
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+
+  if (child.status !== 0) {
+    throw new Error(child.stderr || child.error?.message || `Failed to set ${keyName} in secrets store`);
+  }
+
+  return {
+    ok: true,
+    provider,
+    key: keyName,
+    message: `Secret ${keyName} securely recorded in Total Recall secrets store.`,
+  };
+}