@yeaft/webchat-agent 0.1.511 → 0.1.512

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.511",
+  "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,
 ];
 
 /**

package/unify/tools/js-repl.js

@@ -3,6 +3,11 @@
  *
  * Runs JavaScript code in a persistent VM context, allowing
  * state to be maintained across calls.
+ *
+ * task-333b: merged the former `JsReplReset` tool into this one as a
+ * `reset: true` parameter. A single tool with a reset flag eliminates a
+ * duplicate schema entry in the function-call catalogue. The old
+ * JsReplReset name is kept below as a deprecated alias for one release.
  */
 
 import { defineTool } from './types.js';
@@ -55,7 +60,9 @@ defined in one call are available in subsequent calls.
 
 Guidelines:
 - Use for calculations, data transformations, and quick experiments
-- State is preserved between calls (use JsReplReset to clear)
+- State is preserved between calls
+- Pass \`reset: true\` to wipe all state before evaluating (clean slate).
+  \`code\` becomes optional in this mode — pass reset alone to just clear.
 - console.log output is captured and returned
 - Returns the last expression's value plus any console output
 - No filesystem or network access from within the REPL`,
@@ -64,16 +71,27 @@ Guidelines:
     properties: {
       code: {
         type: 'string',
-        description: 'JavaScript code to evaluate',
+        description: 'JavaScript code to evaluate. Optional when reset=true and you only want to clear state.',
+      },
+      reset: {
+        type: 'boolean',
+        description: 'When true, reset the REPL context BEFORE evaluating `code`. If `code` is omitted, just resets.',
       },
     },
-    required: ['code'],
   },
   isConcurrencySafe: () => false,
   isReadOnly: () => true,
   async execute(input, ctx) {
-    const { code } = input;
-    if (!code) return JSON.stringify({ error: 'code is required' });
+    const { code, reset } = input || {};
+
+    if (reset) {
+      vmContext = null;
+      if (!code) {
+        return JSON.stringify({ success: true, message: 'REPL context reset' });
+      }
+    }
+
+    if (!code) return JSON.stringify({ error: 'code is required (or pass reset=true to clear state)' });
 
     const vmCtx = getContext();
 
@@ -87,6 +105,7 @@ Guidelines:
       const resultStr = result === undefined ? '' : String(result);
 
       const parts = [];
+      if (reset) parts.push('(REPL context reset)');
       if (output.length > 0) parts.push(output.join('\n'));
       if (resultStr) parts.push(`→ ${resultStr}`);
 
@@ -101,20 +120,28 @@ Guidelines:
   },
 });
 
+/**
+ * Deprecated alias — `JsReplReset`. task-333b merged reset behaviour into
+ * `JsRepl` via `reset: true`. Kept registered for one release so older
+ * prompts / saved tool calls still resolve. Emits a one-time deprecation
+ * warning on first invocation, then delegates to jsRepl.execute with reset.
+ */
+const _jsReplResetWarned = { v: false };
+function warnJsReplResetDeprecated() {
+  if (_jsReplResetWarned.v) return;
+  _jsReplResetWarned.v = true;
+  // eslint-disable-next-line no-console
+  console.warn('[deprecated] JsReplReset → JsRepl. Call JsRepl with { reset: true } to clear REPL state.');
+}
+
 export const jsReplReset = defineTool({
   name: 'JsReplReset',
-  description: `Reset the JavaScript REPL environment.
-
-Clears all variables and state from previous evaluations.
-Use when you want a clean slate.`,
-  parameters: {
-    type: 'object',
-    properties: {},
-  },
+  description: 'DEPRECATED — use JsRepl with `reset: true` instead. Resets the persistent REPL context. Removal target: v0.2.0.',
+  parameters: { type: 'object', properties: {} },
   isConcurrencySafe: () => false,
   isReadOnly: () => false,
   async execute(input, ctx) {
-    vmContext = null;
-    return JSON.stringify({ success: true, message: 'REPL context reset' });
+    warnJsReplResetDeprecated();
+    return jsRepl.execute({ reset: true }, ctx);
   },
 });

package/unify/tools/memory-query.js

@@ -10,7 +10,9 @@
  *   3. Returns a compact list suitable for LLM consumption
  *
  * Use this for fuzzy discovery over atomic entries. For loading a known
- * classification file in full, use `memory_search` instead.
+ * classification file in full, use `memory_load` instead (renamed from
+ * the old `memory_search` in task-333b; the old name still works as a
+ * deprecated alias for one release).
  */
 
 import { defineTool } from './types.js';

package/unify/tools/memory-search.js

