@poolzin/pool-bot 2026.2.25 → 2026.2.26

package/dist/channels/status-reactions.js

@@ -0,0 +1,297 @@
+/**
+ * Channel-agnostic status reaction controller.
+ * Provides a unified interface for displaying agent status via message reactions.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+export const DEFAULT_EMOJIS = {
+    queued: "👀",
+    thinking: "🤔",
+    tool: "🔥",
+    coding: "👨‍💻",
+    web: "⚡",
+    done: "👍",
+    error: "😱",
+    stallSoft: "🥱",
+    stallHard: "😨",
+};
+export const DEFAULT_TIMING = {
+    debounceMs: 700,
+    stallSoftMs: 10_000,
+    stallHardMs: 30_000,
+    doneHoldMs: 1500,
+    errorHoldMs: 2500,
+};
+export const CODING_TOOL_TOKENS = [
+    "exec",
+    "process",
+    "read",
+    "write",
+    "edit",
+    "session_status",
+    "bash",
+];
+export const WEB_TOOL_TOKENS = [
+    "web_search",
+    "web-search",
+    "web_fetch",
+    "web-fetch",
+    "browser",
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Resolve the appropriate emoji for a tool invocation.
+ */
+export function resolveToolEmoji(toolName, emojis) {
+    const normalized = toolName?.trim().toLowerCase() ?? "";
+    if (!normalized) {
+        return emojis.tool;
+    }
+    if (WEB_TOOL_TOKENS.some((token) => normalized.includes(token))) {
+        return emojis.web;
+    }
+    if (CODING_TOOL_TOKENS.some((token) => normalized.includes(token))) {
+        return emojis.coding;
+    }
+    return emojis.tool;
+}
+/**
+ * Create a status reaction controller.
+ *
+ * Features:
+ * - Promise chain serialization (prevents concurrent API calls)
+ * - Debouncing (intermediate states debounce, terminal states are immediate)
+ * - Stall timers (soft/hard warnings on inactivity)
+ * - Terminal state protection (done/error mark finished, subsequent updates ignored)
+ */
+export function createStatusReactionController(params) {
+    const { enabled, adapter, initialEmoji, onError } = params;
+    // Merge user-provided overrides with defaults
+    const emojis = {
+        ...DEFAULT_EMOJIS,
+        queued: params.emojis?.queued ?? initialEmoji,
+        ...params.emojis,
+    };
+    const timing = {
+        ...DEFAULT_TIMING,
+        ...params.timing,
+    };
+    // State
+    let currentEmoji = "";
+    let pendingEmoji = "";
+    let debounceTimer = null;
+    let stallSoftTimer = null;
+    let stallHardTimer = null;
+    let finished = false;
+    let chainPromise = Promise.resolve();
+    // Known emojis for clear operation
+    const knownEmojis = new Set([
+        initialEmoji,
+        emojis.queued,
+        emojis.thinking,
+        emojis.tool,
+        emojis.coding,
+        emojis.web,
+        emojis.done,
+        emojis.error,
+        emojis.stallSoft,
+        emojis.stallHard,
+    ]);
+    /**
+     * Serialize async operations to prevent race conditions.
+     */
+    function enqueue(fn) {
+        chainPromise = chainPromise.then(fn, fn);
+        return chainPromise;
+    }
+    /**
+     * Clear all timers.
+     */
+    function clearAllTimers() {
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+            debounceTimer = null;
+        }
+        if (stallSoftTimer) {
+            clearTimeout(stallSoftTimer);
+            stallSoftTimer = null;
+        }
+        if (stallHardTimer) {
+            clearTimeout(stallHardTimer);
+            stallHardTimer = null;
+        }
+    }
+    /**
+     * Clear debounce timer only (used during phase transitions).
+     */
+    function clearDebounceTimer() {
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+            debounceTimer = null;
+        }
+    }
+    /**
+     * Reset stall timers (called on each phase change).
+     */
+    function resetStallTimers() {
+        if (stallSoftTimer) {
+            clearTimeout(stallSoftTimer);
+        }
+        if (stallHardTimer) {
+            clearTimeout(stallHardTimer);
+        }
+        stallSoftTimer = setTimeout(() => {
+            scheduleEmoji(emojis.stallSoft, { immediate: true, skipStallReset: true });
+        }, timing.stallSoftMs);
+        stallHardTimer = setTimeout(() => {
+            scheduleEmoji(emojis.stallHard, { immediate: true, skipStallReset: true });
+        }, timing.stallHardMs);
+    }
+    /**
+     * Apply an emoji: set new reaction and optionally remove old one.
+     */
+    async function applyEmoji(newEmoji) {
+        if (!enabled) {
+            return;
+        }
+        try {
+            const previousEmoji = currentEmoji;
+            await adapter.setReaction(newEmoji);
+            // If adapter supports removeReaction and there's a different previous emoji, remove it
+            if (adapter.removeReaction && previousEmoji && previousEmoji !== newEmoji) {
+                await adapter.removeReaction(previousEmoji);
+            }
+            currentEmoji = newEmoji;
+        }
+        catch (err) {
+            if (onError) {
+                onError(err);
+            }
+        }
+    }
+    /**
+     * Schedule an emoji change (debounced or immediate).
+     */
+    function scheduleEmoji(emoji, options = {}) {
+        if (!enabled || finished) {
+            return;
+        }
+        // Deduplicate: if already scheduled/current, skip send but keep stall timers fresh
+        if (emoji === currentEmoji || emoji === pendingEmoji) {
+            if (!options.skipStallReset) {
+                resetStallTimers();
+            }
+            return;
+        }
+        pendingEmoji = emoji;
+        clearDebounceTimer();
+        if (options.immediate) {
+            // Immediate execution for terminal states
+            void enqueue(async () => {
+                await applyEmoji(emoji);
+                pendingEmoji = "";
+            });
+        }
+        else {
+            // Debounced execution for intermediate states
+            debounceTimer = setTimeout(() => {
+                void enqueue(async () => {
+                    await applyEmoji(emoji);
+                    pendingEmoji = "";
+                });
+            }, timing.debounceMs);
+        }
+        // Reset stall timers on phase change (unless triggered by stall timer itself)
+        if (!options.skipStallReset) {
+            resetStallTimers();
+        }
+    }
+    // ───────────────────────────────────────────────────────────────────────────
+    // Controller API
+    // ───────────────────────────────────────────────────────────────────────────
+    function setQueued() {
+        scheduleEmoji(emojis.queued, { immediate: true });
+    }
+    function setThinking() {
+        scheduleEmoji(emojis.thinking);
+    }
+    function setTool(toolName) {
+        const emoji = resolveToolEmoji(toolName, emojis);
+        scheduleEmoji(emoji);
+    }
+    function setDone() {
+        if (!enabled) {
+            return Promise.resolve();
+        }
+        finished = true;
+        clearAllTimers();
+        // Directly enqueue to ensure we return the updated promise
+        return enqueue(async () => {
+            await applyEmoji(emojis.done);
+            pendingEmoji = "";
+        });
+    }
+    function setError() {
+        if (!enabled) {
+            return Promise.resolve();
+        }
+        finished = true;
+        clearAllTimers();
+        // Directly enqueue to ensure we return the updated promise
+        return enqueue(async () => {
+            await applyEmoji(emojis.error);
+            pendingEmoji = "";
+        });
+    }
+    async function clear() {
+        if (!enabled) {
+            return;
+        }
+        clearAllTimers();
+        finished = true;
+        await enqueue(async () => {
+            if (adapter.removeReaction) {
+                // Remove all known emojis (Discord-style)
+                const emojisToRemove = Array.from(knownEmojis);
+                for (const emoji of emojisToRemove) {
+                    try {
+                        await adapter.removeReaction(emoji);
+                    }
+                    catch (err) {
+                        if (onError) {
+                            onError(err);
+                        }
+                    }
+                }
+            }
+            else {
+                // For platforms without removeReaction, set empty or just skip
+                // (Telegram handles this atomically on the next setReaction)
+            }
+            currentEmoji = "";
+            pendingEmoji = "";
+        });
+    }
+    async function restoreInitial() {
+        if (!enabled) {
+            return;
+        }
+        clearAllTimers();
+        await enqueue(async () => {
+            await applyEmoji(initialEmoji);
+            pendingEmoji = "";
+        });
+    }
+    return {
+        setQueued,
+        setThinking,
+        setTool,
+        setDone,
+        setError,
+        clear,
+        restoreInitial,
+    };
+}

