@poolzin/pool-bot 2026.2.17 → 2026.2.19

package/dist/infra/outbound/message-action-params.js

@@ -0,0 +1,307 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertMediaNotDataUrl, resolveSandboxedMediaSource } from "../../agents/sandbox-paths.js";
+import { readStringParam } from "../../agents/tools/common.js";
+import { extensionForMime } from "../../media/mime.js";
+import { parseSlackTarget } from "../../slack/targets.js";
+import { parseTelegramTarget } from "../../telegram/targets.js";
+import { loadWebMedia } from "../../web/media.js";
+export function readBooleanParam(params, key) {
+    const raw = params[key];
+    if (typeof raw === "boolean") {
+        return raw;
+    }
+    if (typeof raw === "string") {
+        const trimmed = raw.trim().toLowerCase();
+        if (trimmed === "true") {
+            return true;
+        }
+        if (trimmed === "false") {
+            return false;
+        }
+    }
+    return undefined;
+}
+export function resolveSlackAutoThreadId(params) {
+    const context = params.toolContext;
+    if (!context?.currentThreadTs || !context.currentChannelId) {
+        return undefined;
+    }
+    // Only mirror auto-threading when Slack would reply in the active thread for this channel.
+    if (context.replyToMode !== "all" && context.replyToMode !== "first") {
+        return undefined;
+    }
+    const parsedTarget = parseSlackTarget(params.to, { defaultKind: "channel" });
+    if (!parsedTarget || parsedTarget.kind !== "channel") {
+        return undefined;
+    }
+    if (parsedTarget.id.toLowerCase() !== context.currentChannelId.toLowerCase()) {
+        return undefined;
+    }
+    if (context.replyToMode === "first" && context.hasRepliedRef?.value) {
+        return undefined;
+    }
+    return context.currentThreadTs;
+}
+/**
+ * Auto-inject Telegram forum topic thread ID when the message tool targets
+ * the same chat the session originated from.  Mirrors the Slack auto-threading
+ * pattern so media, buttons, and other tool-sent messages land in the correct
+ * topic instead of the General Topic.
+ *
+ * Unlike Slack, we do not gate on `replyToMode` here: Telegram forum topics
+ * are persistent sub-channels (not ephemeral reply threads), so auto-injection
+ * should always apply when the target chat matches.
+ */
+export function resolveTelegramAutoThreadId(params) {
+    const context = params.toolContext;
+    if (!context?.currentThreadTs || !context.currentChannelId) {
+        return undefined;
+    }
+    // Use parseTelegramTarget to extract canonical chatId from both sides,
+    // mirroring how Slack uses parseSlackTarget. This handles format variations
+    // like `telegram:group:123:topic:456` vs `telegram:123`.
+    const parsedTo = parseTelegramTarget(params.to);
+    const parsedChannel = parseTelegramTarget(context.currentChannelId);
+    if (parsedTo.chatId.toLowerCase() !== parsedChannel.chatId.toLowerCase()) {
+        return undefined;
+    }
+    return context.currentThreadTs;
+}
+function resolveAttachmentMaxBytes(params) {
+    const accountId = typeof params.accountId === "string" ? params.accountId.trim() : "";
+    const channelCfg = params.cfg.channels?.[params.channel];
+    const channelObj = channelCfg && typeof channelCfg === "object"
+        ? channelCfg
+        : undefined;
+    const channelMediaMax = typeof channelObj?.mediaMaxMb === "number" ? channelObj.mediaMaxMb : undefined;
+    const accountsObj = channelObj?.accounts && typeof channelObj.accounts === "object"
+        ? channelObj.accounts
+        : undefined;
+    const accountCfg = accountId && accountsObj ? accountsObj[accountId] : undefined;
+    const accountMediaMax = accountCfg && typeof accountCfg === "object"
+        ? accountCfg.mediaMaxMb
+        : undefined;
+    // Priority: account-specific > channel-level > global default
+    const limitMb = (typeof accountMediaMax === "number" ? accountMediaMax : undefined) ??
+        channelMediaMax ??
+        params.cfg.agents?.defaults?.mediaMaxMb;
+    return typeof limitMb === "number" ? limitMb * 1024 * 1024 : undefined;
+}
+function inferAttachmentFilename(params) {
+    const mediaHint = params.mediaHint?.trim();
+    if (mediaHint) {
+        try {
+            if (mediaHint.startsWith("file://")) {
+                const filePath = fileURLToPath(mediaHint);
+                const base = path.basename(filePath);
+                if (base) {
+                    return base;
+                }
+            }
+            else if (/^https?:\/\//i.test(mediaHint)) {
+                const url = new URL(mediaHint);
+                const base = path.basename(url.pathname);
+                if (base) {
+                    return base;
+                }
+            }
+            else {
+                const base = path.basename(mediaHint);
+                if (base) {
+                    return base;
+                }
+            }
+        }
+        catch {
+            // fall through to content-type based default
+        }
+    }
+    const ext = params.contentType ? extensionForMime(params.contentType) : undefined;
+    return ext ? `attachment${ext}` : "attachment";
+}
+function normalizeBase64Payload(params) {
+    if (!params.base64) {
+        return { base64: params.base64, contentType: params.contentType };
+    }
+    const match = /^data:([^;]+);base64,(.*)$/i.exec(params.base64.trim());
+    if (!match) {
+        return { base64: params.base64, contentType: params.contentType };
+    }
+    const [, mime, payload] = match;
+    return {
+        base64: payload,
+        contentType: params.contentType ?? mime,
+    };
+}
+async function hydrateAttachmentPayload(params) {
+    const contentTypeParam = params.contentTypeParam ?? undefined;
+    const rawBuffer = readStringParam(params.args, "buffer", { trim: false });
+    const normalized = normalizeBase64Payload({
+        base64: rawBuffer,
+        contentType: contentTypeParam ?? undefined,
+    });
+    if (normalized.base64 !== rawBuffer && normalized.base64) {
+        params.args.buffer = normalized.base64;
+        if (normalized.contentType && !contentTypeParam) {
+            params.args.contentType = normalized.contentType;
+        }
+    }
+    const filename = readStringParam(params.args, "filename");
+    const mediaSource = (params.mediaHint ?? undefined) || (params.fileHint ?? undefined);
+    if (!params.dryRun && !readStringParam(params.args, "buffer", { trim: false }) && mediaSource) {
+        const maxBytes = resolveAttachmentMaxBytes({
+            cfg: params.cfg,
+            channel: params.channel,
+            accountId: params.accountId,
+        });
+        // mediaSource already validated by normalizeSandboxMediaList; allow bypass but force explicit readFile.
+        const media = await loadWebMedia(mediaSource, {
+            maxBytes,
+            sandboxValidated: true,
+            readFile: (filePath) => fs.readFile(filePath),
+        });
+        params.args.buffer = media.buffer.toString("base64");
+        if (!contentTypeParam && media.contentType) {
+            params.args.contentType = media.contentType;
+        }
+        if (!filename) {
+            params.args.filename = inferAttachmentFilename({
+                mediaHint: media.fileName ?? mediaSource,
+                contentType: media.contentType ?? contentTypeParam ?? undefined,
+            });
+        }
+    }
+    else if (!filename) {
+        params.args.filename = inferAttachmentFilename({
+            mediaHint: mediaSource,
+            contentType: contentTypeParam ?? undefined,
+        });
+    }
+}
+export async function normalizeSandboxMediaParams(params) {
+    const sandboxRoot = params.sandboxRoot?.trim();
+    const mediaKeys = ["media", "path", "filePath"];
+    for (const key of mediaKeys) {
+        const raw = readStringParam(params.args, key, { trim: false });
+        if (!raw) {
+            continue;
+        }
+        assertMediaNotDataUrl(raw);
+        if (!sandboxRoot) {
+            continue;
+        }
+        const normalized = await resolveSandboxedMediaSource({ media: raw, sandboxRoot });
+        if (normalized !== raw) {
+            params.args[key] = normalized;
+        }
+    }
+}
+export async function normalizeSandboxMediaList(params) {
+    const sandboxRoot = params.sandboxRoot?.trim();
+    const normalized = [];
+    const seen = new Set();
+    for (const value of params.values) {
+        const raw = value?.trim();
+        if (!raw) {
+            continue;
+        }
+        assertMediaNotDataUrl(raw);
+        const resolved = sandboxRoot
+            ? await resolveSandboxedMediaSource({ media: raw, sandboxRoot })
+            : raw;
+        if (seen.has(resolved)) {
+            continue;
+        }
+        seen.add(resolved);
+        normalized.push(resolved);
+    }
+    return normalized;
+}
+async function hydrateAttachmentActionPayload(params) {
+    const mediaHint = readStringParam(params.args, "media", { trim: false });
+    const fileHint = readStringParam(params.args, "path", { trim: false }) ??
+        readStringParam(params.args, "filePath", { trim: false });
+    const contentTypeParam = readStringParam(params.args, "contentType") ?? readStringParam(params.args, "mimeType");
+    if (params.allowMessageCaptionFallback) {
+        const caption = readStringParam(params.args, "caption", { allowEmpty: true })?.trim();
+        const message = readStringParam(params.args, "message", { allowEmpty: true })?.trim();
+        if (!caption && message) {
+            params.args.caption = message;
+        }
+    }
+    await hydrateAttachmentPayload({
+        cfg: params.cfg,
+        channel: params.channel,
+        accountId: params.accountId,
+        args: params.args,
+        dryRun: params.dryRun,
+        contentTypeParam,
+        mediaHint,
+        fileHint,
+    });
+}
+export async function hydrateSetGroupIconParams(params) {
+    if (params.action !== "setGroupIcon") {
+        return;
+    }
+    await hydrateAttachmentActionPayload(params);
+}
+export async function hydrateSendAttachmentParams(params) {
+    if (params.action !== "sendAttachment") {
+        return;
+    }
+    await hydrateAttachmentActionPayload({ ...params, allowMessageCaptionFallback: true });
+}
+export function parseButtonsParam(params) {
+    const raw = params.buttons;
+    if (typeof raw !== "string") {
+        return;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        delete params.buttons;
+        return;
+    }
+    try {
+        params.buttons = JSON.parse(trimmed);
+    }
+    catch {
+        throw new Error("--buttons must be valid JSON");
+    }
+}
+export function parseCardParam(params) {
+    const raw = params.card;
+    if (typeof raw !== "string") {
+        return;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        delete params.card;
+        return;
+    }
+    try {
+        params.card = JSON.parse(trimmed);
+    }
+    catch {
+        throw new Error("--card must be valid JSON");
+    }
+}
+export function parseComponentsParam(params) {
+    const raw = params.components;
+    if (typeof raw !== "string") {
+        return;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        delete params.components;
+        return;
+    }
+    try {
+        params.components = JSON.parse(trimmed);
+    }
+    catch {
+        throw new Error("--components must be valid JSON");
+    }
+}

