@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/commands/agent.js

@@ -1,38 +1,122 @@
-import { listAgentIds, resolveAgentDir, resolveAgentModelFallbacksOverride, resolveAgentModelPrimary, resolveAgentWorkspaceDir, } from "../agents/agent-scope.js";
+import { listAgentIds, resolveAgentDir, resolveEffectiveModelFallbacks, resolveAgentModelPrimary, resolveAgentSkillsFilter, resolveAgentWorkspaceDir, } from "../agents/agent-scope.js";
 import { ensureAuthProfileStore } from "../agents/auth-profiles.js";
+import { clearSessionAuthProfileOverride } from "../agents/auth-profiles/session-override.js";
 import { runCliAgent } from "../agents/cli-runner.js";
 import { getCliSessionId } from "../agents/cli-session.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../agents/defaults.js";
+import { AGENT_LANE_SUBAGENT } from "../agents/lanes.js";
 import { loadModelCatalog } from "../agents/model-catalog.js";
 import { runWithModelFallback } from "../agents/model-fallback.js";
-import { buildAllowedModelSet, isCliProvider, modelKey, resolveConfiguredModelRef, resolveThinkingDefault, } from "../agents/model-selection.js";
+import { buildAllowedModelSet, isCliProvider, modelKey, normalizeModelRef, resolveConfiguredModelRef, resolveThinkingDefault, } from "../agents/model-selection.js";
 import { runEmbeddedPiAgent } from "../agents/pi-embedded.js";
 import { buildWorkspaceSkillSnapshot } from "../agents/skills.js";
 import { getSkillsSnapshotVersion } from "../agents/skills/refresh.js";
 import { resolveAgentTimeoutMs } from "../agents/timeout.js";
 import { ensureAgentWorkspace } from "../agents/workspace.js";
 import { formatThinkingLevels, formatXHighModelHint, normalizeThinkLevel, normalizeVerboseLevel, supportsXHighThinking, } from "../auto-reply/thinking.js";
+import { formatCliCommand } from "../cli/command-format.js";
 import { createDefaultDeps } from "../cli/deps.js";
 import { loadConfig } from "../config/config.js";
 import { resolveAgentIdFromSessionKey, resolveSessionFilePath, updateSessionStore, } from "../config/sessions.js";
 import { clearAgentRunContext, emitAgentEvent, registerAgentRunContext, } from "../infra/agent-events.js";
 import { getRemoteSkillEligibility } from "../infra/skills-remote.js";
+import { normalizeAgentId } from "../routing/session-key.js";
 import { defaultRuntime } from "../runtime.js";
-import { formatCliCommand } from "../cli/command-format.js";
 import { applyVerboseOverride } from "../sessions/level-overrides.js";
-import { resolveSendPolicy } from "../sessions/send-policy.js";
 import { applyModelOverrideToSessionEntry } from "../sessions/model-overrides.js";
-import { clearSessionAuthProfileOverride } from "../agents/auth-profiles/session-override.js";
+import { resolveSendPolicy } from "../sessions/send-policy.js";
 import { resolveMessageChannel } from "../utils/message-channel.js";
 import { deliverAgentCommandResult } from "./agent/delivery.js";
 import { resolveAgentRunContext } from "./agent/run-context.js";
-import { resolveSession } from "./agent/session.js";
 import { updateSessionStoreAfterAgentRun } from "./agent/session-store.js";
