Add TrueFoundryAgentStore for agents

.changeset/20260902194500-truefoundry-agent-store.md

@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Sync ServiceFoundry remote agents on create/update/delete and store the remote id in `external_id`. Filter `listAgents` by `external_ids`. Keep general ServiceFoundry HTTP at 10s and agent CRUD calls at 3s.

.changeset/20260903013000-reserve-agent-names.md

@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Reject reserved agent names `tfg` and `trueforge` in create requests.

packages/trueforge/.env.example

@@ -27,6 +27,10 @@ PORT=8790
 ## ServiceFoundry server (caller token) and turns call the tenant's default AI Gateway. Unset = local
 ## API-key model catalog. Mutually exclusive with OIDC.
 # TRUEFOUNDRY_SERVICEFOUNDRY_SERVER_URL=https://servicefoundry-server.truefoundry.svc.cluster.local
+## Max ms for non-agent ServiceFoundry HTTP calls. Default 10000.
+# TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_TIMEOUT_MS=10000
+## Max ms for ServiceFoundry agent create/update/delete calls. Default 3000.
+# TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_AGENT_TIMEOUT_MS=3000
 
 ## Internal mutual TLS for calls to the ServiceFoundry server. When true, trueforge presents its client
 ## certificate (and upgrades a mesh-direct http:// peer URL to https://). Only meaningful in-cluster,

packages/trueforge/scripts/write-openapi.ts

