Skip to content

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

Standardize persisted event types.

debajyoti-truefoundry2010185d2b73
diff --git a/packages/harness/src/agentSession/TurnHandle.ts b/packages/harness/src/agentSession/TurnHandle.ts
index 6669b56e4..9f5184ee4 100644
--- a/packages/harness/src/agentSession/TurnHandle.ts
+++ b/packages/harness/src/agentSession/TurnHandle.ts
@@ -3,7 +3,6 @@
*/
import type { MCPAuthRequiredEvent, ModelMessageDeltaEvent, ThreadDoneEvent } from '../core/events/eventSchemas';
import { EventType as HarnessEventType, newEventId } from '../core/events/eventSchemas';
-import type { WithRegisteredPassthrough } from '../core/events/PassthroughEvents';
import { getEmptyUsage } from '../core/llm/LLMTypes';
import { getEmptyMetric } from '../core/llm/metrics';
import {
@@ -16,15 +15,13 @@ import {
import type { AgentThreadOrchestrator } from '../core/runtime/AgentThreadOrchestrator';
import type { ITurnResourceResolver } from './ITurnResourceResolver';
import type { TurnRecord } from './models/TurnRecord';
-import { EventType, type TurnCreatedEvent, type TurnDoneEvent, type TurnEvent } from './schemas/events';
+import { EventType, type PersistedTurnEvent, type TurnCreatedEvent, type TurnDoneEvent } from './schemas/events';
import type { TokenPagination } from './schemas/pagination';
import { CancellationReason, type TerminalTurnState, type TurnInputItem, type TurnState } from './schemas/turn';
import type { ISessionStore } from './store/ISessionStore';
/** Streaming yield union — deltas pass through; never persisted. No sequence_number. */
-export type TurnStreamingEvent = WithRegisteredPassthrough<
- TurnCreatedEvent | TurnDoneEvent | TurnEvent | ModelMessageDeltaEvent
->;
+export type TurnStreamingEvent = PersistedTurnEvent | ModelMessageDeltaEvent;
function cancellationReasonFromAbortReason(abortReason: unknown): CancellationReason {
if (abortReason === CancellationReason.ServerExecutionTimeout) {
@@ -301,7 +298,7 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
page_token?: string | undefined;
order?: 'asc' | 'desc' | undefined;
}): Promise<{
- data: WithRegisteredPassthrough<TurnEvent | TurnCreatedEvent | TurnDoneEvent>[];
+ data: PersistedTurnEvent[];
pagination: TokenPagination;
}> {
return this.store.listTurnEvents({
diff --git a/packages/harness/src/agentSession/index.ts b/packages/harness/src/agentSession/index.ts
index 5f98262a8..66e2d2bc8 100644
--- a/packages/harness/src/agentSession/index.ts
+++ b/packages/harness/src/agentSession/index.ts
@@ -27,11 +27,19 @@ export type { Session } from './schemas/session';
export {
EventType,
SessionEventItemSchema,
+ SessionEventSchema,
TurnCreatedEventSchema,
TurnDoneEventSchema,
TurnEventSchema,
} from './schemas/events';
-export type { SessionEventItem, TurnCreatedEvent, TurnDoneEvent, TurnEvent } from './schemas/events';
+export type {
+ PersistedTurnEvent,
+ SessionEvent,
+ SessionEventItem,
+ TurnCreatedEvent,
+ TurnDoneEvent,
+ TurnEvent,
+} from './schemas/events';
export { TokenPaginationSchema } from './schemas/pagination';
export type { TokenPagination } from './schemas/pagination';
diff --git a/packages/harness/src/agentSession/schemas/events.ts b/packages/harness/src/agentSession/schemas/events.ts
index ce446e1eb..d2d3d16ac 100644
--- a/packages/harness/src/agentSession/schemas/events.ts
+++ b/packages/harness/src/agentSession/schemas/events.ts
@@ -17,6 +17,7 @@ import {
ToolResponseEventSchema,
ToolResponseRequiredEventSchema,
} from '../../core/events/eventSchemas';
+import type { WithRegisteredPassthrough } from '../../core/events/PassthroughEvents';
import {
TurnInputItemSchema,
TurnStateCancelledSchema,
@@ -71,7 +72,7 @@ export const TurnEventSchema = z
.openapi('TurnEvent');
/** turn.created, turn.done, or a persisted turn event — no deltas. */
-const SessionEventSchema = z
+export const SessionEventSchema = z
.discriminatedUnion('type', [TurnCreatedEventSchema, TurnDoneEventSchema, ...TurnEventSchema.options])
.openapi('SessionEvent');
@@ -86,4 +87,13 @@ export const SessionEventItemSchema = z
export type TurnCreatedEvent = z.infer<typeof TurnCreatedEventSchema>;
export type TurnDoneEvent = z.infer<typeof TurnDoneEventSchema>;
export type TurnEvent = z.infer<typeof TurnEventSchema>;
-export type SessionEventItem = z.infer<typeof SessionEventItemSchema>;
+export type SessionEvent = z.infer<typeof SessionEventSchema>;
+/**
+ * Durable turn event log entries: {@link SessionEvent} plus any registered
+ * passthrough events. Shared by append and list operations.
+ */
+export type PersistedTurnEvent = WithRegisteredPassthrough<SessionEvent>;
+export type SessionEventItem = {
+ turn_id: string;
+ event: PersistedTurnEvent;
+};
diff --git a/packages/harness/src/agentSession/store/ISessionStore.ts b/packages/harness/src/agentSession/store/ISessionStore.ts
index b42fc97f9..e7a97cac8 100644
--- a/packages/harness/src/agentSession/store/ISessionStore.ts
+++ b/packages/harness/src/agentSession/store/ISessionStore.ts
@@ -1,5 +1,4 @@
import type { MCPServerInitInfo, ThreadOverwriteContextEvent } from '../../core/events/eventSchemas';
-import type { WithRegisteredPassthrough } from '../../core/events/PassthroughEvents';
import type { CompletionUsage } from '../../core/llm/LLMTypes';
import type {
AgentThreadSnapshot,
@@ -9,7 +8,7 @@ import type {
import type { SandboxInfo } from '../../core/sandbox/Sandbox';
import type { SessionRecord } from '../models/SessionRecord';
import type { TurnRecord } from '../models/TurnRecord';
-import type { SessionEventItem, TurnCreatedEvent, TurnDoneEvent, TurnEvent } from '../schemas/events';
+import type { PersistedTurnEvent, SessionEventItem } from '../schemas/events';
import type { TokenPagination } from '../schemas/pagination';
import type { TerminalTurnState } from '../schemas/turn';
@@ -70,7 +69,7 @@ export type AppendToEventsInput = {
tenant_name: string;
session_id: string;
turn_id: string;
- events: WithRegisteredPassthrough<TurnEvent | TurnCreatedEvent | TurnDoneEvent>[];
+ events: PersistedTurnEvent[];
};
export type AddThreadsInput = {
@@ -264,7 +263,7 @@ export interface ISessionStore<
/** Paginated read of one turn's persisted events, insertion order (asc default). */
listTurnEvents(input: ListTurnEventsInput): Promise<{
- data: WithRegisteredPassthrough<TurnEvent | TurnCreatedEvent | TurnDoneEvent>[];
+ data: PersistedTurnEvent[];
pagination: TokenPagination;
}>;
diff --git a/packages/harness/src/agentSession/store/InMemorySessionStore.ts b/packages/harness/src/agentSession/store/InMemorySessionStore.ts
index 391b3c174..8d686e179 100644
--- a/packages/harness/src/agentSession/store/InMemorySessionStore.ts
+++ b/packages/harness/src/agentSession/store/InMemorySessionStore.ts
@@ -1,7 +1,6 @@
-import type { WithRegisteredPassthrough } from '../../core/events/PassthroughEvents';
import type { SessionRecord } from '../models/SessionRecord';
import type { TurnRecord } from '../models/TurnRecord';
-import type { SessionEventItem, TurnCreatedEvent, TurnDoneEvent, TurnEvent } from '../schemas/events';
+import type { PersistedTurnEvent, SessionEventItem } from '../schemas/events';
import type { TokenPagination } from '../schemas/pagination';
import type {
AddThreadsInput,
@@ -28,7 +27,7 @@ import { SessionStoreConflictError, SessionStoreNotFoundError } from './SessionS
/* eslint-disable @typescript-eslint/require-await -- in-memory store is synchronous; methods stay async so thrown SessionStore*Error reject as Promises for ISessionStore callers */
-type StoredEvent = WithRegisteredPassthrough<TurnEvent | TurnCreatedEvent | TurnDoneEvent>;
+type StoredEvent = PersistedTurnEvent;
interface StoredSession<TSessionCustom extends object> {
record: SessionRecord<TSessionCustom>;
@@ -312,7 +311,7 @@ export class InMemorySessionStore<
}
async listTurnEvents(input: ListTurnEventsInput): Promise<{
- data: WithRegisteredPassthrough<TurnEvent | TurnCreatedEvent | TurnDoneEvent>[];
+ data: PersistedTurnEvent[];
pagination: TokenPagination;
}> {
const list = this.events.get(turnKey(input.tenant_name, input.session_id, input.turn_id));
@@ -344,9 +343,7 @@ export class InMemorySessionStore<
for (const turnId of turnIds) {
const evts = this.events.get(turnKey(input.tenant_name, input.session_id, turnId)) ?? [];
for (const event of evts) {
- if (isSessionFeedEvent(event)) {
- flattened.push({ turn_id: turnId, event });
- }
+ flattened.push({ turn_id: turnId, event });
}
}
// Newest first for session feed.
@@ -376,7 +373,3 @@ export class InMemorySessionStore<
return chain;
}
}
-
-function isSessionFeedEvent(event: StoredEvent): event is TurnCreatedEvent | TurnDoneEvent | TurnEvent {
- return event.type === 'turn.created' || event.type === 'turn.done' || !('event' in event);
-}
diff --git a/packages/harness/tests/agentSession/inMemorySessionStore.test.ts b/packages/harness/tests/agentSession/inMemorySessionStore.test.ts
index 8893e3d46..7408bbd97 100644
--- a/packages/harness/tests/agentSession/inMemorySessionStore.test.ts
+++ b/packages/harness/tests/agentSession/inMemorySessionStore.test.ts
@@ -1,4 +1,5 @@
import { MAIN_THREAD_ID } from '../../src/agentSession/models/TurnRecord';
+import type { PersistedTurnEvent } from '../../src/agentSession/schemas/events';
import { CancellationReason } from '../../src/agentSession/schemas/turn';
import type { ISessionStore } from '../../src/agentSession/store/ISessionStore';
import { InMemorySessionStore } from '../../src/agentSession/store/InMemorySessionStore';
@@ -556,6 +557,32 @@ function runStoreContractSuite(createStore: () => ISessionStore) {
expect(data.every(row => row.event.type === 'turn.created')).toBe(true);
});
+ it('listSessionEvents includes registered passthrough events', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn({
+ tenant_name: tenant,
+ turn: makeRunningTurnRecord({ sessionId, turnId: 't1' }),
+ });
+ const passthrough = {
+ type: 'custom.event',
+ event: { value: 1 },
+ } as unknown as PersistedTurnEvent;
+ await store.appendToEvents({
+ tenant_name: tenant,
+ session_id: sessionId,
+ turn_id: 't1',
+ events: [passthrough],
+ });
+
+ const { data } = await store.listSessionEvents({
+ tenant_name: tenant,
+ session_id: sessionId,
+ limit: 10,
+ });
+ expect(data).toEqual([{ turn_id: 't1', event: passthrough }]);
+ });
+
it('listSessionEvents with last_turn_id scopes to that branch, excluding fork siblings', async () => {
const store = createStore();
await seedSession(store);