The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Inject db into TrueFoundryAgentStore for advisory locks (#588)
Bhavesh Patel7968f59e018b
diff --git a/.changeset/20260904054931-truefoundry-agent-store-db-txn.md b/.changeset/20260904054931-truefoundry-agent-store-db-txn.mdnew file mode 100644index 000000000..1f3f6ef10--- /dev/null+++ b/.changeset/20260904054931-truefoundry-agent-store-db-txn.md@@ -0,0 +1,5 @@+---+"@truefoundry/trueforge": patch+---++Use injected `db` for TrueFoundryAgentStore advisory-lock transactions.diff --git a/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts b/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.tsindex d47085c35..9003e2adb 100644--- a/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts+++ b/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts@@ -81,10 +81,6 @@ export class PostgresAgentStore implements IAgentStore<Transaction<Database>> {return row === undefined ? undefined : toRecord(row);}- withTransaction<T>(fn: (transaction: Transaction<Database>) => Promise<T>): Promise<T> {- return this.#db.transaction().execute(fn);- }-async createAgent(input: CreateAgentInput, transaction?: Transaction<Database>): Promise<AgentRecord> {const db = transaction ?? this.#db;try {diff --git a/packages/trueforge/src/main.ts b/packages/trueforge/src/main.tsindex 56909e37f..aab5f2be0 100644--- a/packages/trueforge/src/main.ts+++ b/packages/trueforge/src/main.ts@@ -51,7 +51,7 @@ import {type TurnStreamingEvent,} from '@truefoundry/trueforge-core/agent-session';import { RequestReplyExecutor, RequestReplyRouter } from '@truefoundry/trueforge-core/request-reply';-import type { Transaction } from 'kysely';+import type { Kysely, Transaction } from 'kysely';import type { RedisClientType } from 'redis';import type { Logger } from 'winston';@@ -197,8 +197,9 @@ function buildResolveMcpServerStore<TTransaction>(options: {function buildResolveAgentStore(options: {persistenceStore: PostgresAgentStore;client: TrueFoundryServiceFoundryServerClient | undefined;+ db: Kysely<PostgresDatabase>;}): (c?: Context) => IAgentStore<Transaction<PostgresDatabase>> {- const { persistenceStore, client } = options;+ const { persistenceStore, client, db } = options;if (!client) {return () => persistenceStore;}@@ -209,6 +210,7 @@ function buildResolveAgentStore(options: {inner: persistenceStore,client,accessToken: requireRequestCredentialToken(c),+ db,}): persistenceStore;}@@ -348,6 +350,7 @@ async function createDistributedPersistence(options: {resolveAgentStore: buildResolveAgentStore({persistenceStore: agentStore,client: serviceFoundryClient,+ db,}),withTransaction: callback => db.transaction().execute(callback),tokenStore,diff --git a/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts b/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.tsindex 2da1d0fc5..10725d0df 100644--- a/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts+++ b/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts@@ -1,5 +1,5 @@import type { AgentSpec } from '@truefoundry/trueforge-core/agent-session';-import { sql, type Transaction } from 'kysely';+import { sql, type Kysely, type Transaction } from 'kysely';import {type AgentRecord,type CreateAgentInput,@@ -9,6 +9,7 @@ import {type ListAgentsInput,type UpdateAgentInput,} from '../db/agentStore';+import { PostgresAgentStore } from '../db/postgres/agent-store/PostgresAgentStore';import type { Database } from '../db/postgres/types';import {TrueFoundryServiceFoundryServerClient,@@ -34,57 +35,79 @@ function toPutRemoteAgentPayload({};}-type TrueFoundryAgentInner<TTransaction> = IAgentStore<TTransaction> & {- withTransaction<T>(fn: (transaction: TTransaction) => Promise<T>): Promise<T>;-};-/**- * create: createDB(null) → putRemote → updateDB(external_id) | on put/update fail → deleteDB (+ deleteRemote if put ok)- * update: lock → get → putRemote(new) → updateDB | on DB fail → putRemote(old) | both fail → AggregateError- * delete: lock → get → deleteRemote(404 ok) → deleteDB+ * Postgres agent store that keeps a matching ServiceFoundry remote agent in sync.+ *+ * DB and ServiceFoundry are not one atomic transaction. Cleanup on failure is+ * best-effort: a delete/restore step can itself fail, leaving temporary SF↔DB skew+ * (orphan remote, orphan local row, or mismatched manifest). create / update /+ * delete stay retryable — a later successful call is expected to recover.+ *+ * create+ * Happy path: insert local row (external_id null) → put remote → set external_id.+ * Name clash on insert: throw; no remote call.+ * putRemote fails: delete local row; rethrow.+ * update(external_id) fails after put: delete remote (if put returned an id), then+ * delete local; if cleanup also fails, AggregateError (primary + cleanup errors).+ *+ * update (manifest)+ * Happy path: lock → load row → put remote (new manifest) → write local.+ * Missing row: return undefined (no remote call).+ * putRemote fails: leave local unchanged; rethrow.+ * local write fails after put: best-effort putRemote(old manifest); if restore fails,+ * AggregateError; if restore ok, rethrow the DB error (local still old, remote restored).+ * external_id-only patches skip ServiceFoundry and go straight to the inner store.+ *+ * delete+ * Happy path: lock → load row → delete remote when external_id is set → delete local.+ * Missing row or null external_id: skip remote; still delete local (idempotent).+ * remote delete fails: do not delete local; rethrow (local kept so retry can finish).*/-export class TrueFoundryAgentStore<- TTransaction extends Transaction<Database> = Transaction<Database>,-> implements IAgentStore<TTransaction> {- readonly #inner: TrueFoundryAgentInner<TTransaction>;+export class TrueFoundryAgentStore implements IAgentStore<Transaction<Database>> {+ readonly #inner: PostgresAgentStore;readonly #client: TrueFoundryServiceFoundryServerClient;readonly #accessToken: string;+ readonly #db: Kysely<Database>;constructor(input: {- inner: TrueFoundryAgentInner<TTransaction>;+ inner: PostgresAgentStore;client: TrueFoundryServiceFoundryServerClient;accessToken: string;+ db: Kysely<Database>;}) {this.#inner = input.inner;this.#client = input.client;this.#accessToken = input.accessToken;+ this.#db = input.db;}- listAgents(input: ListAgentsInput, transaction?: TTransaction): Promise<AgentRecord[]> {+ listAgents(input: ListAgentsInput, transaction?: Transaction<Database>): Promise<AgentRecord[]> {return this.#inner.listAgents(input, transaction);}- getAgent(input: GetAgentInput, transaction?: TTransaction): Promise<AgentRecord | undefined> {+ getAgent(input: GetAgentInput, transaction?: Transaction<Database>): Promise<AgentRecord | undefined> {return this.#inner.getAgent(input, transaction);}- // Serializes updates for this tenant ID and agent id.- // Prevents concurrent MCP writes from desyncing the remote agent.+ // Takes a Postgres transaction advisory lock for this tenant + agent id so concurrent+ // update/delete cannot desync ServiceFoundry MCP grants. The lock only lasts for the+ // lifetime of a DB transaction: if the caller passed one, use it; otherwise open a+ // short transaction on db just for this critical section.#withUpdateLock<T>(input: { tenant_id: string; id: string },- transaction: TTransaction | undefined,- fn: (transaction: TTransaction) => Promise<T>,+ transaction: Transaction<Database> | undefined,+ fn: (transaction: Transaction<Database>) => Promise<T>,): Promise<T> {- const run = async (txn: TTransaction) => {+ const run = async (txn: Transaction<Database>) => {const key = `tf:agent:${input.tenant_id}:${input.id}`;await sql`SELECT pg_advisory_xact_lock(hashtext(${key}))`.execute(txn);return fn(txn);};- return transaction !== undefined ? run(transaction) : this.#inner.withTransaction(run);+ return transaction !== undefined ? run(transaction) : this.#db.transaction().execute(run);}- async createAgent(input: CreateAgentInput, transaction?: TTransaction): Promise<AgentRecord> {- // Lets the DB unique constraint pick one winner for this tenant ID and name.+ async createAgent(input: CreateAgentInput, transaction?: Transaction<Database>): Promise<AgentRecord> {+ // Unique (tenant_id, name) picks one winner even when transaction is omitted (auto-commit inserts).// Prevents concurrent requests from both creating the same remote agent.const created = await this.#inner.createAgent({ ...input, external_id: null }, transaction);@@ -123,7 +146,7 @@ export class TrueFoundryAgentStore<}}- async updateAgent(input: UpdateAgentInput, transaction?: TTransaction): Promise<AgentRecord | undefined> {+ async updateAgent(input: UpdateAgentInput, transaction?: Transaction<Database>): Promise<AgentRecord | undefined> {const nextManifest = input.manifest;if (nextManifest === undefined) {// No manifest means only `external_id` changed; pass through to the inner store.@@ -169,7 +192,7 @@ export class TrueFoundryAgentStore<});}- async deleteAgent(input: DeleteAgentInput, transaction?: TTransaction): Promise<void> {+ async deleteAgent(input: DeleteAgentInput, transaction?: Transaction<Database>): Promise<void> {return this.#withUpdateLock(input, transaction, async txn => {const previous = await this.#inner.getAgent({ tenant_id: input.tenant_id, id: input.id }, txn);if (previous?.external_id) {diff --git a/packages/trueforge/tests/unit/truefoundry/TrueFoundryAgentStore.test.ts b/packages/trueforge/tests/unit/truefoundry/TrueFoundryAgentStore.test.tsindex fc9ade104..6049bc6e3 100644--- a/packages/trueforge/tests/unit/truefoundry/TrueFoundryAgentStore.test.ts+++ b/packages/trueforge/tests/unit/truefoundry/TrueFoundryAgentStore.test.ts@@ -1,8 +1,11 @@import { AgentSpecSchema, type CreatedBySubject } from '@truefoundry/trueforge-core/agent-session';+import type { Kysely, Transaction } from 'kysely';import { createLogger } from 'winston';import type { AgentRecord } from '../../../src/db/agentStore';import { AgentNameConflictError } from '../../../src/db/agentStore';+import type { PostgresAgentStore } from '../../../src/db/postgres/agent-store/PostgresAgentStore';+import type { Database } from '../../../src/db/postgres/types';import { TrueFoundryAgentStore } from '../../../src/truefoundry/TrueFoundryAgentStore';import {TrueFoundryServiceFoundryServerClient,@@ -20,7 +23,7 @@ const CREATED_BY_SUBJECT: CreatedBySubject = {subject_display_name: 'tester',};-function mockTransaction() {+function mockTransaction(): Transaction<Database> {const executor = {transformQuery(node: unknown) {return node;@@ -37,7 +40,7 @@ function mockTransaction() {getExecutor() {return executor;},- };+ } as unknown as Transaction<Database>;}const TXN = mockTransaction();@@ -65,16 +68,39 @@ function record(overrides: Partial<AgentRecord> = {}): AgentRecord {};}-function mockInner(overrides = {}) {+function mockDb(+ transactionExecute: <T>(fn: (txn: Transaction<Database>) => Promise<T>) => Promise<T> = async fn => fn(TXN),+): Kysely<Database> {+ return {+ transaction: () => ({+ execute: async <T>(fn: (txn: Transaction<Database>) => Promise<T>): Promise<T> => transactionExecute(fn),+ }),+ } as unknown as Kysely<Database>;+}++function mockInner(overrides = {}): PostgresAgentStore {return {listAgents: jest.fn(),getAgent: jest.fn(),createAgent: jest.fn(),updateAgent: jest.fn(),deleteAgent: jest.fn(),- withTransaction: jest.fn(async fn => fn(TXN)),...overrides,- };+ } as unknown as PostgresAgentStore;+}++function tfStore(input: {+ inner: PostgresAgentStore;+ client: TrueFoundryServiceFoundryServerClient;+ accessToken?: string;+ db?: Kysely<Database>;+}) {+ return new TrueFoundryAgentStore({+ inner: input.inner,+ client: input.client,+ accessToken: input.accessToken ?? TOKEN,+ db: input.db ?? mockDb(),+ });}function mockClient(@@ -109,10 +135,9 @@ describe('TrueFoundryAgentStore', () => {const agents = [record()];const listAgents = jest.fn(async () => agents);const getAgent = jest.fn(async () => agents[0]);- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ listAgents, getAgent }),client: mockClient(),- accessToken: TOKEN,});await expect(store.listAgents({ tenant_id: TENANT }, TXN)).resolves.toBe(agents);@@ -136,10 +161,9 @@ describe('TrueFoundryAgentStore', () => {});const createAgent = jest.fn(async () => local);const updateAgent = jest.fn(async () => linked);- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ createAgent, updateAgent }),client: mockClient({ putRemoteAgent }),- accessToken: TOKEN,});await expect(@@ -174,10 +198,9 @@ describe('TrueFoundryAgentStore', () => {const putRemoteAgent = jest.fn();const updateAgent = jest.fn();const deleteRemoteAgent = jest.fn();- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ createAgent, updateAgent }),client: mockClient({ putRemoteAgent, deleteRemoteAgent }),- accessToken: TOKEN,});await expect(@@ -205,10 +228,9 @@ describe('TrueFoundryAgentStore', () => {});const createAgent = jest.fn(async () => record({ external_id: null }));const updateAgent = jest.fn(async () => record({ external_id: 'sf-1' }));- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ createAgent, updateAgent }),client: mockClient({ putRemoteAgent }),- accessToken: TOKEN,});await store.createAgent(@@ -233,10 +255,9 @@ describe('TrueFoundryAgentStore', () => {throw new Error('sf failed');});const deleteRemoteAgent = jest.fn();- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ createAgent, updateAgent, deleteAgent }),client: mockClient({ putRemoteAgent, deleteRemoteAgent }),- accessToken: TOKEN,});await expect(@@ -264,10 +285,9 @@ describe('TrueFoundryAgentStore', () => {});const deleteAgent = jest.fn(async () => undefined);const deleteRemoteAgent = jest.fn(async () => undefined);- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ createAgent, updateAgent, deleteAgent }),client: mockClient({ deleteRemoteAgent }),- accessToken: TOKEN,});await expect(@@ -298,10 +318,9 @@ describe('TrueFoundryAgentStore', () => {const deleteRemoteAgent = jest.fn(async () => {throw new Error('remote cleanup failed');});- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ createAgent, updateAgent, deleteAgent }),client: mockClient({ deleteRemoteAgent }),- accessToken: TOKEN,});await expect(@@ -329,10 +348,9 @@ describe('TrueFoundryAgentStore', () => {const updated = record({ external_id: 'sf-agent-1' });const updateAgent = jest.fn(async () => updated);const putRemoteAgent = jest.fn();- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ updateAgent }),client: mockClient({ putRemoteAgent }),- accessToken: TOKEN,});await expect(store.updateAgent({ tenant_id: TENANT, id: 'agent-1', external_id: 'sf-agent-1' })).resolves.toBe(@@ -349,10 +367,9 @@ describe('TrueFoundryAgentStore', () => {const getAgent = jest.fn(async () => undefined);const updateAgent = jest.fn();const putRemoteAgent = jest.fn();- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, updateAgent }),client: mockClient({ putRemoteAgent }),- accessToken: TOKEN,});await expect(@@ -362,21 +379,39 @@ describe('TrueFoundryAgentStore', () => {expect(putRemoteAgent).not.toHaveBeenCalled();});- it('updateAgent reads the agent inside the transaction for manifest updates', async () => {+ it('updateAgent opens a db transaction when the caller does not pass one', async () => {const previous = record({ external_id: 'sf-1' });const updatedManifest = manifest({ instructions: 'Updated.' });const updated = record({ manifest: updatedManifest, external_id: 'sf-1' });const getAgent = jest.fn(async () => previous);const updateAgent = jest.fn(async () => updated);- const withTransaction = jest.fn(async fn => fn(TXN));- const store = new TrueFoundryAgentStore({- inner: mockInner({ getAgent, updateAgent, withTransaction }),+ const transactionOpens: unknown[] = [];+ const store = tfStore({+ inner: mockInner({ getAgent, updateAgent }),client: mockClient(),- accessToken: TOKEN,+ db: mockDb(async fn => {+ transactionOpens.push(true);+ return fn(TXN);+ }),});await store.updateAgent({ tenant_id: TENANT, id: previous.id, manifest: updatedManifest });- expect(withTransaction).toHaveBeenCalled();+ expect(transactionOpens).toHaveLength(1);+ expect(getAgent).toHaveBeenCalledWith({ tenant_id: TENANT, id: previous.id }, TXN);+ });++ it('updateAgent reads the agent inside the caller transaction for manifest updates', async () => {+ const previous = record({ external_id: 'sf-1' });+ const updatedManifest = manifest({ instructions: 'Updated.' });+ const updated = record({ manifest: updatedManifest, external_id: 'sf-1' });+ const getAgent = jest.fn(async () => previous);+ const updateAgent = jest.fn(async () => updated);+ const store = tfStore({+ inner: mockInner({ getAgent, updateAgent }),+ client: mockClient(),+ });++ await store.updateAgent({ tenant_id: TENANT, id: previous.id, manifest: updatedManifest }, TXN);expect(getAgent).toHaveBeenCalledWith({ tenant_id: TENANT, id: previous.id }, TXN);});@@ -387,15 +422,14 @@ describe('TrueFoundryAgentStore', () => {const getAgent = jest.fn(async () => previous);const updateAgent = jest.fn(async () => updated);const putRemoteAgent = jest.fn(async () => ({ externalId: 'sf-1' }));- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, updateAgent }),client: mockClient({ putRemoteAgent }),- accessToken: TOKEN,});- await expect(store.updateAgent({ tenant_id: TENANT, id: previous.id, manifest: updatedManifest })).resolves.toBe(- updated,- );+ await expect(+ store.updateAgent({ tenant_id: TENANT, id: previous.id, manifest: updatedManifest }, TXN),+ ).resolves.toBe(updated);expect(putRemoteAgent).toHaveBeenCalledTimes(1);expect(updateAgent).toHaveBeenCalledTimes(1);expect(updateAgent).toHaveBeenCalledWith(@@ -416,10 +450,9 @@ describe('TrueFoundryAgentStore', () => {const getAgent = jest.fn(async () => previous);const updateAgent = jest.fn(async () => updated);const putRemoteAgent = jest.fn(async () => ({ externalId: 'sf-new' }));- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, updateAgent }),client: mockClient({ putRemoteAgent }),- accessToken: TOKEN,});const result = await store.updateAgent(@@ -450,10 +483,9 @@ describe('TrueFoundryAgentStore', () => {const putRemoteAgent = jest.fn(async () => {throw new Error('sf failed');});- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, updateAgent }),client: mockClient({ putRemoteAgent }),- accessToken: TOKEN,});await expect(@@ -473,10 +505,9 @@ describe('TrueFoundryAgentStore', () => {.fn().mockResolvedValueOnce({ externalId: 'sf-new' }).mockResolvedValueOnce({ externalId: 'sf-old' });- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, updateAgent }),client: mockClient({ putRemoteAgent }),- accessToken: TOKEN,});await expect(store.updateAgent({ tenant_id: TENANT, id: previous.id, manifest: updatedManifest })).rejects.toThrow(@@ -503,10 +534,9 @@ describe('TrueFoundryAgentStore', () => {.fn().mockResolvedValueOnce({ externalId: 'sf-new' }).mockRejectedValueOnce(new Error('sf restore failed'));- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, updateAgent }),client: mockClient({ putRemoteAgent }),- accessToken: TOKEN,});await expect(@@ -524,10 +554,9 @@ describe('TrueFoundryAgentStore', () => {const previous = record({ external_id: 'sf-1' });const getAgent = jest.fn(async () => previous);const deleteAgent = jest.fn(async () => undefined);- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, deleteAgent }),client: mockClient(),- accessToken: TOKEN,});await store.deleteAgent({ tenant_id: TENANT, id: previous.id });@@ -539,10 +568,9 @@ describe('TrueFoundryAgentStore', () => {const getAgent = jest.fn(async () => previous);const deleteAgent = jest.fn(async () => undefined);const deleteRemoteAgent = jest.fn(async () => undefined);- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, deleteAgent }),client: mockClient({ deleteRemoteAgent }),- accessToken: TOKEN,});await store.deleteAgent({ tenant_id: TENANT, id: previous.id });@@ -556,10 +584,9 @@ describe('TrueFoundryAgentStore', () => {const getAgent = jest.fn(async () => previous);const deleteAgent = jest.fn(async () => undefined);const deleteRemoteAgent = jest.fn();- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, deleteAgent }),client: mockClient({ deleteRemoteAgent }),- accessToken: TOKEN,});await store.deleteAgent({ tenant_id: TENANT, id: previous.id });@@ -571,10 +598,9 @@ describe('TrueFoundryAgentStore', () => {const getAgent = jest.fn(async () => undefined);const deleteAgent = jest.fn(async () => undefined);const deleteRemoteAgent = jest.fn();- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, deleteAgent }),client: mockClient({ deleteRemoteAgent }),- accessToken: TOKEN,});await store.deleteAgent({ tenant_id: TENANT, id: 'missing' });@@ -589,10 +615,9 @@ describe('TrueFoundryAgentStore', () => {const deleteRemoteAgent = jest.fn(async () => {throw new Error('sf delete failed');});- const store = new TrueFoundryAgentStore({+ const store = tfStore({inner: mockInner({ getAgent, deleteAgent }),client: mockClient({ deleteRemoteAgent }),- accessToken: TOKEN,});await expect(store.deleteAgent({ tenant_id: TENANT, id: previous.id })).rejects.toThrow('sf delete failed');