@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/agent/structured-generation-providers.d.ts

@@ -0,0 +1,29 @@
+import type { AgentProvider } from "./agent-sdk-types.js";
+import type { StructuredGenerationProvider } from "./agent-response-loop.js";
+import type { ProviderSnapshotManager } from "./provider-snapshot-manager.js";
+export interface StructuredGenerationDaemonConfig {
+    metadataGeneration?: {
+        providers?: Array<{
+            provider: string;
+            model?: string;
+            thinkingOptionId?: string;
+        }>;
+    };
+}
+export interface StructuredGenerationProviderIdentifier {
+    modelSubstring: string;
+    thinkingOptionId?: string;
+}
+export declare const DEFAULT_STRUCTURED_GENERATION_PROVIDERS: readonly StructuredGenerationProviderIdentifier[];
+export interface ResolveStructuredGenerationProvidersOptions {
+    cwd: string;
+    providerSnapshotManager: Pick<ProviderSnapshotManager, "listProviders">;
+    daemonConfig?: StructuredGenerationDaemonConfig | null;
+    currentSelection?: {
+        provider?: AgentProvider | null;
+        model?: string | null;
+        thinkingOptionId?: string | null;
+    };
+}
+export declare function resolveStructuredGenerationProviders(options: ResolveStructuredGenerationProvidersOptions): Promise<StructuredGenerationProvider[]>;
+//# sourceMappingURL=structured-generation-providers.d.ts.map

package/dist/server/server/agent/structured-generation-providers.js

