@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/agent/tools/types.d.ts

@@ -0,0 +1,39 @@
+import type { z } from "zod";
+import type { ProviderPaseoToolsPolicy } from "@camerontaylor/paseo-protocol/provider-config";
+export interface PaseoToolExecutionContext {
+    signal?: AbortSignal;
+    sendUpdate?: (update: PaseoToolResult) => void;
+}
+export interface PaseoToolResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    structuredContent?: unknown;
+    isError?: boolean;
+}
+export interface PaseoToolConfig {
+    title?: string;
+    description?: string;
+    inputSchema?: z.ZodRawShape | z.ZodType;
+    outputSchema?: z.ZodRawShape;
+}
+export interface PaseoToolDefinition extends PaseoToolConfig {
+    name: string;
+    description: string;
+    handler: (input: unknown, context: PaseoToolExecutionContext) => Promise<PaseoToolResult>;
+}
+export interface PaseoToolCatalog {
+    tools: ReadonlyMap<string, PaseoToolDefinition>;
+    getTool(name: string): PaseoToolDefinition | undefined;
+    executeTool(name: string, input: unknown, context?: PaseoToolExecutionContext): Promise<PaseoToolResult>;
+}
+export interface PaseoToolRuntimeContext {
+    callerAgentId?: string;
+    paseoToolPolicy?: ProviderPaseoToolsPolicy;
+    enableVoiceTools?: boolean;
+    voiceOnly?: boolean;
+}
+export type PaseoToolCatalogFactory = (context: PaseoToolRuntimeContext) => PaseoToolCatalog | Promise<PaseoToolCatalog>;
+//# sourceMappingURL=types.d.ts.map

package/dist/server/server/agent/tools/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,8 @@
+import type pino from "pino";
+export interface TtsDebugAudioMetadata {
+    sessionId: string;
+    groupId: string;
+    format: string;
+}
+export declare function maybePersistTtsDebugAudio(audio: Buffer, metadata: TtsDebugAudioMetadata, logger: pino.Logger): Promise<string | null>;
+//# sourceMappingURL=tts-debug.d.ts.map

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

