@poolzin/pool-bot 2026.2.17 → 2026.2.19

package/dist/pairing/setup-code.js

@@ -0,0 +1,285 @@
+import os from "node:os";
+const DEFAULT_GATEWAY_PORT = 18789;
+function normalizeUrl(raw, schemeFallback) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    try {
+        const parsed = new URL(trimmed);
+        const scheme = parsed.protocol.replace(":", "");
+        if (!scheme) {
+            return null;
+        }
+        const resolvedScheme = scheme === "http" ? "ws" : scheme === "https" ? "wss" : scheme;
+        if (resolvedScheme !== "ws" && resolvedScheme !== "wss") {
+            return null;
+        }
+        const host = parsed.hostname;
+        if (!host) {
+            return null;
+        }
+        const port = parsed.port ? `:${parsed.port}` : "";
+        return `${resolvedScheme}://${host}${port}`;
+    }
+    catch {
+        // Fall through to host:port parsing.
+    }
+    const withoutPath = trimmed.split("/")[0] ?? "";
+    if (!withoutPath) {
+        return null;
+    }
+    return `${schemeFallback}://${withoutPath}`;
+}
+function resolveGatewayPort(cfg, env) {
+    const envRaw = env.POOLBOT_GATEWAY_PORT?.trim() || env.CLAWDBOT_GATEWAY_PORT?.trim();
+    if (envRaw) {
+        const parsed = Number.parseInt(envRaw, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    const configPort = cfg.gateway?.port;
+    if (typeof configPort === "number" && Number.isFinite(configPort) && configPort > 0) {
+        return configPort;
+    }
+    return DEFAULT_GATEWAY_PORT;
+}
+function resolveScheme(cfg, opts) {
+    if (opts?.forceSecure) {
+        return "wss";
+    }
+    return cfg.gateway?.tls?.enabled === true ? "wss" : "ws";
+}
+function parseIPv4Octets(address) {
+    const parts = address.split(".");
+    if (parts.length !== 4) {
+        return null;
+    }
+    const octets = parts.map((part) => Number.parseInt(part, 10));
+    if (octets.some((value) => !Number.isFinite(value) || value < 0 || value > 255)) {
+        return null;
+    }
+    return [octets[0], octets[1], octets[2], octets[3]];
+}
+function isPrivateIPv4(address) {
+    const octets = parseIPv4Octets(address);
+    if (!octets) {
+        return false;
+    }
+    const [a, b] = octets;
+    if (a === 10) {
+        return true;
+    }
+    if (a === 172 && b >= 16 && b <= 31) {
+        return true;
+    }
+    if (a === 192 && b === 168) {
+        return true;
+    }
+    return false;
+}
+function isTailnetIPv4(address) {
+    const octets = parseIPv4Octets(address);
+    if (!octets) {
+        return false;
+    }
+    const [a, b] = octets;
+    return a === 100 && b >= 64 && b <= 127;
+}
+function pickIPv4Matching(networkInterfaces, matches) {
+    const nets = networkInterfaces();
+    for (const entries of Object.values(nets)) {
+        if (!entries) {
+            continue;
+        }
+        for (const entry of entries) {
+            const family = entry?.family;
+            const isIpv4 = family === "IPv4";
+            if (!entry || entry.internal || !isIpv4) {
+                continue;
+            }
+            const address = entry.address?.trim() ?? "";
+            if (!address) {
+                continue;
+            }
+            if (matches(address)) {
+                return address;
+            }
+        }
+    }
+    return null;
+}
+function pickLanIPv4(networkInterfaces) {
+    return pickIPv4Matching(networkInterfaces, isPrivateIPv4);
+}
+function pickTailnetIPv4(networkInterfaces) {
+    return pickIPv4Matching(networkInterfaces, isTailnetIPv4);
+}
+function parsePossiblyNoisyJsonObject(raw) {
+    const start = raw.indexOf("{");
+    const end = raw.lastIndexOf("}");
+    if (start === -1 || end <= start) {
+        return {};
+    }
+    try {
+        return JSON.parse(raw.slice(start, end + 1));
+    }
+    catch {
+        return {};
+    }
+}
+async function resolveTailnetHost(runCommandWithTimeout) {
+    if (!runCommandWithTimeout) {
+        return null;
+    }
+    const candidates = ["tailscale", "/Applications/Tailscale.app/Contents/MacOS/Tailscale"];
+    for (const candidate of candidates) {
+        try {
+            const result = await runCommandWithTimeout([candidate, "status", "--json"], {
+                timeoutMs: 5000,
+            });
+            if (result.code !== 0) {
+                continue;
+            }
+            const raw = result.stdout.trim();
+            if (!raw) {
+                continue;
+            }
+            const parsed = parsePossiblyNoisyJsonObject(raw);
+            const self = typeof parsed.Self === "object" && parsed.Self !== null
+                ? parsed.Self
+                : undefined;
+            const dns = typeof self?.DNSName === "string" ? self.DNSName : undefined;
+            if (dns && dns.length > 0) {
+                return dns.replace(/\.$/, "");
+            }
+            const ips = Array.isArray(self?.TailscaleIPs) ? self.TailscaleIPs : [];
+            if (ips.length > 0) {
+                return ips[0] ?? null;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function resolveAuth(cfg, env) {
+    const mode = cfg.gateway?.auth?.mode;
+    const token = env.POOLBOT_GATEWAY_TOKEN?.trim() ||
+        env.CLAWDBOT_GATEWAY_TOKEN?.trim() ||
+        cfg.gateway?.auth?.token?.trim();
+    const password = env.POOLBOT_GATEWAY_PASSWORD?.trim() ||
+        env.CLAWDBOT_GATEWAY_PASSWORD?.trim() ||
+        cfg.gateway?.auth?.password?.trim();
+    if (mode === "password") {
+        if (!password) {
+            return { error: "Gateway auth is set to password, but no password is configured." };
+        }
+        return { password, label: "password" };
+    }
+    if (mode === "token") {
+        if (!token) {
+            return { error: "Gateway auth is set to token, but no token is configured." };
+        }
+        return { token, label: "token" };
+    }
+    if (token) {
+        return { token, label: "token" };
+    }
+    if (password) {
+        return { password, label: "password" };
+    }
+    return { error: "Gateway auth is not configured (no token or password)." };
+}
+async function resolveGatewayUrl(cfg, opts) {
+    const scheme = resolveScheme(cfg, { forceSecure: opts.forceSecure });
+    const port = resolveGatewayPort(cfg, opts.env);
+    if (typeof opts.publicUrl === "string" && opts.publicUrl.trim()) {
+        const url = normalizeUrl(opts.publicUrl, scheme);
+        if (url) {
+            return { url, source: "plugins.entries.device-pair.config.publicUrl" };
+        }
+        return { error: "Configured publicUrl is invalid." };
+    }
+    const remoteUrlRaw = cfg.gateway?.remote?.url;
+    const remoteUrl = typeof remoteUrlRaw === "string" && remoteUrlRaw.trim()
+        ? normalizeUrl(remoteUrlRaw, scheme)
+        : null;
+    if (opts.preferRemoteUrl && remoteUrl) {
+        return { url: remoteUrl, source: "gateway.remote.url" };
+    }
+    const tailscaleMode = cfg.gateway?.tailscale?.mode ?? "off";
+    if (tailscaleMode === "serve" || tailscaleMode === "funnel") {
+        const host = await resolveTailnetHost(opts.runCommandWithTimeout);
+        if (!host) {
+            return { error: "Tailscale Serve is enabled, but MagicDNS could not be resolved." };
+        }
+        return { url: `wss://${host}`, source: `gateway.tailscale.mode=${tailscaleMode}` };
+    }
+    if (remoteUrl) {
+        return { url: remoteUrl, source: "gateway.remote.url" };
+    }
+    const bind = cfg.gateway?.bind ?? "loopback";
+    if (bind === "custom") {
+        const host = cfg.gateway?.customBindHost?.trim();
+        if (host) {
+            return { url: `${scheme}://${host}:${port}`, source: "gateway.bind=custom" };
+        }
+        return { error: "gateway.bind=custom requires gateway.customBindHost." };
+    }
+    if (bind === "tailnet") {
+        const host = pickTailnetIPv4(opts.networkInterfaces);
+        if (host) {
+            return { url: `${scheme}://${host}:${port}`, source: "gateway.bind=tailnet" };
+        }
+        return { error: "gateway.bind=tailnet set, but no tailnet IP was found." };
+    }
+    if (bind === "lan") {
+        const host = pickLanIPv4(opts.networkInterfaces);
+        if (host) {
+            return { url: `${scheme}://${host}:${port}`, source: "gateway.bind=lan" };
+        }
+        return { error: "gateway.bind=lan set, but no private LAN IP was found." };
+    }
+    return {
+        error: "Gateway is only bound to loopback. Set gateway.bind=lan, enable tailscale serve, or configure plugins.entries.device-pair.config.publicUrl.",
+    };
+}
+export function encodePairingSetupCode(payload) {
+    const json = JSON.stringify(payload);
+    const base64 = Buffer.from(json, "utf8").toString("base64");
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+export async function resolvePairingSetupFromConfig(cfg, options = {}) {
+    const env = options.env ?? process.env;
+    const auth = resolveAuth(cfg, env);
+    if (auth.error) {
+        return { ok: false, error: auth.error };
+    }
+    const urlResult = await resolveGatewayUrl(cfg, {
+        env,
+        publicUrl: options.publicUrl,
+        preferRemoteUrl: options.preferRemoteUrl,
+        forceSecure: options.forceSecure,
+        runCommandWithTimeout: options.runCommandWithTimeout,
+        networkInterfaces: options.networkInterfaces ?? os.networkInterfaces,
+    });
+    if (!urlResult.url) {
+        return { ok: false, error: urlResult.error ?? "Gateway URL unavailable." };
+    }
+    if (!auth.label) {
+        return { ok: false, error: "Gateway auth is not configured (no token or password)." };
+    }
+    return {
+        ok: true,
+        payload: {
+            url: urlResult.url,
+            token: auth.token,
+            password: auth.password,
+        },
+        authLabel: auth.label,
+        urlSource: urlResult.source ?? "unknown",
+    };
+}

package/dist/plugin-sdk/account-id.js

@@ -0,0 +1 @@
+export { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../routing/session-key.js";

package/dist/plugin-sdk/agent-media-payload.js

@@ -0,0 +1,13 @@
+export function buildAgentMediaPayload(mediaList) {
+    const first = mediaList[0];
+    const mediaPaths = mediaList.map((media) => media.path);
+    const mediaTypes = mediaList.map((media) => media.contentType).filter(Boolean);
+    return {
+        MediaPath: first?.path,
+        MediaType: first?.contentType ?? undefined,
+        MediaUrl: first?.path,
+        MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
+        MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
+        MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
+    };
+}

package/dist/plugin-sdk/allow-from.js

@@ -0,0 +1,47 @@
+export function formatAllowFromLowercase(params) {
+    return params.allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => (params.stripPrefixRe ? entry.replace(params.stripPrefixRe, "") : entry))
+        .map((entry) => entry.toLowerCase());
+}
+export function isAllowedParsedChatSender(params) {
+    const allowFrom = params.allowFrom.map((entry) => String(entry).trim());
+    if (allowFrom.length === 0) {
+        return true;
+    }
+    if (allowFrom.includes("*")) {
+        return true;
+    }
+    const senderNormalized = params.normalizeSender(params.sender);
+    const chatId = params.chatId ?? undefined;
+    const chatGuid = params.chatGuid?.trim();
+    const chatIdentifier = params.chatIdentifier?.trim();
+    for (const entry of allowFrom) {
+        if (!entry) {
+            continue;
+        }
+        const parsed = params.parseAllowTarget(entry);
+        if (parsed.kind === "chat_id" && chatId !== undefined) {
+            if (parsed.chatId === chatId) {
+                return true;
+            }
+        }
+        else if (parsed.kind === "chat_guid" && chatGuid) {
+            if (parsed.chatGuid === chatGuid) {
+                return true;
+            }
+        }
+        else if (parsed.kind === "chat_identifier" && chatIdentifier) {
+            if (parsed.chatIdentifier === chatIdentifier) {
+                return true;
+            }
+        }
+        else if (parsed.kind === "handle" && senderNormalized) {
+            if (parsed.handle === senderNormalized) {
+                return true;
+            }
+        }
+    }
+    return false;
+}

package/dist/plugin-sdk/command-auth.js

@@ -0,0 +1,23 @@
+export async function resolveSenderCommandAuthorization(params) {
+    const shouldComputeAuth = params.shouldComputeCommandAuthorized(params.rawBody, params.cfg);
+    const storeAllowFrom = !params.isGroup && (params.dmPolicy !== "open" || shouldComputeAuth)
+        ? await params.readAllowFromStore().catch(() => [])
+        : [];
+    const effectiveAllowFrom = [...params.configuredAllowFrom, ...storeAllowFrom];
+    const useAccessGroups = params.cfg.commands?.useAccessGroups !== false;
+    const senderAllowedForCommands = params.isSenderAllowed(params.senderId, effectiveAllowFrom);
+    const commandAuthorized = shouldComputeAuth
+        ? params.resolveCommandAuthorizedFromAuthorizers({
+            useAccessGroups,
+            authorizers: [
+                { configured: effectiveAllowFrom.length > 0, allowed: senderAllowedForCommands },
+            ],
+        })
+        : undefined;
+    return {
+        shouldComputeAuth,
+        effectiveAllowFrom,
+        senderAllowedForCommands,
+        commandAuthorized,
+    };
+}

package/dist/plugin-sdk/config-paths.js

@@ -0,0 +1,9 @@
+export function resolveChannelAccountConfigBasePath(params) {
+    const channels = params.cfg.channels;
+    const channelSection = channels?.[params.channelKey];
+    const accounts = channelSection?.accounts;
+    const useAccountPath = Boolean(accounts?.[params.accountId]);
+    return useAccountPath
+        ? `channels.${params.channelKey}.accounts.${params.accountId}.`
+        : `channels.${params.channelKey}.`;
+}

package/dist/plugin-sdk/file-lock.js

@@ -0,0 +1,116 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isPidAlive } from "../shared/pid-alive.js";
+import { resolveProcessScopedMap } from "../shared/process-scoped-map.js";
+const HELD_LOCKS_KEY = Symbol.for("poolbot.fileLockHeldLocks");
+const HELD_LOCKS = resolveProcessScopedMap(HELD_LOCKS_KEY);
+function computeDelayMs(retries, attempt) {
+    const base = Math.min(retries.maxTimeout, Math.max(retries.minTimeout, retries.minTimeout * retries.factor ** attempt));
+    const jitter = retries.randomize ? 1 + Math.random() : 1;
+    return Math.min(retries.maxTimeout, Math.round(base * jitter));
+}
+async function readLockPayload(lockPath) {
+    try {
+        const raw = await fs.readFile(lockPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== "number" || typeof parsed.createdAt !== "string") {
+            return null;
+        }
+        return { pid: parsed.pid, createdAt: parsed.createdAt };
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveNormalizedFilePath(filePath) {
+    const resolved = path.resolve(filePath);
+    const dir = path.dirname(resolved);
+    await fs.mkdir(dir, { recursive: true });
+    try {
+        const realDir = await fs.realpath(dir);
+        return path.join(realDir, path.basename(resolved));
+    }
+    catch {
+        return resolved;
+    }
+}
+async function isStaleLock(lockPath, staleMs) {
+    const payload = await readLockPayload(lockPath);
+    if (payload?.pid && !isPidAlive(payload.pid)) {
+        return true;
+    }
+    if (payload?.createdAt) {
+        const createdAt = Date.parse(payload.createdAt);
+        if (!Number.isFinite(createdAt) || Date.now() - createdAt > staleMs) {
+            return true;
+        }
+    }
+    try {
+        const stat = await fs.stat(lockPath);
+        return Date.now() - stat.mtimeMs > staleMs;
+    }
+    catch {
+        return true;
+    }
+}
+async function releaseHeldLock(normalizedFile) {
+    const current = HELD_LOCKS.get(normalizedFile);
+    if (!current) {
+        return;
+    }
+    current.count -= 1;
+    if (current.count > 0) {
+        return;
+    }
+    HELD_LOCKS.delete(normalizedFile);
+    await current.handle.close().catch(() => undefined);
+    await fs.rm(current.lockPath, { force: true }).catch(() => undefined);
+}
+export async function acquireFileLock(filePath, options) {
+    const normalizedFile = await resolveNormalizedFilePath(filePath);
+    const lockPath = `${normalizedFile}.lock`;
+    const held = HELD_LOCKS.get(normalizedFile);
+    if (held) {
+        held.count += 1;
+        return {
+            lockPath,
+            release: () => releaseHeldLock(normalizedFile),
+        };
+    }
+    const attempts = Math.max(1, options.retries.retries + 1);
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            const handle = await fs.open(lockPath, "wx");
+            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }, null, 2), "utf8");
+            HELD_LOCKS.set(normalizedFile, { count: 1, handle, lockPath });
+            return {
+                lockPath,
+                release: () => releaseHeldLock(normalizedFile),
+            };
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST") {
+                throw err;
+            }
+            if (await isStaleLock(lockPath, options.stale)) {
+                await fs.rm(lockPath, { force: true }).catch(() => undefined);
+                continue;
+            }
+            if (attempt >= attempts - 1) {
+                break;
+            }
+            await new Promise((resolve) => setTimeout(resolve, computeDelayMs(options.retries, attempt)));
+        }
+    }
+    throw new Error(`file lock timeout for ${normalizedFile}`);
+}
+export async function withFileLock(filePath, options, fn) {
+    const lock = await acquireFileLock(filePath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/plugin-sdk/json-store.js

@@ -0,0 +1,31 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { safeParseJson } from "../utils.js";
+export async function readJsonFileWithFallback(filePath, fallback) {
+    try {
+        const raw = await fs.promises.readFile(filePath, "utf-8");
+        const parsed = safeParseJson(raw);
+        if (parsed == null) {
+            return { value: fallback, exists: true };
+        }
+        return { value: parsed, exists: true };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return { value: fallback, exists: false };
+        }
+        return { value: fallback, exists: false };
+    }
+}
+export async function writeJsonFileAtomically(filePath, value) {
+    const dir = path.dirname(filePath);
+    await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `${path.basename(filePath)}.${crypto.randomUUID()}.tmp`);
+    await fs.promises.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, {
+        encoding: "utf-8",
+    });
+    await fs.promises.chmod(tmp, 0o600);
+    await fs.promises.rename(tmp, filePath);
+}

package/dist/plugin-sdk/onboarding.js

@@ -0,0 +1,28 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../routing/session-key.js";
+export async function promptAccountId(params) {
+    const existingIds = params.listAccountIds(params.cfg);
+    const initial = params.currentId?.trim() || params.defaultAccountId || DEFAULT_ACCOUNT_ID;
+    const choice = await params.prompter.select({
+        message: `${params.label} account`,
+        options: [
+            ...existingIds.map((id) => ({
+                value: id,
+                label: id === DEFAULT_ACCOUNT_ID ? "default (primary)" : id,
+            })),
+            { value: "__new__", label: "Add a new account" },
+        ],
+        initialValue: initial,
+    });
+    if (choice !== "__new__") {
+        return normalizeAccountId(choice);
+    }
+    const entered = await params.prompter.text({
+        message: `New ${params.label} account id`,
+        validate: (value) => (value?.trim() ? undefined : "Required"),
+    });
+    const normalized = normalizeAccountId(String(entered));
+    if (String(entered).trim() !== normalized) {
+        await params.prompter.note(`Normalized account id to "${normalized}".`, `${params.label} account`);
+    }
+    return normalized;
+}

package/dist/plugin-sdk/provider-auth-result.js

@@ -0,0 +1,29 @@
+export function buildOauthProviderAuthResult(params) {
+    const email = params.email ?? undefined;
+    const profilePrefix = params.profilePrefix ?? params.providerId;
+    const profileId = `${profilePrefix}:${email ?? "default"}`;
+    const credential = {
+        type: "oauth",
+        provider: params.providerId,
+        access: params.access,
+        ...(params.refresh ? { refresh: params.refresh } : {}),
+        ...(Number.isFinite(params.expires) ? { expires: params.expires } : {}),
+        ...(email ? { email } : {}),
+        ...params.credentialExtra,
+    };
+    return {
+        profiles: [{ profileId, credential }],
+        configPatch: params.configPatch ??
+            {
+                agents: {
+                    defaults: {
+                        models: {
+                            [params.defaultModel]: {},
+                        },
+                    },
+                },
+            },
+        defaultModel: params.defaultModel,
+        notes: params.notes,
+    };
+}