@qduc/term2 0.20.0 → 0.22.0

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

@@ -1,3 +1,5 @@
+import { type RestoredState } from './conversation-persistence.js';
+import { SessionIndexService } from './session-index/session-index-service.js';
 export declare const MIN_SESSION_BROWSER_CHARS = 512;
 export declare const MAX_SESSION_BROWSER_CHARS = 12000;
 export type SessionBrowserContext = {
@@ -5,11 +7,19 @@ export type SessionBrowserContext = {
     sshHost?: string;
     currentSessionId?: string;
 };
-type BrowserError = {
-    error: {
-        code: 'not_found' | 'session_unavailable' | 'invalid_cursor' | 'stale_cursor' | 'output_budget_exceeded';
-        message: string;
-    };
+export type Kind = 'user' | 'assistant' | 'reasoning' | 'system' | 'tool' | 'subagent';
+export type ProjectedMessage = {
+    index: number;
+    kind: Kind;
+    text: string;
+};
+type ReadSnapshotSession = {
+    id: string;
+    createdAt: string;
+    updatedAt?: string;
+    model?: string;
+    provider?: string;
+    rolloverFrom?: string;
 };
 export type SessionListInput = {
     limit?: number;
@@ -17,36 +27,38 @@ export type SessionListInput = {
 };
 export type SessionSearchInput = {
     query: string;
+    kinds?: Kind[];
     limit?: number;
     maxChars?: number;
 };
 export type SessionReadInput = {
     id: string;
     cursor?: string;
+    from?: 'end';
     limit?: number;
     maxChars?: number;
 };
+export interface SessionBrowserOptions {
+    backend?: 'canonical' | 'indexed';
+    indexService?: SessionIndexService;
+}
 export declare class SessionBrowser {
     #private;
     private readonly getContext;
-    constructor(getContext: () => SessionBrowserContext);
-    list(input: SessionListInput): number | BrowserError | {
-        sessions: Array<Record<string, unknown>>;
-        scope: string;
-        total: number;
-        omitted: number;
-        unavailable: number;
-    };
-    search(input: SessionSearchInput): number | BrowserError | {
-        results: Array<Record<string, unknown>>;
-        scope: string;
-        total: number;
-        omitted: number;
-        unavailable: number;
-        skippedMessageCount: number;
-    };
-    read(input: SessionReadInput): unknown;
+    constructor(getContext: () => SessionBrowserContext, options?: SessionBrowserOptions);
+    close(): Promise<void>;
+    list(input: SessionListInput): unknown | Promise<unknown>;
+    search(input: SessionSearchInput): unknown | Promise<unknown>;
+    read(input: SessionReadInput): unknown | Promise<unknown>;
     private conversations;
 }
-export {};
+declare function project(conversation: RestoredState): {
+    records: ProjectedMessage[];
+    skipped: number;
+} | null;
+declare function updatedAt(conversation: RestoredState | ReadSnapshotSession): string;
+declare function prefixSnippet(text: string): string;
+declare function isBrowsableSession(conversation: RestoredState): boolean;
+declare function revision(conversation: RestoredState, projection: NonNullable<ReturnType<typeof project>>): string;
+export { project as projectMessages, updatedAt as sessionUpdatedAt, revision as sessionRevision, isBrowsableSession, prefixSnippet, };
 //# sourceMappingURL=session-browser.d.ts.map

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

@@ -1 +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;AASF,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;;IAKb,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;;;;;MAsBjD;IAED,MAAM,CAAC,KAAK,EAAE,kBAAkB;iBAsDb,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;;;;MAchD;IAED,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAuHrC;IAoBD,OAAO,CAAC,aAAa;CAWtB"}
+{"version":3,"file":"session-browser.d.ts","sourceRoot":"","sources":["../../../source/services/conversation/session-browser.ts"],"names":[],"mappings":"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"}

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

@@ -1,55 +1,65 @@
-import { browseConversationsForProject, loadConversationForProjectReadOnly, } from './conversation-persistence.js';
+import { browseConversationsForProject, getConversationSourceVersionReadOnly, getConversationsDirectoryVersionReadOnly, loadConversationForProjectReadOnly, resolveConversationReference, uniqueConversationShortRefs, } 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';
+import { SessionIndexService } from './session-index/session-index-service.js';
+import { SNIPPET_CHARS, scoreText, termsFor } from './session-search-helpers.js';
 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;
     #cursorStates = new Map();
     #cursorHandles = new Map();
+    #readSnapshot = null;
     #nextCursorId = 1;
-    constructor(getContext) {
+    #backend;
+    #indexService;
+    #lazyIndexService = null;
+    constructor(getContext, options) {
         this.getContext = getContext;
+        this.#backend =
+            options?.backend ?? (process.env['TERM2_SESSION_BROWSER_BACKEND'] === 'canonical' ? 'canonical' : 'indexed');
+        this.#indexService = options?.indexService;
+    }
+    async close() {
+        if (this.#indexService) {
+            await this.#indexService.close();
+        }
+        if (this.#lazyIndexService) {
+            await this.#lazyIndexService.close();
+            this.#lazyIndexService = null;
+        }
+    }
+    #getIndexService() {
+        if (this.#indexService)
+            return this.#indexService;
+        if (!this.#lazyIndexService) {
+            this.#lazyIndexService = new SessionIndexService();
+        }
+        return this.#lazyIndexService;
     }
     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 });
+        if (this.#backend === 'indexed') {
+            return this.#listIndexed(input);
         }
-        const selected = candidates.slice(0, clamp(input.limit, DEFAULT_LIMIT));
+        return this.#listCanonical(input);
+    }
+    #pageListResult(scope, items, total, unavailable, limit, maxChars) {
+        const budget = maxChars ?? DEFAULT_INDEX_CHARS;
+        const selected = items.slice(0, clamp(limit, DEFAULT_LIMIT));
         const result = {
             sessions: [],
-            scope: browsed.scope,
-            total: candidates.length,
+            scope,
+            total,
             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,
-            };
+        for (const item of selected) {
             const candidate = fitted({ ...result, sessions: [...result.sessions, item], omitted: selected.length }, budget);
             if (candidate)
                 result.sessions = candidate.sessions;
@@ -58,14 +68,55 @@ export class SessionBrowser {
         }
         return fitted(result, budget) ?? outputBudgetError(budget);
     }
+    #listCanonical(input) {
+        const browsed = this.conversations();
+        let unavailable = browsed.unavailable;
+        const conversations = browsed.conversations;
+        const shortRefs = uniqueConversationShortRefs(conversations);
+        const candidates = [];
+        for (const conversation of conversations) {
+            const projection = project(conversation);
+            if (!projection || !isBrowsableSession(conversation)) {
+                unavailable++;
+            }
+            else {
+                const firstUser = projection.records.find((record) => record.kind === 'user' && record.text);
+                candidates.push({
+                    id: conversation.id,
+                    shortRef: shortRefs.get(conversation.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,
+                });
+            }
+        }
+        return this.#pageListResult(browsed.scope, candidates, candidates.length, unavailable, input.limit, input.maxChars);
+    }
+    async #listIndexed(input) {
+        const service = this.#getIndexService();
+        const context = this.getContext();
+        const indexed = await service.list(context);
+        if (indexed !== null) {
+            return this.#pageListResult(indexed.scope, indexed.sessions, indexed.total, indexed.unavailable, input.limit, input.maxChars);
+        }
+        return this.#listCanonical(input);
+    }
     search(input) {
-        const budget = input.maxChars ?? DEFAULT_INDEX_CHARS;
+        if (this.#backend === 'indexed') {
+            return this.#searchIndexed(input);
+        }
+        return this.#searchCanonical(input);
+    }
+    #searchCanonical(input) {
         const terms = termsFor(input.query);
         const browsed = this.conversations();
         let unavailable = browsed.unavailable;
         const conversations = browsed.conversations;
