Skip to content

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

Add SQLite session storage with shared contract coverage.

debajyoti-truefoundry39a2c62f92ce
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 78af1ade2..d95fc66c2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -74,7 +74,7 @@ jobs:
uses: actions/checkout@v4
- name: Detect session-store path changes
- uses: dorny/paths-filter@v3
+ uses: dorny/paths-filter@v4
id: filter
with:
filters: |
@@ -82,6 +82,7 @@ jobs:
- 'packages/server/src/db/**'
- 'packages/server/tsup.config.ts'
- 'packages/server/tests/**'
+ - 'packages/server/jest.store.postgres.config.cjs'
- 'packages/harness/src/agent-session/**'
- 'packages/harness/tests/agent-session/**'
@@ -112,4 +113,57 @@ jobs:
if: steps.filter.outputs.store == 'true'
env:
SESSION_STORE_TEST_PG_URL: postgres://proto:proto@localhost:55432/proto
- run: pnpm --dir packages/server test:store
+ run: pnpm --dir packages/server test:store:postgres
+
+ sqlite-store-tests:
+ name: SQLite Session Store Tests
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ permissions:
+ contents: read
+ pull-requests: read
+
+ steps:
+ - name: Check out repository code
+ uses: actions/checkout@v4
+
+ - name: Detect session-store path changes
+ uses: dorny/paths-filter@v4
+ id: filter
+ with:
+ filters: |
+ store:
+ - 'packages/server/src/db/**'
+ - 'packages/server/tsup.config.ts'
+ - 'packages/server/tests/**'
+ - 'packages/server/jest.store.sqlite.config.cjs'
+ - 'packages/harness/src/agent-session/**'
+ - 'packages/harness/tests/agent-session/**'
+ - 'pnpm-workspace.yaml'
+
+ - name: Skip — no session-store changes
+ if: steps.filter.outputs.store != 'true'
+ run: echo "No session-store paths changed; skipping SQLite store tests."
+
+ - name: Setup pnpm
+ if: steps.filter.outputs.store == 'true'
+ uses: pnpm/action-setup@v4
+
+ - name: Setup Node.js
+ if: steps.filter.outputs.store == 'true'
+ uses: actions/setup-node@v4
+ with:
+ node-version: '24'
+ cache: 'pnpm'
+
+ - name: Install dependencies
+ if: steps.filter.outputs.store == 'true'
+ run: pnpm install --frozen-lockfile
+
+ - name: Build
+ if: steps.filter.outputs.store == 'true'
+ run: pnpm build
+
+ - name: SQLite session store contract tests
+ if: steps.filter.outputs.store == 'true'
+ run: pnpm --dir packages/server test:store:sqlite
diff --git a/package.json b/package.json
index 50c58de8e..8f8974886 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,7 @@
"format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,md}\" --cache --error-on-unmatched-pattern --config .prettierrc",
"format:fix": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md}\" --cache --config .prettierrc",
"test": "pnpm --filter @truefoundry/utils test && pnpm --filter @truefoundry/server test && pnpm --filter frontend test",
- "test:store:local": "bash scripts/test-store-with-postgres.sh",
+ "test:store:local": "bash scripts/test-store-local.sh",
"dev": "pnpm --parallel --filter @truefoundry/server --filter frontend dev",
"dev:server": "pnpm --filter @truefoundry/server dev",
"dev:frontend": "pnpm --filter frontend dev",
diff --git a/packages/harness/src/agent-session/SessionHandle.ts b/packages/harness/src/agent-session/SessionHandle.ts
index d83b75e95..759db0c49 100644
--- a/packages/harness/src/agent-session/SessionHandle.ts
+++ b/packages/harness/src/agent-session/SessionHandle.ts
@@ -234,7 +234,7 @@ export class SessionHandle<
const new_context_appends = await collectContextAppends(orchestrator.send(sendBatch));
const turnId = input.turn_id;
- const now = new Date().toISOString();
+ const now = new Date();
const new_threads: NewThreadInit[] = [];
if (!previous) {
diff --git a/packages/harness/src/agent-session/TurnHandle.ts b/packages/harness/src/agent-session/TurnHandle.ts
index f051583be..67ab183d8 100644
--- a/packages/harness/src/agent-session/TurnHandle.ts
+++ b/packages/harness/src/agent-session/TurnHandle.ts
@@ -139,7 +139,7 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
return this.turn.state;
}
- get created_at(): string {
+ get created_at(): Date {
return this.turn.created_at;
}
@@ -206,7 +206,7 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
previous_turn_id: this.turn.previous_turn_id,
...(this.turn.input.length > 0 ? { input: this.turn.input } : {}),
state: { status: 'running' },
- created_at: this.turn.created_at,
+ created_at: this.turn.created_at.toISOString(),
thread_id: null,
};
await this.store.appendToEvents({
@@ -236,16 +236,17 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
await generator.return(emptyResult);
// Cleared so the finally block does not close the generator a second time.
generator = undefined;
- const createdAt = new Date().toISOString();
+ const updatedAt = new Date();
+ const createdAtIso = updatedAt.toISOString();
const state: TerminalTurnState = {
...error.state,
metrics: turnMetricsFromAgentThreadMetrics(orchestrator.getMetrics()),
};
- this.turn = { ...this.turn, state, updated_at: createdAt };
+ this.turn = { ...this.turn, state, updated_at: updatedAt };
yield {
type: EventType.TURN_DONE,
id: newEventId(),
- created_at: createdAt,
+ created_at: createdAtIso,
state,
thread_id: null,
};
@@ -267,28 +268,29 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
await generator.return(emptyResult);
}
- const createdAt = new Date().toISOString();
+ const updatedAt = new Date();
+ const createdAtIso = updatedAt.toISOString();
const metrics = turnMetricsFromAgentThreadMetrics(orchestrator.getMetrics());
let terminalState: TerminalTurnState;
if (signal.aborted) {
terminalState = {
status: 'cancelled',
reason: cancellationReasonFromAbortReason(signal.reason),
- completed_at: createdAt,
+ completed_at: createdAtIso,
metrics,
};
} else if (caughtError) {
terminalState = {
status: 'error',
message: caughtError.message,
- completed_at: createdAt,
+ completed_at: createdAtIso,
metrics,
};
} else if (executeResult?.root_agent_error) {
terminalState = {
status: 'error',
message: executeResult.root_agent_error.error,
- completed_at: createdAt,
+ completed_at: createdAtIso,
metrics,
};
} else if (executeResult === undefined) {
@@ -297,7 +299,7 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
terminalState = {
status: 'cancelled',
reason: CancellationReason.ClientCancelled,
- completed_at: createdAt,
+ completed_at: createdAtIso,
metrics,
};
} else {
@@ -306,7 +308,7 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
// TODO: revert alongside TurnStateDone.output.
...(executeResult.output && { output: executeResult.output }),
required_actions: executeResult.required_actions,
- completed_at: createdAt,
+ completed_at: createdAtIso,
metrics,
};
}
@@ -314,7 +316,7 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
const turnDone: TurnDoneEvent = {
type: EventType.TURN_DONE,
id: newEventId(),
- created_at: createdAt,
+ created_at: createdAtIso,
state: terminalState,
thread_id: null,
};
@@ -328,18 +330,18 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {
state: terminalState,
turn_done_event: turnDone,
});
- this.turn = { ...this.turn, state: terminalState, updated_at: createdAt };
+ this.turn = { ...this.turn, state: terminalState, updated_at: updatedAt };
} catch (persistError) {
if (persistError instanceof TurnNotRunningError) {
const state: TerminalTurnState = { ...persistError.state, metrics };
- this.turn = { ...this.turn, state, updated_at: createdAt };
+ this.turn = { ...this.turn, state, updated_at: updatedAt };
await resolver.close().catch(() => {
/* no-op */
});
yield {
type: EventType.TURN_DONE,
id: newEventId(),
- created_at: createdAt,
+ created_at: createdAtIso,
state,
thread_id: null,
};
diff --git a/packages/harness/src/agent-session/index.ts b/packages/harness/src/agent-session/index.ts
index c326d5faf..c60c42f2b 100644
--- a/packages/harness/src/agent-session/index.ts
+++ b/packages/harness/src/agent-session/index.ts
@@ -47,6 +47,7 @@ export type { SessionRecord } from './models/SessionRecord';
export { MAIN_THREAD_ID } from './models/TurnRecord';
export type { TurnRecord, TurnSnapshot } from './models/TurnRecord';
+export { assertCreateTurnThreadDelta } from './store/assertCreateTurnThreadDelta';
export { InMemorySessionStore } from './store/InMemorySessionStore';
export type {
AddThreadsInput,
diff --git a/packages/harness/src/agent-session/models/SessionRecord.ts b/packages/harness/src/agent-session/models/SessionRecord.ts
index 01d683e78..5e7134172 100644
--- a/packages/harness/src/agent-session/models/SessionRecord.ts
+++ b/packages/harness/src/agent-session/models/SessionRecord.ts
@@ -22,10 +22,10 @@ export interface SessionRecord<TCustom extends object = Record<string, never>> {
* listing anchors. Advanced only by `createTurn` (atomic link).
*/
last_turn_id: string | null;
- /** ISO-8601 UTC datetime string (for example, `2026-07-24T02:45:00.000Z`). */
- created_at: string;
- /** ISO-8601 UTC datetime string (for example, `2026-07-24T02:45:00.000Z`). */
- updated_at: string;
+ /** Instant the session was created (store domain). Wire/API serialize as ISO-8601. */
+ created_at: Date;
+ /** Instant the session was last updated (store domain). Wire/API serialize as ISO-8601. */
+ updated_at: Date;
/**
* Liveness clock (ms since epoch). The store bumps it on createSession,
* updateSession, and createTurn — never on reads.
diff --git a/packages/harness/src/agent-session/models/TurnRecord.ts b/packages/harness/src/agent-session/models/TurnRecord.ts
index bd72122a6..5c9502e7b 100644
--- a/packages/harness/src/agent-session/models/TurnRecord.ts
+++ b/packages/harness/src/agent-session/models/TurnRecord.ts
@@ -31,9 +31,9 @@ export interface TurnRecord<TCustom extends object = Record<string, never>> {
state: TurnState;
input: TurnInputItem[];
snapshot: TurnSnapshot;
- /** ISO-8601 UTC datetime string (for example, `2026-07-24T02:45:00.000Z`). */
- created_at: string;
- /** ISO-8601 UTC datetime string (for example, `2026-07-24T02:45:00.000Z`). */
- updated_at: string;
+ /** Instant the turn was created (store domain). Wire/API serialize as ISO-8601. */
+ created_at: Date;
+ /** Instant the turn was last updated (store domain). Wire/API serialize as ISO-8601. */
+ updated_at: Date;
custom: TCustom | null;
}
diff --git a/packages/harness/src/agent-session/store/ISessionStore.ts b/packages/harness/src/agent-session/store/ISessionStore.ts
index 5ba533060..00b764bdd 100644
--- a/packages/harness/src/agent-session/store/ISessionStore.ts
+++ b/packages/harness/src/agent-session/store/ISessionStore.ts
@@ -40,8 +40,10 @@ export interface ListSessionsInput {
limit: number;
page_token: string | undefined;
order: 'asc' | 'desc' | undefined;
- start_timestamp: string | undefined;
- end_timestamp: string | undefined;
+ /** Inclusive lower bound on `created_at` (instant). */
+ start_timestamp: Date | undefined;
+ /** Inclusive upper bound on `created_at` (instant). */
+ end_timestamp: Date | undefined;
}
/** Turn row fields without assembled snapshot (create input / listTurns). */
@@ -233,7 +235,7 @@ export interface ISessionStore<
/**
* Paginated list of the tenant's sessions ordered by `created_at`
* (`order` defaults to `desc`). `start_timestamp` / `end_timestamp` are
- * inclusive ISO-8601 bounds on `created_at`.
+ * inclusive instant bounds on `created_at`.
* Does **not** bump `last_activity_timestamp_ms` (read path).
*/
listSessions(
diff --git a/packages/harness/src/agent-session/store/InMemorySessionStore.ts b/packages/harness/src/agent-session/store/InMemorySessionStore.ts
index b3b808fb1..042b0c394 100644
--- a/packages/harness/src/agent-session/store/InMemorySessionStore.ts
+++ b/packages/harness/src/agent-session/store/InMemorySessionStore.ts
@@ -5,6 +5,7 @@ import type { TurnRecord, TurnSnapshot } from '../models/TurnRecord';
import type { PersistedTurnEvent, SessionEventItem } from '../schemas/events';
import type { TokenPagination } from '../schemas/pagination';
import { CancellationReason, type TerminalTurnState } from '../schemas/turn';
+import { assertCreateTurnThreadDelta } from './assertCreateTurnThreadDelta';
import type {
AddThreadsInput,
AppendToEventsInput,
@@ -102,40 +103,25 @@ function buildSnapshotFromDelta(input: {
? deepCopy(input.previousSnapshot.threads)
: {};
+ assertCreateTurnThreadDelta({
+ previousThreadIds: new Set(Object.keys(threads)),
+ new_threads: input.new_threads,
+ new_context_appends: input.new_context_appends,
+ capability_states: input.capability_states,
+ });
+
for (const nt of input.new_threads) {
- if (threads[nt.thread_id] !== undefined) {
- throw new SessionStoreInvariantError(
- `new_threads must only contain threads absent on the previous turn; thread '${nt.thread_id}' already exists`,
- );
- }
threads[nt.thread_id] = newThreadSnapshot(nt);
}
- const knownThreadIds = new Set(Object.keys(threads));
- for (const append of input.new_context_appends) {
- if (!knownThreadIds.has(append.thread_id)) {
- throw new SessionStoreInvariantError(`new_context_appends references unknown thread ${append.thread_id}`);
- }
- }
-
applyContextAppends(threads, input.new_context_appends);
- const seenCapabilityThreads = new Set<string>();
for (const capability of input.capability_states) {
const thread = threads[capability.thread_id];
if (thread === undefined) {
throw new SessionStoreInvariantError(`capability_states references unknown thread ${capability.thread_id}`);
}
- if (seenCapabilityThreads.has(capability.thread_id)) {
- throw new SessionStoreInvariantError(`capability_states contains duplicate thread ${capability.thread_id}`);
- }
- seenCapabilityThreads.add(capability.thread_id);
thread.capability_state = deepCopy(capability.capability_state);
}
- for (const threadId of Object.keys(threads)) {
- if (!seenCapabilityThreads.has(threadId)) {
- throw new SessionStoreInvariantError(`capability_states is missing thread ${threadId}`);
- }
- }
return {
threads,
@@ -174,7 +160,7 @@ export class InMemorySessionStore<
if (this.sessions.has(key)) {
throw new SessionAlreadyExistsError(input.session_id);
}
- const now = new Date().toISOString();
+ const now = new Date();
const record: SessionRecord<TSessionCustom> = {
tenant_id: input.tenant_id,
session_id: input.session_id,
@@ -208,7 +194,7 @@ export class InMemorySessionStore<
stored.record.title = input.title;
}
const now = Date.now();
- stored.record.updated_at = new Date(now).toISOString();
+ stored.record.updated_at = new Date(now);
stored.record.last_activity_timestamp_ms = now;
return;
}
@@ -220,13 +206,15 @@ export class InMemorySessionStore<
const records: SessionRecord<TSessionCustom>[] = [];
for (const [key, stored] of this.sessions) {
if (!key.startsWith(prefix)) continue;
- const createdAt = stored.record.created_at;
- if (input.start_timestamp !== undefined && createdAt < input.start_timestamp) continue;
- if (input.end_timestamp !== undefined && createdAt > input.end_timestamp) continue;
+ const createdAt = stored.record.created_at.getTime();
+ if (input.start_timestamp !== undefined && createdAt < input.start_timestamp.getTime()) continue;
+ if (input.end_timestamp !== undefined && createdAt > input.end_timestamp.getTime()) continue;
records.push(stored.record);
}
records.sort((a, b) =>
- input.order === 'asc' ? a.created_at.localeCompare(b.created_at) : b.created_at.localeCompare(a.created_at),
+ input.order === 'asc'
+ ? a.created_at.getTime() - b.created_at.getTime()
+ : b.created_at.getTime() - a.created_at.getTime(),
);
const page = paginate(records, input.limit, input.page_token);
return { data: deepCopy(page.data), pagination: page.pagination };
@@ -279,7 +267,7 @@ export class InMemorySessionStore<
stored.turnIds.push(input.turn.turn_id);
stored.record.last_turn_id = input.turn.turn_id;
stored.record.last_activity_timestamp_ms = Date.now();
- stored.record.updated_at = new Date().toISOString();
+ stored.record.updated_at = new Date();
if (input.update_session_title_if_not_exist !== null && stored.record.title === null) {
stored.record.title = input.update_session_title_if_not_exist;
}
@@ -299,7 +287,7 @@ export class InMemorySessionStore<
completed_at: new Date().toISOString(),
};
turn.state = cancelledState;
- turn.updated_at = new Date().toISOString();
+ turn.updated_at = new Date();
const list = this.events.get(tKey);
if (list) {
list.push(deepCopy(input.turn_done_event));
@@ -344,7 +332,7 @@ export class InMemorySessionStore<
throw new TurnNotRunningError(input.turn_id, turn.state);
}
turn.state = deepCopy(input.state);
- turn.updated_at = new Date().toISOString();
+ turn.updated_at = new Date();
const list = this.events.get(tKey);
if (list) {
list.push(deepCopy(input.turn_done_event));
@@ -383,16 +371,19 @@ export class InMemorySessionStore<
for (const thread of input.threads) {
turn.snapshot.threads[thread.thread_id] = deepCopy(thread);
}
- turn.updated_at = new Date().toISOString();
+ turn.updated_at = new Date();
return;
}
async removeThreads(input: RemoveThreadsInput): Promise<void> {
+ if (input.thread_ids.length === 0) {
+ return;
+ }
const turn = this.requireRunningTurn(input.tenant_id, input.session_id, input.turn_id);
for (const id of input.thread_ids) {
Reflect.deleteProperty(turn.snapshot.threads, id);
}
- turn.updated_at = new Date().toISOString();
+ turn.updated_at = new Date();
return;
}
@@ -409,7 +400,7 @@ export class InMemorySessionStore<
if (input.completion !== null) {
thread.completion = deepCopy(input.completion);
}
- turn.updated_at = new Date().toISOString();
+ turn.updated_at = new Date();
return;
}
@@ -422,7 +413,7 @@ export class InMemorySessionStore<
}
thread.context = deepCopy(input.event.context);
thread.current_context_usage = deepCopy(input.event.current_context_usage);
- turn.updated_at = new Date().toISOString();
+ turn.updated_at = new Date();
return;
}
@@ -432,14 +423,14 @@ export class InMemorySessionStore<
for (const server of input.mcp_servers) {
turn.snapshot.mcp_servers[server.id] = deepCopy(server);
}
- turn.updated_at = new Date().toISOString();
+ turn.updated_at = new Date();
return;
}
async patchSandboxInfo(input: PatchSandboxInfoInput): Promise<void> {
const turn = this.requireRunningTurn(input.tenant_id, input.session_id, input.turn_id);
turn.snapshot.sandbox_info = deepCopy(input.sandbox_info);
- turn.updated_at = new Date().toISOString();
+ turn.updated_at = new Date();
return;
}
@@ -458,7 +449,7 @@ export class InMemorySessionStore<
} else {
thread.capability_state[input.key] = deepCopy(input.state);
}
- turn.updated_at = new Date().toISOString();
+ turn.updated_at = new Date();
return;
}
diff --git a/packages/harness/src/agent-session/store/SessionStoreErrors.ts b/packages/harness/src/agent-session/store/SessionStoreErrors.ts
index 2caa95164..3bffa80b6 100644
--- a/packages/harness/src/agent-session/store/SessionStoreErrors.ts
+++ b/packages/harness/src/agent-session/store/SessionStoreErrors.ts
@@ -2,24 +2,24 @@ import type { TerminalTurnState } from '../schemas/turn';
/** Store conflict (e.g. first-terminal-wins violation, concurrent createTurn). */
export abstract class SessionStoreConflictError extends Error {
- constructor(message: string) {
- super(message);
+ constructor(message: string, options?: ErrorOptions) {
+ super(message, options);
this.name = 'SessionStoreConflictError';
}
}
/** Store not-found (session or turn missing). */
export abstract class SessionStoreNotFoundError extends Error {
- constructor(message: string) {
- super(message);
+ constructor(message: string, options?: ErrorOptions) {
+ super(message, options);
this.name = 'SessionStoreNotFoundError';
}
}
/** Implementation bug or thread misuse — not mapped to 4xx by API handlers. */
export class SessionStoreInvariantError extends Error {
- constructor(message: string) {
- super(message);
+ constructor(message: string, options?: ErrorOptions) {
+ super(message, options);
this.name = 'SessionStoreInvariantError';
}
}
@@ -47,8 +47,8 @@ export class TurnNotFoundError extends SessionStoreNotFoundError {
export class SessionAlreadyExistsError extends SessionStoreConflictError {
readonly session_id: string;
- constructor(session_id: string) {
- super(`Session already exists: ${session_id}`);
+ constructor(session_id: string, options?: ErrorOptions) {
+ super(`Session already exists: ${session_id}`, options);
this.name = 'SessionAlreadyExistsError';
this.session_id = session_id;
}
@@ -57,8 +57,8 @@ export class SessionAlreadyExistsError extends SessionStoreConflictError {
export class TurnAlreadyExistsError extends SessionStoreConflictError {
readonly turn_id: string;
- constructor(turn_id: string) {
- super(`Turn already exists: ${turn_id}`);
+ constructor(turn_id: string, options?: ErrorOptions) {
+ super(`Turn already exists: ${turn_id}`, options);
this.name = 'TurnAlreadyExistsError';
this.turn_id = turn_id;
}
diff --git a/packages/harness/src/agent-session/store/assertCreateTurnThreadDelta.ts b/packages/harness/src/agent-session/store/assertCreateTurnThreadDelta.ts
new file mode 100644
index 000000000..1c260b45c
--- /dev/null
+++ b/packages/harness/src/agent-session/store/assertCreateTurnThreadDelta.ts
@@ -0,0 +1,52 @@
+import { SessionStoreInvariantError } from './SessionStoreErrors';
+
+/**
+ * Pure createTurn thread-graph checks shared by all ISessionStore backends.
+ * Call after previous-turn thread ids are known; no DB I/O.
+ * Returns the resulting thread-id set (previous ∪ new_threads).
+ */
+export function assertCreateTurnThreadDelta(input: {
+ previousThreadIds: ReadonlySet<string>;
+ new_threads: readonly { thread_id: string }[];
+ new_context_appends: readonly { thread_id: string }[];
+ capability_states: readonly { thread_id: string }[];
+}): Set<string> {
+ const newThreadIds = new Set<string>();
+ for (const nt of input.new_threads) {
+ if (input.previousThreadIds.has(nt.thread_id) || newThreadIds.has(nt.thread_id)) {
+ throw new SessionStoreInvariantError(
+ `new_threads must only contain threads absent on the previous turn; thread '${nt.thread_id}' already exists`,
+ );
+ }
+ newThreadIds.add(nt.thread_id);
+ }
+
+ const knownThreadIds = new Set(input.previousThreadIds);
+ for (const threadId of newThreadIds) {
+ knownThreadIds.add(threadId);
+ }
+
+ for (const append of input.new_context_appends) {
+ if (!knownThreadIds.has(append.thread_id)) {
+ throw new SessionStoreInvariantError(`new_context_appends references unknown thread ${append.thread_id}`);
+ }
+ }
+
+ const seenCapabilityThreads = new Set<string>();
+ for (const capability of input.capability_states) {
+ if (!knownThreadIds.has(capability.thread_id)) {
+ throw new SessionStoreInvariantError(`capability_states references unknown thread ${capability.thread_id}`);
+ }
+ if (seenCapabilityThreads.has(capability.thread_id)) {
+ throw new SessionStoreInvariantError(`capability_states contains duplicate thread ${capability.thread_id}`);
+ }
+ seenCapabilityThreads.add(capability.thread_id);
+ }
+ for (const threadId of knownThreadIds) {
+ if (!seenCapabilityThreads.has(threadId)) {
+ throw new SessionStoreInvariantError(`capability_states is missing thread ${threadId}`);
+ }
+ }
+
+ return knownThreadIds;
+}
diff --git a/packages/harness/tests/agent-session/store/storeContractSuite.ts b/packages/harness/tests/agent-session/store/storeContractSuite.ts
index 2c457c469..084d8060f 100644
--- a/packages/harness/tests/agent-session/store/storeContractSuite.ts
+++ b/packages/harness/tests/agent-session/store/storeContractSuite.ts
@@ -8,8 +8,10 @@ import { decodeSessionEventPageToken } from '../../../src/agent-session/store/Se
import {
PreviousTurnRunningError,
SessionStoreConflictError,
+ SessionStoreInvariantError,
SessionStoreNotFoundError,
TurnAlreadyExistsError,
+ TurnNotFoundError,
TurnNotRunningError,
} from '../../../src/agent-session/store/SessionStoreErrors';
import { newEventId } from '../../../src/core/events/schema';
@@ -1014,6 +1016,25 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
expect(turn?.snapshot.threads[MAIN_THREAD_ID]?.capability_state).toEqual({ 'tfy.plan': { v: 2 } });
});
+ // InMemory rejects unknown thread_id; Postgres/SQLite only fence on a running turn and
+ // will upsert an orphan capability row. Production callers (TurnHandle) only patch threads
+ // that already exist on the turn — not enforced at the SQL store boundary yet.
+ it.skip('patchThreadCapabilityState rejects a thread_id not present on the turn', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ await expect(
+ store.patchThreadCapabilityState({
+ tenant_id: tenant,
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ thread_id: 'missing-thread',
+ key: 'tfy.plan',
+ state: { v: 1 },
+ }),
+ ).rejects.toBeInstanceOf(SessionStoreInvariantError);
+ });
+
it('capability state is per-turn: patching the successor does not change a frozen predecessor', async () => {
const store = createStore();
await seedSession(store);
@@ -1077,9 +1098,48 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
turn_id: 'turn-1',
});
// Totality: JSON round-trip must not drop keys (undefined is stripped by stringify).
- const revived = JSON.parse(JSON.stringify(turn)) as unknown;
- expect(revived).toEqual(turn);
- expect(JSON.stringify(turn)).toBe(JSON.stringify(revived));
+ // Store timestamps are Date; wire form is ISO string after stringify.
+ const record = mustGet(turn);
+ const revived = JSON.parse(JSON.stringify(record)) as unknown;
+ expect(revived).toEqual({
+ ...record,
+ created_at: record.created_at.toISOString(),
+ updated_at: record.updated_at.toISOString(),
+ });
+ });
+
+ it('JSON-looking strings remain strings', async () => {
+ const store = createStore();
+ const jsonLooking = '{"x":1}';
+ await seedSession(store, makeAgentSpec({ instructions: jsonLooking }));
+ await store.updateSession({
+ tenant_id: tenant,
+ session_id: sessionId,
+ agent_spec: undefined,
+ title: jsonLooking,
+ });
+ await store.createTurn(
+ makeCreateTurnInput({
+ sessionId,
+ turnId: 'turn-1',
+ new_context_appends: [
+ {
+ thread_id: MAIN_THREAD_ID,
+ context: [userMessage(jsonLooking)],
+ current_context_usage: getEmptyCurrentContextUsage(),
+ },
+ ],
+ }),
+ );
+ const turn = await store.getTurn({
+ tenant_id: tenant,
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ });
+ const session = mustGet(await store.getSession({ tenant_id: tenant, session_id: sessionId }));
+ expect(session.title).toBe(jsonLooking);
+ expect(session.agent_spec.instructions).toBe(jsonLooking);
+ expect(mustGet(turn).snapshot.threads[MAIN_THREAD_ID]?.context).toEqual([{ role: 'user', content: jsonLooking }]);
});
it('patchMCPServers and patchSandboxInfo', async () => {
@@ -1102,6 +1162,28 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
expect(turn?.snapshot.mcp_servers?.['svc']?.session_id).toBe('mcp-1');
expect(mustGet(turn).snapshot.sandbox_info?.sandbox_id).toBe('sbx-1');
});
+
+ it('patchMCPServers replaces each server id wholesale (omitted fields do not linger)', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ await store.patchMCPServers({
+ tenant_id: tenant,
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ mcp_servers: [{ id: 'svc', name: 'svc', session_id: 'mcp-1', transport_type: 'streamable-http' }],
+ });
+ await store.patchMCPServers({
+ tenant_id: tenant,
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ mcp_servers: [{ id: 'svc', name: 'svc', transport_type: 'sse' }],
+ });
+ const turn = await store.getTurn({ tenant_id: tenant, session_id: sessionId, turn_id: 'turn-1' });
+ expect(mustGet(turn).snapshot.mcp_servers).toEqual({
+ svc: { id: 'svc', name: 'svc', transport_type: 'sse' },
+ });
+ });
});
describe('pagination', () => {
@@ -1155,6 +1237,37 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
expect(data[0]?.type).toBe(EventType.MODEL_MESSAGE);
});
+ it('listTurnEvents missing turn → not found', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await expect(
+ store.listTurnEvents({
+ tenant_id: tenant,
+ session_id: sessionId,
+ turn_id: 'missing',
+ limit: 10,
+ page_token: undefined,
+ order: undefined,
+ }),
+ ).rejects.toBeInstanceOf(TurnNotFoundError);
+ });
+
+ it('listTurnEvents on a turn with no events returns an empty page', async () => {
+ const store = createStore();
+ await seedSession(store);
+ await store.createTurn(makeCreateTurnInput({ sessionId, turnId: 'turn-1' }));
+ const page = await store.listTurnEvents({
+ tenant_id: tenant,
+ session_id: sessionId,
+ turn_id: 'turn-1',
+ limit: 10,
+ page_token: undefined,
+ order: undefined,
+ });
+ expect(page.data).toEqual([]);
+ expect(page.pagination.next_page_token).toBeUndefined();
+ });
+
it('listSessionEvents includes running turns and is newest-first', async () => {
const store = createStore();
await seedSession(store);
diff --git a/packages/harness/tests/agent-session/testHelpers.ts b/packages/harness/tests/agent-session/testHelpers.ts
index d8a50d36d..2c09f2dd4 100644
--- a/packages/harness/tests/agent-session/testHelpers.ts
+++ b/packages/harness/tests/agent-session/testHelpers.ts
@@ -203,7 +203,7 @@ export function makeRunningTurnRecord(input: {
previousTurnId?: string | null;
firstTurnId?: string;
}): TurnRecord {
- const now = new Date().toISOString();
+ const now = new Date();
return {
turn_id: input.turnId,
session_id: input.sessionId,
diff --git a/packages/server/jest.store.postgres.config.cjs b/packages/server/jest.store.postgres.config.cjs
new file mode 100644
index 000000000..8b971479f
--- /dev/null
+++ b/packages/server/jest.store.postgres.config.cjs
@@ -0,0 +1,27 @@
+/** @type {import('jest').Config} */
+module.exports = {
+ testEnvironment: 'node',
+ globalSetup: '<rootDir>/tests/db/session-store/postgres/globalSetup.ts',
+ transform: {
+ '^.+\\.(m?js|tsx?)$': [
+ '@swc/jest',
+ {
+ jsc: {
+ parser: { syntax: 'typescript', decorators: true, dynamicImport: true },
+ target: 'es2022',
+ },
+ module: { type: 'commonjs' },
+ },
+ ],
+ },
+ moduleNameMapper: {
+ '^(\\.{1,2}/.*)\\.js$': '$1',
+ '^@truefoundry/utils/agent-session/(.*)$': '<rootDir>/../harness/src/agent-session/$1',
+ '^@truefoundry/utils/core/(.*)$': '<rootDir>/../harness/src/core/$1',
+ },
+ transformIgnorePatterns: ['/node_modules/(?!.*kysely)'],
+ testTimeout: 120_000,
+ maxWorkers: '50%',
+ roots: ['<rootDir>/tests/db/session-store/postgres', '<rootDir>/src'],
+ testMatch: ['<rootDir>/tests/db/session-store/postgres/**/*.test.ts'],
+};
diff --git a/packages/server/jest.store.config.cjs b/packages/server/jest.store.sqlite.config.cjs
similarity index 77%
rename from packages/server/jest.store.config.cjs
rename to packages/server/jest.store.sqlite.config.cjs
index 241fb4126..edaaa340d 100644
--- a/packages/server/jest.store.config.cjs
+++ b/packages/server/jest.store.sqlite.config.cjs
@@ -1,7 +1,6 @@
/** @type {import('jest').Config} */
module.exports = {
testEnvironment: 'node',
- globalSetup: '<rootDir>/tests/db/session-store/globalSetup.ts',
transform: {
'^.+\\.(m?js|tsx?)$': [
'@swc/jest',
@@ -22,6 +21,6 @@ module.exports = {
transformIgnorePatterns: ['/node_modules/(?!.*kysely)'],
testTimeout: 120_000,
maxWorkers: '50%',
- roots: ['<rootDir>/tests/db/session-store', '<rootDir>/src'],
- testMatch: ['<rootDir>/tests/db/session-store/**/*.test.ts'],
+ roots: ['<rootDir>/tests/db/session-store/sqlite', '<rootDir>/src'],
+ testMatch: ['<rootDir>/tests/db/session-store/sqlite/**/*.test.ts'],
};
diff --git a/packages/server/package.json b/packages/server/package.json
index 756c21442..e7f21b320 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -13,7 +13,8 @@
"typecheck": "tsc --noEmit",
"openapi:write": "tsx --env-file=.env.test scripts/write-openapi.ts",
"test": "tsx --env-file=.env.test --test \"src/**/*.test.ts\"",
- "test:store": "jest --config jest.store.config.cjs",
+ "test:store:postgres": "jest --config jest.store.postgres.config.cjs",
+ "test:store:sqlite": "jest --config jest.store.sqlite.config.cjs",
"start": "node dist/main.js"
},
"dependencies": {
@@ -21,6 +22,7 @@
"@hono/swagger-ui": "^0.2.1",
"@hono/zod-openapi": "^0.19.10",
"@truefoundry/utils": "workspace:*",
+ "better-sqlite3": "^13.0.2",
"hono": "^4.12.31",
"kysely": "^0.29.4",
"pg": "^8.22.0",
@@ -33,6 +35,7 @@
"devDependencies": {
"@swc/core": "^1.11.0",
"@swc/jest": "^0.2.37",
+ "@types/better-sqlite3": "^7.6.13",
"@types/jest": "^29.5.14",
"@types/node": "^24.12.0",
"@types/pg": "^8.20.0",
diff --git a/packages/server/src/apis/sessions.ts b/packages/server/src/apis/sessions.ts
index 94ea41eb8..87690e0b6 100644
--- a/packages/server/src/apis/sessions.ts
+++ b/packages/server/src/apis/sessions.ts
@@ -45,8 +45,8 @@ export function toWireSession(record: SessionRecord): Session {
id: record.session_id,
agent_spec: record.agent_spec,
title: record.title,
- created_at: record.created_at,
- updated_at: record.updated_at,
+ created_at: record.created_at.toISOString(),
+ updated_at: record.updated_at.toISOString(),
};
}
diff --git a/packages/server/src/apis/turns.ts b/packages/server/src/apis/turns.ts
index 57d73e576..1938c6207 100644
--- a/packages/server/src/apis/turns.ts
+++ b/packages/server/src/apis/turns.ts
@@ -34,7 +34,7 @@ function toWireTurn(record: TurnRecordWithoutSnapshot): Turn {
previous_turn_id: record.previous_turn_id,
input: record.input,
state: record.state,
- created_at: record.created_at,
+ created_at: record.created_at.toISOString(),
};
}
diff --git a/packages/server/src/db/migrateSqlite.ts b/packages/server/src/db/migrateSqlite.ts
new file mode 100644
index 000000000..b2e275932
--- /dev/null
+++ b/packages/server/src/db/migrateSqlite.ts
@@ -0,0 +1,42 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import type { Kysely } from 'kysely';
+import { FileMigrationProvider, Migrator } from 'kysely/migration';
+
+import type { Database } from './sqlite/types';
+
+/**
+ * Runs all pending SQLite migrations.
+ *
+ * Test / packaging helper only — do not import from `main` or `migrate-cli`.
+ * Production startup and `pnpm migrate` run Postgres via `migratePostgres`.
+ * Resolves `…/sqlite/migrations` next to this module (source or `dist/`).
+ */
+export async function migrateSqliteToLatest(db: Kysely<Database>): Promise<void> {
+ const migrator = new Migrator({
+ db,
+ provider: new FileMigrationProvider({
+ fs,
+ path,
+ migrationFolder: path.join(import.meta.dirname, 'sqlite', 'migrations'),
+ }),
+ });
+
+ const { error, results } = await migrator.migrateToLatest();
+
+ results?.forEach(it => {
+ if (it.status === 'Success') {
+ console.log(`migration "${it.migrationName}" was executed successfully`);
+ } else if (it.status === 'Error') {
+ console.error(`failed to execute migration "${it.migrationName}"`);
+ }
+ });
+
+ if (error) {
+ if (error instanceof Error) {
+ throw error;
+ }
+ throw new Error('failed to migrate', { cause: error });
+ }
+}
diff --git a/packages/server/src/db/postgres/migrate-cli.ts b/packages/server/src/db/postgres/migrate-cli.ts
index b80b7fea3..9c548ba81 100644
--- a/packages/server/src/db/postgres/migrate-cli.ts
+++ b/packages/server/src/db/postgres/migrate-cli.ts
@@ -1,5 +1,7 @@
/**
- * Run pending migrations and exit. Usage: `pnpm migrate` from packages/server.
+ * Run pending Postgres migrations and exit.
+ * Usage: `pnpm migrate` from packages/server.
+ * SQLite migrations are built into dist for packaging but are not run here.
*/
import configuration from '../../config';
import { migrateToLatest } from '../migratePostgres';
diff --git a/packages/server/src/db/postgres/session-store/queries/events.ts b/packages/server/src/db/postgres/session-store/queries/events.ts
index 9f18dc4ed..630fa8d4e 100644
--- a/packages/server/src/db/postgres/session-store/queries/events.ts
+++ b/packages/server/src/db/postgres/session-store/queries/events.ts
@@ -59,42 +59,57 @@ export async function appendToEvents(db: Kysely<Database>, input: AppendToEvents
}
}
+/**
+ * listTurnEvents — one statement: drive from turn, left-join a page of events.
+ * Missing turn → 0 rows → TurnNotFoundError. Empty log → one null-event sentinel.
+ */
export async function listTurnEvents(
db: Kysely<Database>,
input: ListTurnEventsInput,
): Promise<{ data: PersistedTurnEvent[]; pagination: TokenPagination }> {
const offset = decodeOffsetPageToken(input.page_token);
const limit = input.limit;
- const order = input.order ?? 'asc';
+ const eventOrder = input.order === 'desc' ? 'desc' : 'asc';
- const turnExists = await db
- .selectFrom('turn')
- .select('turn_id')
- .where('tenant_id', '=', input.tenant_id)
- .where('session_id', '=', input.session_id)
- .where('turn_id', '=', input.turn_id)
- .executeTakeFirst();
- if (!turnExists) {
+ const rows = await db
+ .selectFrom('turn as t')
+ .leftJoin(
+ eb =>
+ eb
+ .selectFrom('session_event')
+ .select(['tenant_id', 'session_id', 'turn_id', 'event_id', 'event'])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .orderBy('event_id', eventOrder)
+ .limit(limit + 1)
+ .offset(offset)
+ .as('e'),
+ join =>
+ join
+ .onRef('e.tenant_id', '=', 't.tenant_id')
+ .onRef('e.session_id', '=', 't.session_id')
+ .onRef('e.turn_id', '=', 't.turn_id'),
+ )
+ .select(['t.turn_id', 'e.event'])
+ .where('t.tenant_id', '=', input.tenant_id)
+ .where('t.session_id', '=', input.session_id)
+ .where('t.turn_id', '=', input.turn_id)
+ .orderBy('e.event_id', eventOrder)
+ .execute();
+
+ if (rows.length === 0) {
throw new TurnNotFoundError(input.turn_id);
}
- const query = db
- .selectFrom('session_event')
- .select(['event'])
- .where('tenant_id', '=', input.tenant_id)
- .where('session_id', '=', input.session_id)
- .where('turn_id', '=', input.turn_id)
- .orderBy('event_id', order === 'desc' ? 'desc' : 'asc')
- .limit(limit + 1)
- .offset(offset);
-
- const rows = await query.execute();
- const page = paginateOffsetRows(
- rows.map(r => r.event),
- limit,
- offset,
- );
- return page;
+ const events: PersistedTurnEvent[] = [];
+ for (const row of rows) {
+ if (row.event !== null) {
+ events.push(row.event);
+ }
+ }
+
+ return paginateOffsetRows(events, limit, offset);
}
export async function listSessionEvents(
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 5f1ecb6b0..25c0b3ff2 100644
--- a/packages/server/src/db/postgres/session-store/queries/sessions.ts
+++ b/packages/server/src/db/postgres/session-store/queries/sessions.ts
@@ -60,8 +60,8 @@ function mapRowToSessionRecord(row: {
title: row.title,
last_turn_id: row.last_turn_id,
custom: parseSessionCustom(row.custom),
- created_at: row.created_at.toISOString(),
- updated_at: row.updated_at.toISOString(),
+ created_at: row.created_at,
+ updated_at: row.updated_at,
last_activity_timestamp_ms: row.last_activity_timestamp_ms,
};
}
@@ -156,10 +156,10 @@ export async function listSessions(
let query = db.selectFrom('session').selectAll().where('tenant_id', '=', input.tenant_id);
if (input.start_timestamp !== undefined) {
- query = query.where('created_at', '>=', new Date(input.start_timestamp));
+ query = query.where('created_at', '>=', input.start_timestamp);
}
if (input.end_timestamp !== undefined) {
- query = query.where('created_at', '<=', new Date(input.end_timestamp));
+ query = query.where('created_at', '<=', input.end_timestamp);
}
if (order === 'asc') {
diff --git a/packages/server/src/db/postgres/session-store/queries/threads.ts b/packages/server/src/db/postgres/session-store/queries/threads.ts
index cd8f04724..0e818735b 100644
--- a/packages/server/src/db/postgres/session-store/queries/threads.ts
+++ b/packages/server/src/db/postgres/session-store/queries/threads.ts
@@ -147,38 +147,48 @@ export async function addThreads(db: Kysely<Database>, input: AddThreadsInput):
}
/**
- * removeThreads — fenced tx: DELETE this turn's turn_thread rows + this turn's
- * capability rows. Older turns keep their per-turn maps. Log rows stay
- * (ancestor arrays reference them).
+ * removeThreads — one statement: fence FOR SHARE + delete turn_thread + capability rows.
+ * Older turns keep their maps; log rows stay. Empty thread_ids is a no-op.
*/
export async function removeThreads(db: Kysely<Database>, input: RemoveThreadsInput): Promise<void> {
- await db.transaction().execute(async trx => {
- await assertTurnRunning(trx, {
- tenant_id: input.tenant_id,
- session_id: input.session_id,
- turn_id: input.turn_id,
- });
+ if (input.thread_ids.length === 0) {
+ return;
+ }
- if (input.thread_ids.length === 0) {
- return;
- }
+ const keys: TurnKeys = {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ };
+ const onFence = sql<boolean>`EXISTS (SELECT 1 FROM turn_fence)`;
- await trx
- .deleteFrom('turn_thread')
- .where('tenant_id', '=', input.tenant_id)
- .where('session_id', '=', input.session_id)
- .where('turn_id', '=', input.turn_id)
- .where('thread_id', 'in', input.thread_ids)
- .execute();
-
- await trx
- .deleteFrom('thread_capability_state')
- .where('tenant_id', '=', input.tenant_id)
- .where('session_id', '=', input.session_id)
- .where('turn_id', '=', input.turn_id)
- .where('thread_id', 'in', input.thread_ids)
- .execute();
- });
+ const fence = await db
+ .with('turn_fence', qb => turnRunningFence(qb, keys))
+ .with('del_cap', qb =>
+ qb
+ .deleteFrom('thread_capability_state')
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .where('thread_id', 'in', input.thread_ids)
+ .where(onFence),
+ )
+ .with('del_tt', qb =>
+ qb
+ .deleteFrom('turn_thread')
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .where('thread_id', 'in', input.thread_ids)
+ .where(onFence),
+ )
+ .selectFrom('turn_fence')
+ .select('one')
+ .executeTakeFirst();
+
+ if (fence === undefined) {
+ await classifyTurnFenceWriteFailure(db, keys);
+ }
}
function completionPatchExpr(completion: SubAgentCompletionMarker | null): RawBuilder<TurnThreadCheckpoint> {
diff --git a/packages/server/src/db/postgres/session-store/queries/turns.ts b/packages/server/src/db/postgres/session-store/queries/turns.ts
index 4ebf6bb04..f892ecd2b 100644
--- a/packages/server/src/db/postgres/session-store/queries/turns.ts
+++ b/packages/server/src/db/postgres/session-store/queries/turns.ts
@@ -5,6 +5,7 @@ import {
type TurnInputItem,
type TurnState,
} from '@truefoundry/utils/agent-session/schemas/turn';
+import { assertCreateTurnThreadDelta } from '@truefoundry/utils/agent-session/store/assertCreateTurnThreadDelta';
import type {
FreezeAndGetTurnInput,
TurnRecordWithoutSnapshot,
@@ -318,8 +319,8 @@ async function assembleTurnRecord(
state: turn.state,
input: turn.input,
snapshot,
- created_at: turn.created_at.toISOString(),
- updated_at: turn.updated_at.toISOString(),
+ created_at: turn.created_at,
+ updated_at: turn.updated_at,
custom: parseTurnCustom(turn.custom),
};
}
@@ -467,21 +468,12 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
}
}
- const newThreadIds = new Set(input.new_threads.map(t => t.thread_id));
- for (const nt of input.new_threads) {
- if (prevThreadRows.some(p => p.thread_id === nt.thread_id)) {
- throw new SessionStoreInvariantError(
- `new_threads must only contain threads absent on the previous turn; thread '${nt.thread_id}' already exists`,
- );
- }
- }
-
- const knownThreadIds = new Set([...prevThreadRows.map(r => r.thread_id), ...newThreadIds]);
- for (const append of input.new_context_appends) {
- if (!knownThreadIds.has(append.thread_id)) {
- throw new SessionStoreInvariantError(`new_context_appends references unknown thread ${append.thread_id}`);
- }
- }
+ assertCreateTurnThreadDelta({
+ previousThreadIds: new Set(prevThreadRows.map(r => r.thread_id)),
+ new_threads: input.new_threads,
+ new_context_appends: input.new_context_appends,
+ capability_states: input.capability_states,
+ });
const checkpoint: TurnCheckpoint = {
mcp_servers: input.mcp_servers ?? prevCheckpoint?.mcp_servers ?? null,
@@ -591,19 +583,9 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
await trx.insertInto('turn_thread').values(turnThreadRows).execute();
}
- // Complete per-turn capability maps are supplied by the caller. Persist
- // them directly; copying parent rows only to replace them is wasted work.
- const seenCapabilityThreads = new Set<string>();
+ // Complete per-turn capability maps (thread coverage asserted above).
const capabilityStateRows: CapabilityStateInsertRow[] = [];
for (const capability of input.capability_states) {
- if (!knownThreadIds.has(capability.thread_id)) {
- throw new SessionStoreInvariantError(`capability_states references unknown thread ${capability.thread_id}`);
- }
- if (seenCapabilityThreads.has(capability.thread_id)) {
- throw new SessionStoreInvariantError(`capability_states contains duplicate thread ${capability.thread_id}`);
- }
- seenCapabilityThreads.add(capability.thread_id);
-
if (capability.capability_state === null) continue;
for (const [key, state] of Object.entries(capability.capability_state)) {
capabilityStateRows.push({
@@ -618,12 +600,6 @@ export async function createTurn(db: Kysely<Database>, input: CreateTurnInput):
}
}
- for (const threadId of knownThreadIds) {
- if (!seenCapabilityThreads.has(threadId)) {
- throw new SessionStoreInvariantError(`capability_states is missing thread ${threadId}`);
- }
- }
-
if (capabilityStateRows.length > 0) {
await trx.insertInto('thread_capability_state').values(capabilityStateRows).execute();
}
@@ -721,8 +697,8 @@ export async function listTurns(db: Kysely<Database>, input: ListTurnsInput): Pr
previous_turn_id: row.previous_turn_id,
state: row.state,
input: row.input,
- created_at: row.created_at.toISOString(),
- updated_at: row.updated_at.toISOString(),
+ created_at: row.created_at,
+ updated_at: row.updated_at,
custom: parseTurnCustom(row.custom),
}));
diff --git a/packages/server/src/db/sqlite/AGENTS.md b/packages/server/src/db/sqlite/AGENTS.md
new file mode 100644
index 000000000..7b9d86997
--- /dev/null
+++ b/packages/server/src/db/sqlite/AGENTS.md
@@ -0,0 +1 @@
+- JSON projection aliases MUST be listed in `client.ts`'s `JSON_RESULT_COLUMNS`.
diff --git a/packages/server/src/db/sqlite/CLAUDE.md b/packages/server/src/db/sqlite/CLAUDE.md
new file mode 100644
index 000000000..43c994c2d
--- /dev/null
+++ b/packages/server/src/db/sqlite/CLAUDE.md
@@ -0,0 +1 @@
diff --git a/packages/server/src/db/sqlite/client.ts b/packages/server/src/db/sqlite/client.ts
new file mode 100644
index 000000000..0d494a397
--- /dev/null
+++ b/packages/server/src/db/sqlite/client.ts
@@ -0,0 +1,167 @@
+import Database from 'better-sqlite3';
+import {
+ CompiledQuery,
+ Kysely,
+ ParseJSONResultsPlugin,
+ SqliteAdapter,
+ SqliteDriver,
+ SqliteIntrospector,
+ SqliteQueryCompiler,
+ type DatabaseConnection,
+ type Dialect,
+ type Driver,
+ type QueryCompiler,
+ type TransactionSettings,
+} from 'kysely';
+
+import type { Database as Schema } from './types';
+
+/**
+ * Wraps SqliteDriver and maps Kysely access mode onto SQLite begin kinds:
+ * - `read only` → deferred BEGIN (read snapshot; no writer reservation)
+ * - default / `read write` → BEGIN IMMEDIATE (RESERVED write lock)
+ *
+ * Stock SqliteDriver.d.ts omits `settings` on beginTransaction; compose instead of override.
+ */
+class ImmediateSqliteDriver implements Driver {
+ readonly #inner: SqliteDriver;
+
+ constructor(database: Database.Database) {
+ this.#inner = new SqliteDriver({ database });
+ }
+
+ init(): Promise<void> {
+ return this.#inner.init();
+ }
+
+ acquireConnection(): Promise<DatabaseConnection> {
+ return this.#inner.acquireConnection();
+ }
+
+ async beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void> {
+ const begin = settings.accessMode === 'read only' ? 'begin' : 'begin immediate';
+ await connection.executeQuery(CompiledQuery.raw(begin));
+ }
+
+ commitTransaction(connection: DatabaseConnection): Promise<void> {
+ return this.#inner.commitTransaction(connection);
+ }
+
+ rollbackTransaction(connection: DatabaseConnection): Promise<void> {
+ return this.#inner.rollbackTransaction(connection);
+ }
+
+ savepoint(
+ connection: DatabaseConnection,
+ savepointName: string,
+ compileQuery: QueryCompiler['compileQuery'],
+ ): Promise<void> {
+ return this.#inner.savepoint(connection, savepointName, compileQuery);
+ }
+
+ rollbackToSavepoint(
+ connection: DatabaseConnection,
+ savepointName: string,
+ compileQuery: QueryCompiler['compileQuery'],
+ ): Promise<void> {
+ return this.#inner.rollbackToSavepoint(connection, savepointName, compileQuery);
+ }
+
+ releaseSavepoint(
+ connection: DatabaseConnection,
+ savepointName: string,
+ compileQuery: QueryCompiler['compileQuery'],
+ ): Promise<void> {
+ return this.#inner.releaseSavepoint(connection, savepointName, compileQuery);
+ }
+
+ releaseConnection(): Promise<void> {
+ return this.#inner.releaseConnection();
+ }
+
+ destroy(): Promise<void> {
+ return this.#inner.destroy();
+ }
+}
+
+class ImmediateSqliteDialect implements Dialect {
+ readonly #database: Database.Database;
+
+ constructor(database: Database.Database) {
+ this.#database = database;
+ }
+
+ createDriver(): Driver {
+ return new ImmediateSqliteDriver(this.#database);
+ }
+
+ createQueryCompiler() {
+ return new SqliteQueryCompiler();
+ }
+
+ createAdapter() {
+ return new SqliteAdapter();
+ }
+
+ createIntrospector(db: Kysely<unknown>) {
+ return new SqliteIntrospector(db);
+ }
+}
+
+function applyPragmas(database: Database.Database): void {
+ database.pragma('journal_mode = WAL');
+ database.pragma('busy_timeout = 5000');
+ database.pragma('synchronous = NORMAL');
+ database.pragma('foreign_keys = ON');
+ database.pragma('temp_store = MEMORY');
+ database.pragma('cache_size = -10240');
+}
+
+/**
+ * Result aliases that are `json(...)` projections of JSONB columns.
+ * Plain TEXT (title, ids, timestamps) must not be parsed even when they look like JSON.
+ */
+const JSON_RESULT_COLUMNS = new Set([
+ 'agent_spec',
+ 'custom',
+ 'ancestor_ids',
+ 'input',
+ 'state',
+ 'checkpoint',
+ 'agent_info',
+ 'current_context_usage',
+ 'body',
+ 'capability_state',
+ 'turn_checkpoint',
+ 'turn_state',
+ 'thread_checkpoint',
+ 'event',
+]);
+
+/** Top-level row field only — `$[0]."body"`, not `$[0]."body"."content"`. */
+function shouldParseJsonResultColumn(_value: string, jsonPath: string): boolean {
+ const match = /^\$\[\d+\]\."([^"]+)"$/.exec(jsonPath);
+ const column = match?.[1];
+ return column !== undefined && JSON_RESULT_COLUMNS.has(column);
+}
+
+export function createSqliteDb(filename: string): Kysely<Schema> {
+ const database = new Database(filename);
+ applyPragmas(database);
+ return new Kysely<Schema>({
+ dialect: new ImmediateSqliteDialect(database),
+ // Parse only projected JSON columns once; never re-parse nested string values.
+ plugins: [new ParseJSONResultsPlugin({ shouldParse: shouldParseJsonResultColumn })],
+ });
+}
+
+/**
+ * Match better-sqlite3 unique constraint errors without brittle instanceof checks.
+ */
+export function isUniqueViolation(err: unknown): boolean {
+ if (typeof err !== 'object' || err === null || !('code' in err)) {
+ return false;
+ }
+ const code = err.code;
+ return code === 'SQLITE_CONSTRAINT_UNIQUE' || code === 'SQLITE_CONSTRAINT_PRIMARYKEY';
+}
diff --git a/packages/server/src/db/sqlite/migrations/20260730_000001_init.ts b/packages/server/src/db/sqlite/migrations/20260730_000001_init.ts
new file mode 100644
index 000000000..d7dfc8500
--- /dev/null
+++ b/packages/server/src/db/sqlite/migrations/20260730_000001_init.ts
@@ -0,0 +1,9 @@
+import { type Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await sql`SELECT 1`.execute(db);
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`SELECT 1`.execute(db);
+}
diff --git a/packages/server/src/db/sqlite/migrations/20260730_000002_session_store.ts b/packages/server/src/db/sqlite/migrations/20260730_000002_session_store.ts
new file mode 100644
index 000000000..e52f78c52
--- /dev/null
+++ b/packages/server/src/db/sqlite/migrations/20260730_000002_session_store.ts
@@ -0,0 +1,135 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * Session-store tables for SQLite (canonical DDL owner).
+ *
+ * JSON payload columns are BLOB holding SQLite JSONB (via jsonb(...)).
+ * Timestamps are ISO-8601 TEXT. Context order is turn_thread_context (not an array column).
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await sql`
+ CREATE TABLE session (
+ tenant_id TEXT NOT NULL,
+ session_id TEXT NOT NULL,
+ agent_spec BLOB NOT NULL,
+ title TEXT,
+ last_turn_id TEXT,
+ custom BLOB,
+ last_activity_timestamp_ms INTEGER NOT NULL,
+ created_at TEXT NOT NULL,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (tenant_id, session_id)
+ ) STRICT
+ `.execute(db);
+
+ await sql`
+ CREATE INDEX session_list_idx
+ ON session (tenant_id, created_at, session_id)
+ `.execute(db);
+
+ await sql`
+ CREATE TABLE turn (
+ tenant_id TEXT NOT NULL,
+ session_id TEXT NOT NULL,
+ turn_id TEXT NOT NULL,
+ first_turn_id TEXT NOT NULL,
+ previous_turn_id TEXT,
+ ancestor_ids BLOB NOT NULL,
+ input BLOB NOT NULL,
+ state BLOB NOT NULL,
+ checkpoint BLOB NOT NULL,
+ custom BLOB,
+ created_at TEXT NOT NULL,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (tenant_id, session_id, turn_id)
+ ) STRICT
+ `.execute(db);
+
+ await sql`
+ CREATE INDEX turn_list_idx
+ ON turn (tenant_id, session_id, created_at, turn_id)
+ `.execute(db);
+
+ await sql`
+ CREATE TABLE turn_thread (
+ tenant_id TEXT NOT NULL,
+ session_id TEXT NOT NULL,
+ turn_id TEXT NOT NULL,
+ thread_id TEXT NOT NULL,
+ checkpoint BLOB NOT NULL,
+ agent_info BLOB,
+ current_context_usage BLOB NOT NULL,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (tenant_id, session_id, turn_id, thread_id)
+ ) STRICT
+ `.execute(db);
+
+ await sql`
+ CREATE TABLE turn_thread_context (
+ tenant_id TEXT NOT NULL,
+ session_id TEXT NOT NULL,
+ turn_id TEXT NOT NULL,
+ thread_id TEXT NOT NULL,
+ pos INTEGER NOT NULL,
+ append_id INTEGER NOT NULL,
+ PRIMARY KEY (tenant_id, session_id, turn_id, thread_id, pos)
+ ) STRICT
+ `.execute(db);
+
+ await sql`
+ CREATE INDEX turn_thread_context_append_idx
+ ON turn_thread_context (tenant_id, session_id, thread_id, append_id)
+ `.execute(db);
+
+ await sql`
+ CREATE TABLE session_event (
+ tenant_id TEXT NOT NULL,
+ session_id TEXT NOT NULL,
+ turn_id TEXT NOT NULL,
+ event_id TEXT NOT NULL,
+ event BLOB NOT NULL,
+ created_at TEXT NOT NULL,
+ PRIMARY KEY (tenant_id, session_id, turn_id, event_id)
+ ) STRICT
+ `.execute(db);
+
+ await sql`
+ CREATE TABLE thread_context_log (
+ append_id INTEGER PRIMARY KEY AUTOINCREMENT,
+ tenant_id TEXT NOT NULL,
+ session_id TEXT NOT NULL,
+ thread_id TEXT NOT NULL,
+ turn_id TEXT NOT NULL,
+ body BLOB NOT NULL,
+ created_at TEXT NOT NULL
+ ) STRICT
+ `.execute(db);
+
+ await sql`
+ CREATE INDEX thread_context_log_lookup_idx
+ ON thread_context_log (tenant_id, session_id, thread_id, append_id)
+ `.execute(db);
+
+ await sql`
+ CREATE TABLE thread_capability_state (
+ tenant_id TEXT NOT NULL,
+ session_id TEXT NOT NULL,
+ turn_id TEXT NOT NULL,
+ thread_id TEXT NOT NULL,
+ key TEXT NOT NULL,
+ state BLOB,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (tenant_id, session_id, turn_id, thread_id, key)
+ ) STRICT
+ `.execute(db);
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`DROP TABLE IF EXISTS thread_capability_state`.execute(db);
+ await sql`DROP TABLE IF EXISTS thread_context_log`.execute(db);
+ await sql`DROP TABLE IF EXISTS session_event`.execute(db);
+ await sql`DROP TABLE IF EXISTS turn_thread_context`.execute(db);
+ await sql`DROP TABLE IF EXISTS turn_thread`.execute(db);
+ await sql`DROP TABLE IF EXISTS turn`.execute(db);
+ await sql`DROP TABLE IF EXISTS session`.execute(db);
+}
diff --git a/packages/server/src/db/sqlite/session-store/SqliteSessionStore.ts b/packages/server/src/db/sqlite/session-store/SqliteSessionStore.ts
new file mode 100644
index 000000000..4100fd2ce
--- /dev/null
+++ b/packages/server/src/db/sqlite/session-store/SqliteSessionStore.ts
@@ -0,0 +1,207 @@
+import type { SessionRecord } from '@truefoundry/utils/agent-session/models/SessionRecord';
+import type { TurnRecord } from '@truefoundry/utils/agent-session/models/TurnRecord';
+import type { PersistedTurnEvent, SessionEventItem } from '@truefoundry/utils/agent-session/schemas/events';
+import type { TokenPagination } from '@truefoundry/utils/agent-session/schemas/pagination';
+import type {
+ AddThreadsInput,
+ AppendToEventsInput,
+ AppendToThreadContextInput,
+ CreateSessionInput,
+ CreateTurnInput,
+ FreezeAndGetTurnInput,
+ GetSessionInput,
+ GetTurnInput,
+ ISessionStore,
+ ListSessionEventsInput,
+ ListSessionsInput,
+ ListTurnEventsInput,
+ ListTurnsInput,
+ OverwriteThreadContextInput,
+ PatchMCPServersInput,
+ PatchSandboxInfoInput,
+ PatchThreadCapabilityStateInput,
+ RemoveThreadsInput,
+ TurnRecordWithoutSnapshot,
+ UpdateSessionInput,
+ UpdateTurnStateInput,
+} from '@truefoundry/utils/agent-session/store/ISessionStore';
+import { decodeOffsetPageToken, encodeOffsetPageToken } from '@truefoundry/utils/agent-session/store/OffsetPageToken';
+import type { Kysely } from 'kysely';
+import type { Database } from '../types';
+import { patchThreadCapabilityState as patchThreadCapabilityStateQuery } from './queries/capabilities';
+import {
+ appendToEvents as appendToEventsQuery,
+ listSessionEvents as listSessionEventsQuery,
+ listTurnEvents as listTurnEventsQuery,
+} from './queries/events';
+import {
+ createSession as createSessionQuery,
+ getSession as getSessionQuery,
+ listSessions as listSessionsQuery,
+ updateSession as updateSessionQuery,
+} from './queries/sessions';
+import {
+ addThreads as addThreadsQuery,
+ appendToThreadContext as appendToThreadContextQuery,
+ overwriteThreadContext as overwriteThreadContextQuery,
+ patchMCPServers as patchMCPServersQuery,
+ patchSandboxInfo as patchSandboxInfoQuery,
+ removeThreads as removeThreadsQuery,
+} from './queries/threads';
+import type { NewThreadRegistration } from './queries/turns';
+import {
+ createTurn as createTurnQuery,
+ freezeAndGetTurn as freezeAndGetTurnQuery,
+ getTurn as getTurnQuery,
+ listTurns as listTurnsQuery,
+ updateTurnState as updateTurnStateQuery,
+} from './queries/turns';
+
+type SessionCustom = Record<string, never>;
+type TurnCustom = Record<string, never>;
+
+/**
+ * ## Design: append-only context log + per-turn position table
+ *
+ * Message bodies live in `thread_context_log`, append-only, written exactly
+ * once; ids are SQLite AUTOINCREMENT (`append_id`). A turn's context per thread
+ * is ordered rows in `turn_thread_context (pos, append_id)` — no array column.
+ * Turns share no mutable structure: linear continuation and fork are the same
+ * copy path (parent context mapping rows + new mapping rows), overwrite deletes
+ * the current mapping and inserts a fresh one, and a still-running ancestor's
+ * 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.
+ * 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).
+ */
+export class SqliteSessionStore implements ISessionStore<SessionCustom, TurnCustom> {
+ constructor(private readonly db: Kysely<Database>) {}
+
+ createSession(input: CreateSessionInput<SessionCustom>): Promise<void> {
+ return createSessionQuery(this.db, input);
+ }
+
+ getSession(input: GetSessionInput): Promise<SessionRecord<SessionCustom> | undefined> {
+ return getSessionQuery(this.db, input);
+ }
+
+ updateSession(input: UpdateSessionInput<SessionCustom>): Promise<void> {
+ return updateSessionQuery(this.db, input);
+ }
+
+ async listSessions(
+ input: ListSessionsInput,
+ ): Promise<{ data: SessionRecord<SessionCustom>[]; pagination: TokenPagination }> {
+ const result = await listSessionsQuery(this.db, input);
+ return {
+ data: result.data,
+ pagination: {
+ limit: input.limit,
+ ...result.pagination,
+ },
+ };
+ }
+
+ async createTurn(input: CreateTurnInput<TurnCustom>): Promise<void> {
+ await createTurnQuery(this.db, {
+ tenant_id: input.tenant_id,
+ session_id: input.turn.session_id,
+ turn: {
+ turn_id: input.turn.turn_id,
+ first_turn_id: input.turn.first_turn_id,
+ previous_turn_id: input.turn.previous_turn_id,
+ ancestor_ids: input.turn.ancestor_ids,
+ input: input.turn.input,
+ state: input.turn.state,
+ custom: input.turn.custom,
+ },
+ new_threads: input.new_threads.map((thread): NewThreadRegistration => ({
+ thread_id: thread.thread_id,
+ parent: thread.parent,
+ agent_info: thread.agent_info,
+ })),
+ new_context_appends: input.new_context_appends,
+ capability_states: input.capability_states,
+ last_activity_timestamp_ms: Date.now(),
+ update_session_title_if_not_exist: input.update_session_title_if_not_exist,
+ mcp_servers: null,
+ sandbox_info: null,
+ });
+ }
+
+ freezeAndGetTurn(input: FreezeAndGetTurnInput): Promise<TurnRecord<TurnCustom>> {
+ return freezeAndGetTurnQuery(this.db, input);
+ }
+
+ getTurn(input: GetTurnInput): Promise<TurnRecord<TurnCustom> | undefined> {
+ return getTurnQuery(this.db, input);
+ }
+
+ async listTurns(
+ input: ListTurnsInput,
+ ): Promise<{ data: TurnRecordWithoutSnapshot<TurnCustom>[]; pagination: TokenPagination }> {
+ const offset = decodeOffsetPageToken(input.page_token);
+ const result = await listTurnsQuery(this.db, {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ limit: input.limit,
+ offset,
+ });
+ const pagination: TokenPagination = { limit: input.limit };
+ if (result.next_offset !== null) {
+ pagination.next_page_token = encodeOffsetPageToken(result.next_offset);
+ }
+ if (offset > 0) {
+ pagination.previous_page_token = encodeOffsetPageToken(Math.max(0, offset - input.limit));
+ }
+ return { data: result.turns, pagination };
+ }
+
+ updateTurnState(input: UpdateTurnStateInput): Promise<void> {
+ return updateTurnStateQuery(this.db, input);
+ }
+
+ appendToEvents(input: AppendToEventsInput): Promise<void> {
+ return appendToEventsQuery(this.db, input);
+ }
+
+ addThreads(input: AddThreadsInput): Promise<void> {
+ return addThreadsQuery(this.db, input);
+ }
+
+ removeThreads(input: RemoveThreadsInput): Promise<void> {
+ return removeThreadsQuery(this.db, input);
+ }
+
+ appendToThreadContext(input: AppendToThreadContextInput): Promise<void> {
+ return appendToThreadContextQuery(this.db, input);
+ }
+
+ overwriteThreadContext(input: OverwriteThreadContextInput): Promise<void> {
+ return overwriteThreadContextQuery(this.db, input);
+ }
+
+ patchMCPServers(input: PatchMCPServersInput): Promise<void> {
+ return patchMCPServersQuery(this.db, input);
+ }
+
+ patchSandboxInfo(input: PatchSandboxInfoInput): Promise<void> {
+ return patchSandboxInfoQuery(this.db, input);
+ }
+
+ patchThreadCapabilityState(input: PatchThreadCapabilityStateInput): Promise<void> {
+ return patchThreadCapabilityStateQuery(this.db, input);
+ }
+
+ listTurnEvents(input: ListTurnEventsInput): Promise<{ data: PersistedTurnEvent[]; pagination: TokenPagination }> {
+ return listTurnEventsQuery(this.db, input);
+ }
+
+ listSessionEvents(input: ListSessionEventsInput): Promise<{ data: SessionEventItem[]; pagination: TokenPagination }> {
+ return listSessionEventsQuery(this.db, input);
+ }
+}
diff --git a/packages/server/src/db/sqlite/session-store/queries/capabilities.ts b/packages/server/src/db/sqlite/session-store/queries/capabilities.ts
new file mode 100644
index 000000000..00ac0487e
--- /dev/null
+++ b/packages/server/src/db/sqlite/session-store/queries/capabilities.ts
@@ -0,0 +1,59 @@
+import type { PatchThreadCapabilityStateInput } from '@truefoundry/utils/agent-session/store/ISessionStore';
+import { sql, type Kysely } from 'kysely';
+import type { Database } from '../../types';
+import { jsonbBind, nowIso } from '../sqlExpressions';
+import { classifyTurnFenceWriteFailure, type TurnKeys } from './turns';
+
+/**
+ * patchThreadCapabilityState — single-statement fenced upsert on the PER-TURN PK.
+ * Does NOT bump turn.updated_at.
+ * State is bound as SQL NULL when input.state is null (matches Postgres contract).
+ */
+export async function patchThreadCapabilityState(
+ db: Kysely<Database>,
+ input: PatchThreadCapabilityStateInput,
+): Promise<void> {
+ const keys: TurnKeys = {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ };
+
+ await db.transaction().execute(async trx => {
+ // Fence inside IMMEDIATE transaction: verify turn is still running.
+ const fenceRow = await trx
+ .selectFrom('turn')
+ .select(sql`1`.as('one'))
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .where(sql<boolean>`state->>'status' = 'running'`)
+ .executeTakeFirst();
+
+ if (!fenceRow) {
+ await classifyTurnFenceWriteFailure(trx, keys);
+ }
+
+ const now = nowIso();
+ const stateValue = input.state !== null ? jsonbBind(input.state) : null;
+
+ await trx
+ .insertInto('thread_capability_state')
+ .values({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ thread_id: input.thread_id,
+ key: input.key,
+ state: stateValue,
+ updated_at: now,
+ })
+ .onConflict(oc =>
+ oc.columns(['tenant_id', 'session_id', 'turn_id', 'thread_id', 'key']).doUpdateSet({
+ state: sql`excluded.state`,
+ updated_at: sql`excluded.updated_at`,
+ }),
+ )
+ .execute();
+ });
+}
diff --git a/packages/server/src/db/sqlite/session-store/queries/events.ts b/packages/server/src/db/sqlite/session-store/queries/events.ts
new file mode 100644
index 000000000..e5b5d7b36
--- /dev/null
+++ b/packages/server/src/db/sqlite/session-store/queries/events.ts
@@ -0,0 +1,215 @@
+import type { PersistedTurnEvent, SessionEventItem } from '@truefoundry/utils/agent-session/schemas/events';
+import type { TokenPagination } from '@truefoundry/utils/agent-session/schemas/pagination';
+import type {
+ AppendToEventsInput,
+ ListSessionEventsInput,
+ ListTurnEventsInput,
+} from '@truefoundry/utils/agent-session/store/ISessionStore';
+import { decodeOffsetPageToken, paginateOffsetRows } from '@truefoundry/utils/agent-session/store/OffsetPageToken';
+import {
+ decodeSessionEventPageToken,
+ paginateSessionEventRows,
+ type SessionEventPageCursor,
+} from '@truefoundry/utils/agent-session/store/SessionEventPageToken';
+import { SessionNotFoundError, TurnNotFoundError } from '@truefoundry/utils/agent-session/store/SessionStoreErrors';
+import { sql, type Kysely } from 'kysely';
+import type { Database } from '../../types';
+import { jsonbBind, jsonText } from '../sqlExpressions';
+import { classifyTurnFenceWriteFailure, type TurnKeys } from './turns';
+
+export async function appendToEvents(db: Kysely<Database>, input: AppendToEventsInput): Promise<void> {
+ if (input.events.length === 0) return;
+
+ const keys: TurnKeys = {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ };
+
+ // Fence check first inside BEGIN IMMEDIATE; then batched insert.
+ await db.transaction().execute(async trx => {
+ const fenceRow = await trx
+ .selectFrom('turn')
+ .select(sql`1`.as('one'))
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .where(sql<boolean>`state->>'status' = 'running'`)
+ .executeTakeFirst();
+
+ if (!fenceRow) {
+ await classifyTurnFenceWriteFailure(trx, keys);
+ }
+
+ const eventRows = input.events.map(event => ({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: event.id,
+ event: jsonbBind(event),
+ created_at: event.created_at,
+ }));
+
+ await trx.insertInto('session_event').values(eventRows).execute();
+ });
+}
+
+/**
+ * listTurnEvents — one statement: drive from turn, left-join a page of events.
+ * Missing turn → 0 rows → TurnNotFoundError. Empty log → one null-event sentinel.
+ */
+export async function listTurnEvents(
+ db: Kysely<Database>,
+ input: ListTurnEventsInput,
+): Promise<{ data: PersistedTurnEvent[]; pagination: TokenPagination }> {
+ const offset = decodeOffsetPageToken(input.page_token);
+ const limit = input.limit;
+ const eventOrder = input.order === 'desc' ? 'desc' : 'asc';
+
+ const rows = await db
+ .selectFrom('turn as t')
+ .leftJoin(
+ eb =>
+ eb
+ .selectFrom('session_event')
+ .select([
+ 'tenant_id',
+ 'session_id',
+ 'turn_id',
+ 'event_id',
+ jsonText<PersistedTurnEvent>(sql.ref('event')).as('event'),
+ ])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .orderBy('event_id', eventOrder)
+ .limit(limit + 1)
+ .offset(offset)
+ .as('e'),
+ join =>
+ join
+ .onRef('e.tenant_id', '=', 't.tenant_id')
+ .onRef('e.session_id', '=', 't.session_id')
+ .onRef('e.turn_id', '=', 't.turn_id'),
+ )
+ .select(['t.turn_id', 'e.event'])
+ .where('t.tenant_id', '=', input.tenant_id)
+ .where('t.session_id', '=', input.session_id)
+ .where('t.turn_id', '=', input.turn_id)
+ .orderBy('e.event_id', eventOrder)
+ .execute();
+
+ if (rows.length === 0) {
+ throw new TurnNotFoundError(input.turn_id);
+ }
+
+ const events: PersistedTurnEvent[] = [];
+ for (const row of rows) {
+ if (row.event !== null) {
+ events.push(row.event);
+ }
+ }
+
+ return paginateOffsetRows(events, limit, offset);
+}
+
+/** Anchor turn fields needed for chain resolution. */
+export interface AnchorTurn {
+ turn_id: string;
+ ancestor_ids: string[];
+}
+
+/**
+ * Full chain (oldest first, anchor last). `ancestor_ids` may be only the
+ * previous N ancestors, so spill through the oldest ancestor's own window
+ * until a root or gap. A missing turn or repeated id ends the walk.
+ */
+export async function resolveAncestorChain(
+ db: Kysely<Database>,
+ tenant: string,
+ sessionId: string,
+ anchor: AnchorTurn,
+): Promise<string[]> {
+ const chain = [...anchor.ancestor_ids, anchor.turn_id];
+ const seen = new Set(chain);
+ let oldestId = chain[0];
+ while (oldestId && oldestId !== anchor.turn_id) {
+ const oldest = await db
+ .selectFrom('turn')
+ .select([jsonText<string[]>(sql.ref('ancestor_ids')).as('ancestor_ids')])
+ .where('tenant_id', '=', tenant)
+ .where('session_id', '=', sessionId)
+ .where('turn_id', '=', oldestId)
+ .executeTakeFirst();
+ if (!oldest) break;
+ const older = oldest.ancestor_ids.filter(id => !seen.has(id));
+ if (older.length === 0) break;
+ chain.unshift(...older);
+ for (const id of older) seen.add(id);
+ oldestId = older[0];
+ }
+ return chain;
+}
+
+export async function listSessionEvents(
+ db: Kysely<Database>,
+ input: ListSessionEventsInput,
+): Promise<{ data: SessionEventItem[]; pagination: TokenPagination }> {
+ const limit = input.limit;
+
+ const session = await db
+ .selectFrom('session')
+ .select('last_turn_id')
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .executeTakeFirst();
+ if (!session) {
+ throw new SessionNotFoundError(input.session_id);
+ }
+
+ const decodedCursor = input.page_token === undefined ? undefined : decodeSessionEventPageToken(input.page_token);
+ const lastTurnId = decodedCursor?.last_turn_id ?? input.last_turn_id ?? session.last_turn_id;
+ if (lastTurnId === null) {
+ return { data: [], pagination: { limit } };
+ }
+ const cursor: SessionEventPageCursor = {
+ last_turn_id: lastTurnId,
+ offset: decodedCursor?.offset ?? 0,
+ };
+
+ const anchor = await db
+ .selectFrom('turn')
+ .select(['turn_id', jsonText<string[]>(sql.ref('ancestor_ids')).as('ancestor_ids')])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', cursor.last_turn_id)
+ .executeTakeFirst();
+ if (!anchor) {
+ throw new TurnNotFoundError(cursor.last_turn_id);
+ }
+
+ const chainIds = await resolveAncestorChain(db, input.tenant_id, input.session_id, {
+ turn_id: anchor.turn_id,
+ ancestor_ids: anchor.ancestor_ids,
+ });
+
+ // Bind the ancestor chain as a JSON array; json_each gives (key=index, value=turn_id).
+ const chainJson = JSON.stringify(chainIds);
+
+ const rows = await db
+ .selectFrom(sql<{ key: number; value: string }>`json_each(${chainJson})`.as('c'))
+ .innerJoin('session_event as e', join =>
+ join
+ .on('e.tenant_id', '=', input.tenant_id)
+ .on('e.session_id', '=', input.session_id)
+ .on(sql<boolean>`e.turn_id = c.value`),
+ )
+ .select([sql<string>`c.value`.as('turn_id'), jsonText<SessionEventItem['event']>(sql.ref('e.event')).as('event')])
+ .orderBy(sql`c.key`, 'desc')
+ .orderBy('e.event_id', 'desc')
+ .limit(limit + 1)
+ .offset(cursor.offset)
+ .execute();
+
+ return paginateSessionEventRows(rows, limit, cursor);
+}
diff --git a/packages/server/src/db/sqlite/session-store/queries/sessions.ts b/packages/server/src/db/sqlite/session-store/queries/sessions.ts
new file mode 100644
index 000000000..3a81088c4
--- /dev/null
+++ b/packages/server/src/db/sqlite/session-store/queries/sessions.ts
@@ -0,0 +1,192 @@
+import type { AgentSpec } from '@truefoundry/utils/agent-session';
+import type { SessionRecord } from '@truefoundry/utils/agent-session/models/SessionRecord';
+import type {
+ CreateSessionInput,
+ GetSessionInput,
+ ListSessionsInput,
+ UpdateSessionInput,
+} from '@truefoundry/utils/agent-session/store/ISessionStore';
+import { decodeOffsetPageToken, paginateOffsetRows } from '@truefoundry/utils/agent-session/store/OffsetPageToken';
+import {
+ SessionAlreadyExistsError,
+ SessionNotFoundError,
+ SessionStoreInvariantError,
+} from '@truefoundry/utils/agent-session/store/SessionStoreErrors';
+import { sql, type Kysely } from 'kysely';
+import { isUniqueViolation } from '../../client';
+import type { Database } from '../../types';
+import { jsonbBind, jsonText, nowIso } from '../sqlExpressions';
+
+type SessionCustom = Record<string, never>;
+type ProtoSessionRecord = SessionRecord<SessionCustom>;
+
+function isEmptyCustomRecord(value: Record<string, unknown>): value is SessionCustom {
+ return Object.keys(value).length === 0;
+}
+
+function parseSessionCustom(value: Record<string, unknown> | null): SessionCustom | null {
+ if (value === null) {
+ return null;
+ }
+ if (!isEmptyCustomRecord(value)) {
+ throw new SessionStoreInvariantError('non-empty session custom is not supported');
+ }
+ return value;
+}
+
+function mapRowToSessionRecord(row: {
+ tenant_id: string;
+ session_id: string;
+ agent_spec: AgentSpec;
+ title: string | null;
+ last_turn_id: string | null;
+ custom: Record<string, unknown> | null;
+ created_at: string;
+ updated_at: string;
+ last_activity_timestamp_ms: number;
+}): ProtoSessionRecord {
+ return {
+ tenant_id: row.tenant_id,
+ session_id: row.session_id,
+ agent_spec: row.agent_spec,
+ title: row.title,
+ last_turn_id: row.last_turn_id,
+ custom: parseSessionCustom(row.custom),
+ created_at: new Date(row.created_at),
+ updated_at: new Date(row.updated_at),
+ last_activity_timestamp_ms: row.last_activity_timestamp_ms,
+ };
+}
+
+export async function createSession(db: Kysely<Database>, input: CreateSessionInput<SessionCustom>): Promise<void> {
+ const now = nowIso();
+
+ try {
+ await db
+ .insertInto('session')
+ .values({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ agent_spec: jsonbBind(input.agent_spec),
+ title: null,
+ custom: input.custom !== null ? jsonbBind(input.custom) : null,
+ created_at: now,
+ updated_at: now,
+ last_activity_timestamp_ms: Date.now(),
+ })
+ .execute();
+ } catch (error) {
+ if (isUniqueViolation(error)) {
+ throw new SessionAlreadyExistsError(input.session_id, { cause: error });
+ }
+ throw error;
+ }
+}
+
+export async function getSession(
+ db: Kysely<Database>,
+ input: GetSessionInput,
+): Promise<ProtoSessionRecord | undefined> {
+ const row = await db
+ .selectFrom('session')
+ .select([
+ 'tenant_id',
+ 'session_id',
+ jsonText<AgentSpec>(sql.ref('agent_spec')).as('agent_spec'),
+ 'title',
+ 'last_turn_id',
+ jsonText<Record<string, unknown> | null>(sql.ref('custom')).as('custom'),
+ 'created_at',
+ 'updated_at',
+ 'last_activity_timestamp_ms',
+ ])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .executeTakeFirst();
+
+ if (row === undefined) {
+ return undefined;
+ }
+
+ return mapRowToSessionRecord(row);
+}
+
+export async function updateSession(db: Kysely<Database>, input: UpdateSessionInput<SessionCustom>): Promise<void> {
+ const agentSpec = input.agent_spec;
+ const title = input.title;
+
+ let qb = db
+ .updateTable('session')
+ .set({
+ updated_at: nowIso(),
+ last_activity_timestamp_ms: Date.now(),
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id);
+
+ if (agentSpec !== undefined) {
+ qb = qb.set({ agent_spec: jsonbBind(agentSpec) });
+ }
+ if (title !== undefined) {
+ qb = qb.set({ title });
+ }
+
+ const result = await qb.executeTakeFirst();
+
+ const numUpdatedRows = Number(result.numUpdatedRows);
+ if (numUpdatedRows === 0) {
+ throw new SessionNotFoundError(input.session_id);
+ }
+}
+
+export async function listSessions(
+ db: Kysely<Database>,
+ input: ListSessionsInput,
+): Promise<{
+ data: ProtoSessionRecord[];
+ pagination: { next_page_token?: string | undefined; previous_page_token?: string | undefined };
+}> {
+ const limit = input.limit;
+ const offset = decodeOffsetPageToken(input.page_token);
+ const order = input.order ?? 'desc';
+
+ let query = db
+ .selectFrom('session')
+ .select([
+ 'tenant_id',
+ 'session_id',
+ jsonText<AgentSpec>(sql.ref('agent_spec')).as('agent_spec'),
+ 'title',
+ 'last_turn_id',
+ jsonText<Record<string, unknown> | null>(sql.ref('custom')).as('custom'),
+ 'created_at',
+ 'updated_at',
+ 'last_activity_timestamp_ms',
+ ])
+ .where('tenant_id', '=', input.tenant_id);
+
+ if (input.start_timestamp !== undefined) {
+ query = query.where('created_at', '>=', input.start_timestamp.toISOString());
+ }
+ if (input.end_timestamp !== undefined) {
+ query = query.where('created_at', '<=', input.end_timestamp.toISOString());
+ }
+
+ if (order === 'asc') {
+ query = query.orderBy('created_at', 'asc').orderBy('session_id', 'asc');
+ } else {
+ query = query.orderBy('created_at', 'desc').orderBy('session_id', 'desc');
+ }
+
+ const rows = await query
+ .limit(limit + 1)
+ .offset(offset)
+ .execute();
+
+ const { data, pagination } = paginateOffsetRows(rows, limit, offset);
+
+ return {
+ data: data.map(mapRowToSessionRecord),
+ pagination,
+ };
+}
diff --git a/packages/server/src/db/sqlite/session-store/queries/threads.ts b/packages/server/src/db/sqlite/session-store/queries/threads.ts
new file mode 100644
index 000000000..ab0f211b9
--- /dev/null
+++ b/packages/server/src/db/sqlite/session-store/queries/threads.ts
@@ -0,0 +1,455 @@
+import type {
+ AddThreadsInput,
+ AppendToThreadContextInput,
+ OverwriteThreadContextInput,
+ PatchMCPServersInput,
+ PatchSandboxInfoInput,
+ RemoveThreadsInput,
+} from '@truefoundry/utils/agent-session/store/ISessionStore';
+import type { ContextMessage, SubAgentCompletionMarker } from '@truefoundry/utils/core/runtime/AgentThread.types';
+import type { CurrentContextUsage } from '@truefoundry/utils/core/runtime/contextUsage';
+import { sql, type Kysely, type RawBuilder, type Transaction } from 'kysely';
+import type { Database, TurnThreadCheckpoint } from '../../types';
+import { jsonbBind, jsonbSet, nowIso, sortedByAppendId } from '../sqlExpressions';
+import {
+ assertTurnRunning,
+ classifyTurnFenceWriteFailure,
+ classifyTurnThreadWriteFailure,
+ type TurnKeys,
+} from './turns';
+
+type DbOrTrx = Kysely<Database> | Transaction<Database>;
+
+/**
+ * addThreads — fenced tx: INSERT log rows, INSERT turn_thread rows,
+ * INSERT turn_thread_context rows, INSERT capability rows.
+ */
+export async function addThreads(db: Kysely<Database>, input: AddThreadsInput): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await assertTurnRunning(trx, {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ });
+
+ const now = nowIso();
+ const logRows: {
+ tenant_id: string;
+ session_id: string;
+ thread_id: string;
+ turn_id: string;
+ body: RawBuilder<string>;
+ created_at: string;
+ }[] = [];
+ const capabilityStateRows: {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ thread_id: string;
+ key: string;
+ state: RawBuilder<string> | null;
+ updated_at: string;
+ }[] = [];
+ const turnThreadPlans: {
+ thread_id: string;
+ checkpoint: TurnThreadCheckpoint;
+ agent_info: RawBuilder<string> | null;
+ current_context_usage: CurrentContextUsage;
+ }[] = [];
+
+ for (const thread of input.threads) {
+ const threadCheckpoint: TurnThreadCheckpoint = {
+ parent: thread.parent ?? null,
+ completion: thread.completion ?? null,
+ };
+ turnThreadPlans.push({
+ thread_id: thread.thread_id,
+ checkpoint: threadCheckpoint,
+ agent_info: thread.agent_info != null ? jsonbBind(thread.agent_info) : null,
+ current_context_usage: thread.current_context_usage,
+ });
+
+ for (const body of thread.context) {
+ logRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ thread_id: thread.thread_id,
+ turn_id: input.turn_id,
+ body: jsonbBind(body),
+ created_at: now,
+ });
+ }
+
+ const capabilityState = thread.capability_state;
+ if (capabilityState != null) {
+ for (const key of Object.keys(capabilityState)) {
+ const state = capabilityState[key];
+ if (state === undefined) {
+ throw new Error(
+ `capability_state['${key}'] for thread '${thread.thread_id}' is undefined — undefined is banned from capability state`,
+ );
+ }
+ capabilityStateRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ thread_id: thread.thread_id,
+ key,
+ state: state !== null ? jsonbBind(state) : null,
+ updated_at: now,
+ });
+ }
+ }
+ }
+
+ const newIdsByThread = new Map<string, number[]>();
+ if (logRows.length > 0) {
+ const inserted = await trx
+ .insertInto('thread_context_log')
+ .values(logRows)
+ .returning(['thread_id', 'append_id'])
+ .execute();
+ for (const row of sortedByAppendId(inserted)) {
+ const list = newIdsByThread.get(row.thread_id);
+ if (list === undefined) {
+ newIdsByThread.set(row.thread_id, [row.append_id]);
+ } else {
+ list.push(row.append_id);
+ }
+ }
+ }
+
+ const turnThreadRows = turnThreadPlans.map(plan => ({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ thread_id: plan.thread_id,
+ checkpoint: jsonbBind(plan.checkpoint),
+ agent_info: plan.agent_info,
+ current_context_usage: jsonbBind(plan.current_context_usage),
+ updated_at: now,
+ }));
+
+ if (turnThreadRows.length > 0) {
+ await trx.insertInto('turn_thread').values(turnThreadRows).execute();
+ }
+
+ const contextMappingRows: {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ thread_id: string;
+ pos: number;
+ append_id: number;
+ }[] = [];
+
+ for (const plan of turnThreadPlans) {
+ const newIds = newIdsByThread.get(plan.thread_id) ?? [];
+ for (let i = 0; i < newIds.length; i++) {
+ const appendId = newIds[i];
+ if (appendId !== undefined) {
+ contextMappingRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ thread_id: plan.thread_id,
+ pos: i + 1,
+ append_id: appendId,
+ });
+ }
+ }
+ }
+
+ if (contextMappingRows.length > 0) {
+ await trx.insertInto('turn_thread_context').values(contextMappingRows).execute();
+ }
+
+ if (capabilityStateRows.length > 0) {
+ await trx.insertInto('thread_capability_state').values(capabilityStateRows).execute();
+ }
+ });
+}
+
+/**
+ * removeThreads — fenced tx: DELETE this turn's turn_thread rows,
+ * turn_thread_context rows, and capability rows.
+ * Older turns keep their per-turn maps. Log rows stay (other turns may reference them).
+ * Empty thread_ids is a no-op.
+ */
+export async function removeThreads(db: Kysely<Database>, input: RemoveThreadsInput): Promise<void> {
+ if (input.thread_ids.length === 0) {
+ return;
+ }
+
+ await db.transaction().execute(async trx => {
+ await assertTurnRunning(trx, {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ });
+
+ await trx
+ .deleteFrom('turn_thread_context')
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .where('thread_id', 'in', input.thread_ids)
+ .execute();
+
+ await trx
+ .deleteFrom('turn_thread')
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .where('thread_id', 'in', input.thread_ids)
+ .execute();
+
+ await trx
+ .deleteFrom('thread_capability_state')
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .where('thread_id', 'in', input.thread_ids)
+ .execute();
+ });
+}
+
+async function getNextPos(db: DbOrTrx, keys: TurnKeys, thread_id: string): Promise<number> {
+ const maxRow = await db
+ .selectFrom('turn_thread_context')
+ .select([sql<number | null>`MAX(pos)`.as('max_pos')])
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .where('thread_id', '=', thread_id)
+ .executeTakeFirst();
+ return (maxRow?.max_pos ?? 0) + 1;
+}
+
+function completionPatchExpr(completion: SubAgentCompletionMarker | null): RawBuilder<string> {
+ if (completion === null) {
+ return sql`checkpoint`;
+ }
+ return jsonbSet(sql.ref('checkpoint'), '$.completion', completion);
+}
+
+function usageSetExpr(usage: CurrentContextUsage | null): RawBuilder<string> {
+ if (usage === null) {
+ return sql`current_context_usage`;
+ }
+ return sql`coalesce(${jsonbBind(usage)}, current_context_usage)`;
+}
+
+async function fencedTurnThreadContextUpdate(
+ db: Kysely<Database>,
+ args: {
+ keys: TurnKeys;
+ thread_id: string;
+ context: ContextMessage[];
+ replace_array: boolean;
+ current_context_usage: CurrentContextUsage | null;
+ completion: SubAgentCompletionMarker | null;
+ /** When replace_array, usage is set unconditionally (overwrite contract). */
+ usage_unconditional: CurrentContextUsage | null;
+ },
+): Promise<void> {
+ const { keys, thread_id, context, replace_array } = args;
+
+ await db.transaction().execute(async trx => {
+ await assertTurnRunning(trx, keys);
+
+ const now = nowIso();
+
+ if (replace_array) {
+ await trx
+ .deleteFrom('turn_thread_context')
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .where('thread_id', '=', thread_id)
+ .execute();
+ }
+
+ if (context.length > 0) {
+ const logRows = context.map(body => ({
+ tenant_id: keys.tenant_id,
+ session_id: keys.session_id,
+ thread_id,
+ turn_id: keys.turn_id,
+ body: jsonbBind(body),
+ created_at: now,
+ }));
+
+ const inserted = await trx.insertInto('thread_context_log').values(logRows).returning(['append_id']).execute();
+
+ let nextPos = replace_array ? 1 : await getNextPos(trx, keys, thread_id);
+
+ const contextMappingRows: {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ thread_id: string;
+ pos: number;
+ append_id: number;
+ }[] = [];
+
+ for (const row of sortedByAppendId(inserted)) {
+ contextMappingRows.push({
+ tenant_id: keys.tenant_id,
+ session_id: keys.session_id,
+ turn_id: keys.turn_id,
+ thread_id,
+ pos: nextPos,
+ append_id: row.append_id,
+ });
+ nextPos++;
+ }
+
+ if (contextMappingRows.length > 0) {
+ await trx.insertInto('turn_thread_context').values(contextMappingRows).execute();
+ }
+ }
+
+ const usageExpr =
+ args.usage_unconditional !== null
+ ? jsonbBind(args.usage_unconditional)
+ : usageSetExpr(args.current_context_usage);
+
+ const updateResult = await trx
+ .updateTable('turn_thread')
+ .set({
+ checkpoint: completionPatchExpr(args.completion),
+ current_context_usage: usageExpr,
+ updated_at: now,
+ })
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .where('thread_id', '=', thread_id)
+ .executeTakeFirst();
+
+ if (Number(updateResult.numUpdatedRows) === 0) {
+ await classifyTurnThreadWriteFailure(trx, keys, thread_id);
+ }
+ });
+}
+
+/**
+ * appendToThreadContext — fenced transaction: inserts log rows, appends mapping rows,
+ * updates usage (COALESCE: provided wins, else keep), patches completion.
+ */
+export async function appendToThreadContext(db: Kysely<Database>, input: AppendToThreadContextInput): Promise<void> {
+ await fencedTurnThreadContextUpdate(db, {
+ keys: {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ },
+ thread_id: input.thread_id,
+ context: input.context,
+ replace_array: false,
+ current_context_usage: input.current_context_usage,
+ completion: input.completion,
+ usage_unconditional: null,
+ });
+}
+
+/**
+ * overwriteThreadContext — same fenced shape; context mapping is REPLACED.
+ * Old log rows stay — ancestor turns' context mapping may reference them.
+ */
+export async function overwriteThreadContext(db: Kysely<Database>, input: OverwriteThreadContextInput): Promise<void> {
+ await fencedTurnThreadContextUpdate(db, {
+ keys: {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ },
+ thread_id: input.event.thread_id,
+ context: input.event.context,
+ replace_array: true,
+ current_context_usage: null,
+ completion: null,
+ usage_unconditional: input.event.current_context_usage,
+ });
+}
+
+/**
+ * patchMCPServers — conditional UPDATE fenced on state->>'status'='running'.
+ * Shallow merge by server id (Postgres `||`): patched ids replace wholesale.
+ */
+export async function patchMCPServers(db: Kysely<Database>, input: PatchMCPServersInput): Promise<void> {
+ const serversById: Record<string, (typeof input.mcp_servers)[number]> = {};
+ for (const server of input.mcp_servers) {
+ serversById[server.id] = server;
+ }
+
+ const keys: TurnKeys = {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ };
+
+ // jsonb_patch is RFC 7396 (deep); rebuild via json_each so each id's value is replaced.
+ const patchJson = JSON.stringify(serversById);
+
+ const result = await db
+ .updateTable('turn')
+ .set({
+ checkpoint: sql<string>`jsonb_set(
+ checkpoint,
+ '$.mcp_servers',
+ coalesce((
+ SELECT jsonb_group_object(key, jsonb(value))
+ FROM (
+ SELECT key, value
+ FROM json_each(
+ CASE WHEN json_type(checkpoint, '$.mcp_servers') = 'object'
+ THEN json(jsonb_extract(checkpoint, '$.mcp_servers'))
+ ELSE '{}' END
+ )
+ WHERE key NOT IN (SELECT key FROM json_each(${patchJson}))
+ UNION ALL
+ SELECT key, value FROM json_each(${patchJson})
+ )
+ ), jsonb('{}'))
+ )`,
+ updated_at: nowIso(),
+ })
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .where(sql<boolean>`state->>'status' = 'running'`)
+ .executeTakeFirst();
+
+ if (Number(result.numUpdatedRows) === 0) {
+ await classifyTurnFenceWriteFailure(db, keys);
+ }
+}
+
+/**
+ * patchSandboxInfo — LWW replace via jsonb_set on sandbox_info key.
+ */
+export async function patchSandboxInfo(db: Kysely<Database>, input: PatchSandboxInfoInput): Promise<void> {
+ const keys: TurnKeys = {
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ };
+
+ const result = await db
+ .updateTable('turn')
+ .set({
+ checkpoint: jsonbSet(sql.ref('checkpoint'), '$.sandbox_info', input.sandbox_info),
+ updated_at: nowIso(),
+ })
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .where(sql<boolean>`state->>'status' = 'running'`)
+ .executeTakeFirst();
+
+ if (Number(result.numUpdatedRows) === 0) {
+ await classifyTurnFenceWriteFailure(db, keys);
+ }
+}
diff --git a/packages/server/src/db/sqlite/session-store/queries/turns.ts b/packages/server/src/db/sqlite/session-store/queries/turns.ts
new file mode 100644
index 000000000..545046ed4
--- /dev/null
+++ b/packages/server/src/db/sqlite/session-store/queries/turns.ts
@@ -0,0 +1,818 @@
+import type { TurnRecord, TurnSnapshot } from '@truefoundry/utils/agent-session/models/TurnRecord';
+import {
+ CancellationReason,
+ type TerminalTurnState,
+ type TurnInputItem,
+ type TurnState,
+} from '@truefoundry/utils/agent-session/schemas/turn';
+import { assertCreateTurnThreadDelta } from '@truefoundry/utils/agent-session/store/assertCreateTurnThreadDelta';
+import type {
+ FreezeAndGetTurnInput,
+ TurnRecordWithoutSnapshot,
+ UpdateTurnStateInput,
+} from '@truefoundry/utils/agent-session/store/ISessionStore';
+import {
+ PreviousTurnRunningError,
+ SessionNotFoundError,
+ SessionStoreConflictError,
+ SessionStoreInvariantError,
+ SessionStoreNotFoundError,
+ TurnAlreadyExistsError,
+ TurnNotFoundError,
+ TurnNotRunningError,
+} from '@truefoundry/utils/agent-session/store/SessionStoreErrors';
+import type { CapabilityState, JsonValue } from '@truefoundry/utils/core/capabilities/AgentCapability';
+import type { AgentInfo, AgentParent, MCPServerInitInfo } from '@truefoundry/utils/core/events/schema';
+import type { AgentThreadSnapshot, ContextMessage } from '@truefoundry/utils/core/runtime/AgentThread.types';
+import type { CurrentContextUsage } from '@truefoundry/utils/core/runtime/contextUsage';
+import { getEmptyCurrentContextUsage } from '@truefoundry/utils/core/runtime/contextUsage';
+import type { SandboxInfo } from '@truefoundry/utils/core/sandbox/Sandbox';
+import { sql, type Kysely, type RawBuilder, type Transaction } from 'kysely';
+import { isUniqueViolation } from '../../client';
+import type { Database, TurnCheckpoint, TurnThreadCheckpoint } from '../../types';
+import { jsonbBind, jsonText, nowIso, sortedByAppendId } from '../sqlExpressions';
+
+type TurnCustom = Record<string, never>;
+
+function isEmptyCustomRecord(value: Record<string, unknown>): value is TurnCustom {
+ return Object.keys(value).length === 0;
+}
+
+function parseTurnCustom(value: Record<string, unknown> | null): TurnCustom | null {
+ if (value === null) {
+ return null;
+ }
+ if (!isEmptyCustomRecord(value)) {
+ throw new SessionStoreInvariantError('non-empty turn custom is not supported');
+ }
+ return value;
+}
+
+/** New thread metadata; mutable per-turn data arrives through dedicated fields. */
+export interface NewThreadRegistration {
+ thread_id: string;
+ parent: AgentParent | null;
+ agent_info: AgentInfo | null;
+}
+
+export interface TurnKeys {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+}
+
+export interface NewContextAppend {
+ thread_id: string;
+ context: ContextMessage[];
+ current_context_usage: CurrentContextUsage | null;
+}
+
+export interface CreateTurnTurnFields {
+ turn_id: string;
+ first_turn_id: string;
+ previous_turn_id: string | null;
+ ancestor_ids: string[];
+ input: TurnInputItem[];
+ state: TurnState;
+ custom: Record<string, unknown> | null;
+}
+
+export interface CreateTurnInput {
+ tenant_id: string;
+ session_id: string;
+ turn: CreateTurnTurnFields;
+ new_threads: NewThreadRegistration[];
+ new_context_appends: NewContextAppend[];
+ capability_states: {
+ thread_id: string;
+ capability_state: CapabilityState | null;
+ }[];
+ last_activity_timestamp_ms: number;
+ update_session_title_if_not_exist: string | null;
+ mcp_servers: Record<string, MCPServerInitInfo> | null;
+ sandbox_info: SandboxInfo | null;
+}
+
+export interface GetTurnInput {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+}
+
+export interface ListTurnsInput {
+ tenant_id: string;
+ session_id: string;
+ limit: number;
+ offset: number;
+}
+
+export interface ListTurnsResult {
+ turns: TurnRecordWithoutSnapshot<TurnCustom>[];
+ next_offset: number | null;
+}
+
+type DbOrTrx = Kysely<Database> | Transaction<Database>;
+
+function terminalTurnState(state: TurnState, turn_id: string): TerminalTurnState {
+ switch (state.status) {
+ case 'running':
+ throw new SessionStoreInvariantError(`expected terminal state for turn ${turn_id}, got running`);
+ case 'done':
+ case 'cancelled':
+ case 'error':
+ return state;
+ }
+}
+
+async function loadTurnState(db: DbOrTrx, keys: TurnKeys): Promise<TurnState | undefined> {
+ const row = await db
+ .selectFrom('turn')
+ .select([jsonText<TurnState>(sql.ref('state')).as('state')])
+ .where('tenant_id', '=', keys.tenant_id)
+ .where('session_id', '=', keys.session_id)
+ .where('turn_id', '=', keys.turn_id)
+ .executeTakeFirst();
+ return row?.state;
+}
+
+/** Classify a 0-row fenced write: missing turn vs frozen/non-running turn. */
+export async function classifyTurnFenceWriteFailure(db: DbOrTrx, keys: TurnKeys): Promise<never> {
+ const state = await loadTurnState(db, keys);
+ if (!state) {
+ throw new TurnNotFoundError(keys.turn_id);
+ }
+ throw new TurnNotRunningError(keys.turn_id, terminalTurnState(state, keys.turn_id));
+}
+
+/**
+ * Classify a 0-row fenced turn_thread UPDATE: turn missing/terminal vs thread row missing.
+ */
+export async function classifyTurnThreadWriteFailure(db: DbOrTrx, keys: TurnKeys, thread_id: string): Promise<never> {
+ const state = await loadTurnState(db, keys);
+ if (!state) {
+ throw new TurnNotFoundError(keys.turn_id);
+ }
+ if (state.status !== 'running') {
+ throw new TurnNotRunningError(keys.turn_id, terminalTurnState(state, keys.turn_id));
+ }
+ throw new SessionStoreInvariantError(`thread ${thread_id} not found in turn ${keys.turn_id}`);
+}
+
+export async function assertTurnRunning(db: DbOrTrx, keys: TurnKeys): Promise<void> {
+ const state = await loadTurnState(db, keys);
+ if (!state) {
+ throw new TurnNotFoundError(keys.turn_id);
+ }
+ if (state.status !== 'running') {
+ throw new TurnNotRunningError(keys.turn_id, terminalTurnState(state, keys.turn_id));
+ }
+}
+
+interface CapabilityAggRow {
+ thread_id: string;
+ capability_state: Record<string, JsonValue> | null;
+}
+
+async function assembleTurnRecord(
+ db: DbOrTrx,
+ args: { tenant_id: string; session_id: string; turn_id: string },
+): Promise<TurnRecord<TurnCustom> | undefined> {
+ const turn = await db
+ .selectFrom('turn')
+ .select([
+ 'tenant_id',
+ 'session_id',
+ 'turn_id',
+ 'first_turn_id',
+ 'previous_turn_id',
+ jsonText<string[]>(sql.ref('ancestor_ids')).as('ancestor_ids'),
+ jsonText<TurnInputItem[]>(sql.ref('input')).as('input'),
+ jsonText<TurnState>(sql.ref('state')).as('state'),
+ jsonText<TurnCheckpoint>(sql.ref('checkpoint')).as('checkpoint'),
+ jsonText<Record<string, unknown> | null>(sql.ref('custom')).as('custom'),
+ 'created_at',
+ 'updated_at',
+ ])
+ .where('tenant_id', '=', args.tenant_id)
+ .where('session_id', '=', args.session_id)
+ .where('turn_id', '=', args.turn_id)
+ .executeTakeFirst();
+
+ if (!turn) return undefined;
+
+ // LEFT JOIN turn_thread + turn_thread_context ORDER BY pos to assemble context per thread.
+ // Empty-context threads emit one row with null pos/append_id from the LEFT JOIN.
+ const contextRows = await db
+ .selectFrom('turn_thread as tt')
+ .leftJoin('turn_thread_context as ttc', join =>
+ join
+ .on('ttc.tenant_id', '=', args.tenant_id)
+ .on('ttc.session_id', '=', args.session_id)
+ .on('ttc.turn_id', '=', args.turn_id)
+ .onRef('ttc.thread_id', '=', 'tt.thread_id'),
+ )
+ .leftJoin('thread_context_log as l', join =>
+ join
+ .on('l.tenant_id', '=', args.tenant_id)
+ .on('l.session_id', '=', args.session_id)
+ .onRef('l.thread_id', '=', 'tt.thread_id')
+ .onRef('l.append_id', '=', 'ttc.append_id'),
+ )
+ .select([
+ 'tt.thread_id',
+ jsonText<TurnThreadCheckpoint>(sql.ref('tt.checkpoint')).as('checkpoint'),
+ jsonText<AgentInfo | null>(sql.ref('tt.agent_info')).as('agent_info'),
+ jsonText<CurrentContextUsage>(sql.ref('tt.current_context_usage')).as('current_context_usage'),
+ jsonText<ContextMessage | null>(sql.ref('l.body')).as('body'),
+ 'ttc.pos',
+ ])
+ .where('tt.tenant_id', '=', args.tenant_id)
+ .where('tt.session_id', '=', args.session_id)
+ .where('tt.turn_id', '=', args.turn_id)
+ .orderBy('tt.thread_id')
+ .orderBy('ttc.pos')
+ .execute();
+
+ const capabilityRows: CapabilityAggRow[] = await db
+ .selectFrom('thread_capability_state')
+ .select([
+ 'thread_id',
+ sql<Record<string, JsonValue> | null>`json(jsonb_group_object(key, json(state)))`.as('capability_state'),
+ ])
+ .where('tenant_id', '=', args.tenant_id)
+ .where('session_id', '=', args.session_id)
+ .where('turn_id', '=', args.turn_id)
+ .groupBy('thread_id')
+ .execute();
+
+ const capabilityByThread = new Map<string, Record<string, JsonValue>>();
+ for (const row of capabilityRows) {
+ if (row.capability_state !== null) {
+ capabilityByThread.set(row.thread_id, row.capability_state);
+ }
+ }
+
+ const threads: Record<string, AgentThreadSnapshot> = {};
+ const orderedBodies = new Map<string, ContextMessage[]>();
+ const threadMeta = new Map<
+ string,
+ {
+ checkpoint: TurnThreadCheckpoint;
+ agent_info: AgentInfo | null;
+ current_context_usage: CurrentContextUsage;
+ }
+ >();
+
+ for (const row of contextRows) {
+ if (!threadMeta.has(row.thread_id)) {
+ threadMeta.set(row.thread_id, {
+ checkpoint: row.checkpoint,
+ agent_info: row.agent_info,
+ current_context_usage: row.current_context_usage,
+ });
+ orderedBodies.set(row.thread_id, []);
+ }
+ if (row.body !== null) {
+ const bodies = orderedBodies.get(row.thread_id);
+ if (bodies !== undefined) {
+ bodies.push(row.body);
+ }
+ }
+ }
+
+ for (const [threadId, meta] of threadMeta) {
+ const context = orderedBodies.get(threadId) ?? [];
+ const capability_state = capabilityByThread.get(threadId) ?? null;
+
+ const snap: AgentThreadSnapshot = {
+ thread_id: threadId,
+ context,
+ current_context_usage: meta.current_context_usage,
+ parent: meta.checkpoint.parent,
+ agent_info: meta.agent_info,
+ completion: meta.checkpoint.completion,
+ capability_state,
+ };
+ threads[threadId] = snap;
+ }
+
+ const checkpoint = turn.checkpoint;
+ const snapshot: TurnSnapshot = {
+ threads,
+ mcp_servers: checkpoint.mcp_servers,
+ sandbox_info: checkpoint.sandbox_info,
+ };
+
+ return {
+ turn_id: turn.turn_id,
+ session_id: turn.session_id,
+ first_turn_id: turn.first_turn_id,
+ ancestor_ids: turn.ancestor_ids,
+ previous_turn_id: turn.previous_turn_id,
+ state: turn.state,
+ input: turn.input,
+ snapshot,
+ created_at: new Date(turn.created_at),
+ updated_at: new Date(turn.updated_at),
+ custom: parseTurnCustom(turn.custom),
+ };
+}
+
+/**
+ * createTurn — IMMEDIATE tx (BEGIN IMMEDIATE covers write locking; no FOR UPDATE/FOR SHARE).
+ * Context order lives in turn_thread_context (pos, append_id); no context_ids array.
+ */
+export async function createTurn(db: Kysely<Database>, input: CreateTurnInput): Promise<void> {
+ try {
+ await db.transaction().execute(async trx => {
+ // Step 1: read session tip; no FOR UPDATE (BEGIN IMMEDIATE is the lock).
+ const locked = await trx
+ .selectFrom('session')
+ .select(['last_turn_id'])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .executeTakeFirst();
+
+ if (!locked) throw new SessionNotFoundError(input.session_id);
+
+ // Step 2: bump session tip + optional title coalesce.
+ let sessionUpdate = trx
+ .updateTable('session')
+ .set({
+ last_turn_id: input.turn.turn_id,
+ updated_at: nowIso(),
+ last_activity_timestamp_ms: input.last_activity_timestamp_ms,
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id);
+
+ if (input.update_session_title_if_not_exist !== null) {
+ const titleValue = input.update_session_title_if_not_exist;
+ sessionUpdate = sessionUpdate.set({
+ title: sql<string>`COALESCE(title, ${titleValue})`,
+ });
+ }
+
+ await sessionUpdate.execute();
+
+ const prevTurnId = input.turn.previous_turn_id;
+
+ let prevCheckpoint: TurnCheckpoint | null = null;
+ const prevThreadRows: {
+ thread_id: string;
+ checkpoint: TurnThreadCheckpoint;
+ agent_info: AgentInfo | null;
+ current_context_usage: CurrentContextUsage;
+ context_pos_max: number;
+ }[] = [];
+
+ if (prevTurnId != null) {
+ // Read previous turn + its turn_thread rows in one join.
+ const prevRows = await trx
+ .selectFrom('turn as t')
+ .leftJoin('turn_thread as tt', join =>
+ join
+ .onRef('tt.tenant_id', '=', 't.tenant_id')
+ .onRef('tt.session_id', '=', 't.session_id')
+ .onRef('tt.turn_id', '=', 't.turn_id'),
+ )
+ .leftJoin(
+ db
+ .selectFrom('turn_thread_context')
+ .select(['thread_id', 'turn_id', sql<number>`MAX(pos)`.as('max_pos')])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', prevTurnId)
+ .groupBy(['thread_id', 'turn_id'])
+ .as('tc_agg'),
+ join => join.onRef('tc_agg.thread_id', '=', 'tt.thread_id').onRef('tc_agg.turn_id', '=', 'tt.turn_id'),
+ )
+ .select([
+ jsonText<TurnCheckpoint>(sql.ref('t.checkpoint')).as('turn_checkpoint'),
+ jsonText<TurnState>(sql.ref('t.state')).as('turn_state'),
+ 'tt.thread_id',
+ jsonText<TurnThreadCheckpoint | null>(sql.ref('tt.checkpoint')).as('thread_checkpoint'),
+ jsonText<AgentInfo | null>(sql.ref('tt.agent_info')).as('agent_info'),
+ jsonText<CurrentContextUsage | null>(sql.ref('tt.current_context_usage')).as('current_context_usage'),
+ 'tc_agg.max_pos',
+ ])
+ .where('t.tenant_id', '=', input.tenant_id)
+ .where('t.session_id', '=', input.session_id)
+ .where('t.turn_id', '=', prevTurnId)
+ .execute();
+
+ const first = prevRows[0];
+ if (first !== undefined) {
+ if (first.turn_state.status === 'running') {
+ throw new PreviousTurnRunningError(prevTurnId);
+ }
+ prevCheckpoint = first.turn_checkpoint;
+
+ for (const row of prevRows) {
+ if (row.thread_id === null) continue;
+ if (row.thread_checkpoint === null || row.current_context_usage === null) {
+ throw new SessionStoreInvariantError(`previous turn_thread row for ${row.thread_id} is incomplete`);
+ }
+ prevThreadRows.push({
+ thread_id: row.thread_id,
+ checkpoint: row.thread_checkpoint,
+ agent_info: row.agent_info,
+ current_context_usage: row.current_context_usage,
+ context_pos_max: row.max_pos ?? 0,
+ });
+ }
+ }
+ }
+
+ assertCreateTurnThreadDelta({
+ previousThreadIds: new Set(prevThreadRows.map(r => r.thread_id)),
+ new_threads: input.new_threads,
+ new_context_appends: input.new_context_appends,
+ capability_states: input.capability_states,
+ });
+
+ const checkpoint: TurnCheckpoint = {
+ mcp_servers: input.mcp_servers ?? prevCheckpoint?.mcp_servers ?? null,
+ sandbox_info: input.sandbox_info ?? prevCheckpoint?.sandbox_info ?? null,
+ };
+
+ const now = nowIso();
+
+ const turnCustom = input.turn.custom ?? null;
+
+ // Step 3: insert turn row.
+ await trx
+ .insertInto('turn')
+ .values({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn.turn_id,
+ first_turn_id: input.turn.first_turn_id,
+ previous_turn_id: input.turn.previous_turn_id ?? null,
+ ancestor_ids: jsonbBind(input.turn.ancestor_ids),
+ input: jsonbBind(input.turn.input),
+ state: jsonbBind(input.turn.state),
+ checkpoint: jsonbBind(checkpoint),
+ custom: turnCustom !== null ? jsonbBind(turnCustom) : null,
+ created_at: now,
+ updated_at: now,
+ })
+ .execute();
+
+ // Step 4: insert new context log rows.
+ const logRows: {
+ tenant_id: string;
+ session_id: string;
+ thread_id: string;
+ turn_id: string;
+ body: RawBuilder<string>;
+ created_at: string;
+ }[] = [];
+
+ for (const append of input.new_context_appends) {
+ for (const body of append.context) {
+ logRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ thread_id: append.thread_id,
+ turn_id: input.turn.turn_id,
+ body: jsonbBind(body),
+ created_at: now,
+ });
+ }
+ }
+
+ const newIdsByThread = new Map<string, number[]>();
+ if (logRows.length > 0) {
+ const inserted = await trx
+ .insertInto('thread_context_log')
+ .values(logRows)
+ .returning(['thread_id', 'append_id'])
+ .execute();
+ for (const row of sortedByAppendId(inserted)) {
+ const list = newIdsByThread.get(row.thread_id);
+ if (list === undefined) {
+ newIdsByThread.set(row.thread_id, [row.append_id]);
+ } else {
+ list.push(row.append_id);
+ }
+ }
+ }
+
+ const appendUsageByThread = new Map<string, CurrentContextUsage>();
+ for (const append of input.new_context_appends) {
+ if (append.current_context_usage !== null) {
+ appendUsageByThread.set(append.thread_id, append.current_context_usage);
+ }
+ }
+
+ // Step 5: insert turn_thread rows for carried-forward and new threads.
+ const turnThreadRows: {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ thread_id: string;
+ checkpoint: RawBuilder<string>;
+ agent_info: RawBuilder<string> | null;
+ current_context_usage: RawBuilder<string>;
+ updated_at: string;
+ }[] = [];
+
+ const turnThreadContextRows: {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ thread_id: string;
+ pos: number;
+ append_id: number;
+ }[] = [];
+
+ for (const parent of prevThreadRows) {
+ const usage = appendUsageByThread.get(parent.thread_id) ?? parent.current_context_usage;
+ turnThreadRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn.turn_id,
+ thread_id: parent.thread_id,
+ checkpoint: jsonbBind(parent.checkpoint),
+ agent_info: parent.agent_info !== null ? jsonbBind(parent.agent_info) : null,
+ current_context_usage: jsonbBind(usage),
+ updated_at: now,
+ });
+ }
+
+ // One SELECT for all parent context mappings (not N+1 per thread).
+ if (prevTurnId != null && prevThreadRows.length > 0) {
+ const parentContextRows = await trx
+ .selectFrom('turn_thread_context')
+ .select(['thread_id', 'pos', 'append_id'])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', prevTurnId)
+ .where(
+ 'thread_id',
+ 'in',
+ prevThreadRows.map(r => r.thread_id),
+ )
+ .orderBy('thread_id')
+ .orderBy('pos')
+ .execute();
+
+ for (const cr of parentContextRows) {
+ turnThreadContextRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn.turn_id,
+ thread_id: cr.thread_id,
+ pos: cr.pos,
+ append_id: cr.append_id,
+ });
+ }
+ }
+
+ for (const parent of prevThreadRows) {
+ const newIds = newIdsByThread.get(parent.thread_id) ?? [];
+ const basePos = parent.context_pos_max;
+ for (let i = 0; i < newIds.length; i++) {
+ const appendId = newIds[i];
+ if (appendId !== undefined) {
+ turnThreadContextRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn.turn_id,
+ thread_id: parent.thread_id,
+ pos: basePos + i + 1,
+ append_id: appendId,
+ });
+ }
+ }
+ }
+
+ // Step 5b: new threads — fresh turn_thread + mapping rows.
+ for (const nt of input.new_threads) {
+ const newIds = newIdsByThread.get(nt.thread_id) ?? [];
+ const usage = appendUsageByThread.get(nt.thread_id) ?? getEmptyCurrentContextUsage();
+ const threadCheckpoint: TurnThreadCheckpoint = {
+ parent: nt.parent,
+ completion: null,
+ };
+ turnThreadRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn.turn_id,
+ thread_id: nt.thread_id,
+ checkpoint: jsonbBind(threadCheckpoint),
+ agent_info: nt.agent_info !== null ? jsonbBind(nt.agent_info) : null,
+ current_context_usage: jsonbBind(usage),
+ updated_at: now,
+ });
+
+ for (let i = 0; i < newIds.length; i++) {
+ const appendId = newIds[i];
+ if (appendId !== undefined) {
+ turnThreadContextRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn.turn_id,
+ thread_id: nt.thread_id,
+ pos: i + 1,
+ append_id: appendId,
+ });
+ }
+ }
+ }
+
+ if (turnThreadRows.length > 0) {
+ await trx.insertInto('turn_thread').values(turnThreadRows).execute();
+ }
+
+ if (turnThreadContextRows.length > 0) {
+ await trx.insertInto('turn_thread_context').values(turnThreadContextRows).execute();
+ }
+
+ // Step 6: insert capability state rows (thread coverage asserted above).
+ const capabilityStateRows: {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ thread_id: string;
+ key: string;
+ state: RawBuilder<string> | null;
+ updated_at: string;
+ }[] = [];
+
+ for (const capability of input.capability_states) {
+ if (capability.capability_state === null) continue;
+ for (const [key, state] of Object.entries(capability.capability_state)) {
+ capabilityStateRows.push({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn.turn_id,
+ thread_id: capability.thread_id,
+ key,
+ state: state !== null ? jsonbBind(state) : null,
+ updated_at: now,
+ });
+ }
+ }
+
+ if (capabilityStateRows.length > 0) {
+ await trx.insertInto('thread_capability_state').values(capabilityStateRows).execute();
+ }
+ });
+ } catch (err) {
+ if (err instanceof SessionStoreNotFoundError || err instanceof SessionStoreConflictError) throw err;
+ if (isUniqueViolation(err)) throw new TurnAlreadyExistsError(input.turn.turn_id, { cause: err });
+ throw err;
+ }
+}
+
+/**
+ * freezeAndGetTurn — cancel if still running, 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> {
+ return await db.transaction().execute(async trx => {
+ const cancelledState: TerminalTurnState = {
+ status: 'cancelled',
+ reason: CancellationReason.CancelledForNextTurn,
+ completed_at: nowIso(),
+ };
+
+ const updateResult = await trx
+ .updateTable('turn')
+ .set({
+ state: jsonbBind(cancelledState),
+ updated_at: nowIso(),
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .where(sql<boolean>`state->>'status' = 'running'`)
+ .executeTakeFirst();
+
+ if (Number(updateResult.numUpdatedRows) > 0) {
+ await trx
+ .insertInto('session_event')
+ .values({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: input.turn_done_event.id,
+ event: jsonbBind(input.turn_done_event),
+ created_at: input.turn_done_event.created_at,
+ })
+ .execute();
+ }
+
+ const record = await assembleTurnRecord(trx, input);
+ if (!record) throw new TurnNotFoundError(input.turn_id);
+ return record;
+ });
+}
+
+/**
+ * getTurn — deferred read tx so assembleTurnRecord's SELECTs share one snapshot.
+ * ImmediateSqliteDriver maps setAccessMode('read only') → BEGIN (not IMMEDIATE).
+ */
+export async function getTurn(db: Kysely<Database>, input: GetTurnInput): Promise<TurnRecord<TurnCustom> | undefined> {
+ return db
+ .transaction()
+ .setAccessMode('read only')
+ .execute(trx => assembleTurnRecord(trx, input));
+}
+
+/**
+ * listTurns — ORDER BY created_at, turn_id; LIMIT limit+1 OFFSET offset.
+ * Returns turn rows only (no snapshot assembly); use getTurn for full TurnRecord.
+ */
+export async function listTurns(db: Kysely<Database>, input: ListTurnsInput): Promise<ListTurnsResult> {
+ const rows = await db
+ .selectFrom('turn')
+ .select([
+ 'session_id',
+ 'turn_id',
+ 'first_turn_id',
+ 'previous_turn_id',
+ jsonText<string[]>(sql.ref('ancestor_ids')).as('ancestor_ids'),
+ jsonText<TurnInputItem[]>(sql.ref('input')).as('input'),
+ jsonText<TurnState>(sql.ref('state')).as('state'),
+ jsonText<Record<string, unknown> | null>(sql.ref('custom')).as('custom'),
+ 'created_at',
+ 'updated_at',
+ ])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .orderBy('created_at', 'asc')
+ .orderBy('turn_id', 'asc')
+ .limit(input.limit + 1)
+ .offset(input.offset)
+ .execute();
+
+ const hasMore = rows.length > input.limit;
+ const page = hasMore ? rows.slice(0, input.limit) : rows;
+
+ const turns: TurnRecordWithoutSnapshot<TurnCustom>[] = page.map(row => ({
+ turn_id: row.turn_id,
+ session_id: row.session_id,
+ first_turn_id: row.first_turn_id,
+ ancestor_ids: row.ancestor_ids,
+ previous_turn_id: row.previous_turn_id,
+ state: row.state,
+ input: row.input,
+ created_at: new Date(row.created_at),
+ updated_at: new Date(row.updated_at),
+ custom: parseTurnCustom(row.custom),
+ }));
+
+ return {
+ turns,
+ next_offset: hasMore ? input.offset + input.limit : null,
+ };
+}
+
+/**
+ * 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> {
+ await db.transaction().execute(async trx => {
+ const result = await trx
+ .updateTable('turn')
+ .set({
+ state: jsonbBind(input.state),
+ updated_at: nowIso(),
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .where(sql<boolean>`state->>'status' = 'running'`)
+ .executeTakeFirst();
+
+ const numUpdated = Number(result.numUpdatedRows);
+ if (numUpdated === 0) {
+ const existing = await trx
+ .selectFrom('turn')
+ .select([jsonText<TurnState>(sql.ref('state')).as('state')])
+ .where('tenant_id', '=', input.tenant_id)
+ .where('session_id', '=', input.session_id)
+ .where('turn_id', '=', input.turn_id)
+ .executeTakeFirst();
+
+ if (!existing) throw new TurnNotFoundError(input.turn_id);
+ throw new TurnNotRunningError(input.turn_id, terminalTurnState(existing.state, input.turn_id));
+ }
+
+ await trx
+ .insertInto('session_event')
+ .values({
+ tenant_id: input.tenant_id,
+ session_id: input.session_id,
+ turn_id: input.turn_id,
+ event_id: input.turn_done_event.id,
+ event: jsonbBind(input.turn_done_event),
+ created_at: input.turn_done_event.created_at,
+ })
+ .execute();
+ });
+}
diff --git a/packages/server/src/db/sqlite/session-store/sqlExpressions.ts b/packages/server/src/db/sqlite/session-store/sqlExpressions.ts
new file mode 100644
index 000000000..fad3f64d3
--- /dev/null
+++ b/packages/server/src/db/sqlite/session-store/sqlExpressions.ts
@@ -0,0 +1,40 @@
+/**
+ * Shared Kysely SQL expression helpers for the SQLite session store.
+ * JSON authority: SQLite JSON1 — bind text via jsonb(?); read via json(column).
+ * ParseJSONResultsPlugin parses top-level json() columns only (see createSqliteDb).
+ */
+import { sql, type Expression, type RawBuilder } from 'kysely';
+
+/** Bind a JS value as SQLite JSONB BLOB (stringify in JS, convert in SQL). */
+export function jsonbBind(value: unknown): RawBuilder<string> {
+ return sql`jsonb(${JSON.stringify(value)})`;
+}
+
+/**
+ * `jsonb_set(column, path, jsonb(?))`.
+ * `path` must be a fixed literal from call sites (e.g. `'$.completion'`).
+ */
+export function jsonbSet(column: Expression<unknown>, path: string, value: unknown): RawBuilder<string> {
+ return sql`jsonb_set(${column}, ${path}, ${jsonbBind(value)})`;
+}
+
+/**
+ * Project a JSONB column to minified text JSON.
+ * With ParseJSONResultsPlugin, the result row field is the parsed JS value typed as `T`.
+ */
+export function jsonText<T>(column: Expression<unknown>): RawBuilder<T> {
+ return sql<T>`json(${column})`;
+}
+
+/** Current UTC instant as ISO-8601 text for TEXT timestamp columns. */
+export function nowIso(): string {
+ return new Date().toISOString();
+}
+
+/**
+ * SQLite RETURNING row order is unspecified. Multi-row INSERT assigns increasing
+ * append_id in VALUES order — sort on that before mapping to pos / per-thread lists.
+ */
+export function sortedByAppendId<T extends { append_id: number }>(rows: readonly T[]): T[] {
+ return [...rows].sort((a, b) => a.append_id - b.append_id);
+}
diff --git a/packages/server/src/db/sqlite/types.ts b/packages/server/src/db/sqlite/types.ts
new file mode 100644
index 000000000..194e7fdb0
--- /dev/null
+++ b/packages/server/src/db/sqlite/types.ts
@@ -0,0 +1,154 @@
+/**
+ * Live app schema for the SQLite-backed session store.
+ * Migrations must not use this type — use `Kysely<unknown>` instead.
+ *
+ * JSON payload columns are BLOB JSONB on disk. Reads must project `json(column)`;
+ * `ParseJSONResultsPlugin` (configured in createSqliteDb) parses those top-level columns only.
+ */
+import type { AgentSpec, PersistedTurnEvent, TurnInputItem, TurnState } from '@truefoundry/utils/agent-session';
+import type {
+ AgentInfo,
+ AgentParent,
+ ContextMessage,
+ JsonValue,
+ MCPServerInitInfo,
+ SandboxInfo,
+ SubAgentCompletionMarker,
+} from '@truefoundry/utils/core';
+import type { CurrentContextUsage } from '@truefoundry/utils/core/runtime/contextUsage';
+import type { ColumnType, Generated, JSONColumnType } from 'kysely';
+
+/**
+ * Trace-level state for one thread at one turn (`turn_thread.checkpoint`).
+ * Total types: `completion` is explicitly null until set — no optional keys.
+ */
+export interface TurnThreadCheckpoint {
+ parent: AgentParent | null;
+ completion: SubAgentCompletionMarker | null;
+}
+
+/** Turn-level checkpoint — threads live in `turn_thread`; only owned top-level keys remain. */
+export interface TurnCheckpoint {
+ mcp_servers: Record<string, MCPServerInitInfo> | null;
+ sandbox_info: SandboxInfo | null;
+}
+
+/** Insert via `jsonbBind()`; select via `jsonText()` (parsed at top-level only). */
+type JsonbColumn<T extends object | null> = JSONColumnType<T, T | string, T | string>;
+
+/**
+ * PRIMARY KEY (tenant_id, session_id)
+ * CREATE INDEX session_list_idx ON session (tenant_id, created_at, session_id)
+ */
+export interface SessionTable {
+ tenant_id: string;
+ session_id: string;
+ agent_spec: JsonbColumn<AgentSpec>;
+ title: string | null;
+ last_turn_id: string | null;
+ custom: JsonbColumn<Record<string, unknown>> | null;
+ created_at: string;
+ updated_at: string;
+ last_activity_timestamp_ms: number;
+}
+
+/**
+ * PRIMARY KEY (tenant_id, session_id, turn_id)
+ * CREATE INDEX turn_list_idx ON turn (tenant_id, session_id, created_at, turn_id)
+ */
+export interface TurnTable {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ first_turn_id: string;
+ previous_turn_id: string | null;
+ /** JSONB array of turn ids — topology only; not a SQL join key. */
+ ancestor_ids: JsonbColumn<string[]>;
+ input: JsonbColumn<TurnInputItem[]>;
+ state: JsonbColumn<TurnState>;
+ checkpoint: JsonbColumn<TurnCheckpoint>;
+ custom: JsonbColumn<Record<string, unknown>> | null;
+ created_at: string;
+ updated_at: string;
+}
+
+/**
+ * Complete state of one thread at one turn.
+ * Context order lives in `turn_thread_context` (no context_ids column).
+ * PRIMARY KEY (tenant_id, session_id, turn_id, thread_id)
+ */
+export interface TurnThreadTable {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ thread_id: string;
+ checkpoint: JsonbColumn<TurnThreadCheckpoint>;
+ agent_info: JsonbColumn<AgentInfo> | null;
+ current_context_usage: JsonbColumn<CurrentContextUsage>;
+ updated_at: string;
+}
+
+/**
+ * Ordered mapping from a turn_thread to append-only log rows.
+ * PRIMARY KEY (tenant_id, session_id, turn_id, thread_id, pos)
+ */
+export interface TurnThreadContextTable {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ thread_id: string;
+ pos: number;
+ append_id: number;
+}
+
+/**
+ * Pure immutable client-facing event log.
+ * PRIMARY KEY (tenant_id, session_id, turn_id, event_id)
+ */
+export interface SessionEventTable {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ event_id: string;
+ event: JsonbColumn<PersistedTurnEvent>;
+ created_at: string;
+}
+
+/**
+ * Pure immutable content; no state → no checkpoint field.
+ * PRIMARY KEY (append_id) AUTOINCREMENT
+ */
+export interface ThreadContextLogTable {
+ append_id: Generated<number>;
+ tenant_id: string;
+ session_id: string;
+ thread_id: string;
+ turn_id: string;
+ body: JsonbColumn<ContextMessage>;
+ created_at: string;
+}
+
+/**
+ * Per-turn KV snapshot, latest-wins per (turn, thread, key).
+ * PRIMARY KEY (tenant_id, session_id, turn_id, thread_id, key)
+ */
+export interface ThreadCapabilityStateTable {
+ tenant_id: string;
+ session_id: string;
+ turn_id: string;
+ thread_id: string;
+ key: string;
+ /** JSONB JsonValue, or SQL NULL if cleared. */
+ state: ColumnType<JsonValue | null, JsonValue | null | string, JsonValue | null | string>;
+ updated_at: string;
+}
+
+export interface Database {
+ session: SessionTable;
+ turn: TurnTable;
+ turn_thread: TurnThreadTable;
+ turn_thread_context: TurnThreadContextTable;
+ session_event: SessionEventTable;
+ thread_context_log: ThreadContextLogTable;
+ thread_capability_state: ThreadCapabilityStateTable;
+}
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 311449cf6..15dca0928 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -1,7 +1,8 @@
/**
- * Server entry point: validates config, migrates the database, loads the YAML
+ * Server entry point: validates config, migrates Postgres, loads the YAML
* stores, wires the Postgres session store and starts the HTTP server.
* Any config, migration, or store error aborts startup.
+ * SQLite migrations are packaged under dist/ but are not run at startup.
*/
import { serve } from '@hono/node-server';
import winston from 'winston';
diff --git a/packages/server/src/schemas/session.ts b/packages/server/src/schemas/session.ts
index 484172b36..ec416da0a 100644
--- a/packages/server/src/schemas/session.ts
+++ b/packages/server/src/schemas/session.ts
@@ -13,6 +13,13 @@ export { CreateSessionRequestSchema, UpdateSessionRequestSchema };
export const DEFAULT_SESSIONS_LIMIT = 10;
export const SESSIONS_MAX_LIMIT = 100;
+/** Wire ISO-8601 (RFC 3339, offsets allowed) → Date for the store. */
+const IsoTimestampQueryParam = z
+ .string()
+ .datetime({ offset: true })
+ .openapi({ type: 'string', format: 'date-time' })
+ .transform(s => new Date(s));
+
export const ListSessionsRequestQuerySchema = z
.object({
limit: z.coerce
@@ -30,8 +37,12 @@ export const ListSessionsRequestQuerySchema = z
.describe('Sort sessions by creation time. Defaults to "desc".')
.openapi('ListSessionsOrder'),
page_token: z.string().optional().describe('Opaque token from a previous response `next_page_token`.'),
- start_timestamp: z.string().optional().describe('Inclusive lower bound on `created_at` (ISO-8601).'),
- end_timestamp: z.string().optional().describe('Inclusive upper bound on `created_at` (ISO-8601).'),
+ start_timestamp: IsoTimestampQueryParam.optional().describe(
+ 'Inclusive lower bound on `created_at` (ISO-8601 / RFC 3339).',
+ ),
+ end_timestamp: IsoTimestampQueryParam.optional().describe(
+ 'Inclusive upper bound on `created_at` (ISO-8601 / RFC 3339).',
+ ),
})
.openapi('ListSessionsRequestQuery');
diff --git a/packages/server/tests/db/session-store/contract.test.ts b/packages/server/tests/db/session-store/postgres/contract.test.ts
similarity index 80%
rename from packages/server/tests/db/session-store/contract.test.ts
rename to packages/server/tests/db/session-store/postgres/contract.test.ts
index d7880caa7..c317d705c 100644
--- a/packages/server/tests/db/session-store/contract.test.ts
+++ b/packages/server/tests/db/session-store/postgres/contract.test.ts
@@ -1,9 +1,9 @@
import type { ISessionStore } from '@truefoundry/utils/agent-session/store/ISessionStore';
-import { runStoreContractSuite } from '../../../../harness/tests/agent-session/store/storeContractSuite';
+import { runStoreContractSuite } from '../../../../../harness/tests/agent-session/store/storeContractSuite';
import { createPostgresStoreEnvironment } from './helpers';
-const describePg = process.env.PG_STORE_TESTS_ENABLED === '1' ? describe : describe.skip;
+const describePg = process.env['PG_STORE_TESTS_ENABLED'] === '1' ? describe : describe.skip;
describePg('PostgresSessionStore (ISessionStore contract)', () => {
let env: Awaited<ReturnType<typeof createPostgresStoreEnvironment>>;
diff --git a/packages/server/tests/db/session-store/globalSetup.ts b/packages/server/tests/db/session-store/postgres/globalSetup.ts
similarity index 100%
rename from packages/server/tests/db/session-store/globalSetup.ts
rename to packages/server/tests/db/session-store/postgres/globalSetup.ts
diff --git a/packages/server/tests/db/session-store/helpers.ts b/packages/server/tests/db/session-store/postgres/helpers.ts
similarity index 90%
rename from packages/server/tests/db/session-store/helpers.ts
rename to packages/server/tests/db/session-store/postgres/helpers.ts
index 0d250a6cb..9290706e9 100644
--- a/packages/server/tests/db/session-store/helpers.ts
+++ b/packages/server/tests/db/session-store/postgres/helpers.ts
@@ -2,10 +2,10 @@ import { sql, type Kysely } from 'kysely';
import { Pool } from 'pg';
import { ulid } from 'ulid';
-import { migrateToLatest } from '../../../src/db/migratePostgres';
-import { createDb } from '../../../src/db/postgres/client';
-import { PostgresSessionStore } from '../../../src/db/postgres/session-store/PostgresSessionStore';
-import type { Database } from '../../../src/db/postgres/types';
+import { migrateToLatest } from '../../../../src/db/migratePostgres';
+import { createDb } from '../../../../src/db/postgres/client';
+import { PostgresSessionStore } from '../../../../src/db/postgres/session-store/PostgresSessionStore';
+import type { Database } from '../../../../src/db/postgres/types';
const ADMIN_URL_ENV = 'PG_STORE_TESTS_ADMIN_URL';
diff --git a/packages/server/tests/db/session-store/sqlite/contract.test.ts b/packages/server/tests/db/session-store/sqlite/contract.test.ts
new file mode 100644
index 000000000..573462238
--- /dev/null
+++ b/packages/server/tests/db/session-store/sqlite/contract.test.ts
@@ -0,0 +1,18 @@
+import type { ISessionStore } from '@truefoundry/utils/agent-session/store/ISessionStore';
+
+import { runStoreContractSuite } from '../../../../../harness/tests/agent-session/store/storeContractSuite';
+import { createSqliteStoreEnvironment } from './helpers';
+
+describe('SqliteSessionStore (ISessionStore contract)', () => {
+ let env: Awaited<ReturnType<typeof createSqliteStoreEnvironment>>;
+
+ beforeEach(async () => {
+ env = await createSqliteStoreEnvironment();
+ }, 120_000);
+
+ afterEach(async () => {
+ await env?.teardown();
+ });
+
+ runStoreContractSuite((): ISessionStore => env.store);
+});
diff --git a/packages/server/tests/db/session-store/sqlite/helpers.ts b/packages/server/tests/db/session-store/sqlite/helpers.ts
new file mode 100644
index 000000000..450434078
--- /dev/null
+++ b/packages/server/tests/db/session-store/sqlite/helpers.ts
@@ -0,0 +1,39 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { migrateSqliteToLatest } from '../../../../src/db/migrateSqlite';
+import { createSqliteDb } from '../../../../src/db/sqlite/client';
+import { SqliteSessionStore } from '../../../../src/db/sqlite/session-store/SqliteSessionStore';
+
+export interface SqliteStoreEnvironment {
+ store: SqliteSessionStore;
+ teardown: () => Promise<void>;
+}
+
+/**
+ * Creates a throwaway file DB under an OS temp dir, migrates it, and returns
+ * a SqliteSessionStore. Each contract test gets a fresh database.
+ */
+export async function createSqliteStoreEnvironment(): Promise<SqliteStoreEnvironment> {
+ const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'harness-sqlite-'));
+ const dbPath = path.join(tempDir, 'session.sqlite');
+ const db = createSqliteDb(dbPath);
+
+ try {
+ await migrateSqliteToLatest(db);
+ } catch (error) {
+ await db.destroy();
+ await fs.rm(tempDir, { recursive: true, force: true });
+ throw error;
+ }
+
+ const store = new SqliteSessionStore(db);
+ return {
+ store,
+ async teardown() {
+ await db.destroy();
+ await fs.rm(tempDir, { recursive: true, force: true });
+ },
+ };
+}
diff --git a/packages/server/tsconfig.json b/packages/server/tsconfig.json
index 4649792e3..e3504fd99 100644
--- a/packages/server/tsconfig.json
+++ b/packages/server/tsconfig.json
@@ -1,11 +1,13 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
- "types": ["node"],
- "noEmit": true
+ "types": ["node", "jest"],
+ "noEmit": true,
+ "paths": {
+ "openai/resources/chat": ["../harness/node_modules/openai/resources/chat/index.d.ts"]
+ }
},
"include": ["src/**/*", "tests/**/*", "scripts/**/*", "tsup.config.ts"],
- // Test bodies pull harness test sources across the package boundary, which needs
- // that package's own compiler paths; support modules stay in-project.
- "exclude": ["node_modules", "dist", "src/**/*.test.ts", "tests/**/*.test.ts"]
+ // node:test files under src/ stay out of the Jest-typed project.
+ "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
}
diff --git a/packages/server/tsup.config.ts b/packages/server/tsup.config.ts
index 4f8dda119..4a2df8fe9 100644
--- a/packages/server/tsup.config.ts
+++ b/packages/server/tsup.config.ts
@@ -4,20 +4,27 @@ import { fileURLToPath } from 'node:url';
import { defineConfig } from 'tsup';
-const migrationsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'src/db/postgres/migrations');
-const migrationEntries = Object.fromEntries(
- readdirSync(migrationsDir)
- .filter(name => name.endsWith('.ts'))
- .map(name => {
- const base = name.replace(/\.ts$/, '');
- return [`postgres/migrations/${base}`, path.join(migrationsDir, name)] as const;
- }),
-);
+const srcDbDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'src/db');
+
+function migrationEntries(engine: 'postgres' | 'sqlite'): Record<string, string> {
+ const migrationsDir = path.join(srcDbDir, engine, 'migrations');
+ return Object.fromEntries(
+ readdirSync(migrationsDir)
+ .filter(name => name.endsWith('.ts'))
+ .map(name => {
+ const base = name.replace(/\.ts$/, '');
+ return [`${engine}/migrations/${base}`, path.join(migrationsDir, name)] as const;
+ }),
+ );
+}
export default defineConfig({
entry: {
main: 'src/main.ts',
- ...migrationEntries,
+ // Emit both engines under dist/{postgres,sqlite}/migrations/.
+ // Only Postgres is applied at runtime (main) and via `pnpm migrate`.
+ ...migrationEntries('postgres'),
+ ...migrationEntries('sqlite'),
},
format: ['esm'],
dts: false,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4075c23bb..c9d1a9ee9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -194,6 +194,9 @@ importers:
'@truefoundry/utils':
specifier: workspace:*
version: link:../harness
+ better-sqlite3:
+ specifier: ^13.0.2
+ version: 13.0.2
hono:
specifier: ^4.12.31
version: 4.12.31
@@ -225,6 +228,9 @@ importers:
'@swc/jest':
specifier: ^0.2.37
version: 0.2.39(@swc/[email protected])
+ '@types/better-sqlite3':
+ specifier: ^7.6.13
+ version: 7.6.13
'@types/jest':
specifier: ^29.5.14
version: 29.5.14
@@ -2890,6 +2896,9 @@ packages:
resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==}
+ '@types/[email protected]':
+ resolution: {integrity: sha512-NMv9ASNARoKksWtsq/SHakpYAYnhBrQgGD8zkLYk/jaK8jUGn08CfEdTRgYhMypUQAfzSP8W6gNLe0q19/t4VA==}
+
resolution: {integrity: sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==}
@@ -3360,6 +3369,10 @@ packages:
engines: {node: '>=6.0.0'}
hasBin: true
+ resolution: {integrity: sha512-jW6oufeDhXZaiX9Lw5A+oerVClx4iFrI6uDj1zu7SqUAjak9vbJvA0NEcKLNxHiQHb6kYCoFzzXYV0YOauhV3g==}
+ engines: {node: '>=22'}
+
resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==}
engines: {node: '>=8'}
@@ -4983,6 +4996,10 @@ packages:
resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
engines: {node: '>= 0.6'}
+ resolution: {integrity: sha512-ekZMeaaIzSQTSpr7X2X3iJM7lTzgnx8ahAG9pJfT/7+14mlEM8ZYQ9cgCDvSSRbReFK0oHli3WrZdCiRsgAT9Q==}
+ engines: {node: ^18 || ^20 || >= 21}
+
resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
engines: {node: '>=10.5.0'}
@@ -9184,6 +9201,10 @@ snapshots:
dependencies:
'@babel/types': 7.29.7
+ '@types/[email protected]':
+ dependencies:
+ '@types/node': 24.13.3
+
'@types/[email protected]': {}
'@types/[email protected]': {}
@@ -9657,6 +9678,10 @@ snapshots:
+ dependencies:
+ node-addon-api: 8.9.0
+
@@ -11780,6 +11805,8 @@ snapshots:
+
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 77b54cf0d..817d3a69a 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -8,6 +8,7 @@ trustLockfile: true
confirmModulesPurge: false
allowBuilds:
'@swc/core': true
+ better-sqlite3: true
esbuild: true
protobufjs: true
diff --git a/scripts/test-store-with-postgres.sh b/scripts/test-store-local.sh
similarity index 81%
rename from scripts/test-store-with-postgres.sh
rename to scripts/test-store-local.sh
index 14f651b36..1cd9cd8a1 100755
--- a/scripts/test-store-with-postgres.sh
+++ b/scripts/test-store-local.sh
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
-# Starts an ephemeral Postgres container (same defaults as CI) and runs the
-# session-store contract tests. The container is removed on exit.
+# Local session-store contract tests: ephemeral Postgres (same defaults as CI)
+# then always-on SQLite. Postgres container is removed on exit.
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -51,5 +51,8 @@ until docker exec "$CONTAINER" pg_isready -U "$PGUSER" -d "$PGDATABASE" >/dev/nu
done
export SESSION_STORE_TEST_PG_URL="$URL"
-echo "Postgres ready. Running store tests (${URL})..."
-pnpm --dir packages/server test:store "$@"
+echo "Postgres ready. Running Postgres store tests (${URL})..."
+pnpm --dir packages/server test:store:postgres "$@"
+
+echo "Running SQLite store tests..."
+pnpm --dir packages/server test:store:sqlite "$@"