@@ -0,0 +1,193 @@
+export const DEFAULT_STRUCTURED_GENERATION_PROVIDERS = [
+    { modelSubstring: "haiku" },
+    { modelSubstring: "gpt-5.4-mini", thinkingOptionId: "low" },
+    { modelSubstring: "minimax-m3" },
+    { modelSubstring: "nemotron-3-super" },
+];
+export async function resolveStructuredGenerationProviders(options) {
+    const configuredProviders = readConfiguredProviders(options.daemonConfig);
+    const providerEntries = await options.providerSnapshotManager.listProviders({
+        cwd: options.cwd,
+        wait: true,
+    });
+    const enabledEntries = providerEntries.filter((entry) => entry.enabled);
+    const modelEntries = enabledEntries.filter((entry) => (entry.models?.length ?? 0) > 0);
+    const entriesByProvider = new Map(enabledEntries.map((entry) => [entry.provider, entry]));
+    const providers = [];
+    for (const configured of configuredProviders) {
+        const resolvedConfigured = resolveConfiguredCandidate(configured, modelEntries, entriesByProvider);
+        if (!resolvedConfigured) {
+            continue;
+        }
+        providers.push(resolvedConfigured);
+    }
+    for (const identifier of DEFAULT_STRUCTURED_GENERATION_PROVIDERS) {
+        const resolved = resolveByModelSubstring(modelEntries, identifier);
+        if (resolved) {
+            providers.push(resolved);
+        }
+    }
+    const currentSelection = resolveCurrentSelection(options.currentSelection, modelEntries, entriesByProvider);
+    if (currentSelection) {
+        providers.push(currentSelection);
+    }
+    return dedupeProviders(providers);
+}
+function resolveCurrentSelection(selection, readyEntries, entriesByProvider) {
+    if (!selection) {
+        return null;
+    }
+    const provider = selection.provider?.trim();
+    if (!provider) {
+        return null;
+    }
+    const normalized = resolveConfiguredCandidate({
+        provider,
+        ...(selection.model ? { model: selection.model } : {}),
+        ...(selection.thinkingOptionId ? { thinkingOptionId: selection.thinkingOptionId } : {}),
+    }, readyEntries, entriesByProvider);
+    if (normalized) {
+        return normalized;
+    }
+    const explicitModel = selection.model?.trim();
+    if (explicitModel) {
+        return {
+            provider,
+            model: explicitModel,
+            ...(selection.thinkingOptionId ? { thinkingOptionId: selection.thinkingOptionId } : {}),
+        };
+    }
+    const model = selectDefaultModel(entriesByProvider.get(provider)?.models ?? []);
+    if (!model) {
+        return { provider };
+    }
+    const thinkingOptionId = resolveThinkingOptionId(model, selection.thinkingOptionId);
+    return {
+        provider,
+        model: model.id,
+        ...(thinkingOptionId ? { thinkingOptionId } : {}),
+    };
+}
+function resolveConfiguredCandidate(candidate, readyEntries, entriesByProvider) {
+    const provider = candidate.provider.trim();
+    if (!provider) {
+        return null;
+    }
+    const topLevelEntry = entriesByProvider.get(provider);
+    const configuredModel = candidate.model?.trim();
+    if (topLevelEntry) {
+        if (configuredModel) {
+            return {
+                provider,
+                model: configuredModel,
+                ...(candidate.thinkingOptionId ? { thinkingOptionId: candidate.thinkingOptionId } : {}),
+            };
+        }
+        const model = selectDefaultModel(topLevelEntry.models ?? []);
+        const thinkingOptionId = resolveThinkingOptionId(model, candidate.thinkingOptionId);
+        return {
+            provider,
+            ...(model ? { model: model.id } : {}),
+            ...(thinkingOptionId ? { thinkingOptionId } : {}),
+        };
+    }
+    if (!configuredModel) {
+        return {
+            provider,
+            ...(candidate.thinkingOptionId ? { thinkingOptionId: candidate.thinkingOptionId } : {}),
+        };
+    }
+    const nestedMatch = resolveNestedProviderModel(provider, configuredModel, readyEntries);
+    if (!nestedMatch) {
+        return {
+            provider,
+            model: configuredModel,
+            ...(candidate.thinkingOptionId ? { thinkingOptionId: candidate.thinkingOptionId } : {}),
+        };
+    }
+    const thinkingOptionId = resolveThinkingOptionId(nestedMatch.model, candidate.thinkingOptionId);
+    return {
+        provider: nestedMatch.provider,
+        model: nestedMatch.model.id,
+        ...(thinkingOptionId ? { thinkingOptionId } : {}),
+    };
+}
+function resolveNestedProviderModel(providerId, modelId, entries) {
+    const normalizedProviderId = providerId.trim().toLowerCase();
+    const normalizedModelId = modelId.trim().toLowerCase();
+    for (const entry of entries) {
+        for (const model of entry.models ?? []) {
+            const modelProviderId = readModelMetadataString(model, "providerId")?.toLowerCase();
+            const nestedModelId = readModelMetadataString(model, "modelId")?.toLowerCase();
+            if (modelProviderId !== normalizedProviderId) {
+                continue;
+            }
+            if (normalizedModelId === model.id.toLowerCase() ||
+                normalizedModelId === nestedModelId ||
+                model.id.toLowerCase() === `${normalizedProviderId}/${normalizedModelId}`) {
+                return { provider: entry.provider, model };
+            }
+        }
+    }
+    return null;
+}
+function resolveByModelSubstring(entries, identifier) {
+    const needle = identifier.modelSubstring.trim().toLowerCase();
+    if (!needle) {
+        return null;
+    }
+    for (const entry of entries) {
+        for (const model of entry.models ?? []) {
+            const haystacks = [model.id, model.label].map((value) => value.toLowerCase());
+            if (!haystacks.some((value) => value.includes(needle))) {
+                continue;
+            }
+            const thinkingOptionId = resolveThinkingOptionId(model, identifier.thinkingOptionId);
+            return {
+                provider: entry.provider,
+                model: model.id,
+                ...(thinkingOptionId ? { thinkingOptionId } : {}),
+            };
+        }
+    }
+    return null;
+}
+function readConfiguredProviders(daemonConfig) {
+    const metadataGeneration = daemonConfig?.metadataGeneration;
+    if (!metadataGeneration || typeof metadataGeneration !== "object") {
+        return [];
+    }
+    const providers = "providers" in metadataGeneration ? metadataGeneration.providers : undefined;
+    return Array.isArray(providers) ? providers : [];
+}
+function selectDefaultModel(models) {
+    return models.find((model) => model.isDefault) ?? models[0] ?? null;
+}
+function resolveThinkingOptionId(model, preferredThinkingOptionId) {
+    if (!model) {
+        return undefined;
+    }
+    if (preferredThinkingOptionId &&
+        model.thinkingOptions?.some((option) => option.id === preferredThinkingOptionId)) {
+        return preferredThinkingOptionId;
+    }
+    return model.defaultThinkingOptionId;
+}
+function dedupeProviders(providers) {
+    const seen = new Set();
+    const deduped = [];
+    for (const provider of providers) {
+        const key = [provider.provider, provider.model ?? "", provider.thinkingOptionId ?? ""].join("\0");
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(provider);
+    }
+    return deduped;
+}
+function readModelMetadataString(model, key) {
+    const value = model.metadata?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+//# sourceMappingURL=structured-generation-providers.js.map

package/dist/server/server/agent/stt-debug.d.ts

@@ -0,0 +1,10 @@
+import type pino from "pino";
+export interface DebugAudioMetadata {
+    sessionId: string;
+    agentId?: string;
+    requestId?: string;
+    label?: string;
+    format: string;
+}
+export declare function maybePersistDebugAudio(audio: Buffer, metadata: DebugAudioMetadata, logger: pino.Logger): Promise<string | null>;
+//# sourceMappingURL=stt-debug.d.ts.map

package/dist/server/server/agent/stt-debug.js

@@ -0,0 +1,33 @@
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { inferAudioExtension, sanitizeForFilename } from "./audio-utils.js";
+import { resolveRecordingsDebugDir } from "./recordings-debug.js";
+const debugDir = resolveRecordingsDebugDir("STT_DEBUG_AUDIO_DIR");
+let announced = false;
+export async function maybePersistDebugAudio(audio, metadata, logger) {
+    if (!debugDir) {
+        return null;
+    }
+    if (!announced) {
+        logger.info({ debugDir }, "Raw audio capture enabled");
+        announced = true;
+    }
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const folder = join(debugDir, sanitizeForFilename(metadata.sessionId, "session"));
+    await mkdir(folder, { recursive: true });
+    const parts = [timestamp];
+    if (metadata.agentId) {
+        parts.push(sanitizeForFilename(metadata.agentId, "agent"));
+    }
+    if (metadata.label) {
+        parts.push(sanitizeForFilename(metadata.label, "source"));
+    }
+    if (metadata.requestId) {
+        parts.push(sanitizeForFilename(metadata.requestId, "request"));
+    }
+    const ext = inferAudioExtension(metadata.format);
+    const filePath = join(folder, `${parts.join("_")}.${ext}`);
+    await writeFile(filePath, audio);
+    return filePath;
+}
+//# sourceMappingURL=stt-debug.js.map

package/dist/server/server/agent/stt-manager.d.ts

@@ -0,0 +1,38 @@
+import type pino from "pino";
+import type { SpeechToTextProvider, TranscriptionResult } from "../speech/speech-provider.js";
+import { type Resolvable } from "../speech/provider-resolver.js";
+interface TranscriptionMetadata {
+    agentId?: string;
+    requestId?: string;
+    label?: string;
+}
+export interface SessionTranscriptionResult extends TranscriptionResult {
+    debugRecordingPath?: string;
+    byteLength: number;
+    format: string;
+}
+export interface STTManagerOptions {
+    language?: string;
+}
+/**
+ * Per-session STT manager
+ * Handles speech-to-text transcription
+ */
+export declare class STTManager {
+    private readonly sessionId;
+    private readonly logger;
+    private readonly resolveStt;
+    private readonly language;
+    constructor(sessionId: string, logger: pino.Logger, stt: Resolvable<SpeechToTextProvider | null>, options?: STTManagerOptions);
+    getProvider(): SpeechToTextProvider | null;
+    /**
+     * Transcribe audio buffer to text
+     */
+    transcribe(audio: Buffer, format: string, metadata?: TranscriptionMetadata): Promise<SessionTranscriptionResult>;
+    /**
+     * Cleanup (currently no-op, but provides extension point)
+     */
+    cleanup(): void;
+}
+export {};
+//# sourceMappingURL=stt-manager.d.ts.map

package/dist/server/server/agent/stt-manager.js

@@ -0,0 +1,246 @@
+import { toResolver } from "../speech/provider-resolver.js";
+import { maybePersistDebugAudio } from "./stt-debug.js";
+import { parsePcm16MonoWav, parsePcmRateFromFormat } from "../speech/audio.js";
+import { Pcm16MonoResampler } from "./pcm16-resampler.js";
+const BATCH_APPEND_CHUNK_SECONDS = 1;
+const DEFAULT_BATCH_COMMIT_EVERY_SECONDS = 15;
+const BATCH_FINAL_TIMEOUT_MS = 120000;
+function assembleTranscriptionResult(params) {
+    const { committedSegmentIds, transcriptsBySegmentId, finalTranscriptSegmentIds, transcriptMetaBySegmentId, durationMs, } = params;
+    const committedSet = new Set(committedSegmentIds);
+    const orderedSegmentIds = [...committedSegmentIds];
+    for (const segmentId of transcriptsBySegmentId.keys()) {
+        if (!committedSet.has(segmentId)) {
+            orderedSegmentIds.push(segmentId);
+        }
+    }
+    const transcript = orderedSegmentIds
+        .map((segmentId) => transcriptsBySegmentId.get(segmentId) ?? "")
+        .join(" ")
+        .trim();
+    const orderedFinalMeta = orderedSegmentIds
+        .filter((segmentId) => finalTranscriptSegmentIds.has(segmentId))
+        .map((segmentId) => transcriptMetaBySegmentId.get(segmentId))
+        .filter((meta) => Boolean(meta));
+    const language = orderedFinalMeta.find((meta) => meta.language)?.language;
+    const singleSegmentMeta = orderedFinalMeta.length === 1 ? orderedFinalMeta[0] : null;
+    const allLowConfidence = orderedFinalMeta.length > 0 && orderedFinalMeta.every((meta) => meta.isLowConfidence === true);
+    return {
+        text: transcript,
+        ...(language ? { language } : {}),
+        ...(singleSegmentMeta?.logprobs ? { logprobs: singleSegmentMeta.logprobs } : {}),
+        ...(singleSegmentMeta?.avgLogprob !== undefined
+            ? { avgLogprob: singleSegmentMeta.avgLogprob }
+            : {}),
+        ...(allLowConfidence ? { isLowConfidence: true } : {}),
+        duration: durationMs,
+    };
+}
+function preparePcmForModel(audio, format, requiredSampleRate) {
+    let inputRate;
+    let pcm16;
+    if (format.toLowerCase().includes("audio/wav")) {
+        const parsed = parsePcm16MonoWav(audio);
+        inputRate = parsed.sampleRate;
+        pcm16 = parsed.pcm16;
+    }
+    else if (format.toLowerCase().includes("audio/pcm")) {
+        inputRate = parsePcmRateFromFormat(format, requiredSampleRate) ?? requiredSampleRate;
+        pcm16 = audio;
+    }
+    else {
+        throw new Error(`Unsupported audio format for STT: ${format}`);
+    }
+    if (inputRate === requiredSampleRate) {
+        return pcm16;
+    }
+    const resampler = new Pcm16MonoResampler({
+        inputRate,
+        outputRate: requiredSampleRate,
+    });
+    return resampler.processChunk(pcm16);
+}
+function resolveBatchCommitEverySeconds() {
+    const fromEnv = process.env.PASEO_STT_BATCH_COMMIT_EVERY_SECONDS;
+    if (!fromEnv) {
+        return DEFAULT_BATCH_COMMIT_EVERY_SECONDS;
+    }
+    const parsed = Number.parseFloat(fromEnv);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return DEFAULT_BATCH_COMMIT_EVERY_SECONDS;
+    }
+    return parsed;
+}
+/**
+ * Per-session STT manager
+ * Handles speech-to-text transcription
+ */
+export class STTManager {
+    constructor(sessionId, logger, stt, options) {
+        this.sessionId = sessionId;
+        this.logger = logger.child({ module: "agent", component: "stt-manager", sessionId });
+        this.resolveStt = toResolver(stt);
+        this.language = options?.language ?? "en";
+    }
+    getProvider() {
+        return this.resolveStt();
+    }
+    /**
+     * Transcribe audio buffer to text
+     */
+    async transcribe(audio, format, metadata) {
+        const stt = this.resolveStt();
+        if (!stt) {
+            throw new Error("STT not configured");
+        }
+        this.logger.debug({ bytes: audio.length, format, label: metadata?.label }, "Transcribing audio");
+        let debugRecordingPath = null;
+        try {
+            debugRecordingPath = await maybePersistDebugAudio(audio, {
+                sessionId: this.sessionId,
+                agentId: metadata?.agentId,
+                requestId: metadata?.requestId,
+                label: metadata?.label,
+                format,
+            }, this.logger);
+        }
+        catch (error) {
+            this.logger.warn({ err: error }, "Failed to persist debug audio");
+        }
+        const session = stt.createSession({
+            logger: this.logger.child({ component: "stt-session" }),
+            language: this.language,
+        });
+        const pcmForModel = preparePcmForModel(audio, format, session.requiredSampleRate);
+        try {
+            const startedAt = Date.now();
+            await session.connect();
+            const committedSegmentIds = [];
+            const transcriptsBySegmentId = new Map();
+            const finalTranscriptSegmentIds = new Set();
+            const transcriptMetaBySegmentId = new Map();
+            let expectedFinals = 0;
+            let settle = null;
+            let fail = null;
+            let settled = false;
+            const allFinalsReady = new Promise((resolve, reject) => {
+                settle = resolve;
+                fail = reject;
+            });
+            const resolveIfComplete = () => {
+                if (settled) {
+                    return;
+                }
+                if (expectedFinals > 0 && finalTranscriptSegmentIds.size >= expectedFinals) {
+                    settled = true;
+                    settle?.();
+                    return;
+                }
+                if (expectedFinals === 0 && finalTranscriptSegmentIds.size > 0) {
+                    settled = true;
+                    settle?.();
+                }
+            };
+            const rejectWith = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                fail?.(error);
+            };
+            session.on("error", (error) => {
+                rejectWith(error instanceof Error ? error : new Error(String(error)));
+            });
+            session.on("committed", ({ segmentId }) => {
+                committedSegmentIds.push(segmentId);
+                expectedFinals += 1;
+                resolveIfComplete();
+            });
+            session.on("transcript", (payload) => {
+                transcriptsBySegmentId.set(payload.segmentId, payload.transcript);
+                if (!payload.isFinal) {
+                    return;
+                }
+                finalTranscriptSegmentIds.add(payload.segmentId);
+                transcriptMetaBySegmentId.set(payload.segmentId, {
+                    language: payload.language,
+                    logprobs: payload.logprobs,
+                    avgLogprob: payload.avgLogprob,
+                    isLowConfidence: payload.isLowConfidence,
+                });
+                resolveIfComplete();
+            });
+            const appendChunkBytes = Math.max(1, Math.round(session.requiredSampleRate * 2 * BATCH_APPEND_CHUNK_SECONDS));
+            const commitEverySeconds = resolveBatchCommitEverySeconds();
+            const commitEveryBytes = commitEverySeconds > 0
+                ? Math.max(1, Math.round(session.requiredSampleRate * 2 * commitEverySeconds))
+                : 0;
+            let bytesSinceCommit = 0;
+            for (let offset = 0; offset < pcmForModel.length; offset += appendChunkBytes) {
+                const chunk = pcmForModel.subarray(offset, Math.min(pcmForModel.length, offset + appendChunkBytes));
+                if (chunk.length === 0) {
+                    continue;
+                }
+                session.appendPcm16(chunk);
+                bytesSinceCommit += chunk.length;
+                if (commitEveryBytes > 0 && bytesSinceCommit >= commitEveryBytes) {
+                    session.commit();
+                    bytesSinceCommit = 0;
+                }
+            }
+            if (bytesSinceCommit > 0 || expectedFinals === 0) {
+                session.commit();
+            }
+            const finalTimeout = setTimeout(() => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                this.logger.warn({
+                    expectedFinals,
+                    receivedFinals: finalTranscriptSegmentIds.size,
+                    label: metadata?.label,
+                }, "Timed out waiting for final STT segments; returning available transcripts");
+                settle?.();
+            }, BATCH_FINAL_TIMEOUT_MS);
+            await allFinalsReady;
+            clearTimeout(finalTimeout);
+            const result = assembleTranscriptionResult({
+                committedSegmentIds,
+                transcriptsBySegmentId,
+                finalTranscriptSegmentIds,
+                transcriptMetaBySegmentId,
+                durationMs: Date.now() - startedAt,
+            });
+            // Filter out low-confidence transcriptions (non-speech sounds)
+            if (result.isLowConfidence) {
+                this.logger.debug({ text: result.text, avgLogprob: result.avgLogprob }, "Filtered low-confidence transcription (likely non-speech)");
+                // Return empty text to ignore this transcription
+                return {
+                    ...result,
+                    text: "",
+                    byteLength: audio.length,
+                    format,
+                    debugRecordingPath: debugRecordingPath ?? undefined,
+                };
+            }
+            this.logger.debug({ text: result.text, avgLogprob: result.avgLogprob }, "Transcription complete");
+            return {
+                ...result,
+                debugRecordingPath: debugRecordingPath ?? undefined,
+                byteLength: audio.length,
+                format,
+            };
+        }
+        finally {
+            session.close();
+        }
+    }
+    /**
+     * Cleanup (currently no-op, but provides extension point)
+     */
+    cleanup() {
+        // No cleanup needed for STT currently
+    }
+}
+//# sourceMappingURL=stt-manager.js.map

