@yeaft/webchat-agent 0.1.510 → 0.1.512

package/crew/routing-metrics.js

@@ -0,0 +1,215 @@
+/**
+ * task-330b — Routing metrics counter (Final Spec §B).
+ *
+ * Centralised observability for crew routing fallbacks. Five canonical
+ * reasons that any fallback path MUST pass to `recordRoutingEvent`:
+ *
+ *   - missing-route     : turn ended with no parseable ROUTE block
+ *   - parse-fail        : ROUTE block found but parse returned null/invalid
+ *   - self-route        : route.to resolves to the sender (rejected by §A)
+ *   - state-stopped     : message arrived while session was stopped/paused
+ *                         and was diverted/dropped
+ *   - fallback-forward  : auto-forward path engaged (non-PM → PM safety net)
+ *
+ * Counters are kept in-memory keyed by `${sessionId}::${reason}` and flushed
+ * to `${sharedDir}/context/routing-metrics.json` periodically (default 30s)
+ * AND on demand via `flushRoutingMetricsNow(session)`. The on-disk format:
+ *
+ *   {
+ *     "schemaVersion": 1,
+ *     "lastFlushedAt": <ms>,
+ *     "counts": {
+ *       "missing-route": 4,
+ *       "parse-fail": 1,
+ *       "self-route": 0,
+ *       "state-stopped": 2,
+ *       "fallback-forward": 4
+ *     },
+ *     "recent": [
+ *       { ts, reason, fromRole, toRole?, taskId?, note? },
+ *       ...                                  // bounded ring buffer (50)
+ *     ]
+ *   }
+ *
+ * Red lines (§330b):
+ *   - Pure observer; never mutates routing decisions.
+ *   - Never throws; failures degrade to console.warn so callers can rely on
+ *     `recordRoutingEvent()` being safe inside hot paths.
+ *
+ * Red lines (§330a — shared with this PR):
+ *   - No engine state-machine touch.
+ *   - PM-self-loop is the responsibility of §A; §B only records the metric
+ *     when §A rejects.
+ */
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+
+export const ROUTING_REASONS = Object.freeze([
+  'missing-route',
+  'parse-fail',
+  'self-route',
+  'state-stopped',
+  'fallback-forward',
+]);
+
+const REASON_SET = new Set(ROUTING_REASONS);
+const RECENT_RING_SIZE = 50;
+const FLUSH_INTERVAL_MS = 30_000;
+
+/**
+ * In-process state — ONE bag per process. Keyed by sessionId so multiple
+ * crew sessions running in the same agent each keep their own counts.
+ *
+ * Shape: Map<sessionId, {
+ *   sharedDir: string,
+ *   counts: Record<reason, number>,
+ *   recent: Array<{ ts, reason, fromRole, toRole?, taskId?, note? }>,
+ *   dirty: boolean,
+ *   flushTimer: NodeJS.Timeout | null,
+ * }>
+ */
+const _state = new Map();
+
+function _zeroCounts() {
+  const c = {};
+  for (const r of ROUTING_REASONS) c[r] = 0;
+  return c;
+}
+
+function _getOrInit(session) {
+  const sid = session?.id;
+  if (!sid) return null;
+  let bag = _state.get(sid);
+  if (!bag) {
+    bag = {
+      sharedDir: session.sharedDir || null,
+      counts: _zeroCounts(),
+      recent: [],
+      dirty: false,
+      flushTimer: null,
+    };
+    _state.set(sid, bag);
+  }
+  // sharedDir may not be available at session creation — keep latest.
+  if (session.sharedDir) bag.sharedDir = session.sharedDir;
+  return bag;
+}
+
+/**
+ * Record a routing fallback event.
+ *
+ * @param {object} session — crew session (must have .id; .sharedDir for flush)
+ * @param {string} reason — one of ROUTING_REASONS
+ * @param {object} [meta]
+ * @param {string} [meta.fromRole]
+ * @param {string} [meta.toRole]
+ * @param {string} [meta.taskId]
+ * @param {string} [meta.note]
+ * @returns {boolean} true if recorded; false if invalid input
+ */
+export function recordRoutingEvent(session, reason, meta = {}) {
+  if (!session || !session.id) return false;
+  if (!REASON_SET.has(reason)) {
+    console.warn(`[routing-metrics] Unknown reason: ${reason} (allowed: ${ROUTING_REASONS.join(', ')})`);
+    return false;
+  }
+  const bag = _getOrInit(session);
+  if (!bag) return false;
+
+  bag.counts[reason] = (bag.counts[reason] || 0) + 1;
+  bag.recent.push({
+    ts: Date.now(),
+    reason,
+    fromRole: meta.fromRole || null,
+    toRole: meta.toRole || null,
+    taskId: meta.taskId || null,
+    note: meta.note || null,
+  });
+  // Bound the ring.
+  if (bag.recent.length > RECENT_RING_SIZE) {
+    bag.recent.splice(0, bag.recent.length - RECENT_RING_SIZE);
+  }
+  bag.dirty = true;
+  _ensureTimer(session.id, bag);
+  return true;
+}
+
+function _ensureTimer(sessionId, bag) {
+  if (bag.flushTimer) return;
+  bag.flushTimer = setTimeout(() => {
+    bag.flushTimer = null;
+    _flush(sessionId, bag).catch((e) =>
+      console.warn(`[routing-metrics] periodic flush failed for ${sessionId}: ${e.message}`),
+    );
+  }, FLUSH_INTERVAL_MS);
+  // Don't keep the event loop alive solely for metrics flush.
+  if (typeof bag.flushTimer.unref === 'function') bag.flushTimer.unref();
+}
+
+async function _flush(sessionId, bag) {
+  if (!bag.dirty) return;
+  if (!bag.sharedDir) return; // can't flush without target dir
+  const dir = join(bag.sharedDir, 'context');
+  const file = join(dir, 'routing-metrics.json');
+  const payload = {
+    schemaVersion: 1,
+    lastFlushedAt: Date.now(),
+    counts: { ...bag.counts },
+    recent: bag.recent.slice(),
+  };
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    // Write-then-rename for atomicity (single-line file is small; tolerate
+    // platform quirks).
+    const tmp = `${file}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(payload, null, 2), 'utf8');
+    await fs.rename(tmp, file);
+    bag.dirty = false;
+  } catch (e) {
+    console.warn(`[routing-metrics] flush write failed: ${e.message}`);
+  }
+}
+
+/**
+ * Force a synchronous-ish flush (still returns a Promise). Useful from
+ * shutdown paths or tests.
+ */
+export async function flushRoutingMetricsNow(session) {
+  const bag = _state.get(session?.id);
+  if (!bag) return;
+  if (bag.flushTimer) {
+    clearTimeout(bag.flushTimer);
+    bag.flushTimer = null;
+  }
+  await _flush(session.id, bag);
+}
+
+/**
+ * Read current counts (test/inspection only; non-mutating snapshot).
+ * @returns {{ counts: Record<string, number>, recent: Array<object> } | null}
+ */
+export function getRoutingMetricsSnapshot(session) {
+  const bag = _state.get(session?.id);
+  if (!bag) return null;
+  return {
+    counts: { ...bag.counts },
+    recent: bag.recent.slice(),
+  };
+}
+
+/**
+ * Reset (test-only).
+ */
+export function _resetRoutingMetricsForTest(sessionId) {
+  if (sessionId) {
+    const bag = _state.get(sessionId);
+    if (bag?.flushTimer) clearTimeout(bag.flushTimer);
+    _state.delete(sessionId);
+    return;
+  }
+  for (const [, bag] of _state) {
+    if (bag.flushTimer) clearTimeout(bag.flushTimer);
+  }
+  _state.clear();
+}

package/crew/routing.js

@@ -1,12 +1,24 @@
 /**
  * Crew — 路由解析与执行
  * parseRoutes, executeRoute, buildRoutePrompt, dispatchToRole
+ *
+ * task-330c — Greedy-strip guard:
+ *   ⚠️ ROUTE-block stripping lives in `parseRoutes()` ONLY. Callers that
+ *      want the role's prose without ROUTE blocks must consume
+ *      `parseRoutes(text).displayBody` — never run a second
+ *      `text.replace(/---ROUTE---[\s\S]*$/g, '')` style strip on already
+ *      parser-cleaned text. A second strip would (a) re-process text
+ *      that no longer has ROUTE markers (no-op at best, miscut at worst),
+ *      (b) reintroduce the greedy tail-eating bug fixed by task-328.
+ *      The summary-fallback in role-output.js and the recent-routes
+ *      injector below both honour this contract.
  */
 import { join } from 'path';
 import { sendCrewMessage, sendCrewOutput, sendStatusUpdate } from './ui-messages.js';
 import { ensureTaskFile, appendTaskRecord, readTaskFile, updateKanban, readKanban, saveRoleWorkSummary } from './task-files.js';
 import { createRoleQuery, clearRoleSessionId } from './role-query.js';
 import { saveSessionMeta } from './persistence.js';
+import { recordRoutingEvent } from './routing-metrics.js';
 import ctx from '../context.js';
 
 /** Format role label */
@@ -14,6 +26,54 @@ function roleLabel(r) {
   return r.icon ? `${r.icon} ${r.displayName}` : r.displayName;
 }
 
+/**
+ * task-330c — Smart truncate for recent-routes / history snippets.
+ *
+ * Cuts at a sentence/line boundary when possible to avoid mid-sentence
+ * truncation; falls back to a hard cut when no good boundary exists in
+ * the candidate window. Always appends a marker so downstream readers
+ * (LLM roles seeing recent-routes context) know the full text lives
+ * elsewhere (feature file).
+ *
+ * Boundary detection: looks for the last period (`.` `。` `!` `?` `！` `？`)
+ * or newline inside the window `[Math.floor(max*0.7), max)`. The 70% lower
+ * bound is a quality floor — we don't want to cut so early that we lose
+ * meaningful tail context just to hit a clean boundary.
+ *
+ * Idempotent: text already short enough is returned unchanged (no marker).
+ *
+ * @param {string} text — input string (may be any length)
+ * @param {number} max  — maximum chars before truncation
+ * @returns {string}    — original text or `<truncated>…(truncated, full in feature file)`
+ */
+const TRUNCATE_MARKER = '…(truncated, full in feature file)';
+export function smartTruncate(text, max) {
+  if (typeof text !== 'string') return '';
+  if (!Number.isFinite(max) || max <= 0) return '';
+  if (text.length <= max) return text;
+
+  // Search window: prefer cuts in the last 30% of the limit.
+  const windowStart = Math.floor(max * 0.7);
+  const windowSlice = text.slice(windowStart, max);
+  // Last sentence boundary in window — period family OR newline.
+  // We accept a boundary char and cut AFTER it so the sentence stays whole.
+  const BOUNDARY_RE = /[.。!?！？\n]/g;
+  let bestIdx = -1;
+  let m;
+  while ((m = BOUNDARY_RE.exec(windowSlice)) !== null) {
+    bestIdx = m.index;
+  }
+  let cutEnd;
+  if (bestIdx !== -1) {
+    cutEnd = windowStart + bestIdx + 1; // include the boundary char itself
+  } else {
+    cutEnd = max; // no boundary in window → hard cut
+  }
+  // Trim trailing whitespace from the cut piece for cleaner output.
+  const head = text.slice(0, cutEnd).replace(/\s+$/, '');
+  return `${head}${TRUNCATE_MARKER}`;
+}
+
 /**
  * Append text to content — works for both string and multimodal array content.
  * For arrays, appends to the last text block (or adds a new one).
@@ -416,6 +476,77 @@ export function resolveRoleName(to, session, fromRole) {
 export async function executeRoute(session, fromRole, route, turnImages = []) {
   let { to, summary, taskId, taskTitle } = route;
 
+  // ─── task-330a §A + task-330b §B: self-route hard-reject + metric ───
+  // 福勒 Final Spec §A — `route.to` 等同于发送方时直接拒绝，不消费 turn、
+  // 不写 kanban、不 dispatch、不 round++（round 已由 role-output 计数）。
+  // 解析顺序：先尝试用 resolveRoleName 还原 alias（pm/dev/displayName/
+  // pm-乔布斯 等），命中即比较；未命中则退回原始字符串大小写不敏感比较。
+  // 拒绝时：先写 330b 的 routing-metrics.json 持久化 metric（observer 路径），
+  // 再 emit 330a 的 sendCrewMessage UI 卡片，最后 return（不消费 turn）。
+  // alias self-route 漏记 metric 已记入 PM backlog 作 follow-up（330b 的
+  // raw 比较 `to === fromRole` 仅命中字面相同的情况；alias 形式由 330a
+  // 的 isSelf 兜底，但 330b 的 raw 检查保留为快速路径 + 兼容）。
+  if (to !== 'human') {
+    const resolvedSelfCheck = resolveRoleName(to, session, fromRole);
+    const isSelf = resolvedSelfCheck === fromRole
+      || (typeof to === 'string' && to.toLowerCase() === String(fromRole).toLowerCase());
+    if (isSelf) {
+      console.warn(`[Crew] Self-route rejected: ${fromRole} → ${to} (taskId=${taskId || '-'})`);
+      // 330b path — persistent metric counter (routing-metrics.json + ring).
+      // Always-safe; never throws (recordRoutingEvent degrades to console.warn).
+      recordRoutingEvent(session, 'self-route', {
+        fromRole,
+        toRole: to,
+        taskId: taskId || null,
+        note: 'route.to === fromRole at executeRoute entry (rejected by §A)',
+      });
+      // 330a path — UI broadcast so the role sees rejection in transcript.
+      try {
+        sendCrewMessage({
+          type: 'routing-metrics',
+          sessionId: session.id,
+          event: 'route_rejected',
+          reason: 'self-route',
+          fromRole,
+          to,
+          taskId: taskId || null,
+          timestamp: Date.now(),
+        });
+      } catch (e) {
+        console.warn('[Crew] Failed to emit routing-metrics:', e.message);
+      }
+      try {
+        sendCrewMessage({
+          type: 'crew_route_rejected',
+          sessionId: session.id,
+          fromRole,
+          to,
+          reason: 'self-route',
+          message: `自路由被拒绝：${fromRole} 不能给自己发消息。请改用 task_close(taskId, summary) 关闭任务，或 role_standby(role) 进入待命，或选择其他角色作为 ROUTE 目标。`,
+          taskId: taskId || null,
+        });
+      } catch (e) {
+        console.warn('[Crew] Failed to emit crew_route_rejected:', e.message);
+      }
+      // Do NOT decrement session.round — role-output.js already incremented
+      // it for this whole turn batch; one rejected route doesn't undo the
+      // turn (other routes in the same batch may still be valid).
+      return;
+    }
+  }
+
+  // task-330b §B item 1: state-stopped metric — message arrived while
+  // session was paused/stopped. Behaviour (auto-resume) is unchanged for
+  // backward compat; this is observer-only.
+  if (session.status === 'paused' || session.status === 'stopped') {
+    recordRoutingEvent(session, 'state-stopped', {
+      fromRole,
+      toRole: to,
+      taskId: taskId || null,
+      note: `session.status=${session.status} at executeRoute entry`,
+    });
+  }
+
   // Auto-resume: paused/stopped → running (route execution means work should continue)
   if (session.status === 'paused' || session.status === 'stopped') {
     console.log(`[Crew] Auto-resuming session from ${session.status} to running (route from ${fromRole} to ${to})`);
@@ -620,11 +751,21 @@ export async function dispatchToRole(session, roleName, content, fromSource, tas
   }
 
   // 最近路由消息注入（帮助 clear 后的角色恢复上下文）
+  // task-330c: each entry is smart-truncated to 400 chars at a sentence
+  // boundary (period/newline) so we don't slice key info mid-sentence.
+  // The full content lives in the feature file — the marker tells the
+  // role where to look if they need more context. The pre-stored
+  // `m.content` was already truncated to 200 (history step below) until
+  // task-330c bumped it to 400 + smart boundary.
+  // ⚠️ DO NOT pass `m.content` through any greedy `.replace(/.../g, '')`
+  //    here — it has already been derived from displayBody at message
+  //    time (parser-stripped), and a second strip would re-process
+  //    text that no longer holds ROUTE markers. See _appendHistory below.
   if (session.messageHistory.length > 0) {
     const recentRoutes = session.messageHistory
       .filter(m => m.from !== 'system')
       .slice(-5)
-      .map(m => `[${m.from} → ${m.to}${m.taskId ? ` (${m.taskId})` : ''}] ${m.content}`)
+      .map(m => `[${m.from} → ${m.to}${m.taskId ? ` (${m.taskId})` : ''}] ${smartTruncate(m.content, 400)}`)
       .join('\n');
     if (recentRoutes) {
       const ctx = `\n\n---\n<recent-routes>\n${recentRoutes}\n</recent-routes>`;
@@ -633,9 +774,15 @@ export async function dispatchToRole(session, roleName, content, fromSource, tas
   }
 
   // 记录消息历史
+  // task-330c: cap raised 200 → 400 to match the recent-routes injection
+  // window. Keeping the pre-store cap at 200 would pin every entry below
+  // smartTruncate's 400 threshold, making the smart-truncate boundary cut
+  // a permanent no-op in production. 400 here lets longer messages flow
+  // into history; smartTruncate trims them at sentence boundaries when
+  // injected into <recent-routes>.
   const historyContent = typeof content === 'string'
-    ? content.substring(0, 200)
-    : (Array.isArray(content) ? content.filter(b => b.type === 'text').map(b => b.text).join('').substring(0, 200) + (content.some(b => b.type === 'image') ? ' [+images]' : '') : '...');
+    ? content.substring(0, 400)
+    : (Array.isArray(content) ? content.filter(b => b.type === 'text').map(b => b.text).join('').substring(0, 400) + (content.some(b => b.type === 'image') ? ' [+images]' : '') : '...');
   session.messageHistory.push({
     from: fromSource,
     to: roleName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.510",
+  "version": "0.1.512",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/engine.js

@@ -43,6 +43,47 @@ import { normalizeEffort } from './models.js';
 /** Maximum auto-continue turns when stopReason is 'max_tokens'. */
 const MAX_CONTINUE_TURNS = 3;
 
+/**
+ * task-331 — Map a conversationMessages entry into the snapshot shape used
+ * by `debug_turn.messages`. Preserves the function-calling metadata that
+ * the Debug panel needs to render:
+ *   - `toolCalls` on assistant turns (the LLM's function_call requests)
+ *   - `toolCallId` + `isError` on tool turns (the paired tool_result)
+ *
+ * Content is truncated at 50000 chars; each tool_call input is JSON-stringified
+ * + sliced at 10000 chars before being re-parsed, so a runaway `input` blob
+ * can't blow past the WebSocket frame budget. Unknown roles pass through
+ * unchanged.
+ *
+ * Pure function — no side effects on the input message.
+ *
+ * @param {{ role: string, content?: any, toolCalls?: Array, toolCallId?: string, isError?: boolean }} m
+ * @returns {{ role: string, content: any, toolCalls?: Array, toolCallId?: string, isError?: boolean }}
+ */
+export function mapDebugMessage(m) {
+  const out = { role: m.role };
+  out.content = typeof m.content === 'string' ? m.content.slice(0, 50000) : m.content;
+  if (Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
+    out.toolCalls = m.toolCalls.map(tc => {
+      let input = tc.input;
+      try {
+        const s = JSON.stringify(input);
+        if (typeof s === 'string' && s.length > 10000) {
+          input = { __truncated: true, preview: s.slice(0, 10000) };
+        }
+      } catch {
+        // Non-serializable input — fall through with raw reference; the
+        // frontend's JSON.stringify will hit the same failure and replace
+        // it with a placeholder string.
+      }
+      return { id: tc.id, name: tc.name, input };
+    });
+  }
+  if (m.toolCallId) out.toolCallId = m.toolCallId;
+  if (m.isError != null) out.isError = m.isError;
+  return out;
+}
+
 // ─── Engine Events (superset of adapter events) ──────────────────
 
 /**
@@ -289,6 +330,13 @@ export class Engine {
       conversationStore: this.#conversationStore,
       adapter: this.#adapter,
       config: this.#config,
+      // ViewImage (task-333b PR-B rev-3 P1-A): expose size cap + allowlist
+      // via tool ctx so hosts can override via ~/.yeaft/config.json without
+      // touching the tool impl.
+      maxImageBytes: this.#config?.unify?.maxImageBytes,
+      imageAllowlist: Array.isArray(this.#config?.unify?.imageAllowlist)
+        ? this.#config.unify.imageAllowlist
+        : [],
     };
   }
 
@@ -508,8 +556,8 @@ export class Engine {
 
     // ─── Pre-query: Memory Injection (task-287) + Compact Summary ──
     // New layout: always inject Memory Index + user-preferences + project
-    // header excerpt. No per-turn fuzzy recall — LLM calls memory_search /
-    // memory_query on demand.
+    // header excerpt. No per-turn fuzzy recall — LLM calls memory_load /
+    // memory_query on demand (memory_search still works as a deprecated alias).
     let memoryInjection = '';
     if (this.#yeaftDir) {
       try {
@@ -634,7 +682,7 @@ export class Engine {
           turnNumber,
           model: currentModel,
           systemPrompt,
-          messages: conversationMessages.map(m => ({ role: m.role, content: typeof m.content === 'string' ? m.content.slice(0, 50000) : m.content })),
+          messages: conversationMessages.map(mapDebugMessage),
           response: responseText || `Error: ${err.message}`,
           toolCalls: toolCalls.map(tc => ({ id: tc.id, name: tc.name, input: tc.input })),
           usage: { inputTokens: totalUsage.inputTokens, outputTokens: totalUsage.outputTokens },
@@ -702,12 +750,15 @@ export class Engine {
 
       // Emit debug_turn event for web UI debug panel
       // (conversationMessages does NOT yet include the assistant response at this point)
+      // task-331: preserve toolCalls / toolCallId / isError on each message so
+      // the Debug panel can render function_call requests and their paired
+      // tool_result responses across turns.
       yield {
         type: 'debug_turn',
         turnNumber,
         model: currentModel,
         systemPrompt,
-        messages: conversationMessages.map(m => ({ role: m.role, content: typeof m.content === 'string' ? m.content.slice(0, 50000) : m.content })),
+        messages: conversationMessages.map(mapDebugMessage),
         response: responseText,
         toolCalls: toolCalls.map(tc => ({ id: tc.id, name: tc.name, input: tc.input })),
         usage: { inputTokens: totalUsage.inputTokens, outputTokens: totalUsage.outputTokens },

package/unify/memory/layout.js

@@ -265,7 +265,7 @@ export function renderIndex(yeaftDir, entryCount) {
   lines.push('## entries', '', `- ${entryCount} atomic entries (use memory_query to search)`, '');
 
   lines.push(
-    '_Note: use the `memory_search` tool with one or more paths to load a classification',
+    '_Note: use the `memory_load` tool with one or more paths to load a classification',
     'file in full, or `memory_query` to search atomic entries by keywords/tags._',
   );
 

package/unify/prompts.js

@@ -32,18 +32,53 @@ const TEMPLATES_DIR = join(__dirname, 'templates');
 
 /**
  * Read a template file from the templates/ directory.
- * Returns empty string if file doesn't exist or can't be read.
+ *
+ * task-332c F3 — missing-template guard:
+ * Required templates MUST be present. If a required template is missing or
+ * unreadable, throw a clear error instead of silently degrading to the
+ * hardcoded fallback. Silent skip previously hid misconfigured deployments
+ * (empty prompts shipped to production), so we now fail fast at load time.
+ *
+ * Non-required templates (passed with { required: false }) retain the old
+ * "return empty string on absence" behavior for optional inclusions.
+ *
  * @param {string} name — filename (e.g. 'base.md')
+ * @param {{ required?: boolean }} [opts]
  * @returns {string}
+ * @throws {Error} when required=true and the file is missing / unreadable / empty
  */
-function readTemplate(name) {
+function readTemplate(name, { required = true } = {}) {
   const path = join(TEMPLATES_DIR, name);
-  if (!existsSync(path)) return '';
+  if (!existsSync(path)) {
+    if (required) {
+      throw new Error(
+        `[prompts] Required template missing: ${name} ` +
+        `(expected at ${path}). Templates are part of the agent package — ` +
+        `check the install or build output.`
+      );
+    }
+    return '';
+  }
+  let content;
   try {
-    return readFileSync(path, 'utf8').trim();
-  } catch {
+    content = readFileSync(path, 'utf8');
+  } catch (e) {
+    if (required) {
+      throw new Error(
+        `[prompts] Required template unreadable: ${name} ` +
+        `(at ${path}): ${e.message}`
+      );
+    }
     return '';
   }
+  const trimmed = content.trim();
+  if (!trimmed && required) {
+    throw new Error(
+      `[prompts] Required template is empty: ${name} (at ${path}). ` +
+      `An empty system prompt template would ship a degenerate prompt to the LLM.`
+    );
+  }
+  return trimmed;
 }
 
 /**

package/unify/tools/index.js

@@ -20,7 +20,7 @@ import exitWorktree from './exit-worktree.js';
 import askUser from './ask-user.js';
 import memoryRead from './memory-read.js';
 import memoryWrite from './memory-write.js';
-import memorySearch from './memory-search.js';
+import memorySearch, { memorySearchAlias } from './memory-search.js';
 import memoryQuery from './memory-query.js';
 import webSearch from './web-search.js';
 import webFetch from './web-fetch.js';
@@ -67,13 +67,14 @@ import {
 } from './thread-tools.js';
 
 // --- P2 Auxiliary tools ---
+// task-333b L1 delete: ToolSearch and WriteStdin removed — the function-call
+// schema already exposes all tools, so ToolSearch was redundant; WriteStdin
+// was a stub returning a hint about Bash piping.
 import { jsRepl, jsReplReset } from './js-repl.js';
 import notebookEdit from './notebook-edit.js';
 import imageGeneration from './image-generation.js';
 import viewImage from './view-image.js';
-import toolSearch from './tool-search.js';
 import requestPermissions from './request-permissions.js';
-import writeStdin from './write-stdin.js';
 
 /**
  * All built-in tools, flattened into a single array.
@@ -92,6 +93,7 @@ export const allTools = [
   memoryRead,
   memoryWrite,
   memorySearch,
+  memorySearchAlias,
   memoryQuery,
   webSearch,
   webFetch,
@@ -139,9 +141,7 @@ export const allTools = [
   notebookEdit,
   imageGeneration,
   viewImage,
-  toolSearch,
   requestPermissions,
-  writeStdin,
 ];
 
 /**