package/dist/cli/banner.js

@@ -25,7 +25,7 @@ export function formatCliBannerLine(version, options = {}) {
     const commitLabel = commit ?? "unknown";
     const tagline = pickTagline(options);
     const rich = options.richTty ?? isRich();
-    const cliName = resolveCliName(options.argv ?? process.argv, options.env);
+    const cliName = resolveCliName(options.argv ?? process.argv);
     const title = cliName === "poolbot" ? "🎱 Pool Bot" : "🎱 Pool Bot";
     const prefix = "🎱 ";
     const columns = options.columns ?? process.stdout.columns ?? 120;

package/dist/cli/browser-cli-actions-input/register.files-downloads.js

@@ -1,13 +1,55 @@
+import { DEFAULT_UPLOAD_DIR, resolveExistingPathsWithinRoot } from "../../browser/paths.js";
 import { danger } from "../../globals.js";
 import { defaultRuntime } from "../../runtime.js";
+import { shortenHomePath } from "../../utils.js";
 import { callBrowserRequest } from "../browser-cli-shared.js";
 import { resolveBrowserActionContext } from "./shared.js";
-import { shortenHomePath } from "../../utils.js";
+async function normalizeUploadPaths(paths) {
+    const result = await resolveExistingPathsWithinRoot({
+        rootDir: DEFAULT_UPLOAD_DIR,
+        requestedPaths: paths,
+        scopeLabel: `uploads directory (${DEFAULT_UPLOAD_DIR})`,
+    });
+    if (!result.ok) {
+        throw new Error(result.error);
+    }
+    return result.paths;
+}
 export function registerBrowserFilesAndDownloadsCommands(browser, parentOpts) {
+    const resolveTimeoutAndTarget = (opts) => {
+        const timeoutMs = Number.isFinite(opts.timeoutMs) ? Number(opts.timeoutMs) : undefined;
+        const targetId = typeof opts.targetId === "string" ? opts.targetId.trim() || undefined : undefined;
+        return { timeoutMs, targetId };
+    };
+    const runDownloadCommand = async (cmd, opts, request) => {
+        const { parent, profile } = resolveBrowserActionContext(cmd, parentOpts);
+        try {
+            const { timeoutMs, targetId } = resolveTimeoutAndTarget(opts);
+            const result = await callBrowserRequest(parent, {
+                method: "POST",
+                path: request.path,
+                query: profile ? { profile } : undefined,
+                body: {
+                    ...request.body,
+                    targetId,
+                    timeoutMs,
+                },
+            }, { timeoutMs: timeoutMs ?? 20000 });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`downloaded: ${shortenHomePath(result.download.path)}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    };
     browser
         .command("upload")
         .description("Arm file upload for the next file chooser")
-        .argument("<paths...>", "File paths to upload")
+        .argument("<paths...>", "File paths to upload (must be within Pool Bot temp uploads dir, e.g. /tmp/poolbot/uploads/file.pdf)")
         .option("--ref <ref>", "Ref id from snapshot to click after arming")
         .option("--input-ref <ref>", "Ref id for <input type=file> to set directly")
         .option("--element <selector>", "CSS selector for <input type=file>")
@@ -16,17 +58,18 @@ export function registerBrowserFilesAndDownloadsCommands(browser, parentOpts) {
         .action(async (paths, opts, cmd) => {
         const { parent, profile } = resolveBrowserActionContext(cmd, parentOpts);
         try {
-            const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : undefined;
+            const normalizedPaths = await normalizeUploadPaths(paths);
+            const { timeoutMs, targetId } = resolveTimeoutAndTarget(opts);
             const result = await callBrowserRequest(parent, {
                 method: "POST",
                 path: "/hooks/file-chooser",
                 query: profile ? { profile } : undefined,
                 body: {
-                    paths,
+                    paths: normalizedPaths,
                     ref: opts.ref?.trim() || undefined,
                     inputRef: opts.inputRef?.trim() || undefined,
                     element: opts.element?.trim() || undefined,
-                    targetId: opts.targetId?.trim() || undefined,
+                    targetId,
                     timeoutMs,
                 },
             }, { timeoutMs: timeoutMs ?? 20000 });
@@ -44,66 +87,32 @@ export function registerBrowserFilesAndDownloadsCommands(browser, parentOpts) {
     browser
         .command("waitfordownload")
         .description("Wait for the next download (and save it)")
-        .argument("[path]", "Save path (default: /tmp/poolbot/downloads/...)")
+        .argument("[path]", "Save path within poolbot temp downloads dir (default: /tmp/poolbot/downloads/...; fallback: os.tmpdir()/poolbot/downloads/...)")
         .option("--target-id <id>", "CDP target id (or unique prefix)")
         .option("--timeout-ms <ms>", "How long to wait for the next download (default: 120000)", (v) => Number(v))
         .action(async (outPath, opts, cmd) => {
-        const { parent, profile } = resolveBrowserActionContext(cmd, parentOpts);
-        try {
-            const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : undefined;
-            const result = await callBrowserRequest(parent, {
-                method: "POST",
-                path: "/wait/download",
-                query: profile ? { profile } : undefined,
-                body: {
-                    path: outPath?.trim() || undefined,
-                    targetId: opts.targetId?.trim() || undefined,
-                    timeoutMs,
-                },
-            }, { timeoutMs: timeoutMs ?? 20000 });
-            if (parent?.json) {
-                defaultRuntime.log(JSON.stringify(result, null, 2));
-                return;
-            }
-            defaultRuntime.log(`downloaded: ${shortenHomePath(result.download.path)}`);
-        }
-        catch (err) {
-            defaultRuntime.error(danger(String(err)));
-            defaultRuntime.exit(1);
-        }
+        await runDownloadCommand(cmd, opts, {
+            path: "/wait/download",
+            body: {
+                path: outPath?.trim() || undefined,
+            },
+        });
     });
     browser
         .command("download")
         .description("Click a ref and save the resulting download")
         .argument("<ref>", "Ref id from snapshot to click")
-        .argument("<path>", "Save path")
+        .argument("<path>", "Save path within poolbot temp downloads dir (e.g. report.pdf or /tmp/poolbot/downloads/report.pdf)")
         .option("--target-id <id>", "CDP target id (or unique prefix)")
         .option("--timeout-ms <ms>", "How long to wait for the download to start (default: 120000)", (v) => Number(v))
         .action(async (ref, outPath, opts, cmd) => {
-        const { parent, profile } = resolveBrowserActionContext(cmd, parentOpts);
-        try {
-            const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : undefined;
-            const result = await callBrowserRequest(parent, {
-                method: "POST",
-                path: "/download",
-                query: profile ? { profile } : undefined,
-                body: {
-                    ref,
-                    path: outPath,
-                    targetId: opts.targetId?.trim() || undefined,
-                    timeoutMs,
-                },
-            }, { timeoutMs: timeoutMs ?? 20000 });
-            if (parent?.json) {
-                defaultRuntime.log(JSON.stringify(result, null, 2));
-                return;
-            }
-            defaultRuntime.log(`downloaded: ${shortenHomePath(result.download.path)}`);
-        }
-        catch (err) {
-            defaultRuntime.error(danger(String(err)));
-            defaultRuntime.exit(1);
-        }
+        await runDownloadCommand(cmd, opts, {
+            path: "/download",
+            body: {
+                ref,
+                path: outPath,
+            },
+        });
     });
     browser
         .command("dialog")
@@ -122,7 +131,7 @@ export function registerBrowserFilesAndDownloadsCommands(browser, parentOpts) {
             return;
         }
         try {
-            const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : undefined;
+            const { timeoutMs, targetId } = resolveTimeoutAndTarget(opts);
             const result = await callBrowserRequest(parent, {
                 method: "POST",
                 path: "/hooks/dialog",
@@ -130,7 +139,7 @@ export function registerBrowserFilesAndDownloadsCommands(browser, parentOpts) {
                 body: {
                     accept,
                     promptText: opts.prompt?.trim() || undefined,
-                    targetId: opts.targetId?.trim() || undefined,
+                    targetId,
                     timeoutMs,
                 },
             }, { timeoutMs: timeoutMs ?? 20000 });

package/dist/cli/cli-name.js

@@ -1,25 +1,25 @@
 import path from "node:path";
 export const DEFAULT_CLI_NAME = "poolbot";
-export const LEGACY_CLI_NAME = "poolbot";
-const KNOWN_CLI_NAMES = new Set([DEFAULT_CLI_NAME, LEGACY_CLI_NAME]);
-const CLI_PREFIX_RE = /^(?:((?:pnpm|npm|bunx|npx)\s+))?(poolbot|poolbot)\b/;
-export function resolveCliName(argv = process.argv, env = process.env) {
-    const override = env.POOLBOT_CLI_NAME?.trim() || env.MOLTBOT_CLI_NAME?.trim() || env.CLAWDBOT_CLI_NAME?.trim();
-    if (override)
-        return override;
+const KNOWN_CLI_NAMES = new Set([DEFAULT_CLI_NAME]);
+const CLI_PREFIX_RE = /^(?:((?:pnpm|npm|bunx|npx)\s+))?(poolbot)\b/;
+export function resolveCliName(argv = process.argv) {
     const argv1 = argv[1];
-    if (!argv1)
+    if (!argv1) {
         return DEFAULT_CLI_NAME;
+    }
     const base = path.basename(argv1).trim();
-    if (KNOWN_CLI_NAMES.has(base))
+    if (KNOWN_CLI_NAMES.has(base)) {
         return base;
+    }
     return DEFAULT_CLI_NAME;
 }
 export function replaceCliName(command, cliName = resolveCliName()) {
-    if (!command.trim())
+    if (!command.trim()) {
         return command;
-    if (!CLI_PREFIX_RE.test(command))
+    }
+    if (!CLI_PREFIX_RE.test(command)) {
         return command;
+    }
     return command.replace(CLI_PREFIX_RE, (_match, runner) => {
         return `${runner ?? ""}${cliName}`;
     });

package/dist/cli/cli-utils.js

@@ -1,6 +1,5 @@
-export function formatErrorMessage(err) {
-    return err instanceof Error ? err.message : String(err);
-}
+import { formatErrorMessage } from "../infra/errors.js";
+export { formatErrorMessage };
 export async function withManager(params) {
     const { manager, error } = await params.getManager();
     if (!manager) {
@@ -32,3 +31,14 @@ export async function runCommandWithRuntime(runtime, action, onError) {
         runtime.exit(1);
     }
 }
+export function resolveOptionFromCommand(command, key) {
+    let current = command;
+    while (current) {
+        const opts = current.opts?.() ?? {};
+        if (opts[key] !== undefined) {
+            return opts[key];
+        }
+        current = current.parent ?? undefined;
+    }
+    return undefined;
+}

package/dist/cli/command-format.js

@@ -4,7 +4,7 @@ const CLI_PREFIX_RE = /^(?:pnpm|npm|bunx|npx)\s+(?:poolbot|poolbot)\b|^(?:poolbo
 const PROFILE_FLAG_RE = /(?:^|\s)--profile(?:\s|=|$)/;
 const DEV_FLAG_RE = /(?:^|\s)--dev(?:\s|$)/;
 export function formatCliCommand(command, env = process.env) {
-    const cliName = resolveCliName(undefined, env);
+    const cliName = resolveCliName();
     const normalizedCommand = replaceCliName(command, cliName);
     const profile = normalizeProfileName(env.POOLBOT_PROFILE || env.CLAWDBOT_PROFILE);
     if (!profile)

package/dist/cli/config-cli.js

@@ -234,7 +234,7 @@ export async function runConfigUnset(opts) {
             runtime.exit(1);
             return;
         }
-        await writeConfigFile(next);
+        await writeConfigFile(next, { unsetPaths: [parsedPath] });
         runtime.log(info(`Removed ${opts.path}. Restart the gateway to apply.`));
     }
     catch (err) {

package/dist/cli/daemon-cli/lifecycle-core.js

@@ -51,6 +51,15 @@ async function handleServiceNotLoaded(params) {
         }
     }
 }
+async function resolveServiceLoadedOrFail(params) {
+    try {
+        return await params.service.isLoaded({ env: process.env });
+    }
+    catch (err) {
+        params.fail(`${params.serviceNoun} service check failed: ${String(err)}`);
+        return null;
+    }
+}
 export async function runServiceUninstall(params) {
     const json = Boolean(params.opts?.json);
     const { stdout, emit, fail } = createActionIO({ action: "uninstall", json });
@@ -100,12 +109,12 @@ export async function runServiceUninstall(params) {
 export async function runServiceStart(params) {
     const json = Boolean(params.opts?.json);
     const { stdout, emit, fail } = createActionIO({ action: "start", json });
-    let loaded = false;
-    try {
-        loaded = await params.service.isLoaded({ env: process.env });
-    }
-    catch (err) {
-        fail(`${params.serviceNoun} service check failed: ${String(err)}`);
+    const loaded = await resolveServiceLoadedOrFail({
+        serviceNoun: params.serviceNoun,
+        service: params.service,
+        fail,
+    });
+    if (loaded === null) {
         return;
     }
     if (!loaded) {
@@ -143,12 +152,12 @@ export async function runServiceStart(params) {
 export async function runServiceStop(params) {
     const json = Boolean(params.opts?.json);
     const { stdout, emit, fail } = createActionIO({ action: "stop", json });
-    let loaded = false;
-    try {
-        loaded = await params.service.isLoaded({ env: process.env });
-    }
-    catch (err) {
-        fail(`${params.serviceNoun} service check failed: ${String(err)}`);
+    const loaded = await resolveServiceLoadedOrFail({
+        serviceNoun: params.serviceNoun,
+        service: params.service,
+        fail,
+    });
+    if (loaded === null) {
         return;
     }
     if (!loaded) {
@@ -186,12 +195,12 @@ export async function runServiceStop(params) {
 export async function runServiceRestart(params) {
     const json = Boolean(params.opts?.json);
     const { stdout, emit, fail } = createActionIO({ action: "restart", json });
-    let loaded = false;
-    try {
-        loaded = await params.service.isLoaded({ env: process.env });
-    }
-    catch (err) {
-        fail(`${params.serviceNoun} service check failed: ${String(err)}`);
+    const loaded = await resolveServiceLoadedOrFail({
+        serviceNoun: params.serviceNoun,
+        service: params.service,
+        fail,
+    });
+    if (loaded === null) {
         return false;
     }
     if (!loaded) {
@@ -222,7 +231,7 @@ export async function runServiceRestart(params) {
                     : driftIssue.message;
                 warnings.push(warning);
                 if (!json) {
-                    defaultRuntime.log(`\n⚠️  ${driftIssue.message}`);
+                    defaultRuntime.log(`\n\u26a0\ufe0f  ${driftIssue.message}`);
                     if (driftIssue.detail) {
                         defaultRuntime.log(`   ${driftIssue.detail}\n`);
                     }
@@ -235,6 +244,9 @@ export async function runServiceRestart(params) {
     }
     try {
         await params.service.restart({ env: process.env, stdout });
+        if (params.postRestartCheck) {
+            await params.postRestartCheck({ json, stdout, warnings, fail });
+        }
         let restarted = true;
         try {
             restarted = await params.service.isLoaded({ env: process.env });