@poolzin/pool-bot 2026.2.17 → 2026.2.19

package/dist/auto-reply/reply/directive-handling.levels.js

@@ -0,0 +1,17 @@
+export async function resolveCurrentDirectiveLevels(params) {
+    const resolvedDefaultThinkLevel = params.sessionEntry?.thinkingLevel ??
+        params.agentCfg?.thinkingDefault ??
+        (await params.resolveDefaultThinkingLevel());
+    const currentThinkLevel = resolvedDefaultThinkLevel;
+    const currentVerboseLevel = params.sessionEntry?.verboseLevel ??
+        params.agentCfg?.verboseDefault;
+    const currentReasoningLevel = params.sessionEntry?.reasoningLevel ?? "off";
+    const currentElevatedLevel = params.sessionEntry?.elevatedLevel ??
+        params.agentCfg?.elevatedDefault;
+    return {
+        currentThinkLevel,
+        currentVerboseLevel,
+        currentReasoningLevel,
+        currentElevatedLevel,
+    };
+}

package/dist/auto-reply/reply/directive-handling.params.js

@@ -0,0 +1 @@
+export {};

package/dist/auto-reply/reply/directive-parsing.js

@@ -0,0 +1,36 @@
+export function skipDirectiveArgPrefix(raw) {
+    let i = 0;
+    const len = raw.length;
+    while (i < len && /\s/.test(raw[i])) {
+        i += 1;
+    }
+    if (raw[i] === ":") {
+        i += 1;
+        while (i < len && /\s/.test(raw[i])) {
+            i += 1;
+        }
+    }
+    return i;
+}
+export function takeDirectiveToken(raw, startIndex) {
+    let i = startIndex;
+    const len = raw.length;
+    while (i < len && /\s/.test(raw[i])) {
+        i += 1;
+    }
+    if (i >= len) {
+        return { token: null, nextIndex: i };
+    }
+    const start = i;
+    while (i < len && !/\s/.test(raw[i])) {
+        i += 1;
+    }
+    if (start === i) {
+        return { token: null, nextIndex: i };
+    }
+    const token = raw.slice(start, i);
+    while (i < len && /\s/.test(raw[i])) {
+        i += 1;
+    }
+    return { token, nextIndex: i };
+}

package/dist/auto-reply/reply/dispatcher-registry.js

@@ -0,0 +1,43 @@
+/**
+ * Global registry for tracking active reply dispatchers.
+ * Used to ensure gateway restart waits for all replies to complete.
+ */
+const activeDispatchers = new Set();
+let nextId = 0;
+/**
+ * Register a reply dispatcher for global tracking.
+ * Returns an unregister function to call when the dispatcher is no longer needed.
+ */
+export function registerDispatcher(dispatcher) {
+    const id = `dispatcher-${++nextId}`;
+    const tracked = {
+        id,
+        pending: dispatcher.pending,
+        waitForIdle: dispatcher.waitForIdle,
+    };
+    activeDispatchers.add(tracked);
+    const unregister = () => {
+        activeDispatchers.delete(tracked);
+    };
+    return { id, unregister };
+}
+/**
+ * Get the total number of pending replies across all dispatchers.
+ */
+export function getTotalPendingReplies() {
+    let total = 0;
+    for (const dispatcher of activeDispatchers) {
+        total += dispatcher.pending();
+    }
+    return total;
+}
+/**
+ * Clear all registered dispatchers (for testing).
+ * WARNING: Only use this in test cleanup!
+ */
+export function clearAllDispatchers() {
+    if (!process.env.VITEST && process.env.NODE_ENV !== "test") {
+        throw new Error("clearAllDispatchers() is only available in test environments");
+    }
+    activeDispatchers.clear();
+}

package/dist/auto-reply/reply/elevated-unavailable.js

@@ -0,0 +1,20 @@
+import { formatCliCommand } from "../../cli/command-format.js";
+export function formatElevatedUnavailableMessage(params) {
+    const lines = [];
+    lines.push(`elevated is not available right now (runtime=${params.runtimeSandboxed ? "sandboxed" : "direct"}).`);
+    if (params.failures.length > 0) {
+        lines.push(`Failing gates: ${params.failures.map((f) => `${f.gate} (${f.key})`).join(", ")}`);
+    }
+    else {
+        lines.push("Failing gates: enabled (tools.elevated.enabled / agents.list[].tools.elevated.enabled), allowFrom (tools.elevated.allowFrom.<provider>).");
+    }
+    lines.push("Fix-it keys:");
+    lines.push("- tools.elevated.enabled");
+    lines.push("- tools.elevated.allowFrom.<provider>");
+    lines.push("- agents.list[].tools.elevated.enabled");
+    lines.push("- agents.list[].tools.elevated.allowFrom.<provider>");
+    if (params.sessionKey) {
+        lines.push(`See: ${formatCliCommand(`openclaw sandbox explain --session ${params.sessionKey}`)}`);
+    }
+    return lines.join("\n");
+}