@@ -60,6 +60,7 @@ function canonicalise(value: unknown): unknown {
 const sessionStore = new InMemorySessionStore();
 const db = createSqliteDb(':memory:');
 const tokenStore = new SqliteOAuthTokenStore(db);
+const agentStore = new SqliteAgentStore(db);
 const app = createServerApp({
   modelCatalog: ModelCatalog.load(),
   resolveModelProviderStore: () => new SqliteModelProviderStore(db),
@@ -76,7 +77,7 @@ const app = createServerApp({
   skillStore: new SqliteSkillStore(db),
   sandboxCatalog: SandboxCatalog.load(),
   sandboxProviderStore: new SqliteSandboxProviderStore(db),
-  agentStore: new SqliteAgentStore(db),
+  resolveAgentStore: () => agentStore,
   scheduleStore: new SqliteScheduleStore(db),
   sessionStore,
   sessionMetricsStore: new SqliteSessionMetricsStore(db),

packages/trueforge/src/apis/agents.ts

@@ -5,7 +5,12 @@ import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
 import type { AgentSpec } from '@truefoundry/trueforge-core/agent-session';
 import type { Context } from 'hono';
 import { createdBySubjectFromRequestContext, type ResolveRequestContext } from '../auth/identity';
-import { AgentNameConflictError, type AgentRecord, type IAgentStore } from '../db/agentStore';
+import {
+  AgentExternalIdConflictError,
+  AgentNameConflictError,
+  type AgentRecord,
+  type IAgentStore,
+} from '../db/agentStore';
 import type { IMcpServerStore } from '../db/mcpServerStore';
 import type { IModelProviderStore } from '../db/modelProviderStore';
 import type { ISandboxProviderStore } from '../db/sandboxProviderStore';
@@ -24,7 +29,7 @@ import { type Agent, type CreateAgentRequest } from '../schemas/agent';
 import { buildAgentCodeSnippets } from './agentCodeSnippets';
 
 export interface AgentsRouterDeps<TTransaction> {
-  agentStore: IAgentStore<TTransaction>;
+  resolveAgentStore: (c: Context) => IAgentStore<TTransaction>;
   resolveModelProviderStore: (c: Context) => IModelProviderStore<TTransaction>;
   resolveMcpServerStore: (c: Context) => IMcpServerStore<TTransaction>;
   skillStore: ISkillStore<TTransaction>;
@@ -70,7 +75,7 @@ async function validateManifest<TTransaction>({
 export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransaction>) {
   const listHandler: RouteHandler<typeof listAgentsRoute> = async c => {
     const requestContext = deps.resolveRequestContext(c);
-    const records = await deps.agentStore.listAgents(requestContext.tenant_id);
+    const records = await deps.resolveAgentStore(c).listAgents({ tenant_id: requestContext.tenant_id });
     return c.json({ data: records.map(toWireAgent) }, 200);
   };
 
@@ -85,7 +90,7 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
       tenant_id: requestContext.tenant_id,
     });
     try {
-      const record = await deps.agentStore.createAgent({
+      const record = await deps.resolveAgentStore(c).createAgent({
         tenant_id: requestContext.tenant_id,
         name: body.name,
         manifest,
@@ -94,7 +99,7 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
       });
       return c.json({ data: toWireAgent(record) }, 201);
     } catch (error) {
-      if (error instanceof AgentNameConflictError) {
+      if (error instanceof AgentNameConflictError || error instanceof AgentExternalIdConflictError) {
         return c.json({ error: { message: error.message } }, 409);
       }
       throw error;
@@ -104,7 +109,7 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
   const getHandler: RouteHandler<typeof getAgentRoute> = async c => {
     const { agent_id: agentId } = c.req.valid('param');
     const requestContext = deps.resolveRequestContext(c);
-    const record = await deps.agentStore.getAgent({
+    const record = await deps.resolveAgentStore(c).getAgent({
       tenant_id: requestContext.tenant_id,
       id: agentId,
     });
@@ -117,7 +122,7 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
   const getCodeSnippetsHandler: RouteHandler<typeof getAgentCodeSnippetsRoute> = async c => {
     const { agent_id: agentId } = c.req.valid('param');
     const requestContext = deps.resolveRequestContext(c);
-    const record = await deps.agentStore.getAgent({
+    const record = await deps.resolveAgentStore(c).getAgent({
       tenant_id: requestContext.tenant_id,
       id: agentId,
     });
@@ -138,7 +143,7 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
   const deleteHandler: RouteHandler<typeof deleteAgentRoute> = async c => {
     const { agent_id: agentId } = c.req.valid('param');
     const requestContext = deps.resolveRequestContext(c);
-    await deps.agentStore.deleteAgent({ tenant_id: requestContext.tenant_id, id: agentId });
+    await deps.resolveAgentStore(c).deleteAgent({ tenant_id: requestContext.tenant_id, id: agentId });
     return c.json({}, 200);
   };
 
@@ -153,7 +158,7 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
       mcpServerStore: deps.resolveMcpServerStore(c),
       tenant_id: requestContext.tenant_id,
     });
-    const record = await deps.agentStore.updateAgent({
+    const record = await deps.resolveAgentStore(c).updateAgent({
       tenant_id: requestContext.tenant_id,
       id: agentId,
       manifest,

packages/trueforge/src/apis/schedules.ts

@@ -3,6 +3,7 @@
  */
 import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
 import { InvalidPageTokenError, type Sessions } from '@truefoundry/trueforge-core/agent-session';
+import type { Context } from 'hono';
 import {
   createdBySubjectFromRequestContext,
   hasAdminRole,
@@ -41,7 +42,7 @@ import { getTurnExecutionError, startTurnInProcess, type BeginTurnExecutionDeps
 
 export interface SchedulesRouterDeps<TTransaction> {
   scheduleStore: IScheduleStore<TTransaction>;
-  agentStore: IAgentStore<TTransaction>;
+  resolveAgentStore: (c: Context) => IAgentStore<TTransaction>;
   sessions: Sessions;
   turnDeps: BeginTurnExecutionDeps;
   withTransaction: WithTransaction<TTransaction>;
@@ -200,7 +201,7 @@ export function createSchedulesRouter<TTransaction>(deps: SchedulesRouterDeps<TT
       await startScheduleRun({
         item: { run, schedule },
         sessions: deps.sessions,
-        agentStore: deps.agentStore,
+        agentStore: deps.resolveAgentStore(c),
         startTurn: async turnParams => {
           await startTurnInProcess({ ...turnParams, deps: deps.turnDeps });
         },
@@ -235,7 +236,7 @@ export function createSchedulesRouter<TTransaction>(deps: SchedulesRouterDeps<TT
 
     validateManifest(body.manifest);
 
-    const agent = await deps.agentStore.getAgent({
+    const agent = await deps.resolveAgentStore(c).getAgent({
       tenant_id: requestContext.tenant_id,
       name: body.agent_name,
     });

packages/trueforge/src/apis/sessions.ts

@@ -75,7 +75,7 @@ export interface SessionsRouterDeps {
   resolveModelProviderStore: (c: Context) => IModelProviderStore;
   resolveMcpServerStore: (c: Context) => IMcpServerStore;
   skillStore: ISkillStore;
-  agentStore: IAgentStore;
+  resolveAgentStore: (c: Context) => IAgentStore;
   sandboxProviderStore: ISandboxProviderStore;
   redis?: RedisClientType | undefined;
   requestReplyRouter: RequestReplyRouter;
@@ -230,7 +230,7 @@ type InternalSessionsRouterDeps = Pick<
   | 'resolveModelProviderStore'
   | 'resolveMcpServerStore'
   | 'skillStore'
-  | 'agentStore'
+  | 'resolveAgentStore'
   | 'sandboxProviderStore'
   | 'resolveRequestContext'
 >;
@@ -260,7 +260,7 @@ function createGetOrCreateSessionByExternalIdHandler(
 
     let agent: SessionRecord['agent'];
     if (isSessionAgentNameRef(body.agent)) {
-      const named = await deps.agentStore.getAgent({
+      const named = await deps.resolveAgentStore(c).getAgent({
         tenant_id: requestContext.tenant_id,
         name: body.agent.name,
       });
@@ -314,7 +314,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
     const requestContext = deps.resolveRequestContext(c);
 
     if (isSessionAgentNameRef(body.agent)) {
-      const agent = await deps.agentStore.getAgent({
+      const agent = await deps.resolveAgentStore(c).getAgent({
         tenant_id: requestContext.tenant_id,
         name: body.agent.name,
       });

packages/trueforge/src/apis/turns.ts

@@ -106,7 +106,7 @@ export interface TurnsRouterDeps {
   resolveModelProviderStore: (c: Context) => IModelProviderStore;
   resolveMcpServerStore: (c: Context) => IMcpServerWithAuthStore;
   skillStore: ISkillStore;
-  agentStore: IAgentStore;
+  resolveAgentStore: (c: Context) => IAgentStore;
   /** Resumable live turn-event transport: create-turn writes, subscribe polls. */
   eventSubscriptions: EventSubscriptionRegistry<TurnStreamingEvent>;
   sandboxProviderStore: ISandboxProviderStore;
@@ -116,15 +116,16 @@ export interface TurnsRouterDeps {
 
 /**
  * Deps needed to create a turn and drain events in-process (no HTTP). Unlike the HTTP path, this
- * carries already-resolved `modelProviderStore` / `mcpServerStore` (the scheduler has no request
+ * carries already-resolved `modelProviderStore` / `mcpServerStore` / `agentStore` (the scheduler has no request
  * context to resolve them).
  */
 export type BeginTurnExecutionDeps = Pick<
   TurnsRouterDeps,
-  'activeTurns' | 'eventSubscriptions' | 'skillStore' | 'agentStore' | 'sandboxProviderStore' | 'logger'
+  'activeTurns' | 'eventSubscriptions' | 'skillStore' | 'sandboxProviderStore' | 'logger'
 > & {
   modelProviderStore: IModelProviderStore;
   mcpServerStore: IMcpServerWithAuthStore;
+  agentStore: IAgentStore;
 };
 
 /**
@@ -721,6 +722,7 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
         ...deps,
         modelProviderStore: deps.resolveModelProviderStore(c),
         mcpServerStore: deps.resolveMcpServerStore(c),
+        agentStore: deps.resolveAgentStore(c),
       },
     };
 

packages/trueforge/src/app.ts

@@ -174,11 +174,15 @@ export interface ServerDeps<TTransaction> {
    * Called without a context (e.g. the scheduler / OAuth callback) it returns the DB persistence store.
    */
   resolveMcpServerStore: (c?: Context) => IMcpServerWithAuthStore<TTransaction>;
+  /**
+   * Per-request store: DB singleton, or a token-bound TrueFoundry decorator in TrueFoundry mode.
+   * Called without a context (e.g. the scheduler) it returns the DB persistence store.
+   */
+  resolveAgentStore: (c?: Context) => IAgentStore<TTransaction>;
   withTransaction: WithTransaction<TTransaction>;
   tokenStore: IOAuthTokenStore<TTransaction>;
   skillStore: ISkillStore<TTransaction>;
   sandboxProviderStore: ISandboxProviderStore<TTransaction>;
-  agentStore: IAgentStore<TTransaction>;
   scheduleStore: IScheduleStore<TTransaction>;
   sessionStore: ISessionStore;
   sessionMetricsStore: ISessionMetricsStore;
@@ -291,7 +295,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
     '/api/v1/agents',
     withAuth(
       createAgentsRouter({
-        agentStore: deps.agentStore,
+        resolveAgentStore: deps.resolveAgentStore,
         resolveModelProviderStore: deps.resolveModelProviderStore,
         resolveMcpServerStore: deps.resolveMcpServerStore,
         skillStore: deps.skillStore,
@@ -307,15 +311,15 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
     withAuth(
       createSchedulesRouter({
         scheduleStore: deps.scheduleStore,
-        agentStore: deps.agentStore,
+        resolveAgentStore: deps.resolveAgentStore,
         sessions: deps.sessions,
         turnDeps: {
           activeTurns: deps.activeTurns,
           eventSubscriptions: deps.eventSubscriptions,
           modelProviderStore: deps.resolveModelProviderStore(),
           mcpServerStore: deps.resolveMcpServerStore(),
           skillStore: deps.skillStore,
-          agentStore: deps.agentStore,
+          agentStore: deps.resolveAgentStore(),
           sandboxProviderStore: deps.sandboxProviderStore,
           logger: deps.logger,
         },
@@ -349,7 +353,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
         resolveModelProviderStore: deps.resolveModelProviderStore,
         resolveMcpServerStore: deps.resolveMcpServerStore,
         skillStore: deps.skillStore,
-        agentStore: deps.agentStore,
+        resolveAgentStore: deps.resolveAgentStore,
         sandboxProviderStore: deps.sandboxProviderStore,
         resolveRequestContext,
       }),
@@ -376,7 +380,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
         resolveModelProviderStore: deps.resolveModelProviderStore,
         resolveMcpServerStore: deps.resolveMcpServerStore,
         skillStore: deps.skillStore,
-        agentStore: deps.agentStore,
+        resolveAgentStore: deps.resolveAgentStore,
         sandboxProviderStore: deps.sandboxProviderStore,
         redis: deps.redis,
         requestReplyRouter: deps.requestReplyRouter,
@@ -396,7 +400,7 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
         resolveModelProviderStore: deps.resolveModelProviderStore,
         resolveMcpServerStore: deps.resolveMcpServerStore,
         skillStore: deps.skillStore,
-        agentStore: deps.agentStore,
+        resolveAgentStore: deps.resolveAgentStore,
         eventSubscriptions: deps.eventSubscriptions,
         sandboxProviderStore: deps.sandboxProviderStore,
         logger: deps.logger,

packages/trueforge/src/config.ts

@@ -489,6 +489,10 @@ export interface SharedServerConfiguration {
    * Env: `TRUEFOUNDRY_SERVICEFOUNDRY_SERVER_URL`.
    */
   TRUEFOUNDRY_SERVICEFOUNDRY_SERVER_URL: string | undefined;
+  /** Max ms for non-agent ServiceFoundry HTTP calls. Env: `TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_TIMEOUT_MS`. Default 10000. */
+  TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_TIMEOUT_MS: number;
+  /** Max ms for agent CRUD ServiceFoundry HTTP calls. Env: `TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_AGENT_TIMEOUT_MS`. Default 3000. */
+  TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_AGENT_TIMEOUT_MS: number;
   /**
    * Present this pod's client certificate on outbound calls to the ServiceFoundry server (internal
    * mutual TLS) and upgrade a mesh-direct peer URL from http to https. Off by default, so an
@@ -664,6 +668,16 @@ const shared: SharedServerConfiguration = {
   SERVER_URL:
     getEnv('SERVER_URL', { defaultValue: `http://localhost:${String(port)}` }) ?? `http://localhost:${String(port)}`,
   TRUEFOUNDRY_SERVICEFOUNDRY_SERVER_URL: getEnv('TRUEFOUNDRY_SERVICEFOUNDRY_SERVER_URL', { required: false }),
+  TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_TIMEOUT_MS: parsePositiveInt({
+    envKey: 'TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_TIMEOUT_MS',
+    raw: getEnv('TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_TIMEOUT_MS'),
+    defaultValue: 10_000,
+  }),
+  TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_AGENT_TIMEOUT_MS: parsePositiveInt({
+    envKey: 'TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_AGENT_TIMEOUT_MS',
+    raw: getEnv('TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_AGENT_TIMEOUT_MS'),
+    defaultValue: 3_000,
+  }),
   TRUEFOUNDRY_MTLS_ENABLED: parseBoolean({
     envKey: 'TRUEFOUNDRY_MTLS_ENABLED',
     raw: getEnv('TRUEFOUNDRY_MTLS_ENABLED'),

packages/trueforge/src/db/agentStore.ts

@@ -31,6 +31,12 @@ export function parseStoredAgentSpec(manifest: unknown): AgentSpec {
 /** Look up by immutable id or unique name within a tenant. */
 export type GetAgentInput = { tenant_id: string } & ({ id: string } | { name: string });
 
+export interface ListAgentsInput {
+  tenant_id: string;
+  /** When set, only agents whose `external_id` is in this list. */
+  external_ids?: readonly string[];
+}
+
 export interface CreateAgentInput {
   tenant_id: string;
   name: ResourceName;
@@ -82,7 +88,7 @@ export class AgentExternalIdConflictError extends Error {
 }
 
 export interface IAgentStore<TTransaction = never> {
-  listAgents(tenantId: string, transaction?: TTransaction): Promise<AgentRecord[]>;
+  listAgents(input: ListAgentsInput, transaction?: TTransaction): Promise<AgentRecord[]>;
   getAgent(input: GetAgentInput, transaction?: TTransaction): Promise<AgentRecord | undefined>;
   /** Inserts a new agent with a generated ULID. Throws AgentNameConflictError or AgentExternalIdConflictError on unique clash. */
   createAgent(input: CreateAgentInput, transaction?: TTransaction): Promise<AgentRecord>;

packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts

@@ -9,6 +9,7 @@ import {
   type DeleteAgentInput,
   type GetAgentInput,
   type IAgentStore,
+  type ListAgentsInput,
   type UpdateAgentInput,
 } from '../../agentStore';
 import { parseStoredCreatedBySubject } from '../../createdBySubject';
@@ -55,9 +56,16 @@ export class PostgresAgentStore implements IAgentStore<Transaction<Database>> {
     this.#db = db;
   }
 
-  async listAgents(tenantId: string, transaction?: Transaction<Database>): Promise<AgentRecord[]> {
+  async listAgents(input: ListAgentsInput, transaction?: Transaction<Database>): Promise<AgentRecord[]> {
+    if (input.external_ids?.length === 0) {
+      return [];
+    }
     const db = transaction ?? this.#db;
-    const rows = await db.selectFrom('agent').selectAll().where('tenant_id', '=', tenantId).orderBy('name').execute();
+    let query = db.selectFrom('agent').selectAll().where('tenant_id', '=', input.tenant_id);
+    if (input.external_ids !== undefined) {
+      query = query.where('external_id', 'in', [...input.external_ids]);
+    }
+    const rows = await query.orderBy('name').execute();
     return rows.map(toRecord);
   }
 
@@ -73,6 +81,10 @@ 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 {