@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/dist/agents/tool-display-common.js

@@ -688,7 +688,7 @@ function summarizeKnownExec(words) {
     }
     if (bin === "poolbot") {
         const sub = firstPositional(words, 1);
-        return sub ? `run openclaw ${sub}` : "run openclaw";
+        return sub ? `run poolbot ${sub}` : "run poolbot";
     }
     const arg = firstPositional(words, 1);
     if (!arg || arg.length > 48) {

package/dist/agents/tool-images.js

@@ -1,38 +1,54 @@
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { getImageMetadata, resizeToJpeg } from "../media/image-ops.js";
-// Anthropic Messages API limitations (observed in Poolbot sessions):
+import { DEFAULT_IMAGE_MAX_BYTES, DEFAULT_IMAGE_MAX_DIMENSION_PX, } from "./image-sanitization.js";
+// Anthropic Messages API limitations (observed in Pool Bot sessions):
 // - Images over ~2000px per side can fail in multi-image requests.
 // - Images over 5MB are rejected by the API.
 //
 // To keep sessions resilient (and avoid "silent" WhatsApp non-replies), we auto-downscale
 // and recompress base64 image blocks when they exceed these limits.
-const MAX_IMAGE_DIMENSION_PX = 2000;
-const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const MAX_IMAGE_DIMENSION_PX = DEFAULT_IMAGE_MAX_DIMENSION_PX;
+const MAX_IMAGE_BYTES = DEFAULT_IMAGE_MAX_BYTES;
 const log = createSubsystemLogger("agents/tool-images");
 function isImageBlock(block) {
-    if (!block || typeof block !== "object")
+    if (!block || typeof block !== "object") {
         return false;
+    }
     const rec = block;
     return rec.type === "image" && typeof rec.data === "string" && typeof rec.mimeType === "string";
 }
 function isTextBlock(block) {
-    if (!block || typeof block !== "object")
+    if (!block || typeof block !== "object") {
         return false;
+    }
     const rec = block;
     return rec.type === "text" && typeof rec.text === "string";
 }
 function inferMimeTypeFromBase64(base64) {
     const trimmed = base64.trim();
-    if (!trimmed)
+    if (!trimmed) {
         return undefined;
-    if (trimmed.startsWith("/9j/"))
+    }
+    if (trimmed.startsWith("/9j/")) {
         return "image/jpeg";
-    if (trimmed.startsWith("iVBOR"))
+    }
+    if (trimmed.startsWith("iVBOR")) {
         return "image/png";
-    if (trimmed.startsWith("R0lGOD"))
+    }
+    if (trimmed.startsWith("R0lGOD")) {
         return "image/gif";
+    }
     return undefined;
 }
+function formatBytesShort(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 1024) {
+        return `${Math.max(0, Math.round(bytes))}B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    }
+    return `${(bytes / (1024 * 1024)).toFixed(2)}MB`;
+}
 async function resizeImageBase64IfNeeded(params) {
     const buf = Buffer.from(params.base64, "base64");
     const meta = await getImageMetadata(buf);
@@ -40,6 +56,7 @@ async function resizeImageBase64IfNeeded(params) {
     const height = meta?.height;
     const overBytes = buf.byteLength > params.maxBytes;
     const hasDimensions = typeof width === "number" && typeof height === "number";
+    const overDimensions = hasDimensions && (width > params.maxDimensionPx || height > params.maxDimensionPx);
     if (hasDimensions &&
         !overBytes &&
         width <= params.maxDimensionPx &&
@@ -52,23 +69,13 @@ async function resizeImageBase64IfNeeded(params) {
             height,
         };
     }
-    if (hasDimensions &&
-        (width > params.maxDimensionPx || height > params.maxDimensionPx || overBytes)) {
-        log.warn("Image exceeds limits; resizing", {
-            label: params.label,
-            width,
-            height,
-            maxDimensionPx: params.maxDimensionPx,
-            maxBytes: params.maxBytes,
-        });
-    }
     const qualities = [85, 75, 65, 55, 45, 35];
     const maxDim = hasDimensions ? Math.max(width ?? 0, height ?? 0) : params.maxDimensionPx;
     const sideStart = maxDim > 0 ? Math.min(params.maxDimensionPx, maxDim) : params.maxDimensionPx;
     const sideGrid = [sideStart, 1800, 1600, 1400, 1200, 1000, 800]
-        .map((v) => Math.min(params.maxDimensionPx, v))
+        .filter((v) => v > 0 && v <= params.maxDimensionPx)
         .filter((v, i, arr) => v > 0 && arr.indexOf(v) === i)
-        .sort((a, b) => b - a);
+        .toSorted((a, b) => b - a);
     let smallest = null;
     for (const side of sideGrid) {
         for (const quality of qualities) {
@@ -82,16 +89,27 @@ async function resizeImageBase64IfNeeded(params) {
                 smallest = { buffer: out, size: out.byteLength };
             }
             if (out.byteLength <= params.maxBytes) {
-                log.info("Image resized", {
+                const sourcePixels = typeof width === "number" && typeof height === "number"
+                    ? `${width}x${height}px`
+                    : "unknown";
+                const byteReductionPct = buf.byteLength > 0
+                    ? Number((((buf.byteLength - out.byteLength) / buf.byteLength) * 100).toFixed(1))
+                    : 0;
+                log.info(`Image resized to fit limits: ${sourcePixels} ${formatBytesShort(buf.byteLength)} -> ${formatBytesShort(out.byteLength)} (-${byteReductionPct}%)`, {
                     label: params.label,
-                    width,
-                    height,
-                    maxDimensionPx: params.maxDimensionPx,
+                    sourceMimeType: params.mimeType,
+                    sourceWidth: width,
+                    sourceHeight: height,
+                    sourceBytes: buf.byteLength,
                     maxBytes: params.maxBytes,
-                    originalBytes: buf.byteLength,
-                    resizedBytes: out.byteLength,
-                    quality,
-                    side,
+                    maxDimensionPx: params.maxDimensionPx,
+                    triggerOverBytes: overBytes,
+                    triggerOverDimensions: overDimensions,
+                    outputMimeType: "image/jpeg",
+                    outputBytes: out.byteLength,
+                    outputQuality: quality,
+                    outputMaxSide: side,
+                    byteReductionPct,
                 });
                 return {
                     base64: out.toString("base64"),
@@ -106,6 +124,19 @@ async function resizeImageBase64IfNeeded(params) {
     const best = smallest?.buffer ?? buf;
     const maxMb = (params.maxBytes / (1024 * 1024)).toFixed(0);
     const gotMb = (best.byteLength / (1024 * 1024)).toFixed(2);
+    const sourcePixels = typeof width === "number" && typeof height === "number" ? `${width}x${height}px` : "unknown";
+    log.warn(`Image resize failed to fit limits: ${sourcePixels} best=${formatBytesShort(best.byteLength)} limit=${formatBytesShort(params.maxBytes)}`, {
+        label: params.label,
+        sourceMimeType: params.mimeType,
+        sourceWidth: width,
+        sourceHeight: height,
+        sourceBytes: buf.byteLength,
+        maxDimensionPx: params.maxDimensionPx,
+        maxBytes: params.maxBytes,
+        smallestCandidateBytes: best.byteLength,
+        triggerOverBytes: overBytes,
+        triggerOverDimensions: overDimensions,
+    });
     throw new Error(`Image could not be reduced below ${maxMb}MB (got ${gotMb}MB)`);
 }
 export async function sanitizeContentBlocksImages(blocks, label, opts = {}) {
@@ -151,16 +182,18 @@ export async function sanitizeContentBlocksImages(blocks, label, opts = {}) {
     return out;
 }
 export async function sanitizeImageBlocks(images, label, opts = {}) {
-    if (images.length === 0)
+    if (images.length === 0) {
         return { images, dropped: 0 };
+    }
     const sanitized = await sanitizeContentBlocksImages(images, label, opts);
     const next = sanitized.filter(isImageBlock);
     return { images: next, dropped: Math.max(0, images.length - next.length) };
 }
 export async function sanitizeToolResultImages(result, label, opts = {}) {
     const content = Array.isArray(result.content) ? result.content : [];
-    if (!content.some((b) => isImageBlock(b) || isTextBlock(b)))
+    if (!content.some((b) => isImageBlock(b) || isTextBlock(b))) {
         return result;
+    }
     const next = await sanitizeContentBlocksImages(content, label, opts);
     return { ...result, content: next };
 }

package/dist/agents/tools/canvas-tool.js

@@ -4,9 +4,10 @@ import { Type } from "@sinclair/typebox";
 import { writeBase64ToFile } from "../../cli/nodes-camera.js";
 import { canvasSnapshotTempPath, parseCanvasSnapshotPayload } from "../../cli/nodes-canvas.js";
 import { imageMimeFromFormat } from "../../media/mime.js";
+import { resolveImageSanitizationLimits } from "../image-sanitization.js";
 import { optionalStringEnum, stringEnum } from "../schema/typebox.js";
 import { imageResult, jsonResult, readStringParam } from "./common.js";
-import { callGatewayTool } from "./gateway.js";
+import { callGatewayTool, readGatewayCallOptions } from "./gateway.js";
 import { resolveNodeId } from "./nodes-utils.js";
 const CANVAS_ACTIONS = [
     "present",
@@ -44,7 +45,8 @@ const CanvasToolSchema = Type.Object({
     jsonl: Type.Optional(Type.String()),
     jsonlPath: Type.Optional(Type.String()),
 });
-export function createCanvasTool() {
+export function createCanvasTool(options) {
+    const imageSanitization = resolveImageSanitizationLimits(options?.config);
     return {
         label: "Canvas",
         name: "canvas",
@@ -53,11 +55,7 @@ export function createCanvasTool() {
         execute: async (_toolCallId, args) => {
             const params = args;
             const action = readStringParam(params, "action", { required: true });
-            const gatewayOpts = {
-                gatewayUrl: readStringParam(params, "gatewayUrl", { trim: false }),
-                gatewayToken: readStringParam(params, "gatewayToken", { trim: false }),
-                timeoutMs: typeof params.timeoutMs === "number" ? params.timeoutMs : undefined,
-            };
+            const gatewayOpts = readGatewayCallOptions(params);
             const nodeId = await resolveNodeId(gatewayOpts, readStringParam(params, "node", { trim: true }), true);
             const invoke = async (command, invokeParams) => await callGatewayTool("node.invoke", gatewayOpts, {
                 nodeId,
@@ -74,8 +72,12 @@ export function createCanvasTool() {
                         height: typeof params.height === "number" ? params.height : undefined,
                     };
                     const invokeParams = {};
-                    if (typeof params.target === "string" && params.target.trim()) {
-                        invokeParams.url = params.target.trim();
+                    // Accept both `target` and `url` for present to match common caller expectations.
+                    // `target` remains the canonical field for CLI compatibility.
+                    const presentTarget = readStringParam(params, "target", { trim: true }) ??
+                        readStringParam(params, "url", { trim: true });
+                    if (presentTarget) {
+                        invokeParams.url = presentTarget;
                     }
                     if (Number.isFinite(placement.x) ||
                         Number.isFinite(placement.y) ||
@@ -90,7 +92,9 @@ export function createCanvasTool() {
                     await invoke("canvas.hide", undefined);
                     return jsonResult({ ok: true });
                 case "navigate": {
-                    const url = readStringParam(params, "url", { required: true });
+                    // Support `target` as an alias so callers can reuse the same field across present/navigate.
+                    const url = readStringParam(params, "url", { trim: true }) ??
+                        readStringParam(params, "target", { required: true, trim: true, label: "url" });
                     await invoke("canvas.navigate", { url });
                     return jsonResult({ ok: true });
                 }
@@ -134,6 +138,7 @@ export function createCanvasTool() {
                         base64: payload.base64,
                         mimeType,
                         details: { format: payload.format },
+                        imageSanitization,
                     });
                 }
                 case "a2ui_push": {
@@ -142,8 +147,9 @@ export function createCanvasTool() {
                         : typeof params.jsonlPath === "string" && params.jsonlPath.trim()
                             ? await fs.readFile(params.jsonlPath.trim(), "utf8")
                             : "";
-                    if (!jsonl.trim())
+                    if (!jsonl.trim()) {
                         throw new Error("jsonl or jsonlPath required");
+                    }
                     await invoke("canvas.a2ui.pushJSONL", { jsonl });
                     return jsonResult({ ok: true });
                 }

package/dist/agents/tools/common.js

@@ -1,11 +1,19 @@
 import fs from "node:fs/promises";
 import { detectMime } from "../../media/mime.js";
 import { sanitizeToolResultImages } from "../tool-images.js";
+export class ToolInputError extends Error {
+    status = 400;
+    constructor(message) {
+        super(message);
+        this.name = "ToolInputError";
+    }
+}
 export function createActionGate(actions) {
     return (key, defaultValue = true) => {
         const value = actions?.[key];
-        if (value === undefined)
+        if (value === undefined) {
             return defaultValue;
+        }
         return value !== false;
     };
 }
@@ -13,14 +21,16 @@ export function readStringParam(params, key, options = {}) {
     const { required = false, trim = true, label = key, allowEmpty = false } = options;
     const raw = params[key];
     if (typeof raw !== "string") {
-        if (required)
-            throw new Error(`${label} required`);
+        if (required) {
+            throw new ToolInputError(`${label} required`);
+        }
         return undefined;
     }
     const value = trim ? raw.trim() : raw;
     if (!value && !allowEmpty) {
-        if (required)
-            throw new Error(`${label} required`);
+        if (required) {
+            throw new ToolInputError(`${label} required`);
+        }
         return undefined;
     }
     return value;
@@ -33,11 +43,13 @@ export function readStringOrNumberParam(params, key, options = {}) {
     }
     if (typeof raw === "string") {
         const value = raw.trim();
-        if (value)
+        if (value) {
             return value;
+        }
+    }
+    if (required) {
+        throw new ToolInputError(`${label} required`);
     }
-    if (required)
-        throw new Error(`${label} required`);
     return undefined;
 }
 export function readNumberParam(params, key, options = {}) {
@@ -51,13 +63,15 @@ export function readNumberParam(params, key, options = {}) {
         const trimmed = raw.trim();
         if (trimmed) {
             const parsed = Number.parseFloat(trimmed);
-            if (Number.isFinite(parsed))
+            if (Number.isFinite(parsed)) {
                 value = parsed;
+            }
         }
     }
     if (value === undefined) {
-        if (required)
-            throw new Error(`${label} required`);
+        if (required) {
+            throw new ToolInputError(`${label} required`);
+        }
         return undefined;
     }
     return integer ? Math.trunc(value) : value;
@@ -71,8 +85,9 @@ export function readStringArrayParam(params, key, options = {}) {
             .map((entry) => entry.trim())
             .filter(Boolean);
         if (values.length === 0) {
-            if (required)
-                throw new Error(`${label} required`);
+            if (required) {
+                throw new ToolInputError(`${label} required`);
+            }
             return undefined;
         }
         return values;
@@ -80,14 +95,16 @@ export function readStringArrayParam(params, key, options = {}) {
     if (typeof raw === "string") {
         const value = raw.trim();
         if (!value) {
-            if (required)
-                throw new Error(`${label} required`);
+            if (required) {
+                throw new ToolInputError(`${label} required`);
+            }
             return undefined;
         }
         return [value];
     }
-    if (required)
-        throw new Error(`${label} required`);
+    if (required) {
+        throw new ToolInputError(`${label} required`);
+    }
     return undefined;
 }
 export function readReactionParams(params, options) {
@@ -99,7 +116,7 @@ export function readReactionParams(params, options) {
         allowEmpty: true,
     });
     if (remove && !emoji) {
-        throw new Error(options.removeErrorMessage);
+        throw new ToolInputError(options.removeErrorMessage);
     }
     return { emoji, remove, isEmpty: !emoji };
 }
@@ -130,7 +147,7 @@ export async function imageResult(params) {
         content,
         details: { path: params.path, ...params.details },
     };
-    return await sanitizeToolResultImages(result, params.label);
+    return await sanitizeToolResultImages(result, params.label, params.imageSanitization);
 }
 export async function imageResultFromFile(params) {
     const buf = await fs.readFile(params.path);
@@ -142,5 +159,6 @@ export async function imageResultFromFile(params) {
         mimeType,
         extraText: params.extraText,
         details: params.details,
+        imageSanitization: params.imageSanitization,
     });
 }

package/dist/agents/tools/cron-tool.js

@@ -1,7 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import { loadConfig } from "../../config/config.js";
 import { normalizeCronJobCreate, normalizeCronJobPatch } from "../../cron/normalize.js";
+import { normalizeHttpWebhookUrl } from "../../cron/webhook-url.js";
 import { parseAgentSessionKey } from "../../sessions/session-key-utils.js";
+import { extractTextFromChatContent } from "../../shared/chat-content.js";
 import { isRecord, truncateUtf16Safe } from "../../utils.js";
 import { resolveSessionAgentId } from "../agent-scope.js";
 import { optionalStringEnum, stringEnum } from "../schema/typebox.js";
@@ -49,37 +51,13 @@ function truncateText(input, maxLen) {
     const truncated = truncateUtf16Safe(input, Math.max(0, maxLen - 3)).trimEnd();
     return `${truncated}...`;
 }
-function normalizeContextText(raw) {
-    return raw.replace(/\s+/g, " ").trim();
-}
 function extractMessageText(message) {
     const role = typeof message.role === "string" ? message.role : "";
     if (role !== "user" && role !== "assistant") {
         return null;
     }
-    const content = message.content;
-    if (typeof content === "string") {
-        const normalized = normalizeContextText(content);
-        return normalized ? { role, text: normalized } : null;
-    }
-    if (!Array.isArray(content)) {
-        return null;
-    }
-    const chunks = [];
-    for (const block of content) {
-        if (!block || typeof block !== "object") {
-            continue;
-        }
-        if (block.type !== "text") {
-            continue;
-        }
-        const text = block.text;
-        if (typeof text === "string" && text.trim()) {
-            chunks.push(text);
-        }
-    }
-    const joined = normalizeContextText(chunks.join(" "));
-    return joined ? { role, text: joined } : null;
+    const text = extractTextFromChatContent(message.content);
+    return text ? { role, text } : null;
 }
 async function buildReminderContextLines(params) {
     const maxMessages = Math.min(REMINDER_CONTEXT_MESSAGES_MAX, Math.max(0, Math.floor(params.contextMessages)));
@@ -201,7 +179,7 @@ JOB SCHEMA (for add action):
   "name": "string (optional)",
   "schedule": { ... },      // Required: when to run
   "payload": { ... },       // Required: what to execute
-  "delivery": { ... },      // Optional: announce summary (isolated only)
+  "delivery": { ... },      // Optional: announce summary or webhook POST
   "sessionTarget": "main" | "isolated",  // Required
   "enabled": true | false   // Optional, default true
 }
@@ -220,16 +198,19 @@ PAYLOAD TYPES (payload.kind):
 - "systemEvent": Injects text as system event into session
   { "kind": "systemEvent", "text": "<message>" }
 - "agentTurn": Runs agent with message (isolated sessions only)
-  { "kind": "agentTurn", "message": "<prompt>", "model": "<optional>", "thinking": "<optional>", "timeoutSeconds": <optional> }
+  { "kind": "agentTurn", "message": "<prompt>", "model": "<optional>", "thinking": "<optional>", "timeoutSeconds": <optional, 0 means no timeout> }
 
-DELIVERY (isolated-only, top-level):
-  { "mode": "none|announce", "channel": "<optional>", "to": "<optional>", "bestEffort": <optional-bool> }
+DELIVERY (top-level):
+  { "mode": "none|announce|webhook", "channel": "<optional>", "to": "<optional>", "bestEffort": <optional-bool> }
   - Default for isolated agentTurn jobs (when delivery omitted): "announce"
-  - If the task needs to send to a specific chat/recipient, set delivery.channel/to here; do not call messaging tools inside the run.
+  - announce: send to chat channel (optional channel/to target)
+  - webhook: send finished-run event as HTTP POST to delivery.to (URL required)
+  - If the task needs to send to a specific chat/recipient, set announce delivery.channel/to; do not call messaging tools inside the run.
 
 CRITICAL CONSTRAINTS:
 - sessionTarget="main" REQUIRES payload.kind="systemEvent"
 - sessionTarget="isolated" REQUIRES payload.kind="agentTurn"
+- For webhook callbacks, use delivery.mode="webhook" with delivery.to set to a URL.
 Default: prefer isolated agentTurn jobs unless the user explicitly wants a main-session system event.
 
 WAKE MODES (for wake action):
@@ -258,7 +239,7 @@ Use jobId as the canonical identifier; id is accepted for compatibility. Use con
                     // job properties to the top level alongside `action` instead of nesting
                     // them inside `job`. When `params.job` is missing or empty, reconstruct
                     // a synthetic job object from any recognised top-level job fields.
-                    // See: https://github.com/openclaw/openclaw/issues/11310
+                    // See: https://github.com/poolbot/poolbot/issues/11310
                     if (!params.job ||
                         (typeof params.job === "object" &&
                             params.job !== null &&
@@ -274,6 +255,7 @@ Use jobId as the canonical identifier; id is accepted for compatibility. Use con
                             "description",
                             "deleteAfterRun",
                             "agentId",
+                            "sessionKey",
                             "message",
                             "text",
                             "model",
@@ -304,13 +286,22 @@ Use jobId as the canonical identifier; id is accepted for compatibility. Use con
                         throw new Error("job required");
                     }
                     const job = normalizeCronJobCreate(params.job) ?? params.job;
-                    if (job && typeof job === "object" && !("agentId" in job)) {
+                    if (job && typeof job === "object") {
                         const cfg = loadConfig();
-                        const agentId = opts?.agentSessionKey
-                            ? resolveSessionAgentId({ sessionKey: opts.agentSessionKey, config: cfg })
+                        const { mainKey, alias } = resolveMainSessionAlias(cfg);
+                        const resolvedSessionKey = opts?.agentSessionKey
+                            ? resolveInternalSessionKey({ key: opts.agentSessionKey, alias, mainKey })
                             : undefined;
-                        if (agentId) {
-                            job.agentId = agentId;
+                        if (!("agentId" in job)) {
+                            const agentId = opts?.agentSessionKey
+                                ? resolveSessionAgentId({ sessionKey: opts.agentSessionKey, config: cfg })
+                                : undefined;
+                            if (agentId) {
+                                job.agentId = agentId;
+                            }
+                        }
+                        if (!("sessionKey" in job) && resolvedSessionKey) {
+                            job.sessionKey = resolvedSessionKey;
                         }
                     }
                     if (opts?.agentSessionKey &&
@@ -322,9 +313,20 @@ Use jobId as the canonical identifier; id is accepted for compatibility. Use con
                         const delivery = isRecord(deliveryValue) ? deliveryValue : undefined;
                         const modeRaw = typeof delivery?.mode === "string" ? delivery.mode : "";
                         const mode = modeRaw.trim().toLowerCase();
+                        if (mode === "webhook") {
+                            const webhookUrl = normalizeHttpWebhookUrl(delivery?.to);
+                            if (!webhookUrl) {
+                                throw new Error('delivery.mode="webhook" requires delivery.to to be a valid http(s) URL');
+                            }
+                            if (delivery) {
+                                delivery.to = webhookUrl;
+                            }
+                        }
                         const hasTarget = (typeof delivery?.channel === "string" && delivery.channel.trim()) ||
                             (typeof delivery?.to === "string" && delivery.to.trim());
-                        const shouldInfer = (deliveryValue == null || delivery) && mode !== "none" && !hasTarget;
+                        const shouldInfer = (deliveryValue == null || delivery) &&
+                            (mode === "" || mode === "announce") &&
+                            !hasTarget;
                         if (shouldInfer) {
                             const inferred = inferDeliveryFromSessionKey(opts.agentSessionKey);
                             if (inferred) {

package/dist/agents/tools/gateway.js

@@ -1,17 +1,85 @@
+import { loadConfig, resolveGatewayPort } from "../../config/config.js";
 import { callGateway } from "../../gateway/call.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../../utils/message-channel.js";
+import { readStringParam } from "./common.js";
 export const DEFAULT_GATEWAY_URL = "ws://127.0.0.1:18789";
+export function readGatewayCallOptions(params) {
+    return {
+        gatewayUrl: readStringParam(params, "gatewayUrl", { trim: false }),
+        gatewayToken: readStringParam(params, "gatewayToken", { trim: false }),
+        timeoutMs: typeof params.timeoutMs === "number" ? params.timeoutMs : undefined,
+    };
+}
+function canonicalizeToolGatewayWsUrl(raw) {
+    const input = raw.trim();
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`invalid gatewayUrl: ${input} (${message})`, { cause: error });
+    }
+    if (url.protocol !== "ws:" && url.protocol !== "wss:") {
+        throw new Error(`invalid gatewayUrl protocol: ${url.protocol} (expected ws:// or wss://)`);
+    }
+    if (url.username || url.password) {
+        throw new Error("invalid gatewayUrl: credentials are not allowed");
+    }
+    if (url.search || url.hash) {
+        throw new Error("invalid gatewayUrl: query/hash not allowed");
+    }
+    // Agents/tools expect the gateway websocket on the origin, not arbitrary paths.
+    if (url.pathname && url.pathname !== "/") {
+        throw new Error("invalid gatewayUrl: path not allowed");
+    }
+    const origin = url.origin;
+    // Key: protocol + host only, lowercased. (host includes IPv6 brackets + port when present)
+    const key = `${url.protocol}//${url.host.toLowerCase()}`;
+    return { origin, key };
+}
+function validateGatewayUrlOverrideForAgentTools(urlOverride) {
+    const cfg = loadConfig();
+    const port = resolveGatewayPort(cfg);
+    const allowed = new Set([
+        `ws://127.0.0.1:${port}`,
+        `wss://127.0.0.1:${port}`,
+        `ws://localhost:${port}`,
+        `wss://localhost:${port}`,
+        `ws://[::1]:${port}`,
+        `wss://[::1]:${port}`,
+    ]);
+    const remoteUrl = typeof cfg.gateway?.remote?.url === "string" ? cfg.gateway.remote.url.trim() : "";
+    if (remoteUrl) {
+        try {
+            const remote = canonicalizeToolGatewayWsUrl(remoteUrl);
+            allowed.add(remote.key);
+        }
+        catch {
+            // ignore: misconfigured remote url; tools should fall back to default resolution.
+        }
+    }
+    const parsed = canonicalizeToolGatewayWsUrl(urlOverride);
+    if (!allowed.has(parsed.key)) {
+        throw new Error([
+            "gatewayUrl override rejected.",
+            `Allowed: ws(s) loopback on port ${port} (127.0.0.1/localhost/[::1])`,
+            "Or: configure gateway.remote.url and omit gatewayUrl to use the configured remote gateway.",
+        ].join(" "));
+    }
+    return parsed.origin;
+}
 export function resolveGatewayOptions(opts) {
     // Prefer an explicit override; otherwise let callGateway choose based on config.
     const url = typeof opts?.gatewayUrl === "string" && opts.gatewayUrl.trim()
-        ? opts.gatewayUrl.trim()
+        ? validateGatewayUrlOverrideForAgentTools(opts.gatewayUrl)
         : undefined;
     const token = typeof opts?.gatewayToken === "string" && opts.gatewayToken.trim()
         ? opts.gatewayToken.trim()
         : undefined;
     const timeoutMs = typeof opts?.timeoutMs === "number" && Number.isFinite(opts.timeoutMs)
         ? Math.max(1, Math.floor(opts.timeoutMs))
-        : 10_000;
+        : 30_000;
     return { url, token, timeoutMs };
 }
 export async function callGatewayTool(method, opts, params, extra) {