@poolzin/pool-bot 2026.2.0 → 2026.2.1

package/dist/agents/tools/web-search.js

@@ -1,8 +1,10 @@
 import { Type } from "@sinclair/typebox";
 import { formatCliCommand } from "../../cli/command-format.js";
+import { wrapWebContent } from "../../security/external-content.js";
+import { normalizeSecretInput } from "../../utils/normalize-secret-input.js";
 import { jsonResult, readNumberParam, readStringParam } from "./common.js";
 import { DEFAULT_CACHE_TTL_MINUTES, DEFAULT_TIMEOUT_SECONDS, normalizeCacheKey, readCache, readResponseText, resolveCacheTtlMs, resolveTimeoutSeconds, withTimeout, writeCache, } from "./web-shared.js";
-const SEARCH_PROVIDERS = ["brave", "perplexity"];
+const SEARCH_PROVIDERS = ["brave", "perplexity", "grok"];
 const DEFAULT_SEARCH_COUNT = 5;
 const MAX_SEARCH_COUNT = 10;
 const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
@@ -11,6 +13,8 @@ const PERPLEXITY_DIRECT_BASE_URL = "https://api.perplexity.ai";
 const DEFAULT_PERPLEXITY_MODEL = "perplexity/sonar-pro";
 const PERPLEXITY_KEY_PREFIXES = ["pplx-"];
 const OPENROUTER_KEY_PREFIXES = ["sk-or-"];
+const XAI_API_ENDPOINT = "https://api.x.ai/v1/responses";
+const DEFAULT_GROK_MODEL = "grok-4-1-fast";
 const SEARCH_CACHE = new Map();
 const BRAVE_FRESHNESS_SHORTCUTS = new Set(["pd", "pw", "pm", "py"]);
 const BRAVE_FRESHNESS_RANGE = /^(\d{4}-\d{2}-\d{2})to(\d{4}-\d{2}-\d{2})$/;
@@ -34,22 +38,35 @@ const WebSearchSchema = Type.Object({
         description: "Filter results by discovery time (Brave only). Values: 'pd' (past 24h), 'pw' (past week), 'pm' (past month), 'py' (past year), or date range 'YYYY-MM-DDtoYYYY-MM-DD'.",
     })),
 });
+function extractGrokContent(data) {
+    // xAI Responses API format: output[0].content[0].text
+    const fromResponses = data.output?.[0]?.content?.[0]?.text;
+    if (typeof fromResponses === "string" && fromResponses) {
+        return fromResponses;
+    }
+    return typeof data.output_text === "string" ? data.output_text : undefined;
+}
 function resolveSearchConfig(cfg) {
     const search = cfg?.tools?.web?.search;
-    if (!search || typeof search !== "object")
+    if (!search || typeof search !== "object") {
         return undefined;
+    }
     return search;
 }
 function resolveSearchEnabled(params) {
-    if (typeof params.search?.enabled === "boolean")
+    if (typeof params.search?.enabled === "boolean") {
         return params.search.enabled;
-    if (params.sandboxed)
+    }
+    if (params.sandboxed) {
         return true;
+    }
     return true;
 }
 function resolveSearchApiKey(search) {
-    const fromConfig = search && "apiKey" in search && typeof search.apiKey === "string" ? search.apiKey.trim() : "";
-    const fromEnv = (process.env.BRAVE_API_KEY ?? "").trim();
+    const fromConfig = search && "apiKey" in search && typeof search.apiKey === "string"
+        ? normalizeSecretInput(search.apiKey)
+        : "";
+    const fromEnv = normalizeSecretInput(process.env.BRAVE_API_KEY);
     return fromConfig || fromEnv || undefined;
 }
 function missingSearchKeyPayload(provider) {
@@ -60,6 +77,13 @@ function missingSearchKeyPayload(provider) {
             docs: "https://docs.molt.bot/tools/web",
         };
     }
