@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/web/media.js

@@ -2,11 +2,71 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { logVerbose, shouldLogVerbose } from "../globals.js";
+import { SafeOpenError, readLocalFileSafely } from "../infra/fs-safe.js";
 import { maxBytesForKind, mediaKindFromMime } from "../media/constants.js";
-import { resolveUserPath } from "../utils.js";
 import { fetchRemoteMedia } from "../media/fetch.js";
 import { convertHeicToJpeg, hasAlphaChannel, optimizeImageToPng, resizeToJpeg, } from "../media/image-ops.js";
+import { getDefaultMediaLocalRoots } from "../media/local-roots.js";
 import { detectMime, extensionForMime } from "../media/mime.js";
+import { resolveUserPath } from "../utils.js";
+export class LocalMediaAccessError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "LocalMediaAccessError";
+    }
+}
+export function getDefaultLocalRoots() {
+    return getDefaultMediaLocalRoots();
+}
+async function assertLocalMediaAllowed(mediaPath, localRoots) {
+    if (localRoots === "any") {
+        return;
+    }
+    const roots = localRoots ?? getDefaultLocalRoots();
+    // Resolve symlinks so a symlink under /tmp pointing to /etc/passwd is caught.
+    let resolved;
+    try {
+        resolved = await fs.realpath(mediaPath);
+    }
+    catch {
+        resolved = path.resolve(mediaPath);
+    }
+    // Hardening: the default allowlist includes the Pool Bot temp dir, and tests/CI may
+    // override the state dir into tmp. Avoid accidentally allowing per-agent
+    // `workspace-*` state roots via the temp-root prefix match; require explicit
+    // localRoots for those.
+    if (localRoots === undefined) {
+        const workspaceRoot = roots.find((root) => path.basename(root) === "workspace");
+        if (workspaceRoot) {
+            const stateDir = path.dirname(workspaceRoot);
+            const rel = path.relative(stateDir, resolved);
+            if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+                const firstSegment = rel.split(path.sep)[0] ?? "";
+                if (firstSegment.startsWith("workspace-")) {
+                    throw new LocalMediaAccessError("path-not-allowed", `Local media path is not under an allowed directory: ${mediaPath}`);
+                }
+            }
+        }
+    }
+    for (const root of roots) {
+        let resolvedRoot;
+        try {
+            resolvedRoot = await fs.realpath(root);
+        }
+        catch {
+            resolvedRoot = path.resolve(root);
+        }
+        if (resolvedRoot === path.parse(resolvedRoot).root) {
+            throw new LocalMediaAccessError("invalid-root", `Invalid localRoots entry (refuses filesystem root): ${root}. Pass a narrower directory.`);
+        }
+        if (resolved === resolvedRoot || resolved.startsWith(resolvedRoot + path.sep)) {
+            return;
+        }
+    }
+    throw new LocalMediaAccessError("path-not-allowed", `Local media path is not under an allowed directory: ${mediaPath}`);
+}
 const HEIC_MIME_RE = /^image\/hei[cf]$/i;
 const HEIC_EXT_RE = /\.(heic|heif)$/i;
 const MB = 1024 * 1024;
