@yeaft/webchat-agent 0.1.511 → 0.1.513

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).',
-    });
-  },
-});