@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/agent/agent-stream-coalescer.js

@@ -0,0 +1,187 @@
+export const AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS = 60;
+function isCoalescableTimelineEvent(event) {
+    return (event.type === "timeline" &&
+        (event.item.type === "assistant_message" ||
+            event.item.type === "reasoning" ||
+            event.item.type === "tool_call"));
+}
+function isTextTimelineItem(item) {
+    return item.type === "assistant_message" || item.type === "reasoning";
+}
+function isTerminalToolCall(item) {
+    return (item.type === "tool_call" &&
+        (item.status === "completed" || item.status === "failed" || item.status === "canceled"));
+}
+function isSameTextStream(previous, next) {
+    if (previous.item.type !== next.item.type) {
+        return false;
+    }
+    if (previous.item.type === "assistant_message" && next.item.type === "assistant_message") {
+        return previous.item.messageId === next.item.messageId;
+    }
+    return true;
+}
+export class AgentStreamCoalescer {
+    constructor(options) {
+        this.buffers = new Map();
+        this.windowMs = options.windowMs ?? AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS;
+        this.timers = options.timers;
+        this.now = options.now ?? Date.now;
+        this.onFlush = options.onFlush;
+    }
+    handle(agentId, event) {
+        if (!isCoalescableTimelineEvent(event)) {
+            return false;
+        }
+        if (isTextTimelineItem(event.item) && event.item.text === "") {
+            return true;
+        }
+        const buffer = this.getOrCreateBuffer(agentId);
+        this.appendToBuffer(buffer, event);
+        if (isTerminalToolCall(event.item)) {
+            this.flushBuffer(agentId);
+            return true;
+        }
+        // Leading edge: the first event after an idle window flushes synchronously so
+        // the first token of a turn isn't delayed a full window. Sustained bursts fall
+        // through to the trailing timer, which keeps the message rate at one per
+        // window. Same shape as TerminalOutputCoalescer.
+        if (!buffer.timer) {
+            const elapsed = buffer.lastFlushAt === null ? Number.POSITIVE_INFINITY : this.now() - buffer.lastFlushAt;
+            if (elapsed >= this.windowMs) {
+                this.flushBuffer(agentId);
+                return true;
+            }
+            this.scheduleFlush(buffer);
+        }
+        return true;
+    }
+    flushFor(agentId) {
+        this.flushBuffer(agentId);
+    }
+    flushAll() {
+        for (const agentId of Array.from(this.buffers.keys())) {
+            this.flushBuffer(agentId);
+        }
+    }
+    flushAndDiscard(agentId) {
+        this.flushBuffer(agentId);
+        const buffer = this.buffers.get(agentId);
+        if (buffer) {
+            this.clearTimer(buffer);
+            this.buffers.delete(agentId);
+        }
+    }
+    getOrCreateBuffer(agentId) {
+        const existing = this.buffers.get(agentId);
+        if (existing) {
+            return existing;
+        }
+        const buffer = {
+            agentId,
+            entries: [],
+            toolCallEntryIndexes: new Map(),
+            timer: null,
+            flushing: false,
+            lastFlushAt: null,
+        };
+        this.buffers.set(agentId, buffer);
+        return buffer;
+    }
+    appendToBuffer(buffer, event) {
+        if (isTextTimelineItem(event.item)) {
+            buffer.entries.push({
+                kind: "text",
+                item: event.item,
+                text: event.item.text,
+                provider: event.provider,
+                ...(event.turnId !== undefined ? { turnId: event.turnId } : {}),
+            });
+            return;
+        }
+        const existingIndex = buffer.toolCallEntryIndexes.get(event.item.callId);
+        const entry = {
+            kind: "tool_call",
+            item: event.item,
+            provider: event.provider,
+            ...(event.turnId !== undefined ? { turnId: event.turnId } : {}),
+        };
+        if (existingIndex !== undefined) {
+            buffer.entries[existingIndex] = entry;
+            return;
+        }
+        buffer.toolCallEntryIndexes.set(event.item.callId, buffer.entries.length);
+        buffer.entries.push(entry);
+    }
+    scheduleFlush(buffer) {
+        const timer = this.timers.setTimeout(() => {
+            this.flushBuffer(buffer.agentId, buffer);
+        }, this.windowMs);
+        timer.unref?.();
+        buffer.timer = timer;
+    }
+    clearTimer(buffer) {
+        if (!buffer.timer) {
+            return;
+        }
+        this.timers.clearTimeout(buffer.timer);
+        buffer.timer = null;
+    }
+    flushBuffer(agentId, expectedBuffer) {
+        const buffer = this.buffers.get(agentId);
+        if (!buffer) {
+            return;
+        }
+        if (expectedBuffer && buffer !== expectedBuffer) {
+            return;
+        }
+        if (buffer.flushing) {
+            return;
+        }
+        this.clearTimer(buffer);
+        if (buffer.entries.length === 0) {
+            return;
+        }
+        const entries = buffer.entries;
+        buffer.entries = [];
+        buffer.toolCallEntryIndexes.clear();
+        buffer.flushing = true;
+        buffer.lastFlushAt = this.now();
+        try {
+            for (const entry of this.collapseEntries(entries)) {
+                this.onFlush({
+                    agentId,
+                    item: entry.kind === "text"
+                        ? {
+                            ...entry.item,
+                            text: entry.text,
+                        }
+                        : entry.item,
+                    provider: entry.provider,
+                    ...(entry.turnId !== undefined ? { turnId: entry.turnId } : {}),
+                });
+            }
+        }
+        finally {
+            buffer.flushing = false;
+        }
+    }
+    collapseEntries(entries) {
+        const collapsed = [];
+        for (const entry of entries) {
+            const previous = collapsed.at(-1);
+            if (previous &&
+                previous.kind === "text" &&
+                entry.kind === "text" &&
+                isSameTextStream(previous, entry) &&
+                previous.provider === entry.provider &&
+                previous.turnId === entry.turnId) {
+                previous.text += entry.text;
+                continue;
+            }
+            collapsed.push({ ...entry });
+        }
+        return collapsed;
+    }
+}
+//# sourceMappingURL=agent-stream-coalescer.js.map

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