@@ -1,7 +1,12 @@
 /**
- * memory-search.js — Load memory classification files by path.
+ * memory-search.js → memory_load (task-333b rename).
  *
- * New-layout tool (task-287 memory refactor).
+ * This tool loads memory classification files by path (it is NOT a search).
+ * task-333b renamed it from `memory_search` → `memory_load` so the name
+ * actually reflects behaviour; `memory_query` remains the fuzzy search tool.
+ *
+ * Backwards compatibility: a thin alias tool named `memory_search` is also
+ * exported (see bottom of file) so older transcripts/prompts still resolve.
  *
  * The system prompt injects `index.md` every turn, which lists all available
  * classification files under `~/.yeaft/memory/` (single files + by-project /
@@ -9,9 +14,6 @@
  * it calls this tool with `paths: [...]` to load one or more of those files
  * in full.
  *
- * This is NOT a fuzzy search. It is a precise file loader. Use `memory_query`
- * for fuzzy search over atomic entries.
- *
  * Only paths under `memory/` are accepted. `..` segments are rejected.
  */
 
@@ -21,9 +23,7 @@ import { readMemoryFile, listClassificationFiles } from '../memory/layout.js';
 const MAX_FILES_PER_CALL = 5;
 const MAX_BYTES_PER_FILE = 32000;
 
