@poolzin/pool-bot 2026.2.0 → 2026.2.1

package/dist/infra/heartbeat-runner.js

@@ -5,23 +5,23 @@ import { resolveUserTimezone } from "../agents/date-time.js";
 import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import { DEFAULT_HEARTBEAT_FILENAME } from "../agents/workspace.js";
 import { DEFAULT_HEARTBEAT_ACK_MAX_CHARS, DEFAULT_HEARTBEAT_EVERY, isHeartbeatContentEffectivelyEmpty, resolveHeartbeatPrompt as resolveHeartbeatPromptText, stripHeartbeatToken, } from "../auto-reply/heartbeat.js";
-import { HEARTBEAT_TOKEN } from "../auto-reply/tokens.js";
 import { getReplyFromConfig } from "../auto-reply/reply.js";
+import { HEARTBEAT_TOKEN } from "../auto-reply/tokens.js";
 import { getChannelPlugin } from "../channels/plugins/index.js";
 import { parseDurationMs } from "../cli/parse-duration.js";
 import { loadConfig } from "../config/config.js";
 import { canonicalizeMainSessionAlias, loadSessionStore, resolveAgentIdFromSessionKey, resolveAgentMainSessionKey, resolveStorePath, saveSessionStore, updateSessionStore, } from "../config/sessions.js";
-import { formatErrorMessage } from "../infra/errors.js";
-import { peekSystemEvents } from "../infra/system-events.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { getQueueSize } from "../process/command-queue.js";
-import { defaultRuntime } from "../runtime.js";
 import { normalizeAgentId, toAgentStoreSessionKey } from "../routing/session-key.js";
+import { defaultRuntime } from "../runtime.js";
+import { formatErrorMessage } from "./errors.js";
 import { emitHeartbeatEvent, resolveIndicatorType } from "./heartbeat-events.js";
 import { resolveHeartbeatVisibility } from "./heartbeat-visibility.js";
 import { requestHeartbeatNow, setHeartbeatWakeHandler, } from "./heartbeat-wake.js";
 import { deliverOutboundPayloads } from "./outbound/deliver.js";
 import { resolveHeartbeatDeliveryTarget, resolveHeartbeatSenderContext, } from "./outbound/targets.js";