@@ -0,0 +1,6 @@
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
+import type { JsonValue } from "@camerontaylor/paseo-protocol/agent-types";
+export declare const PLUGIN_TIMELINE_DATA_MAX_BYTES: number;
+export declare function assertPluginTimelineDataSize(data: JsonValue): void;
+export declare function limitAgentTimelineItemContent(item: AgentTimelineItem): AgentTimelineItem;
+//# sourceMappingURL=agent-timeline-content.d.ts.map

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

@@ -0,0 +1,62 @@
+const TOOL_CALL_CONTENT_MAX_LENGTH = 64 * 1024;
+export const PLUGIN_TIMELINE_DATA_MAX_BYTES = 64 * 1024;
+export function assertPluginTimelineDataSize(data) {
+    const serializedBytes = Buffer.byteLength(JSON.stringify(data), "utf8");
+    if (serializedBytes > PLUGIN_TIMELINE_DATA_MAX_BYTES) {
+        throw new Error(`Plugin timeline item data exceeds ${PLUGIN_TIMELINE_DATA_MAX_BYTES} bytes`);
+    }
+}
+function limitFailedShellError(item) {
+    if (item.type !== "tool_call" ||
+        item.detail.type !== "shell" ||
+        item.status !== "failed" ||
+        typeof item.error !== "object" ||
+        item.error === null ||
+        !("content" in item.error) ||
+        typeof item.error.content !== "string" ||
+        item.error.content.length <= TOOL_CALL_CONTENT_MAX_LENGTH) {
+        return item;
+    }
+    return {
+        ...item,
+        error: {
+            ...item.error,
+            content: item.error.content.slice(0, TOOL_CALL_CONTENT_MAX_LENGTH),
+        },
+    };
+}
+function limitPlainText(item) {
+    if (item.type !== "tool_call" ||
+        item.detail.type !== "plain_text" ||
+        typeof item.detail.text !== "string" ||
+        item.detail.text.length <= TOOL_CALL_CONTENT_MAX_LENGTH) {
+        return item;
+    }
+    return {
+        ...item,
+        detail: {
+            ...item.detail,
+            text: item.detail.text.slice(0, TOOL_CALL_CONTENT_MAX_LENGTH),
+        },
+    };
+}
+export function limitAgentTimelineItemContent(item) {
+    item = limitFailedShellError(item);
+    item = limitPlainText(item);
+    if (item.type !== "tool_call" ||
+        item.detail.type !== "shell" ||
+        typeof item.detail.output !== "string") {
+        return item;
+    }
+    if (item.detail.output.length <= TOOL_CALL_CONTENT_MAX_LENGTH) {
+        return item;
+    }
+    return {
+        ...item,
+        detail: {
+            ...item.detail,
+            output: item.detail.output.slice(0, TOOL_CALL_CONTENT_MAX_LENGTH),
+        },
+    };
+}
+//# sourceMappingURL=agent-timeline-content.js.map

