Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 163 additions & 0 deletions backend/chat/message-pages.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
/**
* Paging a chat's active branch: pages start at a turn so no turn is split,
* consecutive pages cover the branch exactly once, and the prompt index and
* task history cover what is not loaded.
*/

import { describe, it, expect, beforeAll, afterAll } from 'bun:test';
import { initializeDatabase, closeDatabase } from '$backend/database';
import { messageQueries, projectQueries, sessionQueries } from '$backend/database/queries';
import type { UnifiedMessage } from '$shared/types/unified';

import { getMessagePage, getPromptIndex, getTaskHistory } from './message-pages';

let projectId: string;
const engine = { type: 'claude-code', provider: '', model: { id: '', name: '' }, account: { id: 0, name: '' } };
const base = { createdAt: '2026-11-17T00:00:00.000Z', sessionId: null, engine };

const prompt = (text: string) =>
({ ...base, type: 'user', parent: { messageId: null, sessionId: null, toolUseId: null }, content: [{ type: 'text', text }] }) as unknown as UnifiedMessage;
const toolCall = (id: string, name = 'Read', input: unknown = {}) =>
({ ...base, type: 'assistant', parent: { messageId: null, sessionId: null, toolUseId: null }, content: [{ type: 'tool_use', id, name, input }] }) as unknown as UnifiedMessage;
const toolResult = (toolUseId: string, content = 'ok') =>
({ ...base, type: 'user', parent: { messageId: null, sessionId: null, toolUseId: null }, content: [{ type: 'tool_result', toolUseId, content }] }) as unknown as UnifiedMessage;
const answer = (text: string) =>
({ ...base, type: 'assistant', parent: { messageId: null, sessionId: null, toolUseId: null }, content: [{ type: 'text', text }] }) as unknown as UnifiedMessage;

function newSession(): string {
return sessionQueries.create({ project_id: projectId, engine: 'claude-code', started_at: new Date().toISOString() } as never).id;
}

/** Build a branch of turns: each turn = prompt, N tool call/result pairs, answer. */
function buildBranch(sessionId: string, turns: number, toolsPerTurn: number): string[] {
const ids: string[] = [];
let parent: string | undefined;
const push = (message: UnifiedMessage) => {
const row = messageQueries.create({ session_id: sessionId, message, parent_message_id: parent });
parent = row.id;
ids.push(row.id);
sessionQueries.updateHead(sessionId, row.id);
};
for (let t = 0; t < turns; t++) {
push(prompt(`turn ${t}`));
for (let k = 0; k < toolsPerTurn; k++) {
push(toolCall(`call-${t}-${k}`));
push(toolResult(`call-${t}-${k}`));
}
push(answer(`done ${t}`));
}
return ids;
}

const textOf = (message: UnifiedMessage) =>
message.type === 'user' || message.type === 'assistant'
? (message.content.find((block) => block.type === 'text') as { text?: string } | undefined)?.text
: undefined;

beforeAll(async () => {
await initializeDatabase();
projectId = projectQueries.create({ name: 'message-pages', path: `/tmp/message-pages-${crypto.randomUUID()}`, created_at: new Date().toISOString(), last_opened_at: new Date().toISOString() } as never).id;
});

afterAll(() => {
sessionQueries.deleteAllByProjectId(projectId);
projectQueries.deleteProject(projectId);
closeDatabase();
});

