@poolzin/pool-bot 2026.2.17 → 2026.2.18

package/extensions/telegram/src/channel.js

@@ -0,0 +1,424 @@
+import { applyAccountNameToChannelSection, buildChannelConfigSchema, collectTelegramStatusIssues, DEFAULT_ACCOUNT_ID, deleteAccountFromConfigSection, formatPairingApproveHint, getChatChannelMeta, listTelegramAccountIds, listTelegramDirectoryGroupsFromConfig, listTelegramDirectoryPeersFromConfig, looksLikeTelegramTargetId, migrateBaseNameToDefaultAccount, normalizeAccountId, normalizeTelegramMessagingTarget, PAIRING_APPROVED_MESSAGE, resolveDefaultTelegramAccountId, resolveTelegramAccount, resolveTelegramGroupRequireMention, resolveTelegramGroupToolPolicy, setAccountEnabledInConfigSection, telegramOnboardingAdapter, TelegramConfigSchema, } from "poolbot/plugin-sdk";
+import { getTelegramRuntime } from "./runtime.js";
+const meta = getChatChannelMeta("telegram");
+const telegramMessageActions = {
+    listActions: (ctx) => getTelegramRuntime().channel.telegram.messageActions.listActions(ctx),
+    extractToolSend: (ctx) => getTelegramRuntime().channel.telegram.messageActions.extractToolSend(ctx),
+    handleAction: async (ctx) => await getTelegramRuntime().channel.telegram.messageActions.handleAction(ctx),
+};
+function parseReplyToMessageId(replyToId) {
+    if (!replyToId)
+        return undefined;
+    const parsed = Number.parseInt(replyToId, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function parseThreadId(threadId) {
+    if (threadId == null)
+        return undefined;
+    if (typeof threadId === "number") {
+        return Number.isFinite(threadId) ? Math.trunc(threadId) : undefined;
+    }
+    const trimmed = threadId.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number.parseInt(trimmed, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+export const telegramPlugin = {
+    id: "telegram",
+    meta: {
+        ...meta,
+        quickstartAllowFrom: true,
+    },
+    onboarding: telegramOnboardingAdapter,
+    pairing: {
+        idLabel: "telegramUserId",
+        normalizeAllowEntry: (entry) => entry.replace(/^(telegram|tg):/i, ""),
+        notifyApproval: async ({ cfg, id }) => {
+            const { token } = getTelegramRuntime().channel.telegram.resolveTelegramToken(cfg);
+            if (!token)
+                throw new Error("telegram token not configured");
+            await getTelegramRuntime().channel.telegram.sendMessageTelegram(id, PAIRING_APPROVED_MESSAGE, {
+                token,
+            });
+        },
+    },
+    capabilities: {
+        chatTypes: ["direct", "group", "channel", "thread"],
+        reactions: true,
+        threads: true,
+        media: true,
+        nativeCommands: true,
+        blockStreaming: true,
+    },
+    reload: { configPrefixes: ["channels.telegram"] },
+    configSchema: buildChannelConfigSchema(TelegramConfigSchema),
+    config: {
+        listAccountIds: (cfg) => listTelegramAccountIds(cfg),
+        resolveAccount: (cfg, accountId) => resolveTelegramAccount({ cfg, accountId }),
+        defaultAccountId: (cfg) => resolveDefaultTelegramAccountId(cfg),
+        setAccountEnabled: ({ cfg, accountId, enabled }) => setAccountEnabledInConfigSection({
+            cfg,
+            sectionKey: "telegram",
+            accountId,
+            enabled,
+            allowTopLevel: true,
+        }),
+        deleteAccount: ({ cfg, accountId }) => deleteAccountFromConfigSection({
+            cfg,
+            sectionKey: "telegram",
+            accountId,
+            clearBaseFields: ["botToken", "tokenFile", "name"],
+        }),
+        isConfigured: (account) => Boolean(account.token?.trim()),
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured: Boolean(account.token?.trim()),
+            tokenSource: account.tokenSource,
+        }),
+        resolveAllowFrom: ({ cfg, accountId }) => (resolveTelegramAccount({ cfg, accountId }).config.allowFrom ?? []).map((entry) => String(entry)),
+        formatAllowFrom: ({ allowFrom }) => allowFrom
+            .map((entry) => String(entry).trim())
+            .filter(Boolean)
+            .map((entry) => entry.replace(/^(telegram|tg):/i, ""))
+            .map((entry) => entry.toLowerCase()),
+    },
+    security: {
+        resolveDmPolicy: ({ cfg, accountId, account }) => {
+            const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+            const useAccountPath = Boolean(cfg.channels?.telegram?.accounts?.[resolvedAccountId]);
+            const basePath = useAccountPath
+                ? `channels.telegram.accounts.${resolvedAccountId}.`
+                : "channels.telegram.";
+            return {
+                policy: account.config.dmPolicy ?? "pairing",
+                allowFrom: account.config.allowFrom ?? [],
+                policyPath: `${basePath}dmPolicy`,
+                allowFromPath: basePath,
+                approveHint: formatPairingApproveHint("telegram"),
+                normalizeEntry: (raw) => raw.replace(/^(telegram|tg):/i, ""),
+            };
+        },
+        collectWarnings: ({ account, cfg }) => {
+            const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+            const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+            if (groupPolicy !== "open")
+                return [];
+            const groupAllowlistConfigured = account.config.groups && Object.keys(account.config.groups).length > 0;
+            if (groupAllowlistConfigured) {
+                return [
+                    `- Telegram groups: groupPolicy="open" allows any member in allowed groups to trigger (mention-gated). Set channels.telegram.groupPolicy="allowlist" + channels.telegram.groupAllowFrom to restrict senders.`,
+                ];
+            }
+            return [
+                `- Telegram groups: groupPolicy="open" with no channels.telegram.groups allowlist; any group can add + ping (mention-gated). Set channels.telegram.groupPolicy="allowlist" + channels.telegram.groupAllowFrom or configure channels.telegram.groups.`,
+            ];
+        },
+    },
+    groups: {
+        resolveRequireMention: resolveTelegramGroupRequireMention,
+        resolveToolPolicy: resolveTelegramGroupToolPolicy,
+    },
+    threading: {
+        resolveReplyToMode: ({ cfg }) => cfg.channels?.telegram?.replyToMode ?? "first",
+    },
+    messaging: {
+        normalizeTarget: normalizeTelegramMessagingTarget,
+        targetResolver: {
+            looksLikeId: looksLikeTelegramTargetId,
+            hint: "<chatId>",
+        },
+    },
+    directory: {
+        self: async () => null,
+        listPeers: async (params) => listTelegramDirectoryPeersFromConfig(params),
+        listGroups: async (params) => listTelegramDirectoryGroupsFromConfig(params),
+    },
+    actions: telegramMessageActions,
+    setup: {
+        resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+        applyAccountName: ({ cfg, accountId, name }) => applyAccountNameToChannelSection({
+            cfg,
+            channelKey: "telegram",
+            accountId,
+            name,
+        }),
+        validateInput: ({ accountId, input }) => {
+            if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+                return "TELEGRAM_BOT_TOKEN can only be used for the default account.";
+            }
+            if (!input.useEnv && !input.token && !input.tokenFile) {
+                return "Telegram requires token or --token-file (or --use-env).";
+            }
+            return null;
+        },
+        applyAccountConfig: ({ cfg, accountId, input }) => {
+            const namedConfig = applyAccountNameToChannelSection({
+                cfg,
+                channelKey: "telegram",
+                accountId,
+                name: input.name,
+            });
+            const next = accountId !== DEFAULT_ACCOUNT_ID
+                ? migrateBaseNameToDefaultAccount({
+                    cfg: namedConfig,
+                    channelKey: "telegram",
+                })
+                : namedConfig;
+            if (accountId === DEFAULT_ACCOUNT_ID) {
+                return {
+                    ...next,
+                    channels: {
+                        ...next.channels,
+                        telegram: {
+                            ...next.channels?.telegram,
+                            enabled: true,
+                            ...(input.useEnv
+                                ? {}
+                                : input.tokenFile
+                                    ? { tokenFile: input.tokenFile }
+                                    : input.token
+                                        ? { botToken: input.token }
+                                        : {}),
+                        },
+                    },
+                };
+            }
+            return {
+                ...next,
+                channels: {
+                    ...next.channels,
+                    telegram: {
+                        ...next.channels?.telegram,
+                        enabled: true,
+                        accounts: {
+                            ...next.channels?.telegram?.accounts,
+                            [accountId]: {
+                                ...next.channels?.telegram?.accounts?.[accountId],
+                                enabled: true,
+                                ...(input.tokenFile
+                                    ? { tokenFile: input.tokenFile }
+                                    : input.token
+                                        ? { botToken: input.token }
+                                        : {}),
+                            },
+                        },
+                    },
+                },
+            };
+        },
+    },
+    outbound: {
+        deliveryMode: "direct",
+        chunker: (text, limit) => getTelegramRuntime().channel.text.chunkMarkdownText(text, limit),
+        chunkerMode: "markdown",
+        textChunkLimit: 4000,
+        sendText: async ({ to, text, accountId, deps, replyToId, threadId }) => {
+            const send = deps?.sendTelegram ?? getTelegramRuntime().channel.telegram.sendMessageTelegram;
+            const replyToMessageId = parseReplyToMessageId(replyToId);
+            const messageThreadId = parseThreadId(threadId);
+            const result = await send(to, text, {
+                verbose: false,
+                messageThreadId,
+                replyToMessageId,
+                accountId: accountId ?? undefined,
+            });
+            return { channel: "telegram", ...result };
+        },
+        sendMedia: async ({ to, text, mediaUrl, accountId, deps, replyToId, threadId }) => {
+            const send = deps?.sendTelegram ?? getTelegramRuntime().channel.telegram.sendMessageTelegram;
+            const replyToMessageId = parseReplyToMessageId(replyToId);
+            const messageThreadId = parseThreadId(threadId);
+            const result = await send(to, text, {
+                verbose: false,
+                mediaUrl,
+                messageThreadId,
+                replyToMessageId,
+                accountId: accountId ?? undefined,
+            });
+            return { channel: "telegram", ...result };
+        },
+    },
+    status: {
+        defaultRuntime: {
+            accountId: DEFAULT_ACCOUNT_ID,
+            running: false,
+            lastStartAt: null,
+            lastStopAt: null,
+            lastError: null,
+        },
+        collectStatusIssues: collectTelegramStatusIssues,
+        buildChannelSummary: ({ snapshot }) => ({
+            configured: snapshot.configured ?? false,
+            tokenSource: snapshot.tokenSource ?? "none",
+            running: snapshot.running ?? false,
+            mode: snapshot.mode ?? null,
+            lastStartAt: snapshot.lastStartAt ?? null,
+            lastStopAt: snapshot.lastStopAt ?? null,
+            lastError: snapshot.lastError ?? null,
+            probe: snapshot.probe,
+            lastProbeAt: snapshot.lastProbeAt ?? null,
+        }),
+        probeAccount: async ({ account, timeoutMs }) => getTelegramRuntime().channel.telegram.probeTelegram(account.token, timeoutMs, account.config.proxy),
+        auditAccount: async ({ account, timeoutMs, probe, cfg }) => {
+            const groups = cfg.channels?.telegram?.accounts?.[account.accountId]?.groups ??
+                cfg.channels?.telegram?.groups;
+            const { groupIds, unresolvedGroups, hasWildcardUnmentionedGroups } = getTelegramRuntime().channel.telegram.collectUnmentionedGroupIds(groups);
+            if (!groupIds.length && unresolvedGroups === 0 && !hasWildcardUnmentionedGroups) {
+                return undefined;
+            }
+            const botId = probe?.ok &&
+                probe.bot?.id != null
+                ? probe.bot.id
+                : null;
+            if (!botId) {
+                return {
+                    ok: unresolvedGroups === 0 && !hasWildcardUnmentionedGroups,
+                    checkedGroups: 0,
+                    unresolvedGroups,
+                    hasWildcardUnmentionedGroups,
+                    groups: [],
+                    elapsedMs: 0,
+                };
+            }
+            const audit = await getTelegramRuntime().channel.telegram.auditGroupMembership({
+                token: account.token,
+                botId,
+                groupIds,
+                proxyUrl: account.config.proxy,
+                timeoutMs,
+            });
+            return { ...audit, unresolvedGroups, hasWildcardUnmentionedGroups };
+        },
+        buildAccountSnapshot: ({ account, cfg, runtime, probe, audit }) => {
+            const configured = Boolean(account.token?.trim());
+            const groups = cfg.channels?.telegram?.accounts?.[account.accountId]?.groups ??
+                cfg.channels?.telegram?.groups;
+            const allowUnmentionedGroups = Boolean(groups?.["*"] && groups["*"].requireMention === false) ||
+                Object.entries(groups ?? {}).some(([key, value]) => key !== "*" &&
+                    Boolean(value) &&
+                    typeof value === "object" &&
+                    value.requireMention === false);
+            return {
+                accountId: account.accountId,
+                name: account.name,
+                enabled: account.enabled,
+                configured,
+                tokenSource: account.tokenSource,
+                running: runtime?.running ?? false,
+                lastStartAt: runtime?.lastStartAt ?? null,
+                lastStopAt: runtime?.lastStopAt ?? null,
+                lastError: runtime?.lastError ?? null,
+                mode: runtime?.mode ?? (account.config.webhookUrl ? "webhook" : "polling"),
+                probe,
+                audit,
+                allowUnmentionedGroups,
+                lastInboundAt: runtime?.lastInboundAt ?? null,
+                lastOutboundAt: runtime?.lastOutboundAt ?? null,
+            };
+        },
+    },
+    gateway: {
+        startAccount: async (ctx) => {
+            const account = ctx.account;
+            const token = account.token.trim();
+            let telegramBotLabel = "";
+            try {
+                const probe = await getTelegramRuntime().channel.telegram.probeTelegram(token, 2500, account.config.proxy);
+                const username = probe.ok ? probe.bot?.username?.trim() : null;
+                if (username)
+                    telegramBotLabel = ` (@${username})`;
+            }
+            catch (err) {
+                if (getTelegramRuntime().logging.shouldLogVerbose()) {
+                    ctx.log?.debug?.(`[${account.accountId}] bot probe failed: ${String(err)}`);
+                }
+            }
+            ctx.log?.info(`[${account.accountId}] starting provider${telegramBotLabel}`);
+            return getTelegramRuntime().channel.telegram.monitorTelegramProvider({
+                token,
+                accountId: account.accountId,
+                config: ctx.cfg,
+                runtime: ctx.runtime,
+                abortSignal: ctx.abortSignal,
+                useWebhook: Boolean(account.config.webhookUrl),
+                webhookUrl: account.config.webhookUrl,
+                webhookSecret: account.config.webhookSecret,
+                webhookPath: account.config.webhookPath,
+            });
+        },
+        logoutAccount: async ({ accountId, cfg }) => {
+            const envToken = process.env.TELEGRAM_BOT_TOKEN?.trim() ?? "";
+            const nextCfg = { ...cfg };
+            const nextTelegram = cfg.channels?.telegram ? { ...cfg.channels.telegram } : undefined;
+            let cleared = false;
+            let changed = false;
+            if (nextTelegram) {
+                if (accountId === DEFAULT_ACCOUNT_ID && nextTelegram.botToken) {
+                    delete nextTelegram.botToken;
+                    cleared = true;
+                    changed = true;
+                }
+                const accounts = nextTelegram.accounts && typeof nextTelegram.accounts === "object"
+                    ? { ...nextTelegram.accounts }
+                    : undefined;
+                if (accounts && accountId in accounts) {
+                    const entry = accounts[accountId];
+                    if (entry && typeof entry === "object") {
+                        const nextEntry = { ...entry };
+                        if ("botToken" in nextEntry) {
+                            const token = nextEntry.botToken;
+                            if (typeof token === "string" ? token.trim() : token) {
+                                cleared = true;
+                            }
+                            delete nextEntry.botToken;
+                            changed = true;
+                        }
+                        if (Object.keys(nextEntry).length === 0) {
+                            delete accounts[accountId];
+                            changed = true;
+                        }
+                        else {
+                            accounts[accountId] = nextEntry;
+                        }
+                    }
+                }
+                if (accounts) {
+                    if (Object.keys(accounts).length === 0) {
+                        delete nextTelegram.accounts;
+                        changed = true;
+                    }
+                    else {
+                        nextTelegram.accounts = accounts;
+                    }
+                }
+            }
+            if (changed) {
+                if (nextTelegram && Object.keys(nextTelegram).length > 0) {
+                    nextCfg.channels = { ...nextCfg.channels, telegram: nextTelegram };
+                }
+                else {
+                    const nextChannels = { ...nextCfg.channels };
+                    delete nextChannels.telegram;
+                    if (Object.keys(nextChannels).length > 0) {
+                        nextCfg.channels = nextChannels;
+                    }
+                    else {
+                        delete nextCfg.channels;
+                    }
+                }
+            }
+            const resolved = resolveTelegramAccount({
+                cfg: changed ? nextCfg : cfg,
+                accountId,
+            });
+            const loggedOut = resolved.tokenSource === "none";
+            if (changed) {
+                await getTelegramRuntime().config.writeConfigFile(nextCfg);
+            }
+            return { cleared, envToken: Boolean(envToken), loggedOut };
+        },
+    },
+};

package/extensions/telegram/src/runtime.js

@@ -0,0 +1,10 @@
+let runtime = null;
+export function setTelegramRuntime(next) {
+    runtime = next;
+}
+export function getTelegramRuntime() {
+    if (!runtime) {
+        throw new Error("Telegram runtime not initialized");
+    }
+    return runtime;
+}

package/extensions/thread-ownership/index.ts

@@ -0,0 +1,133 @@
+import type { PoolBotConfig, PoolBotPluginApi } from "poolbot/plugin-sdk";
+
+type ThreadOwnershipConfig = {
+  forwarderUrl?: string;
+  abTestChannels?: string[];
+};
+
+type AgentEntry = NonNullable<NonNullable<PoolBotConfig["agents"]>["list"]>[number];
+
+// In-memory set of {channel}:{thread} keys where this agent was @-mentioned.
+// Entries expire after 5 minutes.
+const mentionedThreads = new Map<string, number>();
+const MENTION_TTL_MS = 5 * 60 * 1000;
+
+function cleanExpiredMentions(): void {
+  const now = Date.now();
+  for (const [key, ts] of mentionedThreads) {
+    if (now - ts > MENTION_TTL_MS) {
+      mentionedThreads.delete(key);
+    }
+  }
+}
+
+function resolveOwnershipAgent(config: PoolBotConfig): { id: string; name: string } {
+  const list = Array.isArray(config.agents?.list)
+    ? config.agents.list.filter((entry): entry is AgentEntry =>
+        Boolean(entry && typeof entry === "object"),
+      )
+    : [];
+  const selected = list.find((entry) => entry.default === true) ?? list[0];
+
+  const id =
+    typeof selected?.id === "string" && selected.id.trim() ? selected.id.trim() : "unknown";
+  const identityName =
+    typeof selected?.identity?.name === "string" ? selected.identity.name.trim() : "";
+  const fallbackName = typeof selected?.name === "string" ? selected.name.trim() : "";
+  const name = identityName || fallbackName;
+
+  return { id, name };
+}
+
+export default function register(api: PoolBotPluginApi) {
+  const pluginCfg = (api.pluginConfig ?? {}) as ThreadOwnershipConfig;
+  const forwarderUrl = (
+    pluginCfg.forwarderUrl ??
+    process.env.SLACK_FORWARDER_URL ??
+    "http://slack-forwarder:8750"
+  ).replace(/\/$/, "");
+
+  const abTestChannels = new Set(
+    pluginCfg.abTestChannels ??
+      process.env.THREAD_OWNERSHIP_CHANNELS?.split(",").filter(Boolean) ??
+      [],
+  );
+
+  const { id: agentId, name: agentName } = resolveOwnershipAgent(api.config);
+  const botUserId = process.env.SLACK_BOT_USER_ID ?? "";
+
+  // ---------------------------------------------------------------------------
+  // message_received: track @-mentions so the agent can reply even if it
+  // doesn't own the thread.
+  // ---------------------------------------------------------------------------
+  api.on("message_received", async (event, ctx) => {
+    if (ctx.channelId !== "slack") return;
+
+    const text = event.content ?? "";
+    const threadTs = (event.metadata?.threadTs as string) ?? "";
+    const channelId = (event.metadata?.channelId as string) ?? ctx.conversationId ?? "";
+
+    if (!threadTs || !channelId) return;
+
+    // Check if this agent was @-mentioned.
+    const mentioned =
+      (agentName && text.includes(`@${agentName}`)) ||
+      (botUserId && text.includes(`<@${botUserId}>`));
+
+    if (mentioned) {
+      cleanExpiredMentions();
+      mentionedThreads.set(`${channelId}:${threadTs}`, Date.now());
+    }
+  });
+
+  // ---------------------------------------------------------------------------
+  // message_sending: check thread ownership before sending to Slack.
+  // Returns { cancel: true } if another agent owns the thread.
+  // ---------------------------------------------------------------------------
+  api.on("message_sending", async (event, ctx) => {
+    if (ctx.channelId !== "slack") return;
+
+    const threadTs = (event.metadata?.threadTs as string) ?? "";
+    const channelId = (event.metadata?.channelId as string) ?? event.to;
+
+    // Top-level messages (no thread) are always allowed.
+    if (!threadTs) return;
+
+    // Only enforce in A/B test channels (if set is empty, skip entirely).
+    if (abTestChannels.size > 0 && !abTestChannels.has(channelId)) return;
+
+    // If this agent was @-mentioned in this thread recently, skip ownership check.
+    cleanExpiredMentions();
+    if (mentionedThreads.has(`${channelId}:${threadTs}`)) return;
+
+    // Try to claim ownership via the forwarder HTTP API.
+    try {
+      const resp = await fetch(`${forwarderUrl}/api/v1/ownership/${channelId}/${threadTs}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ agent_id: agentId }),
+        signal: AbortSignal.timeout(3000),
+      });
+
+      if (resp.ok) {
+        // We own it (or just claimed it), proceed.
+        return;
+      }
+
+      if (resp.status === 409) {
+        // Another agent owns this thread — cancel the send.
+        const body = (await resp.json()) as { owner?: string };
+        api.logger.info?.(
+          `thread-ownership: cancelled send to ${channelId}:${threadTs} — owned by ${body.owner}`,
+        );
+        return { cancel: true };
+      }
+
+      // Unexpected status — fail open.
+      api.logger.warn?.(`thread-ownership: unexpected status ${resp.status}, allowing send`);
+    } catch (err) {
+      // Network error — fail open.
+      api.logger.warn?.(`thread-ownership: ownership check failed (${String(err)}), allowing send`);
+    }
+  });
+}

package/extensions/tlon/src/account-fields.ts

@@ -0,0 +1,25 @@
+export type TlonAccountFieldsInput = {
+  ship?: string;
+  url?: string;
+  code?: string;
+  allowPrivateNetwork?: boolean;
+  groupChannels?: string[];
+  dmAllowlist?: string[];
+  autoDiscoverChannels?: boolean;
+};
+
+export function buildTlonAccountFields(input: TlonAccountFieldsInput) {
+  return {
+    ...(input.ship ? { ship: input.ship } : {}),
+    ...(input.url ? { url: input.url } : {}),
+    ...(input.code ? { code: input.code } : {}),
+    ...(typeof input.allowPrivateNetwork === "boolean"
+      ? { allowPrivateNetwork: input.allowPrivateNetwork }
+      : {}),
+    ...(input.groupChannels ? { groupChannels: input.groupChannels } : {}),
+    ...(input.dmAllowlist ? { dmAllowlist: input.dmAllowlist } : {}),
+    ...(typeof input.autoDiscoverChannels === "boolean"
+      ? { autoDiscoverChannels: input.autoDiscoverChannels }
+      : {}),
+  };
+}

package/extensions/tlon/src/urbit/base-url.ts

@@ -0,0 +1,57 @@
+import { isBlockedHostname, isPrivateIpAddress } from "poolbot/plugin-sdk";
+
+export type UrbitBaseUrlValidation =
+  | { ok: true; baseUrl: string; hostname: string }
+  | { ok: false; error: string };
+
+function hasScheme(value: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(value);
+}
+
+export function validateUrbitBaseUrl(raw: string): UrbitBaseUrlValidation {
+  const trimmed = String(raw ?? "").trim();
+  if (!trimmed) {
+    return { ok: false, error: "Required" };
+  }
+
+  const candidate = hasScheme(trimmed) ? trimmed : `https://${trimmed}`;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    return { ok: false, error: "Invalid URL" };
+  }
+
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    return { ok: false, error: "URL must use http:// or https://" };
+  }
+
+  if (parsed.username || parsed.password) {
+    return { ok: false, error: "URL must not include credentials" };
+  }
+
+  const hostname = parsed.hostname.trim().toLowerCase().replace(/\.$/, "");
+  if (!hostname) {
+    return { ok: false, error: "Invalid hostname" };
+  }
+
+  // Normalize to origin so callers can't smuggle paths/query fragments into the base URL,
+  // and strip a trailing dot from the hostname (DNS root label).
+  const isIpv6 = hostname.includes(":");
+  const host = parsed.port
+    ? `${isIpv6 ? `[${hostname}]` : hostname}:${parsed.port}`
+    : isIpv6
+      ? `[${hostname}]`
+      : hostname;
+
+  return { ok: true, baseUrl: `${parsed.protocol}//${host}`, hostname };
+}
+
+export function isBlockedUrbitHostname(hostname: string): boolean {
+  const normalized = hostname.trim().toLowerCase().replace(/\.$/, "");
+  if (!normalized) {
+    return false;
+  }
+  return isBlockedHostname(normalized) || isPrivateIpAddress(normalized);
+}