@poolzin/pool-bot 2026.3.4 → 2026.3.7

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## v2026.3.6 (2026-03-06)
+
+### Features
+- **PDF Analysis Tool:** new `pdf` tool for Pool Bot agents — supports native PDF processing for Anthropic (via `pdfs-2024-09-25` beta header) and Google Gemini (via `inline_data`), with automatic text-extraction + page-image fallback for other providers; configurable via `pdfModel` in agent defaults
+- **Cron onFailure Alerts:** `onFailure` config on cron jobs — triggers webhook or announce alert when a job fails (`status="error"`); supports `bestEffort` flag to silence delivery errors
+- **Gateway Health Probes:** `/health`, `/healthz` (liveness) and `/ready`, `/readyz` (readiness) endpoints — run before auth middleware for Docker/K8s orchestrator compatibility
+- **Tool Result Truncation:** head+tail truncation strategy preserving important tail content (errors, JSON closing braces, summaries) via `hasImportantTail()` heuristic and `MIDDLE_OMISSION_MARKER`
+
+---
+
 ## v2026.3.4 (2026-03-04)
 
 ### Features

package/dist/agents/pi-embedded-runner/tool-result-truncation.js

@@ -26,20 +26,75 @@ const TRUNCATION_SUFFIX = "\n\n⚠️ [Content truncated — original was too la
     "The content above is a partial view. If you need more, request specific sections or use " +
     "offset/limit parameters to read smaller chunks.]";
 /**
- * Truncate a single text string to fit within maxChars, preserving the beginning.
+ * Marker inserted between head and tail when both ends are preserved.
  */