package/dist/server/server/agent/system-prompt.d.ts

@@ -0,0 +1,2 @@
+export declare function composeSystemPromptParts(...parts: Array<string | null | undefined>): string | undefined;
+//# sourceMappingURL=system-prompt.d.ts.map

package/dist/server/server/agent/system-prompt.js

@@ -0,0 +1,8 @@
+export function composeSystemPromptParts(...parts) {
+    const prompt = parts
+        .map((part) => part?.trim())
+        .filter((part) => typeof part === "string" && part.length > 0)
+        .join("\n\n");
+    return prompt.length > 0 ? prompt : undefined;
+}
+//# sourceMappingURL=system-prompt.js.map

package/dist/server/server/agent/timeline-append.d.ts

@@ -0,0 +1,10 @@
+import type { AgentManager } from "./agent-manager.js";
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
+export interface AppendTimelineItemIfAgentKnownOptions {
+    agentManager: AgentManager;
+    agentId: string;
+    item: AgentTimelineItem;
+}
+export declare function appendTimelineItemIfAgentKnown(options: AppendTimelineItemIfAgentKnownOptions): Promise<boolean>;
+export declare function emitLiveTimelineItemIfAgentKnown(options: AppendTimelineItemIfAgentKnownOptions): Promise<boolean>;
+//# sourceMappingURL=timeline-append.d.ts.map

