Skip to content

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 = z
export 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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: CreateSessionIn
agent_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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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: CreateSessionIn
agent_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.ts
index 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;