@@ -0,0 +1,24 @@
+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("TTS_DEBUG_AUDIO_DIR");
+let announced = false;
+export async function maybePersistTtsDebugAudio(audio, metadata, logger) {
+    if (!debugDir) {
+        return null;
+    }
+    if (!announced) {
+        logger.info({ debugDir }, "TTS 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, sanitizeForFilename(metadata.groupId, "tts")];
+    const ext = inferAudioExtension(metadata.format);
+    const filePath = join(folder, `${parts.join("_")}.${ext}`);
+    await writeFile(filePath, audio);
+    return filePath;
+}
+//# sourceMappingURL=tts-debug.js.map

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

@@ -0,0 +1,41 @@
+import type pino from "pino";
+import type { TextToSpeechProvider } from "../speech/speech-provider.js";
+import { type Resolvable } from "../speech/provider-resolver.js";
+import type { SessionOutboundMessage } from "../messages.js";
+/**
+ * Per-session TTS manager
+ * Handles TTS audio generation and playback confirmation tracking
+ */
+export declare class TTSManager {
+    private pendingPlaybacks;
+    private readonly recentlyClosedAudioIds;
+    private readonly logger;
+    private readonly resolveTts;
+    constructor(sessionId: string, logger: pino.Logger, tts: Resolvable<TextToSpeechProvider | null>);
+    /**
+     * Generate TTS audio, emit to client, and wait for playback confirmation
+     * Returns a Promise that resolves when the client confirms playback completed
+     */
+    generateAndWaitForPlayback(text: string, emitMessage: (msg: SessionOutboundMessage) => void, abortSignal: AbortSignal, isVoiceMode: boolean): Promise<void>;
+    private synthesizeSegment;
+    private scheduleSegmentSynthesis;
+    private cleanupPrefetchedSegments;
+    private destroySpeechStream;
+    private pruneRecentlyClosedAudioIds;
+    private rememberClosedAudioId;
+    private emitPreparedSegment;
+    /**
+     * Called when client confirms audio playback completed
+     * Resolves the corresponding promise
+     */
+    confirmAudioPlayed(chunkId: string): void;
+    /**
+     * Cancel all pending playbacks (e.g., user interrupted audio)
+     */
+    cancelPendingPlaybacks(reason: string): void;
+    /**
+     * Cleanup all pending playbacks
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=tts-manager.d.ts.map

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

@@ -0,0 +1,375 @@
+import { v4 as uuidv4 } from "uuid";
+import { toResolver } from "../speech/provider-resolver.js";
+const MAX_TTS_SEGMENT_CHARS = 260;
+const TTS_PREFETCH_SEGMENTS = 2;
+const CLOSED_AUDIO_ID_TTL_MS = 10000;
+function splitOversizedFragment(fragment, maxChars) {
+    const trimmed = fragment.trim();
+    if (!trimmed) {
+        return [];
+    }
+    if (trimmed.length <= maxChars) {
+        return [trimmed];
+    }
+    const clauseChunks = trimmed.split(/(?<=[,;:])\s+/);
+    if (clauseChunks.length > 1) {
+        const parts = [];
+        let current = "";
+        const pushCurrent = () => {
+            const value = current.trim();
+            if (value) {
+                parts.push(value);
+            }
+            current = "";
+        };
+        for (const clause of clauseChunks) {
+            const clauseText = clause.trim();
+            if (!clauseText) {
+                continue;
+            }
+            if (clauseText.length > maxChars) {
+                pushCurrent();
+                parts.push(...splitOversizedFragment(clauseText, maxChars));
+                continue;
+            }
+            if (!current) {
+                current = clauseText;
+                continue;
+            }
+            const candidate = `${current} ${clauseText}`;
+            if (candidate.length <= maxChars) {
+                current = candidate;
+                continue;
+            }
+            pushCurrent();
+            current = clauseText;
+        }
+        pushCurrent();
+        if (parts.length > 1 || parts[0] !== trimmed) {
+            return parts;
+        }
+    }
+    const parts = [];
+    let remaining = trimmed;
+    while (remaining.length > maxChars) {
+        let idx = remaining.lastIndexOf(" ", maxChars);
+        if (idx < Math.floor(maxChars * 0.5)) {
+            idx = maxChars;
+        }
+        parts.push(remaining.slice(0, idx).trim());
+        remaining = remaining.slice(idx).trim();
+    }
+    if (remaining.length > 0) {
+        parts.push(remaining);
+    }
+    return parts;
+}
+function splitTextForTts(text) {
+    const normalized = text.trim().replace(/\s+/g, " ");
+    if (!normalized) {
+        throw new Error("Cannot synthesize empty text");
+    }
+    const sentences = normalized.split(/(?<=[.!?])\s+/);
+    const parts = [];
+    let segmentIndex = 0;
+    for (const sentence of sentences) {
+        const fragments = splitOversizedFragment(sentence, MAX_TTS_SEGMENT_CHARS);
+        for (const fragment of fragments) {
+            parts.push({ index: segmentIndex, text: fragment });
+            segmentIndex += 1;
+        }
+    }
+    return parts;
+}
+/**
+ * Per-session TTS manager
+ * Handles TTS audio generation and playback confirmation tracking
+ */
+export class TTSManager {
+    constructor(sessionId, logger, tts) {
+        this.pendingPlaybacks = new Map();
+        this.recentlyClosedAudioIds = new Map();
+        this.logger = logger.child({ module: "agent", component: "tts-manager", sessionId });
+        this.resolveTts = toResolver(tts);
+    }
+    /**
+     * Generate TTS audio, emit to client, and wait for playback confirmation
+     * Returns a Promise that resolves when the client confirms playback completed
+     */
+    async generateAndWaitForPlayback(text, emitMessage, abortSignal, isVoiceMode) {
+        const ttsStartMs = Date.now();
+        this.logger.info({
+            isVoiceMode,
+            textLength: text.length,
+            text,
+        }, "TTS input text");
+        const segments = splitTextForTts(text);
+        this.logger.info({
+            segmentCount: segments.length,
+            segments: segments.map((s) => ({
+                index: s.index,
+                chars: s.text.length,
+                text: s.text.slice(0, 80),
+            })),
+        }, `TTS split into ${segments.length} segment(s)`);
+        const inflight = new Map();
+        let nextSegmentToSchedule = 0;
+        const scheduleNextSegments = () => {
+            while (nextSegmentToSchedule < segments.length && inflight.size < TTS_PREFETCH_SEGMENTS) {
+                const segment = segments[nextSegmentToSchedule];
+                inflight.set(segment.index, this.scheduleSegmentSynthesis(segment, abortSignal));
+                nextSegmentToSchedule += 1;
+            }
+        };
+        scheduleNextSegments();
+        try {
+            for (const segment of segments) {
+                if (abortSignal.aborted) {
+                    this.logger.debug("Aborted before emitting segmented audio");
+                    return;
+                }
+                const synthWaitStart = Date.now();
+                const result = await inflight.get(segment.index);
+                const synthWaitMs = Date.now() - synthWaitStart;
+                inflight.delete(segment.index);
+                scheduleNextSegments();
+                if (result.kind === "aborted") {
+                    return;
+                }
+                if (result.kind === "error") {
+                    throw result.error;
+                }
+                this.logger.info({
+                    segmentIndex: segment.index,
+                    synthWaitMs,
+                    totalElapsedMs: Date.now() - ttsStartMs,
+                    chars: segment.text.length,
+                }, `TTS segment ${segment.index} synthesis ready (waited ${synthWaitMs}ms, total ${Date.now() - ttsStartMs}ms)`);
+                const emitStart = Date.now();
+                await this.emitPreparedSegment({
+                    prepared: result.prepared,
+                    emitMessage,
+                    abortSignal,
+                    isVoiceMode,
+                });
+                this.logger.info({
+                    segmentIndex: segment.index,
+                    emitAndPlayMs: Date.now() - emitStart,
+                    totalElapsedMs: Date.now() - ttsStartMs,
+                }, `TTS segment ${segment.index} playback confirmed (emit+play ${Date.now() - emitStart}ms, total ${Date.now() - ttsStartMs}ms)`);
+                scheduleNextSegments();
+            }
+        }
+        finally {
+            this.cleanupPrefetchedSegments(inflight);
+            this.logger.info({ totalMs: Date.now() - ttsStartMs }, `TTS generateAndWaitForPlayback done (${Date.now() - ttsStartMs}ms)`);
+        }
+    }
+    async synthesizeSegment(segment, abortSignal) {
+        const resolveStart = Date.now();
+        const tts = this.resolveTts();
+        if (!tts) {
+            throw new Error("TTS not configured");
+        }
+        const resolveMs = Date.now() - resolveStart;
+        if (abortSignal.aborted) {
+            throw new Error("TTS synthesis aborted");
+        }
+        const synthStart = Date.now();
+        const { stream, format } = await tts.synthesizeSpeech(segment.text);
+        this.logger.info({
+            segmentIndex: segment.index,
+            resolveMs,
+            synthMs: Date.now() - synthStart,
+            chars: segment.text.length,
+        }, `TTS segment ${segment.index} synthesized (resolve=${resolveMs}ms, synth=${Date.now() - synthStart}ms, ${segment.text.length} chars)`);
+        if (abortSignal.aborted) {
+            this.destroySpeechStream(stream);
+            throw new Error("TTS synthesis aborted");
+        }
+        return {
+            ...segment,
+            stream,
+            format,
+        };
+    }
+    scheduleSegmentSynthesis(segment, abortSignal) {
+        return this.synthesizeSegment(segment, abortSignal).then((prepared) => {
+            if (abortSignal.aborted) {
+                this.destroySpeechStream(prepared.stream);
+                return { kind: "aborted" };
+            }
+            return { kind: "prepared", prepared };
+        }, (error) => {
+            if (abortSignal.aborted) {
+                return { kind: "aborted" };
+            }
+            return { kind: "error", error };
+        });
+    }
+    cleanupPrefetchedSegments(inflight) {
+        if (inflight.size === 0) {
+            return;
+        }
+        for (const pending of inflight.values()) {
+            void pending.then((result) => {
+                if (result.kind === "prepared") {
+                    this.destroySpeechStream(result.prepared.stream);
+                }
+                return;
+            });
+        }
+    }
+    destroySpeechStream(stream) {
+        if (typeof stream.destroy === "function" && !stream.destroyed) {
+            stream.destroy();
+        }
+    }
+    pruneRecentlyClosedAudioIds(now) {
+        for (const [audioId, expiresAt] of this.recentlyClosedAudioIds.entries()) {
+            if (expiresAt <= now) {
+                this.recentlyClosedAudioIds.delete(audioId);
+            }
+        }
+    }
+    rememberClosedAudioId(audioId) {
+        const now = Date.now();
+        this.pruneRecentlyClosedAudioIds(now);
+        this.recentlyClosedAudioIds.set(audioId, now + CLOSED_AUDIO_ID_TTL_MS);
+    }
+    async emitPreparedSegment(params) {
+        const { prepared, emitMessage, abortSignal, isVoiceMode } = params;
+        const { stream, format, text } = prepared;
+        const audioId = uuidv4();
+        let playbackResolve;
+        let playbackReject;
+        const playbackPromise = new Promise((resolve, reject) => {
+            playbackResolve = resolve;
+            playbackReject = reject;
+        });
+        const pendingPlayback = {
+            resolve: playbackResolve,
+            reject: playbackReject,
+            pendingChunks: 0,
+            streamEnded: false,
+        };
+        this.pendingPlaybacks.set(audioId, pendingPlayback);
+        let onAbort;
+        onAbort = () => {
+            this.logger.debug("Aborted while waiting for playback");
+            pendingPlayback.streamEnded = true;
+            pendingPlayback.pendingChunks = 0;
+            this.pendingPlaybacks.delete(audioId);
+            this.rememberClosedAudioId(audioId);
+            playbackResolve();
+            this.destroySpeechStream(stream);
+        };
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+        try {
+            const buffers = [];
+            for await (const chunk of stream) {
+                if (abortSignal.aborted) {
+                    this.logger.debug("Aborted during stream collection");
+                    break;
+                }
+                buffers.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            }
+            if (!abortSignal.aborted && buffers.length > 0) {
+                const fullBuffer = Buffer.concat(buffers);
+                const chunkId = `${audioId}:0`;
+                pendingPlayback.pendingChunks = 1;
+                emitMessage({
+                    type: "audio_output",
+                    payload: {
+                        id: chunkId,
+                        groupId: audioId,
+                        chunkIndex: 0,
+                        isLastChunk: true,
+                        audio: fullBuffer.toString("base64"),
+                        format,
+                        isVoiceMode,
+                    },
+                });
+            }
+            pendingPlayback.streamEnded = true;
+            if (pendingPlayback.pendingChunks === 0) {
+                this.pendingPlaybacks.delete(audioId);
+                this.rememberClosedAudioId(audioId);
+                playbackResolve();
+            }
+            await playbackPromise;
+        }
+        catch (error) {
+            if (abortSignal.aborted) {
+                this.logger.debug("Audio stream closed after abort");
+            }
+            else {
+                this.logger.error({ err: error }, "Error streaming audio");
+                this.pendingPlaybacks.delete(audioId);
+                throw error;
+            }
+        }
+        finally {
+            if (onAbort) {
+                abortSignal.removeEventListener("abort", onAbort);
+            }
+            this.destroySpeechStream(stream);
+        }
+        if (abortSignal.aborted) {
+            return;
+        }
+        this.logger.debug({ audioId, textLength: text.length }, "Audio playback confirmed");
+    }
+    /**
+     * Called when client confirms audio playback completed
+     * Resolves the corresponding promise
+     */
+    confirmAudioPlayed(chunkId) {
+        const [audioId] = chunkId.includes(":") ? chunkId.split(":") : [chunkId];
+        const pending = this.pendingPlaybacks.get(audioId);
+        if (!pending) {
+            const now = Date.now();
+            this.pruneRecentlyClosedAudioIds(now);
+            const expiresAt = this.recentlyClosedAudioIds.get(audioId);
+            if (expiresAt && expiresAt > now) {
+                this.logger.debug({ chunkId }, "Ignoring late confirmation for recently closed audio ID");
+                return;
+            }
+            this.logger.warn({ chunkId }, "Received confirmation for unknown audio ID");
+            return;
+        }
+        pending.pendingChunks = Math.max(0, pending.pendingChunks - 1);
+        if (pending.pendingChunks === 0 && pending.streamEnded) {
+            pending.resolve();
+            this.pendingPlaybacks.delete(audioId);
+            this.rememberClosedAudioId(audioId);
+        }
+    }
+    /**
+     * Cancel all pending playbacks (e.g., user interrupted audio)
+     */
+    cancelPendingPlaybacks(reason) {
+        if (this.pendingPlaybacks.size === 0) {
+            return;
+        }
+        this.logger.debug({ count: this.pendingPlaybacks.size, reason }, "Cancelling pending playbacks");
+        for (const [audioId, pending] of this.pendingPlaybacks.entries()) {
+            pending.resolve();
+            this.pendingPlaybacks.delete(audioId);
+            this.rememberClosedAudioId(audioId);
+            this.logger.debug({ audioId }, "Cleared pending playback");
+        }
+    }
+    /**
+     * Cleanup all pending playbacks
+     */
+    cleanup() {
+        // Reject all pending playbacks
+        for (const [audioId, pending] of this.pendingPlaybacks.entries()) {
+            pending.reject(new Error("Session closed"));
+            this.pendingPlaybacks.delete(audioId);
+            this.rememberClosedAudioId(audioId);
+        }
+    }
+}
+//# sourceMappingURL=tts-manager.js.map

package/dist/server/server/agent-attention-policy.d.ts

@@ -0,0 +1,29 @@
+import type { AgentAttentionReason } from "@camerontaylor/paseo-protocol/agent-attention-notification";
+export declare const PRESENCE_THRESHOLD_MS = 180000;
+export interface ClientPresenceState {
+    appVisible: boolean;
+    lastActivityAtMs: number | null;
+    focusedAgentId: string | null;
+    focusedTerminalId: string | null;
+}
+export type AttentionFocusTarget = {
+    kind: "agent";
+    id: string;
+} | {
+    kind: "terminal";
+    id: string;
+};
+export interface NotificationPlan {
+    inAppRecipientIndex: number | null;
+    shouldPush: boolean;
+}
+interface ComputeNotificationPlanInput {
+    allStates: ClientPresenceState[];
+    focusTarget: AttentionFocusTarget | null;
+    pushEligible: boolean;
+    nowMs: number;
+}
+export declare function computeNotificationPlan({ allStates, focusTarget, pushEligible, nowMs, }: ComputeNotificationPlanInput): NotificationPlan;
+export declare function isPushEligibleAttentionReason(reason: AgentAttentionReason): boolean;
+export {};
+//# sourceMappingURL=agent-attention-policy.d.ts.map

package/dist/server/server/agent-attention-policy.js

@@ -0,0 +1,36 @@
+export const PRESENCE_THRESHOLD_MS = 180000;
+function isFocusedOnTarget(state, target) {
+    if (target === null) {
+        return false;
+    }
+    if (target.kind === "agent") {
+        return state.focusedAgentId === target.id;
+    }
+    return state.focusedTerminalId === target.id;
+}
+export function computeNotificationPlan({ allStates, focusTarget, pushEligible, nowMs, }) {
+    let mostRecentPresentIndex = null;
+    let mostRecentPresentAtMs = Number.NEGATIVE_INFINITY;
+    for (const [clientIndex, state] of allStates.entries()) {
+        const clampedActivityAtMs = state.lastActivityAtMs === null ? null : Math.min(state.lastActivityAtMs, nowMs);
+        const isPresent = clampedActivityAtMs !== null && nowMs - clampedActivityAtMs <= PRESENCE_THRESHOLD_MS;
+        if (!isPresent) {
+            continue;
+        }
+        if (state.appVisible && isFocusedOnTarget(state, focusTarget)) {
+            return { inAppRecipientIndex: null, shouldPush: false };
+        }
+        if (clampedActivityAtMs > mostRecentPresentAtMs) {
+            mostRecentPresentIndex = clientIndex;
+            mostRecentPresentAtMs = clampedActivityAtMs;
+        }
+    }
+    if (mostRecentPresentIndex !== null) {
+        return { inAppRecipientIndex: mostRecentPresentIndex, shouldPush: false };
+    }
+    return { inAppRecipientIndex: null, shouldPush: pushEligible };
+}
+export function isPushEligibleAttentionReason(reason) {
+    return reason !== "error";
+}
+//# sourceMappingURL=agent-attention-policy.js.map

package/dist/server/server/agent-history-search.d.ts

@@ -0,0 +1,48 @@
+import type { AgentSearchMatch, AgentSnapshotPayload, ProjectPlacementPayload } from "@camerontaylor/paseo-protocol/messages";
+/**
+ * History search ranks what the daemon already knows about a session: the four
+ * names attached to it. Transcripts are deliberately out — they are unbounded,
+ * and a partial-transcript index would answer "not found" for sessions that do
+ * contain the phrase, which is worse than never claiming to search them.
+ *
+ * Field order is the tie-break order. Workspace and agent titles are what
+ * people actually recall; a project name matches every session in the repo, so
+ * it ranks last and only decides ties.
+ */
+export interface AgentHistorySearchCandidate {
+    agent: AgentSnapshotPayload;
+    project: ProjectPlacementPayload;
+}
+/**
+ * Every token has to match something, so adding a word always narrows. Tokens
+ * may land on different fields — "stripe main" finds the Stripe workspace on
+ * the main branch.
+ */
+export declare function scoreAgentHistoryCandidate(query: string, candidate: AgentHistorySearchCandidate): number | null;
+/**
+ * Where the query landed in each field, for the rows that will actually be
+ * rendered. The ranker already knows this; sending it means the client never
+ * has to re-derive a second opinion that could disagree with the ranking it is
+ * explaining.
+ */
+export declare function describeAgentHistoryMatches(query: string, candidate: AgentHistorySearchCandidate): AgentSearchMatch[];
+export interface RankedAgentHistoryCandidate<T extends AgentHistorySearchCandidate> {
+    candidate: T;
+    searchScore: number;
+}
+/**
+ * Ranks the whole candidate set rather than a page of it. The daemon holds
+ * every persisted agent in memory already, so search is complete by
+ * construction and the client never has to warn that it only looked at what it
+ * had loaded.
+ *
+ * A searched response is one page: the best `limit` matches, and a flag saying
+ * more matched. There is no search cursor. Offsets into a ranking that is
+ * recomputed per request duplicate and skip rows as history mutates underneath
+ * them, and a keyset cursor would buy the ability to walk past result 200 of a
+ * relevance order — which is browsing, not searching. Narrowing the query is
+ * the answer, and the global top K is exactly recoverable from each host's own
+ * top K, which is what lets several hosts merge without a federated pager.
+ */
+export declare function rankAgentHistoryCandidates<T extends AgentHistorySearchCandidate>(query: string, candidates: readonly T[], compareTies: (left: T, right: T) => number): RankedAgentHistoryCandidate<T>[];
+//# sourceMappingURL=agent-history-search.d.ts.map