@qduc/term2 0.15.0 → 0.17.0

package/dist/services/conversation/session-audit.js

@@ -0,0 +1,164 @@
+import { isTruncatedLogEvent } from '../logging/conversation-log-events.js';
+/**
+ * Derive an after-the-fact verdict about one persisted session from its event
+ * log alone, without resuming it.
+ *
+ * The in-flight bookkeeping here deliberately mirrors `replayEvents`: a call is
+ * registered by `tool_started` (and by `approval_required`, which can name a
+ * call the process died before dispatching), retired by `tool_result`, and
+ * cleared wholesale by `assistant_turn` and `undo`. That correspondence is the
+ * point — the audit reports what a resume of the same log would find, so the
+ * two cannot disagree about whether work was left unpaid.
+ *
+ * `session_cleared` is intentionally not treated as a reset, matching replay,
+ * which also ignores it here.
+ */
+export function auditSessionLog(envelopes) {
+    const inFlight = new Map();
+    const openSubagents = new Map();
+    const openShells = new Map();
+    const errors = [];
+    let sessionId;
+    let userTurns = 0;
+    let assistantTurns = 0;
+    let truncatedEvents = 0;
+    let trailingUserMessage = false;
+    let pendingApproval;
+    let started = 0;
+    let completed = 0;
+    let failed = 0;
+    let aborted = 0;
+    let unknown = 0;
+    for (const envelope of envelopes) {
+        const event = envelope.event;
+        if (isTruncatedLogEvent(event)) {
+            truncatedEvents++;
+            continue;
+        }
+        switch (event.type) {
+            case 'session_init':
+                sessionId = event.id;
+                break;
+            case 'user_message':
+                userTurns++;
+                trailingUserMessage = true;
+                break;
+            case 'assistant_turn':
+                assistantTurns++;
+                trailingUserMessage = false;
+                inFlight.clear();
+                pendingApproval = undefined;
+                break;
+            case 'undo':
+                trailingUserMessage = false;
+                inFlight.clear();
+                pendingApproval = undefined;
+                break;
+            case 'tool_started':
+                started++;
+                inFlight.set(event.toolCallId, { callId: event.toolCallId, toolName: event.toolName });
+                break;
+            case 'tool_result':
+                inFlight.delete(event.callId);
+                if (event.status === 'completed')
+                    completed++;
+                else if (event.status === 'failed')
+                    failed++;
+                else if (event.status === 'aborted')
+                    aborted++;
+                else
+                    unknown++;
+                break;
+            case 'approval_required': {
+                const callId = event.approval.callId;
+                const pending = { callId: callId ?? '', toolName: event.approval.toolName };
+                pendingApproval = pending;
+                if (callId && !inFlight.has(callId)) {
+                    inFlight.set(callId, { callId, toolName: event.approval.toolName });
+                }
+                break;
+            }
+            case 'approval_resolved':
+                pendingApproval = undefined;
+                break;
+            case 'subagent_started':
+                openSubagents.set(event.agentId, { agentId: event.agentId, role: event.role });
+                break;
+            case 'subagent_completed':
+                openSubagents.delete(event.result.agentId);
+                break;
+            case 'subagent_interrupted':
+            case 'subagent_transferred':
+                openSubagents.delete(event.agentId);
+                break;
+            case 'background_shell_started':
+                openShells.set(event.jobId, { jobId: event.jobId, command: event.command });
+                break;
+            case 'background_shell_completed':
+                openShells.delete(event.jobId);
+                break;
+            case 'error':
+                errors.push(event.kind ? { message: event.message, kind: event.kind } : { message: event.message });
+                break;
+            default:
+                break;
+        }
+    }
+    const unfinishedToolCalls = [...inFlight.values()];
+    const outcome = userTurns === 0
+        ? 'empty'
+        : pendingApproval
+            ? 'awaiting_approval'
+            : unfinishedToolCalls.length > 0
+                ? 'interrupted_mid_tool'
+                : trailingUserMessage
+                    ? 'interrupted_mid_turn'
+                    : 'settled';
+    return {
+        sessionId,
+        outcome,
+        userTurns,
+        assistantTurns,
+        toolCalls: { started, completed, failed, aborted, unknown },
+        unfinishedToolCalls,
+        unfinishedSubagents: [...openSubagents.values()],
+        unfinishedBackgroundShells: [...openShells.values()],
+        errors,
+        truncatedEvents,
+        firstEventAt: envelopes[0]?.ts,
+        lastEventAt: envelopes[envelopes.length - 1]?.ts,
+    };
+}
+const OUTCOME_SUMMARY = {
+    empty: 'No user turns were recorded.',
+    settled: 'Ended cleanly after a completed assistant turn.',
+    awaiting_approval: 'Stopped waiting for an approval that was never answered.',
+    interrupted_mid_tool: 'Ended with tool calls dispatched but never observed.',
+    interrupted_mid_turn: 'Ended after a user turn that never produced a reply.',
+};
+/** Render an audit as plain text for a report or a terminal. */
+export function formatSessionAudit(audit) {
+    const lines = [];
+    lines.push(`Session ${audit.sessionId ?? '(unknown)'}: ${audit.outcome}`);
+    lines.push(OUTCOME_SUMMARY[audit.outcome]);
+    lines.push(`Turns: ${audit.userTurns} user, ${audit.assistantTurns} assistant`);
+    const t = audit.toolCalls;
+    lines.push(`Tools: ${t.started} started, ${t.completed} completed, ${t.failed} failed, ${t.aborted} aborted, ${t.unknown} unknown`);
+    for (const call of audit.unfinishedToolCalls) {
+        lines.push(`  unfinished tool: ${call.toolName} (${call.callId || 'no call id'})`);
+    }
+    for (const agent of audit.unfinishedSubagents) {
+        lines.push(`  unfinished subagent: ${agent.role} (${agent.agentId})`);
+    }
+    for (const shell of audit.unfinishedBackgroundShells) {
+        lines.push(`  unfinished background shell: ${shell.command} (${shell.jobId})`);
+    }
+    for (const error of audit.errors) {
+        lines.push(`  error${error.kind ? ` [${error.kind}]` : ''}: ${error.message}`);
+    }
+    if (audit.truncatedEvents > 0) {
+        lines.push(`  ${audit.truncatedEvents} truncated event(s): this log is lossy`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=session-audit.js.map

package/dist/services/conversation/session-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-audit.js","sourceRoot":"","sources":["../../../source/services/conversation/session-audit.ts"],"names":[],"mappings":"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"}

package/dist/services/conversation/session-browser.d.ts

@@ -0,0 +1,49 @@
+export declare const MIN_SESSION_BROWSER_CHARS = 512;
+export declare const MAX_SESSION_BROWSER_CHARS = 12000;
+export type SessionBrowserContext = {
+    projectPath: string;
+    sshHost?: string;
+    currentSessionId?: string;
+};
+type BrowserError = {
+    error: {
+        code: 'not_found' | 'session_unavailable' | 'invalid_cursor' | 'stale_cursor' | 'output_budget_exceeded';
+        message: string;
+    };
+};
+export type SessionListInput = {
+    limit?: number;
+    maxChars?: number;
+};
+export type SessionSearchInput = {
+    query: string;
+    limit?: number;
+    maxChars?: number;
+};
+export type SessionReadInput = {
+    id: string;
+    cursor?: string;
+    limit?: number;
+    maxChars?: number;
+};
+export declare class SessionBrowser {
+    private readonly getContext;
+    constructor(getContext: () => SessionBrowserContext);
+    list(input: SessionListInput): number | BrowserError | {
+        sessions: Array<Record<string, unknown>>;
+        total: number;
+        omitted: number;
+        unavailable: number;
+    };
+    search(input: SessionSearchInput): number | BrowserError | {
+        results: Array<Record<string, unknown>>;
+        total: number;
+        omitted: number;
+        unavailable: number;
+        skippedMessageCount: number;
+    };
+    read(input: SessionReadInput): unknown;
+    private conversations;
+}
+export {};
+//# sourceMappingURL=session-browser.d.ts.map

package/dist/services/conversation/session-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-browser.d.ts","sourceRoot":"","sources":["../../../source/services/conversation/session-browser.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAQhD,MAAM,MAAM,qBAAqB,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAGzG,KAAK,YAAY,GAAG;IAClB,KAAK,EAAE;QACL,IAAI,EAAE,WAAW,GAAG,qBAAqB,GAAG,gBAAgB,GAAG,cAAc,GAAG,wBAAwB,CAAC;QACzG,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAGF,MAAM,MAAM,gBAAgB,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACrE,MAAM,MAAM,kBAAkB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACtF,MAAM,MAAM,gBAAgB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAvC,YAA6B,UAAU,EAAE,MAAM,qBAAqB,EAAI;IAExE,IAAI,CAAC,KAAK,EAAE,gBAAgB;kBAaR,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;;MAqBjD;IAED,MAAM,CAAC,KAAK,EAAE,kBAAkB;iBAsDb,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;;;MAahD;IAED,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAwGrC;IAED,OAAO,CAAC,aAAa;CAUtB"}

package/dist/services/conversation/session-browser.js

@@ -0,0 +1,411 @@
+import { browseConversationsForProject, loadConversationForProjectReadOnly, } from './conversation-persistence.js';
+import { boundedJsonFailure, fitSerializedEnvelope, fitsSerializedText, safeUtf16Slice, } from '../../utils/output/bounded-json.js';
+import { matchCenteredSnippet } from '../../utils/output/text-snippet.js';
+import { createHash } from 'node:crypto';
+export const MIN_SESSION_BROWSER_CHARS = 512;
+export const MAX_SESSION_BROWSER_CHARS = 12_000;
+const DEFAULT_INDEX_CHARS = 12_000;
+const DEFAULT_READ_CHARS = 12_000;
+const DEFAULT_LIMIT = 10;
+const DEFAULT_READ_LIMIT = 20;
+const SNIPPET_CHARS = 240;
+const SAFE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+export class SessionBrowser {
+    getContext;
+    constructor(getContext) {
+        this.getContext = getContext;
+    }
+    list(input) {
+        const budget = input.maxChars ?? DEFAULT_INDEX_CHARS;
+        const browsed = this.conversations();
+        let unavailable = browsed.unavailable;
+        const conversations = browsed.conversations;
+        const candidates = [];
+        for (const conversation of conversations) {
+            const projection = project(conversation);
+            if (!projection || !isBrowsableSession(conversation))
+                unavailable++;
+            else
+                candidates.push({ conversation, projection });
+        }
+        const selected = candidates.slice(0, clamp(input.limit, DEFAULT_LIMIT));
+        const result = {
+            sessions: [],
+            total: candidates.length,
+            omitted: 0,
+            unavailable,
+        };
+        for (const { conversation, projection } of selected) {
+            const firstUser = projection.records.find((record) => record.kind === 'user' && record.text);
+            const item = {
+                id: conversation.id,
+                createdAt: conversation.createdAt,
+                updatedAt: updatedAt(conversation),
+                ...(firstUser ? { firstUserMessage: prefixSnippet(firstUser.text) } : {}),
+                ...(conversation.model ? { model: conversation.model } : {}),
+                ...(conversation.provider ? { provider: conversation.provider } : {}),
+                messageCount: projection.records.length,
+            };
+            const candidate = fitted({ ...result, sessions: [...result.sessions, item], omitted: selected.length }, budget);
+            if (candidate)
+                result.sessions = candidate.sessions;
+            else
+                result.omitted++;
+        }
+        return fitted(result, budget) ?? outputBudgetError(budget);
+    }
+    search(input) {
+        const budget = input.maxChars ?? DEFAULT_INDEX_CHARS;
+        const terms = termsFor(input.query);
+        const browsed = this.conversations();
+        let unavailable = browsed.unavailable;
+        const conversations = browsed.conversations;
+        let skippedMessageCount = 0;
+        const currentSessionId = this.getContext().currentSessionId;
+        const matches = [];
+        for (const conversation of conversations) {
+            const projection = project(conversation);
+            if (!projection || !isBrowsableSession(conversation)) {
+                unavailable++;
+                continue;
+            }
+            skippedMessageCount += projection.skipped;
+            for (const record of projection.records) {
+                if (!record.text)
+                    continue;
+                const score = scoreText(record.text, terms);
+                if (score)
+                    matches.push({
+                        sessionId: conversation.id,
+                        kind: record.kind,
+                        messageIndex: record.index,
+                        snippet: matchCenteredSnippet(record.text, terms, SNIPPET_CHARS),
+                        updatedAt: updatedAt(conversation),
+                        score,
+                    });
+            }
+        }
+        matches.sort((a, b) => {
+            // Demote the live session so its self-referential matches (the query text
+            // appears in its own transcript while the agent is searching) cannot
+            // crowd out older sessions by the updatedAt tie-break. Ordering only:
+            // scoring and result contents are unchanged.
+            const aCurrent = a.sessionId === currentSessionId ? 1 : 0;
+            const bCurrent = b.sessionId === currentSessionId ? 1 : 0;
+            if (aCurrent !== bCurrent)
+                return aCurrent - bCurrent;
+            return (b.score - a.score ||
+                b.updatedAt.localeCompare(a.updatedAt) ||
+                a.sessionId.localeCompare(b.sessionId) ||
+                a.messageIndex - b.messageIndex);
+        });
+        const selected = matches.slice(0, clamp(input.limit, DEFAULT_LIMIT));
+        const result = {
+            results: [],
+            total: matches.length,
+            omitted: 0,
+            unavailable,
+            skippedMessageCount,
+        };
+        for (const match of selected) {
+            const { score: _, ...item } = match;
+            const candidate = fitted({ ...result, results: [...result.results, item], omitted: selected.length }, budget);
+            if (candidate)
+                result.results = candidate.results;
+            else
+                result.omitted++;
+        }
+        return fitted(result, budget) ?? outputBudgetError(budget);
+    }
+    read(input) {
+        const budget = input.maxChars ?? DEFAULT_READ_CHARS;
+        if (!SAFE_SESSION_ID.test(input.id))
+            return boundedError('not_found', 'Session was not found.', budget);
+        const context = this.getContext();
+        const loaded = loadConversationForProjectReadOnly(input.id, context.projectPath, context.sshHost);
+        if (loaded.status === 'not_found' || loaded.status === 'project_mismatch')
+            return boundedError('not_found', 'Session was not found.', budget);
+        if (loaded.status !== 'loaded' || loaded.conversation.id !== input.id || !loaded.conversation.createdAt)
+            return boundedError('session_unavailable', 'Session transcript is unavailable.', budget);
+        const conversation = loaded.conversation;
+        const projection = project(conversation);
+        if (!projection || !isBrowsableSession(conversation))
+            return boundedError('session_unavailable', 'Session transcript is unavailable.', budget);
+        const currentUpdatedAt = updatedAt(conversation);
+        const currentRevision = revision(conversation, projection);
+        const cursor = input.cursor
+            ? decodeCursor(input.cursor, input.id)
+            : { updatedAt: currentUpdatedAt, revision: currentRevision, nextIndex: 0, nextTextOffset: 0 };
+        if (!cursor)
+            return boundedError('invalid_cursor', 'The session cursor is invalid.', budget);
+        if (input.cursor && (cursor.updatedAt !== currentUpdatedAt || cursor.revision !== currentRevision))
+            return boundedError('stale_cursor', 'The session cursor is stale.', budget);
+        if (input.cursor && !validCursorPosition(cursor, projection.records))
+            return boundedError('invalid_cursor', 'The session cursor is invalid.', budget);
+        const session = {
+            id: conversation.id,
+            createdAt: conversation.createdAt,
+            updatedAt: currentUpdatedAt,
+            ...(conversation.model ? { model: conversation.model } : {}),
+            ...(conversation.provider ? { provider: conversation.provider } : {}),
+        };
+        const items = [];
+        let index = cursor.nextIndex;
+        let offset = cursor.nextTextOffset;
+        const total = projection.records.length;
+        const limit = clamp(input.limit, DEFAULT_READ_LIMIT);
+        while (index < projection.records.length && items.length < limit) {
+            const record = projection.records[index];
+            if (offset > record.text.length)
+                return boundedError('invalid_cursor', 'The session cursor is invalid.', budget);
+            const completeItem = pageItem(record, record.text.slice(offset), offset, true);
+            const afterIndex = index + 1;
+            const nextCursor = afterIndex < projection.records.length
+                ? encodeCursor(input.id, currentUpdatedAt, currentRevision, afterIndex, 0)
+                : undefined;
+            const candidate = fitted({
+                session,
+                items: [...items, completeItem],
+                ...(nextCursor ? { nextCursor } : {}),
+                total,
+                omitted: total,
+                skippedMessageCount: projection.skipped,
+            }, budget);
+            if (candidate) {
+                items.push(completeItem);
+                index = afterIndex;
+                offset = 0;
+                continue;
+            }
+            // Preserve source order: once fitting records already occupy this page,
+            // leave the next record for its own page rather than making an earlier
+            // page invalid by trying to append a partial later record.
+            if (items.length > 0)
+                break;
+            if (record.text.length === offset)
+                return outputBudgetError(budget);
+            const chunk = largestChunk(record, offset, (text) => {
+                const next = encodeCursor(input.id, currentUpdatedAt, currentRevision, index, offset + text.length);
+                return fitted({
+                    session,
+                    items: [...items, pageItem(record, text, offset, false)],
+                    nextCursor: next,
+                    total,
+                    omitted: total,
+                    skippedMessageCount: projection.skipped,
+                }, budget);
+            });
+            if (!chunk)
+                return outputBudgetError(budget);
+            items.push(pageItem(record, chunk, offset, false));
+            offset += chunk.length;
+            break;
+        }
+        const nextCursor = index < total ? encodeCursor(input.id, currentUpdatedAt, currentRevision, index, offset) : undefined;
+        // Records begun in this page are total - omitted. A mid-record chunk (the
+        // cursor offset is nonzero) began its own record, so it is not counted as
+        // omitted; every later record is.
+        const omitted = total - index - (offset > 0 ? 1 : 0);
+        return (fitted({
+            session,
+            items,
+            ...(nextCursor ? { nextCursor } : {}),
+            total,
+            omitted,
+            skippedMessageCount: projection.skipped,
+        }, budget) ?? outputBudgetError(budget));
+    }
+    conversations() {
+        const context = this.getContext();
+        const result = browseConversationsForProject(context.projectPath, context.sshHost);
+        return {
+            unavailable: result.unavailable,
+            conversations: result.conversations.sort((a, b) => updatedAt(b).localeCompare(updatedAt(a)) || a.id.localeCompare(b.id)),
+        };
+    }
+}
+function project(conversation) {
+    const records = [];
+    let skipped = 0;
+    for (let index = 0; index < conversation.messages.length; index++) {
+        const message = conversation.messages[index];
+        switch (message.sender) {
+            case 'user':
+                if (typeof message.text !== 'string')
+                    return null;
+                records.push({ index, kind: 'user', text: message.text });
+                break;
+            case 'bot':
+                if (typeof message.text !== 'string')
+                    return null;
+                records.push({ index, kind: 'assistant', text: message.text });
+                break;
+            case 'reasoning':
+                if (typeof message.text !== 'string')
+                    return null;
+                records.push({ index, kind: 'reasoning', text: message.text });
+                break;
+            case 'system':
+                if (typeof message.text !== 'string')
+                    return null;
+                records.push({ index, kind: 'system', text: message.text });
+                break;
+            case 'command':
+                if (typeof message.command !== 'string' || (message.output !== undefined && typeof message.output !== 'string'))
+                    return null;
+                records.push({
+                    index,
+                    kind: 'tool',
+                    text: message.output ? `${message.command}\n${message.output}` : message.command,
+                });
+                break;
+            case 'subagent':
+                if (typeof message.task !== 'string' ||
+                    (message.finalText !== undefined && typeof message.finalText !== 'string'))
+                    return null;
+                records.push({
+                    index,
+                    kind: 'subagent',
+                    text: message.finalText !== undefined ? `${message.task}\n${message.finalText}` : message.task,
+                });
+                break;
+            default:
+                skipped++;
+        }
+    }
+    return { records, skipped };
+}
+function updatedAt(conversation) {
+    return conversation.updatedAt ?? conversation.createdAt;
+}
+function clamp(value, fallback) {
+    return Math.max(1, Math.min(50, value ?? fallback));
+}
+function termsFor(query) {
+    return query
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((term) => term.toLowerCase());
+}
+function scoreText(text, terms) {
+    const lower = text.toLowerCase();
+    return terms.reduce((total, term) => total + (lower === term ? 100 : lower.startsWith(term) ? 20 : lower.includes(term) ? 2 : 0), 0);
+}
+function prefixSnippet(text) {
+    if (text.length <= SNIPPET_CHARS)
+        return text;
+    return `${safeUtf16Slice(text, 0, SNIPPET_CHARS - 1)}…`;
+}
+function pageItem(record, text, textOffset, complete) {
+    return { index: record.index, kind: record.kind, text, textOffset, totalTextChars: record.text.length, complete };
+}
+function fitted(value, maxChars) {
+    const result = fitSerializedEnvelope((charsUsed) => ({ ...value, charsUsed }), { maxChars });
+    return result?.value ?? null;
+}
+function outputBudgetError(maxChars) {
+    return boundedError('output_budget_exceeded', 'The requested result cannot fit in the output budget.', maxChars);
+}
+function boundedError(code, message, maxChars) {
+    const value = { error: { code, message } };
+    if (fitsSerializedText(JSON.stringify(value), { maxChars }))
+        return value;
+    const fallback = boundedJsonFailure({ maxChars });
+    return fallback ? JSON.parse(fallback) : 0;
+}
+function largestChunk(record, offset, fits) {
+    let low = 1;
+    let high = record.text.length - offset;
+    let best = '';
+    while (low <= high) {
+        const middle = Math.floor((low + high) / 2);
+        const text = safeUtf16Slice(record.text, offset, offset + middle);
+        if (text && fits(text)) {
+            best = text;
+            low = middle + 1;
+        }
+        else
+            high = middle - 1;
+    }
+    return best;
+}
+function encodeCursor(sessionId, updatedAt, revision, nextIndex, nextTextOffset) {
+    return Buffer.from(JSON.stringify({ v: 1, sessionId, updatedAt, revision, nextIndex, nextTextOffset })).toString('base64url');
+}
+function decodeCursor(cursor, id) {
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(cursor))
+            return null;
+        const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+        if (Buffer.from(decoded, 'utf8').toString('base64url') !== cursor)
+            return null;
+        const value = JSON.parse(decoded);
+        const nextIndex = value.nextIndex;
+        const nextTextOffset = value.nextTextOffset;
+        if (decoded !== JSON.stringify(value) ||
+            Object.keys(value).join(',') !== 'v,sessionId,updatedAt,revision,nextIndex,nextTextOffset' ||
+            value.v !== 1 ||
+            value.sessionId !== id ||
+            !isUtcTimestamp(value.updatedAt) ||
+            typeof value.revision !== 'string' ||
+            !/^[A-Za-z0-9_-]{16}$/.test(value.revision) ||
+            typeof nextIndex !== 'number' ||
+            typeof nextTextOffset !== 'number' ||
+            !Number.isSafeInteger(nextIndex) ||
+            !Number.isSafeInteger(nextTextOffset) ||
+            nextIndex < 0 ||
+            nextTextOffset < 0)
+            return null;
+        return { updatedAt: value.updatedAt, revision: value.revision, nextIndex, nextTextOffset };
+    }
+    catch {
+        return null;
+    }
+}
+function isBrowsableSession(conversation) {
+    return (SAFE_SESSION_ID.test(conversation.id) &&
+        isUtcTimestamp(conversation.createdAt) &&
+        isUtcTimestamp(updatedAt(conversation)) &&
+        (conversation.model === undefined || typeof conversation.model === 'string') &&
+        (conversation.provider === undefined || typeof conversation.provider === 'string'));
+}
+function validCursorPosition(cursor, records) {
+    if (cursor.nextIndex > records.length)
+        return false;
+    if (cursor.nextIndex === records.length)
+        return false;
+    const text = records[cursor.nextIndex].text;
+    if (cursor.nextTextOffset === 0)
+        return true;
+    if (cursor.nextTextOffset >= text.length)
+        return false;
+    return !(isHighSurrogate(text.charCodeAt(cursor.nextTextOffset - 1)) &&
+        isLowSurrogate(text.charCodeAt(cursor.nextTextOffset)));
+}
+function revision(conversation, projection) {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        id: conversation.id,
+        createdAt: conversation.createdAt,
+        model: conversation.model,
+        provider: conversation.provider,
+        records: projection.records,
+        skipped: projection.skipped,
+    }))
+        .digest()
+        .subarray(0, 12)
+        .toString('base64url');
+}
+function isUtcTimestamp(value) {
+    return (typeof value === 'string' &&
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value) &&
+        !Number.isNaN(Date.parse(value)));
+}
+function isHighSurrogate(value) {
+    return value >= 0xd800 && value <= 0xdbff;
+}
+function isLowSurrogate(value) {
+    return value >= 0xdc00 && value <= 0xdfff;
+}
+//# sourceMappingURL=session-browser.js.map