package/dist/auto-reply/reply/reply-delivery.js

@@ -0,0 +1,92 @@
+import { logVerbose } from "../../globals.js";
+import { SILENT_REPLY_TOKEN } from "../tokens.js";
+import { createBlockReplyPayloadKey } from "./block-reply-pipeline.js";
+import { parseReplyDirectives } from "./reply-directives.js";
+import { applyReplyTagsToPayload, isRenderablePayload } from "./reply-payloads.js";
+export function normalizeReplyPayloadDirectives(params) {
+    const parseMode = params.parseMode ?? "always";
+    const silentToken = params.silentToken ?? SILENT_REPLY_TOKEN;
+    const sourceText = params.payload.text ?? "";
+    const shouldParse = parseMode === "always" ||
+        (parseMode === "auto" &&
+            (sourceText.includes("[[") ||
+                sourceText.includes("MEDIA:") ||
+                sourceText.includes(silentToken)));
+    const parsed = shouldParse
+        ? parseReplyDirectives(sourceText, {
+            currentMessageId: params.currentMessageId,
+            silentToken,
+        })
+        : undefined;
+    let text = parsed ? parsed.text || undefined : params.payload.text || undefined;
+    if (params.trimLeadingWhitespace && text) {
+        text = text.trimStart() || undefined;
+    }
+    const mediaUrls = params.payload.mediaUrls ?? parsed?.mediaUrls;
+    const mediaUrl = params.payload.mediaUrl ?? parsed?.mediaUrl ?? mediaUrls?.[0];
+    return {
+        payload: {
+            ...params.payload,
+            text,
+            mediaUrls,
+            mediaUrl,
+            replyToId: params.payload.replyToId ?? parsed?.replyToId,
+            replyToTag: params.payload.replyToTag || parsed?.replyToTag,
+            replyToCurrent: params.payload.replyToCurrent || parsed?.replyToCurrent,
+            audioAsVoice: Boolean(params.payload.audioAsVoice || parsed?.audioAsVoice),
+        },
+        isSilent: parsed?.isSilent ?? false,
+    };
+}
+const hasRenderableMedia = (payload) => Boolean(payload.mediaUrl) || (payload.mediaUrls?.length ?? 0) > 0;
+export function createBlockReplyDeliveryHandler(params) {
+    return async (payload) => {
+        const { text, skip } = params.normalizeStreamingText(payload);
+        if (skip && !hasRenderableMedia(payload)) {
+            return;
+        }
+        const taggedPayload = applyReplyTagsToPayload({
+            ...payload,
+            text,
+            mediaUrl: payload.mediaUrl ?? payload.mediaUrls?.[0],
+            replyToId: payload.replyToId ??
+                (payload.replyToCurrent === false ? undefined : params.currentMessageId),
+        }, params.currentMessageId);
+        // Let through payloads with audioAsVoice flag even if empty (need to track it).
+        if (!isRenderablePayload(taggedPayload) && !payload.audioAsVoice) {
+            return;
+        }
+        const normalized = normalizeReplyPayloadDirectives({
+            payload: taggedPayload,
+            currentMessageId: params.currentMessageId,
+            silentToken: SILENT_REPLY_TOKEN,
+            trimLeadingWhitespace: true,
+            parseMode: "auto",
+        });
+        const blockPayload = params.applyReplyToMode(normalized.payload);
+        const blockHasMedia = hasRenderableMedia(blockPayload);
+        // Skip empty payloads unless they have audioAsVoice flag (need to track it).
+        if (!blockPayload.text && !blockHasMedia && !blockPayload.audioAsVoice) {
+            return;
+        }
+        if (normalized.isSilent && !blockHasMedia) {
+            return;
+        }
+        if (blockPayload.text) {
+            void params.typingSignals.signalTextDelta(blockPayload.text).catch((err) => {
+                logVerbose(`block reply typing signal failed: ${String(err)}`);
+            });
+        }
+        // Use pipeline if available (block streaming enabled), otherwise send directly.
+        if (params.blockStreamingEnabled && params.blockReplyPipeline) {
+            params.blockReplyPipeline.enqueue(blockPayload);
+        }
+        else if (params.blockStreamingEnabled) {
+            // Send directly when flushing before tool execution (no pipeline but streaming enabled).
+            // Track sent key to avoid duplicate in final payloads.
+            params.directlySentBlockKeys.add(createBlockReplyPayloadKey(blockPayload));
+            await params.onBlockReply(blockPayload);
+        }
+        // When streaming is disabled entirely, blocks are accumulated in final text instead.
+    };
+}

