advisor-pi 1.0.3 → 1.2.0

package/dist/index.js

@@ -1,15 +1,19 @@
 import { completeSimple, StringEnum } from "@earendil-works/pi-ai";
 import { buildSessionContext, convertToLlm, serializeConversation, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-const STATE_ENTRY = "advisor-pi-state";
+import { loadPreferences, savePreferencesPatch } from "./preferences.js";
+import { buildMenuRows, rowForLabel } from "./config-ui.js";
+export { loadPreferences, preferencesPath, savePreferences, savePreferencesPatch } from "./preferences.js";
+export const STATE_ENTRY = "advisor-pi-state";
 const TOOL_NAME = "advisor";
-const DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.6-sol";
-const LEGACY_DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.5";
+export const DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.6-sol";
+export const LEGACY_DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.5";
 const DEFAULT_ADVISOR_THINKING_LEVEL = "high";
 const DEFAULT_MAX_USES = 5;
 const DEFAULT_CACHE_RETENTION = "short";
 const DEFAULT_TIMEOUT_MS = 600_000;
 const DEFAULT_MAX_TOKENS = 4_000;
+export const DEFAULT_MAX_TRANSCRIPT_CHARS = 20_000;
 const advisorToolSchema = Type.Object({
     question: Type.String({
         description: "Strategic question for the advisor. Ask for planning, risk analysis, course correction, or review guidance.",
@@ -22,8 +26,11 @@ const advisorToolSchema = Type.Object({
         description: "Optional extra context that is not obvious from the transcript, such as constraints, current plan, or failed attempts.",
     })),
 });
+function isTuiContext(ctx) {
+    return ctx.mode === "tui" && ctx.hasUI;
+}
 export default function advisorPiExtension(pi) {
-    let config = defaultConfig();
+    let config = normalizeConfig(loadPreferences(), defaultConfig(), undefined, { migrateLegacyDefault: false });
     let useCount = 0;
     pi.registerFlag("advisor-model", {
         description: "Advisor model as provider/model, e.g. openai-codex/gpt-5.6-sol",
@@ -41,10 +48,13 @@ export default function advisorPiExtension(pi) {
         description: "Advisor prompt-cache preference: none, short, or long",
         type: "string",
     });
+    pi.registerFlag("advisor-max-transcript-chars", {
+        description: "Maximum conversation transcript characters sent per advisor call (keeps most recent)",
+        type: "string",
+    });
     pi.registerFlag("advisor-enabled", {
         description: "Enable the advisor tool on startup",
         type: "boolean",
-        default: true,
     });
     pi.registerTool({
         name: TOOL_NAME,
@@ -59,7 +69,8 @@ export default function advisorPiExtension(pi) {
         parameters: advisorToolSchema,
         executionMode: "sequential",
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
-            refreshStateFromBranch(ctx);
+            // Branch state is replayed at session_start/session_tree; refreshing here
+            // would reapply startup flags over explicit in-session command edits.
             if (!config.enabled) {
                 return advisorDisabledResult(config, useCount, params);
             }
@@ -83,7 +94,7 @@ export default function advisorPiExtension(pi) {
             if (!auth.ok)
                 throw new Error(auth.error);
             const startedAt = Date.now();
-            const conversationText = serializeCurrentConversation(ctx);
+            const conversationText = truncateTranscript(serializeCurrentConversation(ctx), config.maxTranscriptChars);
             const userMessage = {
                 role: "user",
                 content: [
@@ -145,15 +156,16 @@ export default function advisorPiExtension(pi) {
         },
     });
     pi.registerCommand("advisor-pi", {
-        description: "Configure advisor-pi: status, enable, disable, model, thinking, max-uses, cache, reset",
+        description: "Configure advisor-pi: status, enable, disable, model, thinking, max-uses, max-transcript-chars, cache, reset",
         handler: async (args, ctx) => {
-            const result = handleCommand(args.trim(), ctx);
-            if (result.persist)
-                persistState(pi, config, useCount);
-            if (result.updateToolState)
-                syncActiveTool(pi);
-            updateStatus(ctx);
-            ctx.ui.notify(result.message, result.level);
+            const trimmed = args.trim();
+            // Bare /advisor-pi is interactive only in the terminal TUI. Other modes
+            // keep the existing status response for scripts and print output.
+            if (!trimmed && isTuiContext(ctx)) {
+                await openConfigPanel(ctx);
+                return;
+            }
+            await applyCommand(trimmed, ctx);
         },
     });
     pi.on("session_start", async (_event, ctx) => {
@@ -173,15 +185,15 @@ export default function advisorPiExtension(pi) {
         persistState(pi, config, useCount);
     });
     function refreshStateFromBranch(ctx) {
-        config = defaultConfig();
+        config = normalizeConfig(loadPreferences(), defaultConfig(), ctx.modelRegistry, { migrateLegacyDefault: false });
         useCount = 0;
-        const restoredFromBranch = restoreStateFromSession(ctx);
-        if (!restoredFromBranch)
-            applyStartupFlags(pi);
+        restoreStateFromSession(ctx, ctx.modelRegistry);
+        applyStartupFlags(pi, ctx.modelRegistry);
+        ensureAdvisorModelResolves(ctx);
         syncActiveTool(pi);
         updateStatus(ctx);
     }
-    function restoreStateFromSession(ctx) {
+    function restoreStateFromSession(ctx, registry) {
         let restored = false;
         const branch = ctx.sessionManager.getBranch();
         for (const entry of branch) {
@@ -189,7 +201,7 @@ export default function advisorPiExtension(pi) {
                 restored = true;
                 const data = entry.data;
                 if (data?.config)
-                    config = normalizeConfig(data.config, config);
+                    config = normalizeConfig(data.config, config, registry);
                 if (typeof data?.useCount === "number")
                     useCount = Math.max(0, data.useCount);
             }
@@ -197,7 +209,7 @@ export default function advisorPiExtension(pi) {
                 restored = true;
                 const details = entry.message.details;
                 if (details?.state?.config)
-                    config = normalizeConfig(details.state.config, config);
+                    config = normalizeConfig(details.state.config, config, registry);
                 if (typeof details?.state?.useCount === "number")
                     useCount = Math.max(useCount, details.state.useCount);
                 else if (details?.advisor?.useCount)
@@ -206,36 +218,65 @@ export default function advisorPiExtension(pi) {
         }
         return restored;
     }
-    function applyStartupFlags(api) {
-        const enabledFlag = api.getFlag("advisor-enabled");
+    function applyStartupFlags(api, registry) {
+        const enabledFlag = flagValue(api, "advisor-enabled");
         if (typeof enabledFlag === "boolean")
             config.enabled = enabledFlag;
-        const modelFlag = api.getFlag("advisor-model");
+        const modelFlag = flagValue(api, "advisor-model");
         if (typeof modelFlag === "string" && modelFlag.trim()) {
             const parsed = parseModelSpec(modelFlag.trim());
-            if (parsed) {
+            if (parsed && (!registry || modelResolves(registry, parsed.provider, parsed.modelId))) {
                 config.provider = parsed.provider;
                 config.modelId = parsed.modelId;
             }
         }
-        const thinkingFlag = api.getFlag("advisor-thinking");
+        const thinkingFlag = flagValue(api, "advisor-thinking");
         if (typeof thinkingFlag === "string") {
             const thinkingLevel = parseThinkingLevel(thinkingFlag);
             if (thinkingLevel)
                 config.thinkingLevel = thinkingLevel;
         }
-        const maxUsesFlag = api.getFlag("advisor-max-uses");
+        const maxUsesFlag = flagValue(api, "advisor-max-uses");
         if (typeof maxUsesFlag === "string") {
             const maxUses = parsePositiveInt(maxUsesFlag);
             if (maxUses !== undefined)
                 config.maxUses = maxUses;
         }
-        const cacheFlag = api.getFlag("advisor-cache");
+        const cacheFlag = flagValue(api, "advisor-cache");
         if (typeof cacheFlag === "string") {
             const cacheRetention = parseCacheRetention(cacheFlag);
             if (cacheRetention)
                 config.cacheRetention = cacheRetention;
         }
+        const maxTranscriptCharsFlag = flagValue(api, "advisor-max-transcript-chars");
+        if (typeof maxTranscriptCharsFlag === "string") {
+            const maxTranscriptChars = parsePositiveInt(maxTranscriptCharsFlag);
+            if (maxTranscriptChars !== undefined)
+                config.maxTranscriptChars = maxTranscriptChars;
+        }
+    }
+    function ensureAdvisorModelResolves(ctx) {
+        const registry = ctx.modelRegistry;
+        if (!registry || modelResolves(registry, config.provider, config.modelId))
+            return;
+        const previous = `${config.provider}/${config.modelId}`;
+        const candidates = [parseModelSpec(DEFAULT_ADVISOR_MODEL), parseModelSpec(LEGACY_DEFAULT_ADVISOR_MODEL)].filter((candidate) => candidate !== undefined);
+        const working = resolveAdvisorModel(registry, candidates);
+        if (!working)
+            return;
+        config.provider = working.provider;
+        config.modelId = working.modelId;
+        persistState(pi, config, useCount);
+        if (ctx.hasUI) {
+            ctx.ui.notify(`Advisor model ${previous} not found. Falling back to ${working.provider}/${working.modelId}.`, "warning");
+        }
+    }
+    async function persistPreferencesForEdit(ctx, patch) {
+        if (await savePreferencesPatch(patch))
+            return;
+        if (ctx.hasUI) {
+            ctx.ui.notify("Could not save advisor-pi preferences; this change applies to the current session only.", "warning");
+        }
     }
     function handleCommand(args, ctx) {
         if (!args || args === "status") {
@@ -251,10 +292,22 @@ export default function advisorPiExtension(pi) {
         switch (command) {
             case "enable":
                 config.enabled = true;
-                return { message: "advisor-pi enabled", level: "info", persist: true, updateToolState: true };
+                return {
+                    message: "advisor-pi enabled",
+                    level: "info",
+                    persist: true,
+                    preferencePatch: { enabled: true },
+                    updateToolState: true,
+                };
             case "disable":
                 config.enabled = false;
-                return { message: "advisor-pi disabled", level: "info", persist: true, updateToolState: true };
+                return {
+                    message: "advisor-pi disabled",
+                    level: "info",
+                    persist: true,
+                    preferencePatch: { enabled: false },
+                    updateToolState: true,
+                };
             case "reset":
                 useCount = 0;
                 return { message: "advisor-pi use count reset", level: "info", persist: true, updateToolState: false };
@@ -283,6 +336,7 @@ export default function advisorPiExtension(pi) {
                     message: `advisor-pi model set to ${config.provider}/${config.modelId}`,
                     level: "info",
                     persist: true,
+                    preferencePatch: { provider: config.provider, modelId: config.modelId },
                     updateToolState: false,
                 };
             }
@@ -301,6 +355,7 @@ export default function advisorPiExtension(pi) {
                     message: `advisor-pi thinking level set to ${thinkingLevel}`,
                     level: "info",
                     persist: true,
+                    preferencePatch: { thinkingLevel },
                     updateToolState: false,
                 };
             }
@@ -319,6 +374,7 @@ export default function advisorPiExtension(pi) {
                     message: `advisor-pi max uses set to ${maxUses}`,
                     level: "info",
                     persist: true,
+                    preferencePatch: { maxUses },
                     updateToolState: false,
                 };
             }
@@ -337,18 +393,143 @@ export default function advisorPiExtension(pi) {
                     message: `advisor-pi cache set to ${cacheRetention}`,
                     level: "info",
                     persist: true,
+                    preferencePatch: { cacheRetention },
+                    updateToolState: false,
+                };
+            }
+            case "max-transcript-chars": {
+                const maxTranscriptChars = parsePositiveInt(value);
+                if (maxTranscriptChars === undefined) {
+                    return {
+                        message: "Usage: /advisor-pi max-transcript-chars <positive-number>",
+                        level: "error",
+                        persist: false,
+                        updateToolState: false,
+                    };
+                }
+                config.maxTranscriptChars = maxTranscriptChars;
+                return {
+                    message: `advisor-pi max transcript chars set to ${maxTranscriptChars}`,
+                    level: "info",
+                    persist: true,
+                    preferencePatch: { maxTranscriptChars },
                     updateToolState: false,
                 };
             }
             default:
                 return {
-                    message: "Usage: /advisor-pi [status|enable|disable|model <provider>/<model>|thinking <minimal|low|medium|high|xhigh|max>|max-uses <n>|cache <none|short|long>|reset]",
+                    message: "Usage: /advisor-pi [status|enable|disable|model <provider>/<model>|thinking <minimal|low|medium|high|xhigh|max>|max-uses <n>|max-transcript-chars <n>|cache <none|short|long>|reset]",
                     level: "error",
                     persist: false,
                     updateToolState: false,
                 };
         }
     }
+    async function applyCommand(args, ctx, options = {}) {
+        const result = handleCommand(args, ctx);
+        if (result.persist) {
+            persistState(pi, config, useCount);
+            if (result.preferencePatch)
+                await persistPreferencesForEdit(ctx, result.preferencePatch);
+        }
+        if (result.updateToolState)
+            syncActiveTool(pi);
+        updateStatus(ctx);
+        const message = options.redactModelErrors && result.level === "error" ? "Advisor model not found" : result.message;
+        ctx.ui.notify(message, result.level);
+    }
+    async function openConfigPanel(ctx) {
+        for (;;) {
+            const rows = buildMenuRows(config, useCount);
+            const choice = await ctx.ui.select("advisor-pi settings", rows.map((row) => row.label));
+            const row = rowForLabel(rows, choice);
+            // Escape returns undefined, which closes the panel without changing state.
+            if (!row || row.key === "close")
+                return;
+            await applyMenuChoice(row.key, ctx);
+        }
+    }
+    async function applyMenuChoice(key, ctx) {
+        switch (key) {
+            case "enabled": {
+                const choice = await ctx.ui.select("Advisor enabled", ["enabled", "disabled"]);
+                if (choice !== "enabled" && choice !== "disabled")
+                    return;
+                const enabled = choice === "enabled";
+                if (enabled === config.enabled)
+                    return;
+                const confirmed = await ctx.ui.confirm(enabled ? "Enable advisor-pi?" : "Disable advisor-pi?", enabled
+                    ? "The advisor tool will be available to the executor."
+                    : "The advisor tool will be removed from the active tool list.");
+                if (!confirmed)
+                    return;
+                await applyCommand(enabled ? "enable" : "disable", ctx);
+                return;
+            }
+            case "model": {
+                const typed = await ctx.ui.input("Advisor model", "provider/model");
+                if (typed === undefined)
+                    return;
+                const parsed = parseModelSpec(typed);
+                if (!parsed) {
+                    ctx.ui.notify("Expected provider/model", "error");
+                    return;
+                }
+                let model;
+                try {
+                    model = ctx.modelRegistry.find(parsed.provider, parsed.modelId);
+                }
+                catch {
+                    model = undefined;
+                }
+                if (!model) {
+                    ctx.ui.notify("Advisor model not found", "error");
+                    return;
+                }
+                await applyCommand(`model ${parsed.provider}/${parsed.modelId}`, ctx, { redactModelErrors: true });
+                return;
+            }
+            case "thinking": {
+                const choice = await ctx.ui.select("Advisor thinking", ["minimal", "low", "medium", "high", "xhigh", "max"]);
+                if (!parseThinkingLevel(choice))
+                    return;
+                await applyCommand(`thinking ${choice}`, ctx);
+                return;
+            }
+            case "max-uses": {
+                const value = await ctx.ui.input("Maximum advisor uses", String(config.maxUses));
+                if (value === undefined)
+                    return;
+                await applyCommand(`max-uses ${value}`, ctx);
+                return;
+            }
+            case "max-transcript-chars": {
+                const value = await ctx.ui.input("Maximum transcript characters", String(config.maxTranscriptChars));
+                if (value === undefined)
+                    return;
+                await applyCommand(`max-transcript-chars ${value}`, ctx);
+                return;
+            }
+            case "cache": {
+                const choice = await ctx.ui.select("Advisor cache retention", ["none", "short", "long"]);
+                if (!parseCacheRetention(choice))
+                    return;
+                await applyCommand(`cache ${choice}`, ctx);
+                return;
+            }
+            case "reset": {
+                if (useCount <= 0)
+                    return;
+                const confirmed = await ctx.ui.confirm("Reset advisor use count?", `This clears ${useCount} advisor use${useCount === 1 ? "" : "s"} for the current session branch.`);
+                if (!confirmed)
+                    return;
+                await applyCommand("reset", ctx);
+                return;
+            }
+            case "close":
+                return;
+        }
+    }
     function syncActiveTool(api) {
         const activeTools = api.getActiveTools();
         const hasAdvisor = activeTools.includes(TOOL_NAME);
@@ -378,6 +559,7 @@ export default function advisorPiExtension(pi) {
             `model: ${config.provider}/${config.modelId} (${availability})`,
             `thinking: ${config.thinkingLevel}`,
             `uses: ${useCount}/${config.maxUses}`,
+            `transcript: max ${config.maxTranscriptChars} chars`,
             `cache: ${config.cacheRetention}`,
         ].join(" • ");
     }
@@ -393,7 +575,7 @@ Your role is strategic guidance only. You do not have tools and you do not make
 - If the task is unsafe, impossible, or underspecified, say what must be clarified.
 
 Return guidance in short sections with bullets when useful.`;
-function defaultConfig() {
+export function defaultConfig() {
     const parsed = parseModelSpec(DEFAULT_ADVISOR_MODEL) ?? { provider: "openai-codex", modelId: "gpt-5.6-sol" };
     return {
         enabled: true,
@@ -404,6 +586,7 @@ function defaultConfig() {
         cacheRetention: DEFAULT_CACHE_RETENTION,
         maxTokens: DEFAULT_MAX_TOKENS,
         timeoutMs: DEFAULT_TIMEOUT_MS,
+        maxTranscriptChars: DEFAULT_MAX_TRANSCRIPT_CHARS,
     };
 }
 function buildExecutorGuidance(config, useCount) {
@@ -422,6 +605,14 @@ function serializeCurrentConversation(ctx) {
     const llmMessages = convertToLlm(sessionContext.messages);
     return serializeConversation(llmMessages);
 }
+export function truncateTranscript(text, maxChars) {
+    if (maxChars <= 0)
+        return text;
+    if (text.length <= maxChars)
+        return text;
+    const omitted = text.length - maxChars;
+    return `[... earlier conversation truncated: showing the most recent ${maxChars} of ${text.length} characters (${omitted} omitted)]\n\n${text.slice(text.length - maxChars)}`;
+}
 function buildAdvisorUserPrompt(params, conversationText) {
     return [
         "## Executor Question",
@@ -480,7 +671,7 @@ function makeSkippedDetails(config, useCount, params) {
         state: makeStateEntry(config, useCount),
     };
 }
-function makeStateEntry(config, useCount) {
+export function makeStateEntry(config, useCount) {
     return {
         version: 1,
         config: { ...config },
@@ -488,42 +679,101 @@ function makeStateEntry(config, useCount) {
         updatedAt: new Date().toISOString(),
     };
 }
-function persistState(pi, config, useCount) {
+export function persistState(pi, config, useCount) {
     pi.appendEntry(STATE_ENTRY, makeStateEntry(config, useCount));
 }
-function normalizeConfig(input, fallback) {
+export function normalizeConfig(input, fallback, registry, options = {}) {
     const normalized = {
         enabled: typeof input.enabled === "boolean" ? input.enabled : fallback.enabled,
-        provider: typeof input.provider === "string" && input.provider ? input.provider : fallback.provider,
-        modelId: typeof input.modelId === "string" && input.modelId ? input.modelId : fallback.modelId,
+        provider: typeof input.provider === "string" && input.provider.trim() ? input.provider.trim() : fallback.provider,
+        modelId: typeof input.modelId === "string" && input.modelId.trim() ? input.modelId.trim() : fallback.modelId,
         thinkingLevel: parseThinkingLevel(input.thinkingLevel) ?? fallback.thinkingLevel,
-        maxUses: typeof input.maxUses === "number" && input.maxUses > 0 ? Math.floor(input.maxUses) : fallback.maxUses,
+        maxUses: typeof input.maxUses === "number" && Number.isFinite(input.maxUses) && Math.floor(input.maxUses) > 0
+            ? Math.floor(input.maxUses)
+            : fallback.maxUses,
         cacheRetention: parseCacheRetention(input.cacheRetention) ?? fallback.cacheRetention,
-        maxTokens: typeof input.maxTokens === "number" && input.maxTokens > 0 ? Math.floor(input.maxTokens) : fallback.maxTokens,
-        timeoutMs: typeof input.timeoutMs === "number" && input.timeoutMs > 0 ? Math.floor(input.timeoutMs) : fallback.timeoutMs,
+        maxTokens: typeof input.maxTokens === "number" && Number.isFinite(input.maxTokens) && Math.floor(input.maxTokens) > 0
+            ? Math.floor(input.maxTokens)
+            : fallback.maxTokens,
+        timeoutMs: typeof input.timeoutMs === "number" && Number.isFinite(input.timeoutMs) && Math.floor(input.timeoutMs) > 0
+            ? Math.floor(input.timeoutMs)
+            : fallback.timeoutMs,
+        maxTranscriptChars: typeof input.maxTranscriptChars === "number" && Number.isFinite(input.maxTranscriptChars) && Math.floor(input.maxTranscriptChars) > 0
+            ? Math.floor(input.maxTranscriptChars)
+            : fallback.maxTranscriptChars,
     };
     const legacyDefault = parseModelSpec(LEGACY_DEFAULT_ADVISOR_MODEL);
-    if (input.thinkingLevel === undefined &&
+    if (options.migrateLegacyDefault !== false &&
+        input.thinkingLevel === undefined &&
         legacyDefault &&
         normalized.provider === legacyDefault.provider &&
         normalized.modelId === legacyDefault.modelId) {
-        normalized.provider = fallback.provider;
-        normalized.modelId = fallback.modelId;
+        // Only rewrite the stored legacy default when the migration target resolves.
+        // Otherwise a resolving stored model would be replaced by a non-resolving default.
+        if (!registry || modelResolves(registry, fallback.provider, fallback.modelId)) {
+            normalized.provider = fallback.provider;
+            normalized.modelId = fallback.modelId;
+        }
+    }
+    if (registry && typeof input.provider === "string" && input.provider && typeof input.modelId === "string" && input.modelId) {
+        // Never replace a resolving stored model with a non-resolving one.
+        if (modelResolves(registry, input.provider, input.modelId) && !modelResolves(registry, normalized.provider, normalized.modelId)) {
+            normalized.provider = input.provider;
+            normalized.modelId = input.modelId;
+        }
     }
     return normalized;
 }
-function parseModelSpec(value) {
-    const slash = value.indexOf("/");
-    if (slash <= 0 || slash === value.length - 1)
+export function modelResolves(registry, provider, modelId) {
+    if (!registry)
+        return false;
+    try {
+        const found = registry.find(provider, modelId);
+        return found !== undefined && found !== null;
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveAdvisorModel(registry, candidates) {
+    if (!registry)
         return undefined;
-    return {
-        provider: value.slice(0, slash),
-        modelId: value.slice(slash + 1),
-    };
+    for (const candidate of candidates) {
+        if (modelResolves(registry, candidate.provider, candidate.modelId))
+            return candidate;
+    }
+    try {
+        const available = registry.getAvailable?.();
+        const first = Array.isArray(available) ? available[0] : undefined;
+        if (first && typeof first.provider === "string" && typeof first.id === "string" && first.provider && first.id) {
+            return { provider: first.provider, modelId: first.id };
+        }
+    }
+    catch {
+        // Ignore registry listing failures; callers keep the current config.
+    }
+    return undefined;
+}
+export function parseModelSpec(value) {
+    const trimmed = value.trim();
+    const slash = trimmed.indexOf("/");
+    if (slash <= 0 || slash === trimmed.length - 1)
+        return undefined;
+    const provider = trimmed.slice(0, slash).trim();
+    const modelId = trimmed.slice(slash + 1).trim();
+    if (!provider || !modelId)
+        return undefined;
+    return { provider, modelId };
+}
+function flagValue(api, name) {
+    return typeof api.getFlag === "function" ? api.getFlag(name) : undefined;
 }
 function parsePositiveInt(value) {
-    const parsed = Number.parseInt(value, 10);
-    if (!Number.isFinite(parsed) || parsed <= 0)
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
         return undefined;
     return parsed;
 }