total-recall-brain 3.44.0 → 3.46.0

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

@@ -1,13 +1,13 @@
 /**
- * Fixture manifests for specs that exercise plumbing rather than card design.
+ * Fixture manifests for specs that exercise plumbing rather than Home design.
  *
- * Every real plugin has a bespoke card face declared in `ui.elements[]`, and the
+ * Every real plugin has a bespoke native Home 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
+ * rule they are not testing. This module supplies a minimal native Home so
  * those specs keep asserting what they mean to assert.
  *
- * The face here is deliberately generic and exists only in tests. Production
+ * The Home 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';
@@ -16,45 +16,46 @@ 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({
+/** The smallest valid native Home. Declared once, as every plugin declares one. */
+export const FIXTURE_HOME = Object.freeze({
+  home: 'home',
   design_tokens: 'ui/DESIGN.md',
   elements: [
     {
-      id: 'card',
-      kind: 'card',
-      tag: 'tr-fixture-card',
-      module: 'ui/card.js',
-      description: 'Fixture card face',
+      id: 'home',
+      kind: 'panel',
+      tag: 'tr-fixture-home',
+      module: 'ui/home.js',
+      description: 'Fixture native Home',
     },
   ],
 });
 
-/** Source of the element module referenced by FIXTURE_CARD_FACE. */
-export const FIXTURE_CARD_SOURCE = 'export const tag = "tr-fixture-card";\n';
+/** Source of the element module referenced by FIXTURE_HOME. */
+export const FIXTURE_HOME_SOURCE = 'export const tag = "tr-fixture-home";\n';
 
 /**
- * Merge a bespoke face into a fixture manifest.
+ * Merge a native Home into a fixture manifest.
  *
- * Pass `ui: null` to omit the face deliberately, e.g. when asserting that a
+ * Pass `ui: null` to omit the Home deliberately, e.g. when asserting that a
  * plugin without one is rejected.
  */