-export default defineTool({
-  name: 'memory_search',
-  description: `Load one or more memory classification files in full.
+const DESCRIPTION = `Load one or more memory classification files in full.
 
 Paths are relative to ~/.yeaft/memory/. Allowed targets:
   - user-preferences.md           — merged user preferences
@@ -36,66 +36,105 @@ of available files. Use this tool when the index suggests a file is relevant
 to the user's current request. For fuzzy search over atomic memory entries
 (facts, lessons, preferences), use the memory_query tool instead.
 
-Up to ${MAX_FILES_PER_CALL} files per call. Each file is capped at ${MAX_BYTES_PER_FILE} bytes.`,
-  parameters: {
-    type: 'object',
-    properties: {
-      paths: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'Relative paths under memory/. Example: ["by-project/claude-web-chat.md", "user-preferences.md"]',
-      },
+Up to ${MAX_FILES_PER_CALL} files per call. Each file is capped at ${MAX_BYTES_PER_FILE} bytes.`;
+
+const PARAMETERS = {
+  type: 'object',
+  properties: {
+    paths: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Relative paths under memory/. Example: ["by-project/claude-web-chat.md", "user-preferences.md"]',
     },
-    required: ['paths'],
   },
-  isConcurrencySafe: () => true,
-  isReadOnly: () => true,
-  async execute(input, ctx) {
-    const yeaftDir = ctx?.yeaftDir;
-    if (!yeaftDir) {
-      return JSON.stringify({ error: 'Memory system not initialized (no yeaftDir in context)' });
-    }
+  required: ['paths'],
+};
 
-    const paths = Array.isArray(input?.paths) ? input.paths : [];
-    if (paths.length === 0) {
-      return JSON.stringify({
-        error: 'paths is required and must be a non-empty string array',
-        availablePaths: listClassificationFiles(yeaftDir).map(f => f.path),
-      });
+async function executeLoad(input, ctx) {
+  const yeaftDir = ctx?.yeaftDir;
+  if (!yeaftDir) {
+    return JSON.stringify({ error: 'Memory system not initialized (no yeaftDir in context)' });
+  }
+
+  const paths = Array.isArray(input?.paths) ? input.paths : [];
+  if (paths.length === 0) {
+    return JSON.stringify({
+      error: 'paths is required and must be a non-empty string array',
+      availablePaths: listClassificationFiles(yeaftDir).map(f => f.path),
+    });
+  }
+
+  const results = [];
+  const errors = [];
+
+  for (const rel of paths.slice(0, MAX_FILES_PER_CALL)) {
+    if (typeof rel !== 'string' || !rel.trim()) {
+      errors.push({ path: rel, error: 'not a non-empty string' });
+      continue;
+    }
+    if (rel.includes('..') || rel.startsWith('/')) {
+      errors.push({ path: rel, error: 'path must be relative and must not contain ..' });
+      continue;
+    }
+    if (!rel.endsWith('.md')) {
+      errors.push({ path: rel, error: 'only .md files are supported' });
+      continue;
     }
 
-    const results = [];
-    const errors = [];
-
-    for (const rel of paths.slice(0, MAX_FILES_PER_CALL)) {
-      if (typeof rel !== 'string' || !rel.trim()) {
-        errors.push({ path: rel, error: 'not a non-empty string' });
-        continue;
-      }
-      if (rel.includes('..') || rel.startsWith('/')) {
-        errors.push({ path: rel, error: 'path must be relative and must not contain ..' });
-        continue;
-      }
-      if (!rel.endsWith('.md')) {
-        errors.push({ path: rel, error: 'only .md files are supported' });
-        continue;
-      }
-
-      const text = readMemoryFile(yeaftDir, rel);
-      if (!text) {
-        errors.push({ path: rel, error: 'file not found or empty' });
-        continue;
-      }
-
-      const truncated = text.length > MAX_BYTES_PER_FILE;
-      results.push({
-        path: rel,
-        content: truncated ? text.slice(0, MAX_BYTES_PER_FILE) : text,
-        truncated,
-        size: text.length,
-      });
+    const text = readMemoryFile(yeaftDir, rel);
+    if (!text) {
+      errors.push({ path: rel, error: 'file not found or empty' });
+      continue;
     }
 
-    return JSON.stringify({ results, errors }, null, 2);
-  },
+    const truncated = text.length > MAX_BYTES_PER_FILE;
+    results.push({
+      path: rel,
+      content: truncated ? text.slice(0, MAX_BYTES_PER_FILE) : text,
+      truncated,
+      size: text.length,
+    });
+  }
+
+  return JSON.stringify({ results, errors }, null, 2);
+}
+
+/**
+ * Canonical tool — `memory_load`. This is the default export so existing
+ * import sites (`import memorySearch from './memory-search.js'`) keep
+ * working; the renamed identity is expressed via the tool's `name`.
+ */
+const memoryLoad = defineTool({
+  name: 'memory_load',
+  description: DESCRIPTION,
+  parameters: PARAMETERS,
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  execute: executeLoad,
+});
+
+/**
+ * Deprecated alias — `memory_search`. Kept so older prompts / saved tool
+ * calls still resolve. Delegates to the same executor. Do not use for new
+ * call sites. Emits a one-time console.warn on first invocation.
+ */
+const _memSearchWarned = { v: false };
+async function executeLoadWithWarn(input, ctx) {
+  if (!_memSearchWarned.v) {
+    _memSearchWarned.v = true;
+    // eslint-disable-next-line no-console
+    console.warn('[deprecated] memory_search → memory_load. Use memory_load for path-based file loading; use memory_query for fuzzy keyword search.');
+  }
+  return executeLoad(input, ctx);
+}
+
+export const memorySearchAlias = defineTool({
+  name: 'memory_search',
+  description: 'DEPRECATED — use memory_load. Same params. Removal target: v0.2.0.',
+  parameters: PARAMETERS,
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  execute: executeLoadWithWarn,
 });
+
+export default memoryLoad;

package/unify/tools/task-tools.js

@@ -48,7 +48,9 @@ export const taskCreate = defineTool({
 
 Tasks have a title, description, priority, and status.
 Each task gets its own folder with task.md, progress.md, and memory.md.
-Use this to break down complex work into trackable items.`,
+Use this to break down complex work into trackable items.
+
+Pass \`parent_id\` to create a subtask under an existing task.`,
   parameters: {
     type: 'object',
     properties: {
@@ -69,6 +71,10 @@ Use this to break down complex work into trackable items.`,
         type: 'string',
         description: 'Parent task ID for subtasks',
       },
+      // Note (task-333b): `parent_task_id` is accepted by execute() as a
+      // soft-compat alias for `parent_id` (absorbed from the former
+      // SpawnTask tool) but intentionally NOT advertised in the schema to
+      // avoid giving the LLM two live params for one field.
     },
     required: ['title'],
   },
@@ -78,9 +84,17 @@ Use this to break down complex work into trackable items.`,
     const err = requireStore();
     if (err) return err;
 
-    const { title, description, priority = 'medium', parent_id } = input;
+    const { title, description, priority = 'medium', parent_id, parent_task_id } = input;
     if (!title) return JSON.stringify({ error: 'title is required' });
 
+    // task-333b: accept either `parent_id` (original TaskCreate field) or
+    // `parent_task_id` (the former SpawnTask field). When both are present,
+    // parent_id wins.
+    const parentId = parent_id || parent_task_id || null;
+    if (parentId && !taskStore.get(parentId)) {
+      return JSON.stringify({ error: `Parent task not found: ${parentId}` });
+    }
+
     const id = `task-${randomUUID().slice(0, 8)}`;
     const task = {
       id,
@@ -88,7 +102,8 @@ Use this to break down complex work into trackable items.`,
       description: description || '',
       priority,
       status: 'pending',
-      parentId: parent_id || null,
+      parentId,
+      parentTaskId: parentId, // design §5 canonical field
       createdAt: Date.now(),
       updatedAt: Date.now(),
     };
@@ -97,8 +112,10 @@ Use this to break down complex work into trackable items.`,
 
     return JSON.stringify({
       success: true,
-      task: { id, title, priority, status: 'pending' },
-      message: `Task created: ${title} (${id})`,
+      task: { id, title, priority, status: 'pending', parentTaskId: parentId },
+      message: parentId
+        ? `Subtask created: ${title} (${id}) under ${parentId}`
+        : `Task created: ${title} (${id})`,
     });
   },
 });

package/unify/tools/thread-tools.js

@@ -193,20 +193,24 @@ the same thread.`,
   },
 });
 
-// ─── SpawnTask (merged — subtask via parent_task_id) ────
+// ─── SpawnTask (deprecated alias — task-333b) ──────────────
+//
+// task-333b folded SpawnTask into TaskCreate (see task-tools.js). Kept
+// registered for one release as a deprecated alias per PM constraint:
+// LLM calls still resolve, but a one-time console.warn nudges migration.
+// Prefer TaskCreate with `parent_task_id` for all new call sites.
+
+const _spawnTaskWarned = { v: false };
+function warnSpawnTaskDeprecated() {
+  if (_spawnTaskWarned.v) return;
+  _spawnTaskWarned.v = true;
+  // eslint-disable-next-line no-console
+  console.warn('[deprecated] SpawnTask → TaskCreate. Pass parent_task_id to TaskCreate for subtasks.');
+}
 
-/**
- * SpawnTask replaces both the old SpawnTask and the separate SpawnSubtask:
- * pass `parent_task_id` when you want a subtask, omit it for top-level.
- * Per prev-1 rework note: eliminating two tools with the same effect.
- */
 export const spawnTask = defineTool({
   name: 'SpawnTask',
-  description: `Spawn a new task. Pass parent_task_id to create a subtask.
-
-When parent_task_id is omitted → top-level task.
-When parent_task_id is provided → subtask under that parent (parent must exist).
-This replaces the deprecated SpawnSubtask tool.`,
+  description: `DEPRECATED — use TaskCreate with parent_id instead. Retained as a thin alias for backwards compatibility; delegates to the same task store. When parent_task_id is omitted this behaves like TaskCreate; when provided it creates a subtask under that parent (parent must exist). Removal target: v0.2.0.`,
   parameters: {
     type: 'object',
     properties: {
@@ -226,6 +230,7 @@ This replaces the deprecated SpawnSubtask tool.`,
   isConcurrencySafe: () => false,
   isReadOnly: () => false,
   async execute(input) {
+    warnSpawnTaskDeprecated();
     const store = getTaskStore();
     if (!store) {
       return JSON.stringify({ error: 'Task store not initialized. Session may still be loading.' });

package/unify/tools/view-image.js

@@ -1,31 +1,68 @@
 /**
- * view-image.js — Read and describe an image file.
+ * view-image.js — Load a local image file into the LLM's context.
  *
- * Returns image metadata (dimensions, format, size).
- * In a full multimodal integration, would pass the image to the LLM.
+ * task-333b PR-B: upgraded from metadata-only stub to a real multimodal
+ * loader. Returns a tool result that includes:
+ *   - `image`: a base64-encoded data URI suitable for embedding into an
+ *     LLM image content block (OpenAI / Anthropic style)
+ *   - `media_type`: the canonical MIME (image/png, image/jpeg, ...)
+ *   - `format`, `width`, `height`, `size`, `sizeFormatted`, `path`
+ *
+ * Safety rules (per PM 乔布斯 PR-B spec + prev-3 product review):
+ *   - Path safety: no `..`, no absolute paths escaping cwd unless the
+ *     resolved path lives under ctx.imageAllowlist[] (absolute dirs
+ *     provided by the host).
+ *   - Size cap: configurable via ctx.maxImageBytes (default 20 MiB).
+ *     Larger files are rejected with a self-correcting error message
+ *     that nudges resize/crop or config.json tuning.
+ *   - MIME whitelist: png / jpeg / gif / webp / jfif. SVG / BMP / ICO /
+ *     TIFF are intentionally excluded — they either aren't multimodal-
+ *     LLM-safe (SVG = embedded script surface) or aren't supported by
+ *     the mainstream vision endpoints.
+ *   - HEIC is special-cased: we cannot decode it server-side, but the
+ *     error nudges the user to convert via `sips -s format jpeg` (mac)
+ *     instead of a generic "Unsupported format".
  */
 
 import { defineTool } from './types.js';
 import { stat, readFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { resolve, extname } from 'path';
+import { resolve, extname, isAbsolute, relative } from 'path';
 
-/** Supported image formats. */
-const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp', '.svg', '.ico']);
+/** Default max image size in bytes (20 MiB). Override via ctx.maxImageBytes. */
+const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
 
 /**
- * Parse basic image dimensions from headers.
+ * Extension → canonical MIME type.
+ * The keys are the whitelist; anything else is rejected.
+ * `.jfif` (common Windows paste extension) maps to image/jpeg.
+ */
+const EXT_TO_MIME = Object.freeze({
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.jfif': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+});
+
+const ALLOWED_EXTS = Object.keys(EXT_TO_MIME);
+
+/**
+ * Parse basic image dimensions from header bytes. Best-effort — returns
+ * null if the file is too short or the format isn't one we parse.
+ *
+ * @param {Buffer} buffer
+ * @param {string} ext — lowercase extension including the dot
  */
 function parseImageDimensions(buffer, ext) {
   try {
-    if (ext === '.png') {
+    if (ext === '.png' && buffer.length >= 24) {
       // PNG: width at offset 16, height at 20 (big-endian 32-bit)
-      if (buffer.length >= 24) {
-        return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
-      }
+      return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
     }
-    if (ext === '.jpg' || ext === '.jpeg') {
-      // JPEG: scan for SOF0 marker (0xFF 0xC0)
+    if ((ext === '.jpg' || ext === '.jpeg' || ext === '.jfif') && buffer.length > 10) {
+      // JPEG: scan for SOF0 (0xFFC0) / SOF2 (0xFFC2) marker
       for (let i = 0; i < buffer.length - 9; i++) {
         if (buffer[i] === 0xFF && (buffer[i + 1] === 0xC0 || buffer[i + 1] === 0xC2)) {
           return {
@@ -35,30 +72,117 @@ function parseImageDimensions(buffer, ext) {
         }
       }
     }
-    if (ext === '.gif') {
+    if (ext === '.gif' && buffer.length >= 10) {
       // GIF: width at offset 6, height at 8 (little-endian 16-bit)
-      if (buffer.length >= 10) {
-        return { width: buffer.readUInt16LE(6), height: buffer.readUInt16LE(8) };
+      return { width: buffer.readUInt16LE(6), height: buffer.readUInt16LE(8) };
+    }
+    if (ext === '.webp' && buffer.length >= 30) {
+      // WEBP: RIFF...WEBP...VP8(L|X| ). Three common sub-chunks.
+      if (buffer.slice(0, 4).toString('ascii') === 'RIFF' &&
+          buffer.slice(8, 12).toString('ascii') === 'WEBP') {
+        const fourcc = buffer.slice(12, 16).toString('ascii');
+        if (fourcc === 'VP8 ' && buffer.length >= 30) {
+          // Lossy: width/height at 26/28 as 14-bit LE (mask 0x3FFF)
+          return {
+            width: buffer.readUInt16LE(26) & 0x3FFF,
+            height: buffer.readUInt16LE(28) & 0x3FFF,
+          };
+        }
+        if (fourcc === 'VP8L' && buffer.length >= 25) {
+          // Lossless: packed 14+14 bits at offset 21
+          const b0 = buffer[21], b1 = buffer[22], b2 = buffer[23], b3 = buffer[24];
+          const width = 1 + (((b1 & 0x3F) << 8) | b0);
+          const height = 1 + (((b3 & 0x0F) << 10) | (b2 << 2) | ((b1 & 0xC0) >> 6));
+          return { width, height };
+        }
+        if (fourcc === 'VP8X' && buffer.length >= 30) {
+          // Extended: 24-bit LE widths/heights at 24/27, stored as (n-1)
+          const width = 1 + (buffer[24] | (buffer[25] << 8) | (buffer[26] << 16));
+          const height = 1 + (buffer[27] | (buffer[28] << 8) | (buffer[29] << 16));
+          return { width, height };
+        }
       }
     }
   } catch {
-    // Dimension parsing is best-effort
+    // Dimension parsing is best-effort only.
   }
   return null;
 }
 
+/**
+ * Check whether `absPath` is allowed given a project `cwd` and an optional
+ * allowlist of absolute directories. Returns `null` on success, or an object
+ * `{ kind, message }` describing the failure. The `kind` field lets callers
+ * tailor the error text (see prev-3 P2: distinguish "absolute path outside
+ * project" from "relative path containing ..").
+ */
+function checkPathAllowed(absPath, cwd, allowlist) {
+  // Reject if the resolved path lives inside the project (good).
+  const relToCwd = relative(cwd, absPath);
+  const insideCwd = relToCwd && !relToCwd.startsWith('..') && !isAbsolute(relToCwd);
+  if (insideCwd) return null;
+
+  // Otherwise must match an allowlist entry.
+  if (Array.isArray(allowlist) && allowlist.length > 0) {
+    for (const dir of allowlist) {
+      if (typeof dir !== 'string' || !isAbsolute(dir)) continue;
+      const rel = relative(dir, absPath);
+      if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return null;
+    }
+  }
+
+  return {
+    kind: 'path_outside',
+    message:
+      'Path is outside the project directory and not on the image allowlist. ' +
+      'Either move the file into the project, or ask the user to add its parent ' +
+      'directory to ctx.imageAllowlist (set via ~/.yeaft/config.json imageAllowlist[]).',
+  };
+}
+
+function formatBytes(n) {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+  return `${(n / 1024 / 1024).toFixed(1)}MB`;
+}
+
 export default defineTool({
   name: 'ViewImage',
-  description: `View an image file and get its metadata.
+  description: `Load a local image file and attach it to the conversation so the LLM can see it.
+
+Returns a base64 data URI (\`image\` field) plus metadata (format, dimensions,
+size). The caller/bridge is responsible for turning the data URI into the
+provider-specific image content block.
+
+When to call:
+  - User references a local image path (screenshot, design, log/chart) and
+    asks you to read, analyse, or describe it.
+  - User says "look at this file" / "check the screenshot at ..." / "what's
+    in docs/assets/arch.png?".
+
+When NOT to call:
+  - The image is already attached to the current message (the host has
+    already uploaded it — you can see it without this tool).
+  - The image is a remote URL (http/https). ViewImage only reads local
+    files; use a fetch-style tool for URLs.
+  - You only need the file's existence / mtime / size — use Read or a
+    filesystem tool instead; ViewImage loads the full bytes into memory.
 
-Returns image format, dimensions, and file size.
-Supports PNG, JPEG, GIF, BMP, WebP, SVG, and ICO.`,
+Path examples:
+  - Relative (resolved against project cwd): "./screenshots/bug.png",
+    "docs/assets/arch.png"
+  - Absolute inside an allowlisted dir: "/home/user/Downloads/error.png"
+    (only works when the host added that dir to ctx.imageAllowlist)
+
+Supported formats: PNG, JPEG (.jpg/.jpeg/.jfif), GIF, WebP.
+Max size: 20 MiB by default (configurable via ctx.maxImageBytes).
+Path must live under the project directory or an explicit host allowlist.`,
   parameters: {
     type: 'object',
     properties: {
       file_path: {
         type: 'string',
-        description: 'Path to the image file',
+        description: 'Path to the image file. Relative paths are resolved against the project cwd.',
       },
     },
     required: ['file_path'],
@@ -66,51 +190,126 @@ Supports PNG, JPEG, GIF, BMP, WebP, SVG, and ICO.`,
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   async execute(input, ctx) {
-    const { file_path } = input;
-    if (!file_path) return JSON.stringify({ error: 'file_path is required' });
+    const { file_path } = input || {};
+    if (!file_path || typeof file_path !== 'string') {
+      return JSON.stringify({ error: 'file_path is required and must be a string' });
+    }
+
+    // Reject `..` segments explicitly before path resolution — catches the
+    // cases where resolve() might still land inside cwd by accident. This
+    // also gives LLMs a self-correcting error ("don't use ../") distinct
+    // from the "path outside project" message for absolute paths.
+    if (file_path.split(/[/\\]/).some(seg => seg === '..')) {
+      return JSON.stringify({
+        error:
+          'file_path must not contain `..` segments. Use a path relative to the ' +
+          'project (e.g. "docs/assets/foo.png") or an absolute path under an ' +
+          'allowlisted directory.',
+      });
+    }
 
     const cwd = ctx?.cwd || process.cwd();
+    const allowlist = Array.isArray(ctx?.imageAllowlist) ? ctx.imageAllowlist : [];
+    // Size cap: ctx.maxImageBytes (host-injected from config.json) wins,
+    // falling back to 20 MiB. A non-finite / non-positive override is ignored.
+    const maxBytes =
+      Number.isFinite(ctx?.maxImageBytes) && ctx.maxImageBytes > 0
+        ? Math.floor(ctx.maxImageBytes)
+        : DEFAULT_MAX_IMAGE_BYTES;
     const absPath = resolve(cwd, file_path);
 
-    if (!existsSync(absPath)) {
-      return JSON.stringify({ error: `Image not found: ${absPath}` });
+    const pathErr = checkPathAllowed(absPath, cwd, allowlist);
+    if (pathErr) {
+      // prev-3 P2: split "absolute outside project" from "relative ..".
+      // The `..` case is already handled above, so anything reaching here
+      // is either an absolute path outside cwd/allowlist or a relative
+      // path that resolve() pushed outside cwd (rare). Either way, the
+      // host-level fix is the same, so we keep one nudge message.
+      const isAbs = isAbsolute(file_path);
+      const hint = isAbs
+        ? 'Absolute path is outside the project directory. '
+        : 'Resolved path is outside the project directory. ';
+      return JSON.stringify({
+        error: hint + pathErr.message,
+        path: absPath,
+      });
     }
 
     const ext = extname(absPath).toLowerCase();
-    if (!IMAGE_EXTS.has(ext)) {
-      return JSON.stringify({ error: `Not a recognized image format: ${ext}` });
+    // HEIC special-case: iPhone screenshots default to HEIC and silently
+    // fail today. Give users a concrete one-liner to fix it instead of a
+    // generic "Unsupported format".
+    if (ext === '.heic' || ext === '.heif') {
+      return JSON.stringify({
+        error:
+          'HEIC images need to be converted to JPEG first. ' +
+          'Use `sips -s format jpeg <file> --out <file>.jpg` on macOS ' +
+          '(or an equivalent tool like ImageMagick on Linux/Windows), then retry.',
+        format: ext.slice(1).toUpperCase(),
+        supported: ALLOWED_EXTS,
+      });
+    }
+    if (!(ext in EXT_TO_MIME)) {
+      return JSON.stringify({
+        error: `Unsupported image format: ${ext || '(none)'}`,
+        supported: ALLOWED_EXTS,
+      });
     }
 
+    if (!existsSync(absPath)) {
+      return JSON.stringify({ error: `Image not found: ${absPath}` });
+    }
+
+    let fileStat;
     try {
-      const fileStat = await stat(absPath);
-      const buffer = await readFile(absPath);
+      fileStat = await stat(absPath);
+    } catch (err) {
+      return JSON.stringify({ error: `Failed to stat image: ${err.message}` });
+    }
 
-      const dimensions = parseImageDimensions(buffer, ext);
+    if (!fileStat.isFile()) {
+      return JSON.stringify({ error: 'file_path does not point to a regular file' });
+    }
 
-      const result = {
-        path: absPath,
-        format: ext.slice(1).toUpperCase(),
+    if (fileStat.size > maxBytes) {
+      return JSON.stringify({
+        error:
+          `Image exceeds ${formatBytes(maxBytes)} (${formatBytes(fileStat.size)} actual). ` +
+          `Reduce image size (resize/crop), or set \`maxImageBytes\` in ` +
+          `~/.yeaft/config.json if your LLM supports more.`,
         size: fileStat.size,
-        sizeFormatted: fileStat.size < 1024 ? `${fileStat.size}B`
-          : fileStat.size < 1024 * 1024 ? `${(fileStat.size / 1024).toFixed(1)}KB`
-          : `${(fileStat.size / 1024 / 1024).toFixed(1)}MB`,
-        modified: fileStat.mtime.toISOString(),
-      };
-
-      if (dimensions) {
-        result.width = dimensions.width;
-        result.height = dimensions.height;
-      }
-
-      // For SVG, include a text preview
-      if (ext === '.svg') {
-        const svgText = buffer.toString('utf-8');
-        result.preview = svgText.slice(0, 500);
-      }
+        maxSize: maxBytes,
+      });
+    }
 
-      return JSON.stringify(result, null, 2);
+    let buffer;
+    try {
+      buffer = await readFile(absPath);
     } catch (err) {
       return JSON.stringify({ error: `Failed to read image: ${err.message}` });
     }
+
+    const mediaType = EXT_TO_MIME[ext];
+    const base64 = buffer.toString('base64');
+    const dataUri = `data:${mediaType};base64,${base64}`;
+    const dimensions = parseImageDimensions(buffer, ext);
+
+    const result = {
+      path: absPath,
+      format: ext.slice(1).toUpperCase() === 'JPG' ? 'JPEG' : ext.slice(1).toUpperCase(),
+      media_type: mediaType,
+      size: fileStat.size,
+      sizeFormatted: formatBytes(fileStat.size),
+      modified: fileStat.mtime.toISOString(),
+      image: dataUri,
+    };
+    // Normalise .jfif to JPEG in display format too, for consistency.
+    if (ext === '.jfif') result.format = 'JPEG';
+    if (dimensions) {
+      result.width = dimensions.width;
+      result.height = dimensions.height;
+    }
+
+    return JSON.stringify(result, null, 2);
   },
 });

package/unify/tools/tool-search.js

@@ -1,88 +0,0 @@
-/**
- * tool-search.js — Search available tools by name or description.
- *
- * task-311: chat/work mode was removed in task-297; this tool no longer
- * accepts or reports a `modes` filter. Results come back as plain
- * { name, description } pairs.
- */
-
-import { defineTool } from './types.js';
-
-export default defineTool({
-  name: 'ToolSearch',
-  description: `Search available tools by name or description keyword.
-
-Use when you're unsure which tool to use for a task.
-Returns matching tools with their descriptions.`,
-  parameters: {
-    type: 'object',
-    properties: {
-      query: {
-        type: 'string',
-        description: 'Search keyword to match against tool names and descriptions',
-      },
-    },
-    required: ['query'],
-  },
-  isConcurrencySafe: () => true,
-  isReadOnly: () => true,
-  async execute(input, _ctx) {
-    const { query } = input;
-    if (!query) return JSON.stringify({ error: 'query is required' });
-
-    const lowerQuery = query.toLowerCase();
-
-    // Self-referential catalogue of tools available to the engine.
-    const toolList = [
-      { name: 'AskUser', description: 'Ask the user a question' },
-      { name: 'MemoryRead', description: 'Read from memory system' },
-      { name: 'MemoryWrite', description: 'Write to memory system' },
-      { name: 'MemorySearch', description: 'Search memory entries' },
-      { name: 'WebSearch', description: 'Search the web' },
-      { name: 'WebFetch', description: 'Fetch web page content' },
-      { name: 'HistorySearch', description: 'Search conversation history' },
-      { name: 'Bash', description: 'Execute shell commands' },
-      { name: 'FileRead', description: 'Read file with line numbers' },
-      { name: 'FileWrite', description: 'Write/create files' },
-      { name: 'FileEdit', description: 'Surgical string replacement in files' },
-      { name: 'Glob', description: 'Find files by pattern' },
-      { name: 'Grep', description: 'Search file contents' },
-      { name: 'ListDir', description: 'List directory contents' },
-      { name: 'ApplyPatch', description: 'Apply unified diff patches' },
-      { name: 'Agent', description: 'Create sub-agents' },
-      { name: 'SendMessage', description: 'Send message to sub-agent' },
-      { name: 'WaitAgent', description: 'Wait for sub-agent result' },
-      { name: 'CloseAgent', description: 'Close a sub-agent' },
-      { name: 'ListAgents', description: 'List all sub-agents' },
-      { name: 'TaskCreate', description: 'Create a task' },
-      { name: 'TaskUpdate', description: 'Update task status' },
-      { name: 'TaskList', description: 'List all tasks' },
-      { name: 'TaskGet', description: 'Get task details' },
-      { name: 'FollowupTask', description: 'Create follow-up task' },
-      { name: 'UpdatePlan', description: 'View/update execution plan' },
-      { name: 'JsRepl', description: 'JavaScript REPL evaluation' },
-      { name: 'JsReplReset', description: 'Reset REPL state' },
-      { name: 'NotebookEdit', description: 'Edit Jupyter notebooks' },
-      { name: 'ImageGeneration', description: 'Generate images from text' },
-      { name: 'ViewImage', description: 'View image metadata' },
-      { name: 'RequestPermissions', description: 'Request dangerous operation permissions' },
-      { name: 'WriteStdin', description: 'Write to running process stdin' },
-      { name: 'Skill', description: 'Load skills from library' },
-      { name: 'EnterWorktree', description: 'Create git worktree' },
-      { name: 'ExitWorktree', description: 'Exit git worktree' },
-      { name: 'mcp_list_tools', description: 'List MCP server tools' },
-      { name: 'mcp_call_tool', description: 'Call MCP server tool' },
-    ];
-
-    const results = toolList.filter(t =>
-      t.name.toLowerCase().includes(lowerQuery) ||
-      t.description.toLowerCase().includes(lowerQuery)
-    );
-
-    return JSON.stringify({
-      results,
-      totalResults: results.length,
-      query,
-    }, null, 2);
-  },
-});

package/unify/tools/write-stdin.js

@@ -1,53 +0,0 @@
-/**
- * write-stdin.js — Write data to a running process's stdin.
- *
- * Used in conjunction with Bash for processes that need interactive input.
- * Currently returns a guidance message since Bash tool uses 'ignore' for stdin.
- */
-
-import { defineTool } from './types.js';
-
-export default defineTool({
-  name: 'WriteStdin',
-  description: `Write data to a running process's standard input.
-
-This tool is intended for sending input to interactive processes.
-Since the Bash tool runs commands non-interactively, this is primarily
-useful with the terminal system or long-running processes.
-
-Note: For most use cases, pipe input via Bash: echo "input" | command`,
-  parameters: {
-    type: 'object',
-    properties: {
-      process_id: {
-        type: 'string',
-        description: 'Process identifier or terminal ID',
-      },
-      data: {
-        type: 'string',
-        description: 'Data to write to stdin',
-      },
-      newline: {
-        type: 'boolean',
-        description: 'Append newline after data (default: true)',
-      },
-    },
-    required: ['data'],
-  },
-  isConcurrencySafe: () => false,
-  isReadOnly: () => false,
-  async execute(input, ctx) {
-    const { process_id, data, newline = true } = input;
-    if (!data && data !== '') return JSON.stringify({ error: 'data is required' });
-
-    // The Bash tool uses 'ignore' for stdin, so direct stdin writing
-    // is only possible through the terminal system.
-    // For most interactive needs, recommend using pipe syntax.
-    return JSON.stringify({
-      hint: 'The Bash tool does not support interactive stdin. Use pipe syntax instead:',
-      example: `echo "${data}" | your_command`,
-      alternativeBash: `printf '%s\\n' '${data.replace(/'/g, "'\\''")}' | your_command`,
-      message: 'For interactive processes, use the terminal system (not the AI tool system).',
-    });
-  },
-});