@hyperdrive.bot/paseo-server 0.2.6

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-projection.d.ts

@@ -0,0 +1,71 @@
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
+import type { AgentTimelineRow } from "./agent-manager.js";
+export type TimelineProjectionMode = "canonical" | "projected";
+export interface TimelineSeqRange {
+    startSeq: number;
+    endSeq: number;
+}
+export type TimelineProjectionKind = "assistant_merge" | "reasoning_merge" | "tool_lifecycle";
+export type TimelineLimitDirection = "tail" | "before" | "after";
+export interface TimelineProjectionEntry {
+    item: AgentTimelineItem;
+    timestamp: string;
+    seqStart: number;
+    seqEnd: number;
+    sourceSeqRanges: TimelineSeqRange[];
+    collapsed: TimelineProjectionKind[];
+}
+interface ProjectedWindowSelection {
+    projectedEntries: TimelineProjectionEntry[];
+    selectedRows: AgentTimelineRow[];
+    minSeq: number | null;
+    maxSeq: number | null;
+}
+export interface ProjectedTimelinePageSelection {
+    entries: TimelineProjectionEntry[];
+    startSeq: number | null;
+    endSeq: number | null;
+    hasOlder: boolean;
+    hasNewer: boolean;
+}
+export declare function projectTimelineRows(input: {
+    rows: readonly AgentTimelineRow[];
+    mode: TimelineProjectionMode;
+}): TimelineProjectionEntry[];
+/**
+ * Select a timeline window based on projected-entry count, then map it back to
+ * contiguous canonical rows. This avoids cutting through merged assistant
+ * chunks when callers request canonical rows with a bounded limit.
+ */
+export declare function selectTimelineWindowByProjectedLimit(input: {
+    rows: readonly AgentTimelineRow[];
+    direction: TimelineLimitDirection;
+    limit: number;
+}): ProjectedWindowSelection;
+export declare function selectProjectedTimelinePage(input: {
+    rows: readonly AgentTimelineRow[];
+    bounds?: {
+        minSeq: number;
+        maxSeq: number;
+    };
+    direction: TimelineLimitDirection;
+    cursorSeq?: number;
+    limit?: number;
+}): ProjectedTimelinePageSelection;
+/**
+ * Apply a projected-count limit to a flat AgentTimelineItem[] without seq metadata.
+ * Used by callers that only have items in hand (e.g. MCP tools reading
+ * `agentManager.getTimeline`). Index position is treated as canonical seq.
+ */
+export interface ProjectedItemSelection {
+    items: AgentTimelineItem[];
+    totalProjected: number;
+    shownProjected: number;
+}
+export declare function selectItemsByProjectedLimit(input: {
+    items: readonly AgentTimelineItem[];
+    direction: TimelineLimitDirection;
+    limit: number;
+}): ProjectedItemSelection;
+export {};
+//# sourceMappingURL=timeline-projection.d.ts.map