Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: store last turn id and status on session as last_turn_details (AGE-2315) (#1089)

Hary Ahujac21132e51370
diff --git a/.changeset/session-last-turn-details.md b/.changeset/session-last-turn-details.md
new file mode 100644
index 000000000..59197352e
--- /dev/null
+++ b/.changeset/session-last-turn-details.md
@@ -0,0 +1,6 @@
+---
+'@truefoundry/trueforge': patch
+'@truefoundry/trueforge-core': patch
+---
+
+Sessions now return `last_turn_details` (`{ id, state: { status } }`, null before the first turn), kept in sync as the last turn changes status. Existing sessions are backfilled.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 5826fcaf2..3ba7bba95 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -3969,6 +3969,9 @@
"description": "Unique session id.",
"type": "string"
},
+ "last_turn_details": {
+ "$ref": "#/components/schemas/SessionLastTurnDetails"
+ },
"metadata": {
"$ref": "#/components/schemas/SessionMetadata"
},
@@ -4004,7 +4007,8 @@
"updated_at",
"metrics",
"metadata",
- "source"
+ "source",
+ "last_turn_details"
],
"type": "object"
},
@@ -4188,6 +4192,39 @@
],
"type": "object"
},
+ "SessionLastTurnDetails": {
+ "additionalProperties": false,
+ "description": "The session's most recent turn; null until the first turn.",
+ "properties": {
+ "id": {
+ "description": "Id of the last turn.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "state": {
+ "$ref": "#/components/schemas/SessionLastTurnState"
+ }
+ },
+ "required": [
+ "id",
+ "state"
+ ],
+ "type": [
+ "object",
+ "null"
+ ]
+ },
+ "SessionLastTurnState": {
+ "properties": {
+ "status": {
+ "$ref": "#/components/schemas/TurnStatus"
+ }
+ },
+ "required": [
+ "status"
+ ],
+ "type": "object"
+ },
"SessionMetadata": {
"additionalProperties": {
"description": "Metadata value; at most 128 characters.",
@@ -5586,6 +5623,16 @@
],
"type": "object"
},
+ "TurnStatus": {
+ "enum": [
+ "running",
+ "paused",
+ "done",
+ "cancelled",
+ "error"
+ ],
+ "type": "string"
+ },
"TurnStreamingEvent": {
"discriminator": {
"mapping": {
diff --git a/docs/openapi.json b/docs/openapi.json
index 5826fcaf2..3ba7bba95 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -3969,6 +3969,9 @@
"description": "Unique session id.",
"type": "string"
},
+ "last_turn_details": {
+ "$ref": "#/components/schemas/SessionLastTurnDetails"
+ },
"metadata": {
"$ref": "#/components/schemas/SessionMetadata"
},
@@ -4004,7 +4007,8 @@
"updated_at",
"metrics",
"metadata",
- "source"
+ "source",
+ "last_turn_details"
],
"type": "object"
},
@@ -4188,6 +4192,39 @@
],
"type": "object"
},
+ "SessionLastTurnDetails": {
+ "additionalProperties": false,
+ "description": "The session's most recent turn; null until the first turn.",
+ "properties": {
+ "id": {
+ "description": "Id of the last turn.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "state": {
+ "$ref": "#/components/schemas/SessionLastTurnState"
+ }
+ },
+ "required": [
+ "id",
+ "state"
+ ],
+ "type": [
+ "object",
+ "null"
+ ]
+ },
+ "SessionLastTurnState": {
+ "properties": {
+ "status": {
+ "$ref": "#/components/schemas/TurnStatus"
+ }
+ },
+ "required": [
+ "status"
+ ],
+ "type": "object"
+ },
"SessionMetadata": {
"additionalProperties": {
"description": "Metadata value; at most 128 characters.",
@@ -5586,6 +5623,16 @@
],
"type": "object"
},
+ "TurnStatus": {
+ "enum": [
+ "running",
+ "paused",
+ "done",
+ "cancelled",
+ "error"
+ ],
+ "type": "string"
+ },
"TurnStreamingEvent": {
"discriminator": {
"mapping": {
diff --git a/packages/trueforge-core/src/agent-session/index.ts b/packages/trueforge-core/src/agent-session/index.ts
index 1d05a2160..5e250c809 100644
--- a/packages/trueforge-core/src/agent-session/index.ts
+++ b/packages/trueforge-core/src/agent-session/index.ts
@@ -34,6 +34,7 @@ export type {
} from './schemas/turn';
export {
+ SessionLastTurnDetailsSchema,
SessionMetadataSchema,
SessionMetricsSchema,
SessionSchema,
@@ -44,6 +45,7 @@ export {
export type {
Session,
SessionAgent,
+ SessionLastTurnDetails,
SessionMetadata,
SessionMetrics,
SessionSource,
diff --git a/packages/trueforge-core/src/agent-session/models/SessionRecord.ts b/packages/trueforge-core/src/agent-session/models/SessionRecord.ts
index 6258a85b9..c35ea685b 100644
--- a/packages/trueforge-core/src/agent-session/models/SessionRecord.ts
+++ b/packages/trueforge-core/src/agent-session/models/SessionRecord.ts
@@ -1,4 +1,10 @@
-import type { SessionAgent, SessionMetadata, SessionMetrics, SessionSource } from '../schemas/session';
+import type {
+ SessionAgent,
+ SessionLastTurnDetails,
+ SessionMetadata,
+ SessionMetrics,
+ SessionSource,
+} from '../schemas/session';
import type { CreatedBySubject } from '../schemas/subject';
/**
@@ -36,6 +42,7 @@ export interface SessionRecord<TCustom extends object = Record<string, never>> {
* listing anchors. Advanced only by `createTurn` (atomic link).
*/
last_turn_id: string | null;
+ last_turn_details: SessionLastTurnDetails | null;
/** Instant the session was created (store domain). Wire/API serialize as ISO-8601. */
created_at: Date;
/** Instant the session was last updated (store domain). Wire/API serialize as ISO-8601. */
diff --git a/packages/trueforge-core/src/agent-session/schemas/session.ts b/packages/trueforge-core/src/agent-session/schemas/session.ts
index 94ac131f8..79af42540 100644
--- a/packages/trueforge-core/src/agent-session/schemas/session.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/session.ts
@@ -5,6 +5,7 @@
import { z } from '@hono/zod-openapi';
import { AgentSpecSchema } from './agentSpec';
import { CreatedBySubjectSchema } from './subject';
+import { TurnStatusSchema } from './turn';
const SESSION_METADATA_MAX_KEY_LENGTH = 32;
/**
@@ -48,6 +49,21 @@ export const SessionMetricsSchema = z
.describe('Rolled-up cost, duration, and turn counters for a session.')
.openapi('SessionMetrics');
+/** Not strict: parsing a full turn state keeps only the fields listed here. */
+export const SessionLastTurnStateSchema = z.object({ status: TurnStatusSchema }).openapi('SessionLastTurnState');
+
+/** The session's last turn, always written as one document. */
+export const SessionLastTurnDetailsSchema = z
+ .object({
+ id: z.string().min(1).describe('Id of the last turn.'),
+ state: SessionLastTurnStateSchema,
+ })
+ .strict()
+ .describe("The session's most recent turn; null until the first turn.")
+ .openapi('SessionLastTurnDetails');
+
+export type SessionLastTurnDetails = z.infer<typeof SessionLastTurnDetailsSchema>;
+
export const SessionAgentReferenceSchema = z
.object({
type: z.literal('reference').describe('Bind the session to a named registry agent.'),
@@ -114,6 +130,7 @@ export const SessionSchema = z
metrics: SessionMetricsSchema,
metadata: SessionMetadataSchema,
source: SessionSourceSchema.nullable(),
+ last_turn_details: SessionLastTurnDetailsSchema.nullable(),
})
.openapi('Session');
diff --git a/packages/trueforge-core/src/agent-session/schemas/turn.ts b/packages/trueforge-core/src/agent-session/schemas/turn.ts
index 700e44787..4a13c1cba 100644
--- a/packages/trueforge-core/src/agent-session/schemas/turn.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/turn.ts
@@ -22,9 +22,12 @@ export enum CancellationReason {
Abandoned = 'abandoned',
}
+/** Every `TurnState` arm takes its `status` literal from here. */
+export const TurnStatusSchema = z.enum(['running', 'paused', 'done', 'cancelled', 'error']).openapi('TurnStatus');
+
export const TurnStateRunningSchema = z
.object({
- status: z.literal('running').describe('Turn is still executing.'),
+ status: z.literal(TurnStatusSchema.enum.running).describe('Turn is still executing.'),
})
.openapi('TurnStateRunning');
@@ -36,7 +39,7 @@ export const ActionRequiredSchema = z
export const TurnStatePausedSchema = z
.object({
- status: z.literal('paused').describe('Turn is paused waiting for required actions.'),
+ status: z.literal(TurnStatusSchema.enum.paused).describe('Turn is paused waiting for required actions.'),
action_required_on_events: z
.array(ActionRequiredSchema)
.describe('Events that still need a user or client action.'),
@@ -93,7 +96,7 @@ export const TurnMetricsSchema = z
export const TurnStateCancelledSchema = z
.object({
- status: z.literal('cancelled').describe('Turn was cancelled before completion.'),
+ status: z.literal(TurnStatusSchema.enum.cancelled).describe('Turn was cancelled before completion.'),
reason: TurnStateCancelledReasonSchema,
completed_at: z.string().describe('ISO 8601 time when cancellation completed.'),
metrics: TurnMetricsSchema.optional().describe('Optional billable aggregate for work done before cancel.'),
@@ -102,7 +105,7 @@ export const TurnStateCancelledSchema = z
export const TurnStateErrorSchema = z
.object({
- status: z.literal('error').describe('Turn ended with an error.'),
+ status: z.literal(TurnStatusSchema.enum.error).describe('Turn ended with an error.'),
message: z.string().describe('Human-readable error message.'),
completed_at: z.string().describe('ISO 8601 time when the error state was recorded.'),
metrics: TurnMetricsSchema.optional().describe('Optional billable aggregate for work done before the error.'),
@@ -111,7 +114,7 @@ export const TurnStateErrorSchema = z
export const TurnStateDoneSchema = z
.object({
- status: z.literal('done').describe('Turn finished with no open required actions.'),
+ status: z.literal(TurnStatusSchema.enum.done).describe('Turn finished with no open required actions.'),
output: z
.union([ModelMessageEventSchema, z.null()])
.describe('Final `model.message` for the turn, or null when the turn ended without a final message.'),
diff --git a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
index 4f11e3e8f..1ecef8382 100644
--- a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
+++ b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
@@ -4,7 +4,13 @@ import type { SessionRecord } from '../models/SessionRecord';
import type { TurnRecord, TurnSnapshot } from '../models/TurnRecord';
import type { PersistedTurnEvent, SessionEventItem } from '../schemas/events';
import type { TokenPagination } from '../schemas/pagination';
-import { isNonTerminalTurnState, type TerminalTurnState, type TurnInboundEventItem } from '../schemas/turn';
+import { SessionLastTurnDetailsSchema } from '../schemas/session';
+import {
+ isNonTerminalTurnState,
+ type TerminalTurnState,
+ type TurnInboundEventItem,
+ type TurnState,
+} from '../schemas/turn';
import { assertCreateTurnThreadDelta } from './assertCreateTurnThreadDelta';
import type {
AddThreadsInput,
@@ -209,6 +215,7 @@ export class InMemorySessionStore<
title: null,
shared: false,
last_turn_id: null,
+ last_turn_details: null,
external_id: externalId,
source: input.source !== null ? deepCopy(input.source) : null,
created_at: now,
@@ -425,6 +432,10 @@ export class InMemorySessionStore<
this.events.set(tKey, []);
stored.turnIds.push(input.turn.turn_id);
stored.record.last_turn_id = input.turn.turn_id;
+ stored.record.last_turn_details = SessionLastTurnDetailsSchema.parse({
+ id: input.turn.turn_id,
+ state: input.turn.state,
+ });
stored.record.metrics.total_turns += 1;
stored.record.last_activity_timestamp_ms = Date.now();
stored.record.updated_at = new Date();
@@ -449,7 +460,12 @@ export class InMemorySessionStore<
if (list) {
list.push(deepCopy(input.turn_done_event));
}
- this.addTerminalSessionMetrics(input.session_id, turn.created_at, cancelledState);
+ this.applyTurnStateToSession({
+ id: input.session_id,
+ turn_id: input.turn_id,
+ turn_created_at: turn.created_at,
+ turn_state: cancelledState,
+ });
}
return deepCopy(turn);
@@ -499,6 +515,12 @@ export class InMemorySessionStore<
turn.state = deepCopy(input.state);
turn.updated_at = new Date();
list.push(deepCopy(input.turn_update_event));
+ this.applyTurnStateToSession({
+ id: input.session_id,
+ turn_id: input.turn_id,
+ turn_created_at: turn.created_at,
+ turn_state: input.state,
+ });
}
async updateTurnTerminalState(input: UpdateTurnTerminalStateInput): Promise<void> {
@@ -514,7 +536,12 @@ export class InMemorySessionStore<
turn.state = deepCopy(input.state);
turn.updated_at = new Date();
list.push(deepCopy(input.turn_done_event));
- this.addTerminalSessionMetrics(input.session_id, turn.created_at, input.state);
+ this.applyTurnStateToSession({
+ id: input.session_id,
+ turn_id: input.turn_id,
+ turn_created_at: turn.created_at,
+ turn_state: input.state,
+ });
}
async appendToEvents(input: AppendToEventsInput): Promise<void> {
@@ -562,18 +589,28 @@ export class InMemorySessionStore<
}
}
- /** Cost from turn metrics when present; duration is completed_at − created_at, floored at 0. */
- private addTerminalSessionMetrics(sessionId: string, created_at: Date, state: TerminalTurnState): void {
- const stored = this.sessions.get(sessionKey(sessionId));
- if (!stored) {
- throw new SessionNotFoundError(sessionId);
+ /** Terminal states fold cost and duration; last_turn_details moves only for the session's last turn. */
+ private applyTurnStateToSession(input: {
+ id: string;
+ turn_id: string;
+ turn_created_at: Date;
+ turn_state: TurnState;
+ }): void {
+ const stored = this.requireSession(input.id);
+ if (!isNonTerminalTurnState(input.turn_state)) {
+ const elapsed_ms = Date.parse(input.turn_state.completed_at) - input.turn_created_at.getTime();
+ const turnCost = input.turn_state.metrics?.total_cost_in_usd;
+ if (turnCost !== undefined) {
+ stored.record.metrics.total_cost_in_usd = (stored.record.metrics.total_cost_in_usd ?? 0) + turnCost;
+ }
+ stored.record.metrics.total_duration_ms += elapsed_ms > 0 ? Math.trunc(elapsed_ms) : 0;
}
- const elapsed_ms = Date.parse(state.completed_at) - created_at.getTime();
- const turnCost = state.metrics?.total_cost_in_usd;
- if (turnCost !== undefined) {
- stored.record.metrics.total_cost_in_usd = (stored.record.metrics.total_cost_in_usd ?? 0) + turnCost;
+ if (stored.record.last_turn_details?.id === input.turn_id) {
+ stored.record.last_turn_details = SessionLastTurnDetailsSchema.parse({
+ id: input.turn_id,
+ state: input.turn_state,
+ });
}
- stored.record.metrics.total_duration_ms += elapsed_ms > 0 ? Math.trunc(elapsed_ms) : 0;
}
private requireSession(sessionId: string): StoredSession<TSessionCustom> {
diff --git a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
index 48532d783..6230ac157 100644
--- a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
+++ b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
@@ -2,7 +2,7 @@ import { z } from 'zod';
import { MAIN_THREAD_ID } from '../../../src/agent-session/models/TurnRecord';
import type { PersistedTurnEvent } from '../../../src/agent-session/schemas/events';
import { EventType } from '../../../src/agent-session/schemas/events';
-import { CancellationReason } from '../../../src/agent-session/schemas/turn';
+import { CancellationReason, type NonTerminalTurnState } from '../../../src/agent-session/schemas/turn';
import type { ISessionStore } from '../../../src/agent-session/store/ISessionStore';
import { decodeSessionEventPageToken } from '../../../src/agent-session/store/SessionEventPageToken';
import {
@@ -1375,6 +1375,112 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
});
});
+ describe('last_turn_details', () => {
+ async function lastTurnDetails(store: ISessionStore) {
+ return mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId })).last_turn_details;
+ }
+
+ async function setNonTerminalState(store: ISessionStore, turnId: string, state: NonTerminalTurnState) {
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: turnId,
+ state,
+ turn_update_event: makeTurnUpdateEvent(state),
+ });
+ }
+
+ async function freezeTurn(store: ISessionStore, turnId: string) {
+ await store.freezeAndGetTurn({
+ session_id: sessionId,
+ turn_id: turnId,
+ reason: CancellationReason.ClientCancelled,
+ turn_done_event: makeTurnDoneEvent(makeCancelledTurnState(CancellationReason.ClientCancelled)),
+ });
+ }
+
+ it('is null before the first turn', async () => {
+ const store = createStore();
+ await seedSession(store);
+ expect(await lastTurnDetails(store)).toBeNull();
+ });
+
+ it('createTurn sets id and running status with last_turn_id', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const session = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
+ expect(session.last_turn_details).toEqual({ id: 'turn-1', state: { status: 'running' } });
+ expect(session.last_turn_id).toBe('turn-1');
+ });
+
+ it('follows pause, resume, and terminal transitions of the last turn', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+
+ await setNonTerminalState(store, 'turn-1', makePausedTurnState());
+ expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', state: { status: 'paused' } });
+
+ await setNonTerminalState(store, 'turn-1', { status: 'running' });
+ expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', state: { status: 'running' } });
+
+ await finishTurn(store, 'turn-1');
+ expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', state: { status: 'done' } });
+ });
+
+ it('freezeAndGetTurn records cancelled, and a repeat freeze leaves it unchanged', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ await freezeTurn(store, 'turn-1');
+ expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', state: { status: 'cancelled' } });
+ await freezeTurn(store, 'turn-1');
+ expect(await lastTurnDetails(store)).toEqual({ id: 'turn-1', state: { status: 'cancelled' } });
+ });
+
+ it('a superseded turn changing status does not touch the newer last turn', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-2' }));
+ const expected = { id: 'turn-2', state: { status: 'running' } };
+ expect(await lastTurnDetails(store)).toEqual(expected);
+
+ await setNonTerminalState(store, 'turn-1', makePausedTurnState());
+ expect(await lastTurnDetails(store)).toEqual(expected);
+
+ await finishTurn(store, 'turn-1');
+ expect(await lastTurnDetails(store)).toEqual(expected);
+
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-3' }));
+ await freezeTurn(store, 'turn-2');
+ expect(await lastTurnDetails(store)).toEqual({ id: 'turn-3', state: { status: 'running' } });
+ });
+
+ it('a superseded turn finishing still adds its cost and duration to session metrics', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-2' }));
+ const turn1 = mustGet(await store.getTurn({ session_id: sessionId, turn_id: 'turn-1' }));
+ const doneState = {
+ ...makeDoneTurnState(),
+ completed_at: new Date(turn1.created_at.getTime() + 1500).toISOString(),
+ metrics: { total_cost_in_usd: 1.25 },
+ };
+ await store.updateTurnTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: doneState,
+ turn_done_event: makeTurnDoneEvent(doneState),
+ });
+
+ const session = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
+ expect(session.last_turn_details).toEqual({ id: 'turn-2', state: { status: 'running' } });
+ expect(session.metrics).toEqual({ total_cost_in_usd: 1.25, total_duration_ms: 1500, total_turns: 2 });
+ });
+ });
+
describe('createTurn', () => {
it('atomically links last_turn_id and bumps activity', async () => {
const store = createStore();
diff --git a/packages/trueforge-sdk/src/api/types/Session.ts b/packages/trueforge-sdk/src/api/types/Session.ts
index 7d3a0614e..62d493532 100644
--- a/packages/trueforge-sdk/src/api/types/Session.ts
+++ b/packages/trueforge-sdk/src/api/types/Session.ts
@@ -9,6 +9,7 @@ export interface Session {
createdBySubject: TrueForge.CreatedBySubject;
/** Unique session id. */
id: string;
+ lastTurnDetails: TrueForge.SessionLastTurnDetails | null;
metadata: TrueForge.SessionMetadata;
metrics: TrueForge.SessionMetrics;
/** When true, any subject in the tenant may read this session and its turns/events by id. */
diff --git a/packages/trueforge-sdk/src/api/types/SessionLastTurnDetails.ts b/packages/trueforge-sdk/src/api/types/SessionLastTurnDetails.ts
new file mode 100644
index 000000000..8b0004ad4
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SessionLastTurnDetails.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+/**
+ * The session's most recent turn; null until the first turn.
+ */
+export interface SessionLastTurnDetails {
+ /** Id of the last turn. */
+ id: string;
+ state: TrueForge.SessionLastTurnState;
+}
diff --git a/packages/trueforge-sdk/src/api/types/SessionLastTurnState.ts b/packages/trueforge-sdk/src/api/types/SessionLastTurnState.ts
new file mode 100644
index 000000000..1bc41d500
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/SessionLastTurnState.ts
@@ -0,0 +1,7 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface SessionLastTurnState {
+ status: TrueForge.TurnStatus;
+}
diff --git a/packages/trueforge-sdk/src/api/types/TurnStatus.ts b/packages/trueforge-sdk/src/api/types/TurnStatus.ts
new file mode 100644
index 000000000..c910e3d88
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/TurnStatus.ts
@@ -0,0 +1,10 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export const TurnStatus = {
+ Running: "running",
+ Paused: "paused",
+ Done: "done",
+ Cancelled: "cancelled",
+ Error: "error",
+} as const;
+export type TurnStatus = (typeof TurnStatus)[keyof typeof TurnStatus];
diff --git a/packages/trueforge-sdk/src/api/types/index.ts b/packages/trueforge-sdk/src/api/types/index.ts
index e05a49b08..b0997baeb 100644
--- a/packages/trueforge-sdk/src/api/types/index.ts
+++ b/packages/trueforge-sdk/src/api/types/index.ts
@@ -192,6 +192,8 @@ export * from "./SessionAgentReference.js";
export * from "./SessionAgentSpecBody.js";
export * from "./SessionEvent.js";
export * from "./SessionEventItem.js";
+export * from "./SessionLastTurnDetails.js";
+export * from "./SessionLastTurnState.js";
export * from "./SessionMetadata.js";
export * from "./SessionMetrics.js";
export * from "./SessionMetricsChart.js";
@@ -249,6 +251,7 @@ export * from "./TurnStateError.js";
export * from "./TurnStateErrorMetrics.js";
export * from "./TurnStatePaused.js";
export * from "./TurnStateRunning.js";
+export * from "./TurnStatus.js";
export * from "./TurnStreamingEvent.js";
export * from "./TurnUpdateEvent.js";
export * from "./TurnUpdateEventState.js";
diff --git a/packages/trueforge-sdk/src/serialization/types/Session.ts b/packages/trueforge-sdk/src/serialization/types/Session.ts
index 6be95d0e0..d2018d2e4 100644
--- a/packages/trueforge-sdk/src/serialization/types/Session.ts
+++ b/packages/trueforge-sdk/src/serialization/types/Session.ts
@@ -5,6 +5,7 @@ import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
import { CreatedBySubject } from "./CreatedBySubject.js";
import { SessionAgent } from "./SessionAgent.js";
+import { SessionLastTurnDetails } from "./SessionLastTurnDetails.js";
import { SessionMetadata } from "./SessionMetadata.js";
import { SessionMetrics } from "./SessionMetrics.js";
import { SessionSource } from "./SessionSource.js";
@@ -15,6 +16,7 @@ export const Session: core.serialization.ObjectSchema<serializers.Session.Raw, T
createdAt: core.serialization.property("created_at", core.serialization.string()),
createdBySubject: core.serialization.property("created_by_subject", CreatedBySubject),
id: core.serialization.string(),
+ lastTurnDetails: core.serialization.property("last_turn_details", SessionLastTurnDetails.nullable()),
metadata: SessionMetadata,
metrics: SessionMetrics,
shared: core.serialization.boolean(),
@@ -29,6 +31,7 @@ export declare namespace Session {
created_at: string;
created_by_subject: CreatedBySubject.Raw;
id: string;
+ last_turn_details?: SessionLastTurnDetails.Raw | null;
metadata: SessionMetadata.Raw;
metrics: SessionMetrics.Raw;
shared: boolean;
diff --git a/packages/trueforge-sdk/src/serialization/types/SessionLastTurnDetails.ts b/packages/trueforge-sdk/src/serialization/types/SessionLastTurnDetails.ts
new file mode 100644
index 000000000..1836fc373
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SessionLastTurnDetails.ts
@@ -0,0 +1,21 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { SessionLastTurnState } from "./SessionLastTurnState.js";
+
+export const SessionLastTurnDetails: core.serialization.ObjectSchema<
+ serializers.SessionLastTurnDetails.Raw,
+ TrueForge.SessionLastTurnDetails
+> = core.serialization.object({
+ id: core.serialization.string(),
+ state: SessionLastTurnState,
+});
+
+export declare namespace SessionLastTurnDetails {
+ export interface Raw {
+ id: string;
+ state: SessionLastTurnState.Raw;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SessionLastTurnState.ts b/packages/trueforge-sdk/src/serialization/types/SessionLastTurnState.ts
new file mode 100644
index 000000000..a0fd1b417
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/SessionLastTurnState.ts
@@ -0,0 +1,19 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { TurnStatus } from "./TurnStatus.js";
+
+export const SessionLastTurnState: core.serialization.ObjectSchema<
+ serializers.SessionLastTurnState.Raw,
+ TrueForge.SessionLastTurnState
+> = core.serialization.object({
+ status: TurnStatus,
+});
+
+export declare namespace SessionLastTurnState {
+ export interface Raw {
+ status: TurnStatus.Raw;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/TurnStatus.ts b/packages/trueforge-sdk/src/serialization/types/TurnStatus.ts
new file mode 100644
index 000000000..27c083c99
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/TurnStatus.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const TurnStatus: core.serialization.Schema<serializers.TurnStatus.Raw, TrueForge.TurnStatus> =
+ core.serialization.enum_(["running", "paused", "done", "cancelled", "error"]);
+
+export declare namespace TurnStatus {
+ export type Raw = "running" | "paused" | "done" | "cancelled" | "error";
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/index.ts b/packages/trueforge-sdk/src/serialization/types/index.ts
index e05a49b08..b0997baeb 100644
--- a/packages/trueforge-sdk/src/serialization/types/index.ts
+++ b/packages/trueforge-sdk/src/serialization/types/index.ts
@@ -192,6 +192,8 @@ export * from "./SessionAgentReference.js";
export * from "./SessionAgentSpecBody.js";
export * from "./SessionEvent.js";
export * from "./SessionEventItem.js";
+export * from "./SessionLastTurnDetails.js";
+export * from "./SessionLastTurnState.js";
export * from "./SessionMetadata.js";
export * from "./SessionMetrics.js";
export * from "./SessionMetricsChart.js";
@@ -249,6 +251,7 @@ export * from "./TurnStateError.js";
export * from "./TurnStateErrorMetrics.js";
export * from "./TurnStatePaused.js";
export * from "./TurnStateRunning.js";
+export * from "./TurnStatus.js";
export * from "./TurnStreamingEvent.js";
export * from "./TurnUpdateEvent.js";
export * from "./TurnUpdateEventState.js";
diff --git a/packages/trueforge-sdk/tests/wire/internal/sessions.test.ts b/packages/trueforge-sdk/tests/wire/internal/sessions.test.ts
index 3244cfc18..927d1c7e8 100644
--- a/packages/trueforge-sdk/tests/wire/internal/sessions.test.ts
+++ b/packages/trueforge-sdk/tests/wire/internal/sessions.test.ts
@@ -19,6 +19,7 @@ describe("SessionsClient", () => {
subject_type: "subject_type",
},
id: "id",
+ last_turn_details: { id: "id", state: { status: "running" } },
metadata: { key: "value" },
metrics: { total_cost_in_usd: 1.1, total_duration_ms: 1, total_turns: 1 },
shared: true,
@@ -60,6 +61,12 @@ describe("SessionsClient", () => {
subjectType: "subject_type",
},
id: "id",
+ lastTurnDetails: {
+ id: "id",
+ state: {
+ status: "running",
+ },
+ },
metadata: {
key: "value",
},
diff --git a/packages/trueforge-sdk/tests/wire/sessions.test.ts b/packages/trueforge-sdk/tests/wire/sessions.test.ts
index bdd8e61fc..4bad42ddc 100644
--- a/packages/trueforge-sdk/tests/wire/sessions.test.ts
+++ b/packages/trueforge-sdk/tests/wire/sessions.test.ts
@@ -20,6 +20,7 @@ describe("SessionsClient", () => {
subject_type: "subject_type",
},
id: "id",
+ last_turn_details: { id: "id", state: { status: "running" } },
metadata: { key: "value" },
metrics: { total_duration_ms: 1, total_turns: 1 },
shared: true,
@@ -57,6 +58,12 @@ describe("SessionsClient", () => {
subjectType: "subject_type",
},
id: "id",
+ lastTurnDetails: {
+ id: "id",
+ state: {
+ status: "running",
+ },
+ },
metadata: {
key: "value",
},
@@ -115,6 +122,7 @@ describe("SessionsClient", () => {
subject_type: "subject_type",
},
id: "id",
+ last_turn_details: { id: "id", state: { status: "running" } },
metadata: { key: "value" },
metrics: { total_cost_in_usd: 1.1, total_duration_ms: 1, total_turns: 1 },
shared: true,
@@ -155,6 +163,12 @@ describe("SessionsClient", () => {
subjectType: "subject_type",
},
id: "id",
+ lastTurnDetails: {
+ id: "id",
+ state: {
+ status: "running",
+ },
+ },
metadata: {
key: "value",
},
@@ -261,6 +275,7 @@ describe("SessionsClient", () => {
subject_type: "subject_type",
},
id: "id",
+ last_turn_details: { id: "id", state: { status: "running" } },
metadata: { key: "value" },
metrics: { total_cost_in_usd: 1.1, total_duration_ms: 1, total_turns: 1 },
shared: true,
@@ -296,6 +311,12 @@ describe("SessionsClient", () => {
subjectType: "subject_type",
},
id: "id",
+ lastTurnDetails: {
+ id: "id",
+ state: {
+ status: "running",
+ },
+ },
metadata: {
key: "value",
},
@@ -397,6 +418,7 @@ describe("SessionsClient", () => {
subject_type: "subject_type",
},
id: "id",
+ last_turn_details: { id: "id", state: { status: "running" } },
metadata: { key: "value" },
metrics: { total_cost_in_usd: 1.1, total_duration_ms: 1, total_turns: 1 },
shared: true,
@@ -433,6 +455,12 @@ describe("SessionsClient", () => {
subjectType: "subject_type",
},
id: "id",
+ lastTurnDetails: {
+ id: "id",
+ state: {
+ status: "running",
+ },
+ },
metadata: {
key: "value",
},
diff --git a/packages/trueforge/src/apis/sessions.ts b/packages/trueforge/src/apis/sessions.ts
index 5890b7a48..28209b824 100644
--- a/packages/trueforge/src/apis/sessions.ts
+++ b/packages/trueforge/src/apis/sessions.ts
@@ -80,6 +80,7 @@ export function toWireSession(record: SessionRecord): Session {
metrics: record.metrics,
metadata: record.metadata,
source: record.source,
+ last_turn_details: record.last_turn_details,
};
}
diff --git a/packages/trueforge/src/db/postgres/migrations/20261018_000001_session_last_turn_details.ts b/packages/trueforge/src/db/postgres/migrations/20261018_000001_session_last_turn_details.ts
new file mode 100644
index 000000000..533520035
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20261018_000001_session_last_turn_details.ts
@@ -0,0 +1,25 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Nullable `last_turn_details` (`{ id, state: { status } }`) on session, backfilled from
+ * the turn `last_turn_id` points at. Sessions whose last turn row is missing stay null.
+ */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await db.schema.alterTable('session').addColumn('last_turn_details', 'jsonb').execute();
+ await sql`
+ UPDATE session s
+ SET last_turn_details = jsonb_build_object(
+ 'id', t.turn_id,
+ 'state', jsonb_build_object('status', t.state->'status')
+ )
+ FROM turn t
+ WHERE t.session_id = s.session_id
+ AND t.turn_id = s.last_turn_id
+ `.execute(db);
+}
+
+export async function down<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await db.schema.alterTable('session').dropColumn('last_turn_details').execute();
+}
diff --git a/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts b/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts
index 542fe7c59..2b998e226 100644
--- a/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts
+++ b/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts
@@ -1,9 +1,11 @@
import {
CreatedBySubjectSchema,
+ SessionLastTurnDetailsSchema,
SessionMetadataSchema,
SessionSourceSchema,
type AgentSpec,
type CreatedBySubject,
+ type SessionLastTurnDetails,
type SessionMetadata,
type SessionMetrics,
type SessionSource,
@@ -67,6 +69,7 @@ function mapRowToSessionRecord(row: {
title: string | null;
shared: boolean;
last_turn_id: string | null;
+ last_turn_details: SessionLastTurnDetails | null;
external_id: string | null;
custom: Record<string, unknown> | null;
metadata: SessionMetadata;
@@ -89,6 +92,7 @@ function mapRowToSessionRecord(row: {
title: row.title,
shared: row.shared,
last_turn_id: row.last_turn_id,
+ last_turn_details: SessionLastTurnDetailsSchema.nullable().parse(row.last_turn_details),
external_id: row.external_id,
custom: parseSessionCustom(row.custom),
metadata: parseSessionMetadata(row.metadata),
diff --git a/packages/trueforge/src/db/postgres/session-store/queries/turns.ts b/packages/trueforge/src/db/postgres/session-store/queries/turns.ts
index 977a49d8c..ef900b8e4 100644
--- a/packages/trueforge/src/db/postgres/session-store/queries/turns.ts
+++ b/packages/trueforge/src/db/postgres/session-store/queries/turns.ts
@@ -1,4 +1,8 @@
-import type { SessionMetrics } from '@truefoundry/trueforge-core/agent-session';
+import {
+ SessionLastTurnDetailsSchema,
+ type SessionLastTurnDetails,
+ type SessionMetrics,
+} from '@truefoundry/trueforge-core/agent-session';
import type { TurnRecord, TurnSnapshot } from '@truefoundry/trueforge-core/agent-session/models/TurnRecord';
import {
isNonTerminalTurnState,
@@ -127,33 +131,44 @@ function incrementSessionTotalTurns(): RawBuilder<SessionMetrics> {
);
}
-/** Same tx as the turn flip; the session row lock serializes concurrent terminal folds. */
-async function addSessionCostAndDuration(
+function lastTurnDetails(input: { turn_id: string; turn_state: TurnState }): RawBuilder<SessionLastTurnDetails> {
+ return json(SessionLastTurnDetailsSchema.parse({ id: input.turn_id, state: input.turn_state }));
+}
+
+/** Terminal states fold cost and duration; last_turn_details moves only for the session's last turn. */
+async function applyTurnStateToSession(
trx: Transaction<Database>,
- input: { session_id: string; turn_created_at: Date; turn_state: TerminalTurnState },
+ input: { id: string; turn_id: string; turn_created_at: Date; turn_state: TurnState },
): Promise<void> {
- const elapsed_ms = Date.parse(input.turn_state.completed_at) - input.turn_created_at.getTime();
- const total_duration_ms = elapsed_ms > 0 ? Math.trunc(elapsed_ms) : 0;
- const turnCost = input.turn_state.metrics?.total_cost_in_usd;
- // bigint: ::int overflows at ~24.8 days of summed ms and would roll back the terminal tx.
- const withDuration = jsonbSet<SessionMetrics>(
- sql`metrics`,
- sql`'{total_duration_ms}'`,
- sql`to_jsonb((metrics->>'total_duration_ms')::bigint + ${total_duration_ms}::bigint)`,
- );
+ let metrics: RawBuilder<SessionMetrics> | undefined;
+ if (!isNonTerminalTurnState(input.turn_state)) {
+ const elapsed_ms = Date.parse(input.turn_state.completed_at) - input.turn_created_at.getTime();
+ const total_duration_ms = elapsed_ms > 0 ? Math.trunc(elapsed_ms) : 0;
+ const turnCost = input.turn_state.metrics?.total_cost_in_usd;
+ // bigint: ::int overflows at ~24.8 days of summed ms and would roll back the terminal tx.
+ metrics = jsonbSet<SessionMetrics>(
+ sql`metrics`,
+ sql`'{total_duration_ms}'`,
+ sql`to_jsonb((metrics->>'total_duration_ms')::bigint + ${total_duration_ms}::bigint)`,
+ );
+ if (turnCost !== undefined) {
+ metrics = jsonbSet<SessionMetrics>(
+ metrics,
+ sql`'{total_cost_in_usd}'`,
+ sql`to_jsonb(COALESCE((metrics->>'total_cost_in_usd')::double precision, 0) + ${turnCost}::double precision)`,
+ );
+ }
+ }
await trx
.updateTable('session')
.set({
- metrics:
- turnCost === undefined
- ? withDuration
- : jsonbSet<SessionMetrics>(
- withDuration,
- sql`'{total_cost_in_usd}'`,
- sql`to_jsonb(COALESCE((metrics->>'total_cost_in_usd')::double precision, 0) + ${turnCost}::double precision)`,
- ),
+ last_turn_details: sql<SessionLastTurnDetails>`CASE
+ WHEN last_turn_details->>'id' = ${input.turn_id} THEN ${lastTurnDetails(input)}
+ ELSE last_turn_details
+ END`,
+ ...(metrics === undefined ? {} : { metrics }),
})
- .where('session_id', '=', input.session_id)
+ .where('session_id', '=', input.id)
.execute();
}
@@ -432,6 +447,7 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
.updateTable('session')
.set({
last_turn_id: input.turn.turn_id,
+ last_turn_details: lastTurnDetails({ turn_id: input.turn.turn_id, turn_state: input.turn.state }),
updated_at: sql`now()`,
last_activity_timestamp_ms: input.last_activity_timestamp_ms,
// total_turns rides the same tip UPDATE so a later failure in this tx rolls it back.
@@ -692,8 +708,9 @@ export async function freezeAndGetTurn(db: Kysely<Database>, input: FreezeAndGet
})
.execute();
// Only the winning cancel folds; a freeze of an already-terminal turn is a read.
- await addSessionCostAndDuration(trx, {
- session_id: input.session_id,
+ await applyTurnStateToSession(trx, {
+ id: input.session_id,
+ turn_id: input.turn_id,
turn_created_at: updateResult.created_at,
turn_state: cancelledState,
});
@@ -774,7 +791,7 @@ export async function updateTurnNonTerminalState(
.where('session_id', '=', input.session_id)
.where('turn_id', '=', input.turn_id)
.where(sql<boolean>`state->>'status' = ${expectedSourceStatus}`)
- .returning('turn_id')
+ .returning(['created_at'])
.executeTakeFirst();
if (result === undefined) {
@@ -806,6 +823,13 @@ export async function updateTurnNonTerminalState(
created_at: new Date(input.turn_update_event.created_at),
})
.execute();
+
+ await applyTurnStateToSession(trx, {
+ id: input.session_id,
+ turn_id: input.turn_id,
+ turn_created_at: result.created_at,
+ turn_state: input.state,
+ });
});
}
@@ -841,8 +865,9 @@ export async function updateTurnTerminalState(
throw new TurnNotRunningError(input.turn_id, terminalTurnState(existing.state, input.turn_id));
}
- await addSessionCostAndDuration(trx, {
- session_id: input.session_id,
+ await applyTurnStateToSession(trx, {
+ id: input.session_id,
+ turn_id: input.turn_id,
turn_created_at: result.created_at,
turn_state: input.state,
});
diff --git a/packages/trueforge/src/db/postgres/types.ts b/packages/trueforge/src/db/postgres/types.ts
index 8fd0b0033..0d225f33b 100644
--- a/packages/trueforge/src/db/postgres/types.ts
+++ b/packages/trueforge/src/db/postgres/types.ts
@@ -6,6 +6,7 @@ import type {
AgentSpec,
CreatedBySubject,
PersistedTurnEvent,
+ SessionLastTurnDetails,
SessionMetadata,
SessionMetrics,
SessionSource,
@@ -96,6 +97,12 @@ export interface SessionTable {
* tiny fixed-width column keeps the bump a cheap HOT update
*/
last_turn_id: string | null;
+ /** Null until the first turn; always replaced as a whole document. */
+ last_turn_details: JSONColumnType<
+ SessionLastTurnDetails,
+ SessionLastTurnDetails | null,
+ SessionLastTurnDetails | null
+ > | null;
/**
* Optional unique key within `tenant_id` (`session_external_id_uq`,
* partial WHERE external_id IS NOT NULL).
diff --git a/packages/trueforge/src/db/sqlite/client.ts b/packages/trueforge/src/db/sqlite/client.ts
index 9e95da431..3f34aa78a 100644
--- a/packages/trueforge/src/db/sqlite/client.ts
+++ b/packages/trueforge/src/db/sqlite/client.ts
@@ -129,6 +129,7 @@ const JSON_RESULT_COLUMNS = new Set([
'custom',
'metadata',
'metrics',
+ 'last_turn_details',
'ancestor_ids',
'input',
'state',
diff --git a/packages/trueforge/src/db/sqlite/migrations/20261018_000001_session_last_turn_details.ts b/packages/trueforge/src/db/sqlite/migrations/20261018_000001_session_last_turn_details.ts
new file mode 100644
index 000000000..1f9e87102
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20261018_000001_session_last_turn_details.ts
@@ -0,0 +1,26 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * SQLite mirror of postgres/migrations/20261018_000001_session_last_turn_details.ts.
+ * Nullable ADD COLUMN needs no table rebuild; column add and backfill share one txn.
+ */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`ALTER TABLE session ADD COLUMN last_turn_details BLOB`.execute(trx);
+ await sql`
+ UPDATE session
+ SET last_turn_details = jsonb(
+ json_object('id', t.turn_id, 'state', json_object('status', json_extract(t.state, '$.status')))
+ )
+ FROM turn t
+ WHERE t.session_id = session.session_id
+ AND t.turn_id = session.last_turn_id
+ `.execute(trx);
+ });
+}
+
+export async function down<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`ALTER TABLE session DROP COLUMN last_turn_details`.execute(trx);
+ });
+}
diff --git a/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts b/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts
index cd0373e54..f9d8b98be 100644
--- a/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts
+++ b/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts
@@ -1,9 +1,11 @@
import {
CreatedBySubjectSchema,
+ SessionLastTurnDetailsSchema,
SessionMetadataSchema,
SessionSourceSchema,
type AgentSpec,
type CreatedBySubject,
+ type SessionLastTurnDetails,
type SessionMetadata,
type SessionMetrics,
type SessionSource,
@@ -66,6 +68,7 @@ function mapRowToSessionRecord(row: {
title: string | null;
shared: number;
last_turn_id: string | null;
+ last_turn_details: SessionLastTurnDetails | null;
external_id: string | null;
custom: Record<string, unknown> | null;
metadata: SessionMetadata;
@@ -88,6 +91,7 @@ function mapRowToSessionRecord(row: {
title: row.title,
shared: row.shared !== 0,
last_turn_id: row.last_turn_id,
+ last_turn_details: SessionLastTurnDetailsSchema.nullable().parse(row.last_turn_details),
external_id: row.external_id,
custom: parseSessionCustom(row.custom),
metadata: parseSessionMetadata(row.metadata),
@@ -110,6 +114,7 @@ function sessionSelectColumns() {
'title' as const,
'shared' as const,
'last_turn_id' as const,
+ jsonText<SessionLastTurnDetails | null>(sql.ref('last_turn_details')).as('last_turn_details'),
'external_id' as const,
jsonText<Record<string, unknown> | null>(sql.ref('custom')).as('custom'),
jsonText<SessionMetadata>(sql.ref('metadata')).as('metadata'),
diff --git a/packages/trueforge/src/db/sqlite/session-store/queries/turns.ts b/packages/trueforge/src/db/sqlite/session-store/queries/turns.ts
index 5d4ad9115..8d9eb4e1b 100644
--- a/packages/trueforge/src/db/sqlite/session-store/queries/turns.ts
+++ b/packages/trueforge/src/db/sqlite/session-store/queries/turns.ts
@@ -1,4 +1,4 @@
-import type { SessionMetrics } from '@truefoundry/trueforge-core/agent-session';
+import { SessionLastTurnDetailsSchema, type SessionMetrics } from '@truefoundry/trueforge-core/agent-session';
import type { TurnRecord, TurnSnapshot } from '@truefoundry/trueforge-core/agent-session/models/TurnRecord';
import {
isNonTerminalTurnState,
@@ -118,32 +118,43 @@ export interface ListTurnsResult {
type DbOrTrx = Kysely<Database> | Transaction<Database>;
-/** Same tx as the turn flip; BEGIN IMMEDIATE serializes concurrent terminal folds. */
-async function addSessionCostAndDuration(
+function lastTurnDetails(input: { turn_id: string; turn_state: TurnState }): RawBuilder<string> {
+ return jsonbBind(SessionLastTurnDetailsSchema.parse({ id: input.turn_id, state: input.turn_state }));
+}
+
+/** Terminal states fold cost and duration; last_turn_details moves only for the session's last turn. */
+async function applyTurnStateToSession(
trx: Transaction<Database>,
- input: { session_id: string; turn_created_at: Date; turn_state: TerminalTurnState },
+ input: { id: string; turn_id: string; turn_created_at: Date; turn_state: TurnState },
): Promise<void> {
- const elapsed_ms = Date.parse(input.turn_state.completed_at) - input.turn_created_at.getTime();
- const total_duration_ms = elapsed_ms > 0 ? Math.trunc(elapsed_ms) : 0;
- const turnCost = input.turn_state.metrics?.total_cost_in_usd;
- const withDuration = sql<SessionMetrics>`jsonb_set(
- metrics,
- '$.total_duration_ms',
- jsonb((metrics->>'total_duration_ms') + ${total_duration_ms})
- )`;
+ let metrics: RawBuilder<SessionMetrics> | undefined;
+ if (!isNonTerminalTurnState(input.turn_state)) {
+ const elapsed_ms = Date.parse(input.turn_state.completed_at) - input.turn_created_at.getTime();
+ const total_duration_ms = elapsed_ms > 0 ? Math.trunc(elapsed_ms) : 0;
+ const turnCost = input.turn_state.metrics?.total_cost_in_usd;
+ metrics = sql<SessionMetrics>`jsonb_set(
+ metrics,
+ '$.total_duration_ms',
+ jsonb((metrics->>'total_duration_ms') + ${total_duration_ms})
+ )`;
+ if (turnCost !== undefined) {
+ metrics = sql<SessionMetrics>`jsonb_set(
+ ${metrics},
+ '$.total_cost_in_usd',
+ jsonb(COALESCE(metrics->>'total_cost_in_usd', 0) + ${turnCost})
+ )`;
+ }
+ }
await trx
.updateTable('session')
.set({
- metrics:
- turnCost === undefined
- ? withDuration
- : sql<SessionMetrics>`jsonb_set(
- ${withDuration},
- '$.total_cost_in_usd',
- jsonb(COALESCE(metrics->>'total_cost_in_usd', 0) + ${turnCost})
- )`,
+ last_turn_details: sql<string>`CASE
+ WHEN json_extract(last_turn_details, '$.id') = ${input.turn_id} THEN ${lastTurnDetails(input)}
+ ELSE last_turn_details
+ END`,
+ ...(metrics === undefined ? {} : { metrics }),
})
- .where('session_id', '=', input.session_id)
+ .where('session_id', '=', input.id)
.execute();
}
@@ -373,6 +384,7 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
.updateTable('session')
.set({
last_turn_id: input.turn.turn_id,
+ last_turn_details: lastTurnDetails({ turn_id: input.turn.turn_id, turn_state: input.turn.state }),
updated_at: nowIso(),
last_activity_timestamp_ms: input.last_activity_timestamp_ms,
// total_turns rides the same tip UPDATE so a later failure in this tx rolls it back.
@@ -734,8 +746,9 @@ export async function freezeAndGetTurn(db: Kysely<Database>, input: FreezeAndGet
})
.execute();
// Only the winning cancel folds; a freeze of an already-terminal turn is a read.
- await addSessionCostAndDuration(trx, {
- session_id: input.session_id,
+ await applyTurnStateToSession(trx, {
+ id: input.session_id,
+ turn_id: input.turn_id,
turn_created_at: new Date(updateResult.created_at),
turn_state: cancelledState,
});
@@ -826,7 +839,7 @@ export async function updateTurnNonTerminalState(
.where('session_id', '=', input.session_id)
.where('turn_id', '=', input.turn_id)
.where(sql<boolean>`state->>'status' = ${expectedSourceStatus}`)
- .returning('turn_id')
+ .returning(['created_at'])
.executeTakeFirst();
if (result === undefined) {
@@ -858,6 +871,13 @@ export async function updateTurnNonTerminalState(
created_at: input.turn_update_event.created_at,
})
.execute();
+
+ await applyTurnStateToSession(trx, {
+ id: input.session_id,
+ turn_id: input.turn_id,
+ turn_created_at: new Date(result.created_at),
+ turn_state: input.state,
+ });
});
}
@@ -893,8 +913,9 @@ export async function updateTurnTerminalState(
throw new TurnNotRunningError(input.turn_id, terminalTurnState(existing.state, input.turn_id));
}
- await addSessionCostAndDuration(trx, {
- session_id: input.session_id,
+ await applyTurnStateToSession(trx, {
+ id: input.session_id,
+ turn_id: input.turn_id,
turn_created_at: new Date(result.created_at),
turn_state: input.state,
});
diff --git a/packages/trueforge/src/db/sqlite/types.ts b/packages/trueforge/src/db/sqlite/types.ts
index 743e005ce..e0a2c30fc 100644
--- a/packages/trueforge/src/db/sqlite/types.ts
+++ b/packages/trueforge/src/db/sqlite/types.ts
@@ -9,6 +9,7 @@ import type {
AgentSpec,
CreatedBySubject,
PersistedTurnEvent,
+ SessionLastTurnDetails,
SessionMetadata,
SessionMetrics,
SessionSource,
@@ -83,6 +84,8 @@ export interface SessionTable {
/** 0/1. When 1, any subject in the tenant may GET this session. */
shared: number;
last_turn_id: string | null;
+ /** Null until the first turn; always replaced as a whole document. */
+ last_turn_details: JsonbColumn<SessionLastTurnDetails> | null;
/** Optional unique key within `tenant_id` when set. */
external_id: string | null;
custom: JsonbColumn<Record<string, unknown>> | null;
diff --git a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
index cc34322be..649032d12 100644
--- a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
+++ b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
@@ -28,7 +28,7 @@ import { SqliteOAuthTokenStore } from '../../../src/db/sqlite/token-store/Sqlite
import { SqliteWebSearchProviderStore } from '../../../src/db/sqlite/web-search-provider-store/SqliteWebSearchProviderStore';
import { ActiveTurnRegistry } from '../../../src/runtime/activeTurns';
import { EventSubscriptionRegistry } from '../../../src/runtime/event-subscription/index.js';
-import { ListSessionsResponseSchema } from '../../../src/schemas/session';
+import { GetSessionResponseSchema, ListSessionsResponseSchema } from '../../../src/schemas/session';
import {
GetSessionMetricsChartDataResponseSchema,
GetSessionMetricsChartResponseSchema,
@@ -196,6 +196,22 @@ describe('sessions HTTP agent binding', () => {
expect(json.data.metrics).toEqual({ total_duration_ms: 0, total_turns: 0 });
});
+ it('returns last_turn_details on get and list', async () => {
+ const created = await app.request('/', jsonInit('POST', { agent: { spec: inlineSpec } }));
+ expect(created.status).toBe(201);
+ const session = GetSessionResponseSchema.parse(await created.json()).data;
+ expect(session.last_turn_details).toBeNull();
+
+ await sessionStore.createTurn(makeCreateTurnInput({ sessionId: session.id, turnId: 'turn-1' }));
+ const expected = { id: 'turn-1', state: { status: 'running' } };
+
+ const fetched = await app.request(`/${session.id}`);
+ expect(GetSessionResponseSchema.parse(await fetched.json()).data.last_turn_details).toEqual(expected);
+
+ const listed = ListSessionsResponseSchema.parse(await (await app.request('/')).json()).data;
+ expect(listed.find(item => item.id === session.id)?.last_turn_details).toEqual(expected);
+ });
+
it('returns 404 when creating a session for an unknown agent name', async () => {
const missing = await app.request('/', jsonInit('POST', { agent: { name: 'does-not-exist' } }));
expect(missing.status).toBe(404);
diff --git a/python/trueforge_sdk/src/trueforge_sdk/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
index c4ccacf02..e9549a227 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
@@ -201,6 +201,8 @@ if typing.TYPE_CHECKING:
SessionAgentSpecBody,
SessionEvent,
SessionEventItem,
+ SessionLastTurnDetails,
+ SessionLastTurnState,
SessionMetadata,
SessionMetrics,
SessionMetricsChart,
@@ -258,6 +260,7 @@ if typing.TYPE_CHECKING:
TurnStateErrorMetrics,
TurnStatePaused,
TurnStateRunning,
+ TurnStatus,
TurnStreamingEvent,
TurnUpdateEvent,
TurnUpdateEventState,
@@ -516,6 +519,8 @@ _dynamic_imports: typing.Dict[str, str] = {
"SessionAgentSpecBody": ".types",
"SessionEvent": ".types",
"SessionEventItem": ".types",
+ "SessionLastTurnDetails": ".types",
+ "SessionLastTurnState": ".types",
"SessionMetadata": ".types",
"SessionMetrics": ".types",
"SessionMetricsChart": ".types",
@@ -574,6 +579,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"TurnStateErrorMetrics": ".types",
"TurnStatePaused": ".types",
"TurnStateRunning": ".types",
+ "TurnStatus": ".types",
"TurnStreamingEvent": ".types",
"TurnUpdateEvent": ".types",
"TurnUpdateEventState": ".types",
@@ -839,6 +845,8 @@ __all__ = [
"SessionAgentSpecBody",
"SessionEvent",
"SessionEventItem",
+ "SessionLastTurnDetails",
+ "SessionLastTurnState",
"SessionMetadata",
"SessionMetrics",
"SessionMetricsChart",
@@ -897,6 +905,7 @@ __all__ = [
"TurnStateErrorMetrics",
"TurnStatePaused",
"TurnStateRunning",
+ "TurnStatus",
"TurnStreamingEvent",
"TurnUpdateEvent",
"TurnUpdateEventState",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
index 6a92da596..eb01dc299 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
@@ -200,6 +200,8 @@ if typing.TYPE_CHECKING:
from .session_agent_spec_body import SessionAgentSpecBody
from .session_event import SessionEvent
from .session_event_item import SessionEventItem
+ from .session_last_turn_details import SessionLastTurnDetails
+ from .session_last_turn_state import SessionLastTurnState
from .session_metadata import SessionMetadata
from .session_metrics import SessionMetrics
from .session_metrics_chart import SessionMetricsChart
@@ -257,6 +259,7 @@ if typing.TYPE_CHECKING:
from .turn_state_error_metrics import TurnStateErrorMetrics
from .turn_state_paused import TurnStatePaused
from .turn_state_running import TurnStateRunning
+ from .turn_status import TurnStatus
from .turn_streaming_event import TurnStreamingEvent
from .turn_update_event import TurnUpdateEvent
from .turn_update_event_state import TurnUpdateEventState
@@ -470,6 +473,8 @@ _dynamic_imports: typing.Dict[str, str] = {
"SessionAgentSpecBody": ".session_agent_spec_body",
"SessionEvent": ".session_event",
"SessionEventItem": ".session_event_item",
+ "SessionLastTurnDetails": ".session_last_turn_details",
+ "SessionLastTurnState": ".session_last_turn_state",
"SessionMetadata": ".session_metadata",
"SessionMetrics": ".session_metrics",
"SessionMetricsChart": ".session_metrics_chart",
@@ -527,6 +532,7 @@ _dynamic_imports: typing.Dict[str, str] = {
"TurnStateErrorMetrics": ".turn_state_error_metrics",
"TurnStatePaused": ".turn_state_paused",
"TurnStateRunning": ".turn_state_running",
+ "TurnStatus": ".turn_status",
"TurnStreamingEvent": ".turn_streaming_event",
"TurnUpdateEvent": ".turn_update_event",
"TurnUpdateEventState": ".turn_update_event_state",
@@ -764,6 +770,8 @@ __all__ = [
"SessionAgentSpecBody",
"SessionEvent",
"SessionEventItem",
+ "SessionLastTurnDetails",
+ "SessionLastTurnState",
"SessionMetadata",
"SessionMetrics",
"SessionMetricsChart",
@@ -821,6 +829,7 @@ __all__ = [
"TurnStateErrorMetrics",
"TurnStatePaused",
"TurnStateRunning",
+ "TurnStatus",
"TurnStreamingEvent",
"TurnUpdateEvent",
"TurnUpdateEventState",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/session.py b/python/trueforge_sdk/src/trueforge_sdk/types/session.py
index 3f2f1baa9..8240f3c38 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/session.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/session.py
@@ -7,6 +7,7 @@ from ..core.pydantic_utilities import IS_PYDANTIC_V2
from ..core.unchecked_base_model import UncheckedBaseModel
from .created_by_subject import CreatedBySubject
from .session_agent import SessionAgent
+from .session_last_turn_details import SessionLastTurnDetails
from .session_metadata import SessionMetadata
from .session_metrics import SessionMetrics
from .session_source import SessionSource
@@ -25,6 +26,7 @@ class Session(UncheckedBaseModel):
Unique session id.
"""
+ last_turn_details: typing.Optional[SessionLastTurnDetails] = None
metadata: SessionMetadata
metrics: SessionMetrics
shared: bool = pydantic.Field()
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/session_last_turn_details.py b/python/trueforge_sdk/src/trueforge_sdk/types/session_last_turn_details.py
new file mode 100644
index 000000000..a807781f6
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/session_last_turn_details.py
@@ -0,0 +1,29 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .session_last_turn_state import SessionLastTurnState
+
+
+class SessionLastTurnDetails(UncheckedBaseModel):
+ """
+ The session's most recent turn; null until the first turn.
+ """
+
+ id: str = pydantic.Field()
+ """
+ Id of the last turn.
+ """
+
+ state: SessionLastTurnState
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/session_last_turn_state.py b/python/trueforge_sdk/src/trueforge_sdk/types/session_last_turn_state.py
new file mode 100644
index 000000000..1e0c72f95
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/session_last_turn_state.py
@@ -0,0 +1,20 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .turn_status import TurnStatus
+
+
+class SessionLastTurnState(UncheckedBaseModel):
+ status: TurnStatus
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/turn_status.py b/python/trueforge_sdk/src/trueforge_sdk/types/turn_status.py
new file mode 100644
index 000000000..8fa7a797c
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/turn_status.py
@@ -0,0 +1,46 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core import enum
+
+T_Result = typing.TypeVar("T_Result")
+
+
+class TurnStatus(enum.StrEnum):
+ RUNNING = "running"
+ PAUSED = "paused"
+ DONE = "done"
+ CANCELLED = "cancelled"
+ ERROR = "error"
+ _UNKNOWN = "__TURNSTATUS_UNKNOWN__"
+ """
+ This member is used for forward compatibility. If the value is not recognized by the enum, it will be stored here, and the raw value is accessible through `.value`.
+ """
+
+ @classmethod
+ def _missing_(cls, value: typing.Any) -> "TurnStatus":
+ unknown = cls._UNKNOWN
+ unknown._value_ = value
+ return unknown
+
+ def visit(
+ self,
+ running: typing.Callable[[], T_Result],
+ paused: typing.Callable[[], T_Result],
+ done: typing.Callable[[], T_Result],
+ cancelled: typing.Callable[[], T_Result],
+ error: typing.Callable[[], T_Result],
+ _unknown_member: typing.Callable[[str], T_Result],
+ ) -> T_Result:
+ if self is TurnStatus.RUNNING:
+ return running()
+ if self is TurnStatus.PAUSED:
+ return paused()
+ if self is TurnStatus.DONE:
+ return done()
+ if self is TurnStatus.CANCELLED:
+ return cancelled()
+ if self is TurnStatus.ERROR:
+ return error()
+ return _unknown_member(self._value_)