-import { normalizeAgentId } from "../routing/session-key.js";
+import { resolveSession } from "./agent/session.js";
+async function persistSessionEntry(params) {
+    params.sessionStore[params.sessionKey] = params.entry;
+    await updateSessionStore(params.storePath, (store) => {
+        store[params.sessionKey] = params.entry;
+    });
+}
+function resolveFallbackRetryPrompt(params) {
+    if (!params.isFallbackRetry) {
+        return params.body;
+    }
+    return "Continue where you left off. The previous model attempt failed or timed out.";
+}
+function runAgentAttempt(params) {
+    const effectivePrompt = resolveFallbackRetryPrompt({
+        body: params.body,
+        isFallbackRetry: params.isFallbackRetry,
+    });
+    if (isCliProvider(params.providerOverride, params.cfg)) {
+        const cliSessionId = getCliSessionId(params.sessionEntry, params.providerOverride);
+        return runCliAgent({
+            sessionId: params.sessionId,
+            sessionKey: params.sessionKey,
+            agentId: params.sessionAgentId,
+            sessionFile: params.sessionFile,
+            workspaceDir: params.workspaceDir,
+            config: params.cfg,
+            prompt: effectivePrompt,
+            provider: params.providerOverride,
+            model: params.modelOverride,
+            thinkLevel: params.resolvedThinkLevel,
+            timeoutMs: params.timeoutMs,
+            runId: params.runId,
+            extraSystemPrompt: params.opts.extraSystemPrompt,
+            cliSessionId,
+            images: params.isFallbackRetry ? undefined : params.opts.images,
+            streamParams: params.opts.streamParams,
+        });
+    }
+    const authProfileId = params.providerOverride === params.primaryProvider
+        ? params.sessionEntry?.authProfileOverride
+        : undefined;
+    return runEmbeddedPiAgent({
+        sessionId: params.sessionId,
+        sessionKey: params.sessionKey,
+        agentId: params.sessionAgentId,
+        messageChannel: params.messageChannel,
+        agentAccountId: params.runContext.accountId,
+        messageTo: params.opts.replyTo ?? params.opts.to,
+        messageThreadId: params.opts.threadId,
+        groupId: params.runContext.groupId,
+        groupChannel: params.runContext.groupChannel,
+        groupSpace: params.runContext.groupSpace,
+        spawnedBy: params.spawnedBy,
+        currentChannelId: params.runContext.currentChannelId,
+        currentThreadTs: params.runContext.currentThreadTs,
+        replyToMode: params.runContext.replyToMode,
+        hasRepliedRef: params.runContext.hasRepliedRef,
+        senderIsOwner: true,
+        sessionFile: params.sessionFile,
+        workspaceDir: params.workspaceDir,
+        config: params.cfg,
+        skillsSnapshot: params.skillsSnapshot,
+        prompt: effectivePrompt,
+        images: params.isFallbackRetry ? undefined : params.opts.images,
+        clientTools: params.opts.clientTools,
+        provider: params.providerOverride,
+        model: params.modelOverride,
+        authProfileId,
+        authProfileIdSource: authProfileId ? params.sessionEntry?.authProfileOverrideSource : undefined,
+        thinkLevel: params.resolvedThinkLevel,
+        verboseLevel: params.resolvedVerboseLevel,
+        timeoutMs: params.timeoutMs,
+        runId: params.runId,
+        lane: params.opts.lane,
+        abortSignal: params.opts.abortSignal,
+        extraSystemPrompt: params.opts.extraSystemPrompt,
+        inputProvenance: params.opts.inputProvenance,
+        streamParams: params.opts.streamParams,
+        agentDir: params.agentDir,
+        onAgentEvent: params.onAgentEvent,
+    });
+}
 export async function agentCommand(opts, runtime = defaultRuntime, deps = createDefaultDeps()) {
     const body = (opts.message ?? "").trim();
-    if (!body)
+    if (!body) {
         throw new Error("Message (--message) is required");
+    }
     if (!opts.to && !opts.sessionId && !opts.sessionKey && !opts.agentId) {
         throw new Error("Pass --to <E.164>, --session-id, or --agent to choose a session");
     }
@@ -78,10 +162,16 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
     if (opts.verbose && !verboseOverride) {
         throw new Error('Invalid verbose level. Use "on", "full", or "off".');
     }
-    const timeoutSecondsRaw = opts.timeout !== undefined ? Number.parseInt(String(opts.timeout), 10) : undefined;
+    const laneRaw = typeof opts.lane === "string" ? opts.lane.trim() : "";
+    const isSubagentLane = laneRaw === String(AGENT_LANE_SUBAGENT);
+    const timeoutSecondsRaw = opts.timeout !== undefined
+        ? Number.parseInt(String(opts.timeout), 10)
+        : isSubagentLane
+            ? 0
+            : undefined;
     if (timeoutSecondsRaw !== undefined &&
-        (Number.isNaN(timeoutSecondsRaw) || timeoutSecondsRaw <= 0)) {
-        throw new Error("--timeout must be a positive integer (seconds)");
+        (Number.isNaN(timeoutSecondsRaw) || timeoutSecondsRaw < 0)) {
+        throw new Error("--timeout must be a non-negative integer (seconds; 0 means no timeout)");
     }
     const timeoutMs = resolveAgentTimeoutMs({
         cfg,
@@ -123,11 +213,13 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
         }
         const needsSkillsSnapshot = isNewSession || !sessionEntry?.skillsSnapshot;
         const skillsSnapshotVersion = getSkillsSnapshotVersion(workspaceDir);
+        const skillFilter = resolveAgentSkillsFilter(cfg, sessionAgentId);
         const skillsSnapshot = needsSkillsSnapshot
             ? buildWorkspaceSkillSnapshot(workspaceDir, {
                 config: cfg,
                 eligibility: { remote: getRemoteSkillEligibility() },
                 snapshotVersion: skillsSnapshotVersion,
+                skillFilter,
             })
             : sessionEntry?.skillsSnapshot;
         if (skillsSnapshot && sessionStore && sessionKey && needsSkillsSnapshot) {
@@ -141,9 +233,11 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
                 updatedAt: Date.now(),
                 skillsSnapshot,
             };
-            sessionStore[sessionKey] = next;
-            await updateSessionStore(storePath, (store) => {
-                store[sessionKey] = next;
+            await persistSessionEntry({
+                sessionStore,
+                sessionKey,
+                storePath,
+                entry: next,
             });
             sessionEntry = next;
         }
@@ -153,15 +247,14 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
                 sessionEntry ?? { sessionId, updatedAt: Date.now() };
             const next = { ...entry, sessionId, updatedAt: Date.now() };
             if (thinkOverride) {
-                if (thinkOverride === "off")
-                    delete next.thinkingLevel;
-                else
-                    next.thinkingLevel = thinkOverride;
+                next.thinkingLevel = thinkOverride;
             }
             applyVerboseOverride(next, verboseOverride);
-            sessionStore[sessionKey] = next;
-            await updateSessionStore(storePath, (store) => {
-                store[sessionKey] = next;
+            await persistSessionEntry({
+                sessionStore,
+                sessionKey,
+                storePath,
+                entry: next,
             });
         }
         const agentModelPrimary = resolveAgentModelPrimary(cfg, sessionAgentId);
@@ -182,11 +275,12 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
                 },
             }
             : cfg;
-        const { provider: defaultProvider, model: defaultModel } = resolveConfiguredModelRef({
+        const configuredDefaultRef = resolveConfiguredModelRef({
             cfg: cfgForModelSelection,
             defaultProvider: DEFAULT_PROVIDER,
             defaultModel: DEFAULT_MODEL,
         });
+        const { provider: defaultProvider, model: defaultModel } = normalizeModelRef(configuredDefaultRef.provider, configuredDefaultRef.model);
         let provider = defaultProvider;
         let model = defaultModel;
         const hasAllowlist = agentCfg?.models && Object.keys(agentCfg.models).length > 0;
@@ -211,8 +305,9 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
             const overrideProvider = sessionEntry.providerOverride?.trim() || defaultProvider;
             const overrideModel = sessionEntry.modelOverride?.trim();
             if (overrideModel) {
-                const key = modelKey(overrideProvider, overrideModel);
-                if (!isCliProvider(overrideProvider, cfg) &&
+                const normalizedOverride = normalizeModelRef(overrideProvider, overrideModel);
+                const key = modelKey(normalizedOverride.provider, normalizedOverride.model);
+                if (!isCliProvider(normalizedOverride.provider, cfg) &&
                     allowedModelKeys.size > 0 &&
                     !allowedModelKeys.has(key)) {
                     const { updated } = applyModelOverrideToSessionEntry({
@@ -220,9 +315,11 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
                         selection: { provider: defaultProvider, model: defaultModel, isDefault: true },
                     });
                     if (updated) {
-                        sessionStore[sessionKey] = entry;
-                        await updateSessionStore(storePath, (store) => {
-                            store[sessionKey] = entry;
+                        await persistSessionEntry({
+                            sessionStore,
+                            sessionKey,
+                            storePath,
+                            entry,
                         });
                     }
                 }
@@ -232,12 +329,13 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
         const storedModelOverride = sessionEntry?.modelOverride?.trim();
         if (storedModelOverride) {
             const candidateProvider = storedProviderOverride || defaultProvider;
-            const key = modelKey(candidateProvider, storedModelOverride);
-            if (isCliProvider(candidateProvider, cfg) ||
+            const normalizedStored = normalizeModelRef(candidateProvider, storedModelOverride);
+            const key = modelKey(normalizedStored.provider, normalizedStored.model);
+            if (isCliProvider(normalizedStored.provider, cfg) ||
                 allowedModelKeys.size === 0 ||
                 allowedModelKeys.has(key)) {
-                provider = candidateProvider;
-                model = storedModelOverride;
+                provider = normalizedStored.provider;
+                model = normalizedStored.model;
             }
         }
         if (sessionEntry) {
@@ -281,9 +379,11 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
                 const entry = sessionEntry;
                 entry.thinkingLevel = "high";
                 entry.updatedAt = Date.now();
-                sessionStore[sessionKey] = entry;
-                await updateSessionStore(storePath, (store) => {
-                    store[sessionKey] = entry;
+                await persistSessionEntry({
+                    sessionStore,
+                    sessionKey,
+                    storePath,
+                    entry,
                 });
             }
         }
@@ -299,72 +399,48 @@ export async function agentCommand(opts, runtime = defaultRuntime, deps = create
             const runContext = resolveAgentRunContext(opts);
             const messageChannel = resolveMessageChannel(runContext.messageChannel, opts.replyChannel ?? opts.channel);
             const spawnedBy = opts.spawnedBy ?? sessionEntry?.spawnedBy;
+            // Keep fallback candidate resolution centralized so session model overrides,
+            // per-agent overrides, and default fallbacks stay consistent across callers.
+            const effectiveFallbacksOverride = resolveEffectiveModelFallbacks({
+                cfg,
+                agentId: sessionAgentId,
+                hasSessionModelOverride: Boolean(storedModelOverride),
+            });
+            // Track model fallback attempts so retries on an existing session don't
+            // re-inject the original prompt as a duplicate user message.
+            let fallbackAttemptIndex = 0;
             const fallbackResult = await runWithModelFallback({
                 cfg,
                 provider,
                 model,
                 agentDir,
-                fallbacksOverride: resolveAgentModelFallbacksOverride(cfg, sessionAgentId),
+                fallbacksOverride: effectiveFallbacksOverride,
                 run: (providerOverride, modelOverride) => {
-                    if (isCliProvider(providerOverride, cfg)) {
-                        const cliSessionId = getCliSessionId(sessionEntry, providerOverride);
-                        return runCliAgent({
-                            sessionId,
-                            sessionKey,
-                            sessionFile,
-                            workspaceDir,
-                            config: cfg,
-                            prompt: body,
-                            provider: providerOverride,
-                            model: modelOverride,
-                            thinkLevel: resolvedThinkLevel,
-                            timeoutMs,
-                            runId,
-                            extraSystemPrompt: opts.extraSystemPrompt,
-                            cliSessionId,
-                            images: opts.images,
-                            streamParams: opts.streamParams,
-                        });
-                    }
-                    const authProfileId = providerOverride === provider ? sessionEntry?.authProfileOverride : undefined;
-                    return runEmbeddedPiAgent({
+                    const isFallbackRetry = fallbackAttemptIndex > 0;
+                    fallbackAttemptIndex += 1;
+                    return runAgentAttempt({
+                        providerOverride,
+                        modelOverride,
+                        cfg,
+                        sessionEntry,
                         sessionId,
                         sessionKey,
-                        messageChannel,
-                        agentAccountId: runContext.accountId,
-                        messageTo: opts.replyTo ?? opts.to,
-                        messageThreadId: opts.threadId,
-                        groupId: runContext.groupId,
-                        groupChannel: runContext.groupChannel,
-                        groupSpace: runContext.groupSpace,
-                        spawnedBy,
-                        currentChannelId: runContext.currentChannelId,
-                        currentThreadTs: runContext.currentThreadTs,
-                        replyToMode: runContext.replyToMode,
-                        hasRepliedRef: runContext.hasRepliedRef,
-                        senderIsOwner: true,
+                        sessionAgentId,
                         sessionFile,
                         workspaceDir,
-                        config: cfg,
-                        skillsSnapshot,
-                        prompt: body,
-                        images: opts.images,
-                        clientTools: opts.clientTools,
-                        provider: providerOverride,
-                        model: modelOverride,
-                        authProfileId,
-                        authProfileIdSource: authProfileId
-                            ? sessionEntry?.authProfileOverrideSource
-                            : undefined,
-                        thinkLevel: resolvedThinkLevel,
-                        verboseLevel: resolvedVerboseLevel,
+                        body,
+                        isFallbackRetry,
+                        resolvedThinkLevel,
                         timeoutMs,
                         runId,
-                        lane: opts.lane,
-                        abortSignal: opts.abortSignal,
-                        extraSystemPrompt: opts.extraSystemPrompt,
-                        streamParams: opts.streamParams,
+                        opts,
+                        runContext,
+                        spawnedBy,
+                        messageChannel,
+                        skillsSnapshot,
+                        resolvedVerboseLevel,
                         agentDir,
+                        primaryProvider: provider,
                         onAgentEvent: (evt) => {
                             // Track lifecycle end for fallback emission below.
                             if (evt.stream === "lifecycle" &&

package/dist/commands/channels.mock-harness.js

@@ -0,0 +1,23 @@
+import { vi } from "vitest";
+export const configMocks = {
+    readConfigFileSnapshot: vi.fn(),
+    writeConfigFile: vi.fn().mockResolvedValue(undefined),
+};
+export const offsetMocks = {
+    deleteTelegramUpdateOffset: vi.fn().mockResolvedValue(undefined),
+};
+vi.mock("../config/config.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        readConfigFileSnapshot: configMocks.readConfigFileSnapshot,
+        writeConfigFile: configMocks.writeConfigFile,
+    };
+});
+vi.mock("../telegram/update-offset-store.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        deleteTelegramUpdateOffset: offsetMocks.deleteTelegramUpdateOffset,
+    };
+});

package/dist/commands/daemon-install-runtime-warning.js

@@ -0,0 +1,11 @@
+import { renderSystemNodeWarning, resolveSystemNodeInfo } from "../daemon/runtime-paths.js";
+export async function emitNodeRuntimeWarning(params) {
+    if (params.runtime !== "node") {
+        return;
+    }
+    const systemNode = await resolveSystemNodeInfo({ env: params.env });
+    const warning = renderSystemNodeWarning(systemNode, params.nodeProgram);
+    if (warning) {
+        params.warn?.(warning, params.title);
+    }
+}

package/dist/commands/onboard-helpers.js

@@ -85,11 +85,11 @@ export function validateGatewayPasswordInput(value) {
 export function printWizardHeader(runtime) {
     const header = [
         "▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄",
-        "██░▄▄▄░██░▄▄░██░▄▄▄██░▀██░██░▄▄▀██░████░▄▄▀██░███░██",
-        "██░███░██░▀▀░██░▄▄▄██░█░█░██░█████░████░▀▀░██░█░█░██",
-        "██░▀▀▀░██░█████░▀▀▀██░██▄░██░▀▀▄██░▀▀░█░██░██▄▀▄▀▄██",
+        "██░▄▄░███░▄▄▄░██░▄▄▄░██░██████░▄▄▀░██░▄▄▄░██▀▀░▀▀███",
+        "██░▀▀░███░███░██░███░██░██████░██▄░██░███░████░█████",
+        "██░██████░▀▀▀░██░▀▀▀░██░▀▀▀░██░▀▀▀░██░▀▀▀░████░█████",
         "▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀",
-        "                  🦞 POOL BOT 🦞                    ",
+        "                  🎱 POOL BOT 🎱                    ",
         " ",
     ].join("\n");
     runtime.log(header);

package/dist/commands/sessions.test-helpers.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { vi } from "vitest";
+export function mockSessionsConfig() {
+    vi.mock("../config/config.js", async (importOriginal) => {
+        const actual = await importOriginal();
+        return {
+            ...actual,
+            loadConfig: () => ({
+                agents: {
+                    defaults: {
+                        model: { primary: "pi:opus" },
+                        models: { "pi:opus": {} },
+                        contextTokens: 32000,
+                    },
+                },
+            }),
+        };
+    });
+}
+export function makeRuntime(params) {
+    const logs = [];
+    const errors = [];
+    const throwOnError = params?.throwOnError ?? false;
+    return {
+        runtime: {
+            log: (msg) => logs.push(String(msg)),
+            error: (msg) => {
+                errors.push(String(msg));
+                if (throwOnError) {
+                    throw new Error(String(msg));
+                }
+            },
+            exit: (code) => {
+                throw new Error(`exit ${code}`);
+            },
+        },
+        logs,
+        errors,
+    };
+}
+export function writeStore(data, prefix = "sessions") {
+    const file = path.join(os.tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(16).slice(2)}.json`);
+    fs.writeFileSync(file, JSON.stringify(data, null, 2));
+    return file;
+}
+export async function runSessionsJson(run, store, options) {
+    const { runtime, logs } = makeRuntime();
+    try {
+        await run({
+            store,
+            json: true,
+            active: options?.active,
+        }, runtime);
+    }
+    finally {
+        fs.rmSync(store, { force: true });
+    }
+    return JSON.parse(logs[0] ?? "{}");
+}

package/dist/compat/legacy-names.js

@@ -1,6 +1,6 @@
-export const LEGACY_PROJECT_NAME = "poolbot";
+export const LEGACY_PROJECT_NAME = "clawdbot";
 export const LEGACY_MANIFEST_KEY = LEGACY_PROJECT_NAME;
-export const MANIFEST_KEY = LEGACY_PROJECT_NAME;
+export const MANIFEST_KEY = "poolbot";
 export const LEGACY_MANIFEST_KEYS = [LEGACY_MANIFEST_KEY];
 export const LEGACY_PLUGIN_MANIFEST_FILENAME = `${LEGACY_PROJECT_NAME}.plugin.json`;
 export const LEGACY_CANVAS_HANDLER_NAME = `${LEGACY_PROJECT_NAME}CanvasA2UIAction`;

package/dist/config/commands.js

@@ -36,3 +36,6 @@ export function isNativeCommandsExplicitlyDisabled(params) {
         return globalSetting === false;
     return false;
 }
+export function isRestartEnabled(config) {
+    return config?.commands?.restart !== false;
+}

package/dist/config/config.js

@@ -1,4 +1,4 @@
-export { createConfigIO, loadConfig, parseConfigJson5, readConfigFileSnapshot, resolveConfigSnapshotHash, writeConfigFile, } from "./io.js";
+export { createConfigIO, loadConfig, parseConfigJson5, readConfigFileSnapshot, readConfigFileSnapshotForWrite, resolveConfigSnapshotHash, writeConfigFile, } from "./io.js";
 export { migrateLegacyConfig } from "./legacy-migrate.js";
 export * from "./paths.js";
 export * from "./runtime-overrides.js";

package/dist/config/env-substitution.js

@@ -21,6 +21,7 @@
  */
 // Pattern for valid uppercase env var names: starts with letter or underscore,
 // followed by letters, numbers, or underscores (all uppercase)
+import { isPlainObject } from "../utils.js";
 const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 export class MissingEnvVarError extends Error {
     varName;
@@ -32,11 +33,35 @@ export class MissingEnvVarError extends Error {
         this.name = "MissingEnvVarError";
     }
 }
-function isPlainObject(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        Object.prototype.toString.call(value) === "[object Object]");
+function parseEnvTokenAt(value, index) {
+    if (value[index] !== "$") {
+        return null;
+    }
+    const next = value[index + 1];
+    const afterNext = value[index + 2];
+    // Escaped: $${VAR} -> ${VAR}
+    if (next === "$" && afterNext === "{") {
+        const start = index + 3;
+        const end = value.indexOf("}", start);
+        if (end !== -1) {
+            const name = value.slice(start, end);
+            if (ENV_VAR_NAME_PATTERN.test(name)) {
+                return { kind: "escaped", name, end };
+            }
+        }
+    }
+    // Substitution: ${VAR} -> value
+    if (next === "{") {
+        const start = index + 2;
+        const end = value.indexOf("}", start);
+        if (end !== -1) {
+            const name = value.slice(start, end);
+            if (ENV_VAR_NAME_PATTERN.test(name)) {
+                return { kind: "substitution", name, end };
+            }
+        }
+    }
+    return null;
 }
 function substituteString(value, env, configPath) {
     if (!value.includes("$")) {
@@ -49,43 +74,46 @@ function substituteString(value, env, configPath) {
             chunks.push(char);
             continue;
         }
-        const next = value[i + 1];
-        const afterNext = value[i + 2];
-        // Escaped: $${VAR} -> ${VAR}
-        if (next === "$" && afterNext === "{") {
-            const start = i + 3;
-            const end = value.indexOf("}", start);
-            if (end !== -1) {
-                const name = value.slice(start, end);
-                if (ENV_VAR_NAME_PATTERN.test(name)) {
-                    chunks.push(`\${${name}}`);
-                    i = end;
-                    continue;
-                }
-            }
+        const token = parseEnvTokenAt(value, i);
+        if (token?.kind === "escaped") {
+            chunks.push(`\${${token.name}}`);
+            i = token.end;
+            continue;
         }
-        // Substitution: ${VAR} -> value
-        if (next === "{") {
-            const start = i + 2;
-            const end = value.indexOf("}", start);
-            if (end !== -1) {
-                const name = value.slice(start, end);
-                if (ENV_VAR_NAME_PATTERN.test(name)) {
-                    const envValue = env[name];
-                    if (envValue === undefined || envValue === "") {
-                        throw new MissingEnvVarError(name, configPath);
-                    }
-                    chunks.push(envValue);
-                    i = end;
-                    continue;
-                }
+        if (token?.kind === "substitution") {
+            const envValue = env[token.name];
+            if (envValue === undefined || envValue === "") {
+                throw new MissingEnvVarError(token.name, configPath);
             }
+            chunks.push(envValue);
+            i = token.end;
+            continue;
         }
         // Leave untouched if not a recognized pattern
         chunks.push(char);
     }
     return chunks.join("");
 }
+export function containsEnvVarReference(value) {
+    if (!value.includes("$")) {
+        return false;
+    }
+    for (let i = 0; i < value.length; i += 1) {
+        const char = value[i];
+        if (char !== "$") {
+            continue;
+        }
+        const token = parseEnvTokenAt(value, i);
+        if (token?.kind === "escaped") {
+            i = token.end;
+            continue;
+        }
+        if (token?.kind === "substitution") {
+            return true;
+        }
+    }
+    return false;
+}
 function substituteAny(value, env, path) {
     if (typeof value === "string") {
         return substituteString(value, env, path);

package/dist/config/env-vars.js

@@ -19,3 +19,12 @@ export function collectConfigEnvVars(cfg) {
     }
     return entries;
 }
+export function applyConfigEnvVars(cfg, env = process.env) {
+    const entries = collectConfigEnvVars(cfg);
+    for (const [key, value] of Object.entries(entries)) {
+        if (env[key]?.trim()) {
+            continue;
+        }
+        env[key] = value;
+    }
+}