The open-source agent harness - the runtime layer that turns an LLM into a working agent.
import type { AppendMessage } from '@assistant-ui/core';
import { describe, expect, it, vi } from 'vitest';
import type {
AgentChatServer,
ModelMessageEvent,
SandboxCreatedEvent,
SessionEventItem,
ThreadCreatedEvent,
ToolApprovalRequiredEvent,
ToolResponseRequiredEvent,
Turn,
TurnDoneEvent,
TurnEvent,
TurnStreamData,
} from '../src/server/index.js';
import { collectPendingToolResponses } from '../src/collectPending.js';
import { ROOT_THREAD_ID } from '../src/constants.js';
import {
buildSnapshotFromSessionEvents,
buildSnapshotThroughTurn,
buildTurnAssistantContent,
buildUserMessageContent,
buildUserMessageFromTurnInput,
convertTurnsToThreadMessages,
getTurnMessageContent,
prependOlderSessionHistory,
projectSessionMessages,
repositoryItemsFromMessages,
resolveGatewayBranchPreviousTurnIdForTurn,
rootModelMessageIdsSinceBaseline,
streamTurnEvents,
TurnStreamDisconnectedError,
turnStreamUpdateToAssistantMessage,
} from '../src/convertTurnMessages.js';
import { buildRootAssistantContent, ingestTurnEvent, PeerThreadFoldState } from '../src/foldPeerThreads.js';
import { findCurrentPausedAssistantMessage } from '../src/requiredActionInputs.js';
import {
createEmptySessionSnapshot,
replaceSessionSnapshot,
type SessionSnapshot,
turnToSessionRecord,
} from '../src/sessionSnapshot.js';
import { TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY } from '../src/toolApproval.js';
import {
applyUserToolResponsesToFold,
TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY,
toolResponseStatus,
} from '../src/toolResponse.js';
import type { TurnStreamUpdate } from '../src/turnStreamUpdate.js';
const createdAt = new Date().toISOString();
const SESSION_ID = 'session-1';
type TurnFixture = Turn & { events: TurnEvent[] };
function modelMessage(event: Omit<ModelMessageEvent, 'type' | 'createdAt'>): ModelMessageEvent {
return { type: 'model.message', createdAt, ...event };
}
function approvalRequired(event: Omit<ToolApprovalRequiredEvent, 'type' | 'createdAt'>): ToolApprovalRequiredEvent {
return { type: 'tool.approval_required', createdAt, ...event };
}
function threadCreated(event: Omit<ThreadCreatedEvent, 'type' | 'createdAt'>): ThreadCreatedEvent {
return { type: 'thread.created', createdAt, ...event };
}
function sandboxCreated(event: { id: string; sandboxId: string; threadId?: string | null }): SandboxCreatedEvent {
return {
type: 'sandbox.created',
createdAt,
threadId: event.threadId ?? null,
id: event.id,
sandboxId: event.sandboxId,
};
}
function responseRequired(event: Omit<ToolResponseRequiredEvent, 'type' | 'createdAt'>): ToolResponseRequiredEvent {
return { type: 'tool.response_required', createdAt, ...event };
}
function turnDone(id = 'turn-done'): TurnDoneEvent {
return {
type: 'turn.done',
id,
createdAt,
state: { status: 'done', requiredActions: [], completedAt: createdAt },
};
}
async function* streamFrom(events: TurnStreamData['event'][]): AsyncGenerator<TurnStreamData> {
for (const [index, event] of events.entries()) {
yield { sequenceNumber: index + 1, event };
}
}
function appendUserMessage(
content: AppendMessage['content'],
attachments: AppendMessage['attachments'] = [],
): AppendMessage {
return {
role: 'user',
content,
attachments,
createdAt: new Date(),
metadata: { custom: {} },
parentId: null,
sourceId: null,
runConfig: undefined,
};
}
function mockTurn(
overrides: Partial<Turn> &
Pick<Turn, 'id' | 'createdAt'> & {
events?: TurnEvent[];
},
): TurnFixture {
const {
events = [
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'assistant reply',
}),
],
...rest
} = overrides;
return {
sessionId: SESSION_ID,
input: [{ type: 'user.message', content: 'hello' }],
state: { status: 'done', requiredActions: [], completedAt: createdAt },
...rest,
events,
};
}
/** Mirror runtime listTurns normalization: ASC stays, DESC (or tied) reverses. */
function toOldestFirstTurns(turns: TurnFixture[]): TurnFixture[] {
const chain = turns.filter(turn => turn.state.status !== 'running');
let newestFirst = chain.length > 1;
for (let i = 1; i < chain.length; i++) {
const newer = chain[i];
const older = chain[i - 1];
if (newer == null || older == null) {
continue;
}
const delta = Date.parse(newer.createdAt) - Date.parse(older.createdAt);
if (delta < 0) {
newestFirst = true;
break;
}
if (delta > 0) {
newestFirst = false;
break;
}
}
return newestFirst ? [...chain].reverse() : [...chain];
}
/** Mirrors the host's ancestor walk: parent pointers only, sibling branches excluded. */
function ancestorChainFromTurns(turns: TurnFixture[], anchorTurnId: string): TurnFixture[] {
const turnsById = new Map(turns.map(turn => [turn.id, turn]));
const chain: TurnFixture[] = [];
const seen = new Set<string>();
let cursor: string | null | undefined = anchorTurnId;
while (cursor != null && !seen.has(cursor)) {
seen.add(cursor);
const turn = turnsById.get(cursor);
if (turn == null) {
break;
}
if (turn.state.status !== 'running') {
chain.unshift(turn);
}
cursor = turn.previousTurnId;
}
return chain;
}
function turnCreatedItem(turn: TurnFixture): SessionEventItem {
return {
turnId: turn.id,
event: {
type: 'turn.created',
id: `created-${turn.id}`,
turnId: turn.id,
...(turn.input === undefined ? {} : { input: turn.input }),
state: { status: 'running' },
createdAt: turn.createdAt,
...(turn.previousTurnId === undefined ? {} : { previousTurnId: turn.previousTurnId }),
},
};
}
/**
* Builds session-level event items from per-turn mocks — accepts ASC or DESC
* listTurns order. Finished turns include `turn.done`. A running tip is an open
* `turn.created` without its content events, which `listTurnEvents` supplies.
* An anchor selects that turn's ancestor chain, not a chronological prefix.
*/
function sessionEventItemsFromTurns(turns: TurnFixture[], lastTurnId?: string): SessionEventItem[] {
const chain = lastTurnId == null ? toOldestFirstTurns(turns) : ancestorChainFromTurns(turns, lastTurnId);
const items: SessionEventItem[] = [];
for (const turn of chain) {
items.push(turnCreatedItem(turn));
for (const event of turn.events) {
items.push({ turnId: turn.id, event });
}
items.push({
turnId: turn.id,
event: {
type: 'turn.done',
id: `done-${turn.id}`,
state: turn.state as TurnDoneEvent['state'],
createdAt: turn.createdAt,
},
});
}
if (lastTurnId == null) {
for (const turn of turns) {
if (turn.state.status !== 'running' || chain.some(done => done.id === turn.id)) {
continue;
}
// Open tip only. Content stays on listTurnEvents so convertTurnsToThreadMessages
// attributes it once when it hydrates the running turn.
items.push(turnCreatedItem(turn));
}
}
return items;
}
function mockServerWithTurns(turns: TurnFixture[]): AgentChatServer {
const eventsByTurnId = new Map(turns.map(turn => [turn.id, turn.events]));
const turnsById = new Map(turns.map(turn => [turn.id, turn]));
return {
listTurns: async ({ limit }: { limit?: number } = {}) => ({
data: limit != null ? turns.slice(0, limit) : turns,
}),
getTurn: async ({ turnId }: { turnId: string }) => {
const turn = turnsById.get(turnId);
if (turn == null) {
throw new Error(`Turn ${turnId} not found`);
}
return turn;
},
listEvents: async (opts: { lastTurnId?: string } = {}) => {
const items = sessionEventItemsFromTurns(turns, opts.lastTurnId);
const newestFirst = [...items].reverse();
return { data: newestFirst };
},
listTurnEvents: async ({ turnId }: { turnId: string }) => ({
data: eventsByTurnId.get(turnId) ?? [],
}),
} as unknown as AgentChatServer;
}
async function collectStream<T>(stream: AsyncGenerator<T>): Promise<T[]> {
const items: T[] = [];
for await (const item of stream) {
items.push(item);
}
return items;
}
describe('convertTurnMessages', () => {
describe('getTurnMessageContent', () => {
it('joins text parts from append message content', () => {
expect(
getTurnMessageContent(
appendUserMessage([
{ type: 'text', text: 'line one' },
{ type: 'text', text: 'line two' },
]),
),
).toBe('line one\nline two');
});
it('throws when no text content is present', () => {
expect(() => getTurnMessageContent(appendUserMessage([]))).toThrow('User message must contain text content.');
});
});
describe('buildUserMessageContent', () => {
it('returns a bare string for text-only messages', () => {
expect(buildUserMessageContent(appendUserMessage([{ type: 'text', text: 'hello there' }]))).toBe('hello there');
});
it('forwards file attachments as gateway file parts', () => {
expect(
buildUserMessageContent(
appendUserMessage(
[{ type: 'text', text: 'see attached' }],
[
{
id: 'att-1',
type: 'file',
name: 'doc.pdf',
contentType: 'application/pdf',
status: { type: 'complete' },
content: [
{
type: 'file',
mimeType: 'application/pdf',
data: 'JVBERi0xLjQK',
},
],
},
],
),
),
).toEqual([
{ type: 'text', text: 'see attached' },
{
type: 'file',
name: 'doc.pdf',
data: 'data:application/pdf;base64,JVBERi0xLjQK',
},
]);
});
it('forwards attachments without requiring text', () => {
expect(
buildUserMessageContent(
appendUserMessage(
[],
[
{
id: 'att-1',
type: 'file',
name: 'doc.pdf',
contentType: 'application/pdf',
status: { type: 'complete' },
content: [
{
type: 'file',
mimeType: 'application/pdf',
data: 'JVBERi0xLjQK',
},
],
},
],
),
),
).toEqual([
{
type: 'file',
name: 'doc.pdf',
data: 'data:application/pdf;base64,JVBERi0xLjQK',
},
]);
});
it('passes through data URIs unchanged', () => {
const dataUri = 'data:application/pdf;base64,JVBERi0xLjQK';
expect(
buildUserMessageContent(
appendUserMessage(
[{ type: 'text', text: 'file' }],
[
{
id: 'att-1',
type: 'file',
name: 'doc.pdf',
contentType: 'application/pdf',
status: { type: 'complete' },
content: [
{
type: 'file',
mimeType: 'application/pdf',
data: dataUri,
},
],
},
],
),
),
).toEqual([
{ type: 'text', text: 'file' },
{
type: 'file',
name: 'doc.pdf',
data: dataUri,
},
]);
});
it('maps image parts to gateway file parts', () => {
expect(
buildUserMessageContent(
appendUserMessage(
[{ type: 'text', text: 'image' }],
[
{
id: 'att-1',
type: 'image',
name: 'photo.png',
contentType: 'image/png',
status: { type: 'complete' },
content: [
{
type: 'image',
image: 'data:image/png;base64,AAAA',
},
],
},
],
),
),
).toEqual([
{ type: 'text', text: 'image' },
{
type: 'file',
name: 'photo.png',
data: 'data:image/png;base64,AAAA',
},
]);
});
it('includes file parts from message content and attachments', () => {
expect(
buildUserMessageContent(
appendUserMessage(
[
{ type: 'text', text: 'inline' },
{
type: 'file',
mimeType: 'application/pdf',
data: 'AAAA',
filename: 'inline.pdf',
},
],
[
{
id: 'att-1',
type: 'file',
name: 'attached.pdf',
contentType: 'application/pdf',
status: { type: 'complete' },
content: [
{
type: 'file',
mimeType: 'application/pdf',
data: 'BBBB',
},
],
},
],
),
),
).toEqual([
{ type: 'text', text: 'inline' },
{
type: 'file',
name: 'inline.pdf',
data: 'data:application/pdf;base64,AAAA',
},
{
type: 'file',
name: 'attached.pdf',
data: 'data:application/pdf;base64,BBBB',
},
]);
});
});
describe('buildUserMessageFromTurnInput', () => {
it('maps gateway file parts to assistant-ui attachments', () => {
const message = buildUserMessageFromTurnInput(
'turn-1',
[
{
type: 'user.message',
content: [
{ type: 'text', text: 'see attached' },
{
type: 'file',
name: 'doc.pdf',
data: 'data:application/pdf;base64,JVBERi0xLjQK',
},
],
},
],
createdAt,
);
expect(message.role).toBe('user');
expect(message.content).toEqual([{ type: 'text', text: 'see attached' }]);
if (message.role !== 'user') {
return;
}
expect(message.attachments).toHaveLength(1);
expect(message.attachments[0]?.name).toBe('doc.pdf');
});
it('maps gateway image_url parts to assistant-ui image attachments', () => {
const message = buildUserMessageFromTurnInput(
'turn-1',
[
{
type: 'user.message',
content: [
{ type: 'text', text: 'see attached' },
{
type: 'image_url',
image_url: {
url: 'data:image/jpeg;base64,/9j/4AAQ',
},
},
] as never,
},
],
createdAt,
);
if (message.role !== 'user') {
throw new Error('expected user message');
}
expect(message.attachments).toHaveLength(1);
expect(message.attachments[0]?.type).toBe('image');
expect(message.attachments[0]?.content[0]).toMatchObject({
type: 'image',
image: 'data:image/jpeg;base64,/9j/4AAQ',
});
});
});
describe('turnStreamUpdateToAssistantMessage', () => {
it('creates a new assistant message when none exists', () => {
const message = turnStreamUpdateToAssistantMessage('turn-1', {
content: [{ type: 'text', text: 'hi' }],
});
expect(message.id).toBe('turn-1-assistant');
expect(message.role).toBe('assistant');
expect(message.status).toEqual({ type: 'running' });
});
it('preserves the existing assistant message id on update', () => {
const existing = turnStreamUpdateToAssistantMessage('turn-1', {
content: [{ type: 'text', text: 'first' }],
});
const updated = turnStreamUpdateToAssistantMessage(
'turn-1',
{ content: [{ type: 'text', text: 'second' }] },
existing,
);
expect(updated.id).toBe(existing.id);
expect(updated.content).toEqual([{ type: 'text', text: 'second' }]);
});
it('stamps the streaming turn id onto the message metadata', () => {
const message = turnStreamUpdateToAssistantMessage('turn-1', {
content: [{ type: 'text', text: 'hi' }],
});
expect(message.metadata.custom['turnId']).toBe('turn-1');
});
it('advances the turn id when a continuation reuses the existing message', () => {
const existing = turnStreamUpdateToAssistantMessage('turn-1', {
content: [{ type: 'text', text: 'first' }],
metadata: { custom: { sandboxId: 'sbx-123' } },
});
const updated = turnStreamUpdateToAssistantMessage(
'turn-2',
{ content: [{ type: 'text', text: 'second' }] },
existing,
);
expect(updated.id).toBe('turn-1-assistant');
expect(updated.metadata.custom['turnId']).toBe('turn-2');
expect(updated.metadata.custom['sandboxId']).toBe('sbx-123');
});
});
describe('repositoryItemsFromMessages', () => {
it('chains parent ids in order', () => {
const userMessage = {
id: 'u1',
role: 'user' as const,
content: [{ type: 'text' as const, text: 'hi' }],
attachments: [],
createdAt: new Date(),
metadata: { custom: {} },
};
const assistant = turnStreamUpdateToAssistantMessage('t1', {
content: [{ type: 'text', text: 'a' }],
});
const items = repositoryItemsFromMessages([userMessage, assistant]);
expect(items).toEqual([
{ parentId: null, message: userMessage },
{ parentId: 'u1', message: assistant },
]);
});
});
describe('buildTurnAssistantContent', () => {
it('aggregates turn listEvents into root assistant content', async () => {
const turn = mockTurn({
id: 'turn-1',
createdAt,
});
const content = await buildTurnAssistantContent(mockServerWithTurns([turn]), SESSION_ID, turn);
expect(content).toEqual([{ type: 'text', text: 'assistant reply' }]);
});
});
describe('convertTurnsToThreadMessages', () => {
it('builds user and assistant messages from completed turns', async () => {
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([
mockTurn({
id: 'turn-1',
createdAt,
input: [{ type: 'user.message', content: 'hello' }],
}),
]),
SESSION_ID,
);
expect(result.messages).toHaveLength(2);
expect(result.messages[0]).toMatchObject({
id: 'turn-1-user',
role: 'user',
content: [{ type: 'text', text: 'hello' }],
});
expect(result.messages[1]).toMatchObject({
id: 'turn-1-assistant',
role: 'assistant',
content: [{ type: 'text', text: 'assistant reply' }],
status: { type: 'complete', reason: 'stop' },
});
expect(result.runningTurn).toBeUndefined();
});
it('emits an assistant row with cancellationReason for an empty cancelled turn', async () => {
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([
mockTurn({
id: 'turn-abandoned',
createdAt,
input: [{ type: 'user.message', content: 'give me a pdf' }],
state: { status: 'cancelled', reason: 'abandoned', completedAt: createdAt },
events: [],
}),
]),
SESSION_ID,
);
expect(result.messages).toHaveLength(2);
expect(result.messages[1]).toMatchObject({
id: 'turn-abandoned-assistant',
role: 'assistant',
content: [],
status: { type: 'incomplete', reason: 'cancelled' },
metadata: { custom: { cancellationReason: 'abandoned', turnId: 'turn-abandoned' } },
});
});
it('keeps model text and stamps cancellationReason on cancelled turns', async () => {
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([
mockTurn({
id: 'turn-cancel',
createdAt,
input: [{ type: 'user.message', content: 'hello' }],
state: { status: 'cancelled', reason: 'client-cancelled', completedAt: createdAt },
events: [
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'partial reply',
}),
],
}),
]),
SESSION_ID,
);
expect(result.messages[1]).toMatchObject({
role: 'assistant',
content: [{ type: 'text', text: 'partial reply' }],
status: { type: 'incomplete', reason: 'cancelled' },
metadata: { custom: { cancellationReason: 'client-cancelled', turnId: 'turn-cancel' } },
});
});
it('emits an assistant row for an empty error turn', async () => {
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([
mockTurn({
id: 'turn-error',
createdAt,
input: [{ type: 'user.message', content: 'hello' }],
state: { status: 'error', message: 'model failed', completedAt: createdAt },
events: [],
}),
]),
SESSION_ID,
);
expect(result.messages).toHaveLength(2);
expect(result.messages[1]).toMatchObject({
id: 'turn-error-assistant',
role: 'assistant',
content: [],
status: { type: 'incomplete', reason: 'error', error: 'model failed' },
});
});
it('marks unfinished nested sub-agent cancelled when parent turn.done is cancelled', async () => {
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([
mockTurn({
id: 'turn-cancel-sub',
createdAt,
input: [{ type: 'user.message', content: 'hunt' }],
state: { status: 'cancelled', reason: 'client-cancelled', completedAt: createdAt },
events: [
modelMessage({
id: 'root-msg',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'spawn-1',
type: 'function',
function: { name: 'create_sub_agent', arguments: '{}' },
toolInfo: { type: 'trueforge-system', name: 'create_sub_agent' },
},
],
}),
{
type: 'thread.created',
id: 't-created',
threadId: 'child-1',
title: 'finder',
createdAt,
agentInfo: { type: 'dynamic', name: 'finder', input: 'find' },
parent: { threadId: ROOT_THREAD_ID, toolCallId: 'spawn-1' },
},
modelMessage({
id: 'child-msg',
threadId: 'child-1',
content: 'still working',
}),
],
}),
]),
SESSION_ID,
);
const assistant = result.messages[1];
expect(assistant).toMatchObject({
role: 'assistant',
status: { type: 'incomplete', reason: 'cancelled' },
metadata: { custom: { cancellationReason: 'client-cancelled' } },
});
const spawn =
assistant?.role === 'assistant' ? assistant.content.find(part => part.type === 'tool-call') : undefined;
expect(spawn?.type).toBe('tool-call');
if (spawn?.type !== 'tool-call') return;
expect(spawn.messages?.[0]?.status).toEqual({ type: 'incomplete', reason: 'cancelled' });
});
it('marks abort-shaped nested thread.done error as cancelled when parent turn is cancelled', async () => {
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([
mockTurn({
id: 'turn-cancel-abort',
createdAt,
input: [{ type: 'user.message', content: 'hunt' }],
state: { status: 'cancelled', reason: 'client-cancelled', completedAt: createdAt },
events: [
modelMessage({
id: 'root-msg',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'spawn-1',
type: 'function',
function: { name: 'create_sub_agent', arguments: '{}' },
toolInfo: { type: 'trueforge-system', name: 'create_sub_agent' },
},
],
}),
{
type: 'thread.created',
id: 't-created',
threadId: 'child-1',
title: 'finder',
createdAt,
agentInfo: { type: 'dynamic', name: 'finder', input: 'find' },
parent: { threadId: ROOT_THREAD_ID, toolCallId: 'spawn-1' },
},
modelMessage({
id: 'child-msg',
threadId: 'child-1',
content: 'still working',
}),
{
type: 'thread.done',
id: 't-done',
threadId: 'child-1',
title: 'finder',
createdAt,
state: { status: 'error', error: 'LLM stream aborted' },
},
],
}),
]),
SESSION_ID,
);
const assistant = result.messages[1];
expect(assistant).toMatchObject({
role: 'assistant',
status: { type: 'incomplete', reason: 'cancelled' },
});
const spawn =
assistant?.role === 'assistant' ? assistant.content.find(part => part.type === 'tool-call') : undefined;
expect(spawn?.type).toBe('tool-call');
if (spawn?.type !== 'tool-call') return;
expect(spawn.messages?.[0]?.status).toEqual({ type: 'incomplete', reason: 'cancelled' });
});
it('carries sandboxId from a historical sandbox.created event onto the assistant message', async () => {
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([
mockTurn({
id: 'turn-1',
createdAt,
input: [{ type: 'user.message', content: 'hello' }],
events: [
sandboxCreated({ id: 'sandbox-evt', sandboxId: 'sbx-123' }),
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'assistant reply',
}),
],
}),
]),
SESSION_ID,
);
expect(result.messages[1]).toMatchObject({
role: 'assistant',
metadata: { custom: { sandboxId: 'sbx-123', turnId: 'turn-1' } },
});
});
it('stamps turnId without sandboxId when history omits sandbox.created (reused sandbox outside window)', async () => {
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([
mockTurn({
id: 'turn-tip',
createdAt,
input: [{ type: 'user.message', content: 'download please' }],
events: [
modelMessage({
id: 'm-tip',
threadId: ROOT_THREAD_ID,
content: 'here is the file',
}),
],
}),
]),
SESSION_ID,
);
expect(result.messages[1]).toMatchObject({
role: 'assistant',
metadata: { custom: { turnId: 'turn-tip' } },
});
expect((result.messages[1]?.metadata.custom as { sandboxId?: string }).sandboxId).toBeUndefined();
});
it('propagates sandboxId onto later turns that reuse the sandbox without emitting sandbox.created', async () => {
const createTurn = mockTurn({
id: 'turn-1',
createdAt: '2026-01-01T00:00:00.000Z',
previousTurnId: null,
input: [{ type: 'user.message', content: 'create file' }],
events: [
sandboxCreated({ id: 'sandbox-evt', sandboxId: 'sbx-123' }),
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'created',
}),
],
});
const reuseTurn = mockTurn({
id: 'turn-2',
createdAt: '2026-01-01T00:01:00.000Z',
previousTurnId: 'turn-1',
input: [{ type: 'user.message', content: 'download it' }],
events: [
modelMessage({
id: 'm2',
threadId: ROOT_THREAD_ID,
content: 'ready',
}),
],
});
// Newest-first listTurns order (tip first).
const result = await convertTurnsToThreadMessages(mockServerWithTurns([reuseTurn, createTurn]), SESSION_ID);
const tipAssistant = result.messages.find(
message => message.role === 'assistant' && (message.metadata.custom as { turnId?: string }).turnId === 'turn-2',
);
expect(tipAssistant).toMatchObject({
metadata: { custom: { sandboxId: 'sbx-123', turnId: 'turn-2' } },
});
});
it('returns runningTurn and unstable_resume for an in-flight turn', async () => {
const runningTurn = mockTurn({
id: 'turn-running',
createdAt,
state: { status: 'running' },
});
const result = await convertTurnsToThreadMessages(mockServerWithTurns([runningTurn]), SESSION_ID);
expect(result.runningTurn).toBe(runningTurn);
expect(result.unstable_resume).toBe(true);
expect(result.messages.at(-1)?.role).toBe('assistant');
});
it('merges continuation turns without user input into the last assistant message', async () => {
const firstTurn = mockTurn({
id: 'turn-1',
createdAt,
events: [
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'first chunk',
}),
],
});
const continuationTurn = mockTurn({
id: 'turn-2',
createdAt,
input: [
{ type: 'user.tool_approval', threadId: ROOT_THREAD_ID, toolCallId: 'tc-1', approval: { status: 'allow' } },
],
events: [
modelMessage({
id: 'm2',
threadId: ROOT_THREAD_ID,
content: ' after approval',
}),
],
});
const result = await convertTurnsToThreadMessages(mockServerWithTurns([continuationTurn, firstTurn]), SESSION_ID);
expect(result.messages).toHaveLength(2);
const assistant = result.messages[1];
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.content).toEqual([
{ type: 'text', text: 'first chunk' },
{ type: 'text', text: ' after approval' },
]);
// Artifacts on a merged message belong to the turn that wrote them last.
expect(assistant.metadata.custom['turnId']).toBe('turn-2');
});
it('keeps the sandboxId when an ask-user continuation is merged', async () => {
const firstTurn = mockTurn({
id: 'turn-1',
createdAt,
input: [{ type: 'user.message', content: 'create a file' }],
events: [
sandboxCreated({ id: 'sandbox-evt', sandboxId: 'sbx-123' }),
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'Which format?',
}),
],
});
const continuationTurn = mockTurn({
id: 'turn-2',
createdAt,
input: [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'ask-1',
content: 'Markdown',
},
],
events: [
modelMessage({
id: 'm2',
threadId: ROOT_THREAD_ID,
content: 'Done',
}),
],
});
const result = await convertTurnsToThreadMessages(mockServerWithTurns([continuationTurn, firstTurn]), SESSION_ID);
expect(result.messages[1]).toMatchObject({
role: 'assistant',
metadata: {
custom: {
sandboxId: 'sbx-123',
turnId: 'turn-2',
},
},
});
});
it('clears pendingMcpAuth when an MCP auth continuation is merged', async () => {
const mcpServers = [
{
id: 'github-auth',
name: 'github',
authUrl: 'https://example.com/auth',
},
];
const pausedTurn = mockTurn({
id: 'turn-1',
createdAt,
input: [{ type: 'user.message', content: 'use github' }],
state: {
status: 'done',
output: undefined,
requiredActions: [
{
type: 'mcp.auth_required',
id: 'mcp-auth',
createdAt,
mcpServers,
},
] as never,
completedAt: createdAt,
},
events: [
sandboxCreated({ id: 'sandbox-evt', sandboxId: 'sbx-123' }),
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'Need auth',
}),
{
type: 'mcp.auth_required',
id: 'mcp-auth',
createdAt,
mcpServers,
},
],
});
const continuationTurn = mockTurn({
id: 'turn-2',
createdAt,
input: [],
events: [
modelMessage({
id: 'm2',
threadId: ROOT_THREAD_ID,
content: 'Authorized',
}),
],
});
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([continuationTurn, pausedTurn]),
SESSION_ID,
);
const assistant = result.messages[1];
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.status).toEqual({ type: 'complete', reason: 'stop' });
expect(assistant.metadata.custom).toEqual({
sandboxId: 'sbx-123',
turnId: 'turn-2',
});
expect(assistant.metadata.custom['pendingMcpAuth']).toBeUndefined();
});
it('preserves requires-action on reload when a turn ends awaiting tool approval', async () => {
const pausedTurn = mockTurn({
id: 'turn-approval',
createdAt,
input: [{ type: 'user.message', content: 'run tool' }],
state: {
status: 'done',
output: undefined,
requiredActions: [
approvalRequired({
id: 'approval-event',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'approval-1', sourceEventId: 'm1' }],
}),
] as never,
completedAt: createdAt,
},
events: [
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'run tool',
toolCalls: [
{
id: 'approval-1',
type: 'function',
function: { name: 'bash', arguments: '{}' },
toolInfo: {
type: 'mcp',
name: 'bash',
serverId: 'bash-server',
serverName: 'bash',
},
},
],
}),
approvalRequired({
id: 'approval-event',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'approval-1', sourceEventId: 'm1' }],
}),
],
});
const result = await convertTurnsToThreadMessages(mockServerWithTurns([pausedTurn]), SESSION_ID);
expect(result.messages).toHaveLength(2);
const assistant = result.messages[1];
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.status).toEqual({
type: 'requires-action',
reason: 'tool-calls',
});
expect(assistant.metadata.custom[TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY]).toBe(ROOT_THREAD_ID);
expect(assistant.content.find(part => part.type === 'tool-call')).toMatchObject({
type: 'tool-call',
toolCallId: 'approval-1',
approval: { id: 'approval-1' },
});
expect(findCurrentPausedAssistantMessage(result.messages)).toBe(assistant);
});
it('downgrades to complete after a later turn submits user.tool_approval', async () => {
const pausedTurn = mockTurn({
id: 'turn-approval',
createdAt,
input: [{ type: 'user.message', content: 'run tool' }],
state: {
status: 'done',
output: undefined,
requiredActions: [
approvalRequired({
id: 'approval-event',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'approval-1', sourceEventId: 'm1' }],
}),
] as never,
completedAt: createdAt,
},
events: [
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'run tool',
toolCalls: [
{
id: 'approval-1',
type: 'function',
function: { name: 'bash', arguments: '{}' },
toolInfo: {
type: 'mcp',
name: 'bash',
serverId: 'bash-server',
serverName: 'bash',
},
},
],
}),
approvalRequired({
id: 'approval-event',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'approval-1', sourceEventId: 'm1' }],
}),
],
});
const continuationTurn = mockTurn({
id: 'turn-approval-resume',
createdAt,
input: [
{
type: 'user.tool_approval',
threadId: ROOT_THREAD_ID,
toolCallId: 'approval-1',
approval: { status: 'allow' },
},
],
events: [
modelMessage({
id: 'm2',
threadId: ROOT_THREAD_ID,
content: 'done',
}),
],
});
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([continuationTurn, pausedTurn]),
SESSION_ID,
);
const assistant = result.messages[1];
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.status).toEqual({ type: 'complete', reason: 'stop' });
expect(assistant.metadata.custom[TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY]).toBeUndefined();
const toolCall = assistant.content.find(part => part.type === 'tool-call');
expect(toolCall?.type).toBe('tool-call');
if (toolCall?.type !== 'tool-call') {
return;
}
expect(toolCall.approval?.approved).toBe(true);
});
it('preserves requires-action on reload when a turn ends awaiting tool response', async () => {
const pausedTurn = mockTurn({
id: 'turn-response',
createdAt,
input: [{ type: 'user.message', content: 'ask me' }],
state: {
status: 'done',
output: undefined,
requiredActions: [
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
] as never,
completedAt: createdAt,
},
events: [
modelMessage({
id: 'model-1',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'question-1',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'Pick one',
options: ['A', 'B'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
],
});
const result = await convertTurnsToThreadMessages(mockServerWithTurns([pausedTurn]), SESSION_ID);
const assistant = result.messages[1];
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.status).toEqual({
type: 'requires-action',
reason: 'tool-calls',
});
expect(assistant.metadata.custom[TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY]).toBe(ROOT_THREAD_ID);
expect(assistant.content[0]).toMatchObject({
type: 'tool-call',
toolCallId: 'question-1',
interrupt: {
type: 'human',
payload: { question: 'Pick one', options: ['A', 'B'] },
},
});
expect(findCurrentPausedAssistantMessage(result.messages)).toBe(assistant);
});
it('downgrades to complete after a later turn submits user.tool_response', async () => {
const pausedTurn = mockTurn({
id: 'turn-response',
createdAt,
input: [{ type: 'user.message', content: 'ask me' }],
state: {
status: 'done',
output: undefined,
requiredActions: [
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
] as never,
completedAt: createdAt,
},
events: [
modelMessage({
id: 'model-1',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'question-1',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'Pick one',
options: ['A', 'B'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
],
});
const continuationTurn = mockTurn({
id: 'turn-response-resume',
createdAt,
input: [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'question-1',
content: 'A',
},
],
events: [
modelMessage({
id: 'model-2',
threadId: ROOT_THREAD_ID,
content: 'Thanks',
}),
],
});
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([continuationTurn, pausedTurn]),
SESSION_ID,
);
const assistant = result.messages[1];
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.status).toEqual({ type: 'complete', reason: 'stop' });
expect(assistant.metadata.custom[TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY]).toBeUndefined();
const toolCall = assistant.content[0];
expect(toolCall?.type).toBe('tool-call');
if (toolCall?.type !== 'tool-call') {
return;
}
expect(toolCall.result).toBe('A');
});
it('scopes assistant content to each user turn group', async () => {
const helloTurn = mockTurn({
id: 'turn-hello',
createdAt,
input: [{ type: 'user.message', content: 'hello' }],
events: [
modelMessage({
id: 'm-hello',
threadId: ROOT_THREAD_ID,
content: 'Hello! How can I help?',
}),
],
});
const analyzeTurn = mockTurn({
id: 'turn-analyze',
createdAt,
input: [{ type: 'user.message', content: 'analyze' }],
events: [
modelMessage({
id: 'm-analyze',
threadId: ROOT_THREAD_ID,
content: 'Let me look at the file.',
}),
],
});
const ticketsTurn = mockTurn({
id: 'turn-tickets',
createdAt,
input: [
{
type: 'user.message',
content: 'create linear tickets',
},
],
events: [
modelMessage({
id: 'm-tickets',
threadId: ROOT_THREAD_ID,
content: 'Creating tickets now.',
}),
],
});
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([ticketsTurn, analyzeTurn, helloTurn]),
SESSION_ID,
);
expect(result.messages).toHaveLength(6);
expect(result.messages[1]).toMatchObject({
id: 'turn-hello-assistant',
role: 'assistant',
content: [{ type: 'text', text: 'Hello! How can I help?' }],
});
expect(result.messages[3]).toMatchObject({
id: 'turn-analyze-assistant',
role: 'assistant',
content: [{ type: 'text', text: 'Let me look at the file.' }],
});
expect(result.messages[5]).toMatchObject({
id: 'turn-tickets-assistant',
role: 'assistant',
content: [{ type: 'text', text: 'Creating tickets now.' }],
});
});
it('projects file attachments on user messages from turn input', async () => {
const fileData = 'data:text/x-python;base64,cHJpbnQoJ2hlbGxvJyk=';
const analyzeTurn = mockTurn({
id: 'turn-analyze',
createdAt,
input: [
{
type: 'user.message',
content: [
{ type: 'text', text: 'analyze' },
{ type: 'file', name: 'Untitled.py', data: fileData },
],
},
],
events: [
modelMessage({
id: 'm-analyze',
threadId: ROOT_THREAD_ID,
content: 'File analyzed.',
}),
],
});
const result = await convertTurnsToThreadMessages(mockServerWithTurns([analyzeTurn]), SESSION_ID);
expect(result.messages).toHaveLength(2);
expect(result.messages[0]).toMatchObject({
id: 'turn-analyze-user',
role: 'user',
content: [{ type: 'text', text: 'analyze' }],
});
if (result.messages[0]?.role !== 'user') {
return;
}
expect(result.messages[0].attachments).toHaveLength(1);
expect(result.messages[0].attachments[0]).toMatchObject({
type: 'file',
name: 'Untitled.py',
contentType: 'text/x-python',
status: { type: 'complete' },
content: [
{
type: 'file',
mimeType: 'text/x-python',
filename: 'Untitled.py',
data: fileData,
},
],
});
});
it('projects file-only turns and their assistant response', async () => {
const fileData = 'data:image/png;base64,AAAA';
const turn = mockTurn({
id: 'turn-image',
createdAt,
input: [
{
type: 'user.message',
content: [{ type: 'file', name: 'image.png', data: fileData }],
},
],
events: [
modelMessage({
id: 'm-image',
threadId: ROOT_THREAD_ID,
content: 'Image received.',
}),
],
});
const result = await convertTurnsToThreadMessages(mockServerWithTurns([turn]), SESSION_ID);
expect(result.messages).toHaveLength(2);
expect(result.messages[0]).toMatchObject({
id: 'turn-image-user',
role: 'user',
content: [{ type: 'text', text: '' }],
attachments: [{ name: 'image.png', status: { type: 'complete' } }],
});
expect(result.messages[1]).toMatchObject({
id: 'turn-image-assistant',
role: 'assistant',
content: [{ type: 'text', text: 'Image received.' }],
});
expect(turnToSessionRecord(turn)).toHaveProperty('userText', '');
});
it('nests sub-agents within a turn group and isolates the next user turn', async () => {
const spawnTurn = mockTurn({
id: 'turn-spawn',
createdAt,
input: [{ type: 'user.message', content: 'spawn agent' }],
events: [
modelMessage({
id: 'root-spawn',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'spawn-1',
type: 'function',
function: { name: 'create_sub_agent', arguments: '{}' },
toolInfo: {
type: 'trueforge-system',
name: 'create_sub_agent',
},
},
],
}),
threadCreated({
id: 't-created',
threadId: 'child-1',
title: 'Research agent',
agentInfo: {
type: 'dynamic',
name: 'researcher',
input: 'do research',
},
parent: { threadId: ROOT_THREAD_ID, toolCallId: 'spawn-1' },
}),
modelMessage({
id: 'child-msg-1',
threadId: 'child-1',
content: 'initial child work',
}),
],
});
const continuationTurn = mockTurn({
id: 'turn-continuation',
createdAt,
input: [
{
type: 'user.tool_approval',
threadId: ROOT_THREAD_ID,
toolCallId: 'spawn-1',
approval: { status: 'allow' },
},
],
events: [
modelMessage({
id: 'child-msg-2',
threadId: 'child-1',
content: 'more child work',
}),
],
});
const nextUserTurn = mockTurn({
id: 'turn-next',
createdAt,
input: [{ type: 'user.message', content: 'thanks' }],
events: [
modelMessage({
id: 'm-thanks',
threadId: ROOT_THREAD_ID,
content: "You're welcome!",
}),
],
});
const result = await convertTurnsToThreadMessages(
mockServerWithTurns([nextUserTurn, continuationTurn, spawnTurn]),
SESSION_ID,
);
expect(result.messages).toHaveLength(4);
const groupAssistant = result.messages[1];
expect(groupAssistant?.role).toBe('assistant');
if (groupAssistant?.role !== 'assistant') {
return;
}
const spawnPart = groupAssistant.content.find(part => part.type === 'tool-call');
expect(spawnPart?.type).toBe('tool-call');
if (spawnPart?.type !== 'tool-call') {
return;
}
expect(spawnPart.artifact).toEqual({
subAgents: [
{
threadId: 'child-1',
title: 'Research agent',
agentInfo: {
type: 'dynamic',
name: 'researcher',
input: 'do research',
},
},
],
});
expect(spawnPart.messages?.[0]?.metadata.custom['subAgent']).toEqual({
threadId: 'child-1',
title: 'Research agent',
name: 'researcher',
input: 'do research',
});
const nextAssistant = result.messages[3];
expect(nextAssistant?.role).toBe('assistant');
if (nextAssistant?.role !== 'assistant') {
return;
}
expect(nextAssistant.content).toEqual([{ type: 'text', text: "You're welcome!" }]);
expect(nextAssistant.content.some(part => part.type === 'tool-call')).toBe(false);
});
});
describe('streamTurnEvents', () => {
it('yields folded root content as model messages arrive', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'streaming',
}),
turnDone(),
]),
foldState,
),
);
expect(updates).toEqual([{ content: [{ type: 'text', text: 'streaming' }], sequenceNumber: 1 }]);
});
it('yields Cancelled: reason and cancellationReason on cancelled turn.done', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
{
type: 'turn.done',
id: 'turn-done-cancel',
createdAt,
state: { status: 'cancelled', reason: 'abandoned', completedAt: createdAt },
},
]),
foldState,
),
);
expect(updates).toEqual([
{
content: [],
status: { type: 'incomplete', reason: 'cancelled' },
metadata: { custom: { cancellationReason: 'abandoned' } },
sequenceNumber: 1,
},
]);
});
it('projects abort-shaped nested thread.done as cancelled on live turn.done cancel', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'root-msg',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'spawn-1',
type: 'function',
function: { name: 'create_sub_agent', arguments: '{}' },
toolInfo: { type: 'trueforge-system', name: 'create_sub_agent' },
},
],
}),
{
type: 'thread.created',
id: 't-created',
threadId: 'child-1',
title: 'finder',
createdAt,
agentInfo: { type: 'dynamic', name: 'finder', input: 'find' },
parent: { threadId: ROOT_THREAD_ID, toolCallId: 'spawn-1' },
},
modelMessage({
id: 'child-msg',
threadId: 'child-1',
content: 'working',
}),
{
type: 'thread.done',
id: 't-done',
threadId: 'child-1',
title: 'finder',
createdAt,
state: { status: 'error', error: 'LLM stream aborted' },
},
{
type: 'turn.done',
id: 'turn-done-cancel',
createdAt,
state: { status: 'cancelled', reason: 'client-cancelled', completedAt: createdAt },
},
]),
foldState,
),
);
const last = updates[updates.length - 1];
expect(last).toMatchObject({
status: { type: 'incomplete', reason: 'cancelled' },
metadata: { custom: { cancellationReason: 'client-cancelled' } },
});
const spawn = last?.content.find(part => part.type === 'tool-call');
expect(spawn?.type).toBe('tool-call');
if (spawn?.type !== 'tool-call') return;
expect(spawn.messages?.[0]?.status).toEqual({ type: 'incomplete', reason: 'cancelled' });
});
it('does not let a post-loop sandbox flush overwrite a cancelled turn.done', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
sandboxCreated({ id: 'sbx-evt', sandboxId: 'sbx-1' }),
{
type: 'turn.done',
id: 'turn-done-cancel',
createdAt,
state: { status: 'cancelled', reason: 'abandoned', completedAt: createdAt },
},
]),
foldState,
),
);
expect(updates).toHaveLength(1);
expect(updates[0]).toMatchObject({
content: [],
status: { type: 'incomplete', reason: 'cancelled' },
metadata: { custom: { cancellationReason: 'abandoned' } },
});
});
it('reports every stream sequence including events that do not yield UI', async () => {
const foldState = new PeerThreadFoldState();
const sequences: number[] = [];
const onSequenceNumber = vi.fn((sequenceNumber: number) => {
sequences.push(sequenceNumber);
});
const gatewayTurnId = 'turn-gw';
await collectStream(
streamTurnEvents(
streamFrom([
{
type: 'turn.created',
createdAt,
id: 'created-1',
turnId: gatewayTurnId,
input: [{ type: 'user.message', content: 'hello' }],
},
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'hi',
}),
turnDone(),
]),
foldState,
undefined,
undefined,
onSequenceNumber,
),
);
expect(sequences).toEqual([1, 2, 3]);
expect(onSequenceNumber).toHaveBeenCalledTimes(3);
});
it('yields folded content after each ingested stream event', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'first',
}),
modelMessage({
id: 'm2',
threadId: ROOT_THREAD_ID,
content: 'second',
}),
modelMessage({
id: 'm3',
threadId: ROOT_THREAD_ID,
content: 'third',
}),
turnDone(),
]),
foldState,
),
);
expect(updates).toHaveLength(3);
expect(updates[0]?.content).toEqual([{ type: 'text', text: 'first' }]);
expect(updates[1]?.content).toEqual([
{ type: 'text', text: 'first' },
{ type: 'text', text: 'second' },
]);
expect(updates[2]?.content).toEqual([
{ type: 'text', text: 'first' },
{ type: 'text', text: 'second' },
{ type: 'text', text: 'third' },
]);
});
it('scopes streamed content to ids after the group baseline', async () => {
const foldState = new PeerThreadFoldState();
foldState.getOrCreateBucket(ROOT_THREAD_ID);
foldState.threads.get(ROOT_THREAD_ID)!.modelMessageIds.push('prior');
foldState.threads.get(ROOT_THREAD_ID)!.events.set(
'prior',
modelMessage({
id: 'prior',
threadId: ROOT_THREAD_ID,
content: 'old turn',
}),
);
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm-new',
threadId: ROOT_THREAD_ID,
content: 'new turn only',
}),
turnDone(),
]),
foldState,
['prior'],
),
);
expect(updates).toEqual([{ content: [{ type: 'text', text: 'new turn only' }], sequenceNumber: 1 }]);
});
it('throws when the turn ends in error', async () => {
const foldState = new PeerThreadFoldState();
await expect(
collectStream(
streamTurnEvents(
streamFrom([
{
type: 'turn.done',
id: 'turn-done',
createdAt,
state: {
status: 'error',
message: 'boom',
completedAt: createdAt,
},
},
]),
foldState,
),
),
).rejects.toThrow('boom');
});
it('emits tool approval metadata after the stream when approvals remain pending', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'run tool',
toolCalls: [
{
id: 'approval-1',
type: 'function',
function: { name: 'bash', arguments: '{}' },
toolInfo: {
type: 'mcp',
name: 'bash',
serverId: 'bash-server',
serverName: 'bash',
},
},
],
}),
approvalRequired({
id: 'approval-event',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'approval-1', sourceEventId: 'm1' }],
}),
]),
foldState,
),
);
const final = updates.at(-1);
expect(final?.status).toEqual({
type: 'requires-action',
reason: 'tool-calls',
});
expect(final?.metadata?.custom?.[TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY]).toBe(ROOT_THREAD_ID);
});
it('defers mcp auth until stream end and appends auth prompt', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'before auth',
}),
{
type: 'mcp.auth_required',
id: 'mcp-auth',
createdAt,
mcpServers: [
{
id: 'github-auth',
name: 'github',
authUrl: 'https://example.com/auth',
},
],
},
]),
foldState,
),
);
expect(updates).toHaveLength(2);
expect(updates[0]).toEqual({
content: [{ type: 'text', text: 'before auth' }],
sequenceNumber: 1,
});
expect(updates[1]?.status).toEqual({
type: 'requires-action',
reason: 'interrupt',
});
expect(updates[1]?.content.at(-1)).toMatchObject({
type: 'text',
text: expect.stringContaining('Connect'),
});
});
it('throws when the SSE body ends without turn.done or a pause', async () => {
const foldState = new PeerThreadFoldState();
await expect(
collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'partial',
}),
]),
foldState,
),
),
).rejects.toThrow(TurnStreamDisconnectedError);
});
it('stamps sandboxId onto every content yield after sandbox.created is seen', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'before sandbox',
}),
sandboxCreated({ id: 'sandbox-evt', sandboxId: 'sbx-123' }),
modelMessage({
id: 'm2',
threadId: ROOT_THREAD_ID,
content: 'after sandbox',
}),
turnDone(),
]),
foldState,
),
);
expect(updates).toHaveLength(2);
expect(updates[0]?.metadata?.custom?.['sandboxId']).toBeUndefined();
expect(updates[1]?.metadata?.custom?.['sandboxId']).toBe('sbx-123');
});
it('yields a trailing update carrying sandboxId when sandbox.created is the last event', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'some content',
}),
sandboxCreated({ id: 'sandbox-evt', sandboxId: 'sbx-123' }),
turnDone(),
]),
foldState,
),
);
const final = updates.at(-1);
expect(final?.metadata?.custom?.['sandboxId']).toBe('sbx-123');
});
it('keeps sandboxId on the final mcp auth yield when both occur in the same stream', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
sandboxCreated({ id: 'sandbox-evt', sandboxId: 'sbx-123' }),
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'before auth',
}),
{
type: 'mcp.auth_required',
id: 'mcp-auth',
createdAt,
mcpServers: [
{
id: 'github-auth',
name: 'github',
authUrl: 'https://example.com/auth',
},
],
},
]),
foldState,
),
);
const final = updates.at(-1);
expect(final?.metadata?.custom?.['sandboxId']).toBe('sbx-123');
expect(final?.status).toEqual({ type: 'requires-action', reason: 'interrupt' });
});
});
describe('projectSessionMessages streamComplete', () => {
const turnId = 'turn-live';
function snapshotWithCompletedStream(update: TurnStreamUpdate, foldState: PeerThreadFoldState) {
return {
...replaceSessionSnapshot(createEmptySessionSnapshot(), {
pendingUser: {
turnId,
content: 'hello',
createdAt: new Date(createdAt),
},
activeStream: {
turnId,
update,
isContinuation: false,
streamComplete: true,
},
}),
fold: foldState,
};
}
it('keeps streamed images on the assistant message for text-only user prompts', () => {
const imageDataUri = 'data:image/jpeg;base64,/9j/4AAQ';
const messages = projectSessionMessages(
replaceSessionSnapshot(createEmptySessionSnapshot(), {
pendingUser: {
turnId,
content: 'Create image of dog',
createdAt: new Date(createdAt),
},
activeStream: {
turnId,
update: {
content: [
{
type: 'image',
image: imageDataUri,
filename: 'image-1.jpeg',
},
],
},
isContinuation: false,
streamComplete: true,
},
}),
);
expect(messages).toHaveLength(2);
const user = messages[0];
const assistant = messages[1];
expect(user?.role).toBe('user');
if (user?.role !== 'user') {
return;
}
expect(user.attachments).toEqual([]);
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.content).toEqual([
{
type: 'image',
image: imageDataUri,
filename: 'image-1.jpeg',
},
]);
});
it('preserves requires-action when streamComplete and update has approval status', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm1',
threadId: ROOT_THREAD_ID,
content: 'run tool',
toolCalls: [
{
id: 'approval-1',
type: 'function',
function: { name: 'bash', arguments: '{}' },
toolInfo: {
type: 'mcp',
name: 'bash',
serverId: 'bash-server',
serverName: 'bash',
},
},
],
}),
approvalRequired({
id: 'approval-event',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'approval-1', sourceEventId: 'm1' }],
}),
]),
foldState,
),
);
const finalUpdate = updates.at(-1)!;
const messages = projectSessionMessages(snapshotWithCompletedStream(finalUpdate, foldState));
const assistant = messages.at(-1);
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.status).toEqual({
type: 'requires-action',
reason: 'tool-calls',
});
expect(assistant.content.find(part => part.type === 'tool-call')).toMatchObject({
type: 'tool-call',
toolCallId: 'approval-1',
approval: { id: 'approval-1' },
});
expect(findCurrentPausedAssistantMessage(messages)).toBe(assistant);
});
it('preserves requires-action when streamComplete and update has ask-user status', async () => {
const foldState = new PeerThreadFoldState();
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'model-1',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'question-1',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'Pick one',
options: ['A', 'B'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
]),
foldState,
),
);
const finalUpdate = updates.at(-1)!;
const messages = projectSessionMessages(snapshotWithCompletedStream(finalUpdate, foldState));
const assistant = messages.at(-1);
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.status).toEqual({
type: 'requires-action',
reason: 'tool-calls',
});
expect(assistant.content[0]).toMatchObject({
type: 'tool-call',
toolCallId: 'question-1',
interrupt: {
type: 'human',
payload: { question: 'Pick one', options: ['A', 'B'] },
},
});
expect(findCurrentPausedAssistantMessage(messages)).toBe(assistant);
});
it('forces complete when streamComplete and update has no explicit status', () => {
const foldState = new PeerThreadFoldState();
const messages = projectSessionMessages(
snapshotWithCompletedStream({ content: [{ type: 'text', text: 'done' }] }, foldState),
);
const assistant = messages.at(-1);
expect(assistant?.role).toBe('assistant');
if (assistant?.role !== 'assistant') {
return;
}
expect(assistant.status).toEqual({
type: 'complete',
reason: 'stop',
});
});
it('prevents duplicate assistant message IDs if an activeStream matches an already projected turn', () => {
const foldState = new PeerThreadFoldState();
const mcpServers = [
{
id: 'test-mcp',
name: 'test-mcp',
authUrl: 'https://test/auth',
},
];
const snapshot: SessionSnapshot = {
...createEmptySessionSnapshot(),
fold: foldState,
turns: [
{
id: turnId,
userText: 'hello',
createdAt,
input: [{ type: 'user.message', content: 'hello' }],
rootModelMessageIds: [],
state: {
status: 'done',
completedAt: createdAt,
requiredActions: [
{
type: 'mcp.auth_required',
id: 'mcp-auth-1',
createdAt,
mcpServers,
},
],
},
},
],
activeStream: {
turnId,
update: {
content: [{ type: 'text', text: 'This agent needs access to external services before it can continue.' }],
status: { type: 'requires-action', reason: 'interrupt' },
metadata: { custom: { pendingMcpAuth: true, mcpServers } },
},
isContinuation: false,
streamComplete: true,
},
};
const messages = projectSessionMessages(snapshot);
const assistantMessages = messages.filter(m => m.role === 'assistant');
expect(assistantMessages).toHaveLength(1);
expect(assistantMessages[0]?.id).toBe(`${turnId}-assistant`);
const messageIds = messages.map(m => m.id);
expect(new Set(messageIds).size).toBe(messageIds.length);
});
});
describe('ask-user reload projection', () => {
it('does not resurface answered ask-user prompts after a continuation turn', () => {
const fold = new PeerThreadFoldState();
const turn1Id = 'turn-1';
const turn2Id = 'turn-2';
const initialCompletedAt = '2026-09-15T09:00:12.000Z';
const continuationCompletedAt = '2026-09-15T09:01:08.000Z';
ingestTurnEvent(
fold,
modelMessage({
id: 'model-1',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'question-1',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'What would you like help with today?',
options: ['Help with a coding or technical task'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
);
ingestTurnEvent(
fold,
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
);
applyUserToolResponsesToFold(fold, []);
ingestTurnEvent(
fold,
modelMessage({
id: 'model-2',
threadId: ROOT_THREAD_ID,
content: "Great, you'd like help with a coding task!",
}),
);
applyUserToolResponsesToFold(fold, [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'question-1',
content: 'Help with a coding or technical task',
},
]);
const snapshot = replaceSessionSnapshot(createEmptySessionSnapshot(), {
fold,
turns: [
{
id: turn1Id,
createdAt,
userText: 'hello',
state: {
status: 'done',
requiredActions: [],
completedAt: initialCompletedAt,
},
input: [{ type: 'user.message', content: 'hello' }],
rootModelMessageIds: ['model-1'],
},
{
id: turn2Id,
createdAt,
state: {
status: 'done',
requiredActions: [],
completedAt: continuationCompletedAt,
},
input: [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'question-1',
content: 'Help with a coding or technical task',
},
],
rootModelMessageIds: ['model-2'],
},
],
});
const messages = projectSessionMessages(snapshot);
expect(collectPendingToolResponses(messages)).toHaveLength(0);
const assistant = messages.find(message => message.role === 'assistant');
expect(assistant).toBeDefined();
expect(assistant?.createdAt).toEqual(new Date(continuationCompletedAt));
const toolCall = assistant?.content.find(part => part.type === 'tool-call');
expect(toolCall).toMatchObject({
type: 'tool-call',
toolCallId: 'question-1',
result: 'Help with a coding or technical task',
});
if (toolCall?.type === 'tool-call') {
expect(toolCall.interrupt).toBeUndefined();
}
});
it('keeps a committed ask-user pause as requires-action so it can be resumed', () => {
// Reproduces the live-stream pause path: once the SSE stream ends,
// `commitActiveStream` moves the paused turn into `turns` with a
// fabricated `TurnStateDone`. The pause must survive as a
// `tool.response_required` required action, otherwise the projected
// assistant message is not `requires-action` and
// `findCurrentPausedAssistantMessage` (the gate that fires the resume turn)
// never sees it.
const fold = new PeerThreadFoldState();
const turnId = 'turn-ask';
ingestTurnEvent(
fold,
modelMessage({
id: 'model-1',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'question-1',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'Pick one',
options: ['A', 'B'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
);
ingestTurnEvent(
fold,
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
);
const snapshot = replaceSessionSnapshot(createEmptySessionSnapshot(), {
fold,
turns: [
{
id: turnId,
createdAt,
userText: 'ask me a question',
state: {
status: 'done',
requiredActions: [
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
] as never,
completedAt: createdAt,
},
input: [{ type: 'user.message', content: 'ask me a question' }],
rootModelMessageIds: ['model-1'],
},
],
});
const messages = projectSessionMessages(snapshot);
const paused = findCurrentPausedAssistantMessage(messages);
expect(paused).toBeDefined();
expect(paused?.status).toMatchObject({ type: 'requires-action' });
});
it('rebuilds paused activeStream content from fold after an ask-user answer is recorded', () => {
const fold = new PeerThreadFoldState();
const turnId = 'turn-ask';
ingestTurnEvent(
fold,
modelMessage({
id: 'model-1',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'question-1',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'Pick one',
options: ['A', 'B'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
);
ingestTurnEvent(
fold,
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
);
const pausedContent = buildRootAssistantContent(fold);
applyUserToolResponsesToFold(fold, [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'question-1',
content: 'A',
},
]);
const snapshot = replaceSessionSnapshot(createEmptySessionSnapshot(), {
fold,
pendingUser: {
turnId,
content: 'ask me a question',
createdAt: new Date(createdAt),
},
activeStream: {
turnId,
isContinuation: false,
streamComplete: true,
update: {
content: pausedContent,
status: toolResponseStatus(),
},
},
groupRootBaseline: [],
});
const messages = projectSessionMessages(snapshot);
expect(collectPendingToolResponses(messages)).toHaveLength(0);
});
});
describe('ask-user live continuation projection', () => {
it('scopes activeStream to the current group when a continuation turn completes', () => {
const fold = new PeerThreadFoldState();
ingestTurnEvent(
fold,
modelMessage({
id: 'model-1',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'question-1',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'What would you like help with?',
options: ['Help with a coding task'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
);
ingestTurnEvent(
fold,
responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
);
applyUserToolResponsesToFold(fold, [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'question-1',
content: 'Help with a coding task',
},
]);
ingestTurnEvent(
fold,
modelMessage({
id: 'model-2',
threadId: ROOT_THREAD_ID,
content: 'Group 1 follow-up',
}),
);
ingestTurnEvent(
fold,
modelMessage({
id: 'model-3',
threadId: ROOT_THREAD_ID,
toolCalls: [
{
id: 'question-2',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'What kind of code?',
options: ['Write new code'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
);
ingestTurnEvent(
fold,
responseRequired({
id: 'resp-req-2',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-2', sourceEventId: 'model-3' }],
}),
);
applyUserToolResponsesToFold(fold, [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'question-2',
content: 'Write new code',
},
]);
ingestTurnEvent(
fold,
modelMessage({
id: 'model-4',
threadId: ROOT_THREAD_ID,
content: 'Group 2 follow-up',
}),
);
const snapshot = replaceSessionSnapshot(createEmptySessionSnapshot(), {
fold,
groupRootBaseline: ['model-1', 'model-2'],
turns: [
{
id: 'turn-1',
createdAt,
userText: 'ask me a question',
state: {
status: 'done',
requiredActions: [],
completedAt: createdAt,
},
input: [{ type: 'user.message', content: 'ask me a question' }],
rootModelMessageIds: ['model-1'],
},
{
id: 'turn-2',
createdAt,
state: {
status: 'done',
requiredActions: [],
completedAt: createdAt,
},
input: [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'question-1',
content: 'Help with a coding task',
},
],
rootModelMessageIds: ['model-2'],
},
{
id: 'turn-3',
createdAt,
userText: 'ask again',
state: {
status: 'done',
requiredActions: [],
completedAt: createdAt,
},
input: [{ type: 'user.message', content: 'ask again' }],
rootModelMessageIds: ['model-3'],
},
],
activeStream: {
turnId: 'turn-4',
isContinuation: true,
streamComplete: true,
update: {
content: [{ type: 'text', text: 'Group 2 follow-up' }],
status: { type: 'complete', reason: 'stop' },
},
},
});
const messages = projectSessionMessages(snapshot);
expect(messages).toHaveLength(4);
const group1Assistant = messages[1];
const group2Assistant = messages[3];
expect(group1Assistant?.role).toBe('assistant');
expect(group2Assistant?.role).toBe('assistant');
if (group1Assistant?.role !== 'assistant' || group2Assistant?.role !== 'assistant') {
return;
}
const group1Texts = group1Assistant.content.filter(part => part.type === 'text').map(part => part.text);
const group2Texts = group2Assistant.content.filter(part => part.type === 'text').map(part => part.text);
expect(group1Texts).toContain('Group 1 follow-up');
expect(group1Texts).not.toContain('Group 2 follow-up');
expect(group2Texts).toContain('Group 2 follow-up');
expect(group2Texts).not.toContain('Group 1 follow-up');
const group2ToolCalls = group2Assistant.content.filter(part => part.type === 'tool-call');
expect(group2ToolCalls).toHaveLength(1);
expect(group2ToolCalls[0]).toMatchObject({
toolCallId: 'question-2',
result: 'Write new code',
});
});
});
});
// ---------------------------------------------------------------------------
// buildSnapshotFromSessionEvents
// ---------------------------------------------------------------------------
/** Simulates session.listEvents — returns items in desc order (newest first). */
function sessionEventsPage(items: SessionEventItem[], options?: { pageSize?: number }) {
return async (opts?: { sessionId?: string; lastTurnId?: string; pageToken?: string; limit?: number }) => {
let filtered = items;
if (opts?.lastTurnId != null) {
// Chronological items: keep through lastTurnId, drop later turns.
const lastIndex = filtered.findLastIndex(item => item.turnId === opts.lastTurnId);
filtered = lastIndex === -1 ? [] : filtered.slice(0, lastIndex + 1);
}
const newestFirst = [...filtered].reverse();
// Prefer fixture pageSize so pagination tests are not forced to the API default limit.
const pageSize = options?.pageSize ?? opts?.limit ?? (newestFirst.length || 1);
const pageIndex = opts?.pageToken != null ? Number(opts.pageToken) : 0;
const start = pageIndex * pageSize;
const slice = newestFirst.slice(start, start + pageSize);
const hasMore = start + pageSize < newestFirst.length;
const nextPageToken = hasMore ? String(pageIndex + 1) : undefined;
return {
data: slice,
...(nextPageToken != null ? { nextPageToken } : {}),
};
};
}
/** Builds a mock AgentChatServer with listTurns and listEvents. */
function mockServerWithEvents(turns: Turn[], eventItems: SessionEventItem[]): AgentChatServer {
return {
listTurns: async ({ limit }: { limit?: number } = {}) => ({
data: limit != null ? turns.slice(0, limit) : turns,
}),
listEvents: sessionEventsPage(eventItems),
listTurnEvents: async () => ({ data: [] }),
} as unknown as AgentChatServer;
}
describe('buildSnapshotFromSessionEvents', () => {
it('builds a snapshot from a single complete turn', async () => {
const turnStartedAt = '2026-09-15T09:00:00.000Z';
const turnCompletedAt = '2026-09-15T09:00:12.000Z';
const items: SessionEventItem[] = [
{
turnId: 't1',
event: {
type: 'turn.created',
id: 'evt-c1',
turnId: 't1',
input: [{ type: 'user.message', content: 'hello' }],
state: { status: 'running' },
createdAt: turnStartedAt,
},
},
{
turnId: 't1',
event: modelMessage({ id: 'm1', threadId: ROOT_THREAD_ID, content: 'hi there' }),
},
{
turnId: 't1',
event: {
type: 'turn.done',
id: 'evt-d1',
state: { status: 'done', requiredActions: [], completedAt: turnCompletedAt },
createdAt: turnCompletedAt,
} as TurnDoneEvent,
},
];
const snapshot = await buildSnapshotFromSessionEvents(mockServerWithEvents([], items), SESSION_ID);
expect(snapshot.turns).toHaveLength(1);
expect(snapshot.turns[0]?.id).toBe('t1');
expect(snapshot.turns[0]?.userText).toBe('hello');
expect(snapshot.turns[0]?.state).toEqual({
status: 'done',
requiredActions: [],
completedAt: turnCompletedAt,
});
expect(snapshot.turns[0]?.rootModelMessageIds).toEqual(['m1']);
expect(snapshot.runningTurn).toBeUndefined();
const messages = projectSessionMessages(snapshot);
expect(messages).toHaveLength(2);
expect(messages[0]?.role).toBe('user');
expect(messages[0]?.createdAt).toEqual(new Date(turnStartedAt));
expect(messages[1]?.role).toBe('assistant');
expect(messages[1]?.createdAt).toEqual(new Date(turnCompletedAt));
});
it('does not attach a running turn that listEvents omits', async () => {
const runningTurn = {
id: 't2',
state: { status: 'running' },
input: [{ type: 'user.message', content: 'in progress' }],
createdAt,
} as unknown as Turn;
const items: SessionEventItem[] = [
{
turnId: 't1',
event: {
type: 'turn.created',
id: 'evt-c1',
turnId: 't1',
input: [{ type: 'user.message', content: 'first' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't1',
event: modelMessage({ id: 'm1', threadId: ROOT_THREAD_ID, content: 'reply 1' }),
},
{
turnId: 't1',
event: {
type: 'turn.done',
id: 'evt-d1',
state: { status: 'done', requiredActions: [], completedAt: createdAt },
createdAt,
} as TurnDoneEvent,
},
];
const snapshot = await buildSnapshotFromSessionEvents(mockServerWithEvents([runningTurn], items), SESSION_ID);
expect(snapshot.turns).toHaveLength(1);
expect(snapshot.turns[0]?.id).toBe('t1');
expect(snapshot.runningTurn).toBeUndefined();
expect(snapshot.pendingUser).toBeUndefined();
});
it('baselines all prior root model messages when resuming a new user tip', async () => {
const runningTurn = {
id: 't3',
state: { status: 'running' },
input: [{ type: 'user.message', content: 'search random opic' }],
createdAt,
} as unknown as Turn;
const items: SessionEventItem[] = [
{
turnId: 't1',
event: {
type: 'turn.created',
id: 'evt-c1',
turnId: 't1',
input: [{ type: 'user.message', content: 'test' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't1',
event: modelMessage({ id: 'm1', threadId: ROOT_THREAD_ID, content: 'Hello! How can I assist you today?' }),
},
{
turnId: 't1',
event: {
type: 'turn.done',
id: 'evt-d1',
state: { status: 'done', requiredActions: [], completedAt: createdAt },
createdAt,
} as TurnDoneEvent,
},
{
turnId: 't2',
event: {
type: 'turn.created',
id: 'evt-c2',
turnId: 't2',
input: [{ type: 'user.message', content: 'hello' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't2',
event: modelMessage({
id: 'm2',
threadId: ROOT_THREAD_ID,
content: 'Hello! How can I help you today?',
reasoningContent: 'The user says "test" then "hello".',
}),
},
{
turnId: 't2',
event: {
type: 'turn.done',
id: 'evt-d2',
state: { status: 'done', requiredActions: [], completedAt: createdAt },
createdAt,
} as TurnDoneEvent,
},
{
turnId: 't3',
event: {
type: 'turn.created',
id: 'evt-c3',
turnId: 't3',
input: [{ type: 'user.message', content: 'search random opic' }],
state: { status: 'running' },
createdAt,
},
},
];
const snapshot = await buildSnapshotFromSessionEvents(mockServerWithEvents([runningTurn], items), SESSION_ID);
expect(snapshot.turns).toHaveLength(2);
// Must include m2 — computeGroupRootBaseline(completedTurns) would omit it and
// leak turn 2 content onto the resumed tip.
expect(snapshot.groupRootBaseline).toEqual(['m1', 'm2']);
expect(snapshot.pendingUser).toMatchObject({
turnId: 't3',
content: 'search random opic',
});
const messages = projectSessionMessages(snapshot);
expect(messages.map(message => message.role)).toEqual(['user', 'assistant', 'user', 'assistant', 'user']);
expect(messages.at(-1)).toMatchObject({
id: 't3-user',
role: 'user',
});
});
it("keeps the running tip's already-ingested model messages in live resume scope", async () => {
const runningTurn = {
id: 't2',
state: { status: 'running' },
input: [{ type: 'user.message', content: 'can 10 random sandbox tool calll' }],
createdAt,
} as unknown as Turn;
const items: SessionEventItem[] = [
{
turnId: 't1',
event: {
type: 'turn.created',
id: 'evt-c1',
turnId: 't1',
input: [{ type: 'user.message', content: 'first' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't1',
event: modelMessage({ id: 'm1', threadId: ROOT_THREAD_ID, content: 'reply 1' }),
},
{
turnId: 't1',
event: {
type: 'turn.done',
id: 'evt-d1',
state: { status: 'done', requiredActions: [], completedAt: createdAt },
createdAt,
} as TurnDoneEvent,
},
{
turnId: 't2',
event: {
type: 'turn.created',
id: 'evt-c2',
turnId: 't2',
input: [{ type: 'user.message', content: 'can 10 random sandbox tool calll' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't2',
event: modelMessage({
id: 'm2',
threadId: ROOT_THREAD_ID,
content: 'Running 10 random sandbox commands at once:',
}),
},
];
const snapshot = await buildSnapshotFromSessionEvents(mockServerWithEvents([runningTurn], items), SESSION_ID);
expect(snapshot.turns).toHaveLength(1);
expect(snapshot.groupRootBaseline).toEqual(['m1']);
expect(rootModelMessageIdsSinceBaseline(snapshot.fold, snapshot.groupRootBaseline ?? [])).toEqual(['m2']);
const updates = await collectStream(
streamTurnEvents(
streamFrom([
modelMessage({
id: 'm3',
threadId: ROOT_THREAD_ID,
content: 'I ran 10 sandbox commands',
}),
turnDone(),
]),
snapshot.fold,
snapshot.groupRootBaseline,
),
);
const texts = (updates.at(-1)?.content ?? []).filter(part => part.type === 'text').map(part => part.text);
expect(texts).toEqual(['Running 10 random sandbox commands at once:', 'I ran 10 sandbox commands']);
});
it('calls onProgress after each completed turn', async () => {
const items: SessionEventItem[] = [
{
turnId: 't1',
event: {
type: 'turn.created',
id: 'evt-c1',
turnId: 't1',
input: [{ type: 'user.message', content: 'first' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't1',
event: modelMessage({ id: 'm1', threadId: ROOT_THREAD_ID, content: 'reply 1' }),
},
{
turnId: 't1',
event: {
type: 'turn.done',
id: 'evt-d1',
state: { status: 'done', requiredActions: [], completedAt: createdAt },
createdAt,
} as TurnDoneEvent,
},
{
turnId: 't2',
event: {
type: 'turn.created',
id: 'evt-c2',
turnId: 't2',
input: [{ type: 'user.message', content: 'second' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't2',
event: modelMessage({ id: 'm2', threadId: ROOT_THREAD_ID, content: 'reply 2' }),
},
{
turnId: 't2',
event: {
type: 'turn.done',
id: 'evt-d2',
state: { status: 'done', requiredActions: [], completedAt: createdAt },
createdAt,
} as TurnDoneEvent,
},
];
const progressSnapshots: number[] = [];
await buildSnapshotFromSessionEvents(mockServerWithEvents([], items), SESSION_ID, snap =>
progressSnapshots.push(snap.turns.length),
);
expect(progressSnapshots).toEqual([1, 2, 2]);
});
it('does not call listTurns when listEvents has no open tip', async () => {
const listTurns = vi.fn(async () => ({
data: [
{
id: 't-running',
sessionId: SESSION_ID,
state: { status: 'running' },
input: [{ type: 'user.message', content: 'now' }],
createdAt,
},
],
nextPageToken: 'more',
}));
const server = {
listTurns,
listEvents: sessionEventsPage([]),
listTurnEvents: async () => ({ data: [] }),
} as unknown as AgentChatServer;
const snapshot = await buildSnapshotFromSessionEvents(server, SESSION_ID);
expect(listTurns).not.toHaveBeenCalled();
expect(snapshot.runningTurn).toBeUndefined();
expect(snapshot.pendingUser).toBeUndefined();
});
it('publishes the open tip before getTurn resolves', async () => {
const progress: SessionSnapshot[] = [];
let resolveGetTurn: (turn: Turn) => void = () => undefined;
const getTurn = vi.fn(
() =>
new Promise<Turn>(resolve => {
resolveGetTurn = resolve;
}),
);
const items: SessionEventItem[] = [
{
turnId: 't-running',
event: {
type: 'turn.created',
id: 'evt-c-running',
turnId: 't-running',
input: [{ type: 'user.message', content: 'now' }],
state: { status: 'running' },
createdAt,
},
},
];
const listTurns = vi.fn(async () => ({ data: [] }));
const server = {
listTurns,
getTurn,
listEvents: sessionEventsPage(items),
listTurnEvents: async () => ({ data: [] }),
} as unknown as AgentChatServer;
let notifyProgress: () => void = () => undefined;
const progressed = new Promise<void>(resolve => {
notifyProgress = resolve;
});
const pending = buildSnapshotFromSessionEvents(server, SESSION_ID, snap => {
progress.push(snap);
if (snap.pendingUser != null) {
notifyProgress();
}
});
await progressed;
expect(getTurn).toHaveBeenCalledWith({ sessionId: SESSION_ID, turnId: 't-running' });
expect(progress.at(-1)?.pendingUser?.content).toBe('now');
expect(progress.at(-1)?.runningTurn?.id).toBe('t-running');
expect(listTurns).not.toHaveBeenCalled();
resolveGetTurn({
id: 't-running',
sessionId: SESSION_ID,
state: { status: 'running' },
input: [{ type: 'user.message', content: 'now' }],
createdAt,
});
const snapshot = await pending;
expect(snapshot.runningTurn?.id).toBe('t-running');
expect(snapshot.pendingUser?.content).toBe('now');
});
it('attaches an open tip from events when listTurns is oldest-first and clears answered ask-user', async () => {
// listEvents includes the running turn. Tip detection uses the open
// turn.created, because listTurns is oldest-first.
const oldestDoneTurn = {
id: 't-pause',
sessionId: SESSION_ID,
state: {
status: 'done',
requiredActions: [
{
id: 'resp-req-1',
type: 'tool.response_required',
threadId: ROOT_THREAD_ID,
createdAt,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
},
],
completedAt: createdAt,
},
input: [{ type: 'user.message', content: 'please research' }],
createdAt,
} as unknown as Turn;
const runningTip = {
id: 't-running',
sessionId: SESSION_ID,
state: { status: 'running' },
input: [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'question-1',
content: 'AI-native / LLM-powered SaaS',
},
],
createdAt,
} as unknown as Turn;
const items: SessionEventItem[] = [
{
turnId: 't-pause',
event: {
type: 'turn.created',
id: 'evt-c-pause',
turnId: 't-pause',
...(oldestDoneTurn.input === undefined ? {} : { input: oldestDoneTurn.input }),
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't-pause',
event: modelMessage({
id: 'model-1',
threadId: ROOT_THREAD_ID,
content: 'One calibration question:',
toolCalls: [
{
id: 'question-1',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'Which direction should I focus on?',
options: ['General B2B SaaS', 'AI-native / LLM-powered SaaS'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
},
{
turnId: 't-pause',
event: responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
},
{
turnId: 't-pause',
event: {
type: 'turn.done',
id: 'evt-d-pause',
state: oldestDoneTurn.state as TurnDoneEvent['state'],
createdAt,
} as TurnDoneEvent,
},
{
turnId: 't-running',
event: {
type: 'turn.created',
id: 'evt-c-running',
turnId: 't-running',
previousTurnId: 't-pause',
...(runningTip.input === undefined ? {} : { input: runningTip.input }),
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't-running',
event: modelMessage({
id: 'model-2',
threadId: ROOT_THREAD_ID,
content: 'Locked in — starting deep research.',
}),
},
];
const listTurns = vi.fn(async () => ({
data: [oldestDoneTurn],
nextPageToken: 'eyJvZmZzZXQiOjF9',
}));
const getTurn = vi.fn(async () => runningTip);
const server = {
listTurns,
getTurn,
listEvents: sessionEventsPage(items),
listTurnEvents: async () => ({ data: [] }),
} as unknown as AgentChatServer;
const snapshot = await buildSnapshotFromSessionEvents(server, SESSION_ID);
expect(getTurn).toHaveBeenCalledWith({
sessionId: SESSION_ID,
turnId: 't-running',
});
expect(listTurns).not.toHaveBeenCalled();
expect(snapshot.runningTurn?.id).toBe('t-running');
expect(snapshot.unstable_resume).toBe(true);
const messages = projectSessionMessages(snapshot);
expect(collectPendingToolResponses(messages)).toHaveLength(0);
const assistant = messages.find(message => message.role === 'assistant');
expect(assistant).toBeDefined();
const toolCall = assistant?.content.find(part => part.type === 'tool-call' && part.toolCallId === 'question-1');
expect(toolCall).toMatchObject({
type: 'tool-call',
toolCallId: 'question-1',
result: 'AI-native / LLM-powered SaaS',
});
if (toolCall?.type === 'tool-call') {
expect(toolCall.interrupt).toBeUndefined();
}
});
it('keeps an answered ask-user answered when the open tip finished before getTurn', async () => {
// The tip can complete between listEvents and getTurn. There is nothing
// left to resume, but its user.tool_response input never reached the
// fold via ingestion (no turn.done in the window), so it must still be
// applied — otherwise the answered prompt resurfaces as pending.
const finishedTip = {
id: 't-tip',
sessionId: SESSION_ID,
state: { status: 'done', requiredActions: [], completedAt: createdAt },
input: [
{
type: 'user.tool_response',
threadId: ROOT_THREAD_ID,
toolCallId: 'question-1',
content: 'AI-native / LLM-powered SaaS',
},
],
createdAt,
} as unknown as Turn;
const items: SessionEventItem[] = [
{
turnId: 't-pause',
event: {
type: 'turn.created',
id: 'evt-c-pause',
turnId: 't-pause',
input: [{ type: 'user.message', content: 'please research' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't-pause',
event: modelMessage({
id: 'model-1',
threadId: ROOT_THREAD_ID,
content: 'One calibration question:',
toolCalls: [
{
id: 'question-1',
type: 'function',
function: {
name: 'ask_user_question',
arguments: JSON.stringify({
question: 'Which direction should I focus on?',
options: ['General B2B SaaS', 'AI-native / LLM-powered SaaS'],
}),
},
toolInfo: {
type: 'trueforge-system',
name: 'ask_user_question',
},
},
],
}),
},
{
turnId: 't-pause',
event: responseRequired({
id: 'resp-req-1',
threadId: ROOT_THREAD_ID,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
}),
},
{
turnId: 't-pause',
event: {
type: 'turn.done',
id: 'evt-d-pause',
state: {
status: 'done',
requiredActions: [
{
id: 'resp-req-1',
type: 'tool.response_required',
threadId: ROOT_THREAD_ID,
createdAt,
toolCalls: [{ id: 'question-1', sourceEventId: 'model-1' }],
},
],
completedAt: createdAt,
},
createdAt,
} as unknown as TurnDoneEvent,
},
{
turnId: 't-tip',
event: {
type: 'turn.created',
id: 'evt-c-tip',
turnId: 't-tip',
previousTurnId: 't-pause',
...(finishedTip.input === undefined ? {} : { input: finishedTip.input }),
state: { status: 'running' },
createdAt,
},
},
];
const listTurns = vi.fn(async () => ({ data: [], nextPageToken: undefined }));
const getTurn = vi.fn(async () => finishedTip);
const server = {
listTurns,
getTurn,
listEvents: sessionEventsPage(items),
listTurnEvents: async () => ({ data: [] }),
} as unknown as AgentChatServer;
const snapshot = await buildSnapshotFromSessionEvents(server, SESSION_ID);
expect(snapshot.runningTurn).toBeUndefined();
expect(snapshot.unstable_resume).toBeFalsy();
const messages = projectSessionMessages(snapshot);
expect(collectPendingToolResponses(messages)).toHaveLength(0);
const assistant = messages.find(message => message.role === 'assistant');
const toolCall = assistant?.content.find(part => part.type === 'tool-call' && part.toolCallId === 'question-1');
expect(toolCall).toMatchObject({
type: 'tool-call',
toolCallId: 'question-1',
result: 'AI-native / LLM-powered SaaS',
});
if (toolCall?.type === 'tool-call') {
expect(toolCall.interrupt).toBeUndefined();
}
});
it('keeps the painted user message when the open tip finished before getTurn', async () => {
const finishedTip = {
id: 't2',
sessionId: SESSION_ID,
state: { status: 'done', requiredActions: [], completedAt: createdAt },
input: [{ type: 'user.message', content: 'what is 2+2' }],
createdAt,
} as unknown as Turn;
const items: SessionEventItem[] = [
{
turnId: 't1',
event: {
type: 'turn.created',
id: 'evt-c1',
turnId: 't1',
input: [{ type: 'user.message', content: 'hello' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't1',
event: modelMessage({ id: 'm1', threadId: ROOT_THREAD_ID, content: 'hi' }),
},
{
turnId: 't1',
event: {
type: 'turn.done',
id: 'evt-d1',
state: { status: 'done', requiredActions: [], completedAt: createdAt },
createdAt,
} as TurnDoneEvent,
},
{
turnId: 't2',
event: {
type: 'turn.created',
id: 'evt-c2',
turnId: 't2',
previousTurnId: 't1',
input: [{ type: 'user.message', content: 'what is 2+2' }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: 't2',
event: modelMessage({ id: 'm2', threadId: ROOT_THREAD_ID, content: '4' }),
},
];
const progress: SessionSnapshot[] = [];
const server = {
listTurns: vi.fn(async () => ({ data: [] })),
getTurn: vi.fn(async () => finishedTip),
listEvents: sessionEventsPage(items),
listTurnEvents: async () => ({ data: [] }),
} as unknown as AgentChatServer;
const snapshot = await buildSnapshotFromSessionEvents(server, SESSION_ID, snap => {
progress.push(snap);
});
expect(progress.some(snap => snap.pendingUser?.content === 'what is 2+2')).toBe(true);
expect(snapshot.runningTurn).toBeUndefined();
expect(snapshot.pendingUser).toBeUndefined();
expect(snapshot.turns.map(turn => turn.id)).toEqual(['t1', 't2']);
const texts = projectSessionMessages(snapshot).flatMap(message =>
message.content.flatMap(part => (part.type === 'text' ? [part.text] : [])),
);
expect(texts).toEqual(['hello', 'hi', 'what is 2+2', '4']);
});
it('loads only the newest event page and exposes an older-history cursor', async () => {
const makeTurnItems = (id: string, text: string): SessionEventItem[] => [
{
turnId: id,
event: {
type: 'turn.created',
id: `evt-c-${id}`,
turnId: id,
input: [{ type: 'user.message', content: text }],
state: { status: 'running' },
createdAt,
},
},
{
turnId: id,
event: modelMessage({
id: `m-${id}`,
threadId: ROOT_THREAD_ID,
content: `reply ${text}`,
}),
},
{
turnId: id,
event: {
type: 'turn.done',
id: `evt-d-${id}`,
state: { status: 'done', requiredActions: [], completedAt: createdAt },
createdAt,
} as TurnDoneEvent,
},
];
// 3 events per turn; pageSize 3 → one turn per page (newest first).
const items = [...makeTurnItems('t1', 'first'), ...makeTurnItems('t2', 'second'), ...makeTurnItems('t3', 'third')];
const listEvents = sessionEventsPage(items, { pageSize: 3 });
const listEventsSpy = vi.fn(listEvents);
const server = {
listTurns: async () => ({ data: [] }),
listEvents: listEventsSpy,
listTurnEvents: async () => ({ data: [] }),
} as unknown as AgentChatServer;
const snapshot = await buildSnapshotFromSessionEvents(server, SESSION_ID);
expect(listEventsSpy).toHaveBeenCalledTimes(1);
expect(snapshot.turns.map(t => t.id)).toEqual(['t3']);
expect(snapshot.historyPagination).toEqual({
hasOlder: true,
olderPageToken: '1',
});
const withOlder = await prependOlderSessionHistory(server, SESSION_ID, snapshot);
expect(withOlder.turns.map(t => t.id)).toEqual(['t2', 't3']);
expect(projectSessionMessages(withOlder).map(m => m.role)).toEqual(['user', 'assistant', 'user', 'assistant']);
expect(withOlder.historyPagination?.hasOlder).toBe(true);
const withAll = await prependOlderSessionHistory(server, SESSION_ID, withOlder);
expect(withAll.turns.map(t => t.id)).toEqual(['t1', 't2', 't3']);
expect(withAll.historyPagination?.hasOlder).toBe(false);
});
it('backfills sandboxId onto tip turns after older history reveals sandbox.created', async () => {
const makeTurnItems = (id: string, text: string, options?: { sandboxId?: string }): SessionEventItem[] => [
{
turnId: id,
event: {
type: 'turn.created',
id: `evt-c-${id}`,
turnId: id,
input: [{ type: 'user.message', content: text }],
state: { status: 'running' },
createdAt,
},
},
...(options?.sandboxId != null
? [
{
turnId: id,
event: sandboxCreated({
id: `sandbox-${id}`,
sandboxId: options.sandboxId,
}),
} satisfies SessionEventItem,
]
: [
{
turnId: id,
event: modelMessage({
id: `m-${id}-pad`,
threadId: ROOT_THREAD_ID,
content: '…',
}),
} satisfies SessionEventItem,
]),
{
turnId: id,
event: modelMessage({
id: `m-${id}`,
threadId: ROOT_THREAD_ID,
content: `reply ${text}`,
}),
},
{
turnId: id,
event: {
type: 'turn.done',
id: `evt-d-${id}`,
state: { status: 'done', requiredActions: [], completedAt: createdAt },
createdAt,
} as TurnDoneEvent,
},
];
// 4 events per turn; pageSize 4 → tip-only first page (no sandbox.created).
const items = [...makeTurnItems('t1', 'create', { sandboxId: 'sbx-123' }), ...makeTurnItems('t2', 'reuse')];
const listEvents = sessionEventsPage(items, { pageSize: 4 });
const server = {
listTurns: async () => ({ data: [] }),
listEvents,
listTurnEvents: async () => ({ data: [] }),
} as unknown as AgentChatServer;
const tipOnly = await buildSnapshotFromSessionEvents(server, SESSION_ID);
expect(tipOnly.turns.map(t => t.id)).toEqual(['t2']);
expect(tipOnly.turns[0]?.sandboxId).toBeUndefined();
const tipMessages = projectSessionMessages(tipOnly);
expect(tipMessages.at(-1)).toMatchObject({
role: 'assistant',
metadata: { custom: { turnId: 't2' } },
});
expect((tipMessages.at(-1)?.metadata.custom as { sandboxId?: string }).sandboxId).toBeUndefined();
const withCreate = await prependOlderSessionHistory(server, SESSION_ID, tipOnly);
expect(withCreate.turns.map(t => t.id)).toEqual(['t1', 't2']);
expect(withCreate.turns.map(t => t.sandboxId)).toEqual(['sbx-123', 'sbx-123']);
expect(projectSessionMessages(withCreate).at(-1)).toMatchObject({
role: 'assistant',
metadata: { custom: { sandboxId: 'sbx-123', turnId: 't2' } },
});
});
});
describe('buildSnapshotThroughTurn', () => {
/** Linear session t1 -> t2 -> t3, oldest-first. */
function linearTurns(): TurnFixture[] {
return [
mockTurn({
id: 't1',
createdAt: '2026-01-01T00:00:00.000Z',
previousTurnId: null,
input: [{ type: 'user.message', content: 'first' }],
events: [modelMessage({ id: 'm1', threadId: ROOT_THREAD_ID, content: 'reply 1' })],
}),
mockTurn({
id: 't2',
createdAt: '2026-01-01T00:01:00.000Z',
previousTurnId: 't1',
input: [{ type: 'user.message', content: 'second' }],
events: [modelMessage({ id: 'm2', threadId: ROOT_THREAD_ID, content: 'reply 2' })],
}),
mockTurn({
id: 't3',
createdAt: '2026-01-01T00:02:00.000Z',
previousTurnId: 't2',
input: [{ type: 'user.message', content: 'third' }],
events: [modelMessage({ id: 'm3', threadId: ROOT_THREAD_ID, content: 'reply 3' })],
}),
];
}
it("rewinds to the anchor's ancestor chain, inclusive", async () => {
const server = mockServerWithTurns(linearTurns());
const snapshot = await buildSnapshotThroughTurn(server, SESSION_ID, 't2');
expect(snapshot.turns.map(turn => turn.id)).toEqual(['t1', 't2']);
expect(projectSessionMessages(snapshot).map(message => message.id)).toEqual([
't1-user',
't1-assistant',
't2-user',
't2-assistant',
]);
});
it('returns an empty snapshot for a null anchor (branching from a root turn)', async () => {
const server = mockServerWithTurns(linearTurns());
const snapshot = await buildSnapshotThroughTurn(server, SESSION_ID, null);
expect(snapshot.turns).toHaveLength(0);
});
it('ignores listTurns page order', async () => {
const asc = linearTurns();
const ascSnapshot = await buildSnapshotThroughTurn(mockServerWithTurns(asc), SESSION_ID, 't2');
const descSnapshot = await buildSnapshotThroughTurn(mockServerWithTurns([...asc].reverse()), SESSION_ID, 't2');
expect(descSnapshot.turns.map(turn => turn.id)).toEqual(ascSnapshot.turns.map(turn => turn.id));
expect(descSnapshot.turns.map(turn => turn.id)).toEqual(['t1', 't2']);
});
it('drops sibling turns left behind by an earlier rerun', async () => {
// m2/m3 were rerun once already: t2/t3 are orphans, t2p/t3p are live.
const [t1, t2, t3] = linearTurns();
const t2p = mockTurn({
id: 't2p',
createdAt: '2026-01-01T00:03:00.000Z',
previousTurnId: 't1',
input: [{ type: 'user.message', content: 'second again' }],
events: [modelMessage({ id: 'm2p', threadId: ROOT_THREAD_ID, content: 'reply 2p' })],
});
const t3p = mockTurn({
id: 't3p',
createdAt: '2026-01-01T00:04:00.000Z',
previousTurnId: 't2p',
input: [{ type: 'user.message', content: 'third again' }],
events: [modelMessage({ id: 'm3p', threadId: ROOT_THREAD_ID, content: 'reply 3p' })],
});
const server = mockServerWithTurns([t1!, t2!, t3!, t2p, t3p]);
// Rerunning the middle live turn rewinds to its parent, not to the
// chronologically preceding turn (t3), whose chain still holds t2/t3.
const previousTurnId = await resolveGatewayBranchPreviousTurnIdForTurn(server, SESSION_ID, 't2p');
expect(previousTurnId).toBe('t1');
const snapshot = await buildSnapshotThroughTurn(server, SESSION_ID, previousTurnId);
expect(snapshot.turns.map(turn => turn.id)).toEqual(['t1']);
// The orphan chain is still reachable, so the assertion above is not
// passing by accident.
const orphanSnapshot = await buildSnapshotThroughTurn(server, SESSION_ID, 't3');
expect(orphanSnapshot.turns.map(turn => turn.id)).toEqual(['t1', 't2', 't3']);
});
});
describe('resolveGatewayBranchPreviousTurnIdForTurn', () => {
it('uses the turn parent for subsequent turns and none for roots (ASC listTurns)', async () => {
const t1 = mockTurn({
id: 't1',
createdAt: '2026-01-01T00:00:00.000Z',
previousTurnId: null,
});
const t2 = mockTurn({
id: 't2',
createdAt: '2026-01-01T00:01:00.000Z',
previousTurnId: 't1',
});
const t3 = mockTurn({
id: 't3',
createdAt: '2026-01-01T00:02:00.000Z',
previousTurnId: 't2',
});
const server = mockServerWithTurns([t1, t2, t3]);
await expect(resolveGatewayBranchPreviousTurnIdForTurn(server, SESSION_ID, 't1')).resolves.toBe('none');
await expect(resolveGatewayBranchPreviousTurnIdForTurn(server, SESSION_ID, 't3')).resolves.toBe('t2');
});
it('uses the turn parent when listTurns is newest-first', async () => {
const t1 = mockTurn({
id: 't1',
createdAt: '2026-01-01T00:00:00.000Z',
previousTurnId: null,
});
const t2 = mockTurn({
id: 't2',
createdAt: '2026-01-01T00:01:00.000Z',
previousTurnId: 't1',
});
const server = mockServerWithTurns([t2, t1]);
await expect(resolveGatewayBranchPreviousTurnIdForTurn(server, SESSION_ID, 't2')).resolves.toBe('t1');
});
});