Skip to content

Commit fff93ee

Browse files
hary73cursoragent
andcommitted
feat: store last turn id and status on session as last_turn_details (AGE-2315)
Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent dd92cff commit fff93ee

18 files changed

Lines changed: 412 additions & 10 deletions

File tree

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@truefoundry/trueforge': patch
3+
'@truefoundry/trueforge-core': patch
4+
---
5+
6+
Store the session's last turn id and status together as `last_turn_details` on `SessionRecord`. Stores replace the whole document when a turn is created and when that turn pauses, resumes, finishes, or is cancelled; a status change from a turn that is no longer the last turn is ignored. Existing sessions are backfilled from their last turn.

‎packages/trueforge-core/src/agent-session/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ export type {
3535
} from './schemas/turn';
3636

3737
export {
38+
SessionLastTurnDetailsSchema,
3839
SessionMetadataSchema,
3940
SessionMetricsSchema,
4041
SessionSchema,
@@ -45,6 +46,7 @@ export {
4546
export type {
4647
Session,
4748
SessionAgent,
49+
SessionLastTurnDetails,
4850
SessionMetadata,
4951
SessionMetrics,
5052
SessionSource,

‎packages/trueforge-core/src/agent-session/models/SessionRecord.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
1-
import type { SessionAgent, SessionMetadata, SessionMetrics, SessionSource } from '../schemas/session';
1+
import type {
2+
SessionAgent,
3+
SessionLastTurnDetails,
4+
SessionMetadata,
5+
SessionMetrics,
6+
SessionSource,
7+
} from '../schemas/session';
28
import type { CreatedBySubject } from '../schemas/subject';
39

410
/**
@@ -36,6 +42,11 @@ export interface SessionRecord<TCustom extends object = Record<string, never>> {
3642
* listing anchors. Advanced only by `createTurn` (atomic link).
3743
*/
3844
last_turn_id: string | null;
45+
/**
46+
* Id and status of the last turn; null until the first turn. Replaced whole on
47+
* createTurn and on that turn's status changes, never patched per key.
48+
*/
49+
last_turn_details: SessionLastTurnDetails | null;
3950
/** Instant the session was created (store domain). Wire/API serialize as ISO-8601. */
4051
created_at: Date;
4152
/** Instant the session was last updated (store domain). Wire/API serialize as ISO-8601. */

‎packages/trueforge-core/src/agent-session/schemas/session.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import { z } from '@hono/zod-openapi';
66
import { AgentSpecSchema } from './agentSpec';
77
import { CreatedBySubjectSchema } from './subject';
8+
import { TurnStatusSchema } from './turn';
89

910
const SESSION_METADATA_MAX_KEY_LENGTH = 32;
1011
/**
@@ -48,6 +49,16 @@ export const SessionMetricsSchema = z
4849
.describe('Rolled-up cost, duration, and turn counters for a session.')
4950
.openapi('SessionMetrics');
5051

52+
/** Id and status of the session's last turn, always written as one document. */
53+
export const SessionLastTurnDetailsSchema = z
54+
.object({
55+
id: z.string().min(1),
56+
status: TurnStatusSchema,
57+
})
58+
.strict();
59+
60+
export type SessionLastTurnDetails = z.infer<typeof SessionLastTurnDetailsSchema>;
61+
5162
export const SessionAgentReferenceSchema = z
5263
.object({
5364
type: z.literal('reference').describe('Bind the session to a named registry agent.'),

‎packages/trueforge-core/src/agent-session/schemas/turn.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,18 @@ export enum CancellationReason {
1818
Abandoned = 'abandoned',
1919
}
2020

21+
/** Every `TurnState` arm takes its `status` literal from here. */
22+
export const TurnStatusSchema = z.enum(['running', 'paused', 'done', 'cancelled', 'error']);
23+
2124
export const TurnStateRunningSchema = z
2225
.object({
23-
status: z.literal('running').describe('Turn is still executing.'),
26+
status: z.literal(TurnStatusSchema.enum.running).describe('Turn is still executing.'),
2427
})
2528
.openapi('TurnStateRunning');
2629

2730
export const TurnStatePausedSchema = z
2831
.object({
29-
status: z.literal('paused').describe('Turn is paused waiting for user actions.'),
32+
status: z.literal(TurnStatusSchema.enum.paused).describe('Turn is paused waiting for user actions.'),
3033
})
3134
.openapi('TurnStatePaused');
3235

@@ -80,7 +83,7 @@ export const TurnMetricsSchema = z
8083

8184
export const TurnStateCancelledSchema = z
8285
.object({
83-
status: z.literal('cancelled').describe('Turn was cancelled before completion.'),
86+
status: z.literal(TurnStatusSchema.enum.cancelled).describe('Turn was cancelled before completion.'),
8487
reason: TurnStateCancelledReasonSchema,
8588
completed_at: z.string().describe('ISO 8601 time when cancellation completed.'),
8689
metrics: TurnMetricsSchema.optional().describe('Optional billable aggregate for work done before cancel.'),
@@ -89,7 +92,7 @@ export const TurnStateCancelledSchema = z
8992

9093
export const TurnStateErrorSchema = z
9194
.object({
92-
status: z.literal('error').describe('Turn ended with an error.'),
95+
status: z.literal(TurnStatusSchema.enum.error).describe('Turn ended with an error.'),
9396
message: z.string().describe('Human-readable error message.'),
9497
completed_at: z.string().describe('ISO 8601 time when the error state was recorded.'),
9598
metrics: TurnMetricsSchema.optional().describe('Optional billable aggregate for work done before the error.'),
@@ -98,7 +101,7 @@ export const TurnStateErrorSchema = z
98101

99102
export const TurnStateDoneSchema = z
100103
.object({
101-
status: z.literal('done').describe('Turn finished with no open required actions.'),
104+
status: z.literal(TurnStatusSchema.enum.done).describe('Turn finished with no open required actions.'),
102105
output: z
103106
.union([ModelMessageEventSchema, z.null()])
104107
.describe('Final `model.message` for the turn, or null when the turn ended without a final message.'),

‎packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import type { SessionRecord } from '../models/SessionRecord';
55
import type { TurnRecord, TurnSnapshot } from '../models/TurnRecord';
66
import type { PersistedTurnEvent, SessionEventItem } from '../schemas/events';
77
import type { TokenPagination } from '../schemas/pagination';
8-
import { isNonTerminalTurnState, type TerminalTurnState } from '../schemas/turn';
8+
import { isNonTerminalTurnState, type TerminalTurnState, type TurnState } from '../schemas/turn';
99
import { assertCreateTurnThreadDelta } from './assertCreateTurnThreadDelta';
1010
import type {
1111
AddThreadsInput,
@@ -217,6 +217,7 @@ export class InMemorySessionStore<
217217
title: null,
218218
shared: false,
219219
last_turn_id: null,
220+
last_turn_details: null,
220221
external_id: externalId,
221222
source: input.source !== null ? deepCopy(input.source) : null,
222223
created_at: now,
@@ -433,6 +434,7 @@ export class InMemorySessionStore<
433434
this.events.set(tKey, []);
434435
stored.turnIds.push(input.turn.turn_id);
435436
stored.record.last_turn_id = input.turn.turn_id;
437+
stored.record.last_turn_details = { id: input.turn.turn_id, status: input.turn.state.status };
436438
stored.record.metrics.total_turns += 1;
437439
stored.record.last_activity_timestamp_ms = Date.now();
438440
stored.record.updated_at = new Date();
@@ -458,6 +460,7 @@ export class InMemorySessionStore<
458460
list.push(deepCopy(input.turn_done_event));
459461
}
460462
this.addTerminalSessionMetrics(input.session_id, turn.created_at, cancelledState);
463+
this.updateLastTurnDetails({ session_id: input.session_id, turn_id: input.turn_id, state: cancelledState });
461464
}
462465

463466
return deepCopy(turn);
@@ -517,6 +520,7 @@ export class InMemorySessionStore<
517520
turn.state = deepCopy(input.state);
518521
turn.updated_at = new Date();
519522
list.push(deepCopy(input.turn_update_event));
523+
this.updateLastTurnDetails(input);
520524
}
521525

522526
async updateTurnTerminalState(input: UpdateTurnTerminalStateInput): Promise<void> {
@@ -533,6 +537,7 @@ export class InMemorySessionStore<
533537
turn.updated_at = new Date();
534538
list.push(deepCopy(input.turn_done_event));
535539
this.addTerminalSessionMetrics(input.session_id, turn.created_at, input.state);
540+
this.updateLastTurnDetails(input);
536541
}
537542

538543
async appendToEvents(input: AppendToEventsInput): Promise<void> {
@@ -631,6 +636,15 @@ export class InMemorySessionStore<
631636
}
632637
}
633638

639+
/** A turn superseded by a newer last turn leaves that turn's document alone. */
640+
private updateLastTurnDetails(input: { session_id: string; turn_id: string; state: TurnState }): void {
641+
const stored = this.sessions.get(sessionKey(input.session_id));
642+
if (stored?.record.last_turn_details?.id !== input.turn_id) {
643+
return;
644+
}
645+
stored.record.last_turn_details = { id: input.turn_id, status: input.state.status };
646+
}
647+
634648
/** Cost from turn metrics when present; duration is completed_at − created_at, floored at 0. */
635649
private addTerminalSessionMetrics(sessionId: string, created_at: Date, state: TerminalTurnState): void {
636650
const stored = this.sessions.get(sessionKey(sessionId));

‎packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts‎

Lines changed: 85 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { z } from 'zod';
22
import { MAIN_THREAD_ID } from '../../../src/agent-session/models/TurnRecord';
33
import type { PersistedTurnEvent } from '../../../src/agent-session/schemas/events';
44
import { EventType } from '../../../src/agent-session/schemas/events';
5-
import { CancellationReason } from '../../../src/agent-session/schemas/turn';
5+
import { CancellationReason, type NonTerminalTurnState } from '../../../src/agent-session/schemas/turn';
66
import type { ISessionStore } from '../../../src/agent-session/store/ISessionStore';
77
import { decodeSessionEventPageToken } from '../../../src/agent-session/store/SessionEventPageToken';
88
import {
@@ -1418,6 +1418,90 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
14181418
});
14191419
});
14201420

1421+
describe('last_turn_details', () => {
1422+
async function lastTurnDetails(store: ISessionStore) {
1423+
return mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId })).last_turn_details;
1424+
}
1425+
1426+
async function setNonTerminalState(store: ISessionStore, turnId: string, state: NonTerminalTurnState) {
1427+
await store.updateTurnNonTerminalState({
1428+
active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
1429+
session_id: sessionId,
1430+
turn_id: turnId,
1431+
state,
1432+
turn_update_event: makeTurnUpdateEvent(state),
1433+
});
1434+
}
1435+
1436+
async function freezeTurn(store: ISessionStore, turnId: string) {
1437+
await store.freezeAndGetTurn({
1438+
session_id: sessionId,
1439+
turn_id: turnId,
1440+
reason: CancellationReason.ClientCancelled,
1441+
turn_done_event: makeTurnDoneEvent(makeCancelledTurnState(CancellationReason.ClientCancelled)),
1442+
});
1443+
}
1444+
1445+
it('is null before the first turn', async () => {
1446+
const store = createStore();
1447+
await seedSession(store);
1448+
expect(await lastTurnDetails(store)).toBeNull();
1449+
});
1450+
1451+
it('createTurn sets id and running status with last_turn_id', async () => {
1452+
const store = createStore();
1453+
await seedSession(store);
1454+
await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
1455+
const session = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
1456+
expect(session.last_turn_details).toEqual({ id: 'turn-1', status: 'running' });
1457+
expect(session.last_turn_id).toBe('turn-1');
1458+
});
1459+
1460+
it('follows pause, resume, and terminal transitions of the last turn', async () => {
1461+
const store = createStore();
1462+
await seedSession(store);
1463+
await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
1464+
1465+
await setNonTerminalState(store, 'turn-1', makePausedTurnState());
1466+
expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', status: 'paused' });
1467+
1468+
await setNonTerminalState(store, 'turn-1', { status: 'running' });
1469+
expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', status: 'running' });
1470+
1471+
await finishTurn(store, 'turn-1');
1472+
expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', status: 'done' });
1473+
});
1474+
1475+
it('freezeAndGetTurn records cancelled, and a repeat freeze leaves it unchanged', async () => {
1476+
const store = createStore();
1477+
await seedSession(store);
1478+
await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
1479+
await freezeTurn(store, 'turn-1');
1480+
expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', status: 'cancelled' });
1481+
await freezeTurn(store, 'turn-1');
1482+
expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', status: 'cancelled' });
1483+
});
1484+
1485+
it('a superseded turn changing status does not touch the newer last turn', async () => {
1486+
const store = createStore();
1487+
await seedSession(store);
1488+
await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
1489+
await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-2' }));
1490+
const expected = { id: 'turn-2', status: 'running' };
1491+
expect(await lastTurnDetails(store)).toEqual(expected);
1492+
1493+
await setNonTerminalState(store, 'turn-1', makePausedTurnState());
1494+
expect(await lastTurnDetails(store)).toEqual(expected);
1495+
1496+
await finishTurn(store, 'turn-1');
1497+
expect(await lastTurnDetails(store)).toEqual(expected);
1498+
1499+
await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-3' }));
1500+
await freezeTurn(store, 'turn-2');
1501+
expect(await lastTurnDetails(store)).toEqual({ id: 'turn-3', status: 'running' });
1502+
});
1503+
});
1504+
14211505
describe('createTurn', () => {
14221506
it('atomically links last_turn_id and bumps activity', async () => {
14231507
const store = createStore();
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import { sql, type Kysely } from 'kysely';
2+
3+
/**
4+
* Nullable `last_turn_details` (`{ id, status }`) on session, backfilled from the
5+
* turn `last_turn_id` points at. Sessions whose last turn row is missing stay null.
6+
*/
7+
export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
8+
await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
9+
await db.schema.alterTable('session').addColumn('last_turn_details', 'jsonb').execute();
10+
await sql`
11+
UPDATE session s
12+
SET last_turn_details = jsonb_build_object('id', t.turn_id, 'status', t.state->>'status')
13+
FROM turn t
14+
WHERE t.session_id = s.session_id
15+
AND t.turn_id = s.last_turn_id
16+
`.execute(db);
17+
}
18+
19+
export async function down<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
20+
await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
21+
await db.schema.alterTable('session').dropColumn('last_turn_details').execute();
22+
}

‎packages/trueforge/src/db/postgres/session-store/queries/sessions.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
import {
22
CreatedBySubjectSchema,
3+
SessionLastTurnDetailsSchema,
34
SessionMetadataSchema,
45
SessionSourceSchema,
56
type AgentSpec,
67
type CreatedBySubject,
8+
type SessionLastTurnDetails,
79
type SessionMetadata,
810
type SessionMetrics,
911
type SessionSource,
@@ -67,6 +69,7 @@ function mapRowToSessionRecord(row: {
6769
title: string | null;
6870
shared: boolean;
6971
last_turn_id: string | null;
72+
last_turn_details: SessionLastTurnDetails | null;
7073
external_id: string | null;
7174
custom: Record<string, unknown> | null;
7275
metadata: SessionMetadata;
@@ -89,6 +92,7 @@ function mapRowToSessionRecord(row: {
8992
title: row.title,
9093
shared: row.shared,
9194
last_turn_id: row.last_turn_id,
95+
last_turn_details: SessionLastTurnDetailsSchema.nullable().parse(row.last_turn_details),
9296
external_id: row.external_id,
9397
custom: parseSessionCustom(row.custom),
9498
metadata: parseSessionMetadata(row.metadata),

0 commit comments

Comments
 (0)