Skip to content

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.json
index 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.ts
index 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.ts
index 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: string
return `${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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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).',
),