package/dist/infra/outbound/tool-payload.js

@@ -0,0 +1,21 @@
+export function extractToolPayload(result) {
+    if (result.details !== undefined) {
+        return result.details;
+    }
+    const textBlock = Array.isArray(result.content)
+        ? result.content.find((block) => block &&
+            typeof block === "object" &&
+            block.type === "text" &&
+            typeof block.text === "string")
+        : undefined;
+    const text = textBlock?.text;
+    if (text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return result.content ?? result;
+}

package/dist/infra/package-json.js

@@ -0,0 +1,23 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function readPackageVersion(root) {
+    try {
+        const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed?.version === "string" ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readPackageName(root) {
+    try {
+        const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        const name = parsed?.name?.trim();
+        return name ? name : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/infra/pairing-files.js

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+export { createAsyncLock, readJsonFile, writeJsonAtomic } from "./json-files.js";
+export function resolvePairingPaths(baseDir, subdir) {
+    const root = baseDir ?? resolveStateDir();
+    const dir = path.join(root, subdir);
+    return {
+        dir,
+        pendingPath: path.join(dir, "pending.json"),
+        pairedPath: path.join(dir, "paired.json"),
+    };
+}
+export function pruneExpiredPending(pendingById, nowMs, ttlMs) {
+    for (const [id, req] of Object.entries(pendingById)) {
+        if (nowMs - req.ts > ttlMs) {
+            delete pendingById[id];
+        }
+    }
+}

package/dist/infra/pairing-token.js

@@ -0,0 +1,9 @@
+import { randomBytes } from "node:crypto";
+import { safeEqualSecret } from "../security/secret-equal.js";
+export const PAIRING_TOKEN_BYTES = 32;
+export function generatePairingToken() {
+    return randomBytes(PAIRING_TOKEN_BYTES).toString("base64url");
+}
+export function verifyPairingToken(provided, expected) {
+    return safeEqualSecret(provided, expected);
+}

package/dist/infra/path-prepend.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+export function normalizePathPrepend(entries) {
+    if (!Array.isArray(entries)) {
+        return [];
+    }
+    const seen = new Set();
+    const normalized = [];
+    for (const entry of entries) {
+        if (typeof entry !== "string") {
+            continue;
+        }
+        const trimmed = entry.trim();
+        if (!trimmed || seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        normalized.push(trimmed);
+    }
+    return normalized;
+}
+export function mergePathPrepend(existing, prepend) {
+    if (prepend.length === 0) {
+        return existing;
+    }
+    const partsExisting = (existing ?? "")
+        .split(path.delimiter)
+        .map((part) => part.trim())
+        .filter(Boolean);
+    const merged = [];
+    const seen = new Set();
+    for (const part of [...prepend, ...partsExisting]) {
+        if (seen.has(part)) {
+            continue;
+        }
+        seen.add(part);
+        merged.push(part);
+    }
+    return merged.join(path.delimiter);
+}
+export function applyPathPrepend(env, prepend, options) {
+    if (!Array.isArray(prepend) || prepend.length === 0) {
+        return;
+    }
+    if (options?.requireExisting && !env.PATH) {
+        return;
+    }
+    const merged = mergePathPrepend(env.PATH, prepend);
+    if (merged) {
+        env.PATH = merged;
+    }
+}

package/dist/infra/process-respawn.js

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+const SUPERVISOR_HINT_ENV_VARS = [
+    "LAUNCH_JOB_LABEL",
+    "LAUNCH_JOB_NAME",
+    "INVOCATION_ID",
+    "SYSTEMD_EXEC_PID",
+    "JOURNAL_STREAM",
+];
+function isTruthy(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+function isLikelySupervisedProcess(env = process.env) {
+    return SUPERVISOR_HINT_ENV_VARS.some((key) => {
+        const value = env[key];
+        return typeof value === "string" && value.trim().length > 0;
+    });
+}
+/**
+ * Attempt to restart this process with a fresh PID.
+ * - supervised environments (launchd/systemd): caller should exit and let supervisor restart
+ * - POOLBOT_NO_RESPAWN=1: caller should keep in-process restart behavior (tests/dev)
+ * - otherwise: spawn detached child with current argv/execArgv, then caller exits
+ */
+export function restartGatewayProcessWithFreshPid() {
+    if (isTruthy(process.env.POOLBOT_NO_RESPAWN)) {
+        return { mode: "disabled" };
+    }
+    if (isLikelySupervisedProcess(process.env)) {
+        return { mode: "supervised" };
+    }
+    try {
+        const args = [...process.execArgv, ...process.argv.slice(1)];
+        const child = spawn(process.execPath, args, {
+            env: process.env,
+            detached: true,
+            stdio: "inherit",
+        });
+        child.unref();
+        return { mode: "spawned", pid: child.pid ?? undefined };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { mode: "failed", detail };
+    }
+}

package/dist/infra/runtime-status.js

@@ -0,0 +1,16 @@
+export function formatRuntimeStatusWithDetails({ status, pid, state, details = [], }) {
+    const runtimeStatus = status ?? "unknown";
+    const fullDetails = [];
+    if (pid) {
+        fullDetails.push(`pid ${pid}`);
+    }
+    if (state && state.toLowerCase() !== runtimeStatus) {
+        fullDetails.push(`state ${state}`);
+    }
+    for (const detail of details) {
+        if (detail) {
+            fullDetails.push(detail);
+        }
+    }
+    return fullDetails.length > 0 ? `${runtimeStatus} (${fullDetails.join(", ")})` : runtimeStatus;
+}

package/dist/infra/session-cost-usage.types.js

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

package/dist/infra/session-maintenance-warning.js

@@ -0,0 +1,89 @@
+import { resolveSessionAgentId } from "../agents/agent-scope.js";
+import { isDeliverableMessageChannel, normalizeMessageChannel } from "../utils/message-channel.js";
+import { resolveSessionDeliveryTarget } from "./outbound/targets.js";
+import { enqueueSystemEvent } from "./system-events.js";
+const warnedContexts = new Map();
+function shouldSendWarning() {
+    return !process.env.VITEST && process.env.NODE_ENV !== "test";
+}
+function buildWarningContext(params) {
+    const { warning } = params;
+    return [
+        warning.activeSessionKey,
+        warning.pruneAfterMs,
+        warning.maxEntries,
+        warning.wouldPrune ? "prune" : "",
+        warning.wouldCap ? "cap" : "",
+    ]
+        .filter(Boolean)
+        .join("|");
+}
+function formatDuration(ms) {
+    if (ms >= 86_400_000) {
+        const days = Math.round(ms / 86_400_000);
+        return `${days} day${days === 1 ? "" : "s"}`;
+    }
+    if (ms >= 3_600_000) {
+        const hours = Math.round(ms / 3_600_000);
+        return `${hours} hour${hours === 1 ? "" : "s"}`;
+    }
+    if (ms >= 60_000) {
+        const mins = Math.round(ms / 60_000);
+        return `${mins} minute${mins === 1 ? "" : "s"}`;
+    }
+    const secs = Math.round(ms / 1000);
+    return `${secs} second${secs === 1 ? "" : "s"}`;
+}
+function buildWarningText(warning) {
+    const reasons = [];
+    if (warning.wouldPrune) {
+        reasons.push(`older than ${formatDuration(warning.pruneAfterMs)}`);
+    }
+    if (warning.wouldCap) {
+        reasons.push(`not in the most recent ${warning.maxEntries} sessions`);
+    }
+    const reasonText = reasons.length > 0 ? reasons.join(" and ") : "over maintenance limits";
+    return (`⚠️ Session maintenance warning: this active session would be evicted (${reasonText}). ` +
+        `Maintenance is set to warn-only, so nothing was reset. ` +
+        `To enforce cleanup, set \`session.maintenance.mode: "enforce"\` or increase the limits.`);
+}
+export async function deliverSessionMaintenanceWarning(params) {
+    if (!shouldSendWarning()) {
+        return;
+    }
+    const contextKey = buildWarningContext(params);
+    if (warnedContexts.get(params.sessionKey) === contextKey) {
+        return;
+    }
+    warnedContexts.set(params.sessionKey, contextKey);
+    const text = buildWarningText(params.warning);
+    const target = resolveSessionDeliveryTarget({
+        entry: params.entry,
+        requestedChannel: "last",
+    });
+    if (!target.channel || !target.to) {
+        enqueueSystemEvent(text, { sessionKey: params.sessionKey });
+        return;
+    }
+    const channel = normalizeMessageChannel(target.channel) ?? target.channel;
+    if (!isDeliverableMessageChannel(channel)) {
+        enqueueSystemEvent(text, { sessionKey: params.sessionKey });
+        return;
+    }
+    try {
+        const { deliverOutboundPayloads } = await import("./outbound/deliver.js");
+        await deliverOutboundPayloads({
+            cfg: params.cfg,
+            channel,
+            to: target.to,
+            accountId: target.accountId,
+            threadId: target.threadId,
+            payloads: [{ text }],
+            agentId: resolveSessionAgentId({ sessionKey: params.sessionKey, config: params.cfg }),
+        });
+    }
+    catch (err) {
+        console.warn(`Failed to deliver session maintenance warning: ${String(err)}`);
+        enqueueSystemEvent(text, { sessionKey: params.sessionKey });
+    }
+}

package/dist/infra/system-run-command.js

@@ -0,0 +1,78 @@
+import path from "node:path";
+function basenameLower(token) {
+    const win = path.win32.basename(token);
+    const posix = path.posix.basename(token);
+    const base = win.length < posix.length ? win : posix;
+    return base.trim().toLowerCase();
+}
+export function formatExecCommand(argv) {
+    return argv
+        .map((arg) => {
+        const trimmed = arg.trim();
+        if (!trimmed) {
+            return '""';
+        }
+        const needsQuotes = /\s|"/.test(trimmed);
+        if (!needsQuotes) {
+            return trimmed;
+        }
+        return `"${trimmed.replace(/"/g, '\\"')}"`;
+    })
+        .join(" ");
+}
+export function extractShellCommandFromArgv(argv) {
+    const token0 = argv[0]?.trim();
+    if (!token0) {
+        return null;
+    }
+    const base0 = basenameLower(token0);
+    // POSIX-style shells: sh -lc "<cmd>"
+    if (base0 === "sh" ||
+        base0 === "bash" ||
+        base0 === "zsh" ||
+        base0 === "dash" ||
+        base0 === "ksh") {
+        const flag = argv[1]?.trim();
+        if (flag !== "-lc" && flag !== "-c") {
+            return null;
+        }
+        const cmd = argv[2];
+        return typeof cmd === "string" ? cmd : null;
+    }
+    // Windows cmd.exe: cmd.exe /d /s /c "<cmd>"
+    if (base0 === "cmd.exe" || base0 === "cmd") {
+        const idx = argv.findIndex((item) => String(item).trim().toLowerCase() === "/c");
+        if (idx === -1) {
+            return null;
+        }
+        const cmd = argv[idx + 1];
+        return typeof cmd === "string" ? cmd : null;
+    }
+    return null;
+}
+export function validateSystemRunCommandConsistency(params) {
+    const raw = typeof params.rawCommand === "string" && params.rawCommand.trim().length > 0
+        ? params.rawCommand.trim()
+        : null;
+    const shellCommand = extractShellCommandFromArgv(params.argv);
+    const inferred = shellCommand ? shellCommand.trim() : formatExecCommand(params.argv);
+    if (raw && raw !== inferred) {
+        return {
+            ok: false,
+            message: "INVALID_REQUEST: rawCommand does not match command",
+            details: {
+                code: "RAW_COMMAND_MISMATCH",
+                rawCommand: raw,
+                inferred,
+            },
+        };
+    }
+    return {
+        ok: true,
+        // Only treat this as a shell command when argv is a recognized shell wrapper.
+        // For direct argv execution, rawCommand is purely display/approval text and
+        // must match the formatted argv.
+        shellCommand: shellCommand ? (raw ?? shellCommand) : null,
+        cmdText: raw ?? shellCommand ?? inferred,
+    };
+}