describe('getMessagePage', () => {
it('never splits a tool call from its result, even inside a long turn', () => {
const session = newSession();
buildBranch(session, 2, 60); // two turns of 122 messages each

const page = getMessagePage(session, { minCount: 10 });
expect(page.messages.length).toBeLessThan(20); // cut inside the turn, not at its start
expect(page.hasMore).toBe(true);
const calls = new Set<string>();
for (const message of page.messages) {
if (message.type !== 'user' && message.type !== 'assistant') continue;
for (const block of message.content) {
if (block.type === 'tool_use') calls.add(block.id);
if (block.type === 'tool_result') expect(calls.has((block as { toolUseId: string }).toolUseId)).toBe(true);
}
}
});

it('does not begin a page with a synthetic message, nor split a sub-agent from its call', () => {
const session = newSession();
let parent: string | undefined;
const push = (message: UnifiedMessage) => {
const row = messageQueries.create({ session_id: session, message, parent_message_id: parent });
parent = row.id;
sessionQueries.updateHead(session, row.id);
};
push(prompt('start'));
push(toolCall('agent-1', 'Agent'));
push({ ...(prompt('sub-agent work') as object), parent: { messageId: null, sessionId: null, toolUseId: 'agent-1' } } as unknown as UnifiedMessage);
push({ ...(answer('sub-agent answer') as object), parent: { messageId: null, sessionId: null, toolUseId: 'agent-1' } } as unknown as UnifiedMessage);
push(toolResult('agent-1'));
push(toolCall('skill-1', 'Skill'));
push({ ...(prompt('expanded skill prompt') as object), synthetic: true } as unknown as UnifiedMessage);

const page = getMessagePage(session, { minCount: 1 });
expect((page.messages[0] as { synthetic?: boolean }).synthetic).not.toBe(true);
const texts = page.messages.map(textOf);
if (texts.includes('sub-agent work')) expect(page.messages.some((m) => JSON.stringify(m).includes('"id":"agent-1"'))).toBe(true);
});

it('pages back through the whole branch exactly once, in order', () => {
const session = newSession();
const ids = buildBranch(session, 12, 2);

const collected: string[] = [];
let before: string | undefined;
for (let guard = 0; guard < 50; guard++) {
const page = getMessagePage(session, { beforeId: before, minCount: 7 });
collected.unshift(...page.messages.map((message) => (message as { messageId: string }).messageId));
if (!page.hasMore) break;
before = (page.messages[0] as { messageId: string }).messageId;
}
expect(collected).toEqual(ids);
});

it('answers an empty page for a session with no messages, or an unknown cursor', () => {
const session = newSession();
expect(getMessagePage(session)).toEqual({ messages: [], hasMore: false });
buildBranch(session, 1, 0);
expect(getMessagePage(session, { beforeId: 'not-a-message' })).toEqual({ messages: [], hasMore: false });
});
});

describe('getPromptIndex', () => {
it('lists every real prompt on the branch, oldest first, with no tool results', () => {
const session = newSession();
buildBranch(session, 4, 2);
expect(getPromptIndex(session).map((entry) => entry.text)).toEqual(['turn 0', 'turn 1', 'turn 2', 'turn 3']);
});
});

describe('getTaskHistory', () => {
it('returns the task calls and their results older than a message, and nothing else', () => {
const session = newSession();
let parent: string | undefined;
const push = (message: UnifiedMessage) => {
const row = messageQueries.create({ session_id: session, message, parent_message_id: parent });
parent = row.id;
sessionQueries.updateHead(session, row.id);
return row.id;
};
push(prompt('plan'));
push(toolCall('task-1', 'TaskCreate', { subject: 'Write tests' }));
push(toolResult('task-1', 'Task #1 created'));
push(toolCall('read-1', 'Read'));
push(toolResult('read-1', 'file body'));
const later = push(prompt('next'));
push(toolCall('task-2', 'TaskUpdate', { taskId: '1', status: 'completed' }));

const history = getTaskHistory(session, later);
expect(history.map((message) => message.type)).toEqual(['assistant', 'user']);
expect(JSON.stringify(history)).toContain('task-1');
expect(JSON.stringify(history)).not.toContain('read-1');
expect(JSON.stringify(history)).not.toContain('task-2'); // newer than the cursor
});
});
233 changes: 233 additions & 0 deletions backend/chat/message-pages.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,233 @@
/**
* Reading a chat's active branch a page at a time.
*
* Opening a chat used to send its whole branch — every message since the first,
* images included — which on a long chat was tens of megabytes on every open.
* The chat now loads its most recent turns and fetches older ones as the user
* scrolls up (or jumps to a message that is not loaded yet).
*
* A page never starts where it would split something the chat renders as one:
* every tool result and every sub-agent message in it has its tool call in the
* same page, and it does not begin with a synthetic user message (a compaction
* summary or an expanded skill prompt, which belong to the message before
* them). That is checked on the page itself, so a boundary can fall inside a
* long agent turn — turns of several hundred messages are common, and cutting
* only at user prompts made the first page nearly the whole chat. A user
* prompt always qualifies.
*
* Two things the chat needs from the WHOLE branch are served separately and
* cheaply, without message bodies the user is not looking at:
* - the prompt index (the navigation rail's dots, one per user prompt);
* - the task tools older than the loaded page (the task progress widget
* replays TaskCreate / TaskUpdate / TodoWrite from the start).
*/