package/dist/server/server/agent/agent-timeline-store-types.d.ts

@@ -0,0 +1,54 @@
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
+export interface AgentTimelineRow {
+    seq: number;
+    timestamp: string;
+    item: AgentTimelineItem;
+    readonly turnId?: string;
+    readonly providerMessageId?: string;
+}
+export interface AgentTimelineCursor {
+    epoch: string;
+    seq: number;
+}
+export type AgentTimelineFetchDirection = "tail" | "before" | "after";
+export interface AgentTimelineFetchOptions {
+    direction?: AgentTimelineFetchDirection;
+    cursor?: AgentTimelineCursor;
+    /**
+     * Number of canonical rows to return.
+     * - undefined: store default
+     * - 0: all rows in the selected window
+     */
+    limit?: number;
+}
+export interface AgentTimelineWindow {
+    minSeq: number;
+    maxSeq: number;
+    nextSeq: number;
+}
+export interface AgentTimelineFetchResult {
+    epoch: string;
+    direction: AgentTimelineFetchDirection;
+    reset: boolean;
+    staleCursor: boolean;
+    gap: boolean;
+    window: AgentTimelineWindow;
+    hasOlder: boolean;
+    hasNewer: boolean;
+    rows: AgentTimelineRow[];
+}
+export interface AgentTimelineStore {
+    appendCommitted(agentId: string, item: AgentTimelineItem, options?: {
+        timestamp?: string;
+        turnId?: string;
+    }): Promise<AgentTimelineRow>;
+    fetchCommitted(agentId: string, options?: AgentTimelineFetchOptions): Promise<AgentTimelineFetchResult>;
+    getLatestCommittedSeq(agentId: string): Promise<number>;
+    getCommittedRows(agentId: string): Promise<AgentTimelineRow[]>;
+    getLastItem(agentId: string): Promise<AgentTimelineItem | null>;
+    getLastAssistantMessage(agentId: string): Promise<string | null>;
+    deleteAgent(agentId: string): Promise<void>;
+    bulkInsert(agentId: string, rows: readonly AgentTimelineRow[]): Promise<void>;
+    updateCommittedRow(agentId: string, row: AgentTimelineRow): Promise<void>;
+}
+//# sourceMappingURL=agent-timeline-store-types.d.ts.map

package/dist/server/server/agent/agent-timeline-store-types.js

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

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

