The open-source agent harness - the runtime layer that turns an LLM into a working agent.
fix: chat ordering by updated_at desc (#184)
Srajan Asthanafb360b2d5363
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.jsonindex ce3bf8922..2893a5583 100644--- a/.github/fern/openapi/openapi.json+++ b/.github/fern/openapi/openapi.json@@ -1400,7 +1400,7 @@},"ListSessionsOrder": {"default": "desc",- "description": "Sort sessions by creation time. Defaults to \"desc\".",+ "description": "Sort sessions by `updated_at`. Defaults to \"desc\".","enum": ["asc","desc"@@ -4908,7 +4908,7 @@}},{- "description": "Sort sessions by creation time. Defaults to \"desc\".",+ "description": "Sort sessions by `updated_at`. Defaults to \"desc\".","in": "query","name": "order","required": false,@@ -4917,12 +4917,13 @@}},{- "description": "Opaque token from a previous response `next_page_token`.",+ "description": "Opaque keyset cursor from a previous response `next_page_token`.","in": "query","name": "page_token","required": false,"schema": {- "description": "Opaque token from a previous response `next_page_token`.",+ "description": "Opaque keyset cursor from a previous response `next_page_token`.",+ "minLength": 1,"type": "string"}},diff --git a/packages/harness/src/agent-session/store/ISessionStore.ts b/packages/harness/src/agent-session/store/ISessionStore.tsindex c6df9c24c..17eab046a 100644--- a/packages/harness/src/agent-session/store/ISessionStore.ts+++ b/packages/harness/src/agent-session/store/ISessionStore.ts@@ -236,11 +236,12 @@ export interface ISessionStore<updateSession(input: UpdateSessionInput<TSessionCustom>): Promise<void>;/**- * Paginated list of the tenant's sessions ordered by `created_at`- * (`order` defaults to `desc`). `start_timestamp` / `end_timestamp` are- * inclusive instant bounds on `created_at`. Optional `agent_id` filters- * ref-bound sessions; optional `created_by` filters by creator identity.- * Does **not** bump `last_activity_timestamp_ms` (read path).+ * Paginated list of the tenant's sessions ordered by `updated_at`+ * (`order` defaults to `desc`, `session_id` tie-break). `page_token` is a+ * keyset cursor on `(updated_at, session_id)`. `start_timestamp` /+ * `end_timestamp` are inclusive instant bounds on `created_at`. Optional+ * `agent_id` filters ref-bound sessions; optional `created_by` filters by+ * creator identity. Does **not** bump `last_activity_timestamp_ms` (read path).*/listSessions(input: ListSessionsInput,diff --git a/packages/harness/src/agent-session/store/InMemorySessionStore.ts b/packages/harness/src/agent-session/store/InMemorySessionStore.tsindex 98df5d2d5..8003ebf36 100644--- a/packages/harness/src/agent-session/store/InMemorySessionStore.ts+++ b/packages/harness/src/agent-session/store/InMemorySessionStore.ts@@ -38,6 +38,7 @@ import {paginateSessionEventRows,type SessionEventPageCursor,} from './SessionEventPageToken';+import { decodeSessionListPageToken, paginateSessionListRows } from './SessionListPageToken';import {PreviousTurnRunningError,SessionAlreadyExistsError,@@ -69,6 +70,13 @@ function turnKey({ session_id, turn_id }: { session_id: string; turn_id: stringreturn `${session_id}:${turn_id}`;}+/** Lexicographic session_id order — shared by listSessions sort and keyset filter. */+function compareSessionId(a: string, b: string): number {+ if (a < b) return -1;+ if (a > b) return 1;+ return 0;+}+function newThreadSnapshot(thread: NewThreadInit): AgentThreadSnapshot {return {thread_id: thread.thread_id,@@ -238,12 +246,33 @@ export class InMemorySessionStore<if (input.end_timestamp !== undefined && createdAt > input.end_timestamp.getTime()) continue;records.push(stored.record);}- records.sort((a, b) =>- input.order === 'asc'- ? a.created_at.getTime() - b.created_at.getTime()- : b.created_at.getTime() - a.created_at.getTime(),- );- const page = paginate(records, input.limit, input.page_token);+ records.sort((a, b) => {+ const aTime = a.updated_at.getTime();+ const bTime = b.updated_at.getTime();+ if (aTime !== bTime) {+ return input.order === 'asc' ? aTime - bTime : bTime - aTime;+ }+ // Same lexicographic order as the keyset predicate below (and Postgres/SQLite).+ return input.order === 'asc'+ ? compareSessionId(a.session_id, b.session_id)+ : compareSessionId(b.session_id, a.session_id);+ });++ let filtered = records;+ const cursor = decodeSessionListPageToken(input.page_token);+ if (cursor) {+ const cursorTime = new Date(cursor.updated_at).getTime();+ filtered = records.filter(record => {+ const t = record.updated_at.getTime();+ const idCmp = compareSessionId(record.session_id, cursor.session_id);+ if (input.order === 'asc') {+ return t > cursorTime || (t === cursorTime && idCmp > 0);+ }+ return t < cursorTime || (t === cursorTime && idCmp < 0);+ });+ }++ const page = paginateSessionListRows(filtered, input.limit, row => row.updated_at.toISOString());return { data: deepCopy(page.data), pagination: page.pagination };}diff --git a/packages/harness/src/agent-session/store/SessionListPageToken.ts b/packages/harness/src/agent-session/store/SessionListPageToken.tsnew file mode 100644index 000000000..c25c41855--- /dev/null+++ b/packages/harness/src/agent-session/store/SessionListPageToken.ts@@ -0,0 +1,53 @@+import { z } from 'zod';+import type { TokenPagination } from '../schemas/pagination';+import { decodePageToken, encodePageToken } from './PageToken';++/**+ * Keyset cursor for `listSessions` (`updated_at`, `session_id`).+ * Opaque on the wire; replaces offset tokens for this list only.+ *+ * `updated_at` must retain the store's full precision (Postgres: microseconds via+ * `to_char`; JS Date / SQLite ISO text: milliseconds). Do not round through+ * `Date` before encode/compare — equality on the cursor must match the DB value.+ */+export const SessionListPageCursorSchema = z+ .object({+ updated_at: z.iso.datetime({ offset: true }),+ session_id: z.string().min(1),+ })+ .strict();++export type SessionListPageCursor = z.infer<typeof SessionListPageCursorSchema>;++export function encodeSessionListPageToken(cursor: SessionListPageCursor): string {+ return encodePageToken(SessionListPageCursorSchema, cursor);+}++export function decodeSessionListPageToken(token: string | undefined): SessionListPageCursor | undefined {+ if (token === undefined) return undefined;+ return decodePageToken(SessionListPageCursorSchema, token);+}++export function paginateSessionListRows<T extends { session_id: string }>(+ rows: T[],+ limit: number,+ getUpdatedAtCursor: (row: T) => string,+): { data: T[]; pagination: TokenPagination } {+ const hasMore = rows.length > limit;+ const data = hasMore ? rows.slice(0, limit) : rows;+ const last = data.at(-1);+ return {+ data,+ pagination: {+ limit,+ ...(hasMore && last !== undefined+ ? {+ next_page_token: encodeSessionListPageToken({+ updated_at: getUpdatedAtCursor(last),+ session_id: last.session_id,+ }),+ }+ : {}),+ },+ };+}diff --git a/packages/harness/tests/agent-session/store/storeContractSuite.ts b/packages/harness/tests/agent-session/store/storeContractSuite.tsindex 27c80526a..107e3e2e5 100644--- a/packages/harness/tests/agent-session/store/storeContractSuite.ts+++ b/packages/harness/tests/agent-session/store/storeContractSuite.ts@@ -661,7 +661,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {expect(asc.data.map(s => s.session_id)).toEqual(['sa', 'sb', 'sc']);});- it('paginates with next/previous tokens and filters by created_at bounds', async () => {+ it('paginates with next_page_token and filters by created_at bounds', async () => {const store = createStore();await seedThreeSessions(store);@@ -716,6 +716,66 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {expect(bounded.data.map(s => s.session_id)).toEqual(['sb']);});+ it('orders by updated_at so later activity ranks ahead of create order', async () => {+ const store = createStore();+ await seedThreeSessions(store);+ await new Promise(r => setTimeout(r, 5));+ await store.updateSession({+ tenant_id: tenant,+ session_id: 'sa',+ agent: undefined,+ title: 'bumped',+ });++ const listArgs = {+ agent_id: undefined,+ created_by: undefined,+ tenant_id: tenant,+ order: undefined,+ start_timestamp: undefined,+ end_timestamp: undefined,+ };+ const desc = await store.listSessions({ ...listArgs, limit: 10, page_token: undefined });+ expect(desc.data.map(s => s.session_id)).toEqual(['sa', 'sc', 'sb']);++ // Keyset must continue from the bumped row's updated_at cursor, not create order.+ const page1 = await store.listSessions({ ...listArgs, limit: 2, page_token: undefined });+ expect(page1.data.map(s => s.session_id)).toEqual(['sa', 'sc']);+ const page2 = await store.listSessions({+ ...listArgs,+ limit: 2,+ page_token: page1.pagination.next_page_token,+ });+ expect(page2.data.map(s => s.session_id)).toEqual(['sb']);+ });++ it('keyset pages partition the ordered list without overlap or gaps', async () => {+ const store = createStore();+ await seedThreeSessions(store);++ const listArgs = {+ agent_id: undefined,+ created_by: undefined,+ tenant_id: tenant,+ order: 'desc' as const,+ start_timestamp: undefined,+ end_timestamp: undefined,+ };+ const full = await store.listSessions({ ...listArgs, limit: 10, page_token: undefined });+ const page1 = await store.listSessions({ ...listArgs, limit: 2, page_token: undefined });+ expect(page1.pagination.next_page_token).toBeDefined();+ const page2 = await store.listSessions({+ ...listArgs,+ limit: 2,+ page_token: page1.pagination.next_page_token,+ });++ const pageIds = [...page1.data, ...page2.data].map(s => s.session_id);+ expect(pageIds).toEqual(full.data.map(s => s.session_id));+ expect(new Set(pageIds).size).toBe(pageIds.length);+ expect(page2.pagination.next_page_token).toBeUndefined();+ });+it('filters by created_by', async () => {const store = createStore();await store.createSession({diff --git a/packages/sdk/src/api/resources/sessions/client/requests/ListSessionsRequest.ts b/packages/sdk/src/api/resources/sessions/client/requests/ListSessionsRequest.tsindex c839e37f2..bbc6969e9 100644--- a/packages/sdk/src/api/resources/sessions/client/requests/ListSessionsRequest.ts+++ b/packages/sdk/src/api/resources/sessions/client/requests/ListSessionsRequest.ts@@ -9,9 +9,9 @@ import type * as TrueForge from "../../../../index.js";export interface ListSessionsRequest {/** Page size. Defaults to 10, max 100. */limit?: number;- /** Sort sessions by creation time. Defaults to "desc". */+ /** Sort sessions by `updated_at`. Defaults to "desc". */order?: TrueForge.ListSessionsOrder;- /** Opaque token from a previous response `next_page_token`. */+ /** Opaque keyset cursor from a previous response `next_page_token`. */pageToken?: string;/** Inclusive lower bound on `created_at` (ISO-8601 / RFC 3339). */startTimestamp?: Date;diff --git a/packages/sdk/src/api/types/ListSessionsOrder.ts b/packages/sdk/src/api/types/ListSessionsOrder.tsindex b118cd32e..74f37aa2e 100644--- a/packages/sdk/src/api/types/ListSessionsOrder.ts+++ b/packages/sdk/src/api/types/ListSessionsOrder.ts@@ -1,6 +1,6 @@// This file was auto-generated by Fern from our API Definition.-/** Sort sessions by creation time. Defaults to "desc". */+/** Sort sessions by `updated_at`. Defaults to "desc". */export const ListSessionsOrder = {Asc: "asc",Desc: "desc",diff --git a/packages/server/src/db/postgres/migrations/20260814_000001_session_list_updated_at_idx.ts b/packages/server/src/db/postgres/migrations/20260814_000001_session_list_updated_at_idx.tsnew file mode 100644index 000000000..404be10de--- /dev/null+++ b/packages/server/src/db/postgres/migrations/20260814_000001_session_list_updated_at_idx.ts@@ -0,0 +1,19 @@+import { sql, type Kysely } from 'kysely';++/**+ * listSessions orders by `updated_at` (session_id tie-break). Keep+ * `session_list_idx` on `created_at` for start/end timestamp filters.+ */+export async function up(db: Kysely<unknown>): Promise<void> {+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);+ await db.schema+ .createIndex('session_list_updated_at_idx')+ .on('session')+ .columns(['tenant_id', 'updated_at', 'session_id'])+ .execute();+}++export async function down(db: Kysely<unknown>): Promise<void> {+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);+ await db.schema.dropIndex('session_list_updated_at_idx').execute();+}diff --git a/packages/server/src/db/postgres/session-store/queries/sessions.ts b/packages/server/src/db/postgres/session-store/queries/sessions.tsindex 44148164f..8be21d754 100644--- a/packages/server/src/db/postgres/session-store/queries/sessions.ts+++ b/packages/server/src/db/postgres/session-store/queries/sessions.ts@@ -7,7 +7,10 @@ import type {ListSessionsInput,UpdateSessionInput,} from '@truefoundry/utils-core/agent-session/store/ISessionStore';-import { decodeOffsetPageToken, paginateOffsetRows } from '@truefoundry/utils-core/agent-session/store/OffsetPageToken';+import {+ decodeSessionListPageToken,+ paginateSessionListRows,+} from '@truefoundry/utils-core/agent-session/store/SessionListPageToken';import {SessionAlreadyExistsError,SessionNotFoundError,@@ -183,11 +186,16 @@ export async function listSessions(pagination: { next_page_token?: string | undefined; previous_page_token?: string | undefined };}> {const limit = input.limit;- const offset = decodeOffsetPageToken(input.page_token);-const order = input.order ?? 'desc';+ const cursor = decodeSessionListPageToken(input.page_token);- let query = db.selectFrom('session').selectAll().where('tenant_id', '=', input.tenant_id);+ let query = db+ .selectFrom('session')+ .selectAll()+ .select(+ sql<string>`to_char(updated_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`.as('updated_at_cursor'),+ )+ .where('tenant_id', '=', input.tenant_id);if (input.agent_id !== undefined) {query = query.where('agent_id', '=', input.agent_id);@@ -202,21 +210,36 @@ export async function listSessions(query = query.where('created_at', '<=', input.end_timestamp);}+ if (cursor) {+ const sessionId = cursor.session_id;+ // Bind the cursor string and cast in SQL so microsecond precision is preserved+ // (JS Date would truncate to milliseconds).+ const cursorUpdatedAt = sql<Date>`${cursor.updated_at}::timestamptz`;+ if (order === 'asc') {+ query = query.where(eb =>+ eb.or([+ eb('updated_at', '>', cursorUpdatedAt),+ eb.and([eb('updated_at', '=', cursorUpdatedAt), eb('session_id', '>', sessionId)]),+ ]),+ );+ } else {+ query = query.where(eb =>+ eb.or([+ eb('updated_at', '<', cursorUpdatedAt),+ eb.and([eb('updated_at', '=', cursorUpdatedAt), eb('session_id', '<', sessionId)]),+ ]),+ );+ }+ }+if (order === 'asc') {- query = query.orderBy('created_at', 'asc').orderBy('session_id', 'asc');+ query = query.orderBy('updated_at', 'asc').orderBy('session_id', 'asc');} else {- query = query.orderBy('created_at', 'desc').orderBy('session_id', 'desc');+ query = query.orderBy('updated_at', 'desc').orderBy('session_id', 'desc');}- const rows = await query- .limit(limit + 1)- .offset(offset)- .execute();-- const { data, pagination } = paginateOffsetRows(rows, limit, offset);+ const rows = await query.limit(limit + 1).execute();+ const { data: pageRows, pagination } = paginateSessionListRows(rows, limit, row => row.updated_at_cursor);- return {- data: data.map(mapRowToSessionRecord),- pagination,- };+ return { data: pageRows.map(mapRowToSessionRecord), pagination };}diff --git a/packages/server/src/db/sqlite/migrations/20260814_000001_session_list_updated_at_idx.ts b/packages/server/src/db/sqlite/migrations/20260814_000001_session_list_updated_at_idx.tsnew file mode 100644index 000000000..75b682a34--- /dev/null+++ b/packages/server/src/db/sqlite/migrations/20260814_000001_session_list_updated_at_idx.ts@@ -0,0 +1,16 @@+import { type Kysely, sql } from 'kysely';++/**+ * listSessions orders by `updated_at` (session_id tie-break). Keep+ * `session_list_idx` on `created_at` for start/end timestamp filters.+ */+export async function up(db: Kysely<unknown>): Promise<void> {+ await sql`+ CREATE INDEX session_list_updated_at_idx+ ON session (tenant_id, updated_at, session_id)+ `.execute(db);+}++export async function down(db: Kysely<unknown>): Promise<void> {+ await sql`DROP INDEX session_list_updated_at_idx`.execute(db);+}diff --git a/packages/server/src/db/sqlite/session-store/queries/sessions.ts b/packages/server/src/db/sqlite/session-store/queries/sessions.tsindex 02d0acf6e..571ec8844 100644--- a/packages/server/src/db/sqlite/session-store/queries/sessions.ts+++ b/packages/server/src/db/sqlite/session-store/queries/sessions.ts@@ -7,7 +7,10 @@ import type {ListSessionsInput,UpdateSessionInput,} from '@truefoundry/utils-core/agent-session/store/ISessionStore';-import { decodeOffsetPageToken, paginateOffsetRows } from '@truefoundry/utils-core/agent-session/store/OffsetPageToken';+import {+ decodeSessionListPageToken,+ paginateSessionListRows,+} from '@truefoundry/utils-core/agent-session/store/SessionListPageToken';import {SessionAlreadyExistsError,SessionNotFoundError,@@ -187,8 +190,8 @@ export async function listSessions(pagination: { next_page_token?: string | undefined; previous_page_token?: string | undefined };}> {const limit = input.limit;- const offset = decodeOffsetPageToken(input.page_token);const order = input.order ?? 'desc';+ const cursor = decodeSessionListPageToken(input.page_token);let query = db.selectFrom('session').select(sessionSelectColumns).where('tenant_id', '=', input.tenant_id);@@ -205,21 +208,35 @@ export async function listSessions(query = query.where('created_at', '<=', input.end_timestamp.toISOString());}+ if (cursor) {+ const cursorUpdatedAt = cursor.updated_at;+ const sessionId = cursor.session_id;+ if (order === 'asc') {+ query = query.where(eb =>+ eb.or([+ eb('updated_at', '>', cursorUpdatedAt),+ eb.and([eb('updated_at', '=', cursorUpdatedAt), eb('session_id', '>', sessionId)]),+ ]),+ );+ } else {+ query = query.where(eb =>+ eb.or([+ eb('updated_at', '<', cursorUpdatedAt),+ eb.and([eb('updated_at', '=', cursorUpdatedAt), eb('session_id', '<', sessionId)]),+ ]),+ );+ }+ }+if (order === 'asc') {- query = query.orderBy('created_at', 'asc').orderBy('session_id', 'asc');+ query = query.orderBy('updated_at', 'asc').orderBy('session_id', 'asc');} else {- query = query.orderBy('created_at', 'desc').orderBy('session_id', 'desc');+ query = query.orderBy('updated_at', 'desc').orderBy('session_id', 'desc');}- const rows = await query- .limit(limit + 1)- .offset(offset)- .execute();-- const { data, pagination } = paginateOffsetRows(rows, limit, offset);+ const rows = await query.limit(limit + 1).execute();+ // SQLite stores updated_at as ISO text already — use it directly for the keyset cursor.+ const { data: pageRows, pagination } = paginateSessionListRows(rows, limit, row => row.updated_at);- return {- data: data.map(mapRowToSessionRecord),- pagination,- };+ return { data: pageRows.map(mapRowToSessionRecord), pagination };}diff --git a/packages/server/src/schemas/session.ts b/packages/server/src/schemas/session.tsindex fb04ee8fe..1c262c21b 100644--- a/packages/server/src/schemas/session.ts+++ b/packages/server/src/schemas/session.ts@@ -66,9 +66,13 @@ export const ListSessionsRequestQuerySchema = z.enum(['asc', 'desc']).optional().default('desc')- .describe('Sort sessions by creation time. Defaults to "desc".')+ .describe('Sort sessions by `updated_at`. Defaults to "desc".').openapi('ListSessionsOrder'),- page_token: z.string().optional().describe('Opaque token from a previous response `next_page_token`.'),+ page_token: z+ .string()+ .min(1)+ .optional()+ .describe('Opaque keyset cursor from a previous response `next_page_token`.'),start_timestamp: IsoTimestampQueryParam.optional().describe('Inclusive lower bound on `created_at` (ISO-8601 / RFC 3339).',),