+        const shortRefs = uniqueConversationShortRefs(conversations);
         let skippedMessageCount = 0;
-        const currentSessionId = this.getContext().currentSessionId;
         const matches = [];
         for (const conversation of conversations) {
             const projection = project(conversation);
@@ -81,6 +132,7 @@ export class SessionBrowser {
                 if (score)
                     matches.push({
                         sessionId: conversation.id,
+                        shortRef: shortRefs.get(conversation.id) ?? conversation.id,
                         kind: record.kind,
                         messageIndex: record.index,
                         snippet: matchCenteredSnippet(record.text, terms, SNIPPET_CHARS),
@@ -89,6 +141,22 @@ export class SessionBrowser {
                     });
             }
         }
+        return this.#pageSearchResult(matches, browsed.scope, unavailable, skippedMessageCount, input.kinds, input.limit, input.maxChars);
+    }
+    async #searchIndexed(input) {
+        const service = this.#getIndexService();
+        const context = this.getContext();
+        const indexed = await service.search(input.query, context);
+        if (indexed !== null) {
+            return this.#pageSearchResult(indexed.matches, indexed.scope, indexed.unavailable, indexed.skippedMessageCount, input.kinds, input.limit, input.maxChars);
+        }
+        return this.#searchCanonical(input);
+    }
+    #pageSearchResult(matches, scope, unavailable, skippedMessageCount, kinds, limit, maxChars) {
+        const budget = maxChars ?? DEFAULT_INDEX_CHARS;
+        const includedKinds = kinds ? new Set(kinds) : null;
+        matches = includedKinds ? matches.filter((match) => includedKinds.has(match.kind)) : matches;
+        const currentSessionId = this.getContext().currentSessionId;
         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