@@ -20,18 +80,22 @@ function formatCapReduce(label, cap, size) {
     return `${label} could not be reduced below ${formatMb(cap, 0)}MB (got ${formatMb(size)}MB)`;
 }
 function isHeicSource(opts) {
-    if (opts.contentType && HEIC_MIME_RE.test(opts.contentType.trim()))
+    if (opts.contentType && HEIC_MIME_RE.test(opts.contentType.trim())) {
         return true;
-    if (opts.fileName && HEIC_EXT_RE.test(opts.fileName.trim()))
+    }
+    if (opts.fileName && HEIC_EXT_RE.test(opts.fileName.trim())) {
         return true;
+    }
     return false;
 }
 function toJpegFileName(fileName) {
-    if (!fileName)
+    if (!fileName) {
         return undefined;
+    }
     const trimmed = fileName.trim();
-    if (!trimmed)
+    if (!trimmed) {
         return fileName;
+    }
     const parsed = path.parse(trimmed);
     if (!parsed.ext || HEIC_EXT_RE.test(parsed.ext)) {
         return path.format({ dir: parsed.dir, name: parsed.name || trimmed, ext: ".jpg" });
@@ -39,10 +103,12 @@ function toJpegFileName(fileName) {
     return path.format({ dir: parsed.dir, name: parsed.name, ext: ".jpg" });
 }
 function logOptimizedImage(params) {
-    if (!shouldLogVerbose())
+    if (!shouldLogVerbose()) {
         return;
-    if (params.optimized.optimizedSize >= params.originalSize)
+    }
+    if (params.optimized.optimizedSize >= params.originalSize) {
         return;
+    }
     if (params.optimized.format === "png") {
         logVerbose(`Optimized PNG (preserving alpha) from ${formatMb(params.originalSize)}MB to ${formatMb(params.optimized.optimizedSize)}MB (side≤${params.optimized.resizeSide}px)`);
         return;
@@ -66,14 +132,17 @@ async function optimizeImageWithFallback(params) {
     return { ...optimized, format: "jpeg" };
 }
 async function loadWebMediaInternal(mediaUrl, options = {}) {
-    const { maxBytes, optimizeImages = true } = options;
+    const { maxBytes, optimizeImages = true, ssrfPolicy, localRoots, sandboxValidated = false, readFile: readFileOverride, } = options;
+    // Strip MEDIA: prefix used by agent tools (e.g. TTS) to tag media paths.
+    // Be lenient: LLM output may add extra whitespace (e.g. "  MEDIA :  /tmp/x.png").
+    mediaUrl = mediaUrl.replace(/^\s*MEDIA\s*:\s*/i, "");
     // Use fileURLToPath for proper handling of file:// URLs (handles file://localhost/path, etc.)
     if (mediaUrl.startsWith("file://")) {
         try {
             mediaUrl = fileURLToPath(mediaUrl);
         }
         catch {
-            throw new Error(`Invalid file:// URL: ${mediaUrl}`);
+            throw new LocalMediaAccessError("invalid-file-url", `Invalid file:// URL: ${mediaUrl}`);
         }
     }
     const optimizeAndClampImage = async (buffer, cap, meta) => {
@@ -129,7 +198,15 @@ async function loadWebMediaInternal(mediaUrl, options = {}) {
         };
     };
     if (/^https?:\/\//i.test(mediaUrl)) {
-        const fetched = await fetchRemoteMedia({ url: mediaUrl });
+        // Enforce a download cap during fetch to avoid unbounded memory usage.
+        // For optimized images, allow fetching larger payloads before compression.
+        const defaultFetchCap = maxBytesForKind("unknown");
+        const fetchCap = maxBytes === undefined
+            ? defaultFetchCap
+            : optimizeImages
+                ? Math.max(maxBytes, defaultFetchCap)
+                : maxBytes;
+        const fetched = await fetchRemoteMedia({ url: mediaUrl, maxBytes: fetchCap, ssrfPolicy });
         const { buffer, contentType, fileName } = fetched;
         const kind = mediaKindFromMime(contentType);
         return await clampAndFinalize({ buffer, contentType, kind, fileName });
@@ -138,15 +215,45 @@ async function loadWebMediaInternal(mediaUrl, options = {}) {
     if (mediaUrl.startsWith("~")) {
         mediaUrl = resolveUserPath(mediaUrl);
     }
+    if ((sandboxValidated || localRoots === "any") && !readFileOverride) {
+        throw new LocalMediaAccessError("unsafe-bypass", "Refusing localRoots bypass without readFile override. Use sandboxValidated with readFile, or pass explicit localRoots.");
+    }
+    // Guard local reads against allowed directory roots to prevent file exfiltration.
+    if (!(sandboxValidated || localRoots === "any")) {
+        await assertLocalMediaAllowed(mediaUrl, localRoots);
+    }
     // Local path
-    const data = await fs.readFile(mediaUrl);
+    let data;
+    if (readFileOverride) {
+        data = await readFileOverride(mediaUrl);
+    }
+    else {
+        try {
+            data = (await readLocalFileSafely({ filePath: mediaUrl })).buffer;
+        }
+        catch (err) {
+            if (err instanceof SafeOpenError) {
+                if (err.code === "not-found") {
+                    throw new LocalMediaAccessError("not-found", `Local media file not found: ${mediaUrl}`, {
+                        cause: err,
+                    });
+                }
+                if (err.code === "not-file") {
+                    throw new LocalMediaAccessError("not-file", `Local media path is not a file: ${mediaUrl}`, { cause: err });
+                }
+                throw new LocalMediaAccessError("invalid-path", `Local media path is not safe to read: ${mediaUrl}`, { cause: err });
+            }
+            throw err;
+        }
+    }
     const mime = await detectMime({ buffer: data, filePath: mediaUrl });
     const kind = mediaKindFromMime(mime);
     let fileName = path.basename(mediaUrl) || undefined;
     if (fileName && !path.extname(fileName) && mime) {
         const ext = extensionForMime(mime);
-        if (ext)
+        if (ext) {
             fileName = `${fileName}${ext}`;
+        }
     }
     return await clampAndFinalize({
         buffer: data,
@@ -155,11 +262,13 @@ async function loadWebMediaInternal(mediaUrl, options = {}) {
         fileName,
     });
 }
-export async function loadWebMedia(mediaUrl, maxBytesOrOptions) {
+export async function loadWebMedia(mediaUrl, maxBytesOrOptions, options) {
     if (typeof maxBytesOrOptions === "number" || maxBytesOrOptions === undefined) {
         return await loadWebMediaInternal(mediaUrl, {
             maxBytes: maxBytesOrOptions,
             optimizeImages: true,
+            ssrfPolicy: options?.ssrfPolicy,
+            localRoots: options?.localRoots,
         });
     }
     return await loadWebMediaInternal(mediaUrl, {
@@ -167,11 +276,13 @@ export async function loadWebMedia(mediaUrl, maxBytesOrOptions) {
         optimizeImages: maxBytesOrOptions.optimizeImages ?? true,
     });
 }
-export async function loadWebMediaRaw(mediaUrl, maxBytesOrOptions) {
+export async function loadWebMediaRaw(mediaUrl, maxBytesOrOptions, options) {
     if (typeof maxBytesOrOptions === "number" || maxBytesOrOptions === undefined) {
         return await loadWebMediaInternal(mediaUrl, {
             maxBytes: maxBytesOrOptions,
             optimizeImages: false,
+            ssrfPolicy: options?.ssrfPolicy,
+            localRoots: options?.localRoots,
         });
     }
     return await loadWebMediaInternal(mediaUrl, {
@@ -187,7 +298,7 @@ export async function optimizeImageToJpeg(buffer, maxBytes, opts = {}) {
             source = await convertHeicToJpeg(buffer);
         }
         catch (err) {
-            throw new Error(`HEIC image conversion failed: ${String(err)}`);
+            throw new Error(`HEIC image conversion failed: ${String(err)}`, { cause: err });
         }
     }
     const sides = [2048, 1536, 1280, 1024, 800];

package/docs/tools/slash-commands.md

@@ -3,6 +3,7 @@ summary: "Slash commands: text vs native, config, and supported commands"
 read_when:
   - Using or configuring chat commands
   - Debugging command routing or permissions
+title: "Slash Commands"
 ---
 # Slash commands
 
@@ -65,8 +66,11 @@ Text + native (when enabled):
 - `/allowlist` (list/add/remove allowlist entries)
 - `/approve <id> allow-once|allow-always|deny` (resolve exec approval prompts)
 - `/context [list|detail|json]` (explain “context”; `detail` shows per-file + per-tool + per-skill + system prompt size)
+- `/export-session [path]` (export the current session; alias: `/export`)
 - `/whoami` (show your sender id; alias: `/id`)
-- `/subagents list|stop|log|info|send` (inspect, stop, log, or message sub-agent runs for the current session)
+- `/subagents list|kill|log|info|send|steer|spawn` (inspect, kill, log, or message sub-agent runs for the current session)
+- `/kill <id|#|all>` (kill a sub-agent run)
+- `/steer <id|#> <message>` (redirect a sub-agent; alias: `/tell`)
 - `/config show|get|set|unset` (persist config to disk, owner-only; requires `commands.config: true`)
 - `/debug show|set|unset|reset` (runtime overrides, owner-only; requires `commands.debug: true`)
 - `/usage off|tokens|full|cost` (per-response usage footer or local cost summary)