import { getDatabase } from '../database';
import type { DatabaseMessage } from '$shared/types/database/schema';
import type { UnifiedMessage } from '$shared/types/unified';
import { trimSubAgentForWire } from '$shared/utils/subagent-wire-trim';
import { isCheckpointMessage, extractMessageText } from '../snapshot/helpers';

/**
* Walks a branch from newest to oldest and says where a page may begin: at a
* message no later message depends on from across the boundary.
*/
class BoundaryTracker {
private readonly defined = new Set<string>();
private readonly needed = new Set<string>();

/** Record `message` (older than everything seen so far); true if a page may start at it. */
add(message: UnifiedMessage): boolean {
if (message.type === 'user' || message.type === 'assistant') {
const parentToolUseId = message.parent?.toolUseId;
if (parentToolUseId && !this.defined.has(parentToolUseId)) this.needed.add(parentToolUseId);
for (const block of message.content) {
if (block.type === 'tool_result') {
const id = (block as { toolUseId?: string }).toolUseId;
if (id && !this.defined.has(id)) this.needed.add(id);
} else if (block.type === 'tool_use') {
this.defined.add(block.id);
this.needed.delete(block.id);
}
}
}
const synthetic = message.type === 'user' && (message as { synthetic?: boolean }).synthetic === true;
return this.needed.size === 0 && !synthetic;
}
}

/** Messages a page holds at least — then it is extended back to the start of a turn. */
export const DEFAULT_PAGE_SIZE = 80;

/** Longest prompt preview the navigation rail shows. */
const PROMPT_PREVIEW_LENGTH = 200;

/** Tools the task progress widget replays. */
const TASK_TOOLS = ['TaskCreate', 'TaskUpdate', 'TodoWrite'] as const;

export interface MessagePage {
/** Oldest first, as the chat renders them. */
messages: UnifiedMessage[];
/** Whether older messages exist on the branch before this page. */
hasMore: boolean;
}

export interface PromptIndexEntry {
messageId: string;
text: string;
createdAt: string;
}

function headOf(sessionId: string): string | null {
const row = getDatabase()
.prepare('SELECT head_message_id FROM chat_sessions WHERE id = ?')
.get(sessionId) as { head_message_id: string | null } | null;
return row?.head_message_id ?? null;
}

/**
* One page of the active branch, ending just before `beforeId` (or at the head
* when absent). Holds at least `minCount` messages and always begins at a turn.
*/
export function getMessagePage(
sessionId: string,
options: { beforeId?: string; minCount?: number } = {}
): MessagePage {
const minCount = Math.max(1, options.minCount ?? DEFAULT_PAGE_SIZE);
const byId = getDatabase().prepare('SELECT * FROM messages WHERE id = ? AND session_id = ?');

let cursor: string | null;
if (options.beforeId) {
const anchor = byId.get(options.beforeId, sessionId) as DatabaseMessage | null;
if (!anchor) return { messages: [], hasMore: false };
cursor = anchor.parent_message_id ?? null;
} else {
cursor = headOf(sessionId);
}

const messages: UnifiedMessage[] = [];
const boundary = new BoundaryTracker();
while (cursor) {
const row = byId.get(cursor, sessionId) as DatabaseMessage | null;
if (!row) {
cursor = null;
break;
}
const message = JSON.parse(row.data) as UnifiedMessage;
messages.push(message);
cursor = row.parent_message_id ?? null;
const mayStartHere = boundary.add(message);
if (messages.length >= minCount && mayStartHere) break;
}

return {
messages: messages.reverse().map(trimSubAgentForWire),
hasMore: cursor !== null && byId.get(cursor, sessionId) != null
};
}