@@ -103,10 +171,10 @@ export class SessionBrowser {
                 a.sessionId.localeCompare(b.sessionId) ||
                 a.messageIndex - b.messageIndex);
         });
-        const selected = matches.slice(0, clamp(input.limit, DEFAULT_LIMIT));
+        const selected = matches.slice(0, clamp(limit, DEFAULT_LIMIT));
         const result = {
             results: [],
-            scope: browsed.scope,
+            scope,
             total: matches.length,
             omitted: 0,
             unavailable,
@@ -123,40 +191,206 @@ export class SessionBrowser {
         return fitted(result, budget) ?? outputBudgetError(budget);
     }
     read(input) {
+        if (this.#backend === 'indexed') {
+            return this.#readIndexed(input);
+        }
+        return this.#readCanonical(input);
+    }
+    #readCanonical(input) {
         const budget = input.maxChars ?? DEFAULT_READ_CHARS;
         if (!SAFE_SESSION_ID.test(input.id))
             return boundedError('not_found', 'Session was not found.', budget);
+        if (input.cursor !== undefined && input.from === 'end')
+            return boundedError('invalid_cursor', 'The `from: "end"` anchor is only valid on an initial read.', budget);
         const context = this.getContext();
-        const loaded = loadConversationForProjectReadOnly(input.id, context.projectPath, context.sshHost);
-        if (loaded.status === 'not_found')
+        const cached = input.cursor ? this.#snapshotForContinuation(input.cursor, input.id, context) : null;
+        let conversation;
+        let projection;
+        let resolvedId;
+        let shortRef;
+        let currentRevision;
+        if (cached) {
+            ({ conversation, projection, shortRef, revision: currentRevision } = cached);
+            resolvedId = conversation.id;
+        }
+        else {
+            const browsed = this.conversations();
+            const resolution = resolveSessionReference(input.id, browsed.conversations, context.currentSessionId);
+            if (resolution.kind === 'ambiguous') {
+                return (fitted({
+                    error: {
+                        code: 'ambiguous_reference',
+                        message: 'Session reference is ambiguous; use a longer prefix or an exact ID.',
+                        candidates: resolution.candidates,
+                    },
+                }, budget) ??
+                    boundedError('ambiguous_reference', `Session reference is ambiguous. Candidates: ${resolution.candidates
+                        .map((candidate) => candidate.shortRef)
+                        .join(', ')}.`, budget));
+            }
+            if (resolution.kind === 'not_found')
+                return boundedError('not_found', resolution.message, budget);
+            resolvedId = resolution.id;
+            const indexedConversation = browsed.conversations.find((candidate) => candidate.id === resolvedId);
+            const indexedSourceVersion = browsed.sourceVersions.get(resolvedId);
+            let sourceVersion;
+            let canonicalConversation;
+            if (indexedConversation &&
+                indexedSourceVersion &&
+                getConversationSourceVersionReadOnly(resolvedId) === indexedSourceVersion) {
+                canonicalConversation = indexedConversation;
+                sourceVersion = indexedSourceVersion;
+            }
+            else {
+                const loaded = loadConversationForProjectReadOnly(resolvedId, context.projectPath, context.sshHost);
+                if (loaded.status === 'not_found')
+                    return boundedError('not_found', `Session was not found in scope ${context.projectPath}.`, budget);
+                if (loaded.status === 'project_mismatch')
+                    return boundedError('not_found', `Session exists but belongs to project ${loaded.conversation.projectPath}, which does not match the current scope (${context.projectPath}); it cannot be read from the current scope.`, budget);
+                if (loaded.status !== 'loaded' || loaded.conversation.id !== resolvedId || !loaded.conversation.createdAt)
+                    return boundedError('session_unavailable', 'Session transcript is unavailable.', budget);
+                canonicalConversation = loaded.conversation;
+                sourceVersion = loaded.sourceVersion;
+            }
+            const projected = project(canonicalConversation);
+            if (!projected || !isBrowsableSession(canonicalConversation))
+                return boundedError('session_unavailable', 'Session transcript is unavailable.', budget);
+            conversation = canonicalConversation;
+            projection = projected;
+            shortRef =
+                uniqueConversationShortRefs(browsed.conversations).get(canonicalConversation.id) ?? canonicalConversation.id;
+            currentRevision = revision(canonicalConversation, projection);
+            if (sourceVersion && browsed.directoryVersion) {
+                const previousDependency = input.id === 'previous' && context.currentSessionId
+                    ? browsed.sourceVersions.get(context.currentSessionId)
+                    : undefined;
+                this.#readSnapshot = {
+                    contextKey: contextKey(context),
+                    directoryVersion: browsed.directoryVersion,
+                    sourceVersion,
+                    conversation,
+                    projection,
+                    shortRef,
+                    revision: currentRevision,
+                    ...(context.currentSessionId && previousDependency
+                        ? { previousDependency: { sessionId: context.currentSessionId, sourceVersion: previousDependency } }
+                        : {}),
+                };
+            }
+            else {
+                this.#readSnapshot = null;
+            }
+        }
+        return this.#pageReadResult(input, context, conversation, projection, shortRef, resolvedId, currentRevision);
+    }
+    async #readIndexed(input) {
+        const budget = input.maxChars ?? DEFAULT_READ_CHARS;
+        if (!SAFE_SESSION_ID.test(input.id))
+            return boundedError('not_found', 'Session was not found.', budget);
+        if (input.cursor !== undefined && input.from === 'end')
+            return boundedError('invalid_cursor', 'The `from: "end"` anchor is only valid on an initial read.', budget);
+        const context = this.getContext();
+        const cached = input.cursor ? this.#snapshotForContinuation(input.cursor, input.id, context) : null;
+        if (cached) {
+            return this.#pageReadResult(input, context, cached.conversation, cached.projection, cached.shortRef, cached.conversation.id, cached.revision);
+        }
+        const service = this.#getIndexService();
+        const resolution = await service.resolveReference(input.id, context);
+        if (!resolution) {
+            return this.#readCanonical(input);
+        }
+        if (resolution.kind === 'ambiguous') {
+            return (fitted({
+                error: {
+                    code: 'ambiguous_reference',
+                    message: 'Session reference is ambiguous; use a longer prefix or an exact ID.',
+                    candidates: resolution.candidates,
+                },
+            }, budget) ??
+                boundedError('ambiguous_reference', `Session reference is ambiguous. Candidates: ${resolution.candidates
+                    .map((candidate) => candidate.shortRef)
+                    .join(', ')}.`, budget));
+        }
+        if (resolution.kind === 'not_found') {
+            return boundedError('not_found', resolution.message, budget);
+        }
+        const resolvedId = resolution.id;
+        const sessionResult = await service.readSession(resolvedId, context);
+        if (!sessionResult) {
+            return this.#readCanonical(input);
+        }
+        if (sessionResult.kind === 'not_found') {
             return boundedError('not_found', `Session was not found in scope ${context.projectPath}.`, budget);
-        if (loaded.status === 'project_mismatch')
-            return boundedError('not_found', `Session exists but belongs to project ${loaded.conversation.projectPath}, which does not match the current scope (${context.projectPath}); it cannot be read from the current scope.`, 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))
+        }
+        if (sessionResult.kind === 'project_mismatch') {
+            return boundedError('not_found', `Session exists but belongs to project ${sessionResult.projectPath ?? 'undefined'}, which does not match the current scope (${context.projectPath}); it cannot be read from the current scope.`, budget);
+        }
+        if (sessionResult.kind === 'unavailable') {
             return boundedError('session_unavailable', 'Session transcript is unavailable.', budget);
+        }
+        const sessionData = sessionResult.session;
+        const conversation = {
+            id: sessionData.id,
+            createdAt: sessionData.createdAt,
+            updatedAt: sessionData.updatedAt,
+            model: sessionData.model ?? undefined,
+            provider: sessionData.provider ?? undefined,
+            rolloverFrom: sessionData.predecessorId ?? undefined,
+        };
+        const projection = {
+            records: sessionData.records,
+            skipped: sessionData.skippedCount,
+        };
+        const shortRef = resolution.shortRef ?? conversation.id;
+        const currentRevision = sessionData.projectionRevision;
+        const dirVersion = getConversationsDirectoryVersionReadOnly();
+        const sourceVersion = sessionData.sourceVersion;
+        if (sourceVersion && dirVersion) {
+            const previousDependency = input.id === 'previous' && context.currentSessionId
+                ? getConversationSourceVersionReadOnly(context.currentSessionId) ?? undefined
+                : undefined;
+            this.#readSnapshot = {
+                contextKey: contextKey(context),
+                directoryVersion: dirVersion,
+                sourceVersion,
+                conversation,
+                projection,
+                shortRef,
+                revision: currentRevision,
+                ...(context.currentSessionId && previousDependency
+                    ? { previousDependency: { sessionId: context.currentSessionId, sourceVersion: previousDependency } }
+                    : {}),
+            };
+        }
+        else {
+            this.#readSnapshot = null;
+        }
+        return this.#pageReadResult(input, context, conversation, projection, shortRef, resolvedId, currentRevision);
+    }
+    #pageReadResult(input, context, conversation, projection, shortRef, resolvedId, currentRevision) {
+        const budget = input.maxChars ?? DEFAULT_READ_CHARS;
         const currentUpdatedAt = updatedAt(conversation);