+    if (provider === "grok") {
+        return {
+            error: "missing_xai_api_key",
+            message: "web_search (grok) needs an xAI API key. Set XAI_API_KEY in the Gateway environment, or configure tools.web.search.grok.apiKey.",
+            docs: "https://docs.molt.bot/tools/web",
+        };
+    }
     return {
         error: "missing_brave_api_key",
         message: `web_search needs a Brave Search API key. Run \`${formatCliCommand("poolbot configure --section web")}\` to store it, or set BRAVE_API_KEY in the Gateway environment.`,
@@ -70,18 +94,25 @@ function resolveSearchProvider(search) {
     const raw = search && "provider" in search && typeof search.provider === "string"
         ? search.provider.trim().toLowerCase()
         : "";
-    if (raw === "perplexity")
+    if (raw === "perplexity") {
         return "perplexity";
-    if (raw === "brave")
+    }
+    if (raw === "grok") {
+        return "grok";
+    }
+    if (raw === "brave") {
         return "brave";
+    }
     return "brave";
 }
 function resolvePerplexityConfig(search) {
-    if (!search || typeof search !== "object")
+    if (!search || typeof search !== "object") {
         return {};
+    }
     const perplexity = "perplexity" in search ? search.perplexity : undefined;
-    if (!perplexity || typeof perplexity !== "object")
+    if (!perplexity || typeof perplexity !== "object") {
         return {};
+    }
     return perplexity;
 }
 function resolvePerplexityApiKey(perplexity) {
@@ -100,11 +131,12 @@ function resolvePerplexityApiKey(perplexity) {
     return { apiKey: undefined, source: "none" };
 }
 function normalizeApiKey(key) {
-    return typeof key === "string" ? key.trim() : "";
+    return normalizeSecretInput(key);
 }
 function inferPerplexityBaseUrlFromApiKey(apiKey) {
-    if (!apiKey)
+    if (!apiKey) {
         return undefined;
+    }
     const normalized = apiKey.toLowerCase();
     if (PERPLEXITY_KEY_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
         return "direct";
@@ -118,18 +150,23 @@ function resolvePerplexityBaseUrl(perplexity, apiKeySource = "none", apiKey) {
     const fromConfig = perplexity && "baseUrl" in perplexity && typeof perplexity.baseUrl === "string"
         ? perplexity.baseUrl.trim()
         : "";
-    if (fromConfig)
+    if (fromConfig) {
         return fromConfig;
-    if (apiKeySource === "perplexity_env")
+    }
+    if (apiKeySource === "perplexity_env") {
         return PERPLEXITY_DIRECT_BASE_URL;
-    if (apiKeySource === "openrouter_env")
+    }
+    if (apiKeySource === "openrouter_env") {
         return DEFAULT_PERPLEXITY_BASE_URL;
+    }
     if (apiKeySource === "config") {
         const inferred = inferPerplexityBaseUrlFromApiKey(apiKey);
-        if (inferred === "direct")
+        if (inferred === "direct") {
             return PERPLEXITY_DIRECT_BASE_URL;
-        if (inferred === "openrouter")
+        }
+        if (inferred === "openrouter") {
             return DEFAULT_PERPLEXITY_BASE_URL;
+        }
     }
     return DEFAULT_PERPLEXITY_BASE_URL;
 }
@@ -139,42 +176,94 @@ function resolvePerplexityModel(perplexity) {
         : "";
     return fromConfig || DEFAULT_PERPLEXITY_MODEL;
 }
+function isDirectPerplexityBaseUrl(baseUrl) {
+    const trimmed = baseUrl.trim();
+    if (!trimmed) {
+        return false;
+    }
+    try {
+        return new URL(trimmed).hostname.toLowerCase() === "api.perplexity.ai";
+    }
+    catch {
+        return false;
+    }
+}
+function resolvePerplexityRequestModel(baseUrl, model) {
+    if (!isDirectPerplexityBaseUrl(baseUrl)) {
+        return model;
+    }
+    return model.startsWith("perplexity/") ? model.slice("perplexity/".length) : model;
+}
+function resolveGrokConfig(search) {
+    if (!search || typeof search !== "object") {
+        return {};
+    }
+    const grok = "grok" in search ? search.grok : undefined;
+    if (!grok || typeof grok !== "object") {
+        return {};
+    }
+    return grok;
+}
+function resolveGrokApiKey(grok) {
+    const fromConfig = normalizeApiKey(grok?.apiKey);
+    if (fromConfig) {
+        return fromConfig;
+    }
+    const fromEnv = normalizeApiKey(process.env.XAI_API_KEY);
+    return fromEnv || undefined;
+}
+function resolveGrokModel(grok) {
+    const fromConfig = grok && "model" in grok && typeof grok.model === "string" ? grok.model.trim() : "";
+    return fromConfig || DEFAULT_GROK_MODEL;
+}
+function resolveGrokInlineCitations(grok) {
+    return grok?.inlineCitations === true;
+}
 function resolveSearchCount(value, fallback) {
     const parsed = typeof value === "number" && Number.isFinite(value) ? value : fallback;
     const clamped = Math.max(1, Math.min(MAX_SEARCH_COUNT, Math.floor(parsed)));
     return clamped;
 }
 function normalizeFreshness(value) {
-    if (!value)
+    if (!value) {
         return undefined;
+    }
     const trimmed = value.trim();
-    if (!trimmed)
+    if (!trimmed) {
         return undefined;
+    }
     const lower = trimmed.toLowerCase();
-    if (BRAVE_FRESHNESS_SHORTCUTS.has(lower))
+    if (BRAVE_FRESHNESS_SHORTCUTS.has(lower)) {
         return lower;
+    }
     const match = trimmed.match(BRAVE_FRESHNESS_RANGE);
-    if (!match)
+    if (!match) {
         return undefined;
+    }
     const [, start, end] = match;
-    if (!isValidIsoDate(start) || !isValidIsoDate(end))
+    if (!isValidIsoDate(start) || !isValidIsoDate(end)) {
         return undefined;
-    if (start > end)
+    }
+    if (start > end) {
         return undefined;
+    }
     return `${start}to${end}`;
 }
 function isValidIsoDate(value) {
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
         return false;
+    }
     const [year, month, day] = value.split("-").map((part) => Number.parseInt(part, 10));
-    if (!Number.isFinite(year) || !Number.isFinite(month) || !Number.isFinite(day))
+    if (!Number.isFinite(year) || !Number.isFinite(month) || !Number.isFinite(day)) {
         return false;
+    }
     const date = new Date(Date.UTC(year, month - 1, day));
     return (date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day);
 }
 function resolveSiteName(url) {
-    if (!url)
+    if (!url) {
         return undefined;
+    }
     try {
         return new URL(url).hostname;
     }
@@ -183,17 +272,19 @@ function resolveSiteName(url) {
     }
 }
 async function runPerplexitySearch(params) {
-    const endpoint = `${params.baseUrl.replace(/\/$/, "")}/chat/completions`;
+    const baseUrl = params.baseUrl.trim().replace(/\/$/, "");
+    const endpoint = `${baseUrl}/chat/completions`;
+    const model = resolvePerplexityRequestModel(baseUrl, params.model);
     const res = await fetch(endpoint, {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
             Authorization: `Bearer ${params.apiKey}`,
             "HTTP-Referer": "https://molt.bot",
-            "X-Title": "Poolbot Web Search",
+            "X-Title": "Pool Bot Web Search",
         },
         body: JSON.stringify({
-            model: params.model,
+            model,
             messages: [
                 {
                     role: "user",
@@ -212,13 +303,49 @@ async function runPerplexitySearch(params) {
     const citations = data.citations ?? [];
     return { content, citations };
 }
+async function runGrokSearch(params) {
+    const body = {
+        model: params.model,
+        input: [
+            {
+                role: "user",
+                content: params.query,
+            },
+        ],
+        tools: [{ type: "web_search" }],
+    };
+    if (params.inlineCitations) {
+        body.include = ["inline_citations"];
+    }
+    const res = await fetch(XAI_API_ENDPOINT, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${params.apiKey}`,
+        },
+        body: JSON.stringify(body),
+        signal: withTimeout(undefined, params.timeoutSeconds * 1000),
+    });
+    if (!res.ok) {
+        const detail = await readResponseText(res);
+        throw new Error(`xAI API error (${res.status}): ${detail || res.statusText}`);
+    }
+    const data = (await res.json());
+    const content = extractGrokContent(data) ?? "No response";
+    const citations = data.citations ?? [];
+    const inlineCitations = data.inline_citations;
+    return { content, citations, inlineCitations };
+}
 async function runWebSearch(params) {
     const cacheKey = normalizeCacheKey(params.provider === "brave"
         ? `${params.provider}:${params.query}:${params.count}:${params.country || "default"}:${params.search_lang || "default"}:${params.ui_lang || "default"}:${params.freshness || "default"}`
-        : `${params.provider}:${params.query}:${params.count}:${params.country || "default"}:${params.search_lang || "default"}:${params.ui_lang || "default"}`);
+        : params.provider === "perplexity"
+            ? `${params.provider}:${params.query}:${params.perplexityBaseUrl ?? DEFAULT_PERPLEXITY_BASE_URL}:${params.perplexityModel ?? DEFAULT_PERPLEXITY_MODEL}`
+            : `${params.provider}:${params.query}:${params.grokModel ?? DEFAULT_GROK_MODEL}:${String(params.grokInlineCitations ?? false)}`);
     const cached = readCache(SEARCH_CACHE, cacheKey);
-    if (cached)
+    if (cached) {
         return { ...cached.value, cached: true };
+    }
     const start = Date.now();
     if (params.provider === "perplexity") {
         const { content, citations } = await runPerplexitySearch({
@@ -233,8 +360,28 @@ async function runWebSearch(params) {
             provider: params.provider,
             model: params.perplexityModel ?? DEFAULT_PERPLEXITY_MODEL,
             tookMs: Date.now() - start,
-            content,
+            content: wrapWebContent(content),
+            citations,
+        };
+        writeCache(SEARCH_CACHE, cacheKey, payload, params.cacheTtlMs);
+        return payload;
+    }
+    if (params.provider === "grok") {
+        const { content, citations, inlineCitations } = await runGrokSearch({
+            query: params.query,
+            apiKey: params.apiKey,
+            model: params.grokModel ?? DEFAULT_GROK_MODEL,
+            timeoutSeconds: params.timeoutSeconds,
+            inlineCitations: params.grokInlineCitations ?? false,
+        });
+        const payload = {
+            query: params.query,
+            provider: params.provider,
+            model: params.grokModel ?? DEFAULT_GROK_MODEL,
+            tookMs: Date.now() - start,
+            content: wrapWebContent(content),
             citations,
+            inlineCitations,
         };
         writeCache(SEARCH_CACHE, cacheKey, payload, params.cacheTtlMs);
         return payload;
@@ -271,13 +418,19 @@ async function runWebSearch(params) {
     }
     const data = (await res.json());
     const results = Array.isArray(data.web?.results) ? (data.web?.results ?? []) : [];
-    const mapped = results.map((entry) => ({
-        title: entry.title ?? "",
-        url: entry.url ?? "",
-        description: entry.description ?? "",
-        published: entry.age ?? undefined,
-        siteName: resolveSiteName(entry.url ?? ""),
-    }));
+    const mapped = results.map((entry) => {
+        const description = entry.description ?? "";
+        const title = entry.title ?? "";
+        const url = entry.url ?? "";
+        const rawSiteName = resolveSiteName(url);
+        return {
+            title: title ? wrapWebContent(title, "web_search") : "",
+            url, // Keep raw for tool chaining
+            description: description ? wrapWebContent(description, "web_search") : "",
+            published: entry.age || undefined,
+            siteName: rawSiteName || undefined,
+        };
+    });
     const payload = {
         query: params.query,
         provider: params.provider,
@@ -290,13 +443,17 @@ async function runWebSearch(params) {
 }
 export function createWebSearchTool(options) {
     const search = resolveSearchConfig(options?.config);
-    if (!resolveSearchEnabled({ search, sandboxed: options?.sandboxed }))
+    if (!resolveSearchEnabled({ search, sandboxed: options?.sandboxed })) {
         return null;
+    }
     const provider = resolveSearchProvider(search);
     const perplexityConfig = resolvePerplexityConfig(search);
+    const grokConfig = resolveGrokConfig(search);
     const description = provider === "perplexity"
         ? "Search the web using Perplexity Sonar (direct or via OpenRouter). Returns AI-synthesized answers with citations from real-time web search."
-        : "Search the web using Brave Search API. Supports region-specific and localized search via country and language parameters. Returns titles, URLs, and snippets for fast research.";
+        : provider === "grok"
+            ? "Search the web using xAI Grok. Returns AI-synthesized answers with citations from real-time web search."
+            : "Search the web using Brave Search API. Supports region-specific and localized search via country and language parameters. Returns titles, URLs, and snippets for fast research.";
     return {
         label: "Web Search",
         name: "web_search",
@@ -304,7 +461,11 @@ export function createWebSearchTool(options) {
         parameters: WebSearchSchema,
         execute: async (_toolCallId, args) => {
             const perplexityAuth = provider === "perplexity" ? resolvePerplexityApiKey(perplexityConfig) : undefined;
-            const apiKey = provider === "perplexity" ? perplexityAuth?.apiKey : resolveSearchApiKey(search);
+            const apiKey = provider === "perplexity"
+                ? perplexityAuth?.apiKey
+                : provider === "grok"
+                    ? resolveGrokApiKey(grokConfig)
+                    : resolveSearchApiKey(search);
             if (!apiKey) {
                 return jsonResult(missingSearchKeyPayload(provider));
             }
@@ -343,6 +504,8 @@ export function createWebSearchTool(options) {
                 freshness,
                 perplexityBaseUrl: resolvePerplexityBaseUrl(perplexityConfig, perplexityAuth?.source, perplexityAuth?.apiKey),
                 perplexityModel: resolvePerplexityModel(perplexityConfig),
+                grokModel: resolveGrokModel(grokConfig),
+                grokInlineCitations: resolveGrokInlineCitations(grokConfig),
             });
             return jsonResult(result);
         },
@@ -351,5 +514,11 @@ export function createWebSearchTool(options) {
 export const __testing = {
     inferPerplexityBaseUrlFromApiKey,
     resolvePerplexityBaseUrl,
+    isDirectPerplexityBaseUrl,
+    resolvePerplexityRequestModel,
     normalizeFreshness,
+    resolveGrokApiKey,
+    resolveGrokModel,
+    resolveGrokInlineCitations,
+    extractGrokContent,
 };

package/dist/agents/usage.js

@@ -38,11 +38,33 @@ export function normalizeUsage(raw) {
     };
 }
 export function derivePromptTokens(usage) {
-    if (!usage)
+    if (!usage) {
         return undefined;
+    }
     const input = usage.input ?? 0;
     const cacheRead = usage.cacheRead ?? 0;
     const cacheWrite = usage.cacheWrite ?? 0;
     const sum = input + cacheRead + cacheWrite;
     return sum > 0 ? sum : undefined;
 }
+export function deriveSessionTotalTokens(params) {
+    const usage = params.usage;
+    if (!usage) {
+        return undefined;
+    }
+    const input = usage.input ?? 0;
+    const promptTokens = derivePromptTokens({
+        input: usage.input,
+        cacheRead: usage.cacheRead,
+        cacheWrite: usage.cacheWrite,
+    });
+    let total = promptTokens ?? usage.total ?? input;
+    if (!(total > 0)) {
+        return undefined;
+    }
+    const contextTokens = params.contextTokens;
+    if (typeof contextTokens === "number" && Number.isFinite(contextTokens) && contextTokens > 0) {
+        total = Math.min(total, contextTokens);
+    }
+    return total;
+}

package/dist/agents/workspace-run.js

@@ -0,0 +1,67 @@
+import { redactIdentifier } from "../logging/redact-identifier.js";
+import { classifySessionKeyShape, DEFAULT_AGENT_ID, normalizeAgentId, parseAgentSessionKey, } from "../routing/session-key.js";
+import { resolveUserPath } from "../utils.js";
+import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "./agent-scope.js";
+function resolveRunAgentId(params) {
+    const rawSessionKey = params.sessionKey?.trim() ?? "";
+    const shape = classifySessionKeyShape(rawSessionKey);
+    if (shape === "malformed_agent") {
+        throw new Error("Malformed agent session key; refusing workspace resolution.");
+    }
+    const explicit = typeof params.agentId === "string" && params.agentId.trim()
+        ? normalizeAgentId(params.agentId)
+        : undefined;
+    if (explicit) {
+        return { agentId: explicit, agentIdSource: "explicit" };
+    }
+    const defaultAgentId = resolveDefaultAgentId(params.config ?? {});
+    if (shape === "missing" || shape === "legacy_or_alias") {
+        return {
+            agentId: defaultAgentId || DEFAULT_AGENT_ID,
+            agentIdSource: "default",
+        };
+    }
+    const parsed = parseAgentSessionKey(rawSessionKey);
+    if (parsed?.agentId) {
+        return {
+            agentId: normalizeAgentId(parsed.agentId),
+            agentIdSource: "session_key",
+        };
+    }
+    // Defensive fallback, should be unreachable for non-malformed shapes.
+    return {
+        agentId: defaultAgentId || DEFAULT_AGENT_ID,
+        agentIdSource: "default",
+    };
+}
+export function redactRunIdentifier(value) {
+    return redactIdentifier(value, { len: 12 });
+}
+export function resolveRunWorkspaceDir(params) {
+    const requested = params.workspaceDir;
+    const { agentId, agentIdSource } = resolveRunAgentId({
+        sessionKey: params.sessionKey,
+        agentId: params.agentId,
+        config: params.config,
+    });
+    if (typeof requested === "string") {
+        const trimmed = requested.trim();
+        if (trimmed) {
+            return {
+                workspaceDir: resolveUserPath(trimmed),
+                usedFallback: false,
+                agentId,
+                agentIdSource,
+            };
+        }
+    }
+    const fallbackReason = requested == null ? "missing" : typeof requested === "string" ? "blank" : "invalid_type";
+    const fallbackWorkspace = resolveAgentWorkspaceDir(params.config ?? {}, agentId);
+    return {
+        workspaceDir: resolveUserPath(fallbackWorkspace),
+        usedFallback: true,
+        fallbackReason,
+        agentId,
+        agentIdSource,
+    };
+}

package/dist/agents/workspace-templates.js

@@ -0,0 +1,44 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolvePoolBotPackageRoot } from "../infra/poolbot-root.js";
+import { pathExists } from "../utils.js";
+const FALLBACK_TEMPLATE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../docs/reference/templates");
+let cachedTemplateDir;
+let resolvingTemplateDir;
+export async function resolveWorkspaceTemplateDir(opts) {
+    if (cachedTemplateDir) {
+        return cachedTemplateDir;
+    }
+    if (resolvingTemplateDir) {
+        return resolvingTemplateDir;
+    }
+    resolvingTemplateDir = (async () => {
+        const moduleUrl = opts?.moduleUrl ?? import.meta.url;
+        const argv1 = opts?.argv1 ?? process.argv[1];
+        const cwd = opts?.cwd ?? process.cwd();
+        const packageRoot = await resolvePoolBotPackageRoot({ moduleUrl, argv1, cwd });
+        const candidates = [
+            packageRoot ? path.join(packageRoot, "docs", "reference", "templates") : null,
+            cwd ? path.resolve(cwd, "docs", "reference", "templates") : null,
+            FALLBACK_TEMPLATE_DIR,
+        ].filter(Boolean);
+        for (const candidate of candidates) {
+            if (await pathExists(candidate)) {
+                cachedTemplateDir = candidate;
+                return candidate;
+            }
+        }
+        cachedTemplateDir = candidates[0] ?? FALLBACK_TEMPLATE_DIR;
+        return cachedTemplateDir;
+    })();
+    try {
+        return await resolvingTemplateDir;
+    }
+    finally {
+        resolvingTemplateDir = undefined;
+    }
+}
+export function resetWorkspaceTemplateDirCache() {
+    cachedTemplateDir = undefined;
+    resolvingTemplateDir = undefined;
+}