-export function withFixtureFace(manifest = {}) {
+export function withFixtureHome(manifest = {}) {
   if (manifest.ui === null) {
     const { ui: _omitted, ...rest } = manifest;
     return rest;
   }
-  return { ...manifest, ui: manifest.ui ?? { ...FIXTURE_CARD_FACE } };
+  return { ...manifest, ui: manifest.ui ?? { ...FIXTURE_HOME } };
 }
 
 /**
- * Write `plugin.json` for a fixture plugin, declaring a face unless the manifest
+ * Write `plugin.json` for a fixture plugin, declaring a Home 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);
+  const written = withFixtureHome(manifest);
   nodeFs.writeFileSync(
     nodePath.join(pluginDir, 'plugin.json'),
     JSON.stringify(written, null, 2),
@@ -62,8 +63,8 @@ export function writeFixturePlugin(pluginDir, manifest, { fs = nodeFs, path = no
   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');
+    nodeFs.writeFileSync(nodePath.join(uiDir, 'home.js'), FIXTURE_HOME_SOURCE);
+    nodeFs.writeFileSync(nodePath.join(uiDir, 'DESIGN.md'), '# Fixture Home\n');
   }
   return written;
 }

package/src/core/throttled-fetch.mjs

@@ -135,31 +135,38 @@ export async function loadFirewallPolicy(brainDir) {
 
     applyPolicy();
 
-    // Watch the file directly if it exists.
-    if (!policyWatcher && fs.existsSync(policyPath)) {
-      policyWatcher = fs.watch(policyPath, (eventType) => {
-        if (eventType === 'change') applyPolicy();
-      });
-      // Unref so this watcher does not prevent one-shot CLI commands (e.g.
-      // `recall`) from exiting cleanly once their work is done.
-      policyWatcher.unref();
-    }
+    const watch = (target, onChange, clear) => {
+      try {
+        const watcher = fs.watch(target, onChange);
+        watcher.on('error', error => {
+          watcher.close();
+          clear(watcher);
+          logger.warn('throttled-fetch', `Network policy watcher unavailable: ${error.message}`);
+        });
+        watcher.unref();
+        return watcher;
+      } catch (error) {
+        logger.warn('throttled-fetch', `Network policy watcher unavailable: ${error.message}`);
+        return null;
+      }
+    };
+    const watchPolicy = () => {
+      if (policyWatcher || !fs.existsSync(policyPath)) return;
+      policyWatcher = watch(policyPath, event => {
+        if (event === 'change') applyPolicy();
+      }, watcher => { if (policyWatcher === watcher) policyWatcher = null; });
+    };
+    watchPolicy();
 
     // Also watch the parent directory so we pick up the policy file being
     // created after boot (e.g. first-run setups where the doc doesn't exist
     // yet). Attach the direct file watcher once it appears.
     if (!parentWatcher && fs.existsSync(systemDir)) {
-      parentWatcher = fs.watch(systemDir, (eventType, filename) => {
+      parentWatcher = watch(systemDir, (_event, filename) => {
         if (filename !== 'network-policy.md') return;
         applyPolicy();
-        if (!policyWatcher && fs.existsSync(policyPath)) {
-          policyWatcher = fs.watch(policyPath, (evt) => {
-            if (evt === 'change') applyPolicy();
-          });
-          policyWatcher.unref();
-        }
-      });
-      parentWatcher.unref();
+        watchPolicy();
+      }, watcher => { if (parentWatcher === watcher) parentWatcher = null; });
     }
   } catch (err) {
     logger.error('throttled-fetch', `Failed to load network policy: ${err.message}`);

package/src/core/ui-chunk-choice.mjs

@@ -0,0 +1,77 @@
+import { getPluginById } from './plugin-loader.mjs';
+import { pluginActivation } from './plugin-state.mjs';
+
+const decisionLimit = 20;
+
+async function requestChoice(state, questions, { projectRoot = process.cwd(), brainDir } = {}) {
+  const plugin = getPluginById('decision', projectRoot);
+  if (!plugin?.valid || !pluginActivation(plugin, { projectRoot }).enabled ||
+      !plugin.manifest.cli?.subcommands?.some(command => command.name === 'run')) return null;
+  const { runPluginCommand } = await import('./plugin-runner.mjs');
+  const run = await runPluginCommand(plugin, {
+    subcommand: 'run',
+    args: ['--state', JSON.stringify(state), '--questions', JSON.stringify(questions), '--json'],
+    timeoutMs: 15_000,
+    cwd: projectRoot ?? brainDir ?? process.cwd(),
+    projectRoot,
+  });
+  if ((!run.ok && run.exitCode !== 4) || run.truncated) return null;
+  return JSON.parse(run.stdout);
+}
+
+export async function chooseUiChunk(chunks, query, surface, decide = requestChoice) {
+  const result = await chooseBlocks(chunks, query, surface, ['selected_chunk'], decide);
+  const { keys, ...selection } = result;
+  return { ...selection, key: keys[0] ?? null };
+}
+
+export async function chooseUiComposition(chunks, query, decide, target) {
+  const choose = decide ?? ((state, questions) => requestChoice(state, questions, target));
+  return chooseBlocks(chunks, query, 'page', ['selected_chunk', 'supporting_chunk', 'reference_chunk'], choose, false);
+}
+
+const instructions = {
+  selected_chunk: 'Choose the primary block that best accomplishes the requested intent.',
+  supporting_chunk: 'Choose an additional block that helps accomplish the same task without repeating the primary block.',
+  reference_chunk: 'Choose an optional readout or reference block that gives useful context for the task.',
+};
+
+async function chooseBlocks(chunks, query, surface, slots, decide, skipSingle = true) {
+  const shortlist = chunks.slice(0, decisionLimit);
+  if (!shortlist.length) return { source: 'lexical', keys: [], reason: 'no-matches' };
+  const fallback = { source: 'lexical', keys: shortlist.slice(0, slots.length).map(chunk => chunk.key) };
+  if (skipSingle && shortlist.length === 1) return { ...fallback, reason: 'single-match' };
+
+  const criteria = Object.fromEntries(shortlist.map(chunk => {
+    const description = [chunk.title, chunk.description, ...chunk.intents, ...(chunk.operations || []), ...(chunk.data || [])].join(' ').slice(0, 600);
+    return [chunk.key, description];
+  }));
+  criteria.none = 'No eligible chunk fits this intent.';
+  const questions = Object.fromEntries(slots.slice(0, shortlist.length).map(slot => [slot, {
+    type: 'choice',
+    instructions: `${instructions[slot]} Choose none when nothing fits.`,
+    criteria,
+  }]));
+  let result;
+  try {
+    result = await decide({ intent: query, surface: surface ?? null }, questions);
+  } catch {
+    return { ...fallback, reason: 'decision-unavailable' };
+  }
+  if (result?.ok !== true) return { ...fallback, reason: 'decision-unavailable' };
+  const eligible = new Set(shortlist.map(chunk => chunk.key));
+  const primary = result.answers?.selected_chunk;
+  if (!confident(primary)) return { ...fallback, reason: 'decision-abstained' };
+  if (primary.choice === 'none') return { source: 'decision', keys: [], reason: 'no-fit', confidence: primary.confidence };
+  if (!eligible.has(primary.choice)) return { source: 'decision', keys: [], reason: 'invalid-choice' };
+  const keys = new Set([primary.choice]);
+  for (const slot of Object.keys(questions).slice(1)) {
+    const answer = result.answers?.[slot];
+    if (confident(answer) && eligible.has(answer.choice)) keys.add(answer.choice);
+  }
+  return { source: 'decision', keys: [...keys], confidence: primary.confidence };
+}
+
+function confident(answer) {
+  return answer?.act === true && Number.isFinite(answer.confidence) && answer.confidence >= 0.5 && answer.confidence <= 1;
+}

package/src/core/ui-chunk.registry.json

@@ -0,0 +1,23 @@
+{
+  "registry": "ui-chunk",
+  "extends": "ssss",
+  "version": "1.1.0",
+  "description": "Portable owner-authored HTML chunks for Total Recall workspace surfaces.",
+  "document_primitives": {
+    "chunk": {
+      "family": "capability",
+      "append_only": false,
+      "portability": "structural",
+      "filename_convention": "A kebab-case chunk ID under ui/chunks/ with the .md extension.",
+      "required_fields": ["type", "title", "description", "timestamp", "plugin", "id", "intents", "surfaces"],
+      "optional_fields": ["panel", "operations", "data"],
+      "immutable_fields": ["plugin", "id"],
+      "enums": { "surfaces": ["page", "left", "right", "bottom"] },
+      "patterns": {
+        "plugin": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+        "id": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+      },
+      "notes": "The body holds HTML. The host validates surface membership, file ownership and native panel bindings before publishing the catalog."
+    }
+  }
+}