-        const currentRevision = revision(conversation, projection);
         const cursor = input.cursor
-            ? this.#decodeCursor(input.cursor, input.id)
+            ? this.#decodeCursor(input.cursor, resolvedId)
             : {
-                sessionId: input.id,
+                sessionId: resolvedId,
                 updatedAt: currentUpdatedAt,
                 revision: currentRevision,
-                nextIndex: 0,
+                // The tail anchor is a region, not a record: start at the last
+                // `limit` projected records so last-N access works through the
+                // existing forward cursor.
+                nextIndex: input.from === 'end' ? Math.max(0, projection.records.length - clamp(input.limit, DEFAULT_READ_LIMIT)) : 0,
                 nextTextOffset: 0,
             };
         if (!cursor)
-            return boundedError('invalid_cursor', 'The session cursor is invalid.', budget);
+            return boundedError('invalid_cursor', invalidCursorMessage(), budget);
         if (input.cursor && (cursor.updatedAt !== currentUpdatedAt || cursor.revision !== currentRevision))
-            return boundedError('stale_cursor', 'The session cursor is stale.', budget);
+            return boundedError('stale_cursor', staleCursorMessage(), budget);
         if (input.cursor && !validCursorPosition(cursor, projection.records))
-            return boundedError('invalid_cursor', 'The session cursor is invalid.', budget);
+            return boundedError('invalid_cursor', invalidCursorMessage(), budget);
         const session = {
             id: conversation.id,
+            shortRef,
             createdAt: conversation.createdAt,
             updatedAt: currentUpdatedAt,
             ...(conversation.model ? { model: conversation.model } : {}),
@@ -170,11 +404,11 @@ export class SessionBrowser {
         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);
+                return boundedError('invalid_cursor', invalidCursorMessage(), budget);
             const completeItem = pageItem(record, record.text.slice(offset), offset, true);
             const afterIndex = index + 1;
             const nextCursor = afterIndex < projection.records.length
-                ? this.#cursorFor(input.id, currentUpdatedAt, currentRevision, afterIndex, 0)
+                ? this.#cursorFor(resolvedId, currentUpdatedAt, currentRevision, afterIndex, 0)
                 : undefined;
             const candidate = fitted({
                 scope: context.projectPath,
@@ -199,7 +433,7 @@ export class SessionBrowser {
             if (record.text.length === offset)
                 return outputBudgetError(budget);
             const chunk = largestChunk(record, offset, (text) => {
-                const next = this.#cursorFor(input.id, currentUpdatedAt, currentRevision, index, offset + text.length);
+                const next = this.#cursorFor(resolvedId, currentUpdatedAt, currentRevision, index, offset + text.length);
                 return fitted({
                     scope: context.projectPath,
                     session,
@@ -216,11 +450,11 @@ export class SessionBrowser {
             offset += chunk.length;
             break;
         }
-        const nextCursor = index < total ? this.#cursorFor(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);
+        const nextCursor = index < total ? this.#cursorFor(resolvedId, currentUpdatedAt, currentRevision, index, offset) : undefined;
+        // Page-local counts: every record represented on this page counts once,
+        // whether complete or a partial/resumed chunk, so on every page shape
+        // `total - omitted === items.length`.
+        const omitted = total - items.length;
         return (fitted({
             scope: context.projectPath,
             session,
@@ -231,6 +465,32 @@ export class SessionBrowser {
             skippedMessageCount: projection.skipped,
         }, budget) ?? outputBudgetError(budget));
     }
+    #snapshotForContinuation(cursorHandle, inputId, context) {
+        if (!/^c[0-9a-z]+$/.test(cursorHandle))
+            return null;
+        const cursor = this.#cursorStates.get(cursorHandle);
+        const snapshot = this.#readSnapshot;
+        if (!cursor || !snapshot || cursor.sessionId !== snapshot.conversation.id)
+            return null;
+        // Reuse is authorization-neutral: the exact context that authorized the
+        // snapshot must still be active, and every persistence source that can
+        // affect this page must still have the same cheap filesystem version.
+        if (snapshot.contextKey !== contextKey(context))
+            return null;
+        if (getConversationsDirectoryVersionReadOnly() !== snapshot.directoryVersion)
+            return null;
+        if (getConversationSourceVersionReadOnly(cursor.sessionId) !== snapshot.sourceVersion)
+            return null;
+        if (inputId !== cursor.sessionId) {
+            const dependency = snapshot.previousDependency;
+            if (inputId !== 'previous' ||
+                !dependency ||
+                dependency.sessionId !== context.currentSessionId ||
+                getConversationSourceVersionReadOnly(dependency.sessionId) !== dependency.sourceVersion)
+                return null;
+        }
+        return snapshot;
+    }
     #cursorFor(sessionId, updatedAt, revision, nextIndex, nextTextOffset) {
         const state = { sessionId, updatedAt, revision, nextIndex, nextTextOffset };
         const stateKey = JSON.stringify(state);
@@ -255,10 +515,22 @@ export class SessionBrowser {
         return {
             unavailable: result.unavailable,
             scope: context.projectPath,
+            sourceVersions: result.sourceVersions,
+            directoryVersion: result.directoryVersion,
             conversations: result.conversations.sort((a, b) => updatedAt(b).localeCompare(updatedAt(a)) || a.id.localeCompare(b.id)),
         };
     }
 }
+function resolveSessionReference(reference, conversations, currentSessionId) {
+    if (reference === 'previous') {
+        const current = conversations.find((conversation) => conversation.id === currentSessionId);
+        if (!current?.rolloverFrom) {
+            return { kind: 'not_found', message: 'This session has no persisted rollover predecessor.' };
+        }
+        return { kind: 'resolved', id: current.rolloverFrom };
+    }
+    return resolveConversationReference(reference, conversations);
+}
 function project(conversation) {
     const records = [];
     let skipped = 0;
@@ -313,20 +585,12 @@ function project(conversation) {
 function updatedAt(conversation) {
     return conversation.updatedAt ?? conversation.createdAt;
 }
+function contextKey(context) {
+    return JSON.stringify([context.projectPath, context.sshHost ?? null, context.currentSessionId ?? null]);
+}
 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;
@@ -342,6 +606,12 @@ function fitted(value, maxChars) {
 function outputBudgetError(maxChars) {
     return boundedError('output_budget_exceeded', 'The requested result cannot fit in the output budget.', maxChars);
 }
+function invalidCursorMessage() {
+    return 'The session cursor is invalid. Use exactly the nextCursor returned by the preceding page with the same id. Restart without a cursor if that handle is unavailable.';
+}
+function staleCursorMessage() {
+    return 'The session cursor is stale because the session changed. Restart without a cursor to read the current transcript.';
+}
 function boundedError(code, message, maxChars) {
     const value = { error: { code, message } };
     if (fitsSerializedText(JSON.stringify(value), { maxChars }))
@@ -410,4 +680,5 @@ function isHighSurrogate(value) {
 function isLowSurrogate(value) {
     return value >= 0xdc00 && value <= 0xdfff;
 }
+export { project as projectMessages, updatedAt as sessionUpdatedAt, revision as sessionRevision, isBrowsableSession, prefixSnippet, };
 //# sourceMappingURL=session-browser.js.map