+import { peekSystemEvents } from "./system-events.js";
 const log = createSubsystemLogger("gateway/heartbeat");
 let heartbeatsEnabled = true;
 export function setHeartbeatsEnabled(enabled) {
@@ -35,6 +35,11 @@ const ACTIVE_HOURS_TIME_PATTERN = /^([01]\d|2[0-3]|24):([0-5]\d)$/;
 const EXEC_EVENT_PROMPT = "An async command you ran earlier has completed. The result is shown in the system messages above. " +
     "Please relay the command output to the user in a helpful way. If the command succeeded, share the relevant output. " +
     "If it failed, explain what went wrong.";
+// Prompt used when a scheduled cron job has fired and injected a system event.
+// This overrides the standard heartbeat prompt so the model relays the scheduled
+// reminder instead of responding with "HEARTBEAT_OK".
+const CRON_EVENT_PROMPT = "A scheduled reminder has been triggered. The reminder message is shown in the system messages above. " +
+    "Please relay this reminder to the user in a helpful and friendly way.";
 function resolveActiveHoursTimezone(cfg, raw) {
     const trimmed = raw?.trim();
     if (!trimmed || trimmed === "user") {
@@ -53,16 +58,19 @@ function resolveActiveHoursTimezone(cfg, raw) {
     }
 }
 function parseActiveHoursTime(opts, raw) {
-    if (!raw || !ACTIVE_HOURS_TIME_PATTERN.test(raw))
+    if (!raw || !ACTIVE_HOURS_TIME_PATTERN.test(raw)) {
         return null;
+    }
     const [hourStr, minuteStr] = raw.split(":");
     const hour = Number(hourStr);
     const minute = Number(minuteStr);
-    if (!Number.isFinite(hour) || !Number.isFinite(minute))
+    if (!Number.isFinite(hour) || !Number.isFinite(minute)) {
         return null;
+    }
     if (hour === 24) {
-        if (!opts.allow24 || minute !== 0)
+        if (!opts.allow24 || minute !== 0) {
             return null;
+        }
         return 24 * 60;
     }
     return hour * 60 + minute;
@@ -77,13 +85,15 @@ function resolveMinutesInTimeZone(nowMs, timeZone) {
         }).formatToParts(new Date(nowMs));
         const map = {};
         for (const part of parts) {
-            if (part.type !== "literal")
+            if (part.type !== "literal") {
                 map[part.type] = part.value;
+            }
         }
         const hour = Number(map.hour);
         const minute = Number(map.minute);
-        if (!Number.isFinite(hour) || !Number.isFinite(minute))
+        if (!Number.isFinite(hour) || !Number.isFinite(minute)) {
             return null;
+        }
         return hour * 60 + minute;
     }
     catch {
@@ -92,18 +102,22 @@ function resolveMinutesInTimeZone(nowMs, timeZone) {
 }
 function isWithinActiveHours(cfg, heartbeat, nowMs) {
     const active = heartbeat?.activeHours;
-    if (!active)
+    if (!active) {
         return true;
+    }
     const startMin = parseActiveHoursTime({ allow24: false }, active.start);
     const endMin = parseActiveHoursTime({ allow24: true }, active.end);
-    if (startMin === null || endMin === null)
+    if (startMin === null || endMin === null) {
         return true;
-    if (startMin === endMin)
+    }
+    if (startMin === endMin) {
         return true;
+    }
     const timeZone = resolveActiveHoursTimezone(cfg, active.timezone);
     const currentMin = resolveMinutesInTimeZone(nowMs ?? Date.now(), timeZone);
-    if (currentMin === null)
+    if (currentMin === null) {
         return true;
+    }
     if (endMin > startMin) {
         return currentMin >= startMin && currentMin < endMin;
     }
@@ -124,11 +138,13 @@ export function isHeartbeatEnabledForAgent(cfg, agentId) {
 }
 function resolveHeartbeatConfig(cfg, agentId) {
     const defaults = cfg.agents?.defaults?.heartbeat;
-    if (!agentId)
+    if (!agentId) {
         return defaults;
+    }
     const overrides = resolveAgentConfig(cfg, agentId)?.heartbeat;
-    if (!defaults && !overrides)
+    if (!defaults && !overrides) {
         return overrides;
+    }
     return { ...defaults, ...overrides };
 }
 export function resolveHeartbeatSummaryForAgent(cfg, agentId) {
@@ -185,11 +201,13 @@ export function resolveHeartbeatIntervalMs(cfg, overrideEvery, heartbeat) {
         heartbeat?.every ??
         cfg.agents?.defaults?.heartbeat?.every ??
         DEFAULT_HEARTBEAT_EVERY;
-    if (!raw)
+    if (!raw) {
         return null;
+    }
     const trimmed = String(raw).trim();
-    if (!trimmed)
+    if (!trimmed) {
         return null;
+    }
     let ms;
     try {
         ms = parseDurationMs(trimmed, { defaultUnit: "m" });
@@ -197,8 +215,9 @@ export function resolveHeartbeatIntervalMs(cfg, overrideEvery, heartbeat) {
     catch {
         return null;
     }
-    if (ms <= 0)
+    if (ms <= 0) {
         return null;
+    }
     return ms;
 }
 export function resolveHeartbeatPrompt(cfg, heartbeat) {
@@ -215,7 +234,9 @@ function resolveHeartbeatSession(cfg, agentId, heartbeat) {
     const resolvedAgentId = normalizeAgentId(agentId ?? resolveDefaultAgentId(cfg));
     const mainSessionKey = scope === "global" ? "global" : resolveAgentMainSessionKey({ cfg, agentId: resolvedAgentId });
     const storeAgentId = scope === "global" ? resolveDefaultAgentId(cfg) : resolvedAgentId;
-    const storePath = resolveStorePath(sessionCfg?.store, { agentId: storeAgentId });
+    const storePath = resolveStorePath(sessionCfg?.store, {
+        agentId: storeAgentId,
+    });
     const store = loadSessionStore(storePath);
     const mainEntry = store[mainSessionKey];
     if (scope === "global") {
@@ -242,20 +263,28 @@ function resolveHeartbeatSession(cfg, agentId, heartbeat) {
     if (canonical !== "global") {
         const sessionAgentId = resolveAgentIdFromSessionKey(canonical);
         if (sessionAgentId === normalizeAgentId(resolvedAgentId)) {
-            return { sessionKey: canonical, storePath, store, entry: store[canonical] };
+            return {
+                sessionKey: canonical,
+                storePath,
+                store,
+                entry: store[canonical],
+            };
         }
     }
     return { sessionKey: mainSessionKey, storePath, store, entry: mainEntry };
 }
 function resolveHeartbeatReplyPayload(replyResult) {
-    if (!replyResult)
+    if (!replyResult) {
         return undefined;
-    if (!Array.isArray(replyResult))
+    }
+    if (!Array.isArray(replyResult)) {
         return replyResult;
+    }
     for (let idx = replyResult.length - 1; idx >= 0; idx -= 1) {
         const payload = replyResult[idx];
-        if (!payload)
+        if (!payload) {
             continue;
+        }
         if (payload.text || payload.mediaUrl || (payload.mediaUrls && payload.mediaUrls.length > 0)) {
             return payload;
         }
@@ -271,22 +300,27 @@ function resolveHeartbeatReasoningPayloads(replyResult) {
 }
 async function restoreHeartbeatUpdatedAt(params) {
     const { storePath, sessionKey, updatedAt } = params;
-    if (typeof updatedAt !== "number")
+    if (typeof updatedAt !== "number") {
         return;
+    }
     const store = loadSessionStore(storePath);
     const entry = store[sessionKey];
-    if (!entry)
+    if (!entry) {
         return;
+    }
     const nextUpdatedAt = Math.max(entry.updatedAt ?? 0, updatedAt);
-    if (entry.updatedAt === nextUpdatedAt)
+    if (entry.updatedAt === nextUpdatedAt) {
         return;
+    }
     await updateSessionStore(storePath, (nextStore) => {
         const nextEntry = nextStore[sessionKey] ?? entry;
-        if (!nextEntry)
+        if (!nextEntry) {
             return;
+        }
         const resolvedUpdatedAt = Math.max(nextEntry.updatedAt ?? 0, updatedAt);
-        if (nextEntry.updatedAt === resolvedUpdatedAt)
+        if (nextEntry.updatedAt === resolvedUpdatedAt) {
             return;
+        }
         nextStore[sessionKey] = { ...nextEntry, updatedAt: resolvedUpdatedAt };
     });
 }
@@ -332,13 +366,17 @@ export async function runHeartbeatOnce(opts) {
     }
     // Skip heartbeat if HEARTBEAT.md exists but has no actionable content.
     // This saves API calls/costs when the file is effectively empty (only comments/headers).
-    // EXCEPTION: Don't skip for exec events - they have pending system events to process.
+    // EXCEPTION: Don't skip for exec events or cron events - they have pending system events
+    // to process regardless of HEARTBEAT.md content.
     const isExecEventReason = opts.reason === "exec-event";
+    const isCronEventReason = Boolean(opts.reason?.startsWith("cron:"));
     const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
     const heartbeatFilePath = path.join(workspaceDir, DEFAULT_HEARTBEAT_FILENAME);
     try {
         const heartbeatFileContent = await fs.readFile(heartbeatFilePath, "utf-8");
-        if (isHeartbeatContentEffectivelyEmpty(heartbeatFileContent) && !isExecEventReason) {
+        if (isHeartbeatContentEffectivelyEmpty(heartbeatFileContent) &&
+            !isExecEventReason &&
+            !isCronEventReason) {
             emitHeartbeatEvent({
                 status: "skipped",
                 reason: "empty-heartbeat-file",
@@ -354,6 +392,20 @@ export async function runHeartbeatOnce(opts) {
     const { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId, heartbeat);
     const previousUpdatedAt = entry?.updatedAt;
     const delivery = resolveHeartbeatDeliveryTarget({ cfg, entry, heartbeat });
+    const heartbeatAccountId = heartbeat?.accountId?.trim();
+    if (delivery.reason === "unknown-account") {
+        log.warn("heartbeat: unknown accountId", {
+            accountId: delivery.accountId ?? heartbeatAccountId ?? null,
+            target: heartbeat?.target ?? "last",
+        });
+    }
+    else if (heartbeatAccountId) {
+        log.info("heartbeat: using explicit accountId", {
+            accountId: delivery.accountId ?? heartbeatAccountId,
+            target: heartbeat?.target ?? "last",
+            channel: delivery.channel,
+        });
+    }
     const visibility = delivery.channel !== "none"
         ? resolveHeartbeatVisibility({
             cfg,
@@ -362,19 +414,28 @@ export async function runHeartbeatOnce(opts) {
         })
         : { showOk: false, showAlerts: true, useIndicator: true };
     const { sender } = resolveHeartbeatSenderContext({ cfg, entry, delivery });
-    const responsePrefix = resolveEffectiveMessagesConfig(cfg, agentId).responsePrefix;
-    // Check if this is an exec event with pending exec completion system events.
+    const responsePrefix = resolveEffectiveMessagesConfig(cfg, agentId, {
+        channel: delivery.channel !== "none" ? delivery.channel : undefined,
+        accountId: delivery.accountId,
+    }).responsePrefix;
+    // Check if this is an exec event or cron event with pending system events.
     // If so, use a specialized prompt that instructs the model to relay the result
     // instead of the standard heartbeat prompt with "reply HEARTBEAT_OK".
     const isExecEvent = opts.reason === "exec-event";
-    const pendingEvents = isExecEvent ? peekSystemEvents(sessionKey) : [];
+    const isCronEvent = Boolean(opts.reason?.startsWith("cron:"));
+    const pendingEvents = isExecEvent || isCronEvent ? peekSystemEvents(sessionKey) : [];
     const hasExecCompletion = pendingEvents.some((evt) => evt.includes("Exec finished"));
-    const prompt = hasExecCompletion ? EXEC_EVENT_PROMPT : resolveHeartbeatPrompt(cfg, heartbeat);
+    const hasCronEvents = isCronEvent && pendingEvents.length > 0;
+    const prompt = hasExecCompletion
+        ? EXEC_EVENT_PROMPT
+        : hasCronEvents
+            ? CRON_EVENT_PROMPT
+            : resolveHeartbeatPrompt(cfg, heartbeat);
     const ctx = {
         Body: prompt,
         From: sender,
         To: sender,
-        Provider: hasExecCompletion ? "exec-event" : "heartbeat",
+        Provider: hasExecCompletion ? "exec-event" : hasCronEvents ? "cron-event" : "heartbeat",
         SessionKey: sessionKey,
     };
     if (!visibility.showAlerts && !visibility.showOk && !visibility.useIndicator) {
@@ -383,14 +444,16 @@ export async function runHeartbeatOnce(opts) {
             reason: "alerts-disabled",
             durationMs: Date.now() - startedAt,
             channel: delivery.channel !== "none" ? delivery.channel : undefined,
+            accountId: delivery.accountId,
         });
         return { status: "skipped", reason: "alerts-disabled" };
     }
     const heartbeatOkText = responsePrefix ? `${responsePrefix} ${HEARTBEAT_TOKEN}` : HEARTBEAT_TOKEN;
     const canAttemptHeartbeatOk = Boolean(visibility.showOk && delivery.channel !== "none" && delivery.to);
     const maybeSendHeartbeatOk = async () => {
-        if (!canAttemptHeartbeatOk || delivery.channel === "none" || !delivery.to)
+        if (!canAttemptHeartbeatOk || delivery.channel === "none" || !delivery.to) {
             return false;
+        }
         const heartbeatPlugin = getChannelPlugin(delivery.channel);
         if (heartbeatPlugin?.heartbeat?.checkReady) {
             const readiness = await heartbeatPlugin.heartbeat.checkReady({
@@ -398,8 +461,9 @@ export async function runHeartbeatOnce(opts) {
                 accountId: delivery.accountId,
                 deps: opts.deps,
             });
-            if (!readiness.ok)
+            if (!readiness.ok) {
                 return false;
+            }
         }
         await deliverOutboundPayloads({
             cfg,
@@ -431,6 +495,7 @@ export async function runHeartbeatOnce(opts) {
                 reason: opts.reason,
                 durationMs: Date.now() - startedAt,
                 channel: delivery.channel !== "none" ? delivery.channel : undefined,
+                accountId: delivery.accountId,
                 silent: !okSent,
                 indicatorType: visibility.useIndicator ? resolveIndicatorType("ok-empty") : undefined,
             });
@@ -462,6 +527,7 @@ export async function runHeartbeatOnce(opts) {
                 reason: opts.reason,
                 durationMs: Date.now() - startedAt,
                 channel: delivery.channel !== "none" ? delivery.channel : undefined,
+                accountId: delivery.accountId,
                 silent: !okSent,
                 indicatorType: visibility.useIndicator ? resolveIndicatorType("ok-token") : undefined,
             });
@@ -491,6 +557,7 @@ export async function runHeartbeatOnce(opts) {
                 durationMs: Date.now() - startedAt,
                 hasMedia: false,
                 channel: delivery.channel !== "none" ? delivery.channel : undefined,
+                accountId: delivery.accountId,
             });
             return { status: "ran", durationMs: Date.now() - startedAt };
         }
@@ -508,11 +575,16 @@ export async function runHeartbeatOnce(opts) {
                 preview: previewText?.slice(0, 200),
                 durationMs: Date.now() - startedAt,
                 hasMedia: mediaUrls.length > 0,
+                accountId: delivery.accountId,
             });
             return { status: "ran", durationMs: Date.now() - startedAt };
         }
         if (!visibility.showAlerts) {
-            await restoreHeartbeatUpdatedAt({ storePath, sessionKey, updatedAt: previousUpdatedAt });
+            await restoreHeartbeatUpdatedAt({
+                storePath,
+                sessionKey,
+                updatedAt: previousUpdatedAt,
+            });
             emitHeartbeatEvent({
                 status: "skipped",
                 reason: "alerts-disabled",
@@ -520,6 +592,7 @@ export async function runHeartbeatOnce(opts) {
                 durationMs: Date.now() - startedAt,
                 channel: delivery.channel,
                 hasMedia: mediaUrls.length > 0,
+                accountId: delivery.accountId,
                 indicatorType: visibility.useIndicator ? resolveIndicatorType("sent") : undefined,
             });
             return { status: "ran", durationMs: Date.now() - startedAt };
@@ -540,6 +613,7 @@ export async function runHeartbeatOnce(opts) {
                     durationMs: Date.now() - startedAt,
                     hasMedia: mediaUrls.length > 0,
                     channel: delivery.channel,
+                    accountId: delivery.accountId,
                 });
                 log.info("heartbeat: channel not ready", {
                     channel: delivery.channel,
@@ -586,6 +660,7 @@ export async function runHeartbeatOnce(opts) {
             durationMs: Date.now() - startedAt,
             hasMedia: mediaUrls.length > 0,
             channel: delivery.channel,
+            accountId: delivery.accountId,
             indicatorType: visibility.useIndicator ? resolveIndicatorType("sent") : undefined,
         });
         return { status: "ran", durationMs: Date.now() - startedAt };
@@ -597,6 +672,7 @@ export async function runHeartbeatOnce(opts) {
             reason,
             durationMs: Date.now() - startedAt,
             channel: delivery.channel !== "none" ? delivery.channel : undefined,
+            accountId: delivery.accountId,
             indicatorType: visibility.useIndicator ? resolveIndicatorType("failed") : undefined,
         });
         log.error(`heartbeat failed: ${reason}`, { error: reason });
@@ -624,22 +700,26 @@ export function startHeartbeatRunner(opts) {
         return now + intervalMs;
     };
     const scheduleNext = () => {
-        if (state.stopped)
+        if (state.stopped) {
             return;
+        }
         if (state.timer) {
             clearTimeout(state.timer);
             state.timer = null;
         }
-        if (state.agents.size === 0)
+        if (state.agents.size === 0) {
             return;
+        }
         const now = Date.now();
         let nextDue = Number.POSITIVE_INFINITY;
         for (const agent of state.agents.values()) {
-            if (agent.nextDueMs < nextDue)
+            if (agent.nextDueMs < nextDue) {
                 nextDue = agent.nextDueMs;
+            }
         }
-        if (!Number.isFinite(nextDue))
+        if (!Number.isFinite(nextDue)) {
             return;
+        }
         const delay = Math.max(0, nextDue - now);
         state.timer = setTimeout(() => {
             requestHeartbeatNow({ reason: "interval", coalesceMs: 0 });
@@ -647,8 +727,9 @@ export function startHeartbeatRunner(opts) {
         state.timer.unref?.();
     };
     const updateConfig = (cfg) => {
-        if (state.stopped)
+        if (state.stopped) {
             return;
+        }
         const now = Date.now();
         const prevAgents = state.agents;
         const prevEnabled = prevAgents.size > 0;
@@ -656,8 +737,9 @@ export function startHeartbeatRunner(opts) {
         const intervals = [];
         for (const agent of resolveHeartbeatAgents(cfg)) {
             const intervalMs = resolveHeartbeatIntervalMs(cfg, undefined, agent.heartbeat);
-            if (!intervalMs)
+            if (!intervalMs) {
                 continue;
+            }
             intervals.push(intervalMs);
             const prevState = prevAgents.get(agent.agentId);
             const nextDueMs = resolveNextDue(now, intervalMs, prevState);
@@ -693,10 +775,16 @@ export function startHeartbeatRunner(opts) {
     };
     const run = async (params) => {
         if (!heartbeatsEnabled) {
-            return { status: "skipped", reason: "disabled" };
+            return {
+                status: "skipped",
+                reason: "disabled",
+            };
         }
         if (state.agents.size === 0) {
-            return { status: "skipped", reason: "disabled" };
+            return {
+                status: "skipped",
+                reason: "disabled",
+            };
         }
         const reason = params?.reason;
         const isInterval = reason === "interval";
@@ -721,12 +809,14 @@ export function startHeartbeatRunner(opts) {
                 agent.lastRunMs = now;
                 agent.nextDueMs = now + agent.intervalMs;
             }
-            if (res.status === "ran")
+            if (res.status === "ran") {
                 ran = true;
+            }
         }
         scheduleNext();
-        if (ran)
+        if (ran) {
             return { status: "ran", durationMs: Date.now() - startedAt };
+        }
         return { status: "skipped", reason: isInterval ? "not-due" : "disabled" };
     };
     setHeartbeatWakeHandler(async (params) => run({ reason: params.reason }));
@@ -734,8 +824,9 @@ export function startHeartbeatRunner(opts) {
     const cleanup = () => {
         state.stopped = true;
         setHeartbeatWakeHandler(null);
-        if (state.timer)
+        if (state.timer) {
             clearTimeout(state.timer);
+        }
         state.timer = null;
     };
     opts.abortSignal?.addEventListener("abort", cleanup, { once: true });

package/dist/infra/home-dir.js

@@ -0,0 +1,54 @@
+import os from "node:os";
+import path from "node:path";
+function normalize(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function resolveEffectiveHomeDir(env = process.env, homedir = os.homedir) {
+    const raw = resolveRawHomeDir(env, homedir);
+    return raw ? path.resolve(raw) : undefined;
+}
+function resolveRawHomeDir(env, homedir) {
+    const explicitHome = normalize(env.CLAWDBOT_HOME);
+    if (explicitHome) {
+        if (explicitHome === "~" || explicitHome.startsWith("~/") || explicitHome.startsWith("~\\")) {
+            const fallbackHome = normalize(env.HOME) ?? normalize(env.USERPROFILE) ?? normalizeSafe(homedir);
+            if (fallbackHome) {
+                return explicitHome.replace(/^~(?=$|[\\/])/, fallbackHome);
+            }
+            return undefined;
+        }
+        return explicitHome;
+    }
+    const envHome = normalize(env.HOME);
+    if (envHome) {
+        return envHome;
+    }
+    const userProfile = normalize(env.USERPROFILE);
+    if (userProfile) {
+        return userProfile;
+    }
+    return normalizeSafe(homedir);
+}
+function normalizeSafe(homedir) {
+    try {
+        return normalize(homedir());
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveRequiredHomeDir(env = process.env, homedir = os.homedir) {
+    return resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
+}
+export function expandHomePrefix(input, opts) {
+    if (!input.startsWith("~")) {
+        return input;
+    }
+    const home = normalize(opts?.home) ??
+        resolveEffectiveHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir);
+    if (!home) {
+        return input;
+    }
+    return input.replace(/^~(?=$|[\\/])/, home);
+}

package/dist/infra/net/fetch-guard.js

@@ -0,0 +1,122 @@
+import { closeDispatcher, createPinnedDispatcher, resolvePinnedHostname, resolvePinnedHostnameWithPolicy, } from "./ssrf.js";
+const DEFAULT_MAX_REDIRECTS = 3;
+function isRedirectStatus(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+function buildAbortSignal(params) {
+    const { timeoutMs, signal } = params;
+    if (!timeoutMs && !signal) {
+        return { signal: undefined, cleanup: () => { } };
+    }
+    if (!timeoutMs) {
+        return { signal, cleanup: () => { } };
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const onAbort = () => controller.abort();
+    if (signal) {
+        if (signal.aborted) {
+            controller.abort();
+        }
+        else {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+    }
+    const cleanup = () => {
+        clearTimeout(timeoutId);
+        if (signal) {
+            signal.removeEventListener("abort", onAbort);
+        }
+    };
+    return { signal: controller.signal, cleanup };
+}
+export async function fetchWithSsrFGuard(params) {
+    const fetcher = params.fetchImpl ?? globalThis.fetch;
+    if (!fetcher) {
+        throw new Error("fetch is not available");
+    }
+    const maxRedirects = typeof params.maxRedirects === "number" && Number.isFinite(params.maxRedirects)
+        ? Math.max(0, Math.floor(params.maxRedirects))
+        : DEFAULT_MAX_REDIRECTS;
+    const { signal, cleanup } = buildAbortSignal({
+        timeoutMs: params.timeoutMs,
+        signal: params.signal,
+    });
+    let released = false;
+    const release = async (dispatcher) => {
+        if (released) {
+            return;
+        }
+        released = true;
+        cleanup();
+        await closeDispatcher(dispatcher ?? undefined);
+    };
+    const visited = new Set();
+    let currentUrl = params.url;
+    let redirectCount = 0;
+    while (true) {
+        let parsedUrl;
+        try {
+            parsedUrl = new URL(currentUrl);
+        }
+        catch {
+            await release();
+            throw new Error("Invalid URL: must be http or https");
+        }
+        if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+            await release();
+            throw new Error("Invalid URL: must be http or https");
+        }
+        let dispatcher = null;
+        try {
+            const usePolicy = Boolean(params.policy?.allowPrivateNetwork || params.policy?.allowedHostnames?.length);
+            const pinned = usePolicy
+                ? await resolvePinnedHostnameWithPolicy(parsedUrl.hostname, {
+                    lookupFn: params.lookupFn,
+                    policy: params.policy,
+                })
+                : await resolvePinnedHostname(parsedUrl.hostname, params.lookupFn);
+            if (params.pinDns !== false) {
+                dispatcher = createPinnedDispatcher(pinned);
+            }
+            const init = {
+                ...(params.init ? { ...params.init } : {}),
+                redirect: "manual",
+                ...(dispatcher ? { dispatcher } : {}),
+                ...(signal ? { signal } : {}),
+            };
+            const response = await fetcher(parsedUrl.toString(), init);
+            if (isRedirectStatus(response.status)) {
+                const location = response.headers.get("location");
+                if (!location) {
+                    await release(dispatcher);
+                    throw new Error(`Redirect missing location header (${response.status})`);
+                }
+                redirectCount += 1;
+                if (redirectCount > maxRedirects) {
+                    await release(dispatcher);
+                    throw new Error(`Too many redirects (limit: ${maxRedirects})`);
+                }
+                const nextUrl = new URL(location, parsedUrl).toString();
+                if (visited.has(nextUrl)) {
+                    await release(dispatcher);
+                    throw new Error("Redirect loop detected");
+                }
+                visited.add(nextUrl);
+                void response.body?.cancel();
+                await closeDispatcher(dispatcher);
+                currentUrl = nextUrl;
+                continue;
+            }
+            return {
+                response,
+                finalUrl: currentUrl,
+                release: async () => release(dispatcher),
+            };
+        }
+        catch (err) {
+            await release(dispatcher);
+            throw err;
+        }
+    }
+}