@@ -0,0 +1,31 @@
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
+import type { AgentTimelineFetchOptions, AgentTimelineFetchResult, AgentTimelineRow } from "./agent-timeline-store-types.js";
+export interface SeedAgentTimelineOptions {
+    items?: readonly AgentTimelineItem[];
+    rows?: readonly AgentTimelineRow[];
+    epoch?: string;
+    nextSeq?: number;
+    timestamp?: string;
+}
+export declare class InMemoryAgentTimelineStore {
+    private readonly states;
+    has(agentId: string): boolean;
+    initialize(agentId: string, options?: SeedAgentTimelineOptions): void;
+    delete(agentId: string): void;
+    getItems(agentId: string): AgentTimelineItem[];
+    getRows(agentId: string): AgentTimelineRow[];
+    getSubmittedUserMessage(agentId: string, clientMessageId: string): AgentTimelineRow | null;
+    enrichSubmittedUserMessage(agentId: string, clientMessageId: string, providerMessageId: string): AgentTimelineRow | null;
+    getEpoch(agentId: string): string;
+    fetch(agentId: string, options?: AgentTimelineFetchOptions): AgentTimelineFetchResult;
+    append(agentId: string, item: AgentTimelineItem, options?: {
+        timestamp?: string;
+        providerMessageId?: string;
+        turnId?: string;
+    }): AgentTimelineRow;
+    getLastItem(agentId: string): AgentTimelineItem | null;
+    getLastAssistantMessage(agentId: string): string | null;
+    private requireState;
+    private buildRowsFromItems;
+}
+//# sourceMappingURL=agent-timeline-store.d.ts.map

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