package/dist/auto-reply/reply/session-reset-prompt.js

@@ -0,0 +1 @@
+export const BARE_SESSION_RESET_PROMPT = "A new session was started via /new or /reset. Greet the user in your configured persona, if one is provided. Be yourself - use your defined voice, mannerisms, and mood. Keep it to 1-3 sentences and ask what they want to do. If the runtime model differs from default_model in the system prompt, mention the default model. Do not mention internal steps, files, tools, or reasoning.";

package/dist/auto-reply/reply/session-run-accounting.js

@@ -0,0 +1,33 @@
+import { deriveSessionTotalTokens } from "../../agents/usage.js";
+import { incrementCompactionCount } from "./session-updates.js";
+import { persistSessionUsageUpdate } from "./session-usage.js";
+export async function persistRunSessionUsage(params) {
+    await persistSessionUsageUpdate({
+        storePath: params.storePath,
+        sessionKey: params.sessionKey,
+        usage: params.usage,
+        lastCallUsage: params.lastCallUsage,
+        promptTokens: params.promptTokens,
+        modelUsed: params.modelUsed,
+        providerUsed: params.providerUsed,
+        contextTokensUsed: params.contextTokensUsed,
+        systemPromptReport: params.systemPromptReport,
+        cliSessionId: params.cliSessionId,
+        logLabel: params.logLabel,
+    });
+}
+export async function incrementRunCompactionCount(params) {
+    const tokensAfterCompaction = params.lastCallUsage
+        ? deriveSessionTotalTokens({
+            usage: params.lastCallUsage,
+            contextTokens: params.contextTokensUsed,
+        })
+        : undefined;
+    return incrementCompactionCount({
+        sessionEntry: params.sessionEntry,
+        sessionStore: params.sessionStore,
+        sessionKey: params.sessionKey,
+        storePath: params.storePath,
+        tokensAfter: tokensAfterCompaction,
+    });
+}

package/dist/auto-reply/reply.directive.directive-behavior.e2e-harness.js

