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.mdnew file mode 100644index 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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 = zmetrics: 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.tsindex 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 = zexport 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 = zexport 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 = zexport 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 = zexport 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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, TcreatedAt: 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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/Sqliteimport { 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__.pyindex 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__.pyindex 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 SessionAgentSpecBodyfrom .session_event import SessionEventfrom .session_event_item import SessionEventItem+ from .session_last_turn_details import SessionLastTurnDetails+ from .session_last_turn_state import SessionLastTurnStatefrom .session_metadata import SessionMetadatafrom .session_metrics import SessionMetricsfrom .session_metrics_chart import SessionMetricsChart@@ -257,6 +259,7 @@ if typing.TYPE_CHECKING:from .turn_state_error_metrics import TurnStateErrorMetricsfrom .turn_state_paused import TurnStatePausedfrom .turn_state_running import TurnStateRunning+ from .turn_status import TurnStatusfrom .turn_streaming_event import TurnStreamingEventfrom .turn_update_event import TurnUpdateEventfrom .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.pyindex 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_V2from ..core.unchecked_base_model import UncheckedBaseModelfrom .created_by_subject import CreatedBySubjectfrom .session_agent import SessionAgent+from .session_last_turn_details import SessionLastTurnDetailsfrom .session_metadata import SessionMetadatafrom .session_metrics import SessionMetricsfrom .session_source import SessionSource@@ -25,6 +26,7 @@ class Session(UncheckedBaseModel):Unique session id."""+ last_turn_details: typing.Optional[SessionLastTurnDetails] = Nonemetadata: SessionMetadatametrics: SessionMetricsshared: 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.pynew file mode 100644index 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.allowdiff --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.pynew file mode 100644index 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.allowdiff --git a/python/trueforge_sdk/src/trueforge_sdk/types/turn_status.py b/python/trueforge_sdk/src/trueforge_sdk/types/turn_status.pynew file mode 100644index 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_)