-export function truncateToolResultText(text, maxChars) {
+export const MIDDLE_OMISSION_MARKER = "\n\n⚠️ [... middle content omitted — showing head and tail ...]\n\n";
+/**
+ * Check whether the tail of a text block contains important content that
+ * should be preserved (error messages, JSON closing braces, summaries).
+ */
+export function hasImportantTail(text) {
+    const tailSlice = text.slice(-2000).toLowerCase();
+    const errorPatterns = [
+        "error",
+        "exception",
+        "failed",
+        "fatal",
+        "traceback",
+        "panic",
+        "stack trace",
+        "errno",
+        "exit code",
+    ];
+    if (errorPatterns.some((p) => tailSlice.includes(p)))
+        return true;
+    // JSON closing brace — likely structured output
+    if (tailSlice.trimEnd().endsWith("}"))
+        return true;
+    // Summary-like keywords
+    const summaryPatterns = ["total", "summary", "result", "complete", "finished", "done"];
+    return summaryPatterns.some((p) => tailSlice.includes(p));
+}
+/**
+ * Truncate a single text string to fit within maxChars.
+ *
+ * When the tail contains important content (errors, JSON, summaries) and the
+ * budget allows, the function preserves both the head and the tail of the
+ * text with a middle-omission marker.  Otherwise it falls back to head-only
+ * truncation.
+ */
+export function truncateToolResultText(text, maxChars, options) {
     if (text.length <= maxChars) {
         return text;
     }
-    const keepChars = Math.max(MIN_KEEP_CHARS, maxChars - TRUNCATION_SUFFIX.length);
+    const suffix = options?.suffix ?? TRUNCATION_SUFFIX;
+    const minKeep = options?.minKeepChars ?? MIN_KEEP_CHARS;
+    // --- head + tail strategy ---
+    if (hasImportantTail(text) && maxChars > minKeep + MIDDLE_OMISSION_MARKER.length + 200) {
+        const budget = maxChars - MIDDLE_OMISSION_MARKER.length;
+        const tailBudget = Math.min(Math.floor(budget * 0.3), 4000);
+        const headBudget = budget - tailBudget;
+        // snap head to newline boundary
+        let headEnd = headBudget;
+        const headNl = text.lastIndexOf("\n", headBudget);
+        if (headNl > headBudget * 0.8)
+            headEnd = headNl;
+        // snap tail to newline boundary
+        let tailStart = text.length - tailBudget;
+        const tailNl = text.indexOf("\n", tailStart);
+        if (tailNl !== -1 && tailNl < tailStart + tailBudget * 0.2)
+            tailStart = tailNl + 1;
+        return text.slice(0, headEnd) + MIDDLE_OMISSION_MARKER + text.slice(tailStart);
+    }
+    // --- head-only fallback ---
+    const keepChars = Math.max(minKeep, maxChars - suffix.length);
     // Try to break at a newline boundary to avoid cutting mid-line
     let cutPoint = keepChars;
     const lastNewline = text.lastIndexOf("\n", keepChars);
     if (lastNewline > keepChars * 0.8) {
         cutPoint = lastNewline;
     }
-    return text.slice(0, cutPoint) + TRUNCATION_SUFFIX;
+    return text.slice(0, cutPoint) + suffix;
 }
 /**
  * Calculate the maximum allowed characters for a single tool result
@@ -57,7 +112,7 @@ export function calculateMaxToolResultChars(contextWindowTokens) {
 /**
  * Get the total character count of text content blocks in a tool result message.
  */
-function getToolResultTextLength(msg) {
+export function getToolResultTextLength(msg) {
     if (!msg || msg.role !== "toolResult") {
         return 0;
     }
@@ -80,7 +135,7 @@ function getToolResultTextLength(msg) {
  * Truncate a tool result message's text content blocks to fit within maxChars.
  * Returns a new message (does not mutate the original).
  */
-function truncateToolResultMessage(msg, maxChars) {
+export function truncateToolResultMessage(msg, maxChars, options) {
     const content = msg.content;
     if (!Array.isArray(content)) {
         return msg;
@@ -104,7 +159,7 @@ function truncateToolResultMessage(msg, maxChars) {
         const blockBudget = Math.max(MIN_KEEP_CHARS, Math.floor(maxChars * blockShare));
         return {
             ...textBlock,
-            text: truncateToolResultText(textBlock.text, blockBudget),
+            text: truncateToolResultText(textBlock.text, blockBudget, options),
         };
     });
     return { ...msg, content: newContent };

package/dist/agents/pi-tools.js

@@ -16,8 +16,10 @@ import { assertRequiredParams, CLAUDE_PARAM_GROUPS, createPoolbotReadTool, creat
 import { cleanToolSchemaForGemini, normalizeToolParameters } from "./pi-tools.schema.js";
 import { getSubagentDepthFromSessionStore } from "./subagent-depth.js";
 import { applyToolPolicyPipeline, buildDefaultToolPolicyPipelineSteps, } from "./tool-policy-pipeline.js";
-import { applyOwnerOnlyToolPolicy, collectExplicitAllowlist, mergeAlsoAllowPolicy, resolveToolProfilePolicy, } from "./tool-policy.js";
+import { applyOwnerOnlyToolPolicy, collectExplicitAllowlist, mergeAlsoAllowPolicy, normalizeToolName, resolveToolProfilePolicy, } from "./tool-policy.js";
 import { resolveWorkspaceRoot } from "./workspace-dir.js";
+import { CapabilityError } from "../security/capability-guards.js";
+import { createDefaultSecurityMiddleware } from "../security/middleware.js";
 function isOpenAIProvider(provider) {
     const normalized = provider?.trim().toLowerCase();
     return normalized === "openai" || normalized === "openai-codex";
@@ -339,8 +341,36 @@ export function createPoolbotCodingTools(options) {
     const withAbort = options?.abortSignal
         ? withHooks.map((tool) => wrapToolWithAbortSignal(tool, options.abortSignal))
         : withHooks;
+    // Apply capability-based security middleware if enabled
+    const withCapabilities = options?.config?.security?.enabled && agentId
+        ? withAbort.map((tool) => wrapToolWithCapabilityCheck(tool, agentId))
+        : withAbort;
     // NOTE: Keep canonical (lowercase) tool names here.
     // pi-ai's Anthropic OAuth transport remaps tool names to Claude Code-style names
     // on the wire and maps them back for tool dispatch.
-    return withAbort;
+    return withCapabilities;
+}
+/**
+ * Wraps a tool with capability-based security checks.
+ * This enforces fine-grained permissions for tool invocation.
+ */
+function wrapToolWithCapabilityCheck(tool, agentId) {
+    const middleware = createDefaultSecurityMiddleware();
+    return {
+        ...tool,
+        execute: async (toolCallId, args, signal, onUpdate) => {
+            const ctx = { agentId };
+            const toolId = normalizeToolName(tool.name);
+            const result = await middleware(ctx, toolId, (args ?? {}), async () => {
+                if (!tool.execute) {
+                    throw new CapabilityError(`Tool ${tool.name} has no execute function`, agentId, {
+                        type: "tool:invoke",
+                        toolId,
+                    });
+                }
+                return await tool.execute(toolCallId, args, signal, onUpdate);
+            });
+            return result;
+        },
+    };
 }

package/dist/agents/poolbot-tools.js

@@ -9,6 +9,7 @@ import { createGatewayTool } from "./tools/gateway-tool.js";
 import { createImageGenerateTool } from "./tools/image-generate-tool.js";
 import { createImageTool } from "./tools/image-tool.js";
 import { createMessageTool } from "./tools/message-tool.js";
+import { createPdfTool } from "./tools/pdf-tool.js";
 import { createNodesTool } from "./tools/nodes-tool.js";
 import { createSessionStatusTool } from "./tools/session-status-tool.js";
 import { createSessionsHistoryTool } from "./tools/sessions-history-tool.js";
@@ -32,6 +33,16 @@ export function createPoolBotTools(options) {
             modelHasVision: options?.modelHasVision,
         })
         : null;
+    const pdfTool = options?.agentDir?.trim()
+        ? createPdfTool({
+            config: options?.config,
+            agentDir: options.agentDir,
+            workspaceDir,
+            sandbox: options?.sandboxRoot && options?.sandboxFsBridge
+                ? { root: options.sandboxRoot, bridge: options.sandboxFsBridge }
+                : undefined,
+        })
+        : null;
     const imageGenerateTool = createImageGenerateTool({
         config: options?.config,
         agentDir: options?.agentDir,
@@ -121,6 +132,7 @@ export function createPoolBotTools(options) {
         ...(webFetchTool ? [webFetchTool] : []),
         ...(imageTool ? [imageTool] : []),
         ...(imageGenerateTool ? [imageGenerateTool] : []),
+        ...(pdfTool ? [pdfTool] : []),
     ];
     // Z.AI-powered research tool (gracefully absent when no key configured)
     const deepResearchTool = createDeepResearchTool({

package/dist/agents/session-write-lock.js

@@ -1,8 +1,11 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { isPidAlive } from "../shared/pid-alive.js";
+import { getProcessStartTime, isPidAlive } from "../shared/pid-alive.js";
 import { resolveProcessScopedMap } from "../shared/process-scoped-map.js";
+function isValidLockNumber(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
 const CLEANUP_SIGNALS = ["SIGINT", "SIGTERM", "SIGQUIT", "SIGABRT"];
 const CLEANUP_STATE_KEY = Symbol.for("poolbot.sessionWriteLockCleanupState");
 const HELD_LOCKS_KEY = Symbol.for("poolbot.sessionWriteLockHeldLocks");
@@ -196,12 +199,15 @@ async function readLockPayload(lockPath) {
         const raw = await fs.readFile(lockPath, "utf8");
         const parsed = JSON.parse(raw);
         const payload = {};
-        if (typeof parsed.pid === "number") {
+        if (isValidLockNumber(parsed.pid) && parsed.pid > 0) {
             payload.pid = parsed.pid;
         }
         if (typeof parsed.createdAt === "string") {
             payload.createdAt = parsed.createdAt;
         }
+        if (isValidLockNumber(parsed.starttime)) {
+            payload.starttime = parsed.starttime;
+        }
         return payload;
     }
     catch {
@@ -209,11 +215,21 @@ async function readLockPayload(lockPath) {
     }
 }
 function inspectLockPayload(payload, staleMs, nowMs) {
-    const pid = typeof payload?.pid === "number" ? payload.pid : null;
+    const pid = isValidLockNumber(payload?.pid) && payload.pid > 0 ? payload.pid : null;
     const pidAlive = pid !== null ? isPidAlive(pid) : false;
     const createdAt = typeof payload?.createdAt === "string" ? payload.createdAt : null;
     const createdAtMs = createdAt ? Date.parse(createdAt) : Number.NaN;
     const ageMs = Number.isFinite(createdAtMs) ? Math.max(0, nowMs - createdAtMs) : null;
+    // Detect PID recycling: if the PID is alive but its start time differs from
+    // what was recorded in the lock file, the original process died and the OS
+    // reassigned the same PID to a different process.
+    const storedStarttime = isValidLockNumber(payload?.starttime) ? payload.starttime : null;
+    const pidRecycled = pidAlive && pid !== null && storedStarttime !== null
+        ? (() => {
+            const currentStarttime = getProcessStartTime(pid);
+            return currentStarttime !== null && currentStarttime !== storedStarttime;
+        })()
+        : false;
     const staleReasons = [];
     if (pid === null) {
         staleReasons.push("missing-pid");
@@ -221,6 +237,9 @@ function inspectLockPayload(payload, staleMs, nowMs) {
     else if (!pidAlive) {
         staleReasons.push("dead-pid");
     }
+    else if (pidRecycled) {
+        staleReasons.push("recycled-pid");
+    }
     if (ageMs === null) {
         staleReasons.push("invalid-createdAt");
     }
@@ -236,6 +255,38 @@ function inspectLockPayload(payload, staleMs, nowMs) {
         staleReasons,
     };
 }
+function lockInspectionNeedsMtimeStaleFallback(details) {
+    return (details.stale &&
+        details.staleReasons.every((reason) => reason === "missing-pid" || reason === "invalid-createdAt"));
+}
+async function shouldReclaimContendedLockFile(lockPath, details, staleMs, nowMs) {
+    if (!details.stale) {
+        return false;
+    }
+    if (!lockInspectionNeedsMtimeStaleFallback(details)) {
+        return true;
+    }
+    try {
+        const stat = await fs.stat(lockPath);
+        const ageMs = Math.max(0, nowMs - stat.mtimeMs);
+        return ageMs > staleMs;
+    }
+    catch (error) {
+        const code = error?.code;
+        return code !== "ENOENT";
+    }
+}
+function shouldTreatAsOrphanSelfLock(params) {
+    const pid = isValidLockNumber(params.payload?.pid) ? params.payload.pid : null;
+    if (pid !== process.pid) {
+        return false;
+    }
+    const hasValidStarttime = isValidLockNumber(params.payload?.starttime);
+    if (hasValidStarttime) {
+        return false;
+    }
+    return !HELD_LOCKS.has(params.normalizedSessionFile);
+}
 export async function cleanStaleLockFiles(params) {
     const sessionsDir = path.resolve(params.sessionsDir);
     const staleMs = resolvePositiveMs(params.staleMs, DEFAULT_STALE_MS);
@@ -256,7 +307,7 @@ export async function cleanStaleLockFiles(params) {
     const cleaned = [];
     const lockEntries = entries
         .filter((entry) => entry.name.endsWith(".jsonl.lock"))
-        .toSorted((a, b) => a.name.localeCompare(b.name));
+        .sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of lockEntries) {
         const lockPath = path.join(sessionsDir, entry.name);
         const payload = await readLockPayload(lockPath);
@@ -307,10 +358,16 @@ export async function acquireSessionWriteLock(params) {
     let attempt = 0;
     while (Date.now() - startedAt < timeoutMs) {
         attempt += 1;
+        let handle = null;
         try {
-            const handle = await fs.open(lockPath, "wx");
+            handle = await fs.open(lockPath, "wx");
             const createdAt = new Date().toISOString();
-            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt }, null, 2), "utf8");
+            const starttime = getProcessStartTime(process.pid);
+            const lockPayload = { pid: process.pid, createdAt };
+            if (starttime !== null) {
+                lockPayload.starttime = starttime;
+            }
+            await handle.writeFile(JSON.stringify(lockPayload, null, 2), "utf8");
             const createdHeld = {
                 count: 1,
                 handle,
@@ -326,13 +383,41 @@ export async function acquireSessionWriteLock(params) {
             };
         }
         catch (err) {
+            if (handle) {
+                try {
+                    await handle.close();
+                }
+                catch {
+                    // Ignore cleanup errors on failed lock initialization.
+                }
+                try {
+                    await fs.rm(lockPath, { force: true });
+                }
+                catch {
+                    // Ignore cleanup errors on failed lock initialization.
+                }
+            }
             const code = err.code;
             if (code !== "EEXIST") {
                 throw err;
             }
             const payload = await readLockPayload(lockPath);
-            const inspected = inspectLockPayload(payload, staleMs, Date.now());
-            if (inspected.stale) {
+            const nowMs = Date.now();
+            const inspected = inspectLockPayload(payload, staleMs, nowMs);
+            const orphanSelfLock = shouldTreatAsOrphanSelfLock({
+                payload,
+                normalizedSessionFile,
+            });
+            const reclaimDetails = orphanSelfLock
+                ? {
+                    ...inspected,
+                    stale: true,
+                    staleReasons: inspected.staleReasons.includes("orphan-self-pid")
+                        ? inspected.staleReasons
+                        : [...inspected.staleReasons, "orphan-self-pid"],
+                }
+                : inspected;
+            if (await shouldReclaimContendedLockFile(lockPath, reclaimDetails, staleMs, nowMs)) {
                 await fs.rm(lockPath, { force: true });
                 continue;
             }

package/dist/agents/tools/pdf-native-providers.js

@@ -0,0 +1,102 @@
+/**
+ * Direct SDK/HTTP calls for providers that support native PDF document input.
+ * This bypasses pi-ai's content type system which does not have a "document" type.
+ */
+import { isRecord } from "../../utils.js";
+import { normalizeSecretInput } from "../../utils/normalize-secret-input.js";
+export async function anthropicAnalyzePdf(params) {
+    const apiKey = normalizeSecretInput(params.apiKey);
+    if (!apiKey) {
+        throw new Error("Anthropic PDF: apiKey required");
+    }
+    const content = [];
+    for (const pdf of params.pdfs) {
+        content.push({
+            type: "document",
+            source: {
+                type: "base64",
+                media_type: "application/pdf",
+                data: pdf.base64,
+            },
+        });
+    }
+    content.push({ type: "text", text: params.prompt });
+    const baseUrl = (params.baseUrl ?? "https://api.anthropic.com").replace(/\/+$/, "");
+    const res = await fetch(`${baseUrl}/v1/messages`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-api-key": apiKey,
+            "anthropic-version": "2023-06-01",
+            "anthropic-beta": "pdfs-2024-09-25",
+        },
+        body: JSON.stringify({
+            model: params.modelId,
+            max_tokens: params.maxTokens ?? 4096,
+            messages: [{ role: "user", content }],
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Anthropic PDF request failed (${res.status} ${res.statusText})${body ? `: ${body.slice(0, 400)}` : ""}`);
+    }
+    const json = (await res.json().catch(() => null));
+    if (!isRecord(json)) {
+        throw new Error("Anthropic PDF response was not JSON.");
+    }
+    const responseContent = json.content;
+    if (!Array.isArray(responseContent)) {
+        throw new Error("Anthropic PDF response missing content array.");
+    }
+    const text = responseContent
+        .filter((block) => block.type === "text" && typeof block.text === "string")
+        .map((block) => block.text)
+        .join("");
+    if (!text.trim()) {
+        throw new Error("Anthropic PDF returned no text.");
+    }
+    return text.trim();
+}
+export async function geminiAnalyzePdf(params) {
+    const apiKey = normalizeSecretInput(params.apiKey);
+    if (!apiKey) {
+        throw new Error("Gemini PDF: apiKey required");
+    }
+    const parts = [];
+    for (const pdf of params.pdfs) {
+        parts.push({
+            inline_data: {
+                mime_type: "application/pdf",
+                data: pdf.base64,
+            },
+        });
+    }
+    parts.push({ text: params.prompt });
+    const baseUrl = (params.baseUrl ?? "https://generativelanguage.googleapis.com").replace(/\/+$/, "");
+    const url = `${baseUrl}/v1beta/models/${encodeURIComponent(params.modelId)}:generateContent?key=${encodeURIComponent(apiKey)}`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            contents: [{ role: "user", parts }],
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Gemini PDF request failed (${res.status} ${res.statusText})${body ? `: ${body.slice(0, 400)}` : ""}`);
+    }
+    const json = (await res.json().catch(() => null));
+    if (!isRecord(json)) {
+        throw new Error("Gemini PDF response was not JSON.");
+    }
+    const candidates = json.candidates;
+    if (!Array.isArray(candidates) || candidates.length === 0) {
+        throw new Error("Gemini PDF returned no candidates.");
+    }
+    const textParts = candidates[0].content?.parts?.filter((p) => typeof p.text === "string") ?? [];
+    const text = textParts.map((p) => p.text).join("");
+    if (!text.trim()) {
+        throw new Error("Gemini PDF returned no text.");
+    }
+    return text.trim();
+}

package/dist/agents/tools/pdf-tool.helpers.js

@@ -0,0 +1,86 @@
+import { extractAssistantText } from "../pi-embedded-utils.js";
+/**
+ * Providers known to support native PDF document input.
+ * When the model's provider is in this set, the tool sends raw PDF bytes
+ * via provider-specific API calls instead of extracting text/images first.
+ */
+export const NATIVE_PDF_PROVIDERS = new Set(["anthropic", "google"]);
+/**
+ * Check whether a provider supports native PDF document input.
+ */
+export function providerSupportsNativePdf(provider) {
+    return NATIVE_PDF_PROVIDERS.has(provider.toLowerCase().trim());
+}
+/**
+ * Parse a page range string (e.g. "1-5", "3", "1-3,7-9") into an array of 1-based page numbers.
+ */
+export function parsePageRange(range, maxPages) {
+    const pages = new Set();
+    const parts = range.split(",").map((p) => p.trim());
+    for (const part of parts) {
+        if (!part) {
+            continue;
+        }
+        const dashMatch = /^(\d+)\s*-\s*(\d+)$/.exec(part);
+        if (dashMatch) {
+            const start = Number(dashMatch[1]);
+            const end = Number(dashMatch[2]);
+            if (!Number.isFinite(start) || !Number.isFinite(end) || start < 1 || end < start) {
+                throw new Error(`Invalid page range: "${part}"`);
+            }
+            for (let i = start; i <= Math.min(end, maxPages); i++) {
+                pages.add(i);
+            }
+        }
+        else {
+            const num = Number(part);
+            if (!Number.isFinite(num) || num < 1) {
+                throw new Error(`Invalid page number: "${part}"`);
+            }
+            if (num <= maxPages) {
+                pages.add(num);
+            }
+        }
+    }
+    return Array.from(pages).toSorted((a, b) => a - b);
+}
+export function coercePdfAssistantText(params) {
+    const label = `${params.provider}/${params.model}`;
+    const errorMessage = params.message.errorMessage?.trim();
+    const fail = (message) => {
+        throw new Error(message ? `PDF model failed (${label}): ${message}` : `PDF model failed (${label})`);
+    };
+    if (params.message.stopReason === "error" || params.message.stopReason === "aborted") {
+        fail(errorMessage);
+    }
+    if (errorMessage) {
+        fail(errorMessage);
+    }
+    const text = extractAssistantText(params.message);
+    const trimmed = text.trim();
+    if (trimmed) {
+        return trimmed;
+    }
+    throw new Error(`PDF model returned no text (${label}).`);
+}
+/**
+ * Coerce the `agents.defaults.pdfModel` config value into a PdfModelConfig.
+ * Follows the same manual pattern as coerceImageModelConfig.
+ */
+export function coercePdfModelConfig(cfg) {
+    const pdfModel = cfg?.agents?.defaults?.pdfModel;
+    const primary = typeof pdfModel === "string" ? pdfModel.trim() : pdfModel?.primary;
+    const fallbacks = typeof pdfModel === "object" ? (pdfModel?.fallbacks ?? []) : [];
+    return {
+        ...(primary?.trim() ? { primary: primary.trim() } : {}),
+        ...(fallbacks.length > 0 ? { fallbacks } : {}),
+    };
+}
+export function resolvePdfToolMaxTokens(modelMaxTokens, requestedMaxTokens = 4096) {
+    if (typeof modelMaxTokens !== "number" ||
+        !Number.isFinite(modelMaxTokens) ||
+        modelMaxTokens <= 0) {
+        return requestedMaxTokens;
+    }
+    return Math.min(requestedMaxTokens, modelMaxTokens);
+}