@@ -0,0 +1,115 @@
+import path from "node:path";
+import { afterEach, beforeEach, expect, vi } from "vitest";
+import { withTempHome as withTempHomeBase } from "../../test/helpers/temp-home.js";
+import { loadModelCatalog } from "../agents/model-catalog.js";
+import { runEmbeddedPiAgent } from "../agents/pi-embedded.js";
+import { loadSessionStore } from "../config/sessions.js";
+export { loadModelCatalog } from "../agents/model-catalog.js";
+export { runEmbeddedPiAgent } from "../agents/pi-embedded.js";
+export const MAIN_SESSION_KEY = "agent:main:main";
+export const DEFAULT_TEST_MODEL_CATALOG = [
+    { id: "claude-opus-4-5", name: "Opus 4.5", provider: "anthropic" },
+    { id: "claude-sonnet-4-1", name: "Sonnet 4.1", provider: "anthropic" },
+    { id: "gpt-4.1-mini", name: "GPT-4.1 Mini", provider: "openai" },
+];
+export function replyText(res) {
+    if (Array.isArray(res)) {
+        return typeof res[0]?.text === "string" ? res[0]?.text : undefined;
+    }
+    return typeof res?.text === "string" ? res.text : undefined;
+}
+export function replyTexts(res) {
+    const payloads = Array.isArray(res) ? res : [res];
+    return payloads
+        .map((entry) => (typeof entry?.text === "string" ? entry.text : undefined))
+        .filter((value) => Boolean(value));
+}
+export async function withTempHome(fn) {
+    return withTempHomeBase(async (home) => {
+        return await fn(home);
+    }, {
+        env: {
+            POOLBOT_AGENT_DIR: (home) => path.join(home, ".openclaw", "agent"),
+            PI_CODING_AGENT_DIR: (home) => path.join(home, ".openclaw", "agent"),
+        },
+        prefix: "openclaw-reply-",
+    });
+}
+export function sessionStorePath(home) {
+    return path.join(home, "sessions.json");
+}
+export function makeWhatsAppDirectiveConfig(home, defaults, extra = {}) {
+    return {
+        agents: {
+            defaults: {
+                workspace: path.join(home, "poolbot"),
+                ...defaults,
+            },
+        },
+        channels: { whatsapp: { allowFrom: ["*"] } },
+        session: { store: sessionStorePath(home) },
+        ...extra,
+    };
+}
+export const AUTHORIZED_WHATSAPP_COMMAND = {
+    From: "+1222",
+    To: "+1222",
+    Provider: "whatsapp",
+    SenderE164: "+1222",
+    CommandAuthorized: true,
+};
+export function makeElevatedDirectiveConfig(home) {
+    return makeWhatsAppDirectiveConfig(home, {
+        model: "anthropic/claude-opus-4-5",
+        elevatedDefault: "on",
+    }, {
+        tools: {
+            elevated: {
+                allowFrom: { whatsapp: ["+1222"] },
+            },
+        },
+        channels: { whatsapp: { allowFrom: ["+1222"] } },
+        session: { store: sessionStorePath(home) },
+    });
+}
+export function assertModelSelection(storePath, selection = {}) {
+    const store = loadSessionStore(storePath);
+    const entry = store[MAIN_SESSION_KEY];
+    expect(entry).toBeDefined();
+    expect(entry?.modelOverride).toBe(selection.model);
+    expect(entry?.providerOverride).toBe(selection.provider);
+}
+export function installDirectiveBehaviorE2EHooks() {
+    beforeEach(() => {
+        vi.mocked(runEmbeddedPiAgent).mockReset();
+        vi.mocked(loadModelCatalog).mockResolvedValue(DEFAULT_TEST_MODEL_CATALOG);
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+}
+export function makeRestrictedElevatedDisabledConfig(home) {
+    return {
+        agents: {
+            defaults: {
+                model: "anthropic/claude-opus-4-5",
+                workspace: path.join(home, "poolbot"),
+            },
+            list: [
+                {
+                    id: "restricted",
+                    tools: {
+                        elevated: { enabled: false },
+                    },
+                },
+            ],
+        },
+        tools: {
+            elevated: {
+                allowFrom: { whatsapp: ["+1222"] },
+            },
+        },
+        channels: { whatsapp: { allowFrom: ["+1222"] } },
+        session: { store: path.join(home, "sessions.json") },
+    };
+}

package/dist/auto-reply/reply.directive.directive-behavior.e2e-mocks.js

@@ -0,0 +1,12 @@
+import { vi } from "vitest";
+vi.mock("../agents/pi-embedded.js", () => ({
+    abortEmbeddedPiRun: vi.fn().mockReturnValue(false),
+    runEmbeddedPiAgent: vi.fn(),
+    queueEmbeddedPiMessage: vi.fn().mockReturnValue(false),
+    resolveEmbeddedSessionLane: (key) => `session:${key.trim() || "main"}`,
+    isEmbeddedPiRunActive: vi.fn().mockReturnValue(false),
+    isEmbeddedPiRunStreaming: vi.fn().mockReturnValue(false),
+}));
+vi.mock("../agents/model-catalog.js", () => ({
+    loadModelCatalog: vi.fn(),
+}));

package/dist/browser/bridge-auth-registry.js

@@ -0,0 +1,26 @@
+// In-process registry for loopback-only bridge servers that require auth, but
+// are addressed via dynamic ephemeral ports (e.g. sandbox browser bridge).
+const authByPort = new Map();
+export function setBridgeAuthForPort(port, auth) {
+    if (!Number.isFinite(port) || port <= 0) {
+        return;
+    }
+    const token = typeof auth.token === "string" ? auth.token.trim() : "";
+    const password = typeof auth.password === "string" ? auth.password.trim() : "";
+    authByPort.set(port, {
+        token: token || undefined,
+        password: password || undefined,
+    });
+}
+export function getBridgeAuthForPort(port) {
+    if (!Number.isFinite(port) || port <= 0) {
+        return undefined;
+    }
+    return authByPort.get(port);
+}
+export function deleteBridgeAuthForPort(port) {
+    if (!Number.isFinite(port) || port <= 0) {
+        return;
+    }
+    authByPort.delete(port);
+}

package/dist/browser/client-actions-url.js

@@ -0,0 +1,10 @@
+export function buildProfileQuery(profile) {
+    return profile ? `?profile=${encodeURIComponent(profile)}` : "";
+}
+export function withBaseUrl(baseUrl, path) {
+    const trimmed = baseUrl?.trim();
+    if (!trimmed) {
+        return path;
+    }
+    return `${trimmed.replace(/\/$/, "")}${path}`;
+}

package/dist/browser/control-auth.js

@@ -0,0 +1,73 @@
+import crypto from "node:crypto";
+import { loadConfig, writeConfigFile } from "../config/config.js";
+import { resolveGatewayAuth } from "../gateway/auth.js";
+export function resolveBrowserControlAuth(cfg, env = process.env) {
+    const auth = resolveGatewayAuth({
+        authConfig: cfg?.gateway?.auth,
+        env,
+        tailscaleMode: cfg?.gateway?.tailscale?.mode,
+    });
+    const token = typeof auth.token === "string" ? auth.token.trim() : "";
+    const password = typeof auth.password === "string" ? auth.password.trim() : "";
+    return {
+        token: token || undefined,
+        password: password || undefined,
+    };
+}
+function shouldAutoGenerateBrowserAuth(env) {
+    const nodeEnv = (env.NODE_ENV ?? "").trim().toLowerCase();
+    if (nodeEnv === "test") {
+        return false;
+    }
+    const vitest = (env.VITEST ?? "").trim().toLowerCase();
+    if (vitest && vitest !== "0" && vitest !== "false" && vitest !== "off") {
+        return false;
+    }
+    return true;
+}
+export async function ensureBrowserControlAuth(params) {
+    const env = params.env ?? process.env;
+    const auth = resolveBrowserControlAuth(params.cfg, env);
+    if (auth.token || auth.password) {
+        return { auth };
+    }
+    if (!shouldAutoGenerateBrowserAuth(env)) {
+        return { auth };
+    }
+    // Respect explicit password mode even if currently unset.
+    if (params.cfg.gateway?.auth?.mode === "password") {
+        return { auth };
+    }
+    if (params.cfg.gateway?.auth?.mode === "trusted-proxy") {
+        return { auth };
+    }
+    // Re-read latest config to avoid racing with concurrent config writers.
+    const latestCfg = loadConfig();
+    const latestAuth = resolveBrowserControlAuth(latestCfg, env);
+    if (latestAuth.token || latestAuth.password) {
+        return { auth: latestAuth };
+    }
+    if (latestCfg.gateway?.auth?.mode === "password") {
+        return { auth: latestAuth };
+    }
+    if (latestCfg.gateway?.auth?.mode === "trusted-proxy") {
+        return { auth: latestAuth };
+    }
+    const generatedToken = crypto.randomBytes(24).toString("hex");
+    const nextCfg = {
+        ...latestCfg,
+        gateway: {
+            ...latestCfg.gateway,
+            auth: {
+                ...latestCfg.gateway?.auth,
+                mode: "token",
+                token: generatedToken,
+            },
+        },
+    };
+    await writeConfigFile(nextCfg);
+    return {
+        auth: { token: generatedToken },
+        generatedToken,
+    };
+}

package/dist/browser/csrf.js

@@ -0,0 +1,64 @@
+import { isLoopbackHost } from "../gateway/net.js";
+function firstHeader(value) {
+    return Array.isArray(value) ? (value[0] ?? "") : (value ?? "");
+}
+function isMutatingMethod(method) {
+    const m = (method || "").trim().toUpperCase();
+    return m === "POST" || m === "PUT" || m === "PATCH" || m === "DELETE";
+}
+function isLoopbackUrl(value) {
+    const v = value.trim();
+    if (!v || v === "null") {
+        return false;
+    }
+    try {
+        const parsed = new URL(v);
+        return isLoopbackHost(parsed.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+export function shouldRejectBrowserMutation(params) {
+    if (!isMutatingMethod(params.method)) {
+        return false;
+    }
+    // Strong signal when present: browser says this is cross-site.
+    // Avoid being overly clever with "same-site" since localhost vs 127.0.0.1 may differ.
+    const secFetchSite = (params.secFetchSite ?? "").trim().toLowerCase();
+    if (secFetchSite === "cross-site") {
+        return true;
+    }
+    const origin = (params.origin ?? "").trim();
+    if (origin) {
+        return !isLoopbackUrl(origin);
+    }
+    const referer = (params.referer ?? "").trim();
+    if (referer) {
+        return !isLoopbackUrl(referer);
+    }
+    // Non-browser clients (curl/undici/Node) typically send no Origin/Referer.
+    return false;
+}
+export function browserMutationGuardMiddleware() {
+    return (req, res, next) => {
+        // OPTIONS is used for CORS preflight. Even if cross-origin, the preflight isn't mutating.
+        const method = (req.method || "").trim().toUpperCase();
+        if (method === "OPTIONS") {
+            return next();
+        }
+        const origin = firstHeader(req.headers.origin);
+        const referer = firstHeader(req.headers.referer);
+        const secFetchSite = firstHeader(req.headers["sec-fetch-site"]);
+        if (shouldRejectBrowserMutation({
+            method,
+            origin,
+            referer,
+            secFetchSite,
+        })) {
+            res.status(403).send("Forbidden");
+            return;
+        }
+        next();
+    };
+}

package/dist/browser/http-auth.js

@@ -0,0 +1,52 @@
+import { safeEqualSecret } from "../security/secret-equal.js";
+function firstHeaderValue(value) {
+    return Array.isArray(value) ? (value[0] ?? "") : (value ?? "");
+}
+function parseBearerToken(authorization) {
+    if (!authorization || !authorization.toLowerCase().startsWith("bearer ")) {
+        return undefined;
+    }
+    const token = authorization.slice(7).trim();
+    return token || undefined;
+}
+function parseBasicPassword(authorization) {
+    if (!authorization || !authorization.toLowerCase().startsWith("basic ")) {
+        return undefined;
+    }
+    const encoded = authorization.slice(6).trim();
+    if (!encoded) {
+        return undefined;
+    }
+    try {
+        const decoded = Buffer.from(encoded, "base64").toString("utf8");
+        const sep = decoded.indexOf(":");
+        if (sep < 0) {
+            return undefined;
+        }
+        const password = decoded.slice(sep + 1).trim();
+        return password || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isAuthorizedBrowserRequest(req, auth) {
+    const authorization = firstHeaderValue(req.headers.authorization).trim();
+    if (auth.token) {
+        const bearer = parseBearerToken(authorization);
+        if (bearer && safeEqualSecret(bearer, auth.token)) {
+            return true;
+        }
+    }
+    if (auth.password) {
+        const passwordHeader = firstHeaderValue(req.headers["x-openclaw-password"]).trim();
+        if (passwordHeader && safeEqualSecret(passwordHeader, auth.password)) {
+            return true;
+        }
+        const basicPassword = parseBasicPassword(authorization);
+        if (basicPassword && safeEqualSecret(basicPassword, auth.password)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/browser/paths.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { resolvePreferredOpenClawTmpDir } from "../infra/tmp-poolbot-dir.js";
+export const DEFAULT_BROWSER_TMP_DIR = resolvePreferredOpenClawTmpDir();
+export const DEFAULT_TRACE_DIR = DEFAULT_BROWSER_TMP_DIR;
+export const DEFAULT_DOWNLOAD_DIR = path.join(DEFAULT_BROWSER_TMP_DIR, "downloads");
+export const DEFAULT_UPLOAD_DIR = path.join(DEFAULT_BROWSER_TMP_DIR, "uploads");
+export function resolvePathWithinRoot(params) {
+    const root = path.resolve(params.rootDir);
+    const raw = params.requestedPath.trim();
+    if (!raw) {
+        if (!params.defaultFileName) {
+            return { ok: false, error: "path is required" };
+        }
+        return { ok: true, path: path.join(root, params.defaultFileName) };
+    }
+    const resolved = path.resolve(root, raw);
+    const rel = path.relative(root, resolved);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+        return { ok: false, error: `Invalid path: must stay within ${params.scopeLabel}` };
+    }
+    return { ok: true, path: resolved };
+}
+export function resolvePathsWithinRoot(params) {
+    const resolvedPaths = [];
+    for (const raw of params.requestedPaths) {
+        const pathResult = resolvePathWithinRoot({
+            rootDir: params.rootDir,
+            requestedPath: raw,
+            scopeLabel: params.scopeLabel,
+        });
+        if (!pathResult.ok) {
+            return { ok: false, error: pathResult.error };
+        }
+        resolvedPaths.push(pathResult.path);
+    }
+    return { ok: true, paths: resolvedPaths };
+}