package/dist/server/server/agent/timeline-append.js

@@ -0,0 +1,27 @@
+export async function appendTimelineItemIfAgentKnown(options) {
+    try {
+        await options.agentManager.appendTimelineItem(options.agentId, options.item);
+        return true;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("Unknown agent")) {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function emitLiveTimelineItemIfAgentKnown(options) {
+    try {
+        await options.agentManager.emitLiveTimelineItem(options.agentId, options.item);
+        return true;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("Unknown agent")) {
+            return false;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=timeline-append.js.map

package/dist/server/server/agent/timeline-page-bounds.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Find the largest projected-item limit in `[1, maxLimit]` whose selected page
+ * fits `budgetBytes`. `measurePageBytes` re-selects the page for a candidate limit
+ * and returns its serialized size; page size is assumed monotonic non-decreasing
+ * in limit (a larger projected window never yields a smaller page).
+ *
+ * The budget is enforced on the *selected* page rather than a pre-selection entry
+ * count because projection can expand a reduced limit back over a wide/merged tool
+ * entry's source span, so the only reliable size is the one measured after
+ * selection. Returns `maxLimit` unchanged when the full page already fits, and `1`
+ * as a forward-progress floor when even the smallest page exceeds the budget (an
+ * unpageable wide entry) so pagination never stalls.
+ */
+export declare function largestFittingProjectedLimit(input: {
+    maxLimit: number;
+    budgetBytes: number;
+    measurePageBytes: (limit: number) => number;
+}): number;
+//# sourceMappingURL=timeline-page-bounds.d.ts.map

package/dist/server/server/agent/timeline-page-bounds.js

@@ -0,0 +1,37 @@
+/**
+ * Find the largest projected-item limit in `[1, maxLimit]` whose selected page
+ * fits `budgetBytes`. `measurePageBytes` re-selects the page for a candidate limit
+ * and returns its serialized size; page size is assumed monotonic non-decreasing
+ * in limit (a larger projected window never yields a smaller page).
+ *
+ * The budget is enforced on the *selected* page rather than a pre-selection entry
+ * count because projection can expand a reduced limit back over a wide/merged tool
+ * entry's source span, so the only reliable size is the one measured after
+ * selection. Returns `maxLimit` unchanged when the full page already fits, and `1`
+ * as a forward-progress floor when even the smallest page exceeds the budget (an
+ * unpageable wide entry) so pagination never stalls.
+ */
+export function largestFittingProjectedLimit(input) {
+    const { maxLimit, budgetBytes, measurePageBytes } = input;
+    if (maxLimit <= 1) {
+        return maxLimit;
+    }
+    if (measurePageBytes(maxLimit) <= budgetBytes) {
+        return maxLimit;
+    }
+    let low = 1;
+    let high = maxLimit - 1;
+    let best = 1;
+    while (low <= high) {
+        const mid = low + Math.floor((high - low) / 2);
+        if (measurePageBytes(mid) <= budgetBytes) {
+            best = mid;
+            low = mid + 1;
+        }
+        else {
+            high = mid - 1;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=timeline-page-bounds.js.map