Skip to content

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

add non terminal turn update to session store (#896)

Heer Ambavi4f74f508724c
diff --git a/.changeset/turn-paused-store.md b/.changeset/turn-paused-store.md
new file mode 100644
index 000000000..df55082c3
--- /dev/null
+++ b/.changeset/turn-paused-store.md
@@ -0,0 +1,6 @@
+---
+"@truefoundry/trueforge-core": patch
+"@truefoundry/trueforge": patch
+---
+
+Treat `paused` as a live turn. `updateTurnNonTerminalState` switches `running` and `paused` and appends `turn.update` without session metrics. Terminal writes and `freezeAndGetTurn` accept a paused tip. `createTurn` rejects a paused predecessor until it is frozen. `updateTurnState` is now `updateTurnTerminalState`.
diff --git a/packages/trueforge-core/src/agent-session/TurnHandle.ts b/packages/trueforge-core/src/agent-session/TurnHandle.ts
index f0bb2be03..64581effc 100644
--- a/packages/trueforge-core/src/agent-session/TurnHandle.ts
+++ b/packages/trueforge-core/src/agent-session/TurnHandle.ts
@@ -335,7 +335,7 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
if (!frozenByStore) {
try {
- await this.store.updateTurnState({
+ await this.store.updateTurnTerminalState({
session_id: this.turn.session_id,
turn_id: this.turn.turn_id,
state: terminalState,
diff --git a/packages/trueforge-core/src/agent-session/index.ts b/packages/trueforge-core/src/agent-session/index.ts
index f380dd585..1d05a2160 100644
--- a/packages/trueforge-core/src/agent-session/index.ts
+++ b/packages/trueforge-core/src/agent-session/index.ts
@@ -21,8 +21,10 @@ export {
TurnStatePausedSchema,
TurnStateRunningSchema,
TurnStateSchema,
+ isNonTerminalTurnState,
} from './schemas/turn';
export type {
+ NonTerminalTurnState,
TerminalTurnState,
Turn,
TurnInboundEventItem,
@@ -104,7 +106,8 @@ export type {
TurnContextAppend,
TurnRecordWithoutSnapshot,
UpdateSessionInput,
- UpdateTurnStateInput,
+ UpdateTurnNonTerminalStateInput,
+ UpdateTurnTerminalStateInput,
} from './store/ISessionStore';
export {
InvalidPageTokenError,
diff --git a/packages/trueforge-core/src/agent-session/schemas/turn.ts b/packages/trueforge-core/src/agent-session/schemas/turn.ts
index 31073c32b..700e44787 100644
--- a/packages/trueforge-core/src/agent-session/schemas/turn.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/turn.ts
@@ -207,6 +207,11 @@ export const TurnInboundEventItemSchema = z
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' | 'paused' }>;
+export type NonTerminalTurnState = Extract<TurnState, { status: 'running' | 'paused' }>;
+export type TerminalTurnState = Exclude<TurnState, NonTerminalTurnState>;
export type TurnMetrics = z.infer<typeof TurnMetricsSchema>;
export type TurnInboundEventItem = z.infer<typeof TurnInboundEventItemSchema>;
+
+export function isNonTerminalTurnState(state: TurnState): state is NonTerminalTurnState {
+ return state.status === 'running' || state.status === 'paused';
+}
diff --git a/packages/trueforge-core/src/agent-session/store/ISessionStore.ts b/packages/trueforge-core/src/agent-session/store/ISessionStore.ts
index c41b2cb63..73884366d 100644
--- a/packages/trueforge-core/src/agent-session/store/ISessionStore.ts
+++ b/packages/trueforge-core/src/agent-session/store/ISessionStore.ts
@@ -9,10 +9,15 @@ import type { CurrentContextUsage } from '../../core/runtime/contextUsage';
import type { SandboxInfo } from '../../core/sandbox/Sandbox';
import type { SessionRecord } from '../models/SessionRecord';
import type { TurnRecord } from '../models/TurnRecord';
-import type { PersistedTurnEvent, SessionEventItem } from '../schemas/events';
+import type { PersistedTurnEvent, SessionEventItem, TurnUpdateEvent } from '../schemas/events';
import type { TokenPagination } from '../schemas/pagination';
import type { SessionMetadata } from '../schemas/session';
-import type { CancellationReason, TerminalTurnState, TurnInboundEventItem } from '../schemas/turn';
+import type {
+ CancellationReason,
+ NonTerminalTurnState,
+ TerminalTurnState,
+ TurnInboundEventItem,
+} from '../schemas/turn';
/**
* Caller-supplied fields for creating a session; the store owns timestamps and tip state.
@@ -158,14 +163,23 @@ export interface ListTurnsInput {
page_token: string | undefined;
}
-export interface UpdateTurnStateInput {
+interface TurnStateUpdateKeys {
session_id: string;
turn_id: string;
+}
+
+export interface UpdateTurnTerminalStateInput extends TurnStateUpdateKeys {
state: TerminalTurnState;
- /** Caller-built turn.done; written atomically with the state flip in the same tx. */
+ /** Caller-built turn.done; written atomically with the state flip. */
turn_done_event: PersistedTurnEvent;
}
+export interface UpdateTurnNonTerminalStateInput extends TurnStateUpdateKeys {
+ state: NonTerminalTurnState;
+ /** Caller-built turn.update; written atomically with the non-terminal state transition. */
+ turn_update_event: TurnUpdateEvent;
+}
+
export interface AppendToEventsInput {
session_id: string;
turn_id: string;
@@ -335,7 +349,7 @@ export interface ISessionStore<
* - string — fork/chain from that turn when it exists. Tip-equality is NOT
* required; concurrent forks from the same tip both succeed. Unknown id is
* allowed (relaxed) and treated as no inheritance. If that turn exists and
- * is still `running`, reject with {@link PreviousTurnRunningError} —
+ * is still `running` or `paused`, reject with {@link PreviousTurnRunningError} —
* callers must {@link freezeAndGetTurn} first.
* `last_turn_id` always advances to the new turn in the same atomic unit.
*
@@ -347,8 +361,8 @@ export interface ISessionStore<
createTurn(input: CreateTurnInput<TTurnCustom>): Promise<void>;
/**
- * Cancel if still running (persist `turn_done` and fold cost/duration into
- * `session.metrics`); already-terminal turns are a read. Missing → {@link TurnNotFoundError}.
+ * Cancel a non-terminal turn (`running` or `paused`): persist `turn_done` and fold cost/duration into
+ * `session.metrics`. Already-terminal turns are a read. Missing → {@link TurnNotFoundError}.
*/
freezeAndGetTurn(input: FreezeAndGetTurnInput): Promise<TurnRecord<TTurnCustom>>;
@@ -360,12 +374,14 @@ export interface ISessionStore<
input: ListTurnsInput,
): Promise<{ data: TurnRecordWithoutSnapshot<TTurnCustom>[]; pagination: TokenPagination }>;
+ /** Atomically performs `running ↔ paused` and appends turn.update. */
+ updateTurnNonTerminalState(input: UpdateTurnNonTerminalStateInput): Promise<void>;
+
/**
- * First terminal write wins (`running` → done/cancelled/error); otherwise 409.
- * Winning write also folds cost/duration into `session.metrics`. Missing → 404.
- * Must use the same lock/CAS as other turn mutations.
+ * First terminal write wins (`running|paused → done|cancelled|error`) and
+ * atomically appends turn.done and folds cost/duration into session metrics.
*/
- updateTurnState(input: UpdateTurnStateInput): Promise<void>;
+ updateTurnTerminalState(input: UpdateTurnTerminalStateInput): Promise<void>;
/**
* Durable event log for the turn. MUST include lifecycle rows: a
diff --git a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
index b1ff71900..e5dc38fa2 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, TurnInboundEventItem } from '../schemas/turn';
+import { isNonTerminalTurnState, type TerminalTurnState, type TurnInboundEventItem } from '../schemas/turn';
import { assertCreateTurnThreadDelta } from './assertCreateTurnThreadDelta';
import type {
AddThreadsInput,
@@ -33,7 +33,8 @@ import type {
TurnContextAppend,
TurnRecordWithoutSnapshot,
UpdateSessionInput,
- UpdateTurnStateInput,
+ UpdateTurnNonTerminalStateInput,
+ UpdateTurnTerminalStateInput,
} from './ISessionStore';
import { decodeOffsetPageToken, encodeOffsetPageToken } from './OffsetPageToken';
import {
@@ -391,9 +392,9 @@ export class InMemorySessionStore<
const prevKey = turnKey({ session_id: input.turn.session_id, turn_id: previousTurnId });
const prev = this.turns.get(prevKey);
// Unknown previous_turn_id is allowed (relaxed): treat as no inheritance.
- // A still-running previous must be frozen first.
+ // A still-live previous (running or paused) must be frozen first.
if (prev !== undefined) {
- if (prev.state.status === 'running') {
+ if (isNonTerminalTurnState(prev.state)) {
throw new PreviousTurnRunningError(previousTurnId);
}
previousSnapshot = prev.snapshot;
@@ -433,7 +434,7 @@ export class InMemorySessionStore<
const tKey = turnKey(input);
const turn = this.requireTurn(input.session_id, input.turn_id);
- if (turn.state.status === 'running') {
+ if (isNonTerminalTurnState(turn.state)) {
const cancelledState: TerminalTurnState = {
status: 'cancelled',
reason: input.reason,
@@ -475,22 +476,41 @@ export class InMemorySessionStore<
return paginate(records, input.limit, input.page_token);
}
- async updateTurnState(input: UpdateTurnStateInput): Promise<void> {
+ async updateTurnNonTerminalState(input: UpdateTurnNonTerminalStateInput): Promise<void> {
// Same as createTurn: synchronous body ⇒ atomic under run-to-completion.
const tKey = turnKey(input);
const turn = this.requireTurn(input.session_id, input.turn_id);
- if (turn.state.status === 'paused') {
- throw new SessionStoreInvariantError(`expected running state for turn ${input.turn_id}, got paused`);
- }
- if (turn.state.status !== 'running') {
+ const expectedSourceStatus = input.state.status === 'paused' ? 'running' : 'paused';
+ if (turn.state.status !== expectedSourceStatus) {
+ if (isNonTerminalTurnState(turn.state)) {
+ throw new SessionStoreInvariantError(
+ `expected ${expectedSourceStatus} state for turn ${input.turn_id}, got ${turn.state.status}`,
+ );
+ }
throw new TurnNotRunningError(input.turn_id, turn.state);
}
+ const list = this.events.get(tKey);
+ if (!list) {
+ throw new TurnNotFoundError(input.turn_id);
+ }
turn.state = deepCopy(input.state);
turn.updated_at = new Date();
+ list.push(deepCopy(input.turn_update_event));
+ }
+
+ async updateTurnTerminalState(input: UpdateTurnTerminalStateInput): Promise<void> {
+ const tKey = turnKey(input);
+ const turn = this.requireTurn(input.session_id, input.turn_id);
+ if (!isNonTerminalTurnState(turn.state)) {
+ throw new TurnNotRunningError(input.turn_id, turn.state);
+ }
const list = this.events.get(tKey);
- if (list) {
- list.push(deepCopy(input.turn_done_event));
+ if (!list) {
+ throw new TurnNotFoundError(input.turn_id);
}
+ turn.state = deepCopy(input.state);
+ turn.updated_at = new Date();
+ list.push(deepCopy(input.turn_done_event));
this.addTerminalSessionMetrics(input.session_id, turn.created_at, input.state);
}
diff --git a/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts b/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts
index 3d6b8d3cb..55be52e97 100644
--- a/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts
+++ b/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts
@@ -93,7 +93,7 @@ export class PreviousTurnRunningError extends SessionStoreConflictError {
constructor(previous_turn_id: string) {
super(
- `Previous turn ${previous_turn_id} is still running; freezeAndGetTurn must be called before creating a successor`,
+ `Previous turn ${previous_turn_id} is still non-terminal; freezeAndGetTurn must be called before creating a successor`,
);
this.name = 'PreviousTurnRunningError';
this.previous_turn_id = previous_turn_id;
diff --git a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
index b9ac5e04d..860143533 100644
--- a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
+++ b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
@@ -26,8 +26,10 @@ import {
makeCreateTurnInput,
makeDoneTurnState,
makeModelMessageEvent,
+ makePausedTurnState,
makeTurnCreatedEvent,
makeTurnDoneEvent,
+ makeTurnUpdateEvent,
TEST_ACTIVE_EXECUTOR_ID,
} from '../testHelpers';
@@ -72,7 +74,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
async function finishTurn(store: ISessionStore, turnId: string) {
const state = makeDoneTurnState();
- await store.updateTurnState({
+ await store.updateTurnTerminalState({
session_id: sessionId,
turn_id: turnId,
state,
@@ -106,7 +108,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
turn_done_event: makeTurnDoneEvent(makeCancelledTurnState(CancellationReason.ClientCancelled)),
}),
() =>
- store.updateTurnState({
+ store.updateTurnTerminalState({
...keys,
state: doneState,
turn_done_event: makeTurnDoneEvent(doneState),
@@ -1523,6 +1525,83 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
).rejects.toBeInstanceOf(PreviousTurnRunningError);
});
+ it('rejects createTurn when previous turn is paused, then counts metrics once after resume', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const pausedState = makePausedTurnState(['required-event-1']);
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: pausedState,
+ turn_update_event: makeTurnUpdateEvent(pausedState),
+ });
+
+ await expect(
+ store.createTurn(
+ makeCreateTurnInput({ sessionId, turnId: 'turn-2', previousTurnId: 'turn-1', firstTurnId: 'turn-1' }),
+ ),
+ ).rejects.toBeInstanceOf(PreviousTurnRunningError);
+ expect(await store.getTurn({ session_id: sessionId, turn_id: 'turn-2' })).toBeUndefined();
+ const afterReject = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
+ expect(afterReject.last_turn_id).toBe('turn-1');
+ expect(afterReject.metrics.total_turns).toBe(1);
+
+ const runningState = { status: 'running' } as const;
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: runningState,
+ turn_update_event: makeTurnUpdateEvent(runningState),
+ });
+ const turn1 = mustGet(await store.getTurn({ session_id: sessionId, turn_id: 'turn-1' }));
+ const doneState = {
+ ...makeDoneTurnState(),
+ completed_at: new Date(turn1.created_at.getTime() + 1500).toISOString(),
+ metrics: { total_cost_in_usd: 1.25 },
+ };
+ await store.updateTurnTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: doneState,
+ turn_done_event: makeTurnDoneEvent(doneState),
+ });
+
+ const session = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
+ expect(session.metrics).toEqual({
+ total_cost_in_usd: 1.25,
+ total_duration_ms: 1500,
+ total_turns: 1,
+ });
+ });
+
+ it('allows createTurn after a paused predecessor is frozen', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const pausedState = makePausedTurnState(['required-event-1']);
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: pausedState,
+ turn_update_event: makeTurnUpdateEvent(pausedState),
+ });
+ const cancelledState = makeCancelledTurnState(CancellationReason.CancelledForNextTurn);
+ await store.freezeAndGetTurn({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ reason: CancellationReason.CancelledForNextTurn,
+ turn_done_event: makeTurnDoneEvent(cancelledState),
+ });
+
+ await store.createTurn(
+ makeCreateTurnInput({ sessionId, turnId: 'turn-2', previousTurnId: 'turn-1', firstTurnId: 'turn-1' }),
+ );
+ const successor = mustGet(await store.getTurn({ session_id: sessionId, turn_id: 'turn-2' }));
+ expect(successor.state.status).toBe('running');
+ expect(successor.previous_turn_id).toBe('turn-1');
+ });
+
it('rejects duplicate turn_id with conflict', async () => {
const store = createStore();
await seedSession(store);
@@ -1867,6 +1946,146 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
}
});
+ it('cancels a paused turn, persists turn.done', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const pausedState = makePausedTurnState(['required-event-1']);
+ const turnUpdate = makeTurnUpdateEvent(pausedState);
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: pausedState,
+ turn_update_event: turnUpdate,
+ });
+
+ const cancelledState = makeCancelledTurnState(CancellationReason.CancelledForNextTurn);
+ const record = await store.freezeAndGetTurn({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ reason: CancellationReason.CancelledForNextTurn,
+ turn_done_event: makeTurnDoneEvent(cancelledState),
+ });
+ expect(record.state).toMatchObject({
+ status: 'cancelled',
+ reason: CancellationReason.CancelledForNextTurn,
+ });
+ if (record.state.status !== 'cancelled') {
+ throw new Error(`expected cancelled turn, got ${record.state.status}`);
+ }
+
+ const { data } = await store.listTurnEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ limit: 10,
+ page_token: undefined,
+ order: undefined,
+ });
+ expect(data).toContainEqual(turnUpdate);
+ expect(data.filter(event => event.type === EventType.TURN_DONE)).toHaveLength(1);
+
+ const afterCancel = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
+ const elapsed_ms = Date.parse(record.state.completed_at) - record.created_at.getTime();
+ expect(afterCancel.metrics).toEqual({
+ total_duration_ms: elapsed_ms > 0 ? Math.trunc(elapsed_ms) : 0,
+ total_turns: 1,
+ });
+ await store.freezeAndGetTurn({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ reason: CancellationReason.CancelledForNextTurn,
+ turn_done_event: makeTurnDoneEvent(cancelledState),
+ });
+ const afterSecond = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
+ expect(afterSecond.metrics).toEqual(afterCancel.metrics);
+ const afterSecondEvents = await store.listTurnEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ limit: 10,
+ page_token: undefined,
+ order: undefined,
+ });
+ expect(afterSecondEvents.data.filter(event => event.type === EventType.TURN_DONE)).toHaveLength(1);
+
+ const keys = { session_id: sessionId, turn_id: 'turn-1' };
+ const runningState = { status: 'running' } as const;
+ const doneState = makeDoneTurnState();
+ const fencedWrites: (() => Promise<unknown>)[] = [
+ () =>
+ store.updateTurnNonTerminalState({
+ ...keys,
+ state: runningState,
+ turn_update_event: makeTurnUpdateEvent(runningState),
+ }),
+ () =>
+ store.updateTurnTerminalState({
+ ...keys,
+ state: doneState,
+ turn_done_event: makeTurnDoneEvent(doneState),
+ }),
+ () =>
+ store.appendToEvents({
+ ...keys,
+ events: [makeTurnCreatedEvent('turn-1')],
+ }),
+ () =>
+ 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-overwrite')],
+ current_context_usage: getEmptyCurrentContextUsage(),
+ usage: getEmptyUsage(),
+ },
+ }),
+ () =>
+ 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: 'do work' },
+ completion: null,
+ capability_state: null,
+ },
+ ],
+ }),
+ () => store.removeThreads({ ...keys, thread_ids: [MAIN_THREAD_ID] }),
+ () =>
+ 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: { v: 1 },
+ }),
+ ];
+
+ for (const write of fencedWrites) {
+ await expect(write()).rejects.toBeInstanceOf(TurnNotRunningError);
+ }
+ });
+
it('cancels a running turn with the caller-supplied reason', async () => {
const store = createStore();
await seedSession(store);
@@ -1969,7 +2188,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
expect(data.filter(e => e.type === EventType.TURN_DONE)).toHaveLength(1);
});
- it('concurrent freeze x updateTurnState: exactly one terminal transition wins', async () => {
+ it('concurrent freeze x updateTurnTerminalState: exactly one terminal transition wins', async () => {
const store = createStore();
await seedSession(store);
await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
@@ -1982,7 +2201,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
reason: CancellationReason.CancelledForNextTurn,
turn_done_event: makeTurnDoneEvent(cancelledState),
}),
- store.updateTurnState({
+ store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-1',
state: doneState,
@@ -2009,7 +2228,130 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
});
});
- describe('updateTurnState', () => {
+ describe('updateTurnNonTerminalState', () => {
+ it('writes paused state and turn.update atomically without terminal metrics', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const metricsBeforePause = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId })).metrics;
+ const state = makePausedTurnState(['required-event-1']);
+ const turnUpdate = makeTurnUpdateEvent(state);
+
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state,
+ turn_update_event: turnUpdate,
+ });
+
+ const turn = mustGet(await store.getTurn({ session_id: sessionId, turn_id: 'turn-1' }));
+ expect(turn.state).toEqual(state);
+ const { data } = await store.listTurnEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ limit: 10,
+ page_token: undefined,
+ order: undefined,
+ });
+ expect(data).toContainEqual(turnUpdate);
+ expect(data.some(event => event.type === EventType.TURN_DONE)).toBe(false);
+
+ const session = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
+ expect(session.metrics).toEqual(metricsBeforePause);
+ });
+
+ it('writes paused → running and turn.update atomically without terminal metrics', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const pausedState = makePausedTurnState(['required-event-1']);
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: pausedState,
+ turn_update_event: makeTurnUpdateEvent(pausedState),
+ });
+ const metricsBeforeResume = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId })).metrics;
+
+ const runningState = { status: 'running' } as const;
+ const turnUpdate = makeTurnUpdateEvent(runningState);
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: runningState,
+ turn_update_event: turnUpdate,
+ });
+
+ const turn = mustGet(await store.getTurn({ session_id: sessionId, turn_id: 'turn-1' }));
+ expect(turn.state).toEqual(runningState);
+ const { data } = await store.listTurnEvents({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ limit: 10,
+ page_token: undefined,
+ order: undefined,
+ });
+ expect(data).toContainEqual(turnUpdate);
+ expect(data.some(event => event.type === EventType.TURN_DONE)).toBe(false);
+ const session = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
+ expect(session.metrics).toEqual(metricsBeforeResume);
+ });
+
+ it('allows a paused turn to be cancelled exactly once', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const pausedState = makePausedTurnState(['required-event-1']);
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: pausedState,
+ turn_update_event: makeTurnUpdateEvent(pausedState),
+ });
+
+ const cancelledState = makeCancelledTurnState(CancellationReason.ClientCancelled);
+ await store.updateTurnTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: cancelledState,
+ turn_done_event: makeTurnDoneEvent(cancelledState),
+ });
+
+ const turn = mustGet(await store.getTurn({ session_id: sessionId, turn_id: 'turn-1' }));
+ expect(turn.state).toEqual(cancelledState);
+ await expect(
+ store.updateTurnTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state: makeDoneTurnState(),
+ turn_done_event: makeTurnDoneEvent(makeDoneTurnState()),
+ }),
+ ).rejects.toBeInstanceOf(SessionStoreConflictError);
+ });
+
+ it('rejects a second pause transition', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const state = makePausedTurnState(['required-event-1']);
+ await store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state,
+ turn_update_event: makeTurnUpdateEvent(state),
+ });
+ await expect(
+ store.updateTurnNonTerminalState({
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ state,
+ turn_update_event: makeTurnUpdateEvent(state),
+ }),
+ ).rejects.toBeInstanceOf(SessionStoreInvariantError);
+ });
+ });
+
+ describe('updateTurnTerminalState', () => {
it('allows running → done and rejects second terminal (first-terminal-wins)', async () => {
const store = createStore();
await seedSession(store);
@@ -2017,7 +2359,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
await finishTurn(store, 'turn-1');
const cancelledState = makeCancelledTurnState(CancellationReason.ClientCancelled);
await expect(
- store.updateTurnState({
+ store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-1',
state: cancelledState,
@@ -2032,7 +2374,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
const state = makeDoneTurnState();
const turnDone = makeTurnDoneEvent(state);
- await store.updateTurnState({
+ await store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-1',
state,
@@ -2065,7 +2407,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
completed_at: completedAt,
metrics: { total_cost_in_usd: 1.25 },
};
- await store.updateTurnState({
+ await store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-1',
state,
@@ -2091,7 +2433,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
completed_at: completedAt,
metrics: { total_tokens: 10 },
};
- await store.updateTurnState({
+ await store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-1',
state,
@@ -2116,7 +2458,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
completed_at: new Date(createdAt.getTime() + 1500).toISOString(),
metrics: { total_cost_in_usd: 1.25 },
};
- await store.updateTurnState({
+ await store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-1',
state: doneState,
@@ -2130,7 +2472,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
metrics: { total_cost_in_usd: 9.99 },
};
await expect(
- store.updateTurnState({
+ store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-1',
state: losingState,
@@ -2157,7 +2499,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
completed_at: new Date(mustGet(turn1).created_at.getTime() + 1500).toISOString(),
metrics: { total_cost_in_usd: 1.25 },
};
- await store.updateTurnState({
+ await store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-1',
state: turn1Done,
@@ -2173,7 +2515,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
completed_at: new Date(mustGet(turn2).created_at.getTime() + 800).toISOString(),
metrics: { total_cost_in_usd: 0.5 },
};
- await store.updateTurnState({
+ await store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-2',
state: turn2Done,
@@ -2199,7 +2541,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
completed_at: new Date(mustGet(turn1).created_at.getTime() + 1000).toISOString(),
metrics: { total_cost_in_usd: 1.0 },
};
- await store.updateTurnState({
+ await store.updateTurnTerminalState({
session_id: sessionId,
turn_id: 'turn-1',
state: turn1Done,
@@ -2241,7 +2583,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
await seedSession(store);
const state = makeDoneTurnState();
await expect(
- store.updateTurnState({
+ store.updateTurnTerminalState({
session_id: sessionId,
turn_id: missingTurnId,
state,
diff --git a/packages/trueforge-core/tests/agent-session/testHelpers.ts b/packages/trueforge-core/tests/agent-session/testHelpers.ts
index e69a3f52e..ee10e586d 100644
--- a/packages/trueforge-core/tests/agent-session/testHelpers.ts
+++ b/packages/trueforge-core/tests/agent-session/testHelpers.ts
@@ -2,8 +2,13 @@ import { ulid } from 'ulid';
import type { ITurnResourceResolver } from '../../src/agent-session/ITurnResourceResolver';
import { MAIN_THREAD_ID, type TurnRecord } from '../../src/agent-session/models/TurnRecord';
import { AgentSpecSchema, type AgentSpec } from '../../src/agent-session/schemas/agentSpec';
-import { EventType } from '../../src/agent-session/schemas/events';
-import { CancellationReason, type TerminalTurnState } from '../../src/agent-session/schemas/turn';
+import { EventType, type TurnUpdateEvent } from '../../src/agent-session/schemas/events';
+import {
+ CancellationReason,
+ type NonTerminalTurnState,
+ type TerminalTurnState,
+ type TurnState,
+} from '../../src/agent-session/schemas/turn';
import type { CreateTurnInput, NewThreadInit, TurnContextAppend } from '../../src/agent-session/store/ISessionStore';
import { TurnResourceResolver } from '../../src/agent-session/TurnResourceResolver';
import type { AgentCapability } from '../../src/core/capabilities/AgentCapability';
@@ -154,6 +159,23 @@ export function makeTurnDoneEvent(state: TerminalTurnState) {
};
}
+export function makePausedTurnState(actionIds: string[] = [newEventId()]): Extract<TurnState, { status: 'paused' }> {
+ return {
+ status: 'paused',
+ action_required_on_events: actionIds.map(id => ({ id })),
+ };
+}
+
+export function makeTurnUpdateEvent(state: NonTerminalTurnState): TurnUpdateEvent {
+ return {
+ type: EventType.TURN_UPDATE,
+ id: newEventId(),
+ created_at: new Date().toISOString(),
+ state,
+ thread_id: null,
+ };
+}
+
const defaultRootThread: NewThreadInit = {
thread_id: MAIN_THREAD_ID,
parent: null,
diff --git a/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts b/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts
index 8be8112f7..f4aa5fde4 100644
--- a/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts
+++ b/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts
@@ -34,7 +34,8 @@ import type {
RemoveThreadsInput,
TurnRecordWithoutSnapshot,
UpdateSessionInput,
- UpdateTurnStateInput,
+ UpdateTurnNonTerminalStateInput,
+ UpdateTurnTerminalStateInput,
} from '@truefoundry/trueforge-core/agent-session/store/ISessionStore';
import {
decodeOffsetPageToken,
@@ -77,7 +78,8 @@ import {
freezeAndGetTurn as freezeAndGetTurnQuery,
getTurn as getTurnQuery,
listTurns as listTurnsQuery,
- updateTurnState as updateTurnStateQuery,
+ updateTurnNonTerminalState as updateTurnNonTerminalStateQuery,
+ updateTurnTerminalState as updateTurnTerminalStateQuery,
} from './queries/turns';
/** Prefix on session.agent_id when the SF agent is not yet imported locally. */
@@ -108,9 +110,10 @@ type TurnCustom = Record<string, never>;
*
* Hard invariants (violations proven by failing tests during prototyping —
* see the freeze/fence tests):
- * 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).
+ * 1. A turn cannot be used as `previous_turn_id` while it is still non-terminal
+ * (`running` or `paused`) — `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'`.
@@ -210,8 +213,12 @@ export class PostgresSessionStore implements ISessionStore<SessionCustom, TurnCu
return { data: result.turns, pagination };
}
- updateTurnState(input: UpdateTurnStateInput): Promise<void> {
- return updateTurnStateQuery(this.db, input);
+ updateTurnNonTerminalState(input: UpdateTurnNonTerminalStateInput): Promise<void> {
+ return updateTurnNonTerminalStateQuery(this.db, input);
+ }
+
+ updateTurnTerminalState(input: UpdateTurnTerminalStateInput): Promise<void> {
+ return updateTurnTerminalStateQuery(this.db, input);
}
appendToEvents(input: AppendToEventsInput): Promise<void> {
diff --git a/packages/trueforge/src/db/postgres/session-store/queries/turns.ts b/packages/trueforge/src/db/postgres/session-store/queries/turns.ts
index 4180945f8..497ef404b 100644
--- a/packages/trueforge/src/db/postgres/session-store/queries/turns.ts
+++ b/packages/trueforge/src/db/postgres/session-store/queries/turns.ts
@@ -1,6 +1,7 @@
import type { SessionMetrics } from '@truefoundry/trueforge-core/agent-session';
import type { TurnRecord, TurnSnapshot } from '@truefoundry/trueforge-core/agent-session/models/TurnRecord';
import {
+ isNonTerminalTurnState,
type TerminalTurnState,
type TurnInputItem,
type TurnState,
@@ -9,7 +10,8 @@ import { assertCreateTurnThreadDelta } from '@truefoundry/trueforge-core/agent-s
import type {
FreezeAndGetTurnInput,
TurnRecordWithoutSnapshot,
- UpdateTurnStateInput,
+ UpdateTurnNonTerminalStateInput,
+ UpdateTurnTerminalStateInput,
} from '@truefoundry/trueforge-core/agent-session/store/ISessionStore';
import {
PreviousTurnRunningError,
@@ -473,7 +475,7 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
const first = prevRows[0];
if (first !== undefined) {
- if (first.turn_state.status === 'running') {
+ if (isNonTerminalTurnState(first.turn_state)) {
throw new PreviousTurnRunningError(prevTurnId);
}
prevCheckpoint = first.turn_checkpoint;
@@ -642,7 +644,7 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
}
/**
- * freezeAndGetTurn — cancel if still running (fencing future writes), then return the record.
+ * freezeAndGetTurn — cancel if still non-terminal (running or paused), then return the record.
* Terminal turns are returned unchanged (freeze is a plain read).
*/
export async function freezeAndGetTurn(db: Kysely<Database>, input: FreezeAndGetTurnInput): Promise<TurnRecord> {
@@ -663,7 +665,7 @@ export async function freezeAndGetTurn(db: Kysely<Database>, input: FreezeAndGet
})
.where('session_id', '=', input.session_id)
.where('turn_id', '=', input.turn_id)
- .where(sql<boolean>`state->>'status' = 'running'`)
+ .where(sql<boolean>`state->>'status' IN ('running', 'paused')`)
.returning(['created_at'])
.executeTakeFirst();
@@ -745,11 +747,62 @@ export async function listTurns(db: Kysely<Database>, input: ListTurnsInput): Pr
};
}
-/**
- * updateTurnState — conditional on state->>'status'='running'.
- * 0 rows → SELECT by PK → missing NotFound, present Conflict (first terminal write wins).
- */
-export async function updateTurnState(db: Kysely<Database>, input: UpdateTurnStateInput): Promise<void> {
+/** Atomically transitions running ↔ paused and appends turn.update. */
+export async function updateTurnNonTerminalState(
+ db: Kysely<Database>,
+ input: UpdateTurnNonTerminalStateInput,
+): Promise<void> {
+ await db.transaction().execute(async trx => {
+ const expectedSourceStatus = input.state.status === 'paused' ? 'running' : 'paused';
+ const result = await trx
+ .updateTable('turn')
+ .set({
+ state: input.state,
+ updated_at: sql`now()`,
+ })
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .where(sql<boolean>`state->>'status' = ${expectedSourceStatus}`)
+ .returning('turn_id')
+ .executeTakeFirst();
+
+ if (result === undefined) {
+ const existing = await trx
+ .selectFrom('turn')
+ .select('state')
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .executeTakeFirst();
+
+ if (!existing) {
+ throw new TurnNotFoundError(input.turn_id);
+ }
+ if (isNonTerminalTurnState(existing.state)) {
+ throw new SessionStoreInvariantError(
+ `expected ${expectedSourceStatus} state for turn ${input.turn_id}, got ${existing.state.status}`,
+ );
+ }
+ throw new TurnNotRunningError(input.turn_id, terminalTurnState(existing.state, input.turn_id));
+ }
+
+ await trx
+ .insertInto('session_event')
+ .values({
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: input.turn_update_event.id,
+ event: json(input.turn_update_event),
+ created_at: new Date(input.turn_update_event.created_at),
+ })
+ .execute();
+ });
+}
+
+/** Atomically transitions a non-terminal turn to terminal and appends turn.done. */
+export async function updateTurnTerminalState(
+ db: Kysely<Database>,
+ input: UpdateTurnTerminalStateInput,
+): Promise<void> {
await db.transaction().execute(async trx => {
const result = await trx
.updateTable('turn')
@@ -759,11 +812,10 @@ export async function updateTurnState(db: Kysely<Database>, input: UpdateTurnSta
})
.where('session_id', '=', input.session_id)
.where('turn_id', '=', input.turn_id)
- .where(sql<boolean>`state->>'status' = 'running'`)
+ .where(sql<boolean>`state->>'status' IN ('running', 'paused')`)
.returning(['created_at'])
.executeTakeFirst();
- // No RETURNING row: UPDATE matched 0 running turns.
if (result === undefined) {
const existing = await trx
.selectFrom('turn')
diff --git a/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts b/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts
index 57b4fe3b5..0bd5d876e 100644
--- a/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts
+++ b/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts
@@ -27,7 +27,8 @@ import type {
RemoveThreadsInput,
TurnRecordWithoutSnapshot,
UpdateSessionInput,
- UpdateTurnStateInput,
+ UpdateTurnNonTerminalStateInput,
+ UpdateTurnTerminalStateInput,
} from '@truefoundry/trueforge-core/agent-session/store/ISessionStore';
import {
decodeOffsetPageToken,
@@ -65,7 +66,8 @@ import {
freezeAndGetTurn as freezeAndGetTurnQuery,
getTurn as getTurnQuery,
listTurns as listTurnsQuery,
- updateTurnState as updateTurnStateQuery,
+ updateTurnNonTerminalState as updateTurnNonTerminalStateQuery,
+ updateTurnTerminalState as updateTurnTerminalStateQuery,
} from './queries/turns';
type SessionCustom = Record<string, never>;
@@ -83,8 +85,9 @@ type TurnCustom = Record<string, never>;
* late appends touch only its OWN rows — structural leaks are impossible.
*
* Hard invariants:
- * 1. A turn cannot be used as `previous_turn_id` while it is still `running` —
- * `createTurn` rejects that; callers must `freezeAndGetTurn` first.
+ * 1. A turn cannot be used as `previous_turn_id` while it is still non-terminal
+ * (`running` or `paused`) — `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'`.
@@ -185,8 +188,12 @@ export class SqliteSessionStore implements ISessionStore<SessionCustom, TurnCust
return { data: result.turns, pagination };
}
- updateTurnState(input: UpdateTurnStateInput): Promise<void> {
- return updateTurnStateQuery(this.db, input);
+ updateTurnNonTerminalState(input: UpdateTurnNonTerminalStateInput): Promise<void> {
+ return updateTurnNonTerminalStateQuery(this.db, input);
+ }
+
+ updateTurnTerminalState(input: UpdateTurnTerminalStateInput): Promise<void> {
+ return updateTurnTerminalStateQuery(this.db, input);
}
appendToEvents(input: AppendToEventsInput): Promise<void> {
diff --git a/packages/trueforge/src/db/sqlite/session-store/queries/turns.ts b/packages/trueforge/src/db/sqlite/session-store/queries/turns.ts
index 160558471..2bf01faf4 100644
--- a/packages/trueforge/src/db/sqlite/session-store/queries/turns.ts
+++ b/packages/trueforge/src/db/sqlite/session-store/queries/turns.ts
@@ -1,6 +1,7 @@
import type { SessionMetrics } from '@truefoundry/trueforge-core/agent-session';
import type { TurnRecord, TurnSnapshot } from '@truefoundry/trueforge-core/agent-session/models/TurnRecord';
import {
+ isNonTerminalTurnState,
type TerminalTurnState,
type TurnInputItem,
type TurnState,
@@ -9,7 +10,8 @@ import { assertCreateTurnThreadDelta } from '@truefoundry/trueforge-core/agent-s
import type {
FreezeAndGetTurnInput,
TurnRecordWithoutSnapshot,
- UpdateTurnStateInput,
+ UpdateTurnNonTerminalStateInput,
+ UpdateTurnTerminalStateInput,
} from '@truefoundry/trueforge-core/agent-session/store/ISessionStore';
import {
PreviousTurnRunningError,
@@ -425,7 +427,7 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
const first = prevRows[0];
if (first !== undefined) {
- if (first.turn_state.status === 'running') {
+ if (isNonTerminalTurnState(first.turn_state)) {
throw new PreviousTurnRunningError(prevTurnId);
}
prevCheckpoint = first.turn_checkpoint;
@@ -686,7 +688,7 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
}
/**
- * freezeAndGetTurn — cancel if still running, then return the assembled record.
+ * freezeAndGetTurn — cancel if still non-terminal (running or paused), then return the assembled record.
* Terminal turns are returned unchanged (freeze is a plain read).
*/
export async function freezeAndGetTurn(db: Kysely<Database>, input: FreezeAndGetTurnInput): Promise<TurnRecord> {
@@ -705,7 +707,7 @@ export async function freezeAndGetTurn(db: Kysely<Database>, input: FreezeAndGet
})
.where('session_id', '=', input.session_id)
.where('turn_id', '=', input.turn_id)
- .where(sql<boolean>`state->>'status' = 'running'`)
+ .where(sql<boolean>`state->>'status' IN ('running', 'paused')`)
.returning(['created_at'])
.executeTakeFirst();
@@ -797,11 +799,62 @@ export async function listTurns(db: Kysely<Database>, input: ListTurnsInput): Pr
};
}
-/**
- * updateTurnState — conditional on state->>'status'='running'.
- * 0 rows → SELECT by PK → missing NotFound, present Conflict (first terminal write wins).
- */
-export async function updateTurnState(db: Kysely<Database>, input: UpdateTurnStateInput): Promise<void> {
+/** Atomically transitions running ↔ paused and appends turn.update. */
+export async function updateTurnNonTerminalState(
+ db: Kysely<Database>,
+ input: UpdateTurnNonTerminalStateInput,
+): Promise<void> {
+ await db.transaction().execute(async trx => {
+ const expectedSourceStatus = input.state.status === 'paused' ? 'running' : 'paused';
+ const result = await trx
+ .updateTable('turn')
+ .set({
+ state: jsonbBind(input.state),
+ updated_at: nowIso(),
+ })
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .where(sql<boolean>`state->>'status' = ${expectedSourceStatus}`)
+ .returning('turn_id')
+ .executeTakeFirst();
+
+ if (result === undefined) {
+ const existing = await trx
+ .selectFrom('turn')
+ .select([jsonText<TurnState>(sql.ref('state')).as('state')])
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .executeTakeFirst();
+
+ if (!existing) {
+ throw new TurnNotFoundError(input.turn_id);
+ }
+ if (isNonTerminalTurnState(existing.state)) {
+ throw new SessionStoreInvariantError(
+ `expected ${expectedSourceStatus} state for turn ${input.turn_id}, got ${existing.state.status}`,
+ );
+ }
+ throw new TurnNotRunningError(input.turn_id, terminalTurnState(existing.state, input.turn_id));
+ }
+
+ await trx
+ .insertInto('session_event')
+ .values({
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: input.turn_update_event.id,
+ event: jsonbBind(input.turn_update_event),
+ created_at: input.turn_update_event.created_at,
+ })
+ .execute();
+ });
+}
+
+/** Atomically transitions a non-terminal turn to terminal and appends turn.done. */
+export async function updateTurnTerminalState(
+ db: Kysely<Database>,
+ input: UpdateTurnTerminalStateInput,
+): Promise<void> {
await db.transaction().execute(async trx => {
const result = await trx
.updateTable('turn')
@@ -811,11 +864,10 @@ export async function updateTurnState(db: Kysely<Database>, input: UpdateTurnSta
})
.where('session_id', '=', input.session_id)
.where('turn_id', '=', input.turn_id)
- .where(sql<boolean>`state->>'status' = 'running'`)
+ .where(sql<boolean>`state->>'status' IN ('running', 'paused')`)
.returning(['created_at'])
.executeTakeFirst();
- // No RETURNING row: UPDATE matched 0 running turns.
if (result === undefined) {
const existing = await trx
.selectFrom('turn')
diff --git a/packages/trueforge/tests/db/session-metrics/metricsContractSuite.ts b/packages/trueforge/tests/db/session-metrics/metricsContractSuite.ts
index a3d1fdab1..46d865e0e 100644
--- a/packages/trueforge/tests/db/session-metrics/metricsContractSuite.ts
+++ b/packages/trueforge/tests/db/session-metrics/metricsContractSuite.ts
@@ -53,7 +53,7 @@ export function runSessionMetricsStoreContractSuite(
completed_at: new Date(turn.created_at.getTime() + 1500).toISOString(),
metrics: { total_cost_in_usd: 1.25 },
};
- await sessionStore.updateTurnState({
+ await sessionStore.updateTurnTerminalState({
session_id: 'metrics-session',
turn_id: 'metrics-turn',
state,
@@ -144,7 +144,7 @@ export function runSessionMetricsStoreContractSuite(
...makeDoneTurnState(),
completed_at: new Date(turn.created_at.getTime() + durationMs).toISOString(),
};
- await sessionStore.updateTurnState({
+ await sessionStore.updateTurnTerminalState({
session_id: definition.id,
turn_id: turnId,
state,
@@ -204,7 +204,7 @@ export function runSessionMetricsStoreContractSuite(
...makeDoneTurnState(),
completed_at: new Date(turn.created_at.getTime() + 2000).toISOString(),
};
- await sessionStore.updateTurnState({
+ await sessionStore.updateTurnTerminalState({
session_id: 'completed-session',
turn_id: 'completed-turn',
state,