Skip to content

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

Add nullable agent external_id with tenant-scoped unique index (#558)

Bhavesh Patel1c67237a7db6
diff --git a/.changeset/20260902143524-agent-external-id.md b/.changeset/20260902143524-agent-external-id.md
new file mode 100644
index 000000000..51d5fee5d
--- /dev/null
+++ b/.changeset/20260902143524-agent-external-id.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Add agent `external_id` (`string | null` on create) with a tenant-scoped partial unique index (Postgres and SQLite).
diff --git a/packages/trueforge/src/apis/agents.ts b/packages/trueforge/src/apis/agents.ts
index 0a3158a40..f9cb16fc0 100644
--- a/packages/trueforge/src/apis/agents.ts
+++ b/packages/trueforge/src/apis/agents.ts
@@ -82,6 +82,7 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransac
tenant_id: TENANT_ID,
name: body.name,
manifest,
+ external_id: null,
});
return c.json({ data: toWireAgent(record) }, 201);
} catch (error) {
diff --git a/packages/trueforge/src/db/agentStore.ts b/packages/trueforge/src/db/agentStore.ts
index b741e80ef..3fdd9ab20 100644
--- a/packages/trueforge/src/db/agentStore.ts
+++ b/packages/trueforge/src/db/agentStore.ts
@@ -14,6 +14,7 @@ export interface AgentRecord {
name: ResourceName;
manifest: AgentSpec;
metadata: AgentMetadata;
+ external_id: string | null;
/** ISO-8601 UTC instant. */
created_at: string;
/** ISO-8601 UTC instant. */
@@ -35,10 +36,11 @@ export interface CreateAgentInput {
tenant_id: string;
name: ResourceName;
manifest: AgentSpec;
+ external_id: string | null;
}
/**
- * Patch an existing agent by immutable id. At least one of `manifest` or `metadata` is required.
+ * Patch an existing agent by immutable id. At least one of `manifest`, `metadata`, or `external_id` is required.
* Provided fields replace the stored column; omitted fields are left unchanged.
*/
export interface UpdateAgentInput {
@@ -46,6 +48,7 @@ export interface UpdateAgentInput {
id: string;
manifest?: AgentSpec;
metadata?: AgentMetadata;
+ external_id?: string | null;
}
export interface DeleteAgentInput {
@@ -66,12 +69,25 @@ export class AgentNameConflictError extends Error {
}
}
+/** Unique `(tenant_id, external_id)` violation when `external_id` is set. */
+export class AgentExternalIdConflictError extends Error {
+ readonly tenant_id: string;
+ readonly external_id: string;
+
+ constructor({ tenant_id, external_id }: { tenant_id: string; external_id: string }, options?: ErrorOptions) {
+ super(`Agent already exists for external id: ${external_id}`, options);
+ this.name = 'AgentExternalIdConflictError';
+ this.tenant_id = tenant_id;
+ this.external_id = external_id;
+ }
+}
+
export interface IAgentStore<TTransaction = never> {
listAgents(tenantId: string, transaction?: TTransaction): Promise<AgentRecord[]>;
getAgent(input: GetAgentInput, transaction?: TTransaction): Promise<AgentRecord | undefined>;
- /** Inserts a new agent with a generated ULID. Throws AgentNameConflictError on name clash. */
+ /** Inserts a new agent with a generated ULID. Throws AgentNameConflictError or AgentExternalIdConflictError on unique clash. */
createAgent(input: CreateAgentInput, transaction?: TTransaction): Promise<AgentRecord>;
- /** Patches `manifest` and/or `metadata` for an existing id. Returns undefined if missing. */
+ /** Patches `manifest`, `metadata`, and/or `external_id`. Throws AgentExternalIdConflictError on unique clash. Returns undefined if missing. */
updateAgent(input: UpdateAgentInput, transaction?: TTransaction): Promise<AgentRecord | undefined>;
/** Deletes by immutable id. Idempotent if already missing. */
deleteAgent(input: DeleteAgentInput, transaction?: TTransaction): Promise<void>;
diff --git a/packages/trueforge/src/db/indexes.ts b/packages/trueforge/src/db/indexes.ts
index 1d546d39f..06720ebb7 100644
--- a/packages/trueforge/src/db/indexes.ts
+++ b/packages/trueforge/src/db/indexes.ts
@@ -1,2 +1,5 @@
/** Partial unique index on `session (tenant_id, external_id) WHERE external_id IS NOT NULL`. */
export const SESSION_EXTERNAL_ID_UQ = 'session_external_id_uq';
+
+/** Partial unique index on `agent (tenant_id, external_id) WHERE external_id IS NOT NULL`. */
+export const AGENT_EXTERNAL_ID_UQ = 'agent_external_id_uq';
diff --git a/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts b/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts
index 0947caf25..97f58c8c7 100644
--- a/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts
+++ b/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts
@@ -2,6 +2,7 @@ import type { Kysely, Selectable, Transaction } from 'kysely';
import { EMPTY_AGENT_METADATA } from '../../../schemas/agentMetadata';
import { newId } from '../../../utils/id';
import {
+ AgentExternalIdConflictError,
AgentNameConflictError,
parseStoredAgentSpec,
type AgentRecord,
@@ -11,7 +12,8 @@ import {
type IAgentStore,
type UpdateAgentInput,
} from '../../agentStore';
-import { isUniqueViolation } from '../client';
+import { AGENT_EXTERNAL_ID_UQ } from '../../indexes';
+import { isPgConstraint, isUniqueViolation } from '../client';
import { json, now } from '../sqlExpressions';
import type { AgentTable, Database } from '../types';
@@ -22,11 +24,30 @@ function toRecord(row: Selectable<AgentTable>): AgentRecord {
name: row.name,
manifest: parseStoredAgentSpec(row.manifest),
metadata: row.metadata,
+ external_id: row.external_id,
created_at: row.created_at.toISOString(),
updated_at: row.updated_at.toISOString(),
};
}
+/** Map unique violations to external_id vs name conflicts. */
+function throwAgentUniqueViolation({
+ error,
+ tenant_id,
+ name,
+ external_id,
+}: {
+ error: unknown;
+ tenant_id: string;
+ name: string;
+ external_id: string | null;
+}): never {
+ if (isPgConstraint(error, AGENT_EXTERNAL_ID_UQ) && external_id) {
+ throw new AgentExternalIdConflictError({ tenant_id, external_id }, { cause: error });
+ }
+ throw new AgentNameConflictError({ tenant_id, name }, { cause: error });
+}
+
export class PostgresAgentStore implements IAgentStore<Transaction<Database>> {
readonly #db: Kysely<Database>;
@@ -63,6 +84,7 @@ export class PostgresAgentStore implements IAgentStore<Transaction<Database>> {
name: input.name,
manifest: json(input.manifest),
metadata: json(EMPTY_AGENT_METADATA),
+ external_id: input.external_id,
created_at: now(),
updated_at: now(),
})
@@ -71,29 +93,45 @@ export class PostgresAgentStore implements IAgentStore<Transaction<Database>> {
return toRecord(row);
} catch (error) {
if (isUniqueViolation(error)) {
- throw new AgentNameConflictError({ tenant_id: input.tenant_id, name: input.name }, { cause: error });
+ throwAgentUniqueViolation({
+ error,
+ tenant_id: input.tenant_id,
+ name: input.name,
+ external_id: input.external_id,
+ });
}
throw error;
}
}
async updateAgent(input: UpdateAgentInput, transaction?: Transaction<Database>): Promise<AgentRecord | undefined> {
- if (input.manifest === undefined && input.metadata === undefined) {
- throw new Error('updateAgent requires manifest and/or metadata');
+ if (input.manifest === undefined && input.metadata === undefined && input.external_id === undefined) {
+ throw new Error('updateAgent requires manifest, metadata, and/or external_id');
}
const db = transaction ?? this.#db;
- const row = await db
- .updateTable('agent')
- .set({
- ...(input.manifest === undefined ? {} : { manifest: json(input.manifest) }),
- ...(input.metadata === undefined ? {} : { metadata: json(input.metadata) }),
- updated_at: now(),
- })
- .where('tenant_id', '=', input.tenant_id)
- .where('id', '=', input.id)
- .returningAll()
- .executeTakeFirst();
- return row === undefined ? undefined : toRecord(row);
+ try {
+ const row = await db
+ .updateTable('agent')
+ .set({
+ ...(input.manifest === undefined ? {} : { manifest: json(input.manifest) }),
+ ...(input.metadata === undefined ? {} : { metadata: json(input.metadata) }),
+ ...(input.external_id === undefined ? {} : { external_id: input.external_id }),
+ updated_at: now(),
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('id', '=', input.id)
+ .returningAll()
+ .executeTakeFirst();
+ return row === undefined ? undefined : toRecord(row);
+ } catch (error) {
+ if (isUniqueViolation(error) && input.external_id) {
+ throw new AgentExternalIdConflictError(
+ { tenant_id: input.tenant_id, external_id: input.external_id },
+ { cause: error },
+ );
+ }
+ throw error;
+ }
}
async deleteAgent(input: DeleteAgentInput, transaction?: Transaction<Database>): Promise<void> {
diff --git a/packages/trueforge/src/db/postgres/migrations/20260902_000002_agent_external_id.ts b/packages/trueforge/src/db/postgres/migrations/20260902_000002_agent_external_id.ts
new file mode 100644
index 000000000..af10b144b
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20260902_000002_agent_external_id.ts
@@ -0,0 +1,22 @@
+import { sql, type Kysely } from 'kysely';
+import { AGENT_EXTERNAL_ID_UQ } from '../../indexes';
+
+/**
+ * Optional agent `external_id`, unique within a tenant when set.
+ * NULLs are excluded so agents without an external id do not collide.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await db.schema.alterTable('agent').addColumn('external_id', 'text').execute();
+ await sql`
+ CREATE UNIQUE INDEX ${sql.raw(AGENT_EXTERNAL_ID_UQ)}
+ ON agent (tenant_id, external_id)
+ WHERE external_id IS NOT NULL
+ `.execute(db);
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await sql`DROP INDEX IF EXISTS ${sql.raw(AGENT_EXTERNAL_ID_UQ)}`.execute(db);
+ await db.schema.alterTable('agent').dropColumn('external_id').execute();
+}
diff --git a/packages/trueforge/src/db/postgres/types.ts b/packages/trueforge/src/db/postgres/types.ts
index 20d35853f..20f2603ca 100644
--- a/packages/trueforge/src/db/postgres/types.ts
+++ b/packages/trueforge/src/db/postgres/types.ts
@@ -378,6 +378,7 @@ export interface AgentTable {
manifest: JSONColumnType<AgentSpec, AgentSpec, AgentSpec>;
/** `agent.metadata` jsonb; default `{}` for existing rows */
metadata: JSONColumnType<AgentMetadata, AgentMetadata, AgentMetadata>;
+ external_id: string | null;
created_at: Date;
updated_at: Date;
}
diff --git a/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts b/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts
index 026f183ee..f9fb814b3 100644
--- a/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts
+++ b/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts
@@ -3,6 +3,7 @@ import type { ExpressionBuilder, Kysely, Transaction } from 'kysely';
import { EMPTY_AGENT_METADATA, type AgentMetadata } from '../../../schemas/agentMetadata';
import { newId } from '../../../utils/id';
import {
+ AgentExternalIdConflictError,
AgentNameConflictError,
parseStoredAgentSpec,
type AgentRecord,
@@ -24,6 +25,7 @@ function recordColumns(eb: ExpressionBuilder<Database, 'agent'>) {
'name' as const,
jsonText<AgentSpec>(eb.ref('manifest')).as('manifest'),
jsonText<AgentMetadata>(eb.ref('metadata')).as('metadata'),
+ 'external_id' as const,
'created_at' as const,
'updated_at' as const,
];
@@ -35,6 +37,7 @@ function toRecord(row: {
name: AgentRecord['name'];
manifest: AgentSpec;
metadata: AgentMetadata;
+ external_id: string | null;
created_at: string;
updated_at: string;
}): AgentRecord {
@@ -83,6 +86,7 @@ export class SqliteAgentStore implements IAgentStore<Transaction<Database>> {
name: input.name,
manifest: jsonbBind(input.manifest),
metadata: jsonbBind(EMPTY_AGENT_METADATA),
+ external_id: input.external_id,
created_at: timestamp,
updated_at: timestamp,
})
@@ -91,33 +95,79 @@ export class SqliteAgentStore implements IAgentStore<Transaction<Database>> {
return toRecord(row);
} catch (error) {
if (isUniqueViolation(error)) {
- throw new AgentNameConflictError({ tenant_id: input.tenant_id, name: input.name }, { cause: error });
+ await this.throwCreateUnique({
+ error,
+ tenant_id: input.tenant_id,
+ name: input.name,
+ external_id: input.external_id,
+ ...(transaction === undefined ? {} : { transaction }),
+ });
}
throw error;
}
}
async updateAgent(input: UpdateAgentInput, transaction?: Transaction<Database>): Promise<AgentRecord | undefined> {
- if (input.manifest === undefined && input.metadata === undefined) {
- throw new Error('updateAgent requires manifest and/or metadata');
+ if (input.manifest === undefined && input.metadata === undefined && input.external_id === undefined) {
+ throw new Error('updateAgent requires manifest, metadata, and/or external_id');
}
const db = transaction ?? this.#db;
- const row = await db
- .updateTable('agent')
- .set({
- ...(input.manifest === undefined ? {} : { manifest: jsonbBind(input.manifest) }),
- ...(input.metadata === undefined ? {} : { metadata: jsonbBind(input.metadata) }),
- updated_at: nowIso(),
- })
- .where('tenant_id', '=', input.tenant_id)
- .where('id', '=', input.id)
- .returning(recordColumns)
- .executeTakeFirst();
- return row === undefined ? undefined : toRecord(row);
+ try {
+ const row = await db
+ .updateTable('agent')
+ .set({
+ ...(input.manifest === undefined ? {} : { manifest: jsonbBind(input.manifest) }),
+ ...(input.metadata === undefined ? {} : { metadata: jsonbBind(input.metadata) }),
+ ...(input.external_id === undefined ? {} : { external_id: input.external_id }),
+ updated_at: nowIso(),
+ })
+ .where('tenant_id', '=', input.tenant_id)
+ .where('id', '=', input.id)
+ .returning(recordColumns)
+ .executeTakeFirst();
+ return row === undefined ? undefined : toRecord(row);
+ } catch (error) {
+ if (isUniqueViolation(error) && input.external_id) {
+ throw new AgentExternalIdConflictError(
+ { tenant_id: input.tenant_id, external_id: input.external_id },
+ { cause: error },
+ );
+ }
+ throw error;
+ }
}
async deleteAgent(input: DeleteAgentInput, transaction?: Transaction<Database>): Promise<void> {
const db = transaction ?? this.#db;
await db.deleteFrom('agent').where('tenant_id', '=', input.tenant_id).where('id', '=', input.id).execute();
}
+
+ /** Map unique violations to external_id vs name conflicts. */
+ private async throwCreateUnique({
+ error,
+ tenant_id,
+ name,
+ external_id,
+ transaction,
+ }: {
+ error: unknown;
+ tenant_id: string;
+ name: string;
+ external_id: string | null;
+ transaction?: Transaction<Database>;
+ }): Promise<never> {
+ if (external_id !== null) {
+ const db = transaction ?? this.#db;
+ const owner = await db
+ .selectFrom('agent')
+ .select('id')
+ .where('tenant_id', '=', tenant_id)
+ .where('external_id', '=', external_id)
+ .executeTakeFirst();
+ if (owner !== undefined) {
+ throw new AgentExternalIdConflictError({ tenant_id, external_id }, { cause: error });
+ }
+ }
+ throw new AgentNameConflictError({ tenant_id, name }, { cause: error });
+ }
}
diff --git a/packages/trueforge/src/db/sqlite/migrations/20260902_000002_agent_external_id.ts b/packages/trueforge/src/db/sqlite/migrations/20260902_000002_agent_external_id.ts
new file mode 100644
index 000000000..2bde0b4cb
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20260902_000002_agent_external_id.ts
@@ -0,0 +1,24 @@
+import { type Kysely, sql } from 'kysely';
+import { AGENT_EXTERNAL_ID_UQ } from '../../indexes';
+
+/**
+ * Optional agent `external_id`, unique within a tenant when set.
+ * NULLs are excluded so agents without an external id do not collide.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`ALTER TABLE agent ADD COLUMN external_id TEXT`.execute(trx);
+ await sql`
+ CREATE UNIQUE INDEX ${sql.raw(AGENT_EXTERNAL_ID_UQ)}
+ ON agent (tenant_id, external_id)
+ WHERE external_id IS NOT NULL
+ `.execute(trx);
+ });
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await db.transaction().execute(async trx => {
+ await sql`DROP INDEX IF EXISTS ${sql.raw(AGENT_EXTERNAL_ID_UQ)}`.execute(trx);
+ await sql`ALTER TABLE agent DROP COLUMN external_id`.execute(trx);
+ });
+}
diff --git a/packages/trueforge/src/db/sqlite/types.ts b/packages/trueforge/src/db/sqlite/types.ts
index 522f9b71c..8cd9c0184 100644
--- a/packages/trueforge/src/db/sqlite/types.ts
+++ b/packages/trueforge/src/db/sqlite/types.ts
@@ -224,6 +224,7 @@ export interface AgentTable {
manifest: JsonbColumn<AgentSpec>;
/** `agent.metadata` jsonb; default `{}` for existing rows */
metadata: JsonbColumn<AgentMetadata>;
+ external_id: string | null;
created_at: string;
updated_at: string;
}
diff --git a/packages/trueforge/tests/db/agentStoreContractSuite.ts b/packages/trueforge/tests/db/agentStoreContractSuite.ts
index 65844b64b..46c91cb38 100644
--- a/packages/trueforge/tests/db/agentStoreContractSuite.ts
+++ b/packages/trueforge/tests/db/agentStoreContractSuite.ts
@@ -3,7 +3,7 @@
* Runs under jest against a fresh store per test (see backend test files).
*/
import { AgentSpecSchema, type AgentSpec } from '@truefoundry/trueforge-core/agent-session';
-import { AgentNameConflictError, type IAgentStore } from '../../src/db/agentStore';
+import { AgentExternalIdConflictError, AgentNameConflictError, type IAgentStore } from '../../src/db/agentStore';
const TENANT = 'default';
@@ -24,6 +24,7 @@ export function runAgentStoreContractSuite(getStore: () => IAgentStore): void {
tenant_id: TENANT,
name: 'research',
manifest: manifest(),
+ external_id: null,
});
expect(created.tenant_id).toBe(TENANT);
@@ -31,6 +32,7 @@ export function runAgentStoreContractSuite(getStore: () => IAgentStore): void {
expect(created.id.length).toBeGreaterThan(0);
expect(created.manifest).toEqual(manifest());
expect(created.metadata).toEqual({});
+ expect(created.external_id).toBeNull();
expect(created.created_at).toMatch(ISO_UTC);
expect(created.updated_at).toBe(created.created_at);
@@ -53,6 +55,7 @@ export function runAgentStoreContractSuite(getStore: () => IAgentStore): void {
tenant_id: TENANT,
name: 'research',
manifest: manifest(),
+ external_id: null,
});
const replacement = manifest({ instructions: 'Updated instructions.' });
@@ -86,6 +89,7 @@ export function runAgentStoreContractSuite(getStore: () => IAgentStore): void {
tenant_id: TENANT,
name: 'research',
manifest: manifest(),
+ external_id: null,
});
const updated = await store.updateAgent({
@@ -135,22 +139,43 @@ export function runAgentStoreContractSuite(getStore: () => IAgentStore): void {
it('createAgent throws AgentNameConflictError on name clash', async () => {
const store = getStore();
- await store.createAgent({ tenant_id: TENANT, name: 'research', manifest: manifest() });
+ await store.createAgent({
+ tenant_id: TENANT,
+ name: 'research',
+ manifest: manifest(),
+ external_id: null,
+ });
await expect(
- store.createAgent({ tenant_id: TENANT, name: 'research', manifest: manifest() }),
+ store.createAgent({
+ tenant_id: TENANT,
+ name: 'research',
+ manifest: manifest(),
+ external_id: null,
+ }),
).rejects.toBeInstanceOf(AgentNameConflictError);
});
it('listAgents returns only the tenant, ordered by name', async () => {
const store = getStore();
- await store.createAgent({ tenant_id: TENANT, name: 'zeta', manifest: manifest() });
+ await store.createAgent({
+ tenant_id: TENANT,
+ name: 'zeta',
+ manifest: manifest(),
+ external_id: null,
+ });
await store.createAgent({
tenant_id: TENANT,
name: 'alpha',
manifest: manifest({ instructions: 'Alpha agent.' }),
+ external_id: null,
+ });
+ await store.createAgent({
+ tenant_id: 'other-tenant',
+ name: 'research',
+ manifest: manifest(),
+ external_id: null,
});
- await store.createAgent({ tenant_id: 'other-tenant', name: 'research', manifest: manifest() });
const agents = await store.listAgents(TENANT);
expect(agents.map(agent => agent.name)).toEqual(['alpha', 'zeta']);
@@ -163,8 +188,88 @@ export function runAgentStoreContractSuite(getStore: () => IAgentStore): void {
tenant_id: TENANT,
name: 'research',
manifest: manifest(),
+ external_id: null,
});
expect(await store.getAgent({ tenant_id: 'other-tenant', id: created.id })).toBeUndefined();
});
+
+ it('createAgent persists external_id', async () => {
+ const store = getStore();
+ const created = await store.createAgent({
+ tenant_id: TENANT,
+ name: 'research',
+ manifest: manifest(),
+ external_id: 'sf-agent-1',
+ });
+ expect(created.external_id).toBe('sf-agent-1');
+ expect(await store.getAgent({ tenant_id: TENANT, id: created.id })).toEqual(created);
+ });
+
+ it('createAgent unique external_id within a tenant; nulls and other tenants do not collide', async () => {
+ const store = getStore();
+ await store.createAgent({
+ tenant_id: TENANT,
+ name: 'alpha',
+ manifest: manifest(),
+ external_id: 'shared-key',
+ });
+ await expect(
+ store.createAgent({
+ tenant_id: TENANT,
+ name: 'beta',
+ manifest: manifest(),
+ external_id: 'shared-key',
+ }),
+ ).rejects.toBeInstanceOf(AgentExternalIdConflictError);
+ await store.createAgent({
+ tenant_id: 'other-tenant',
+ name: 'alpha',
+ manifest: manifest(),
+ external_id: 'shared-key',
+ });
+ await store.createAgent({ tenant_id: TENANT, name: 'gamma', manifest: manifest(), external_id: null });
+ await store.createAgent({ tenant_id: TENANT, name: 'delta', manifest: manifest(), external_id: null });
+ });
+
+ it('updateAgent can write and clear external_id', async () => {
+ const store = getStore();
+ const created = await store.createAgent({
+ tenant_id: TENANT,
+ name: 'research',
+ manifest: manifest(),
+ external_id: null,
+ });
+ const updated = await store.updateAgent({
+ tenant_id: TENANT,
+ id: created.id,
+ external_id: 'sf-agent-1',
+ });
+ expect(updated?.external_id).toBe('sf-agent-1');
+ const cleared = await store.updateAgent({
+ tenant_id: TENANT,
+ id: created.id,
+ external_id: null,
+ });
+ expect(cleared?.external_id).toBeNull();
+ });
+
+ it('updateAgent throws AgentExternalIdConflictError when external_id is taken', async () => {
+ const store = getStore();
+ await store.createAgent({
+ tenant_id: TENANT,
+ name: 'alpha',
+ manifest: manifest(),
+ external_id: 'shared-key',
+ });
+ const beta = await store.createAgent({
+ tenant_id: TENANT,
+ name: 'beta',
+ manifest: manifest(),
+ external_id: null,
+ });
+ await expect(
+ store.updateAgent({ tenant_id: TENANT, id: beta.id, external_id: 'shared-key' }),
+ ).rejects.toBeInstanceOf(AgentExternalIdConflictError);
+ });
}
diff --git a/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts b/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts
index 42bed510f..d6a9b15b6 100644
--- a/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts
+++ b/packages/trueforge/tests/db/scheduleDispatchContractSuite.ts
@@ -64,6 +64,7 @@ export function runScheduleDispatchContractSuite<TTransaction>(deps: {
model: { name: 'anthropic/claude-sonnet-4-6' },
instructions: 'Be helpful.',
}),
+ external_id: null,
});
return agent.name;
}
diff --git a/packages/trueforge/tests/db/scheduleStoreContractSuite.ts b/packages/trueforge/tests/db/scheduleStoreContractSuite.ts
index b83a627e0..7097e5657 100644
--- a/packages/trueforge/tests/db/scheduleStoreContractSuite.ts
+++ b/packages/trueforge/tests/db/scheduleStoreContractSuite.ts
@@ -29,6 +29,7 @@ export function runScheduleStoreContractSuite(deps: {
model: { name: 'anthropic/claude-sonnet-4-6' },
instructions: 'Be helpful.',
}),
+ external_id: null,
});
return { id: agent.id, name: agent.name };
}
diff --git a/packages/trueforge/tests/unit/apis/schedules.test.ts b/packages/trueforge/tests/unit/apis/schedules.test.ts
index abdfff846..b98b088ed 100644
--- a/packages/trueforge/tests/unit/apis/schedules.test.ts
+++ b/packages/trueforge/tests/unit/apis/schedules.test.ts
@@ -42,6 +42,7 @@ async function setup() {
tenant_id: TENANT_ID,
name: 'reporter',
manifest: AgentSpecSchema.parse({ model: { name: 'test-provider/test-model' }, instructions: 'test' }),
+ external_id: null,
});
let current: UserContext = ALICE;
@@ -155,6 +156,7 @@ describe('schedule RBAC — creator-scoped, admin sees all', () => {
tenant_id: TENANT_ID,
name: 'reporter-two',
manifest: AgentSpecSchema.parse({ model: { name: 'test-provider/test-model' }, instructions: 'test' }),
+ external_id: null,
});
asUser(ALICE);
@@ -190,6 +192,7 @@ describe('schedule list agent_names filter', () => {
tenant_id: TENANT_ID,
name: 'reporter-two',
manifest: AgentSpecSchema.parse({ model: { name: 'test-provider/test-model' }, instructions: 'test' }),
+ external_id: null,
});
asUser(ALICE);
diff --git a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
index 3f1767bc8..6bebb6c2b 100644
--- a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
+++ b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
@@ -130,6 +130,7 @@ describe('sessions HTTP agent binding', () => {
model: { name: 'anthropic/claude-sonnet-4-6' },
instructions: 'from-registry',
}),
+ external_id: null,
});
const created = await app.request('/', jsonInit('POST', { agent: { name: agent.name } }));
@@ -153,6 +154,7 @@ describe('sessions HTTP agent binding', () => {
tenant_id: TENANT_ID,
name: 'metrics-agent',
manifest: inlineSpec,
+ external_id: null,
});
await sessionStore.createSession({
tenant_id: TENANT_ID,
@@ -280,6 +282,7 @@ describe('sessions HTTP agent binding', () => {
model: { name: 'anthropic/claude-sonnet-4-6' },
instructions: 'from-registry',
}),
+ external_id: null,
});
const created = await app.request('/', jsonInit('POST', { agent: { name: agent.name } }));