The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Persist session metrics JSON on Postgres and SQLite (#478)
Bhavesh Pateld89b2ffe3a42
diff --git a/.changeset/20260827210200-session-metrics.md b/.changeset/20260827210200-session-metrics.mdnew file mode 100644index 000000000..b5f1befbd--- /dev/null+++ b/.changeset/20260827210200-session-metrics.md@@ -0,0 +1,6 @@+---+'@truefoundry/trueforge-core': patch+'@truefoundry/trueforge': patch+---++Persist zero-initialized metrics on agent sessions.diff --git a/packages/trueforge-core/src/agent-session/index.ts b/packages/trueforge-core/src/agent-session/index.tsindex 85eba425e..4c9277089 100644--- a/packages/trueforge-core/src/agent-session/index.ts+++ b/packages/trueforge-core/src/agent-session/index.ts@@ -21,8 +21,8 @@ export {} from './schemas/turn';export type { TerminalTurnState, Turn, TurnInputItem, TurnMetrics, TurnState } from './schemas/turn';-export { SessionSchema } from './schemas/session';-export type { Session, SessionAgent } from './schemas/session';+export { SessionMetricsSchema, SessionSchema } from './schemas/session';+export type { Session, SessionAgent, SessionMetrics } from './schemas/session';export {EventType,diff --git a/packages/trueforge-core/src/agent-session/models/SessionRecord.ts b/packages/trueforge-core/src/agent-session/models/SessionRecord.tsindex bbb95ce5d..721ad6731 100644--- a/packages/trueforge-core/src/agent-session/models/SessionRecord.ts+++ b/packages/trueforge-core/src/agent-session/models/SessionRecord.ts@@ -1,4 +1,4 @@-import type { SessionAgent } from '../schemas/session';+import type { SessionAgent, SessionMetrics } from '../schemas/session';/*** Session persistence record. Agent binding is a single discriminated `agent`@@ -30,5 +30,6 @@ export interface SessionRecord<TCustom extends object = Record<string, never>> {* updateSession, and createTurn — never on reads.*/last_activity_timestamp_ms: number;+ metrics: SessionMetrics;custom: TCustom | null;}diff --git a/packages/trueforge-core/src/agent-session/schemas/session.ts b/packages/trueforge-core/src/agent-session/schemas/session.tsindex 23287efcd..a25eb0679 100644--- a/packages/trueforge-core/src/agent-session/schemas/session.ts+++ b/packages/trueforge-core/src/agent-session/schemas/session.ts@@ -5,6 +5,14 @@import { z } from '@hono/zod-openapi';import { AgentSpecSchema } from './agentSpec';+export const SessionMetricsSchema = z+ .object({+ total_cost_in_usd: z.number().nonnegative(),+ total_duration_ms: z.number().int().nonnegative(),+ total_turns: z.number().int().nonnegative(),+ })+ .strict();+export const SessionAgentReferenceSchema = z.object({type: z.literal('reference').describe('Bind the session to a named registry agent.'),@@ -46,4 +54,5 @@ export const SessionSchema = zexport type SessionAgentReference = z.infer<typeof SessionAgentReferenceSchema>;export type SessionAgentInline = z.infer<typeof SessionAgentInlineSchema>;export type SessionAgent = z.infer<typeof SessionAgentSchema>;+export type SessionMetrics = z.infer<typeof SessionMetricsSchema>;export type Session = z.infer<typeof SessionSchema>;diff --git a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.tsindex fb477beb8..5ebeacaf0 100644--- a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts+++ b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts@@ -184,6 +184,11 @@ export class InMemorySessionStore<created_at: now,updated_at: now,last_activity_timestamp_ms: Date.now(),+ metrics: {+ total_cost_in_usd: 0,+ total_duration_ms: 0,+ total_turns: 0,+ },custom: input.custom !== null ? deepCopy(input.custom) : null,};this.sessions.set(key, { record, turnIds: [] });diff --git a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.tsindex f67685ae0..30ec42212 100644--- a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts+++ b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts@@ -175,6 +175,11 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {});expect(mustGet(session).last_activity_timestamp_ms).toBeGreaterThanOrEqual(before);expect(mustGet(session).title).toBeNull();+ expect(mustGet(session).metrics).toEqual({+ total_cost_in_usd: 0,+ total_duration_ms: 0,+ total_turns: 0,+ });});it('createSession persists created_by', async () => {diff --git a/packages/trueforge/src/db/postgres/migrations/20260827_000001_session_metrics.ts b/packages/trueforge/src/db/postgres/migrations/20260827_000001_session_metrics.tsnew file mode 100644index 000000000..8a7162792--- /dev/null+++ b/packages/trueforge/src/db/postgres/migrations/20260827_000001_session_metrics.ts@@ -0,0 +1,24 @@+import { sql, type Kysely } from 'kysely';++export async function up(db: Kysely<unknown>): Promise<void> {+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);+ await db.schema+ .alterTable('session')+ .addColumn('metrics', 'jsonb', col =>+ col.notNull().defaultTo(sql`'{"total_cost_in_usd":0,"total_duration_ms":0,"total_turns":0}'::jsonb`),+ )+ .execute();+ // Serves GET /sessions/metrics (named agent + created_at window).+ // session_agent_id_idx cannot range on created_at; partial skips inline sessions.+ await sql`+ CREATE INDEX session_agent_created_at_idx+ ON session (tenant_id, agent_id, created_at)+ WHERE agent_id IS NOT NULL+ `.execute(db);+}++export async function down(db: Kysely<unknown>): Promise<void> {+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);+ await sql`DROP INDEX IF EXISTS session_agent_created_at_idx`.execute(db);+ await db.schema.alterTable('session').dropColumn('metrics').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 62894605b..6be30a46e 100644--- a/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts+++ b/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts@@ -1,4 +1,4 @@-import type { AgentSpec } from '@truefoundry/trueforge-core/agent-session';+import type { AgentSpec, SessionMetrics } from '@truefoundry/trueforge-core/agent-session';import type { SessionRecord } from '@truefoundry/trueforge-core/agent-session/models/SessionRecord';import type {CreateSessionInput,@@ -58,6 +58,7 @@ function mapRowToSessionRecord(row: {title: string | null;last_turn_id: string | null;custom: Record<string, unknown> | null;+ metrics: SessionMetrics;created_at: Date;updated_at: Date;last_activity_timestamp_ms: number;@@ -75,6 +76,7 @@ function mapRowToSessionRecord(row: {title: row.title,last_turn_id: row.last_turn_id,custom: parseSessionCustom(row.custom),+ metrics: row.metrics,created_at: row.created_at,updated_at: row.updated_at,last_activity_timestamp_ms: row.last_activity_timestamp_ms,@@ -97,6 +99,11 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionInagent_spec: columns.agent_spec !== null ? json(columns.agent_spec) : null,title: null,custom: input.custom !== null ? json(input.custom) : null,+ metrics: json({+ total_cost_in_usd: 0,+ total_duration_ms: 0,+ total_turns: 0,+ }),created_at: new Date(nowMs),updated_at: new Date(nowMs),last_activity_timestamp_ms: nowMs,diff --git a/packages/trueforge/src/db/postgres/types.ts b/packages/trueforge/src/db/postgres/types.tsindex 634cdc270..07b88b216 100644--- a/packages/trueforge/src/db/postgres/types.ts+++ b/packages/trueforge/src/db/postgres/types.ts@@ -5,6 +5,7 @@import type {AgentSpec,PersistedTurnEvent,+ SessionMetrics,TurnInputItem,TurnState,} from '@truefoundry/trueforge-core/agent-session';@@ -80,6 +81,7 @@ export interface SessionTable {last_turn_id: string | null;/** top: caller-owned opaque extension; never mixed with store state */custom: JSONColumnType<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>> | null;+ metrics: JSONColumnType<SessionMetrics, SessionMetrics, SessionMetrics>;/** top: list ordering (indexed below) */created_at: Date;updated_at: Date;diff --git a/packages/trueforge/src/db/sqlite/client.ts b/packages/trueforge/src/db/sqlite/client.tsindex e49a178a1..ffa1aaee2 100644--- a/packages/trueforge/src/db/sqlite/client.ts+++ b/packages/trueforge/src/db/sqlite/client.ts@@ -124,6 +124,7 @@ function applyPragmas(database: Database.Database): void {const JSON_RESULT_COLUMNS = new Set(['agent_spec','custom',+ 'metrics','ancestor_ids','input','state',diff --git a/packages/trueforge/src/db/sqlite/migrations/20260827_000001_session_metrics.ts b/packages/trueforge/src/db/sqlite/migrations/20260827_000001_session_metrics.tsnew file mode 100644index 000000000..ef59e51a6--- /dev/null+++ b/packages/trueforge/src/db/sqlite/migrations/20260827_000001_session_metrics.ts@@ -0,0 +1,170 @@+import { sql, type Kysely } from 'kysely';++/**+ * Rebuild `session`: ADD COLUMN cannot take DEFAULT (jsonb(...)) (expression default).+ * DROP TABLE session needs FKs off; PRAGMA foreign_keys is a no-op inside a txn.+ * down also rebuilds — DROP COLUMN rewrites STRICT parents and can CASCADE children.+ */+export async function up(db: Kysely<unknown>): Promise<void> {+ await sql`PRAGMA foreign_keys = OFF`.execute(db);+ try {+ await db.transaction().execute(async trx => {+ await sql`+ CREATE TABLE session_new (+ tenant_id TEXT NOT NULL,+ session_id TEXT NOT NULL,+ created_by TEXT NOT NULL DEFAULT '',+ agent_id TEXT,+ agent_name TEXT,+ agent_spec BLOB,+ title TEXT,+ last_turn_id TEXT,+ custom BLOB,+ metrics BLOB NOT NULL DEFAULT (jsonb('{"total_cost_in_usd":0,"total_duration_ms":0,"total_turns":0}')),+ last_activity_timestamp_ms INTEGER NOT NULL,+ created_at TEXT NOT NULL,+ updated_at TEXT NOT NULL,+ PRIMARY KEY (session_id),+ CHECK (+ (agent_id IS NOT NULL AND agent_spec IS NULL)+ OR (agent_id IS NULL AND agent_spec IS NOT NULL)+ )+ ) STRICT+ `.execute(trx);++ await sql`+ INSERT INTO session_new (+ tenant_id,+ session_id,+ created_by,+ agent_id,+ agent_name,+ agent_spec,+ title,+ last_turn_id,+ custom,+ metrics,+ last_activity_timestamp_ms,+ created_at,+ updated_at+ )+ SELECT+ tenant_id,+ session_id,+ created_by,+ agent_id,+ agent_name,+ agent_spec,+ title,+ last_turn_id,+ custom,+ jsonb('{"total_cost_in_usd":0,"total_duration_ms":0,"total_turns":0}'),+ last_activity_timestamp_ms,+ created_at,+ updated_at+ FROM session+ `.execute(trx);++ await sql`DROP TABLE session`.execute(trx);+ await sql`ALTER TABLE session_new RENAME TO session`.execute(trx);+ await sql`+ CREATE INDEX session_list_idx+ ON session (tenant_id, created_at, session_id)+ `.execute(trx);+ await sql`+ CREATE INDEX session_agent_id_idx+ ON session (tenant_id, agent_id)+ WHERE agent_id IS NOT NULL+ `.execute(trx);+ await sql`+ CREATE INDEX session_list_updated_at_idx+ ON session (tenant_id, updated_at, session_id)+ `.execute(trx);+ await sql`+ CREATE INDEX session_agent_created_at_idx+ ON session (tenant_id, agent_id, created_at)+ WHERE agent_id IS NOT NULL+ `.execute(trx);+ });+ } finally {+ await sql`PRAGMA foreign_keys = ON`.execute(db);+ }+}++export async function down(db: Kysely<unknown>): Promise<void> {+ await sql`PRAGMA foreign_keys = OFF`.execute(db);+ try {+ await db.transaction().execute(async trx => {+ await sql`+ CREATE TABLE session_old (+ tenant_id TEXT NOT NULL,+ session_id TEXT NOT NULL,+ created_by TEXT NOT NULL DEFAULT '',+ agent_id TEXT,+ agent_name TEXT,+ agent_spec BLOB,+ title TEXT,+ last_turn_id TEXT,+ custom BLOB,+ last_activity_timestamp_ms INTEGER NOT NULL,+ created_at TEXT NOT NULL,+ updated_at TEXT NOT NULL,+ PRIMARY KEY (session_id),+ CHECK (+ (agent_id IS NOT NULL AND agent_spec IS NULL)+ OR (agent_id IS NULL AND agent_spec IS NOT NULL)+ )+ ) STRICT+ `.execute(trx);++ await sql`+ INSERT INTO session_old (+ tenant_id,+ session_id,+ created_by,+ agent_id,+ agent_name,+ agent_spec,+ title,+ last_turn_id,+ custom,+ last_activity_timestamp_ms,+ created_at,+ updated_at+ )+ SELECT+ tenant_id,+ session_id,+ created_by,+ agent_id,+ agent_name,+ agent_spec,+ title,+ last_turn_id,+ custom,+ last_activity_timestamp_ms,+ created_at,+ updated_at+ FROM session+ `.execute(trx);++ await sql`DROP TABLE session`.execute(trx);+ await sql`ALTER TABLE session_old RENAME TO session`.execute(trx);+ await sql`+ CREATE INDEX session_list_idx+ ON session (tenant_id, created_at, session_id)+ `.execute(trx);+ await sql`+ CREATE INDEX session_agent_id_idx+ ON session (tenant_id, agent_id)+ WHERE agent_id IS NOT NULL+ `.execute(trx);+ await sql`+ CREATE INDEX session_list_updated_at_idx+ ON session (tenant_id, updated_at, session_id)+ `.execute(trx);+ });+ } finally {+ await sql`PRAGMA foreign_keys = ON`.execute(db);+ }+}diff --git a/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts b/packages/trueforge/src/db/sqlite/session-store/queries/sessions.tsindex beaf1414e..e651364a3 100644--- a/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts+++ b/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts@@ -1,4 +1,4 @@-import type { AgentSpec } from '@truefoundry/trueforge-core/agent-session';+import type { AgentSpec, SessionMetrics } from '@truefoundry/trueforge-core/agent-session';import type { SessionRecord } from '@truefoundry/trueforge-core/agent-session/models/SessionRecord';import type {CreateSessionInput,@@ -49,6 +49,7 @@ function mapRowToSessionRecord(row: {title: string | null;last_turn_id: string | null;custom: Record<string, unknown> | null;+ metrics: SessionMetrics;created_at: string;updated_at: string;last_activity_timestamp_ms: number;@@ -66,6 +67,7 @@ function mapRowToSessionRecord(row: {title: row.title,last_turn_id: row.last_turn_id,custom: parseSessionCustom(row.custom),+ metrics: row.metrics,created_at: new Date(row.created_at),updated_at: new Date(row.updated_at),last_activity_timestamp_ms: row.last_activity_timestamp_ms,@@ -83,6 +85,7 @@ function sessionSelectColumns() {'title' as const,'last_turn_id' as const,jsonText<Record<string, unknown> | null>(sql.ref('custom')).as('custom'),+ jsonText<SessionMetrics>(sql.ref('metrics')).as('metrics'),'created_at' as const,'updated_at' as const,'last_activity_timestamp_ms' as const,@@ -105,6 +108,11 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionInagent_spec: columns.agent_spec !== null ? jsonbBind(columns.agent_spec) : null,title: null,custom: input.custom !== null ? jsonbBind(input.custom) : null,+ metrics: jsonbBind({+ total_cost_in_usd: 0,+ total_duration_ms: 0,+ total_turns: 0,+ }),created_at: now,updated_at: now,last_activity_timestamp_ms: Date.now(),diff --git a/packages/trueforge/src/db/sqlite/types.ts b/packages/trueforge/src/db/sqlite/types.tsindex 3237924db..2a8a17278 100644--- a/packages/trueforge/src/db/sqlite/types.ts+++ b/packages/trueforge/src/db/sqlite/types.ts@@ -8,6 +8,7 @@import type {AgentSpec,PersistedTurnEvent,+ SessionMetrics,TurnInputItem,TurnState,} from '@truefoundry/trueforge-core/agent-session';@@ -68,6 +69,7 @@ export interface SessionTable {title: string | null;last_turn_id: string | null;custom: JsonbColumn<Record<string, unknown>> | null;+ metrics: JsonbColumn<SessionMetrics>;created_at: string;updated_at: string;last_activity_timestamp_ms: number;