Skip to content

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

Cap persisted turn ancestor windows.

debajyoti-truefoundry92f2eb004e92
diff --git a/packages/harness/src/agentSession/SessionHandle.ts b/packages/harness/src/agentSession/SessionHandle.ts
index 0e2dde257..e7b9323fc 100644
--- a/packages/harness/src/agentSession/SessionHandle.ts
+++ b/packages/harness/src/agentSession/SessionHandle.ts
@@ -17,13 +17,15 @@ import type { AgentTracing } from '../core/tracing/AgentTracing';
import { builtinsFromSpec } from './builtinsFromSpec';
import type { ITurnResourceResolver } from './ITurnResourceResolver';
import type { SessionRecord } from './models/SessionRecord';
-import { MAIN_THREAD_ID, TURN_SERIALIZATION_VERSION, type TurnRecord } from './models/TurnRecord';
+import { MAIN_THREAD_ID, type TurnRecord } from './models/TurnRecord';
import type { TurnCreatedEvent, TurnDoneEvent, TurnEvent } from './schemas/events';
import type { TokenPagination } from './schemas/pagination';
import type { TurnInputItem } from './schemas/turn';
import type { ISessionStore } from './store/ISessionStore';
import { TurnHandle } from './TurnHandle';
+/** How many recent ancestors SessionHandle persists on each turn. Store-local. */
+const MAX_TURN_ANCESTORS = 20;
function resolvePreviousTurnId(
requested: string | null | undefined,
lastTurnId: string | undefined,
@@ -187,11 +189,11 @@ export class SessionHandle<
const turnId = ulid().toLowerCase();
const now = new Date().toISOString();
const turnRecord: TurnRecord<TTurnCustom> = {
- serialization_version: TURN_SERIALIZATION_VERSION,
turn_id: turnId,
session_id: this.session.session_id,
first_turn_id: previous?.first_turn_id ?? turnId,
- ancestor_ids: previous ? [...previous.ancestor_ids, previous.turn_id] : [],
+ // Truncate to a recent window; stores spill if they need older ancestors.
+ ancestor_ids: previous ? [...previous.ancestor_ids, previous.turn_id].slice(-MAX_TURN_ANCESTORS) : [],
previous_turn_id: previousTurnId,
state: { status: 'running' },
input: input.input ?? [],
diff --git a/packages/harness/src/agentSession/index.ts b/packages/harness/src/agentSession/index.ts
index 7607c5c10..58ac109bc 100644
--- a/packages/harness/src/agentSession/index.ts
+++ b/packages/harness/src/agentSession/index.ts
@@ -37,7 +37,7 @@ export { TokenPaginationSchema } from './schemas/pagination';
export type { TokenPagination } from './schemas/pagination';
export type { SessionRecord } from './models/SessionRecord';
-export { MAIN_THREAD_ID, TURN_SERIALIZATION_VERSION } from './models/TurnRecord';
+export { MAIN_THREAD_ID } from './models/TurnRecord';
export type { TurnRecord, TurnSnapshot } from './models/TurnRecord';
export { InMemorySessionStore } from './store/InMemorySessionStore';
diff --git a/packages/harness/src/agentSession/models/TurnRecord.ts b/packages/harness/src/agentSession/models/TurnRecord.ts
index 237f8c797..ccc3fa73d 100644
--- a/packages/harness/src/agentSession/models/TurnRecord.ts
+++ b/packages/harness/src/agentSession/models/TurnRecord.ts
@@ -18,10 +18,14 @@ export interface TurnSnapshot {
}
export interface TurnRecord<TCustom extends object = Record<string, never>> {
- serialization_version: number;
turn_id: string;
session_id: string;
first_turn_id: string;
+ /**
+ * Newest-last list of recent ancestor turn ids. Writers may truncate to a
+ * recent window; this need not reach the session root. Store readers that
+ * need the full chain spill through older turns' own `ancestor_ids`.
+ */
ancestor_ids: string[];
previous_turn_id?: string | undefined;
state: TurnState;
@@ -31,6 +35,3 @@ export interface TurnRecord<TCustom extends object = Record<string, never>> {
updated_at: string;
custom?: TCustom | undefined;
}
-
-/** Current serialization version for TurnRecord. */
-export const TURN_SERIALIZATION_VERSION = 1;
diff --git a/packages/harness/src/agentSession/store/ISessionStore.ts b/packages/harness/src/agentSession/store/ISessionStore.ts
index 90ac8244f..465dc56df 100644
--- a/packages/harness/src/agentSession/store/ISessionStore.ts
+++ b/packages/harness/src/agentSession/store/ISessionStore.ts
@@ -230,8 +230,10 @@ export interface ISessionStore<
* Includes events from **running** turns (the HTTP layer may 409 separately;
* that is not store semantics). Ordering: newest-first across the flattened
* feed. `last_turn_id` anchors the window to that turn plus its ancestors
- * (the `ancestor_ids` chain, oldest first) — sibling branches from forks are
- * excluded; omit to use the full session turn list.
+ * (oldest first). `ancestor_ids` may be only the previous N ancestors and
+ * need not reach the root — implementations that need the full chain must
+ * spill through older turns' own `ancestor_ids`. Sibling branches from forks
+ * are excluded; omit `last_turn_id` to use the full session turn list.
*/
listSessionEvents(input: {
tenant_name: string;
diff --git a/packages/harness/src/agentSession/store/InMemorySessionStore.ts b/packages/harness/src/agentSession/store/InMemorySessionStore.ts
index a1b96fbf2..55ac7d63a 100644
--- a/packages/harness/src/agentSession/store/InMemorySessionStore.ts
+++ b/packages/harness/src/agentSession/store/InMemorySessionStore.ts
@@ -442,7 +442,7 @@ export class InMemorySessionStore<
if (!anchor) {
throw new SessionStoreNotFoundError(`Turn not found: ${input.last_turn_id}`);
}
- turnIds = [...anchor.ancestor_ids, anchor.turn_id];
+ turnIds = this.resolveAncestorChain(input.tenant_name, input.session_id, anchor);
}
const flattened: { turn_id: string; event: TurnCreatedEvent | TurnDoneEvent | TurnEvent }[] = [];
for (const turnId of turnIds) {
@@ -458,6 +458,27 @@ export class InMemorySessionStore<
const page = paginate(flattened, input.limit, input.page_token);
return { data: deepCopy(page.data), pagination: page.pagination };
}
+
+ /**
+ * Full chain (oldest first, anchor last). `ancestor_ids` may be only the
+ * previous N ancestors, so spill through the oldest ancestor's own window
+ * until a root or gap. A missing turn or repeated id ends the walk.
+ */
+ private resolveAncestorChain(tenant: string, sessionId: string, anchor: TurnRecord<TTurnCustom>): string[] {
+ const chain = [...anchor.ancestor_ids, anchor.turn_id];
+ const seen = new Set(chain);
+ let oldestId = chain[0];
+ while (oldestId && oldestId !== anchor.turn_id) {
+ const oldest = this.turns.get(turnKey(tenant, sessionId, oldestId));
+ if (!oldest) break;
+ const older = oldest.ancestor_ids.filter(id => !seen.has(id));
+ if (older.length === 0) break;
+ chain.unshift(...older);
+ for (const id of older) seen.add(id);
+ oldestId = older[0];
+ }
+ return chain;
+ }
}
function isSessionFeedEvent(event: StoredEvent): event is TurnCreatedEvent | TurnDoneEvent | TurnEvent {
diff --git a/packages/harness/tests/agentSession/inMemorySessionStore.test.ts b/packages/harness/tests/agentSession/inMemorySessionStore.test.ts
index 826c8b590..8ff2622e6 100644
--- a/packages/harness/tests/agentSession/inMemorySessionStore.test.ts
+++ b/packages/harness/tests/agentSession/inMemorySessionStore.test.ts
@@ -1,4 +1,4 @@
-import { MAIN_THREAD_ID, TURN_SERIALIZATION_VERSION } from '../../src/agentSession/models/TurnRecord';
+import { MAIN_THREAD_ID } from '../../src/agentSession/models/TurnRecord';
import { CancellationReason } from '../../src/agentSession/schemas/turn';
import type { ISessionStore } from '../../src/agentSession/store/ISessionStore';
import { InMemorySessionStore } from '../../src/agentSession/store/InMemorySessionStore';
@@ -597,6 +597,44 @@ function runStoreContractSuite(createStore: () => ISessionStore) {
}),
).rejects.toBeInstanceOf(SessionStoreNotFoundError);
});
+
+ it('listSessionEvents spills through truncated ancestor_ids windows to reach the chain root', async () => {
+ const store = createStore();
+ await seedSession(store);
+ // Writer-chosen window shorter than the chain — store must spill.
+ const ancestorWindow = 3;
+ const chainLength = ancestorWindow + 5;
+ const ids = Array.from({ length: chainLength }, (_, i) => `t${String(i + 1)}`);
+ for (let i = 0; i < ids.length; i++) {
+ const window = ids.slice(Math.max(0, i - ancestorWindow), i);
+ await store.createTurn({
+ tenant_name: tenant,
+ turn: {
+ ...makeRunningTurnRecord({
+ sessionId,
+ turnId: ids[i]!,
+ ...(i > 0 ? { previousTurnId: ids[i - 1], firstTurnId: ids[0] } : {}),
+ }),
+ ancestor_ids: window,
+ },
+ });
+ await store.appendToEvents({
+ tenant_name: tenant,
+ session_id: sessionId,
+ turn_id: ids[i]!,
+ events: [makeTurnCreatedEvent(ids[i]!)],
+ });
+ }
+ const tip = ids.at(-1)!;
+ const { data } = await store.listSessionEvents({
+ tenant_name: tenant,
+ session_id: sessionId,
+ limit: chainLength + 10,
+ last_turn_id: tip,
+ });
+ // Full chain reachable despite truncated windows, newest first.
+ expect(data.map(row => row.turn_id)).toEqual([...ids].reverse());
+ });
});
describe('deep-copy boundary', () => {
@@ -617,11 +655,6 @@ function runStoreContractSuite(createStore: () => ISessionStore) {
expect(keys.some(k => k.startsWith('subscribe'))).toBe(false);
});
});
-
- // Keep serialization_version visible in fixtures
- it('turn records use TURN_SERIALIZATION_VERSION', () => {
- expect(TURN_SERIALIZATION_VERSION).toBe(1);
- });
}
describe('InMemorySessionStore (ISessionStore contract)', () => {
diff --git a/packages/harness/tests/agentSession/testHelpers.ts b/packages/harness/tests/agentSession/testHelpers.ts
index efd982199..2bcc17a18 100644
--- a/packages/harness/tests/agentSession/testHelpers.ts
+++ b/packages/harness/tests/agentSession/testHelpers.ts
@@ -1,5 +1,5 @@
import type { ITurnResourceResolver } from '../../src/agentSession/ITurnResourceResolver';
-import { MAIN_THREAD_ID, TURN_SERIALIZATION_VERSION, type TurnRecord } from '../../src/agentSession/models/TurnRecord';
+import { MAIN_THREAD_ID, type TurnRecord } from '../../src/agentSession/models/TurnRecord';
import { AgentSpecSchema, type AgentSpec } from '../../src/agentSession/schemas/agentSpec';
import { TurnResourceResolver } from '../../src/agentSession/TurnResourceResolver';
import type { AgentCapability } from '../../src/core/capabilities/AgentCapability';
@@ -126,7 +126,6 @@ export function makeRunningTurnRecord(input: {
}): TurnRecord {
const now = new Date().toISOString();
return {
- serialization_version: TURN_SERIALIZATION_VERSION,
turn_id: input.turnId,
session_id: input.sessionId,
first_turn_id: input.firstTurnId ?? input.turnId,