Skip to content

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

Add session deletion API (#21)

Bhavesh Patelc61be90b6b7e
diff --git a/fern/openapi/openapi.json b/fern/openapi/openapi.json
index 6986be705..2a7783b57 100644
--- a/fern/openapi/openapi.json
+++ b/fern/openapi/openapi.json
@@ -3152,6 +3152,36 @@
}
},
"/api/v1/sessions/{sessionId}": {
+ "delete": {
+ "description": "Delete a session and all related turns, events, and internal state. Idempotent if already gone.",
+ "parameters": [
+ {
+ "description": "Session identifier.",
+ "in": "path",
+ "name": "sessionId",
+ "required": true,
+ "schema": {
+ "description": "Session identifier.",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "Session and all related data deleted."
+ }
+ },
+ "summary": "Delete a session",
+ "tags": [
+ "Sessions"
+ ],
+ "x-fern-sdk-group-name": [
+ "sessions"
+ ],
+ "x-fern-sdk-method-name": "delete"
+ },
"get": {
"description": "Fetch a session by ID.",
"parameters": [
diff --git a/packages/harness/src/agent-session/index.ts b/packages/harness/src/agent-session/index.ts
index c60c42f2b..09c803814 100644
--- a/packages/harness/src/agent-session/index.ts
+++ b/packages/harness/src/agent-session/index.ts
@@ -55,6 +55,7 @@ export type {
AppendToThreadContextInput,
CreateSessionInput,
CreateTurnInput,
+ DeleteSessionInput,
FreezeAndGetTurnInput,
GetSessionInput,
GetTurnInput,
diff --git a/packages/harness/src/agent-session/store/ISessionStore.ts b/packages/harness/src/agent-session/store/ISessionStore.ts
index ea5c6bedd..06a7cd936 100644
--- a/packages/harness/src/agent-session/store/ISessionStore.ts
+++ b/packages/harness/src/agent-session/store/ISessionStore.ts
@@ -35,6 +35,11 @@ export interface GetSessionInput {
session_id: string;
}
+export interface DeleteSessionInput {
+ tenant_id: string;
+ session_id: string;
+}
+
export interface ListSessionsInput {
tenant_id: string;
limit: number;
@@ -203,6 +208,9 @@ export interface ISessionStore<
*/
createSession(input: CreateSessionInput<TSessionCustom>): Promise<void>;
+ /** Permanently removes a session and all related data; missing sessions are a no-op. */
+ deleteSession(input: DeleteSessionInput): Promise<void>;
+
/**
* MUST return SessionRecord with `agent_spec` fully hydrated, even if the backend
* only stores a uri/id (or named-agent ref). Hydration is the store's job — harness
diff --git a/packages/harness/src/agent-session/store/InMemorySessionStore.ts b/packages/harness/src/agent-session/store/InMemorySessionStore.ts
index 100e1ccec..6d3b71629 100644
--- a/packages/harness/src/agent-session/store/InMemorySessionStore.ts
+++ b/packages/harness/src/agent-session/store/InMemorySessionStore.ts
@@ -12,6 +12,7 @@ import type {
AppendToThreadContextInput,
CreateSessionInput,
CreateTurnInput,
+ DeleteSessionInput,
FreezeAndGetTurnInput,
GetSessionInput,
GetTurnInput,
@@ -176,6 +177,20 @@ export class InMemorySessionStore<
return;
}
+ async deleteSession(input: DeleteSessionInput): Promise<void> {
+ const sKey = sessionKey(input.session_id);
+ const stored = this.sessions.get(sKey);
+ if (stored?.record.tenant_id !== input.tenant_id) {
+ return;
+ }
+ for (const turnId of stored.turnIds) {
+ const tKey = turnKey({ session_id: input.session_id, turn_id: turnId });
+ this.turns.delete(tKey);
+ this.events.delete(tKey);
+ }
+ this.sessions.delete(sKey);
+ }
+
async getSession(input: GetSessionInput): Promise<SessionRecord<TSessionCustom> | undefined> {
const stored = this.sessions.get(sessionKey(input.session_id));
return stored?.record.tenant_id === input.tenant_id ? deepCopy(stored.record) : undefined;
diff --git a/packages/harness/tests/agent-session/store/storeContractSuite.ts b/packages/harness/tests/agent-session/store/storeContractSuite.ts
index 180fcd2e8..71667e479 100644
--- a/packages/harness/tests/agent-session/store/storeContractSuite.ts
+++ b/packages/harness/tests/agent-session/store/storeContractSuite.ts
@@ -7,6 +7,7 @@ import type { ISessionStore } from '../../../src/agent-session/store/ISessionSto
import { decodeSessionEventPageToken } from '../../../src/agent-session/store/SessionEventPageToken';
import {
PreviousTurnRunningError,
+ SessionNotFoundError,
SessionStoreConflictError,
SessionStoreInvariantError,
SessionStoreNotFoundError,
@@ -64,6 +65,8 @@ function contextContents(messages: ContextMessage[] | undefined): string[] {
export function runStoreContractSuite(createStore: () => ISessionStore) {
const tenant = 't1';
const sessionId = 's1';
+ const missingSessionId = 'missing-session';
+ const missingTurnId = 'missing-turn';
async function finishTurn(store: ISessionStore, turnId: string) {
const state = makeDoneTurnState();
@@ -84,6 +87,77 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
});
}
+ function turnScopedWrites(
+ store: ISessionStore,
+ keys: { session_id: string; turn_id: string },
+ ): (() => Promise<unknown>)[] {
+ const doneState = makeDoneTurnState();
+ return [
+ () =>
+ store.freezeAndGetTurn({
+ ...keys,
+ turn_done_event: makeTurnDoneEvent(makeCancelledTurnState(CancellationReason.ClientCancelled)),
+ }),
+ () =>
+ store.updateTurnState({
+ ...keys,
+ state: doneState,
+ turn_done_event: makeTurnDoneEvent(doneState),
+ }),
+ () =>
+ store.addThreads({
+ ...keys,
+ threads: [
+ {
+ thread_id: 'child',
+ context: [],
+ current_context_usage: getEmptyCurrentContextUsage(),
+ parent: { thread_id: MAIN_THREAD_ID, tool_call_id: 'tc1' },
+ agent_info: { type: 'dynamic', name: 'child', input: 'task' },
+ completion: null,
+ capability_state: null,
+ },
+ ],
+ }),
+ () => store.removeThreads({ ...keys, thread_ids: [MAIN_THREAD_ID] }),
+ () =>
+ store.appendToThreadContext({
+ ...keys,
+ thread_id: MAIN_THREAD_ID,
+ context: [userMessage('late')],
+ current_context_usage: null,
+ completion: null,
+ }),
+ () =>
+ store.overwriteThreadContext({
+ ...keys,
+ event: {
+ type: EventType.AGENT_CONTEXT_OVERWRITE,
+ id: newEventId(),
+ created_at: new Date().toISOString(),
+ thread_id: MAIN_THREAD_ID,
+ reason: 'compaction',
+ context: [userMessage('late')],
+ current_context_usage: getEmptyCurrentContextUsage(),
+ usage: getEmptyUsage(),
+ },
+ }),
+ () =>
+ store.patchMCPServers({
+ ...keys,
+ mcp_servers: [{ id: 'svc', name: 'svc', session_id: 'mcp-1', transport_type: 'streamable-http' }],
+ }),
+ () => store.patchSandboxInfo({ ...keys, sandbox_info: { sandbox_id: 'sbx-1' } }),
+ () =>
+ store.patchThreadCapabilityState({
+ ...keys,
+ thread_id: MAIN_THREAD_ID,
+ key: 'tfy.plan',
+ state: { step: 1 },
+ }),
+ ];
+ }
+
describe('session CRUD + activity', () => {
it('createSession hydrates agent_spec and sets last_activity_timestamp_ms', async () => {
const store = createStore();
@@ -144,6 +218,313 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
});
});
+ describe('deleteSession', () => {
+ it('removes all session data, is idempotent, and is a no-op when tenant_id does not match', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createSession({
+ tenant_id: 'other',
+ session_id: 'other-session',
+ agent_spec: makeAgentSpec(),
+ custom: null,
+ });
+
+ await store.createTurn(
+ makeCreateTurnInput({
+ sessionId,
+ turnId: 'turn-1',
+ new_context_appends: [
+ {
+ thread_id: MAIN_THREAD_ID,
+ context: [userMessage('private context')],
+ current_context_usage: getEmptyCurrentContextUsage(),
+ },
+ ],
+ capability_states: [{ thread_id: MAIN_THREAD_ID, capability_state: { 'tfy.initial': { value: 1 } } }],
+ }),
+ );
+ await store.appendToEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ events: [makeTurnCreatedEvent('turn-1'), makeModelMessageEvent()],
+ });
+ await store.patchThreadCapabilityState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ thread_id: MAIN_THREAD_ID,
+ key: 'tfy.plan',
+ state: { step: 'secret' },
+ });
+ await store.patchMCPServers({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ mcp_servers: [{ id: 'svc', name: 'svc', session_id: 'mcp-1', transport_type: 'streamable-http' }],
+ });
+ await store.patchSandboxInfo({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ sandbox_info: { sandbox_id: 'sbx-1' },
+ });
+
+ await store.deleteSession({ tenant_id: 'other', session_id: sessionId });
+ expect(await store.getSession({ tenant_id: tenant, session_id: sessionId })).toBeDefined();
+ expect(await store.getTurn({ session_id: sessionId, turn_id: 'turn-1' })).toBeDefined();
+ expect(
+ (
+ await store.listTurnEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ limit: 10,
+ page_token: undefined,
+ order: 'asc',
+ })
+ ).data,
+ ).toHaveLength(2);
+
+ await store.deleteSession({ tenant_id: tenant, session_id: sessionId });
+ await store.deleteSession({ tenant_id: tenant, session_id: sessionId });
+
+ expect(await store.getSession({ tenant_id: tenant, session_id: sessionId })).toBeUndefined();
+ expect(await store.getSession({ tenant_id: 'other', session_id: 'other-session' })).toBeDefined();
+ expect(await store.getTurn({ session_id: sessionId, turn_id: 'turn-1' })).toBeUndefined();
+ await expect(
+ store.listTurnEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ limit: 10,
+ page_token: undefined,
+ order: 'asc',
+ }),
+ ).rejects.toBeInstanceOf(TurnNotFoundError);
+ await expect(
+ store.listSessionEvents({
+ session_id: sessionId,
+ limit: 10,
+ page_token: undefined,
+ last_turn_id: undefined,
+ }),
+ ).rejects.toBeInstanceOf(SessionNotFoundError);
+
+ const listed = await store.listSessions({
+ tenant_id: tenant,
+ limit: 10,
+ page_token: undefined,
+ order: undefined,
+ start_timestamp: undefined,
+ end_timestamp: undefined,
+ });
+ expect(listed.data).toHaveLength(0);
+
+ // Reusing every identifier must not expose orphaned events, context, or checkpoint state.
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const recreated = mustGet(await store.getTurn({ session_id: sessionId, turn_id: 'turn-1' }));
+ expect(recreated.snapshot.threads[MAIN_THREAD_ID]?.context).toEqual([]);
+ expect(recreated.snapshot.threads[MAIN_THREAD_ID]?.capability_state).toBeNull();
+ expect(recreated.snapshot.mcp_servers).toBeNull();
+ expect(recreated.snapshot.sandbox_info).toBeNull();
+ expect(
+ (
+ await store.listTurnEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ limit: 10,
+ page_token: undefined,
+ order: 'asc',
+ })
+ ).data,
+ ).toEqual([]);
+ });
+
+ it('rejects session mutations after deleteSession', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ await store.deleteSession({ tenant_id: tenant, session_id: sessionId });
+
+ await expect(
+ store.updateSession({
+ tenant_id: tenant,
+ session_id: sessionId,
+ agent_spec: undefined,
+ title: 'new-title',
+ }),
+ ).rejects.toBeInstanceOf(SessionNotFoundError);
+ await expect(store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-2' }))).rejects.toBeInstanceOf(
+ SessionNotFoundError,
+ );
+ });
+
+ it('rejects turn mutations after deleteSession', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ await store.deleteSession({ tenant_id: tenant, session_id: sessionId });
+
+ for (const write of turnScopedWrites(store, { session_id: sessionId, turn_id: 'turn-1' })) {
+ await expect(write()).rejects.toBeInstanceOf(TurnNotFoundError);
+ }
+ });
+
+ it('rejects event mutations after deleteSession', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ await store.deleteSession({ tenant_id: tenant, session_id: sessionId });
+
+ const keys = { session_id: sessionId, turn_id: 'turn-1' };
+ await expect(
+ store.appendToEvents({
+ ...keys,
+ events: [makeTurnCreatedEvent('turn-1')],
+ }),
+ ).rejects.toBeInstanceOf(TurnNotFoundError);
+ await expect(
+ store.listTurnEvents({
+ ...keys,
+ limit: 10,
+ page_token: undefined,
+ order: undefined,
+ }),
+ ).rejects.toBeInstanceOf(TurnNotFoundError);
+ await expect(
+ store.listSessionEvents({
+ session_id: sessionId,
+ limit: 10,
+ page_token: undefined,
+ last_turn_id: undefined,
+ }),
+ ).rejects.toBeInstanceOf(SessionNotFoundError);
+ });
+
+ it('leaves sessions whose id extends the deleted id untouched', async () => {
+ const store = createStore();
+ const nested = `${sessionId}:nested`;
+ await seedSession(store);
+ await store.createSession({
+ tenant_id: tenant,
+ session_id: nested,
+ agent_spec: makeAgentSpec(),
+ custom: null,
+ });
+ await store.createTurn(makeCreateTurnInput({ sessionId: nested, turnId: 'turn-1' }));
+ const nestedKeys = { session_id: nested, turn_id: 'turn-1' };
+ await store.appendToEvents({ ...nestedKeys, events: [makeTurnCreatedEvent('turn-1')] });
+
+ await store.deleteSession({ tenant_id: tenant, session_id: sessionId });
+
+ expect(await store.getSession({ tenant_id: tenant, session_id: nested })).toBeDefined();
+ expect(await store.getTurn(nestedKeys)).toBeDefined();
+ expect(
+ (await store.listTurnEvents({ ...nestedKeys, limit: 10, page_token: undefined, order: 'asc' })).data,
+ ).toHaveLength(1);
+ });
+
+ it('child appends that race deleteSession fail cleanly and leave no orphans', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const keys = { session_id: sessionId, turn_id: 'turn-1' };
+
+ const results = await Promise.allSettled([
+ store.deleteSession({ tenant_id: tenant, session_id: sessionId }),
+ store.appendToEvents({
+ ...keys,
+ events: [makeTurnCreatedEvent('turn-1'), makeModelMessageEvent()],
+ }),
+ store.appendToThreadContext({
+ ...keys,
+ thread_id: MAIN_THREAD_ID,
+ context: [userMessage('raced')],
+ current_context_usage: null,
+ completion: null,
+ }),
+ ]);
+
+ const [deletion, ...appends] = results;
+ expect(deletion.status).toBe('fulfilled');
+ for (const result of appends) {
+ if (result.status === 'rejected') {
+ expect(result.reason).toBeInstanceOf(SessionStoreNotFoundError);
+ }
+ }
+
+ expect(await store.getSession({ tenant_id: tenant, session_id: sessionId })).toBeUndefined();
+ expect(await store.getTurn(keys)).toBeUndefined();
+
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const recreated = mustGet(await store.getTurn(keys));
+ expect(recreated.snapshot.threads[MAIN_THREAD_ID]?.context).toEqual([]);
+ expect(
+ (
+ await store.listTurnEvents({
+ ...keys,
+ limit: 10,
+ page_token: undefined,
+ order: 'asc',
+ })
+ ).data,
+ ).toEqual([]);
+ });
+ });
+
+ describe('missing session / turn', () => {
+ it('rejects session mutations for a missing session', async () => {
+ const store = createStore();
+
+ await expect(
+ store.updateSession({
+ tenant_id: tenant,
+ session_id: missingSessionId,
+ agent_spec: undefined,
+ title: 'new-title',
+ }),
+ ).rejects.toBeInstanceOf(SessionNotFoundError);
+ await expect(
+ store.createTurn(makeCreateTurnInput({ sessionId: missingSessionId, turnId: 'turn-1' })),
+ ).rejects.toBeInstanceOf(SessionNotFoundError);
+ });
+
+ it('rejects turn mutations for a missing turn', async () => {
+ const store = createStore();
+ await seedSession(store);
+
+ for (const write of turnScopedWrites(store, { session_id: sessionId, turn_id: missingTurnId })) {
+ await expect(write()).rejects.toBeInstanceOf(TurnNotFoundError);
+ }
+ });
+
+ it('rejects event mutations for a missing session or turn', async () => {
+ const store = createStore();
+ await seedSession(store);
+ const keys = { session_id: sessionId, turn_id: missingTurnId };
+
+ await expect(
+ store.appendToEvents({
+ ...keys,
+ events: [makeTurnCreatedEvent(missingTurnId)],
+ }),
+ ).rejects.toBeInstanceOf(TurnNotFoundError);
+ await expect(
+ store.listTurnEvents({
+ ...keys,
+ limit: 10,
+ page_token: undefined,
+ order: undefined,
+ }),
+ ).rejects.toBeInstanceOf(TurnNotFoundError);
+ await expect(
+ store.listSessionEvents({
+ session_id: missingSessionId,
+ limit: 10,
+ page_token: undefined,
+ last_turn_id: undefined,
+ }),
+ ).rejects.toBeInstanceOf(SessionNotFoundError);
+ });
+ });
+
describe('listSessions', () => {
async function seedThreeSessions(store: ISessionStore) {
for (const id of ['sa', 'sb', 'sc']) {
@@ -842,11 +1223,11 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
await expect(
store.updateTurnState({
session_id: sessionId,
- turn_id: 'missing',
+ turn_id: missingTurnId,
state,
turn_done_event: makeTurnDoneEvent(state),
}),
- ).rejects.toBeInstanceOf(SessionStoreNotFoundError);
+ ).rejects.toBeInstanceOf(TurnNotFoundError);
});
});
@@ -1214,7 +1595,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
await expect(
store.listTurnEvents({
session_id: sessionId,
- turn_id: 'missing',
+ turn_id: missingTurnId,
limit: 10,
page_token: undefined,
order: undefined,
@@ -1336,10 +1717,10 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
store.listSessionEvents({
session_id: sessionId,
limit: 10,
- last_turn_id: 'missing',
+ last_turn_id: missingTurnId,
page_token: undefined,
}),
- ).rejects.toBeInstanceOf(SessionStoreNotFoundError);
+ ).rejects.toBeInstanceOf(TurnNotFoundError);
});
it('listSessionEvents page tokens retain their anchor when the active branch changes', async () => {
diff --git a/packages/server/src/apis/sessions.ts b/packages/server/src/apis/sessions.ts
index e02c25b15..c714079b8 100644
--- a/packages/server/src/apis/sessions.ts
+++ b/packages/server/src/apis/sessions.ts
@@ -15,6 +15,7 @@ import configuration from '../config';
import {
cancelSessionRoute,
createSessionRoute,
+ deleteSessionRoute,
getSessionRoute,
listSessionEventsRoute,
listSessionsRoute,
@@ -244,6 +245,12 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
return c.json({ data: toWireSession(record) }, 200);
};
+ const deleteSessionHandler: RouteHandler<typeof deleteSessionRoute> = async c => {
+ const { sessionId } = c.req.valid('param');
+ await deps.sessionStore.deleteSession({ tenant_id: TENANT_ID, session_id: sessionId });
+ return c.body(null, 204);
+ };
+
const updateSessionHandler: RouteHandler<typeof updateSessionRoute> = async c => {
const { sessionId } = c.req.valid('param');
const body = c.req.valid('json');
@@ -341,6 +348,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
const router = new OpenAPIHono();
router.openapi(createSessionRoute, createSessionHandler);
router.openapi(getSessionRoute, getSessionHandler);
+ router.openapi(deleteSessionRoute, deleteSessionHandler);
router.openapi(updateSessionRoute, updateSessionHandler);
router.openapi(listSessionsRoute, listSessionsHandler);
router.openapi(cancelSessionRoute, cancelSessionHandler);
diff --git a/packages/server/src/apis/turns.ts b/packages/server/src/apis/turns.ts
index c95821033..e3b3fe384 100644
--- a/packages/server/src/apis/turns.ts
+++ b/packages/server/src/apis/turns.ts
@@ -267,7 +267,20 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
}
}
} catch (error) {
- deps.logger.error('Unexpected error in turn SSE stream loop', extractErrorLogFields(error));
+ // Session delete can cascade mid-stream; store misses leave the DB clean but end SSE here.
+ if (error instanceof SessionStoreNotFoundError) {
+ deps.logger.warn('Turn stream ended after session/turn was removed', {
+ sessionId,
+ turnId: turn.id,
+ ...extractErrorLogFields(error),
+ });
+ } else {
+ deps.logger.error('Unexpected error in turn SSE stream loop', {
+ sessionId,
+ turnId: turn.id,
+ ...extractErrorLogFields(error),
+ });
+ }
} finally {
clearTimeout(maxExecutionTimer);
await stream.close();
diff --git a/packages/server/src/db/postgres/session-store/PostgresSessionStore.ts b/packages/server/src/db/postgres/session-store/PostgresSessionStore.ts
index 00ab7c8c2..ce47a4182 100644
--- a/packages/server/src/db/postgres/session-store/PostgresSessionStore.ts
+++ b/packages/server/src/db/postgres/session-store/PostgresSessionStore.ts
@@ -8,6 +8,7 @@ import type {
AppendToThreadContextInput,
CreateSessionInput,
CreateTurnInput,
+ DeleteSessionInput,
FreezeAndGetTurnInput,
GetSessionInput,
GetTurnInput,
@@ -36,6 +37,7 @@ import {
} from './queries/events';
import {
createSession as createSessionQuery,
+ deleteSession as deleteSessionQuery,
getSession as getSessionQuery,
listSessions as listSessionsQuery,
updateSession as updateSessionQuery,
@@ -74,9 +76,11 @@ type TurnCustom = Record<string, never>;
*
* Hard invariants (violations proven by failing tests during prototyping —
* see the freeze/fence tests):
- * 1. Only the session tip can be running. `createTurn` rejects a running
- * previous turn; callers must `freezeAndGetTurn` first (barge-in IS the
- * cancellation of the predecessor).
+ * 1. A turn cannot be used as `previous_turn_id` while it is still `running` —
+ * `createTurn` rejects that with PreviousTurnRunningError; callers must
+ * `freezeAndGetTurn` first (barge-in IS cancellation of that predecessor).
+ * Tip-equality is NOT required: new roots and concurrent forks from a
+ * finished tip can leave more than one turn `running` at once.
* 2. Every turn-scoped write is fenced on `state->>'status' = 'running'`.
* 3. Terminal turns are IMMUTABLE — a terminal read is a final read.
*/
@@ -87,6 +91,10 @@ export class PostgresSessionStore implements ISessionStore<SessionCustom, TurnCu
return createSessionQuery(this.db, input);
}
+ deleteSession(input: DeleteSessionInput): Promise<void> {
+ return deleteSessionQuery(this.db, input);
+ }
+
getSession(input: GetSessionInput): Promise<SessionRecord<SessionCustom> | undefined> {
return getSessionQuery(this.db, input);
}
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 25c0b3ff2..5459d9b0a 100644
--- a/packages/server/src/db/postgres/session-store/queries/sessions.ts
+++ b/packages/server/src/db/postgres/session-store/queries/sessions.ts
@@ -1,6 +1,7 @@
import type { SessionRecord } from '@truefoundry/utils/agent-session/models/SessionRecord';
import type {
CreateSessionInput,
+ DeleteSessionInput,
GetSessionInput,
ListSessionsInput,
UpdateSessionInput,
@@ -91,6 +92,14 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionIn
}
}
+export async function deleteSession(db: Kysely<Database>, input: DeleteSessionInput): Promise<void> {
+ await db
+ .deleteFrom('session')
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .execute();
+}
+
export async function getSession(
db: Kysely<Database>,
input: GetSessionInput,
diff --git a/packages/server/src/db/sqlite/session-store/SqliteSessionStore.ts b/packages/server/src/db/sqlite/session-store/SqliteSessionStore.ts
index 940e01ec6..90d60a042 100644
--- a/packages/server/src/db/sqlite/session-store/SqliteSessionStore.ts
+++ b/packages/server/src/db/sqlite/session-store/SqliteSessionStore.ts
@@ -8,6 +8,7 @@ import type {
AppendToThreadContextInput,
CreateSessionInput,
CreateTurnInput,
+ DeleteSessionInput,
FreezeAndGetTurnInput,
GetSessionInput,
GetTurnInput,
@@ -36,6 +37,7 @@ import {
} from './queries/events';
import {
createSession as createSessionQuery,
+ deleteSession as deleteSessionQuery,
getSession as getSessionQuery,
listSessions as listSessionsQuery,
updateSession as updateSessionQuery,
@@ -72,8 +74,10 @@ type TurnCustom = Record<string, never>;
* late appends touch only its OWN rows — structural leaks are impossible.
*
* Hard invariants:
- * 1. Only the session tip can be running. `createTurn` rejects a running
- * previous turn; callers must `freezeAndGetTurn` first.
+ * 1. A turn cannot be used as `previous_turn_id` while it is still `running` —
+ * `createTurn` rejects that; callers must `freezeAndGetTurn` first.
+ * Tip-equality is NOT required: new roots and concurrent forks from a
+ * finished tip can leave more than one turn `running` at once.
* 2. Every turn-scoped write is fenced on `state->>'status' = 'running'`.
* 3. Terminal turns are IMMUTABLE — a terminal read is a final read.
* 4. BEGIN IMMEDIATE provides write locking (no FOR SHARE / FOR UPDATE).
@@ -85,6 +89,10 @@ export class SqliteSessionStore implements ISessionStore<SessionCustom, TurnCust
return createSessionQuery(this.db, input);
}
+ deleteSession(input: DeleteSessionInput): Promise<void> {
+ return deleteSessionQuery(this.db, input);
+ }
+
getSession(input: GetSessionInput): Promise<SessionRecord<SessionCustom> | undefined> {
return getSessionQuery(this.db, input);
}
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 3a81088c4..64bcbb982 100644
--- a/packages/server/src/db/sqlite/session-store/queries/sessions.ts
+++ b/packages/server/src/db/sqlite/session-store/queries/sessions.ts
@@ -2,6 +2,7 @@ import type { AgentSpec } from '@truefoundry/utils/agent-session';
import type { SessionRecord } from '@truefoundry/utils/agent-session/models/SessionRecord';
import type {
CreateSessionInput,
+ DeleteSessionInput,
GetSessionInput,
ListSessionsInput,
UpdateSessionInput,
@@ -83,6 +84,14 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionIn
}
}
+export async function deleteSession(db: Kysely<Database>, input: DeleteSessionInput): Promise<void> {
+ await db
+ .deleteFrom('session')
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .execute();
+}
+
export async function getSession(
db: Kysely<Database>,
input: GetSessionInput,
diff --git a/packages/server/src/routes/sessionRoutes.ts b/packages/server/src/routes/sessionRoutes.ts
index af4d16c8b..adf830b2b 100644
--- a/packages/server/src/routes/sessionRoutes.ts
+++ b/packages/server/src/routes/sessionRoutes.ts
@@ -75,6 +75,24 @@ export const getSessionRoute = createRoute({
},
});
+export const deleteSessionRoute = createRoute({
+ method: 'delete',
+ path: '/{sessionId}',
+ tags: [SESSIONS_TAG],
+ summary: 'Delete a session',
+ description: 'Delete a session and all related turns, events, and internal state. Idempotent if already gone.',
+ 'x-fern-sdk-group-name': ['sessions'],
+ 'x-fern-sdk-method-name': 'delete',
+ request: {
+ params: SessionIdParamsSchema,
+ },
+ responses: {
+ 204: {
+ description: 'Session and all related data deleted.',
+ },
+ },
+});
+
export const updateSessionRoute = createRoute({
method: 'patch',
path: '/{sessionId}',
diff --git a/packages/server/tests/unit/apis/deletedSessionCrud.test.ts b/packages/server/tests/unit/apis/deletedSessionCrud.test.ts
new file mode 100644
index 000000000..e3b30d201
--- /dev/null
+++ b/packages/server/tests/unit/apis/deletedSessionCrud.test.ts
@@ -0,0 +1,87 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { InMemorySessionStore, Sessions } from '@truefoundry/utils/agent-session';
+import { RequestReplyRouter } from '@truefoundry/utils/request-reply';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { createClient } from 'redis';
+import { createLogger } from 'winston';
+import { createSessionsRouter, TENANT_ID } from '../../../src/apis/sessions';
+import { createTurnsRouter } from '../../../src/apis/turns';
+import { ActiveTurnRegistry } from '../../../src/runtime/activeTurns';
+import { ListSessionsResponseSchema } from '../../../src/schemas/session';
+import { McpStore } from '../../../src/store/McpStore';
+import { ModelStore } from '../../../src/store/ModelStore';
+
+describe('public CRUD after session deletion', () => {
+ it('returns not found for session and turn operations', async () => {
+ const sessionStore = new InMemorySessionStore();
+ const sessions = new Sessions({ sessionStore });
+ const activeTurns = new ActiveTurnRegistry();
+ const modelStore = new ModelStore([]);
+ const mcpStore = new McpStore([]);
+ const app = new OpenAPIHono();
+
+ app.route(
+ '/',
+ createSessionsRouter({
+ sessions,
+ sessionStore,
+ activeTurns,
+ modelStore,
+ mcpStore,
+ sandboxSupported: false,
+ redis: createClient(),
+ requestReplyRouter: new RequestReplyRouter(),
+ }),
+ );
+ app.route(
+ '/',
+ createTurnsRouter({
+ sessions,
+ activeTurns,
+ modelStore,
+ mcpStore,
+ logger: createLogger({ silent: true }),
+ }),
+ );
+
+ await sessionStore.createSession({
+ tenant_id: TENANT_ID,
+ session_id: 's1',
+ agent_spec: {
+ model: { name: 'test-model' },
+ instructions: 'test',
+ },
+ custom: null,
+ });
+ assert.equal((await app.request('/s1', { method: 'DELETE' })).status, 204);
+
+ const requests = [
+ app.request('/s1'),
+ app.request('/s1', {
+ method: 'PATCH',
+ headers: { 'content-type': 'application/json' },
+ body: '{}',
+ }),
+ app.request('/s1/events'),
+ app.request('/s1/cancel', { method: 'POST' }),
+ app.request('/s1/turns'),
+ app.request('/s1/turns/turn-1'),
+ app.request('/s1/turns/turn-1/events'),
+ app.request('/s1/turns', {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: '{}',
+ }),
+ ];
+
+ for (const response of await Promise.all(requests)) {
+ assert.equal(response.status, 404);
+ }
+
+ const listed = await app.request('/');
+ assert.equal(listed.status, 200);
+ assert.deepEqual(ListSessionsResponseSchema.parse(await listed.json()).data, []);
+ assert.equal((await app.request('/s1', { method: 'DELETE' })).status, 204);
+ });
+});
diff --git a/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts b/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts
new file mode 100644
index 000000000..d51ec00e8
--- /dev/null
+++ b/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts
@@ -0,0 +1,61 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+import type { Sessions } from '@truefoundry/utils/agent-session';
+import { TurnNotFoundError } from '@truefoundry/utils/agent-session';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { createLogger } from 'winston';
+import { createTurnsRouter } from '../../../src/apis/turns';
+import { ActiveTurnRegistry } from '../../../src/runtime/activeTurns';
+import { McpStore } from '../../../src/store/McpStore';
+import { ModelStore } from '../../../src/store/ModelStore';
+
+describe('turn SSE after session deletion', () => {
+ it('warns when the stream ends because the session/turn was removed', async () => {
+ const warnings: unknown[] = [];
+ const logger = createLogger({ silent: true });
+ logger.warn = ((message: unknown) => {
+ warnings.push(message);
+ return logger;
+ }) as typeof logger.warn;
+
+ const sessions = {
+ get: () =>
+ Promise.resolve({
+ record: { last_turn_id: null },
+ createTurn: () =>
+ Promise.resolve({
+ id: 'turn-gone',
+ stream: async function* stream() {
+ throw new TurnNotFoundError('turn-gone');
+ },
+ }),
+ }),
+ } as unknown as Sessions;
+
+ const app = new OpenAPIHono();
+ app.route(
+ '/',
+ createTurnsRouter({
+ sessions,
+ activeTurns: new ActiveTurnRegistry(),
+ modelStore: new ModelStore([]),
+ mcpStore: new McpStore([]),
+ logger,
+ }),
+ );
+
+ const response = await app.request('/s1/turns', {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: '{}',
+ });
+ assert.equal(response.status, 200);
+ await response.text();
+
+ assert.ok(
+ warnings.some(
+ message => typeof message === 'string' && message.includes('Turn stream ended after session/turn was removed'),
+ ),
+ );
+ });
+});