/**
* The branch, newest first, as light rows: id and parent for every message,
* plus the body only where `wantBody` says so (decided in SQL, so the bodies
* of everything else — tool output, images — are never read into JS).
*/
function branchRows(
sessionId: string,
wantBody: string,
fromId: string | null
): Array<{ id: string; parent_message_id: string | null; data: string | null }> {
if (!fromId) return [];
const rows = getDatabase()
.prepare(`SELECT id, parent_message_id, CASE WHEN ${wantBody} THEN data END AS data FROM messages WHERE session_id = ?`)
.all(sessionId) as Array<{ id: string; parent_message_id: string | null; data: string | null }>;
const byId = new Map(rows.map((row) => [row.id, row]));

const branch: typeof rows = [];
const seen = new Set<string>();
let cursor: string | null = fromId;
while (cursor && !seen.has(cursor)) {
seen.add(cursor);
const row = byId.get(cursor);
if (!row) break;
branch.push(row);
cursor = row.parent_message_id;
}
return branch;
}

/** Every user prompt on the active branch, oldest first — the navigation rail. */
export function getPromptIndex(sessionId: string): PromptIndexEntry[] {
const rows = branchRows(sessionId, `json_extract(data, '$.type') = 'user'`, headOf(sessionId));
const prompts: PromptIndexEntry[] = [];
for (let i = rows.length - 1; i >= 0; i--) {
const row = rows[i];
if (!row.data) continue;
const asRow = row as unknown as DatabaseMessage;
if (!isCheckpointMessage(asRow)) continue;
const message = JSON.parse(row.data) as UnifiedMessage;
prompts.push({
messageId: row.id,
text: extractMessageText(message).slice(0, PROMPT_PREVIEW_LENGTH),
createdAt: (message as { createdAt?: string }).createdAt ?? ''
});
}
return prompts;
}

/**
* The task-tool calls (and their results) on the branch older than `beforeId`,
* oldest first. Together with the loaded messages this is exactly what the task
* widget used to replay from the full branch.
*/
export function getTaskHistory(sessionId: string, beforeId: string): UnifiedMessage[] {
const parent = getDatabase()
.prepare('SELECT parent_message_id FROM messages WHERE id = ? AND session_id = ?')
.get(beforeId, sessionId) as { parent_message_id: string | null } | null;
if (!parent?.parent_message_id) return [];

// Pass 1: the branch, with bodies only for messages that call a task tool.
const mentionsTaskTool = TASK_TOOLS.map((name) => `instr(data, '"name":"${name}"') > 0`).join(' OR ');
const branch = branchRows(sessionId, mentionsTaskTool, parent.parent_message_id).reverse();

const taskCallIds = new Set<string>();
const calls = new Map<string, UnifiedMessage>();
for (const row of branch) {
if (!row.data) continue;
const message = JSON.parse(row.data) as UnifiedMessage;
if (message.type !== 'assistant') continue;
let hasTaskCall = false;
for (const block of message.content) {
if (block.type === 'tool_use' && (TASK_TOOLS as readonly string[]).includes(block.name)) {
taskCallIds.add(block.id);
hasTaskCall = true;
}
}
if (hasTaskCall) calls.set(row.id, message);
}
if (taskCallIds.size === 0) return [];

// Pass 2: only the messages that answer one of those calls — never the
// thousands of other tool results (file reads, screenshots) on the branch.
const ids = [...taskCallIds];
const answerRows = getDatabase()
.prepare(
`SELECT id, data FROM messages WHERE session_id = ? AND (${ids.map(() => 'instr(data, ?) > 0').join(' OR ')})`
)
.all(sessionId, ...ids.map((id) => `"toolUseId":"${id}"`)) as Array<{ id: string; data: string }>;
const answers = new Map<string, UnifiedMessage>();
for (const row of answerRows) {
const message = JSON.parse(row.data) as UnifiedMessage;
if (message.type !== 'user') continue;
const answersTask = message.content.some(
(block) => block.type === 'tool_result' && taskCallIds.has((block as { toolUseId: string }).toolUseId)
);
if (answersTask) answers.set(row.id, message);
}

const history: UnifiedMessage[] = [];
for (const row of branch) {
const message = calls.get(row.id) ?? answers.get(row.id);
if (message) history.push(message);
}
return history;
}
Loading
Loading