Skip to content

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

feat: add table for turn inbound events (#805)

Heer Ambavi5adde289683b
diff --git a/.changeset/20260924052304-regenerate-sdk-from-openapi.md b/.changeset/20260924052304-regenerate-sdk-from-openapi.md
new file mode 100644
index 000000000..efd8ff00f
--- /dev/null
+++ b/.changeset/20260924052304-regenerate-sdk-from-openapi.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Regenerate SDK from updated OpenAPI spec.
diff --git a/.changeset/turn-inbound-events.md b/.changeset/turn-inbound-events.md
new file mode 100644
index 000000000..e7c335ab2
--- /dev/null
+++ b/.changeset/turn-inbound-events.md
@@ -0,0 +1,6 @@
+---
+"@truefoundry/trueforge-core": patch
+"@truefoundry/trueforge": patch
+---
+
+Add `turn_inbound_events` store API for durable tip HITL send-event inbox (insert / list unconsumed / mark consumed), with Postgres and SQLite migrations.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 3cbb63504..76efd9628 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -5232,8 +5232,8 @@
"discriminator": {
"mapping": {
"user.message": "#/components/schemas/UserMessage",
- "user.tool_approval": "#/components/schemas/UserToolApprovalEvent",
- "user.tool_response": "#/components/schemas/UserToolResponseEvent"
+ "user.tool_approval": "#/components/schemas/UserToolApprovalInputEvent",
+ "user.tool_response": "#/components/schemas/UserToolResponseInputEvent"
},
"propertyName": "type"
},
@@ -5242,10 +5242,10 @@
"$ref": "#/components/schemas/UserMessage"
},
{
- "$ref": "#/components/schemas/UserToolApprovalEvent"
+ "$ref": "#/components/schemas/UserToolApprovalInputEvent"
},
{
- "$ref": "#/components/schemas/UserToolResponseEvent"
+ "$ref": "#/components/schemas/UserToolResponseInputEvent"
}
]
},
@@ -5764,7 +5764,7 @@
}
]
},
- "UserToolApprovalEvent": {
+ "UserToolApprovalInputEvent": {
"properties": {
"approval": {
"$ref": "#/components/schemas/ApprovalDecision"
@@ -5795,7 +5795,7 @@
],
"type": "object"
},
- "UserToolResponseEvent": {
+ "UserToolResponseInputEvent": {
"properties": {
"content": {
"description": "Client-side tool result content.",
diff --git a/docs/openapi.json b/docs/openapi.json
index 3cbb63504..76efd9628 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -5232,8 +5232,8 @@
"discriminator": {
"mapping": {
"user.message": "#/components/schemas/UserMessage",
- "user.tool_approval": "#/components/schemas/UserToolApprovalEvent",
- "user.tool_response": "#/components/schemas/UserToolResponseEvent"
+ "user.tool_approval": "#/components/schemas/UserToolApprovalInputEvent",
+ "user.tool_response": "#/components/schemas/UserToolResponseInputEvent"
},
"propertyName": "type"
},
@@ -5242,10 +5242,10 @@
"$ref": "#/components/schemas/UserMessage"
},
{
- "$ref": "#/components/schemas/UserToolApprovalEvent"
+ "$ref": "#/components/schemas/UserToolApprovalInputEvent"
},
{
- "$ref": "#/components/schemas/UserToolResponseEvent"
+ "$ref": "#/components/schemas/UserToolResponseInputEvent"
}
]
},
@@ -5764,7 +5764,7 @@
}
]
},
- "UserToolApprovalEvent": {
+ "UserToolApprovalInputEvent": {
"properties": {
"approval": {
"$ref": "#/components/schemas/ApprovalDecision"
@@ -5795,7 +5795,7 @@
],
"type": "object"
},
- "UserToolResponseEvent": {
+ "UserToolResponseInputEvent": {
"properties": {
"content": {
"description": "Client-side tool result content.",
diff --git a/packages/trueforge-core/src/agent-session/index.ts b/packages/trueforge-core/src/agent-session/index.ts
index 3b9b5d66c..a3caa641f 100644
--- a/packages/trueforge-core/src/agent-session/index.ts
+++ b/packages/trueforge-core/src/agent-session/index.ts
@@ -9,6 +9,7 @@ export type { AgentSpec, Skill } from './schemas/agentSpec';
export {
CancellationReason,
CreateTurnRequestSchema,
+ TurnInboundEventItemSchema,
TurnInputItemSchema,
TurnMetricsSchema,
TurnSchema,
@@ -19,7 +20,14 @@ export {
TurnStateRunningSchema,
TurnStateSchema,
} from './schemas/turn';
-export type { TerminalTurnState, Turn, TurnInputItem, TurnMetrics, TurnState } from './schemas/turn';
+export type {
+ TerminalTurnState,
+ Turn,
+ TurnInboundEventItem,
+ TurnInputItem,
+ TurnMetrics,
+ TurnState,
+} from './schemas/turn';
export {
SessionMetadataSchema,
@@ -80,6 +88,7 @@ export type {
GetSessionInput,
GetTurnInput,
ISessionStore,
+ InsertTurnInboundEventsInput,
ListSessionEventsInput,
ListSessionsInput,
ListTurnEventsInput,
@@ -105,6 +114,7 @@ export {
SessionStoreInvariantError,
SessionStoreNotFoundError,
TurnAlreadyExistsError,
+ TurnEventAlreadyExistsError,
TurnNotFoundError,
TurnNotRunningError,
} from './store/SessionStoreErrors';
diff --git a/packages/trueforge-core/src/agent-session/schemas/turn.ts b/packages/trueforge-core/src/agent-session/schemas/turn.ts
index 59ec0b9a0..3c08a46db 100644
--- a/packages/trueforge-core/src/agent-session/schemas/turn.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/turn.ts
@@ -176,8 +176,13 @@ export const CreateTurnRequestSchema = z
})
.openapi('CreateTurnRequest');
+export const TurnInboundEventItemSchema = z
+ .discriminatedUnion('type', [UserToolApprovalMessageSchema, UserToolResponseMessageSchema])
+ .openapi('TurnInboundEventItem');
+
export type Turn = z.infer<typeof TurnSchema>;
export type TurnInputItem = z.infer<typeof TurnInputItemSchema>;
export type TurnState = z.infer<typeof TurnStateSchema>;
export type TerminalTurnState = Exclude<TurnState, { status: 'running' }>;
export type TurnMetrics = z.infer<typeof TurnMetricsSchema>;
+export type TurnInboundEventItem = z.infer<typeof TurnInboundEventItemSchema>;
diff --git a/packages/trueforge-core/src/agent-session/store/ISessionStore.ts b/packages/trueforge-core/src/agent-session/store/ISessionStore.ts
index b11a7ca1d..e423cfff6 100644
--- a/packages/trueforge-core/src/agent-session/store/ISessionStore.ts
+++ b/packages/trueforge-core/src/agent-session/store/ISessionStore.ts
@@ -12,7 +12,7 @@ import type { TurnRecord } from '../models/TurnRecord';
import type { PersistedTurnEvent, SessionEventItem } from '../schemas/events';
import type { TokenPagination } from '../schemas/pagination';
import type { SessionMetadata } from '../schemas/session';
-import type { CancellationReason, TerminalTurnState } from '../schemas/turn';
+import type { CancellationReason, TerminalTurnState, TurnInboundEventItem } from '../schemas/turn';
/**
* Caller-supplied fields for creating a session; the store owns timestamps and tip state.
@@ -170,6 +170,21 @@ export interface AppendToEventsInput {
events: PersistedTurnEvent[];
}
+export interface InsertTurnInboundEventsInput {
+ session_id: string;
+ /** Tip that receives this batch. One send = one tip; stamp every row with this id. */
+ turn_id: string;
+ /**
+ * Caller mints `event_id` (monotonic ULID) — same contract as session_event.
+ * Empty array is a no-op.
+ */
+ events: {
+ event_id: string;
+ payload: TurnInboundEventItem;
+ created_at: string;
+ }[];
+}
+
export interface AddThreadsInput {
session_id: string;
turn_id: string;
@@ -360,6 +375,15 @@ export interface ISessionStore<
*/
appendToEvents(input: AppendToEventsInput): Promise<void>;
+ /**
+ * Durable inbound send-event inbox for a tip. Tip must be non-terminal
+ * (v1: `running`; `paused` when that status lands) — terminal tip →
+ * {@link TurnNotRunningError}. Missing session → {@link SessionNotFoundError};
+ * unknown turn → {@link TurnNotFoundError}. Duplicate `event_id` on that tip →
+ * {@link TurnEventAlreadyExistsError}.
+ */
+ insertTurnInboundEvents(input: InsertTurnInboundEventsInput): Promise<void>;
+
/** Adds thread snapshots to the turn (sub-agent spawns). */
addThreads(input: AddThreadsInput): Promise<void>;
diff --git a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
index a2e114b61..88ee5b224 100644
--- a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
+++ b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
@@ -4,7 +4,7 @@ import type { SessionRecord } from '../models/SessionRecord';
import type { TurnRecord, TurnSnapshot } from '../models/TurnRecord';
import type { PersistedTurnEvent, SessionEventItem } from '../schemas/events';
import type { TokenPagination } from '../schemas/pagination';
-import type { TerminalTurnState } from '../schemas/turn';
+import type { TerminalTurnState, TurnInboundEventItem } from '../schemas/turn';
import { assertCreateTurnThreadDelta } from './assertCreateTurnThreadDelta';
import type {
AddThreadsInput,
@@ -18,6 +18,7 @@ import type {
GetSessionByExternalIdInput,
GetSessionInput,
GetTurnInput,
+ InsertTurnInboundEventsInput,
ISessionStore,
ListSessionEventsInput,
ListSessionsInput,
@@ -48,6 +49,7 @@ import {
SessionNotFoundError,
SessionStoreInvariantError,
TurnAlreadyExistsError,
+ TurnEventAlreadyExistsError,
TurnNotFoundError,
TurnNotRunningError,
} from './SessionStoreErrors';
@@ -56,6 +58,14 @@ import {
type StoredEvent = PersistedTurnEvent;
+interface StoredInboundEvent {
+ event_id: string;
+ turn_id: string;
+ payload: TurnInboundEventItem;
+ created_at: string;
+ consumed: boolean;
+}
+
interface StoredSession<TSessionCustom extends object> {
record: SessionRecord<TSessionCustom>;
turnIds: string[];
@@ -170,6 +180,8 @@ export class InMemorySessionStore<
private readonly sessions = new Map<string, StoredSession<TSessionCustom>>();
private readonly turns = new Map<string, TurnRecord<TTurnCustom>>();
private readonly events = new Map<string, StoredEvent[]>();
+ /** session_id → inbound send-event inbox */
+ private readonly inboundEvents = new Map<string, StoredInboundEvent[]>();
async createSession(input: CreateSessionInput<TSessionCustom>): Promise<void> {
const key = sessionKey(input.session_id);
@@ -218,6 +230,7 @@ export class InMemorySessionStore<
const tKey = turnKey({ session_id: input.session_id, turn_id: turnId });
this.turns.delete(tKey);
this.events.delete(tKey);
+ this.inboundEvents.delete(tKey);
}
this.sessions.delete(sKey);
}
@@ -485,6 +498,40 @@ export class InMemorySessionStore<
return;
}
+ async insertTurnInboundEvents(input: InsertTurnInboundEventsInput): Promise<void> {
+ if (input.events.length === 0) {
+ return;
+ }
+ this.requireSession(input.session_id);
+ this.requireRunningTurn(input.session_id, input.turn_id);
+ const tKey = turnKey(input);
+ let list = this.inboundEvents.get(tKey);
+ if (!list) {
+ list = [];
+ this.inboundEvents.set(tKey, list);
+ }
+ const existing = new Set(list.map(row => row.event_id));
+ for (const event of input.events) {
+ if (existing.has(event.event_id)) {
+ throw new TurnEventAlreadyExistsError({
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: event.event_id,
+ });
+ }
+ existing.add(event.event_id);
+ }
+ for (const event of input.events) {
+ list.push({
+ event_id: event.event_id,
+ turn_id: input.turn_id,
+ payload: deepCopy(event.payload),
+ created_at: event.created_at,
+ consumed: false,
+ });
+ }
+ }
+
/** Cost from turn metrics when present; duration is completed_at − created_at, floored at 0. */
private addTerminalSessionMetrics(sessionId: string, created_at: Date, state: TerminalTurnState): void {
const stored = this.sessions.get(sessionKey(sessionId));
@@ -499,6 +546,14 @@ export class InMemorySessionStore<
stored.record.metrics.total_duration_ms += elapsed_ms > 0 ? Math.trunc(elapsed_ms) : 0;
}
+ private requireSession(sessionId: string): StoredSession<TSessionCustom> {
+ const stored = this.sessions.get(sessionKey(sessionId));
+ if (!stored) {
+ throw new SessionNotFoundError(sessionId);
+ }
+ return stored;
+ }
+
private requireTurn(sessionId: string, turnId: string): TurnRecord<TTurnCustom> {
const turn = this.turns.get(turnKey({ session_id: sessionId, turn_id: turnId }));
if (!turn) {
diff --git a/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts b/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts
index 89b31ee90..3d6b8d3cb 100644
--- a/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts
+++ b/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts
@@ -74,6 +74,20 @@ export class TurnAlreadyExistsError extends SessionStoreConflictError {
}
}
+export class TurnEventAlreadyExistsError extends SessionStoreConflictError {
+ readonly session_id: string;
+ readonly turn_id: string;
+ readonly event_id: string;
+
+ constructor(input: { session_id: string; turn_id: string; event_id: string }, options?: ErrorOptions) {
+ super(`Turn event already exists: ${input.session_id}/${input.turn_id}/${input.event_id}`, options);
+ this.name = 'TurnEventAlreadyExistsError';
+ this.session_id = input.session_id;
+ this.turn_id = input.turn_id;
+ this.event_id = input.event_id;
+ }
+}
+
export class PreviousTurnRunningError extends SessionStoreConflictError {
readonly previous_turn_id: string;
diff --git a/packages/trueforge-core/src/core/events/schema.ts b/packages/trueforge-core/src/core/events/schema.ts
index bdced8eda..84b424c10 100644
--- a/packages/trueforge-core/src/core/events/schema.ts
+++ b/packages/trueforge-core/src/core/events/schema.ts
@@ -85,7 +85,7 @@ export const UserToolApprovalMessageSchema = z
tool_call_id: z.string().min(1, 'tool_call_id is required').describe('Tool call id being approved or denied.'),
approval: ApprovalDecisionSchema,
})
- .openapi('UserToolApprovalEvent');
+ .openapi('UserToolApprovalInputEvent');
export const UserToolResponseMessageSchema = z
.object({
@@ -94,7 +94,7 @@ export const UserToolResponseMessageSchema = z
tool_call_id: z.string().min(1, 'tool_call_id is required').describe('Tool call id receiving the client response.'),
content: z.string().min(1, 'content cannot be empty').describe('Client-side tool result content.'),
})
- .openapi('UserToolResponseEvent');
+ .openapi('UserToolResponseInputEvent');
export const TextContentPartSchema = z
.object({
diff --git a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
index 28a85e43f..36a8f0eba 100644
--- a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
+++ b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
@@ -687,6 +687,24 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
order: undefined,
}),
).rejects.toBeInstanceOf(TurnNotFoundError);
+ await expect(
+ store.insertTurnInboundEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [
+ {
+ event_id: newEventId(),
+ payload: {
+ type: 'user.tool_approval',
+ thread_id: 'main',
+ tool_call_id: 'tc-1',
+ approval: { status: 'allow' },
+ },
+ created_at: new Date().toISOString(),
+ },
+ ],
+ }),
+ ).rejects.toBeInstanceOf(SessionNotFoundError);
await expect(
store.listSessionEvents({
session_id: sessionId,
@@ -2208,6 +2226,206 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
expect(data.map(e => e.id)).toEqual([created.id, model.id]);
});
+ it('turn_inbound_events: insert, duplicate id, terminal tip rejects', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+
+ const earlier = {
+ event_id: 'evt-a',
+ payload: {
+ type: 'user.tool_approval' as const,
+ thread_id: 'main',
+ tool_call_id: 'tc-1',
+ approval: { status: 'allow' as const },
+ },
+ created_at: new Date().toISOString(),
+ };
+ const later = {
+ event_id: 'evt-b',
+ payload: {
+ type: 'user.tool_approval' as const,
+ thread_id: 'main',
+ tool_call_id: 'tc-2',
+ approval: { status: 'deny' as const, reason: 'nope' },
+ },
+ created_at: new Date().toISOString(),
+ };
+
+ await store.insertTurnInboundEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [later, earlier],
+ });
+
+ await expect(
+ store.insertTurnInboundEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [later],
+ }),
+ ).rejects.toMatchObject({
+ name: 'TurnEventAlreadyExistsError',
+ event_id: later.event_id,
+ });
+
+ // Later id in the batch collides — error must name that id.
+ const fresh = {
+ event_id: 'evt-fresh',
+ payload: {
+ type: 'user.tool_approval' as const,
+ thread_id: 'main',
+ tool_call_id: 'tc-fresh',
+ approval: { status: 'allow' as const },
+ },
+ created_at: new Date().toISOString(),
+ };
+ await expect(
+ store.insertTurnInboundEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [fresh, later],
+ }),
+ ).rejects.toMatchObject({
+ name: 'TurnEventAlreadyExistsError',
+ event_id: later.event_id,
+ });
+
+ const dupId = 'evt-dup';
+ await expect(
+ store.insertTurnInboundEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [
+ {
+ event_id: dupId,
+ payload: {
+ type: 'user.tool_approval' as const,
+ thread_id: 'main',
+ tool_call_id: 'tc-dup',
+ approval: { status: 'allow' as const },
+ },
+ created_at: new Date().toISOString(),
+ },
+ {
+ event_id: dupId,
+ payload: {
+ type: 'user.tool_approval' as const,
+ thread_id: 'main',
+ tool_call_id: 'tc-dup-2',
+ approval: { status: 'deny' as const, reason: 'dup' },
+ },
+ created_at: new Date().toISOString(),
+ },
+ ],
+ }),
+ ).rejects.toMatchObject({
+ name: 'TurnEventAlreadyExistsError',
+ event_id: dupId,
+ });
+
+ // Terminal tip rejects inbox writes.
+ await finishTurn(store, 'turn-1');
+ await expect(
+ store.insertTurnInboundEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [
+ {
+ event_id: 'evt-after-done',
+ payload: {
+ type: 'user.tool_response' as const,
+ thread_id: 'main',
+ tool_call_id: 'tc-3',
+ content: 'client result',
+ },
+ created_at: new Date().toISOString(),
+ },
+ ],
+ }),
+ ).rejects.toBeInstanceOf(TurnNotRunningError);
+ });
+
+ it('concurrent freeze x insertTurnInboundEvents: terminal tip rejects or insert wins cleanly', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const cancelledState = makeCancelledTurnState(CancellationReason.CancelledForNextTurn);
+ const inbound = {
+ event_id: 'evt-race',
+ payload: {
+ type: 'user.tool_approval' as const,
+ thread_id: 'main',
+ tool_call_id: 'tc-race',
+ approval: { status: 'allow' as const },
+ },
+ created_at: new Date().toISOString(),
+ };
+
+ const results = await Promise.allSettled([
+ store.freezeAndGetTurn({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ reason: CancellationReason.CancelledForNextTurn,
+ turn_done_event: makeTurnDoneEvent(cancelledState),
+ }),
+ store.insertTurnInboundEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [inbound],
+ }),
+ ]);
+
+ const insertResult = results[1];
+ if (insertResult.status === 'rejected') {
+ expect(insertResult.reason).toBeInstanceOf(TurnNotRunningError);
+ }
+
+ const turn = await store.getTurn({ session_id: sessionId, turn_id: 'turn-1' });
+ expect(mustGet(turn).state.status).toBe('cancelled');
+ });
+
+ it('turn_inbound_events cascade away with deleteSession', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ await store.insertTurnInboundEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [
+ {
+ event_id: newEventId(),
+ payload: {
+ type: 'user.tool_approval',
+ thread_id: 'main',
+ tool_call_id: 'tc-x',
+ approval: { status: 'allow' },
+ },
+ created_at: new Date().toISOString(),
+ },
+ ],
+ });
+ await store.deleteSession({ tenant_id: tenant, session_id: sessionId });
+ await expect(
+ store.insertTurnInboundEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [
+ {
+ event_id: newEventId(),
+ payload: {
+ type: 'user.tool_approval',
+ thread_id: 'main',
+ tool_call_id: 'tc-after-delete',
+ approval: { status: 'allow' },
+ },
+ created_at: new Date().toISOString(),
+ },
+ ],
+ }),
+ ).rejects.toBeInstanceOf(SessionNotFoundError);
+ });
+
it('add/remove threads and append/overwrite context', async () => {
const store = createStore();
await seedSession(store);
diff --git a/packages/trueforge-sdk/src/api/types/TurnInputItem.ts b/packages/trueforge-sdk/src/api/types/TurnInputItem.ts
index 24c1cb953..6be50ea32 100644
--- a/packages/trueforge-sdk/src/api/types/TurnInputItem.ts
+++ b/packages/trueforge-sdk/src/api/types/TurnInputItem.ts
@@ -2,4 +2,7 @@
import type * as TrueForge from "../index.js";
-export type TurnInputItem = TrueForge.UserMessage | TrueForge.UserToolApprovalEvent | TrueForge.UserToolResponseEvent;
+export type TurnInputItem =
+ | TrueForge.UserMessage
+ | TrueForge.UserToolApprovalInputEvent
+ | TrueForge.UserToolResponseInputEvent;
diff --git a/packages/trueforge-sdk/src/api/types/UserToolApprovalEvent.ts b/packages/trueforge-sdk/src/api/types/UserToolApprovalInputEvent.ts
similarity index 87%
rename from packages/trueforge-sdk/src/api/types/UserToolApprovalEvent.ts
rename to packages/trueforge-sdk/src/api/types/UserToolApprovalInputEvent.ts
index 432dde181..96d2d9dd4 100644
--- a/packages/trueforge-sdk/src/api/types/UserToolApprovalEvent.ts
+++ b/packages/trueforge-sdk/src/api/types/UserToolApprovalInputEvent.ts
@@ -2,7 +2,7 @@
import type * as TrueForge from "../index.js";
-export interface UserToolApprovalEvent {
+export interface UserToolApprovalInputEvent {
approval: TrueForge.ApprovalDecision;
/** Thread that owns the pending tool call. */
threadId: string;
diff --git a/packages/trueforge-sdk/src/api/types/UserToolResponseEvent.ts b/packages/trueforge-sdk/src/api/types/UserToolResponseInputEvent.ts
similarity index 87%
rename from packages/trueforge-sdk/src/api/types/UserToolResponseEvent.ts
rename to packages/trueforge-sdk/src/api/types/UserToolResponseInputEvent.ts
index d86330196..246396e03 100644
--- a/packages/trueforge-sdk/src/api/types/UserToolResponseEvent.ts
+++ b/packages/trueforge-sdk/src/api/types/UserToolResponseInputEvent.ts
@@ -1,6 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
-export interface UserToolResponseEvent {
+export interface UserToolResponseInputEvent {
/** Client-side tool result content. */
content: string;
/** Thread that owns the pending tool call. */
diff --git a/packages/trueforge-sdk/src/api/types/index.ts b/packages/trueforge-sdk/src/api/types/index.ts
index 3c8a2dcf3..fcd37521a 100644
--- a/packages/trueforge-sdk/src/api/types/index.ts
+++ b/packages/trueforge-sdk/src/api/types/index.ts
@@ -235,8 +235,8 @@ export * from "./TurnUpdateStateRunning.js";
export * from "./UserMessage.js";
export * from "./UserMessageContent.js";
export * from "./UserMessageContentItem.js";
-export * from "./UserToolApprovalEvent.js";
-export * from "./UserToolResponseEvent.js";
+export * from "./UserToolApprovalInputEvent.js";
+export * from "./UserToolResponseInputEvent.js";
export * from "./WebSearchCapability.js";
export * from "./WebSearchConfig.js";
export * from "./WebSearchProviderManifest.js";
diff --git a/packages/trueforge-sdk/src/serialization/types/TurnInputItem.ts b/packages/trueforge-sdk/src/serialization/types/TurnInputItem.ts
index 36becb445..170430784 100644
--- a/packages/trueforge-sdk/src/serialization/types/TurnInputItem.ts
+++ b/packages/trueforge-sdk/src/serialization/types/TurnInputItem.ts
@@ -4,12 +4,12 @@ import type * as TrueForge from "../../api/index.js";
import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
import { UserMessage } from "./UserMessage.js";
-import { UserToolApprovalEvent } from "./UserToolApprovalEvent.js";
-import { UserToolResponseEvent } from "./UserToolResponseEvent.js";
+import { UserToolApprovalInputEvent } from "./UserToolApprovalInputEvent.js";
+import { UserToolResponseInputEvent } from "./UserToolResponseInputEvent.js";
export const TurnInputItem: core.serialization.Schema<serializers.TurnInputItem.Raw, TrueForge.TurnInputItem> =
- core.serialization.undiscriminatedUnion([UserMessage, UserToolApprovalEvent, UserToolResponseEvent]);
+ core.serialization.undiscriminatedUnion([UserMessage, UserToolApprovalInputEvent, UserToolResponseInputEvent]);
export declare namespace TurnInputItem {
- export type Raw = UserMessage.Raw | UserToolApprovalEvent.Raw | UserToolResponseEvent.Raw;
+ export type Raw = UserMessage.Raw | UserToolApprovalInputEvent.Raw | UserToolResponseInputEvent.Raw;
}
diff --git a/packages/trueforge-sdk/src/serialization/types/UserToolApprovalEvent.ts b/packages/trueforge-sdk/src/serialization/types/UserToolApprovalInputEvent.ts
similarity index 77%
rename from packages/trueforge-sdk/src/serialization/types/UserToolApprovalEvent.ts
rename to packages/trueforge-sdk/src/serialization/types/UserToolApprovalInputEvent.ts
index 18f86bbbf..7def0f702 100644
--- a/packages/trueforge-sdk/src/serialization/types/UserToolApprovalEvent.ts
+++ b/packages/trueforge-sdk/src/serialization/types/UserToolApprovalInputEvent.ts
@@ -5,9 +5,9 @@ import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
import { ApprovalDecision } from "./ApprovalDecision.js";
-export const UserToolApprovalEvent: core.serialization.ObjectSchema<
- serializers.UserToolApprovalEvent.Raw,
- TrueForge.UserToolApprovalEvent
+export const UserToolApprovalInputEvent: core.serialization.ObjectSchema<
+ serializers.UserToolApprovalInputEvent.Raw,
+ TrueForge.UserToolApprovalInputEvent
> = core.serialization.object({
approval: ApprovalDecision,
threadId: core.serialization.property("thread_id", core.serialization.string()),
@@ -15,7 +15,7 @@ export const UserToolApprovalEvent: core.serialization.ObjectSchema<
type: core.serialization.stringLiteral("user.tool_approval"),
});
-export declare namespace UserToolApprovalEvent {
+export declare namespace UserToolApprovalInputEvent {
export interface Raw {
approval: ApprovalDecision.Raw;
thread_id: string;
diff --git a/packages/trueforge-sdk/src/serialization/types/UserToolResponseEvent.ts b/packages/trueforge-sdk/src/serialization/types/UserToolResponseInputEvent.ts
similarity index 76%
rename from packages/trueforge-sdk/src/serialization/types/UserToolResponseEvent.ts
rename to packages/trueforge-sdk/src/serialization/types/UserToolResponseInputEvent.ts
index 8a878654a..9b2ebcb6e 100644
--- a/packages/trueforge-sdk/src/serialization/types/UserToolResponseEvent.ts
+++ b/packages/trueforge-sdk/src/serialization/types/UserToolResponseInputEvent.ts
@@ -4,9 +4,9 @@ import type * as TrueForge from "../../api/index.js";
import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
-export const UserToolResponseEvent: core.serialization.ObjectSchema<
- serializers.UserToolResponseEvent.Raw,
- TrueForge.UserToolResponseEvent
+export const UserToolResponseInputEvent: core.serialization.ObjectSchema<
+ serializers.UserToolResponseInputEvent.Raw,
+ TrueForge.UserToolResponseInputEvent
> = core.serialization.object({
content: core.serialization.string(),
threadId: core.serialization.property("thread_id", core.serialization.string()),
@@ -14,7 +14,7 @@ export const UserToolResponseEvent: core.serialization.ObjectSchema<
type: core.serialization.stringLiteral("user.tool_response"),
});
-export declare namespace UserToolResponseEvent {
+export declare namespace UserToolResponseInputEvent {
export interface Raw {
content: string;
thread_id: string;
diff --git a/packages/trueforge-sdk/src/serialization/types/index.ts b/packages/trueforge-sdk/src/serialization/types/index.ts
index 3c8a2dcf3..fcd37521a 100644
--- a/packages/trueforge-sdk/src/serialization/types/index.ts
+++ b/packages/trueforge-sdk/src/serialization/types/index.ts
@@ -235,8 +235,8 @@ export * from "./TurnUpdateStateRunning.js";
export * from "./UserMessage.js";
export * from "./UserMessageContent.js";
export * from "./UserMessageContentItem.js";
-export * from "./UserToolApprovalEvent.js";
-export * from "./UserToolResponseEvent.js";
+export * from "./UserToolApprovalInputEvent.js";
+export * from "./UserToolResponseInputEvent.js";
export * from "./WebSearchCapability.js";
export * from "./WebSearchConfig.js";
export * from "./WebSearchProviderManifest.js";
diff --git a/packages/trueforge/src/db/postgres/migrations/20260924_000001_turn_inbound_events.ts b/packages/trueforge/src/db/postgres/migrations/20260924_000001_turn_inbound_events.ts
new file mode 100644
index 000000000..54af1de25
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20260924_000001_turn_inbound_events.ts
@@ -0,0 +1,37 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Turn-scoped inbound send-event inbox (tip HITL / policies).
+ * `turn_id` is required — every row belongs to a tip.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+
+ await db.schema
+ .createTable('turn_inbound_events')
+ .addColumn('session_id', 'text', col => col.notNull())
+ .addColumn('turn_id', 'text', col => col.notNull())
+ .addColumn('event_id', 'text', col => col.notNull())
+ .addColumn('payload', 'jsonb', col => col.notNull())
+ .addColumn('consumed', 'boolean', col => col.notNull().defaultTo(false))
+ .addColumn('created_at', 'timestamptz', col => col.notNull())
+ .addPrimaryKeyConstraint('turn_inbound_events_pkey', ['session_id', 'turn_id', 'event_id'])
+ .execute();
+
+ await db.schema
+ .alterTable('turn_inbound_events')
+ .addForeignKeyConstraint('turn_inbound_events_session_fkey', ['session_id'], 'session', ['session_id'])
+ .onDelete('cascade')
+ .execute();
+
+ await sql`
+ CREATE INDEX turn_inbound_events_unconsumed_idx
+ ON turn_inbound_events (session_id, turn_id, event_id)
+ WHERE consumed = false
+ `.execute(db);
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await db.schema.dropTable('turn_inbound_events').ifExists().cascade().execute();
+}
diff --git a/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts b/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts
index 76b6ce66b..fff1f5ca6 100644
--- a/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts
+++ b/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts
@@ -21,6 +21,7 @@ import type {
GetSessionByExternalIdInput,
GetSessionInput,
GetTurnInput,
+ InsertTurnInboundEventsInput,
ISessionStore,
ListSessionEventsInput,
ListSessionsInput,
@@ -52,6 +53,7 @@ import {
listSessionEvents as listSessionEventsQuery,
listTurnEvents as listTurnEventsQuery,
} from './queries/events';
+import { insertTurnInboundEvents as insertTurnInboundEventsQuery } from './queries/inboundEvents';
import {
createSession as createSessionQuery,
deleteSession as deleteSessionQuery,
@@ -216,6 +218,10 @@ export class PostgresSessionStore implements ISessionStore<SessionCustom, TurnCu
return appendToEventsQuery(this.db, input);
}
+ insertTurnInboundEvents(input: InsertTurnInboundEventsInput): Promise<void> {
+ return insertTurnInboundEventsQuery(this.db, input);
+ }
+
addThreads(input: AddThreadsInput): Promise<void> {
return addThreadsQuery(this.db, input);
}
diff --git a/packages/trueforge/src/db/postgres/session-store/queries/inboundEvents.ts b/packages/trueforge/src/db/postgres/session-store/queries/inboundEvents.ts
new file mode 100644
index 000000000..058e7c93e
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/session-store/queries/inboundEvents.ts
@@ -0,0 +1,100 @@
+import type { InsertTurnInboundEventsInput } from '@truefoundry/trueforge-core/agent-session/store/ISessionStore';
+import {
+ SessionNotFoundError,
+ TurnEventAlreadyExistsError,
+} from '@truefoundry/trueforge-core/agent-session/store/SessionStoreErrors';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import { firstCollidingEventId, firstDuplicateEventIdInBatch } from '../../../turnInboundEvents';
+import { isUniqueViolation } from '../../client';
+import { json } from '../../sqlExpressions';
+import type { Database } from '../../types';
+import { assertTurnRunning, type TurnKeys } from './turns';
+
+async function requireSession(db: Kysely<Database>, sessionId: string): Promise<void> {
+ const row = await db
+ .selectFrom('session')
+ .select('session_id')
+ .where('session_id', '=', sessionId)
+ .executeTakeFirst();
+ if (!row) {
+ throw new SessionNotFoundError(sessionId);
+ }
+}
+
+async function resolveCollidingEventId(
+ db: Kysely<Database>,
+ sessionId: string,
+ turnId: string,
+ events: InsertTurnInboundEventsInput['events'],
+): Promise<string> {
+ const ids = [...new Set(events.map(e => e.event_id))];
+ if (ids.length === 0) {
+ return '';
+ }
+ const rows = await db
+ .selectFrom('turn_inbound_events')
+ .select('event_id')
+ .where('session_id', '=', sessionId)
+ .where('turn_id', '=', turnId)
+ .where('event_id', 'in', ids)
+ .execute();
+ return firstCollidingEventId(events, new Set(rows.map(r => r.event_id)));
+}
+
+export async function insertTurnInboundEvents(
+ db: Kysely<Database>,
+ input: InsertTurnInboundEventsInput,
+): Promise<void> {
+ if (input.events.length === 0) {
+ return;
+ }
+ await requireSession(db, input.session_id);
+
+ const duplicateInBatch = firstDuplicateEventIdInBatch(input.events);
+ if (duplicateInBatch !== undefined) {
+ throw new TurnEventAlreadyExistsError({
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: duplicateInBatch,
+ });
+ }
+
+ const keys: TurnKeys = {
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ };
+
+ try {
+ // Ensure the turn does not stop before we insert events.
+ await db.transaction().execute(async trx => {
+ await assertTurnRunning(trx, keys);
+ await trx
+ .insertInto('turn_inbound_events')
+ .values(
+ input.events.map(event => ({
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: event.event_id,
+ payload: json(event.payload),
+ consumed: false,
+ created_at: sql<Date>`${event.created_at}::timestamptz`,
+ })),
+ )
+ .execute();
+ });
+ } catch (error) {
+ if (isUniqueViolation(error)) {
+ const eventId = await resolveCollidingEventId(db, input.session_id, input.turn_id, input.events);
+ throw new TurnEventAlreadyExistsError(
+ {
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: eventId,
+ },
+ { cause: error },
+ );
+ }
+ throw error;
+ }
+}
diff --git a/packages/trueforge/src/db/postgres/types.ts b/packages/trueforge/src/db/postgres/types.ts
index e9afee3fe..b188b353f 100644
--- a/packages/trueforge/src/db/postgres/types.ts
+++ b/packages/trueforge/src/db/postgres/types.ts
@@ -9,6 +9,7 @@ import type {
SessionMetadata,
SessionMetrics,
SessionSource,
+ TurnInboundEventItem,
TurnInputItem,
TurnState,
} from '@truefoundry/trueforge-core/agent-session';
@@ -250,6 +251,19 @@ export interface SessionEventTable {
created_at: Date;
}
+/**
+ * Turn-scoped inbound send-event inbox.
+ * PRIMARY KEY (session_id, turn_id, event_id).
+ */
+export interface TurnInboundEventsTable {
+ session_id: string;
+ turn_id: string;
+ event_id: string;
+ payload: JSONColumnType<TurnInboundEventItem, TurnInboundEventItem, TurnInboundEventItem>;
+ consumed: boolean;
+ created_at: Date;
+}
+
/**
* pure immutable CONTENT; no state → no checkpoint field
* PRIMARY KEY (session_id, thread_id, append_id)
@@ -532,6 +546,7 @@ export interface Database {
turn: TurnTable;
turn_thread: TurnThreadTable;
session_event: SessionEventTable;
+ turn_inbound_events: TurnInboundEventsTable;
thread_context_log: ThreadContextLogTable;
thread_capability_state: ThreadCapabilityStateTable;
model_provider: ModelProviderTable;
diff --git a/packages/trueforge/src/db/sqlite/client.ts b/packages/trueforge/src/db/sqlite/client.ts
index 8c29149aa..ce6dc9407 100644
--- a/packages/trueforge/src/db/sqlite/client.ts
+++ b/packages/trueforge/src/db/sqlite/client.ts
@@ -141,6 +141,7 @@ const JSON_RESULT_COLUMNS = new Set([
'turn_state',
'thread_checkpoint',
'event',
+ 'payload',
'manifest',
'metadata',
'build_metadata',
diff --git a/packages/trueforge/src/db/sqlite/migrations/20260924_000001_turn_inbound_events.ts b/packages/trueforge/src/db/sqlite/migrations/20260924_000001_turn_inbound_events.ts
new file mode 100644
index 000000000..4ccd16009
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20260924_000001_turn_inbound_events.ts
@@ -0,0 +1,35 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * Turn-scoped inbound send-event inbox (tip HITL / policies).
+ * `turn_id` is required — every row belongs to a tip.
+ * Kysely does not wrap SQLite migrations — keep CREATE TABLE + INDEX atomic.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`
+ CREATE TABLE turn_inbound_events (
+ session_id TEXT NOT NULL REFERENCES session(session_id) ON DELETE CASCADE,
+ turn_id TEXT NOT NULL,
+ event_id TEXT NOT NULL,
+ payload BLOB NOT NULL,
+ consumed INTEGER NOT NULL DEFAULT 0,
+ created_at TEXT NOT NULL,
+ PRIMARY KEY (session_id, turn_id, event_id)
+ ) STRICT
+ `.execute(trx);
+
+ await sql`
+ CREATE INDEX turn_inbound_events_unconsumed_idx
+ ON turn_inbound_events (session_id, turn_id, event_id)
+ WHERE consumed = 0
+ `.execute(trx);
+ });
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`DROP INDEX IF EXISTS turn_inbound_events_unconsumed_idx`.execute(trx);
+ await sql`DROP TABLE IF EXISTS turn_inbound_events`.execute(trx);
+ });
+}
diff --git a/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts b/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts
index f0c597a68..57b4fe3b5 100644
--- a/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts
+++ b/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts
@@ -14,6 +14,7 @@ import type {
GetSessionByExternalIdInput,
GetSessionInput,
GetTurnInput,
+ InsertTurnInboundEventsInput,
ISessionStore,
ListSessionEventsInput,
ListSessionsInput,
@@ -40,6 +41,7 @@ import {
listSessionEvents as listSessionEventsQuery,
listTurnEvents as listTurnEventsQuery,
} from './queries/events';
+import { insertTurnInboundEvents as insertTurnInboundEventsQuery } from './queries/inboundEvents';
import {
createSession as createSessionQuery,
deleteSession as deleteSessionQuery,
@@ -191,6 +193,10 @@ export class SqliteSessionStore implements ISessionStore<SessionCustom, TurnCust
return appendToEventsQuery(this.db, input);
}
+ insertTurnInboundEvents(input: InsertTurnInboundEventsInput): Promise<void> {
+ return insertTurnInboundEventsQuery(this.db, input);
+ }
+
addThreads(input: AddThreadsInput): Promise<void> {
return addThreadsQuery(this.db, input);
}
diff --git a/packages/trueforge/src/db/sqlite/session-store/queries/inboundEvents.ts b/packages/trueforge/src/db/sqlite/session-store/queries/inboundEvents.ts
new file mode 100644
index 000000000..737468401
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/session-store/queries/inboundEvents.ts
@@ -0,0 +1,99 @@
+import type { InsertTurnInboundEventsInput } from '@truefoundry/trueforge-core/agent-session/store/ISessionStore';
+import {
+ SessionNotFoundError,
+ TurnEventAlreadyExistsError,
+} from '@truefoundry/trueforge-core/agent-session/store/SessionStoreErrors';
+import type { Kysely } from 'kysely';
+import { firstCollidingEventId, firstDuplicateEventIdInBatch } from '../../../turnInboundEvents';
+import { isUniqueViolation } from '../../client';
+import { jsonbBind } from '../../sqlExpressions';
+import type { Database } from '../../types';
+import { assertTurnRunning, type TurnKeys } from './turns';
+
+async function requireSession(db: Kysely<Database>, sessionId: string): Promise<void> {
+ const row = await db
+ .selectFrom('session')
+ .select('session_id')
+ .where('session_id', '=', sessionId)
+ .executeTakeFirst();
+ if (!row) {
+ throw new SessionNotFoundError(sessionId);
+ }
+}
+
+async function resolveCollidingEventId(
+ db: Kysely<Database>,
+ sessionId: string,
+ turnId: string,
+ events: InsertTurnInboundEventsInput['events'],
+): Promise<string> {
+ const ids = [...new Set(events.map(e => e.event_id))];
+ if (ids.length === 0) {
+ return '';
+ }
+ const rows = await db
+ .selectFrom('turn_inbound_events')
+ .select('event_id')
+ .where('session_id', '=', sessionId)
+ .where('turn_id', '=', turnId)
+ .where('event_id', 'in', ids)
+ .execute();
+ return firstCollidingEventId(events, new Set(rows.map(r => r.event_id)));
+}
+
+export async function insertTurnInboundEvents(
+ db: Kysely<Database>,
+ input: InsertTurnInboundEventsInput,
+): Promise<void> {
+ if (input.events.length === 0) {
+ return;
+ }
+ await requireSession(db, input.session_id);
+
+ const duplicateInBatch = firstDuplicateEventIdInBatch(input.events);
+ if (duplicateInBatch !== undefined) {
+ throw new TurnEventAlreadyExistsError({
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: duplicateInBatch,
+ });
+ }
+
+ const keys: TurnKeys = {
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ };
+
+ try {
+ // Ensure the turn does not stop before we insert events.
+ await db.transaction().execute(async trx => {
+ await assertTurnRunning(trx, keys);
+ await trx
+ .insertInto('turn_inbound_events')
+ .values(
+ input.events.map(event => ({
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: event.event_id,
+ payload: jsonbBind(event.payload),
+ consumed: 0,
+ created_at: event.created_at,
+ })),
+ )
+ .execute();
+ });
+ } catch (error) {
+ if (isUniqueViolation(error)) {
+ const eventId = await resolveCollidingEventId(db, input.session_id, input.turn_id, input.events);
+ throw new TurnEventAlreadyExistsError(
+ {
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: eventId,
+ },
+ { cause: error },
+ );
+ }
+ throw error;
+ }
+}
diff --git a/packages/trueforge/src/db/sqlite/types.ts b/packages/trueforge/src/db/sqlite/types.ts
index de10ff0be..2ed2bc59c 100644
--- a/packages/trueforge/src/db/sqlite/types.ts
+++ b/packages/trueforge/src/db/sqlite/types.ts
@@ -12,6 +12,7 @@ import type {
SessionMetadata,
SessionMetrics,
SessionSource,
+ TurnInboundEventItem,
TurnInputItem,
TurnState,
} from '@truefoundry/trueforge-core/agent-session';
@@ -148,6 +149,20 @@ export interface SessionEventTable {
created_at: string;
}
+/**
+ * Turn-scoped inbound send-event inbox.
+ * PRIMARY KEY (session_id, turn_id, event_id).
+ * `consumed` is INTEGER 0/1 (STRICT has no boolean).
+ */
+export interface TurnInboundEventsTable {
+ session_id: string;
+ turn_id: string;
+ event_id: string;
+ payload: JsonbColumn<TurnInboundEventItem>;
+ consumed: number;
+ created_at: string;
+}
+
/**
* Pure immutable content; no state → no checkpoint field.
* PRIMARY KEY (append_id) AUTOINCREMENT
@@ -352,6 +367,7 @@ export interface Database {
turn_thread: TurnThreadTable;
turn_thread_context: TurnThreadContextTable;
session_event: SessionEventTable;
+ turn_inbound_events: TurnInboundEventsTable;
thread_context_log: ThreadContextLogTable;
thread_capability_state: ThreadCapabilityStateTable;
model_provider: ModelProviderTable;
diff --git a/packages/trueforge/src/db/turnInboundEvents.ts b/packages/trueforge/src/db/turnInboundEvents.ts
new file mode 100644
index 000000000..ac21c3fad
--- /dev/null
+++ b/packages/trueforge/src/db/turnInboundEvents.ts
@@ -0,0 +1,28 @@
+import type { InsertTurnInboundEventsInput } from '@truefoundry/trueforge-core/agent-session/store/ISessionStore';
+
+type InboundInsertEvent = InsertTurnInboundEventsInput['events'][number];
+
+/** First repeated `event_id` in the batch (input order), if any. */
+export function firstDuplicateEventIdInBatch(
+ events: readonly Pick<InboundInsertEvent, 'event_id'>[],
+): string | undefined {
+ const seen = new Set<string>();
+ for (const event of events) {
+ if (seen.has(event.event_id)) {
+ return event.event_id;
+ }
+ seen.add(event.event_id);
+ }
+ return undefined;
+}
+
+/**
+ * After a unique/PK violation, pick the colliding id: first input `event_id`
+ * that already exists.
+ */
+export function firstCollidingEventId(
+ events: readonly Pick<InboundInsertEvent, 'event_id'>[],
+ existingEventIds: ReadonlySet<string>,
+): string {
+ return events.find(e => existingEventIds.has(e.event_id))?.event_id ?? events[0]?.event_id ?? '';
+}
diff --git a/python/trueforge_sdk/src/trueforge_sdk/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
index 9b49e63fa..36414e450 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
@@ -244,8 +244,8 @@ if typing.TYPE_CHECKING:
UserMessage,
UserMessageContent,
UserMessageContentItem,
- UserToolApprovalEvent,
- UserToolResponseEvent,
+ UserToolApprovalInputEvent,
+ UserToolResponseInputEvent,
WebSearchCapability,
WebSearchConfig,
WebSearchProviderManifest,
@@ -523,8 +523,8 @@ _dynamic_imports: typing.Dict[str, str] = {
"UserMessage": ".types",
"UserMessageContent": ".types",
"UserMessageContentItem": ".types",
- "UserToolApprovalEvent": ".types",
- "UserToolResponseEvent": ".types",
+ "UserToolApprovalInputEvent": ".types",
+ "UserToolResponseInputEvent": ".types",
"WebSearchCapability": ".types",
"WebSearchConfig": ".types",
"WebSearchProviderManifest": ".types",
@@ -819,8 +819,8 @@ __all__ = [
"UserMessage",
"UserMessageContent",
"UserMessageContentItem",
- "UserToolApprovalEvent",
- "UserToolResponseEvent",
+ "UserToolApprovalInputEvent",
+ "UserToolResponseInputEvent",
"WebSearchCapability",
"WebSearchConfig",
"WebSearchProviderManifest",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
index 07d9b1918..e07f381e8 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
@@ -243,8 +243,8 @@ if typing.TYPE_CHECKING:
from .user_message import UserMessage
from .user_message_content import UserMessageContent
from .user_message_content_item import UserMessageContentItem
- from .user_tool_approval_event import UserToolApprovalEvent
- from .user_tool_response_event import UserToolResponseEvent
+ from .user_tool_approval_input_event import UserToolApprovalInputEvent
+ from .user_tool_response_input_event import UserToolResponseInputEvent
from .web_search_capability import WebSearchCapability
from .web_search_config import WebSearchConfig
from .web_search_provider_manifest import WebSearchProviderManifest
@@ -487,8 +487,8 @@ _dynamic_imports: typing.Dict[str, str] = {
"UserMessage": ".user_message",
"UserMessageContent": ".user_message_content",
"UserMessageContentItem": ".user_message_content_item",
- "UserToolApprovalEvent": ".user_tool_approval_event",
- "UserToolResponseEvent": ".user_tool_response_event",
+ "UserToolApprovalInputEvent": ".user_tool_approval_input_event",
+ "UserToolResponseInputEvent": ".user_tool_response_input_event",
"WebSearchCapability": ".web_search_capability",
"WebSearchConfig": ".web_search_config",
"WebSearchProviderManifest": ".web_search_provider_manifest",
@@ -755,8 +755,8 @@ __all__ = [
"UserMessage",
"UserMessageContent",
"UserMessageContentItem",
- "UserToolApprovalEvent",
- "UserToolResponseEvent",
+ "UserToolApprovalInputEvent",
+ "UserToolResponseInputEvent",
"WebSearchCapability",
"WebSearchConfig",
"WebSearchProviderManifest",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/turn_input_item.py b/python/trueforge_sdk/src/trueforge_sdk/types/turn_input_item.py
index 9e1c299ac..48167a7e0 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/turn_input_item.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/turn_input_item.py
@@ -3,7 +3,7 @@
import typing
from .user_message import UserMessage
-from .user_tool_approval_event import UserToolApprovalEvent
-from .user_tool_response_event import UserToolResponseEvent
+from .user_tool_approval_input_event import UserToolApprovalInputEvent
+from .user_tool_response_input_event import UserToolResponseInputEvent
-TurnInputItem = typing.Union[UserMessage, UserToolApprovalEvent, UserToolResponseEvent]
+TurnInputItem = typing.Union[UserMessage, UserToolApprovalInputEvent, UserToolResponseInputEvent]
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/user_tool_approval_event.py b/python/trueforge_sdk/src/trueforge_sdk/types/user_tool_approval_input_event.py
similarity index 93%
rename from python/trueforge_sdk/src/trueforge_sdk/types/user_tool_approval_event.py
rename to python/trueforge_sdk/src/trueforge_sdk/types/user_tool_approval_input_event.py
index 79939dc2c..ac68922da 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/user_tool_approval_event.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/user_tool_approval_input_event.py
@@ -8,7 +8,7 @@ from ..core.unchecked_base_model import UncheckedBaseModel
from .approval_decision import ApprovalDecision
-class UserToolApprovalEvent(UncheckedBaseModel):
+class UserToolApprovalInputEvent(UncheckedBaseModel):
approval: ApprovalDecision
thread_id: str = pydantic.Field()
"""
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/user_tool_response_event.py b/python/trueforge_sdk/src/trueforge_sdk/types/user_tool_response_input_event.py
similarity index 93%
rename from python/trueforge_sdk/src/trueforge_sdk/types/user_tool_response_event.py
rename to python/trueforge_sdk/src/trueforge_sdk/types/user_tool_response_input_event.py
index 0fa843bf1..a81901444 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/user_tool_response_event.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/user_tool_response_input_event.py
@@ -7,7 +7,7 @@ from ..core.pydantic_utilities import IS_PYDANTIC_V2
from ..core.unchecked_base_model import UncheckedBaseModel
-class UserToolResponseEvent(UncheckedBaseModel):
+class UserToolResponseInputEvent(UncheckedBaseModel):
content: str = pydantic.Field()
"""
Client-side tool result content.