@@ -0,0 +1,249 @@
+import { randomUUID } from "node:crypto";
+const DEFAULT_TIMELINE_FETCH_LIMIT = 200;
+function cloneRow(row) {
+    return { ...row };
+}
+function fetchTail(ctx) {
+    const { state, direction, limit, selectAll, minSeq, window } = ctx;
+    const selected = selectAll || limit >= state.rows.length
+        ? state.rows
+        : state.rows.slice(state.rows.length - limit);
+    return {
+        epoch: state.epoch,
+        direction,
+        reset: false,
+        staleCursor: false,
+        gap: false,
+        window,
+        hasOlder: selected.length > 0 && selected[0].seq > minSeq,
+        hasNewer: false,
+        rows: selected.map(cloneRow),
+    };
+}
+function fetchAfter(ctx) {
+    const { state, direction, limit, selectAll, cursor, minSeq, maxSeq, window } = ctx;
+    const baseSeq = cursor?.seq ?? 0;
+    const startIdx = state.rows.findIndex((row) => row.seq > baseSeq);
+    if (startIdx < 0) {
+        return {
+            epoch: state.epoch,
+            direction,
+            reset: false,
+            staleCursor: false,
+            gap: false,
+            window,
+            hasOlder: baseSeq >= minSeq,
+            hasNewer: false,
+            rows: [],
+        };
+    }
+    const selected = selectAll
+        ? state.rows.slice(startIdx)
+        : state.rows.slice(startIdx, startIdx + limit);
+    const lastSelected = selected[selected.length - 1];
+    return {
+        epoch: state.epoch,
+        direction,
+        reset: false,
+        staleCursor: false,
+        gap: false,
+        window,
+        hasOlder: selected[0].seq > minSeq,
+        hasNewer: lastSelected !== null && lastSelected !== undefined && lastSelected.seq < maxSeq,
+        rows: selected.map(cloneRow),
+    };
+}
+function fetchBefore(ctx) {
+    const { state, direction, limit, selectAll, cursor, minSeq, window } = ctx;
+    const beforeSeq = cursor?.seq ?? state.nextSeq;
+    const endExclusive = state.rows.findIndex((row) => row.seq >= beforeSeq);
+    const boundedRows = endExclusive < 0 ? state.rows : state.rows.slice(0, endExclusive);
+    const selected = selectAll || limit >= boundedRows.length
+        ? boundedRows
+        : boundedRows.slice(boundedRows.length - limit);
+    return {
+        epoch: state.epoch,
+        direction,
+        reset: false,
+        staleCursor: false,
+        gap: false,
+        window,
+        hasOlder: selected.length > 0 && selected[0].seq > minSeq,
+        hasNewer: endExclusive >= 0,
+        rows: selected.map(cloneRow),
+    };
+}
+function fetchReset(ctx, flags) {
+    const { state, direction, limit, selectAll, minSeq, window } = ctx;
+    const rows = selectAll || limit >= state.rows.length
+        ? state.rows.map(cloneRow)
+        : state.rows.slice(state.rows.length - limit).map(cloneRow);
+    return {
+        epoch: state.epoch,
+        direction,
+        reset: true,
+        staleCursor: flags.staleCursor,
+        gap: flags.gap,
+        window,
+        hasOlder: rows.length > 0 && rows[0].seq > minSeq,
+        hasNewer: false,
+        rows,
+    };
+}
+export class InMemoryAgentTimelineStore {
+    constructor() {
+        this.states = new Map();
+    }
+    has(agentId) {
+        return this.states.has(agentId);
+    }
+    initialize(agentId, options) {
+        const timestamp = options?.timestamp ?? new Date().toISOString();
+        const rows = options?.rows?.length
+            ? options.rows.map(cloneRow)
+            : this.buildRowsFromItems(options?.items ?? [], options?.nextSeq ?? 1, timestamp);
+        const nextSeq = options?.nextSeq ?? (rows.length ? rows[rows.length - 1].seq + 1 : 1);
+        this.states.set(agentId, {
+            epoch: options?.epoch ?? randomUUID(),
+            rows,
+            nextSeq,
+        });
+    }
+    delete(agentId) {
+        this.states.delete(agentId);
+    }
+    getItems(agentId) {
+        return this.requireState(agentId).rows.map((row) => row.item);
+    }
+    getRows(agentId) {
+        return this.requireState(agentId).rows.map(cloneRow);
+    }
+    getSubmittedUserMessage(agentId, clientMessageId) {
+        const row = this.requireState(agentId).rows.find((candidate) => candidate.item.type === "user_message" &&
+            candidate.item.clientMessageId === clientMessageId);
+        return row ? cloneRow(row) : null;
+    }
+    enrichSubmittedUserMessage(agentId, clientMessageId, providerMessageId) {
+        const state = this.requireState(agentId);
+        const index = state.rows.findIndex((candidate) => candidate.item.type === "user_message" &&
+            candidate.item.clientMessageId === clientMessageId);
+        const row = state.rows[index];
+        if (!row || row.item.type !== "user_message") {
+            return null;
+        }
+        const enriched = { ...row, providerMessageId };
+        state.rows[index] = enriched;
+        return cloneRow(enriched);
+    }
+    getEpoch(agentId) {
+        return this.requireState(agentId).epoch;
+    }
+    fetch(agentId, options) {
+        const state = this.requireState(agentId);
+        const direction = options?.direction ?? "tail";
+        const requestedLimit = options?.limit;
+        const limit = requestedLimit === undefined
+            ? DEFAULT_TIMELINE_FETCH_LIMIT
+            : Math.max(0, Math.floor(requestedLimit));
+        const cursor = options?.cursor;
+        const minSeq = state.rows.length ? state.rows[0].seq : 0;
+        const maxSeq = state.rows.length ? state.rows[state.rows.length - 1].seq : 0;
+        const selectAll = limit === 0;
+        const window = {
+            minSeq,
+            maxSeq,
+            nextSeq: state.nextSeq,
+        };
+        const ctx = {
+            state,
+            direction,
+            limit,
+            selectAll,
+            cursor,
+            minSeq,
+            maxSeq,
+            window,
+        };
+        if (cursor && typeof cursor.epoch === "string" && cursor.epoch !== state.epoch) {
+            return fetchReset(ctx, { staleCursor: true, gap: false });
+        }
+        if (direction === "after" && cursor && state.rows.length > 0 && cursor.seq < minSeq - 1) {
+            return fetchReset(ctx, { staleCursor: false, gap: true });
+        }
+        if (state.rows.length === 0) {
+            return {
+                epoch: state.epoch,
+                direction,
+                reset: false,
+                staleCursor: false,
+                gap: false,
+                window,
+                hasOlder: false,
+                hasNewer: false,
+                rows: [],
+            };
+        }
+        if (direction === "tail") {
+            return fetchTail(ctx);
+        }
+        if (direction === "after") {
+            return fetchAfter(ctx);
+        }
+        return fetchBefore(ctx);
+    }
+    append(agentId, item, options) {
+        const state = this.requireState(agentId);
+        const row = {
+            seq: state.nextSeq,
+            timestamp: options?.timestamp ?? new Date().toISOString(),
+            item,
+            ...(options?.turnId ? { turnId: options.turnId } : {}),
+            ...(options?.providerMessageId ? { providerMessageId: options.providerMessageId } : {}),
+        };
+        state.nextSeq += 1;
+        state.rows.push(row);
+        return cloneRow(row);
+    }
+    getLastItem(agentId) {
+        const state = this.requireState(agentId);
+        return state.rows[state.rows.length - 1]?.item ?? null;
+    }
+    getLastAssistantMessage(agentId) {
+        const rows = this.requireState(agentId).rows;
+        const chunks = [];
+        for (let i = rows.length - 1; i >= 0; i -= 1) {
+            const item = rows[i].item;
+            if (item.type !== "assistant_message") {
+                if (chunks.length > 0) {
+                    break;
+                }
+                continue;
+            }
+            chunks.push(item.text);
+        }
+        if (chunks.length === 0) {
+            return null;
+        }
+        return chunks.toReversed().join("");
+    }
+    requireState(agentId) {
+        const state = this.states.get(agentId);
+        if (!state) {
+            throw new Error(`Unknown agent '${agentId}'`);
+        }
+        return state;
+    }
+    buildRowsFromItems(items, startSeq, timestamp) {
+        let nextSeq = startSeq;
+        return items.map((item) => {
+            const row = {
+                seq: nextSeq,
+                timestamp,
+                item,
+            };
+            nextSeq += 1;
+            return row;
+        });
+    }
+}
+//# sourceMappingURL=agent-timeline-store.js.map

