@myagentroam/node 0.9.3 → 0.9.5

package/dist/service/workspace-watch-service.js

@@ -36,20 +36,29 @@ export class WorkspaceWatchService {
         return { sessions, changes, files };
     }
     key(input) {
-        return `${this.sessionHash(input)}:${input.watchId}`;
+        return `${this.sessionHash(input)}:${this.connectionId(input)}`;
     }
     sessionHash(input) {
         return typeof input.__workspaceWatchSessionHash === 'string'
             ? input.__workspaceWatchSessionHash
             : 'local-test';
     }
-    create(workspaceId, watchId, sessionHash, topics) {
-        const key = `${sessionHash}:${watchId}`;
-        this.remove(workspaceId, key);
+    connectionId(input) {
+        if (typeof input.workbenchConnectionId !== 'string')
+            throw new Error('WORKSPACE_WATCH_INVALID');
+        return input.workbenchConnectionId;
+    }
+    create(workspaceId, watchId, sessionHash, workbenchConnectionId, nodeGeneration, topics) {
+        const key = `${sessionHash}:${workbenchConnectionId}`;
+        for (const [activeWorkspaceId, watches] of this.state.watches)
+            if (watches.has(key))
+                this.remove(activeWorkspaceId, key);
         const watch = {
             workspaceId,
             watchId,
             sessionHash,
+            workbenchConnectionId,
+            nodeGeneration,
             expiresAt: Date.now() + WATCH_TTL_MS,
             topics,
             timer: undefined
@@ -62,9 +71,11 @@ export class WorkspaceWatchService {
             this.onSessionWatchRequired(workspaceId);
         return watch;
     }
-    renew(workspaceId, key) {
+    renew(workspaceId, key, watchId) {
         const watch = this.state.watches.get(workspaceId)?.get(key);
-        if (watch === undefined || watch.expiresAt <= Date.now()) {
+        if (watch === undefined || watch.watchId !== watchId)
+            return undefined;
+        if (watch.expiresAt <= Date.now()) {
             this.remove(workspaceId, key);
             return undefined;
         }
@@ -73,6 +84,14 @@ export class WorkspaceWatchService {
         watch.timer = this.expiryTimer(workspaceId, key);
         return watch;
     }
+    matches(workspaceId, key, watchId) {
+        const watch = this.state.watches.get(workspaceId)?.get(key);
+        return watch !== undefined && watch.watchId === watchId && watch.expiresAt > Date.now();
+    }
+    existing(workspaceId, key) {
+        const watch = this.state.watches.get(workspaceId)?.get(key);
+        return watch !== undefined && watch.expiresAt > Date.now() ? watch : undefined;
+    }
     remove(workspaceId, key) {
         const watches = this.state.watches.get(workspaceId);
         const watch = watches?.get(key);
@@ -106,9 +125,16 @@ export class WorkspaceWatchService {
         this.state.watchRevisions.set(workspaceId, revision);
         return revision;
     }
+    nextSnapshotSequence() {
+        this.state.watchSnapshotSequence += 1;
+        return this.state.watchSnapshotSequence;
+    }
     topicActive(workspaceId, topic) {
         return [...(this.state.watches.get(workspaceId)?.values() ?? [])].some((watch) => topic === 'files' ? watch.topics.files !== undefined : watch.topics[topic]);
     }
+    activeWatches(workspaceId) {
+        return [...(this.state.watches.get(workspaceId)?.values() ?? [])].filter((watch) => watch.expiresAt > Date.now());
+    }
     expiryTimer(workspaceId, key) {
         const timer = setTimeout(() => this.remove(workspaceId, key), WATCH_TTL_MS);
         timer.unref();

package/dist/service/workspace-workbench-service.d.ts

@@ -12,14 +12,26 @@ export interface WorkspaceWorkbenchServiceOptions {
     readonly changes: WorkspaceChangeService;
     readonly listSessions: (workspaceId: string) => Promise<unknown>;
     readonly invalidate: (workspaceId: string) => void;
+    readonly nodeId: () => string;
+    readonly nodeGeneration: () => string;
+    readonly emitWatchEvent: (payload: unknown) => void;
 }
 export declare class WorkspaceWorkbenchService {
     private readonly options;
     private readonly contentSearch;
+    private readonly topicRefreshes;
+    private readonly dirtyTopics;
     constructor(options: WorkspaceWorkbenchServiceOptions);
     operations(): Readonly<Record<string, NodeOperationHandler>>;
+    refreshTopic(workspaceId: string, topic: 'sessions' | 'files' | 'changes'): Promise<void>;
+    private emitTopicFailure;
+    private performTopicRefresh;
     private watch;
     private unwatch;
+    private accepted;
+    private createInitialSnapshots;
+    private emitSnapshot;
+    private deliverSnapshot;
     private listFiles;
     private readFile;
     private searchFiles;
@@ -31,6 +43,7 @@ export declare class WorkspaceWorkbenchService {
     private completeUpload;
     private cancelUpload;
     private currentChanges;
+    private readFileContent;
     private changeDiff;
     private restoreChange;
     private gitRepository;
@@ -39,6 +52,7 @@ export declare class WorkspaceWorkbenchService {
     private gitHistory;
     private gitCommitFiles;
     private gitCommitFileDiff;
+    private gitCommitFileContent;
     private diff;
     private gitWorkspace;
 }

package/dist/service/workspace-workbench-service.js

@@ -1,8 +1,10 @@
-import { listGitHistoryRefs, readGitHistory, readGitHistoryFileDiff, readGitHistoryFiles, readCurrentChangeDiff, readRestrictedDiff, resolveGitRepository, restoreCurrentChange } from '../workspace.js';
+import { listGitHistoryRefs, readGitHistory, readGitHistoryFileDiff, readGitHistoryFileContentRange, readGitHistoryFiles, readCurrentChangeDiff, readRestrictedDiff, resolveGitRepository, restoreCurrentChange } from '../workspace.js';
 import { WorkspaceContentSearchService } from './workspace-content-search-service.js';
 export class WorkspaceWorkbenchService {
     options;
     contentSearch;
+    topicRefreshes = new Map();
+    dirtyTopics = new Set();
     constructor(options) {
         this.options = options;
         this.contentSearch = new WorkspaceContentSearchService(options.files);
@@ -13,6 +15,7 @@ export class WorkspaceWorkbenchService {
             'workspace.unwatch': (data) => this.unwatch(record(data)),
             'workspace.files.list': (data) => this.listFiles(record(data)),
             'workspace.file.read': (data) => this.readFile(record(data)),
+            'workspace.file.content.read': (data) => this.readFileContent(record(data)),
             'workspace.files.search': (data) => this.searchFiles(record(data)),
             'workspace.files.mutate': (data) => this.mutateFile(record(data)),
             'workspace.content.search': (data) => this.searchContent(record(data)),
@@ -31,44 +34,220 @@ export class WorkspaceWorkbenchService {
             'workspace.git.history.list': (data) => this.gitHistory(record(data)),
             'workspace.git.commit.files': (data) => this.gitCommitFiles(record(data)),
             'workspace.git.commit.file.diff': (data) => this.gitCommitFileDiff(record(data)),
+            'workspace.git.commit.file.content.read': (data) => this.gitCommitFileContent(record(data)),
             'workspace.diff': (data) => this.diff(record(data))
         };
     }
+    async refreshTopic(workspaceId, topic) {
+        const key = `${workspaceId}:${topic}`;
+        const active = this.topicRefreshes.get(key);
+        if (active !== undefined) {
+            this.dirtyTopics.add(key);
+            return active;
+        }
+        const refresh = this.performTopicRefresh(workspaceId, topic).catch(() => {
+            this.emitTopicFailure(workspaceId, topic);
+        });
+        this.topicRefreshes.set(key, refresh);
+        try {
+            await refresh;
+        }
+        finally {
+            if (this.topicRefreshes.get(key) === refresh)
+                this.topicRefreshes.delete(key);
+            if (this.dirtyTopics.delete(key))
+                void this.refreshTopic(workspaceId, topic);
+        }
+    }
+    emitTopicFailure(workspaceId, topic) {
+        for (const watch of this.options.watch.activeWatches(workspaceId)) {
+            const subscribed = topic === 'files' ? watch.topics.files !== undefined : watch.topics[topic] === true;
+            if (!subscribed)
+                continue;
+            this.options.emitWatchEvent({
+                type: 'watch.failed',
+                workbenchConnectionId: watch.workbenchConnectionId,
+                watchType: 'workspace',
+                watchId: watch.watchId,
+                nodeGeneration: watch.nodeGeneration,
+                nodeId: this.options.nodeId(),
+                workspaceId,
+                topic,
+                code: 'WORKSPACE_WATCH_SNAPSHOT_FAILED',
+                message: 'Workspace watch snapshot failed.'
+            });
+        }
+    }
+    async performTopicRefresh(workspaceId, topic) {
+        const workspace = this.options.requireWorkspace(workspaceId);
+        const watches = this.options.watch.activeWatches(workspaceId);
+        if (topic === 'sessions') {
+            const subscribers = watches.filter((watch) => watch.topics.sessions);
+            if (subscribers.length === 0)
+                return;
+            const payload = await this.options.listSessions(workspace.id);
+            for (const watch of subscribers)
+                this.deliverSnapshot(workspace, watch, topic, payload);
+            return;
+        }
+        if (topic === 'changes') {
+            const subscribers = watches.filter((watch) => watch.topics.changes);
+            if (subscribers.length === 0)
+                return;
+            const payload = workspace.kind === 'GIT_WORKSPACE' ? await this.options.changes.current(workspace) : null;
+            for (const watch of subscribers)
+                this.deliverSnapshot(workspace, watch, topic, payload);
+            return;
+        }
+        const views = new Map();
+        for (const watch of watches) {
+            if (watch.topics.files === undefined)
+                continue;
+            const key = JSON.stringify(watch.topics.files);
+            views.set(key, [...(views.get(key) ?? []), watch]);
+        }
+        await Promise.all([...views.values()].map(async (subscribers) => {
+            const view = subscribers[0]?.topics.files;
+            if (view === undefined)
+                return;
+            const payload = { files: await this.options.files.list(workspace, view) };
+            for (const watch of subscribers)
+                this.deliverSnapshot(workspace, watch, topic, payload);
+        }));
+    }
     async watch(input) {
         if (typeof input.workspaceId !== 'string' ||
             typeof input.watchId !== 'string' ||
+            typeof input.workbenchConnectionId !== 'string' ||
             !/^[A-Za-z0-9_-]{8,128}$/.test(input.watchId) ||
             (input.mode !== 'initial' && input.mode !== 'renew'))
             throw new Error('WORKSPACE_WATCH_INVALID');
         const workspace = this.options.requireWorkspace(input.workspaceId);
         if (input.mode === 'renew') {
-            const watch = this.options.watch.renew(workspace.id, this.options.watch.key(input));
+            const watch = this.options.watch.renew(workspace.id, this.options.watch.key(input), input.watchId);
             if (watch === undefined)
                 throw new Error('WORKSPACE_WATCH_NOT_FOUND');
-            return { renewed: true };
+            return this.accepted(watch);
         }
         const topics = this.options.watch.parseTopics(input);
-        const snapshot = {};
-        if (topics.sessions)
-            snapshot.sessions = await this.options.listSessions(workspace.id);
-        if (topics.files !== undefined)
-            snapshot.files = { files: await this.options.files.list(workspace, topics.files) };
-        if (topics.changes)
-            snapshot.changes =
-                workspace.kind === 'GIT_WORKSPACE' ? await this.options.changes.current(workspace) : null;
-        if (topics.files !== undefined || topics.changes)
-            await this.options.files.index(workspace).observe();
-        const watch = this.options.watch.create(workspace.id, input.watchId, this.options.watch.sessionHash(input), topics);
-        return { watch: { expiresAt: watch.expiresAt }, snapshot };
+        const existing = this.options.watch.existing(workspace.id, this.options.watch.key(input));
+        if (existing?.watchId === input.watchId &&
+            JSON.stringify(existing.topics) === JSON.stringify(topics)) {
+            this.options.watch.renew(workspace.id, this.options.watch.key(input), input.watchId);
+            return this.accepted(existing);
+        }
+        const watch = this.options.watch.create(workspace.id, input.watchId, this.options.watch.sessionHash(input), input.workbenchConnectionId, this.options.nodeGeneration(), topics);
+        void this.createInitialSnapshots(workspace, watch);
+        return this.accepted(watch);
     }
     unwatch(input) {
         if (typeof input.workspaceId !== 'string' ||
             typeof input.watchId !== 'string' ||
+            typeof input.workbenchConnectionId !== 'string' ||
             !/^[A-Za-z0-9_-]{8,128}$/.test(input.watchId))
             throw new Error('WORKSPACE_WATCH_INVALID');
-        this.options.watch.remove(input.workspaceId, this.options.watch.key(input));
+        const key = this.options.watch.key(input);
+        const watch = this.options.watch.renew(input.workspaceId, key, input.watchId);
+        if (watch !== undefined)
+            this.options.watch.remove(input.workspaceId, key);
         return { stopped: true };
     }
+    accepted(watch) {
+        return {
+            accepted: true,
+            watchId: watch.watchId,
+            nodeGeneration: watch.nodeGeneration,
+            expiresAt: watch.expiresAt
+        };
+    }
+    async createInitialSnapshots(workspace, watch) {
+        const tasks = [];
+        const emit = async (topic, read) => {
+            try {
+                const payload = await read();
+                if (!this.options.watch.matches(workspace.id, `${watch.sessionHash}:${watch.workbenchConnectionId}`, watch.watchId))
+                    return;
+                this.options.emitWatchEvent({
+                    type: 'watch.workspace.snapshot',
+                    workbenchConnectionId: watch.workbenchConnectionId,
+                    watchId: watch.watchId,
+                    nodeGeneration: watch.nodeGeneration,
+                    nodeId: this.options.nodeId(),
+                    workspaceId: workspace.id,
+                    topic,
+                    revision: this.options.watch.nextRevision(workspace.id),
+                    snapshotSequence: this.options.watch.nextSnapshotSequence(),
+                    expiresAt: watch.expiresAt,
+                    payload
+                });
+            }
+            catch {
+                this.options.emitWatchEvent({
+                    type: 'watch.failed',
+                    workbenchConnectionId: watch.workbenchConnectionId,
+                    watchType: 'workspace',
+                    watchId: watch.watchId,
+                    nodeGeneration: watch.nodeGeneration,
+                    nodeId: this.options.nodeId(),
+                    workspaceId: workspace.id,
+                    topic,
+                    code: 'WORKSPACE_WATCH_SNAPSHOT_FAILED',
+                    message: 'Workspace watch snapshot failed.'
+                });
+            }
+        };
+        if (watch.topics.sessions)
+            tasks.push(emit('sessions', () => this.options.listSessions(workspace.id)));
+        if (watch.topics.files !== undefined)
+            tasks.push(emit('files', async () => ({
+                files: await this.options.files.list(workspace, watch.topics.files)
+            })));
+        if (watch.topics.changes)
+            tasks.push(emit('changes', async () => workspace.kind === 'GIT_WORKSPACE' ? this.options.changes.current(workspace) : null));
+        if (watch.topics.files !== undefined || watch.topics.changes)
+            void this.options.files
+                .index(workspace)
+                .observe()
+                .catch(() => undefined);
+        await Promise.all(tasks);
+    }
+    async emitSnapshot(workspace, watch, topic, read) {
+        try {
+            const payload = await read();
+            this.deliverSnapshot(workspace, watch, topic, payload);
+        }
+        catch {
+            this.options.emitWatchEvent({
+                type: 'watch.failed',
+                workbenchConnectionId: watch.workbenchConnectionId,
+                watchType: 'workspace',
+                watchId: watch.watchId,
+                nodeGeneration: watch.nodeGeneration,
+                nodeId: this.options.nodeId(),
+                workspaceId: workspace.id,
+                topic,
+                code: 'WORKSPACE_WATCH_SNAPSHOT_FAILED',
+                message: 'Workspace watch snapshot failed.'
+            });
+        }
+    }
+    deliverSnapshot(workspace, watch, topic, payload) {
+        if (!this.options.watch.matches(workspace.id, `${watch.sessionHash}:${watch.workbenchConnectionId}`, watch.watchId))
+            return;
+        this.options.emitWatchEvent({
+            type: 'watch.workspace.snapshot',
+            workbenchConnectionId: watch.workbenchConnectionId,
+            watchId: watch.watchId,
+            nodeGeneration: watch.nodeGeneration,
+            nodeId: this.options.nodeId(),
+            workspaceId: workspace.id,
+            topic,
+            revision: this.options.watch.nextRevision(workspace.id),
+            snapshotSequence: this.options.watch.nextSnapshotSequence(),
+            expiresAt: watch.expiresAt,
+            payload
+        });
+    }
     async listFiles(input) {
         const workspace = this.options.requireWorkspace(input.workspaceId);
         return { files: await this.options.files.list(workspace, input) };
@@ -112,6 +291,13 @@ export class WorkspaceWorkbenchService {
     async currentChanges(input) {
         return this.options.changes.current(this.options.requireWorkspace(input.workspaceId));
     }
+    async readFileContent(input) {
+        if (typeof input.workspaceId !== 'string')
+            throw new Error('WORKSPACE_NOT_FOUND');
+        return {
+            file: await this.options.files.readContent(this.options.requireWorkspace(input.workspaceId), input)
+        };
+    }
     async changeDiff(input) {
         if (typeof input.workspaceId !== 'string' ||
             typeof input.path !== 'string' ||
@@ -184,6 +370,19 @@ export class WorkspaceWorkbenchService {
             diff: await readGitHistoryFileDiff(await this.gitRepository(input), input.commit, input.path, this.refs(input), input.previousPath)
         };
     }
+    async gitCommitFileContent(input) {
+        if (typeof input.commit !== 'string' ||
+            typeof input.path !== 'string' ||
+            !Number.isSafeInteger(input.offset) ||
+            input.offset < 0 ||
+            !Number.isSafeInteger(input.limit) ||
+            input.limit < 1 ||
+            input.limit > 20 * 1024 * 1024)
+            throw new Error('FILE_RANGE_INVALID');
+        return {
+            file: await readGitHistoryFileContentRange(await this.gitRepository(input), input.commit, input.path, input.offset, input.limit, this.refs(input))
+        };
+    }
     async diff(input) {
         if (typeof input.workspaceId !== 'string' ||
             typeof input.fromRef !== 'string' ||

package/dist/util/personal-instructions.d.ts

@@ -0,0 +1,2 @@
+import type { RunnerName } from '@myagentroam/protocol';
+export declare function personalInstructionsForRunner(value: unknown, runner: RunnerName): string | undefined;

package/dist/util/personal-instructions.js

@@ -0,0 +1,31 @@
+const MAX_CONTENT_LENGTH = 20_000;
+export function personalInstructionsForRunner(value, runner) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('PERSONAL_INSTRUCTION_INVALID');
+    const record = value;
+    const instructions = {
+        common: content(record['common']),
+        codex: content(record['codex']),
+        claudeCode: content(record['claudeCode']),
+        openCode: content(record['openCode'])
+    };
+    const specialized = runner === 'codex'
+        ? instructions.codex
+        : runner === 'claude-code'
+            ? instructions.claudeCode
+            : instructions.openCode;
+    const merged = [instructions.common, specialized].filter((item) => item.length > 0).join('\n\n');
+    return merged.length === 0 ? undefined : merged;
+}
+function content(value) {
+    if (value === undefined)
+        return '';
+    if (typeof value !== 'string')
+        throw new Error('PERSONAL_INSTRUCTION_INVALID');
+    const normalized = value.trim();
+    if (normalized.length > MAX_CONTENT_LENGTH)
+        throw new Error('PERSONAL_INSTRUCTION_INVALID');
+    return normalized;
+}

package/dist/util/runner-native-session-parsers.d.ts

@@ -15,12 +15,14 @@ export interface ConversationHistoryPage {
     readonly source: ConversationHistorySource;
     readonly readAt: number;
     readonly latestVisibleAt: number;
+    readonly deferredOlderHistory?: boolean;
 }
 export declare function extractId(result: unknown, key: 'thread' | 'turn'): string;
 export declare function settleWithin<T>(promise: Promise<T>, milliseconds: number): Promise<T | undefined>;
 export declare function extractCodexThreads(result: unknown): readonly {
     readonly id: string;
     readonly source: string | undefined;
+    readonly derived: boolean;
     readonly cwd: unknown;
     readonly title: string | undefined;
 }[];
@@ -50,7 +52,7 @@ export declare function nativeConversationPage(session: NodeAgentSession, histor
  */
 export declare function nativeUserClientMessageId(entry: Extract<NativeSessionHistory['items'][number], {
     readonly kind: 'message';
-}>, createdAt: number, runtimeTurns: readonly NodeConversationTurn[]): string | null;
+}>, createdAt: number | null, runtimeTurns: readonly NodeConversationTurn[]): string | null;
 /**
  * Normalize the documented App Server `thread/read(includeTurns: true)`
  * result.  Only items with a user-visible Workbench representation are kept;

package/dist/util/runner-native-session-parsers.js

@@ -49,12 +49,17 @@ export function extractCodexThreads(result) {
                     typeof value.source.kind === 'string'
                     ? value.source.kind
                     : undefined;
+        const sourceRecord = isPlainRecord(value.source) ? value.source : undefined;
+        const derived = source === 'subagent' ||
+            sourceRecord?.kind === 'subagent' ||
+            isPlainRecord(sourceRecord?.subagent) ||
+            isPlainRecord(sourceRecord?.subAgent);
         const title = typeof value.name === 'string' && value.name.trim().length > 0
             ? value.name.trim()
             : typeof value.preview === 'string' && value.preview.trim().length > 0
                 ? value.preview.trim()
                 : undefined;
-        return [{ id: value.id, source, cwd: value.cwd, title }];
+        return [{ id: value.id, source, derived, cwd: value.cwd, title }];
     });
 }
 export function codexThreadActivity(result) {
@@ -106,6 +111,8 @@ export function claudeDiscoveredSession(value, fallbackCwd) {
     if (typeof value !== 'object' || value === null)
         return undefined;
     const record = value;
+    if (record.isSidechain === true)
+        return undefined;
     const externalSessionId = typeof record.sessionId === 'string'
         ? record.sessionId
         : typeof record.id === 'string'
@@ -165,14 +172,18 @@ export function nativeConversationPage(session, history, input, runtimeTurns = [
         .slice(start, end)
         .map((entries, relativeIndex) => {
         const firstIndex = entries[0]?.index ?? 0;
-        const turnId = `${session.id}:native:${firstIndex}`;
-        const nativeItems = entries.map(({ entry, index }) => nativeTranscriptConversationItem(session, entry, index, turnId, runtimeTurns, registerImages));
-        const clientMessageId = nativeItems.flatMap((item) => item.kind === 'user_message' && isPlainRecord(item.payload)
-            ? [item.payload.clientMessageId]
-            : [])[0];
-        const runtimeTurn = typeof clientMessageId === 'string'
-            ? runtimeTurns.find((turn) => runtimeTurnClientMessageId(turn) === clientMessageId)
+        const nativeUser = entries.find(({ entry }) => entry.kind === 'message' && entry.role === 'USER')?.entry;
+        const matchedClientMessageId = nativeUser?.kind === 'message'
+            ? nativeUserClientMessageId(nativeUser, nativeUser.createdAt, runtimeTurns)
+            : null;
+        const runtimeTurn = typeof matchedClientMessageId === 'string'
+            ? runtimeTurns.find((turn) => runtimeTurnClientMessageId(turn) === matchedClientMessageId)
             : undefined;
+        const turnId = runtimeTurn?.id ?? `${session.id}:native:${firstIndex}`;
+        const nativeItems = entries.map(({ entry, index }) => ({
+            ...nativeTranscriptConversationItem(session, entry, index, turnId, runtimeTurns, registerImages),
+            runId: runtimeTurn?.runId ?? null
+        }));
         const runtimeErrors = (runtimeTurn?.items ?? [])
             .filter((item) => item.kind === 'error')
             .map((item) => ({ ...item, turnId, runId: runtimeTurn?.runId ?? null }));
@@ -180,7 +191,7 @@ export function nativeConversationPage(session, history, input, runtimeTurns = [
             ...nativeItems,
             ...runtimeErrors.filter((error) => !nativeItems.some((item) => item.id === error.id))
         ];
-        const startedAt = items[0]?.startedAt ?? firstIndex;
+        const startedAt = items[0]?.startedAt ?? null;
         const completedAt = items.at(-1)?.completedAt ?? startedAt;
         const after = lastNativeItemId(entries);
         return {
@@ -205,7 +216,7 @@ export function nativeConversationPage(session, history, input, runtimeTurns = [
             completedAt
         };
     });
-    const combined = [...nativePageTurns, ...missingRuntimeErrorTurns].sort((left, right) => (left.startedAt ?? 0) - (right.startedAt ?? 0));
+    const combined = [...nativePageTurns, ...missingRuntimeErrorTurns];
     const dropped = combined.slice(0, Math.max(0, combined.length - limit));
     const turns = combined.slice(-limit);
     const nativePageIds = new Set(nativePageTurns.map((turn) => turn.id));
@@ -241,7 +252,7 @@ function nativeTranscriptTurns(items) {
     return turns;
 }
 function nativeTranscriptConversationItem(session, entry, index, turnId, runtimeTurns, registerImages) {
-    const time = entry.createdAt ?? index;
+    const time = entry.createdAt;
     const isToolCall = entry.kind === 'tool_call';
     const isUnknown = entry.kind === 'unknown';
     const isReasoning = entry.kind === 'reasoning_summary';
@@ -336,6 +347,7 @@ function nativeTranscriptConversationItem(session, entry, index, turnId, runtime
  * runtime user messages by content and creation time so native history replaces the optimistic Turn.
  */
 export function nativeUserClientMessageId(entry, createdAt, runtimeTurns) {
+    const candidates = [];
     for (const turn of runtimeTurns) {
         const user = turn.items.find((item) => item.kind === 'user_message');
         if (user === undefined || !isPlainRecord(user.payload))
@@ -346,13 +358,19 @@ export function nativeUserClientMessageId(entry, createdAt, runtimeTurns) {
         if (clientMessageId === null || payload.text !== stripClaudePlanTag(entry.text))
             continue;
         const runtimeCreatedAt = user.startedAt ?? turn.startedAt;
-        if (runtimeCreatedAt !== null &&
-            runtimeCreatedAt !== undefined &&
-            Math.abs(createdAt - runtimeCreatedAt) > 60_000)
-            continue;
-        return clientMessageId;
+        candidates.push({ clientMessageId, createdAt: runtimeCreatedAt ?? null });
     }
-    return null;
+    if (createdAt === null)
+        return candidates.length === 1 ? candidates[0].clientMessageId : null;
+    const timed = candidates
+        .filter((candidate) => candidate.createdAt !== null)
+        .map((candidate) => ({
+        ...candidate,
+        distance: Math.abs(createdAt - candidate.createdAt)
+    }))
+        .filter((candidate) => candidate.distance <= 60_000)
+        .sort((left, right) => left.distance - right.distance);
+    return timed[0]?.clientMessageId ?? null;
 }
 /**
  * Normalize the documented App Server `thread/read(includeTurns: true)`

package/dist/workspace.d.ts

@@ -111,6 +111,13 @@ export declare function readWorkspaceTextFile(workspaceRoot: string, requestedPa
     readonly truncated: boolean;
     readonly nextOffset: number | null;
 }>;
+export declare function readWorkspaceFileContentRange(workspaceRoot: string, requestedPath: string, offset?: number, limit?: number): Promise<{
+    readonly path: string;
+    readonly size: number;
+    readonly offset: number;
+    readonly contentBase64: string;
+    readonly nextOffset: number | null;
+}>;
 /** Reads one absolute file only when the resolved target remains within a Node allowed root. */
 export declare function readAllowedTextFile(requestedPath: string, allowedRoots: readonly string[], offset?: number, limit?: number): Promise<{
     readonly path: string;
@@ -177,8 +184,13 @@ export declare function readGitHistoryFileDiff(repository: string, commit: strin
     readonly text?: string;
     readonly summary?: string;
     readonly truncated: boolean;
-    readonly beforePreview?: BinaryDiffPreview;
-    readonly afterPreview?: BinaryDiffPreview;
+}>;
+export declare function readGitHistoryFileContentRange(repository: string, commit: string, requestedPath: string, offset: number, limit: number, refs?: readonly string[]): Promise<{
+    readonly path: string;
+    readonly size: number;
+    readonly offset: number;
+    readonly contentBase64: string;
+    readonly nextOffset: number | null;
 }>;
 export declare function readCurrentChanges(workspacePath: string): Promise<readonly {
     readonly path: string;
@@ -192,15 +204,9 @@ export declare function readCurrentChangeDiff(workspacePath: string, requestedPa
     readonly truncated: boolean;
     readonly afterText?: string;
     readonly afterTruncated?: boolean;
-    readonly beforePreview?: BinaryDiffPreview;
-    readonly afterPreview?: BinaryDiffPreview;
 }>;
 /** Current Changes must not expose an external link. */
 export declare function isWorkspaceChangeVisible(workspacePath: string, requestedPath: string): Promise<boolean>;
-interface BinaryDiffPreview {
-    readonly contentBase64?: string;
-    readonly truncated: boolean;
-}
 export declare function restoreCurrentChange(workspacePath: string, requestedPath: string, state: 'STAGED' | 'UNSTAGED' | 'UNTRACKED'): Promise<void>;
 declare function gitChange(status: string): 'ADDED' | 'MODIFIED' | 'DELETED' | 'RENAMED' | 'COPIED' | 'TYPE_CHANGED';
 export declare class GitCommandError extends Error {