Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat(turns): add TurnHandle.get to load turns without an extra session read (#26)

Bhavesh Patel7b7afc1cc5b1
diff --git a/packages/harness/src/agent-session/SessionHandle.ts b/packages/harness/src/agent-session/SessionHandle.ts
index d1f2bce4e..a0895536c 100644
--- a/packages/harness/src/agent-session/SessionHandle.ts
+++ b/packages/harness/src/agent-session/SessionHandle.ts
@@ -309,17 +309,11 @@ export class SessionHandle<
/** Returns the turn handle (store-backed; not executable), or undefined if not found. */
async getTurn(turn_id: string): Promise<TurnHandle<TTurnCustom> | undefined> {
- const turn = await this.store.getTurn({
+ return TurnHandle.get({
+ store: this.store,
session_id: this.session.session_id,
turn_id,
});
- if (!turn) {
- return undefined;
- }
- return TurnHandle.fromRecord({
- store: this.store,
- turn,
- });
}
/** Paginated list of this session's turn rows (no snapshot). */
diff --git a/packages/harness/src/agent-session/TurnHandle.ts b/packages/harness/src/agent-session/TurnHandle.ts
index 4b7803ac8..f0bb2be03 100644
--- a/packages/harness/src/agent-session/TurnHandle.ts
+++ b/packages/harness/src/agent-session/TurnHandle.ts
@@ -115,6 +115,24 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
return new TurnHandle(options);
}
+ static async get<TCustom extends object = Record<string, never>>(options: {
+ store: ISessionStore<object, TCustom>;
+ session_id: string;
+ turn_id: string;
+ }): Promise<TurnHandle<TCustom> | undefined> {
+ const turn = await options.store.getTurn({
+ session_id: options.session_id,
+ turn_id: options.turn_id,
+ });
+ if (!turn) {
+ return undefined;
+ }
+ return TurnHandle.fromRecord({
+ store: options.store,
+ turn,
+ });
+ }
+
get id(): string {
return this.turn.turn_id;
}
diff --git a/packages/harness/tests/agent-session/sessions.test.ts b/packages/harness/tests/agent-session/sessions.test.ts
index f8efb442e..eaf7ff552 100644
--- a/packages/harness/tests/agent-session/sessions.test.ts
+++ b/packages/harness/tests/agent-session/sessions.test.ts
@@ -1,6 +1,7 @@
import { EventType } from '../../src/agent-session/schemas/events';
import { Sessions } from '../../src/agent-session/Sessions';
import { InMemorySessionStore } from '../../src/agent-session/store/InMemorySessionStore';
+import { TurnHandle } from '../../src/agent-session/TurnHandle';
import { makeAgentSpec, makeTestResolver, mintTestTurnId } from './testHelpers';
describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
@@ -52,6 +53,42 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
expect(sessionRecord?.last_turn_id).toBe(turn.id);
});
+ it('loads turn handles without reading the session', async () => {
+ const store = new InMemorySessionStore();
+ const sessions = new Sessions({ sessionStore: store });
+ const session = await sessions.create({
+ tenant_id: tenant,
+ session_id: 's1',
+ agent_spec: makeAgentSpec(),
+ });
+ const created = await session.createTurn({
+ turn_id: mintTestTurnId(),
+ previous_turn_id: null,
+ signal: new AbortController().signal,
+ resolver: makeTestResolver(),
+ });
+ const getSession = jest.spyOn(store, 'getSession');
+
+ const direct = await TurnHandle.get({
+ store,
+ session_id: 's1',
+ turn_id: created.id,
+ });
+ const throughSession = await session.getTurn(created.id);
+ const missingDirect = await TurnHandle.get({
+ store,
+ session_id: 's1',
+ turn_id: 'missing-turn',
+ });
+ const missingThroughSession = await session.getTurn('missing-turn');
+
+ expect(direct?.id).toBe(created.id);
+ expect(throughSession?.id).toBe(created.id);
+ expect(missingDirect).toBeUndefined();
+ expect(missingThroughSession).toBeUndefined();
+ expect(getSession).not.toHaveBeenCalled();
+ });
+
it('custom value vs merge-fn', async () => {
const store = new InMemorySessionStore<{ tag: string }, { n: number }>();
const sessions = new Sessions({ sessionStore: store });
diff --git a/packages/server/src/apis/turns.ts b/packages/server/src/apis/turns.ts
index 25018ae71..5ff25d200 100644
--- a/packages/server/src/apis/turns.ts
+++ b/packages/server/src/apis/turns.ts
@@ -1,10 +1,11 @@
import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
-import type { Sessions, Turn, TurnStreamingEvent } from '@truefoundry/utils/agent-session';
+import type { ISessionStore, Sessions, Turn, TurnStreamingEvent } from '@truefoundry/utils/agent-session';
import {
CancellationReason,
EventType,
SessionStoreConflictError,
SessionStoreNotFoundError,
+ TurnHandle,
TurnResourceResolver,
type TurnInputItem,
type TurnRecordWithoutSnapshot,
@@ -50,6 +51,7 @@ function toWireTurn(record: TurnRecordWithoutSnapshot): Turn {
export interface TurnsRouterDeps {
sessions: Sessions;
+ sessionStore: ISessionStore;
activeTurns: ActiveTurnRegistry;
modelStore: ModelStore;
mcpStore: McpStore;
@@ -190,11 +192,11 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
const getTurnHandler: RouteHandler<typeof getTurnRoute> = async c => {
const { sessionId, turnId } = c.req.valid('param');
- const session = await deps.sessions.get({ tenant_id: TENANT_ID, session_id: sessionId });
- if (!session) {
- return c.json({ error: { message: `Session not found: ${sessionId}` } }, 404);
- }
- const turn = await session.getTurn(turnId);
+ const turn = await TurnHandle.get({
+ store: deps.sessionStore,
+ session_id: sessionId,
+ turn_id: turnId,
+ });
if (!turn) {
return c.json({ error: { message: `Turn not found: ${turnId}` } }, 404);
}
@@ -204,11 +206,11 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
const listTurnEventsHandler: RouteHandler<typeof listTurnEventsRoute> = async c => {
const { sessionId, turnId } = c.req.valid('param');
const query = c.req.valid('query');
- const session = await deps.sessions.get({ tenant_id: TENANT_ID, session_id: sessionId });
- if (!session) {
- return c.json({ error: { message: `Session not found: ${sessionId}` } }, 404);
- }
- const turn = await session.getTurn(turnId);
+ const turn = await TurnHandle.get({
+ store: deps.sessionStore,
+ session_id: sessionId,
+ turn_id: turnId,
+ });
if (!turn) {
return c.json({ error: { message: `Turn not found: ${turnId}` } }, 404);
}
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index e8e9b0aae..f42000600 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -126,6 +126,7 @@ export function createServerApp(deps: ServerDeps) {
'/api/v1/sessions',
createTurnsRouter({
sessions: deps.sessions,
+ sessionStore: deps.sessionStore,
activeTurns: deps.activeTurns,
modelStore: deps.modelStore,
mcpStore: deps.mcpStore,
diff --git a/packages/server/tests/unit/apis/deletedSessionCrud.test.ts b/packages/server/tests/unit/apis/deletedSessionCrud.test.ts
index 94996a603..ed82b9586 100644
--- a/packages/server/tests/unit/apis/deletedSessionCrud.test.ts
+++ b/packages/server/tests/unit/apis/deletedSessionCrud.test.ts
@@ -37,6 +37,7 @@ describe('public CRUD after session deletion', () => {
'/',
createTurnsRouter({
sessions,
+ sessionStore,
activeTurns,
modelStore,
mcpStore,
diff --git a/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts b/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts
index bf8ae2e0e..23542d66b 100644
--- a/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts
+++ b/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts
@@ -1,6 +1,6 @@
import { OpenAPIHono } from '@hono/zod-openapi';
import type { Sessions } from '@truefoundry/utils/agent-session';
-import { TurnNotFoundError } from '@truefoundry/utils/agent-session';
+import { InMemorySessionStore, TurnNotFoundError } from '@truefoundry/utils/agent-session';
import { createLogger } from 'winston';
import { createTurnsRouter } from '../../../src/apis/turns';
import { McpStore } from '../../../src/legacy-registry-store/McpStore';
@@ -36,6 +36,7 @@ describe('turn SSE after session deletion', () => {
'/',
createTurnsRouter({
sessions,
+ sessionStore: new InMemorySessionStore(),
activeTurns: new ActiveTurnRegistry(),
modelStore: new ModelStore([]),
mcpStore: new McpStore([]),