package/dist/server/server/agent/audio-utils.d.ts

@@ -0,0 +1,3 @@
+export declare function inferAudioExtension(format: string | undefined): string;
+export declare function sanitizeForFilename(segment: string | undefined, fallback: string): string;
+//# sourceMappingURL=audio-utils.d.ts.map

package/dist/server/server/agent/audio-utils.js

@@ -0,0 +1,19 @@
+const AUDIO_EXTENSIONS = [
+    { match: (format) => format.includes("webm"), ext: "webm" },
+    { match: (format) => format.includes("ogg"), ext: "ogg" },
+    { match: (format) => format.includes("mp3"), ext: "mp3" },
+    { match: (format) => format.includes("wav"), ext: "wav" },
+    { match: (format) => format.includes("m4a") || format.includes("aac"), ext: "m4a" },
+    { match: (format) => format.includes("mp4"), ext: "mp4" },
+    { match: (format) => format.includes("flac"), ext: "flac" },
+];
+export function inferAudioExtension(format) {
+    const normalized = (format || "webm").toLowerCase();
+    const candidate = AUDIO_EXTENSIONS.find((entry) => entry.match(normalized));
+    return candidate?.ext ?? "webm";
+}
+export function sanitizeForFilename(segment, fallback) {
+    const value = segment && segment.length > 0 ? segment : fallback;
+    return value.replace(/[^a-zA-Z0-9-_]/g, "_").slice(0, 64);
+}
+//# sourceMappingURL=audio-utils.js.map