Skip to content

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

add session get-or-create-by-external-id endpoint (#515)

Heer Ambavi38ce0685ea75
diff --git a/.changeset/session-external-id.md b/.changeset/session-external-id.md
new file mode 100644
index 000000000..16193f1d9
--- /dev/null
+++ b/.changeset/session-external-id.md
@@ -0,0 +1,7 @@
+---
+"@truefoundry/trueforge": patch
+"@truefoundry/trueforge-core": patch
+"@truefoundry/trueforge-sdk": patch
+---
+
+Add tenant-unique optional session `external_id`, `Sessions.getOrCreateByExternalId`, and an idempotent `POST /internal/sessions/get-or-create-by-external-id` endpoint and SDK method.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 3c7d7aacb..5d269a904 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -1355,6 +1355,25 @@
],
"type": "object"
},
+ "GetOrCreateSessionByExternalIdRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "agent": {
+ "$ref": "#/components/schemas/CreateSessionAgent"
+ },
+ "external_id": {
+ "description": "Caller-supplied id unique within the tenant.",
+ "maxLength": 128,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "external_id",
+ "agent"
+ ],
+ "type": "object"
+ },
"GetSandboxProviderCatalogResponse": {
"properties": {
"data": {
@@ -7660,6 +7679,92 @@
],
"x-fern-sdk-method-name": "list"
}
+ },
+ "/internal/sessions/get-or-create-by-external-id": {
+ "post": {
+ "description": "Idempotent get-or-create: returns the existing session for this `external_id`, or creates one",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetOrCreateSessionByExternalIdRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetSessionResponse"
+ }
+ }
+ },
+ "description": "Session already existed for this external id."
+ },
+ "201": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetSessionResponse"
+ }
+ }
+ },
+ "description": "Session created."
+ },
+ "400": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid request body."
+ },
+ "403": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Caller is not the session creator."
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Named agent not found."
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "The agent spec is valid but references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox)."
+ }
+ },
+ "summary": "Get or create a session by external id",
+ "tags": [
+ "Internal"
+ ],
+ "x-fern-sdk-group-name": [
+ "internal",
+ "sessions"
+ ],
+ "x-fern-sdk-method-name": "get_or_create_by_external_id"
+ }
}
},
"security": [
@@ -7668,6 +7773,9 @@
}
],
"tags": [
+ {
+ "name": "Internal"
+ },
{
"name": "Auth"
},
diff --git a/docs/openapi.json b/docs/openapi.json
index 3c7d7aacb..5d269a904 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -1355,6 +1355,25 @@
],
"type": "object"
},
+ "GetOrCreateSessionByExternalIdRequest": {
+ "additionalProperties": false,
+ "properties": {
+ "agent": {
+ "$ref": "#/components/schemas/CreateSessionAgent"
+ },
+ "external_id": {
+ "description": "Caller-supplied id unique within the tenant.",
+ "maxLength": 128,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "external_id",
+ "agent"
+ ],
+ "type": "object"
+ },
"GetSandboxProviderCatalogResponse": {
"properties": {
"data": {
@@ -7660,6 +7679,92 @@
],
"x-fern-sdk-method-name": "list"
}
+ },
+ "/internal/sessions/get-or-create-by-external-id": {
+ "post": {
+ "description": "Idempotent get-or-create: returns the existing session for this `external_id`, or creates one",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetOrCreateSessionByExternalIdRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetSessionResponse"
+ }
+ }
+ },
+ "description": "Session already existed for this external id."
+ },
+ "201": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetSessionResponse"
+ }
+ }
+ },
+ "description": "Session created."
+ },
+ "400": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Invalid request body."
+ },
+ "403": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Caller is not the session creator."
+ },
+ "404": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "Named agent not found."
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "The agent spec is valid but references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox)."
+ }
+ },
+ "summary": "Get or create a session by external id",
+ "tags": [
+ "Internal"
+ ],
+ "x-fern-sdk-group-name": [
+ "internal",
+ "sessions"
+ ],
+ "x-fern-sdk-method-name": "get_or_create_by_external_id"
+ }
}
},
"security": [
@@ -7668,6 +7773,9 @@
}
],
"tags": [
+ {
+ "name": "Internal"
+ },
{
"name": "Auth"
},
diff --git a/packages/trueforge-core/src/agent-session/Sessions.ts b/packages/trueforge-core/src/agent-session/Sessions.ts
index bc5376c5a..5d94a8b86 100644
--- a/packages/trueforge-core/src/agent-session/Sessions.ts
+++ b/packages/trueforge-core/src/agent-session/Sessions.ts
@@ -2,8 +2,15 @@
* Storage-only session collection: create / get. Behavior arrives per run via
* the resolver on {@link SessionHandle.createTurn}.
*/
+import { ulid } from 'ulid';
import { SessionHandle } from './SessionHandle';
-import type { CreateSessionInput, GetSessionInput, ISessionStore } from './store/ISessionStore';
+import type {
+ CreateSessionInput,
+ GetSessionByExternalIdInput,
+ GetSessionInput,
+ ISessionStore,
+} from './store/ISessionStore';
+import { SessionExternalIdConflictError } from './store/SessionStoreErrors';
export type SessionsCreateInput<TSessionCustom extends object> = Omit<CreateSessionInput<TSessionCustom>, 'custom'> & {
custom?: TSessionCustom | undefined;
@@ -54,4 +61,53 @@ export class Sessions<
session: record,
});
}
+
+ /**
+ * Returns the session bound to this tenant-scoped external id, or undefined.
+ * Read-only: does not bump last_activity_timestamp_ms.
+ */
+ async getByExternalId(
+ input: GetSessionByExternalIdInput,
+ ): Promise<SessionHandle<TSessionCustom, TTurnCustom> | undefined> {
+ const record = await this.store.getSessionByExternalId(input);
+ if (!record) {
+ return undefined;
+ }
+ return new SessionHandle({
+ store: this.store,
+ session: record,
+ });
+ }
+
+ /**
+ * Get-or-create the session bound to a tenant-scoped `external_id`.
+ */
+ async getOrCreateByExternalId(
+ input: Omit<SessionsCreateInput<TSessionCustom>, 'session_id' | 'external_id'> & { external_id: string },
+ ): Promise<{ session: SessionHandle<TSessionCustom, TTurnCustom>; created: boolean }> {
+ const { tenant_id, external_id } = input;
+
+ const existing = await this.getByExternalId({ tenant_id, external_id });
+ if (existing !== undefined) {
+ return { session: existing, created: false };
+ }
+
+ try {
+ const session = await this.create({
+ ...input,
+ session_id: ulid().toLowerCase(),
+ external_id,
+ });
+ return { session, created: true };
+ } catch (error) {
+ if (!(error instanceof SessionExternalIdConflictError)) {
+ throw error;
+ }
+ const winner = await this.getByExternalId({ tenant_id, external_id });
+ if (winner === undefined) {
+ throw error;
+ }
+ return { session: winner, created: false };
+ }
+ }
}
diff --git a/packages/trueforge-core/src/agent-session/index.ts b/packages/trueforge-core/src/agent-session/index.ts
index 4c9277089..5da6e8278 100644
--- a/packages/trueforge-core/src/agent-session/index.ts
+++ b/packages/trueforge-core/src/agent-session/index.ts
@@ -56,6 +56,7 @@ export type {
CreateTurnInput,
DeleteSessionInput,
FreezeAndGetTurnInput,
+ GetSessionByExternalIdInput,
GetSessionInput,
GetTurnInput,
ISessionStore,
@@ -78,6 +79,7 @@ export {
InvalidPageTokenError,
PreviousTurnRunningError,
SessionAlreadyExistsError,
+ SessionExternalIdConflictError,
SessionNotFoundError,
SessionStoreConflictError,
SessionStoreInvariantError,
diff --git a/packages/trueforge-core/src/agent-session/models/SessionRecord.ts b/packages/trueforge-core/src/agent-session/models/SessionRecord.ts
index 721ad6731..21497510b 100644
--- a/packages/trueforge-core/src/agent-session/models/SessionRecord.ts
+++ b/packages/trueforge-core/src/agent-session/models/SessionRecord.ts
@@ -16,6 +16,11 @@ export interface SessionRecord<TCustom extends object = Record<string, never>> {
* update_session_title_if_not_exist (first write wins; caller derives).
*/
title: string | null;
+ /**
+ * Optional caller-supplied key, unique within a tenant when set.
+ * Null means the session has no external id.
+ */
+ external_id: string | null;
/**
* Session tip — used for `previous_turn_id: 'auto'` resolution and turn
* listing anchors. Advanced only by `createTurn` (atomic link).
diff --git a/packages/trueforge-core/src/agent-session/store/ISessionStore.ts b/packages/trueforge-core/src/agent-session/store/ISessionStore.ts
index 87222662a..41bd1b60a 100644
--- a/packages/trueforge-core/src/agent-session/store/ISessionStore.ts
+++ b/packages/trueforge-core/src/agent-session/store/ISessionStore.ts
@@ -19,7 +19,7 @@ import type { CancellationReason, TerminalTurnState } from '../schemas/turn';
*/
export type CreateSessionInput<TSessionCustom extends object = Record<string, never>> = Pick<
SessionRecord<TSessionCustom>,
- 'tenant_id' | 'session_id' | 'agent' | 'created_by'
+ 'tenant_id' | 'session_id' | 'agent' | 'created_by' | 'external_id'
> & {
custom: TSessionCustom | null;
};
@@ -41,6 +41,11 @@ export interface GetSessionInput {
session_id: string;
}
+export interface GetSessionByExternalIdInput {
+ tenant_id: string;
+ external_id: string;
+}
+
export interface DeleteSessionInput {
tenant_id: string;
session_id: string;
@@ -229,6 +234,12 @@ export interface ISessionStore<
*/
getSession(input: GetSessionInput): Promise<SessionRecord<TSessionCustom> | undefined>;
+ /**
+ * Lookup by tenant-scoped `external_id`. Missing or null external ids are not found.
+ * Does **not** bump `last_activity_timestamp_ms` (read path).
+ */
+ getSessionByExternalId(input: GetSessionByExternalIdInput): Promise<SessionRecord<TSessionCustom> | undefined>;
+
/**
* PATCH semantics — update only the provided fields:
* - agent: replace inline binding (inline sessions only; reference → invariant error).
diff --git a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
index 095f32c47..3dc0e0f56 100644
--- a/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
+++ b/packages/trueforge-core/src/agent-session/store/InMemorySessionStore.ts
@@ -14,6 +14,7 @@ import type {
CreateTurnInput,
DeleteSessionInput,
FreezeAndGetTurnInput,
+ GetSessionByExternalIdInput,
GetSessionInput,
GetTurnInput,
ISessionStore,
@@ -42,6 +43,7 @@ import { decodeSessionListPageToken, paginateSessionListRows } from './SessionLi
import {
PreviousTurnRunningError,
SessionAlreadyExistsError,
+ SessionExternalIdConflictError,
SessionNotFoundError,
SessionStoreInvariantError,
TurnAlreadyExistsError,
@@ -173,6 +175,14 @@ export class InMemorySessionStore<
if (this.sessions.has(key)) {
throw new SessionAlreadyExistsError(input.session_id);
}
+ const externalId = input.external_id;
+ if (externalId !== null) {
+ for (const stored of this.sessions.values()) {
+ if (stored.record.tenant_id === input.tenant_id && stored.record.external_id === externalId) {
+ throw new SessionExternalIdConflictError(externalId);
+ }
+ }
+ }
const now = new Date();
const record: SessionRecord<TSessionCustom> = {
tenant_id: input.tenant_id,
@@ -181,6 +191,7 @@ export class InMemorySessionStore<
agent: deepCopy(input.agent),
title: null,
last_turn_id: null,
+ external_id: externalId,
created_at: now,
updated_at: now,
last_activity_timestamp_ms: Date.now(),
@@ -214,6 +225,15 @@ export class InMemorySessionStore<
return stored?.record.tenant_id === input.tenant_id ? deepCopy(stored.record) : undefined;
}
+ async getSessionByExternalId(input: GetSessionByExternalIdInput): Promise<SessionRecord<TSessionCustom> | undefined> {
+ for (const stored of this.sessions.values()) {
+ if (stored.record.tenant_id === input.tenant_id && stored.record.external_id === input.external_id) {
+ return deepCopy(stored.record);
+ }
+ }
+ return undefined;
+ }
+
async updateSession(input: UpdateSessionInput<TSessionCustom>): Promise<void> {
const key = sessionKey(input.session_id);
const stored = this.sessions.get(key);
diff --git a/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts b/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts
index 3bffa80b6..89b31ee90 100644
--- a/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts
+++ b/packages/trueforge-core/src/agent-session/store/SessionStoreErrors.ts
@@ -54,6 +54,16 @@ export class SessionAlreadyExistsError extends SessionStoreConflictError {
}
}
+export class SessionExternalIdConflictError extends SessionStoreConflictError {
+ readonly external_id: string;
+
+ constructor(external_id: string, options?: ErrorOptions) {
+ super(`Session already exists for external id: ${external_id}`, options);
+ this.name = 'SessionExternalIdConflictError';
+ this.external_id = external_id;
+ }
+}
+
export class TurnAlreadyExistsError extends SessionStoreConflictError {
readonly turn_id: string;
diff --git a/packages/trueforge-core/tests/agent-session/capabilityState.test.ts b/packages/trueforge-core/tests/agent-session/capabilityState.test.ts
index 5b58e94fa..5cf6d74e9 100644
--- a/packages/trueforge-core/tests/agent-session/capabilityState.test.ts
+++ b/packages/trueforge-core/tests/agent-session/capabilityState.test.ts
@@ -64,6 +64,7 @@ describe('capability_state (tfy.plan fixture)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
const planV1: JsonValue = {
@@ -136,6 +137,7 @@ describe('capability_state (tfy.plan fixture)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
const planV1: JsonValue = {
todo: [{ title: 'step', description: 'do it', status: 'done' }],
@@ -229,6 +231,7 @@ describe('capability_state (tfy.plan fixture)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
const turn = await session.createTurn({
turn_id: mintTestTurnId(),
diff --git a/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts b/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts
index ed77de533..b2f6399df 100644
--- a/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts
+++ b/packages/trueforge-core/tests/agent-session/resolveAgentSpec.test.ts
@@ -91,6 +91,7 @@ describe('SessionHandle.createTurn named resolve', () => {
session_id: 's-named',
created_by: 'user-1',
agent: { type: 'reference', id: 'agent-abc', name: null },
+ external_id: null,
});
const live = makeAgentSpec({ instructions: 'from-registry' });
diff --git a/packages/trueforge-core/tests/agent-session/sessions.test.ts b/packages/trueforge-core/tests/agent-session/sessions.test.ts
index 3c37ec1fc..0463110c8 100644
--- a/packages/trueforge-core/tests/agent-session/sessions.test.ts
+++ b/packages/trueforge-core/tests/agent-session/sessions.test.ts
@@ -18,6 +18,7 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec({ instructions: 'hydrate-me' }) },
custom: { tag: 'a' },
+ external_id: null,
});
expect(created.agent).toEqual({
type: 'inline',
@@ -33,6 +34,61 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
expect(loaded?.session_id).toBe('s1');
});
+ it('getOrCreateByExternalId creates once and returns the existing row on retry', async () => {
+ const store = new InMemorySessionStore();
+ const sessions = new Sessions({ sessionStore: store });
+ const agent = { type: 'inline' as const, spec: makeAgentSpec({ instructions: 'first' }) };
+
+ const first = await sessions.getOrCreateByExternalId({
+ tenant_id: tenant,
+ created_by: 'user-1',
+ agent,
+ external_id: 'run-1',
+ });
+ expect(first.created).toBe(true);
+ expect(first.session.record.external_id).toBe('run-1');
+
+ const again = await sessions.getOrCreateByExternalId({
+ tenant_id: tenant,
+ created_by: 'other',
+ agent: { type: 'inline', spec: makeAgentSpec({ instructions: 'ignored' }) },
+ external_id: 'run-1',
+ });
+ expect(again.created).toBe(false);
+ expect(again.session.session_id).toBe(first.session.session_id);
+ expect(again.session.record.created_by).toBe('user-1');
+ expect(again.session.agent).toEqual({
+ type: 'inline',
+ spec: expect.objectContaining({ instructions: 'first' }),
+ });
+ });
+
+ it('getOrCreateByExternalId returns the winner when create loses the unique race', async () => {
+ const store = new InMemorySessionStore();
+ const sessions = new Sessions({ sessionStore: store });
+ const agent = { type: 'inline' as const, spec: makeAgentSpec() };
+
+ await sessions.create({
+ tenant_id: tenant,
+ session_id: 'winner',
+ created_by: 'user-1',
+ agent,
+ external_id: 'run-1',
+ });
+
+ const getByExternalId = jest.spyOn(sessions, 'getByExternalId');
+ getByExternalId.mockResolvedValueOnce(undefined);
+
+ const { session, created } = await sessions.getOrCreateByExternalId({
+ tenant_id: tenant,
+ created_by: 'user-2',
+ agent,
+ external_id: 'run-1',
+ });
+ expect(created).toBe(false);
+ expect(session.session_id).toBe('winner');
+ });
+
it('run() happy path commits a running turn without executing', async () => {
const store = new InMemorySessionStore();
const sessions = new Sessions({ sessionStore: store });
@@ -41,6 +97,7 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
const turn = await session.createTurn({
turn_id: mintTestTurnId(),
@@ -71,6 +128,7 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
const created = await session.createTurn({
turn_id: mintTestTurnId(),
@@ -108,6 +166,7 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
const turn = await session.createTurn({
turn_id: mintTestTurnId(),
@@ -136,6 +195,7 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
const t1 = await session.createTurn({
turn_id: mintTestTurnId(),
@@ -166,6 +226,7 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
const first = await session.createTurn({
turn_id: mintTestTurnId(),
@@ -198,6 +259,7 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
await expect(
session.createTurn({
@@ -235,6 +297,7 @@ describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
session_id: 's1',
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
+ external_id: null,
});
// Failure path: resources acquired before the throw must be released.
diff --git a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
index 243f9f537..6633e3fa7 100644
--- a/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
+++ b/packages/trueforge-core/tests/agent-session/store/storeContractSuite.ts
@@ -7,6 +7,7 @@ import type { ISessionStore } from '../../../src/agent-session/store/ISessionSto
import { decodeSessionEventPageToken } from '../../../src/agent-session/store/SessionEventPageToken';
import {
PreviousTurnRunningError,
+ SessionExternalIdConflictError,
SessionNotFoundError,
SessionStoreConflictError,
SessionStoreInvariantError,
@@ -85,6 +86,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'user-1',
agent: { type: 'inline', spec: agentSpec },
custom: null,
+ external_id: null,
});
}
@@ -190,6 +192,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: '[email protected]',
agent: { type: 'inline', spec: makeAgentSpec() },
custom: null,
+ external_id: null,
});
const session = mustGet(await store.getSession({ tenant_id: tenant, session_id: 'created-by-session' }));
expect(session.created_by).toBe('[email protected]');
@@ -216,6 +219,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'user-1',
agent: { type: 'reference', id: 'agent-abc', name: null },
custom: null,
+ external_id: null,
});
await seedSession(store);
@@ -243,6 +247,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'user-1',
agent: { type: 'reference', id: 'agent-abc', name: null },
custom: null,
+ external_id: null,
});
await expect(
@@ -301,9 +306,100 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
custom: null,
+ external_id: null,
}),
).rejects.toBeInstanceOf(SessionStoreConflictError);
});
+
+ it('createSession stores a null external_id', async () => {
+ const store = createStore();
+ await seedSession(store);
+ const record = await store.getSession({ tenant_id: tenant, session_id: sessionId });
+ expect(mustGet(record).external_id).toBeNull();
+ });
+
+ it('createSession persists external_id and getSessionByExternalId finds it', async () => {
+ const store = createStore();
+ await store.createSession({
+ tenant_id: tenant,
+ session_id: sessionId,
+ created_by: 'user-1',
+ agent: { type: 'inline', spec: makeAgentSpec() },
+ custom: null,
+ external_id: 'run-1',
+ });
+ const byId = await store.getSession({ tenant_id: tenant, session_id: sessionId });
+ expect(mustGet(byId).external_id).toBe('run-1');
+ const byExternal = await store.getSessionByExternalId({ tenant_id: tenant, external_id: 'run-1' });
+ expect(mustGet(byExternal).session_id).toBe(sessionId);
+ expect(await store.getSessionByExternalId({ tenant_id: tenant, external_id: 'missing' })).toBeUndefined();
+ expect(await store.getSessionByExternalId({ tenant_id: 'other', external_id: 'run-1' })).toBeUndefined();
+ });
+
+ it('createSession unique external_id within a tenant; nulls and other tenants do not collide', async () => {
+ const store = createStore();
+ await store.createSession({
+ tenant_id: tenant,
+ session_id: 's-a',
+ created_by: 'user-1',
+ agent: { type: 'inline', spec: makeAgentSpec() },
+ custom: null,
+ external_id: 'shared-key',
+ });
+ // Specifically the external-id arm, not just any conflict: get-or-create
+ // treats this rejection as its normal repeat-call path.
+ await expect(
+ store.createSession({
+ tenant_id: tenant,
+ session_id: 's-b',
+ created_by: 'user-1',
+ agent: { type: 'inline', spec: makeAgentSpec() },
+ custom: null,
+ external_id: 'shared-key',
+ }),
+ ).rejects.toBeInstanceOf(SessionExternalIdConflictError);
+
+ await store.createSession({
+ tenant_id: 'other',
+ session_id: 's-c',
+ created_by: 'user-1',
+ agent: { type: 'inline', spec: makeAgentSpec() },
+ custom: null,
+ external_id: 'shared-key',
+ });
+ await store.createSession({
+ tenant_id: tenant,
+ session_id: 's-d',
+ created_by: 'user-1',
+ agent: { type: 'inline', spec: makeAgentSpec() },
+ custom: null,
+ external_id: null,
+ });
+ await store.createSession({
+ tenant_id: tenant,
+ session_id: 's-e',
+ created_by: 'user-1',
+ agent: { type: 'inline', spec: makeAgentSpec() },
+ custom: null,
+ external_id: null,
+ });
+ });
+
+ it('getSessionByExternalId does not bump last_activity_timestamp_ms', async () => {
+ const store = createStore();
+ await store.createSession({
+ tenant_id: tenant,
+ session_id: sessionId,
+ created_by: 'user-1',
+ agent: { type: 'inline', spec: makeAgentSpec() },
+ custom: null,
+ external_id: 'run-1',
+ });
+ const first = await store.getSessionByExternalId({ tenant_id: tenant, external_id: 'run-1' });
+ await new Promise(r => setTimeout(r, 5));
+ const second = await store.getSessionByExternalId({ tenant_id: tenant, external_id: 'run-1' });
+ expect(mustGet(second).last_activity_timestamp_ms).toBe(mustGet(first).last_activity_timestamp_ms);
+ });
});
describe('deleteSession', () => {
@@ -316,6 +412,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
custom: null,
+ external_id: null,
});
await store.createTurn(
@@ -498,6 +595,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
custom: null,
+ external_id: null,
});
await store.createTurn(makeCreateTurnInput({ sessionId: nested, turnId: 'turn-1' }));
const nestedKeys = { session_id: nested, turn_id: 'turn-1' };
@@ -626,6 +724,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
custom: null,
+ external_id: null,
});
await new Promise(r => setTimeout(r, 2));
}
@@ -640,6 +739,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'user-1',
agent: { type: 'inline', spec: makeAgentSpec() },
custom: null,
+ external_id: null,
});
const desc = await store.listSessions({
@@ -792,6 +892,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'alice',
agent: { type: 'inline', spec: makeAgentSpec() },
custom: null,
+ external_id: null,
});
await store.createSession({
tenant_id: tenant,
@@ -799,6 +900,7 @@ export function runStoreContractSuite(createStore: () => ISessionStore) {
created_by: 'bob',
agent: { type: 'inline', spec: makeAgentSpec() },
custom: null,
+ external_id: null,
});
const aliceOnly = await store.listSessions({
diff --git a/packages/trueforge-core/tests/agent-session/turnStream.test.ts b/packages/trueforge-core/tests/agent-session/turnStream.test.ts
index 2c0c93d30..1ccd57e67 100644
--- a/packages/trueforge-core/tests/agent-session/turnStream.test.ts
+++ b/packages/trueforge-core/tests/agent-session/turnStream.test.ts
@@ -32,6 +32,7 @@ describe('TurnHandle.stream()', () => {
},
}),
},
+ external_id: null,
});
return { store, session };
}
@@ -493,6 +494,7 @@ describe('TurnResourceResolver caches', () => {
},
}),
},
+ external_id: null,
});
const turn = await session.createTurn({
turn_id: mintTestTurnId(),
diff --git a/packages/trueforge-sdk/package.json b/packages/trueforge-sdk/package.json
index 4741b5fd8..fe9ebec2d 100644
--- a/packages/trueforge-sdk/package.json
+++ b/packages/trueforge-sdk/package.json
@@ -194,6 +194,17 @@
},
"default": "./dist/cjs/api/resources/internal/resources/agents/exports.js"
},
+ "./internal/sessions": {
+ "import": {
+ "types": "./dist/esm/api/resources/internal/resources/sessions/exports.d.mts",
+ "default": "./dist/esm/api/resources/internal/resources/sessions/exports.mjs"
+ },
+ "require": {
+ "types": "./dist/cjs/api/resources/internal/resources/sessions/exports.d.ts",
+ "default": "./dist/cjs/api/resources/internal/resources/sessions/exports.js"
+ },
+ "default": "./dist/cjs/api/resources/internal/resources/sessions/exports.js"
+ },
"./settings": {
"import": {
"types": "./dist/esm/api/resources/settings/exports.d.mts",
diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.md
index fb50247e7..1cc749687 100644
--- a/packages/trueforge-sdk/reference.md
+++ b/packages/trueforge-sdk/reference.md
@@ -2496,6 +2496,75 @@ await client.internal.agents.getCodeSnippets("agent_id");
</dl>
+</dd>
+</dl>
+</details>
+
+## Internal Sessions
+<details><summary><code>client.internal.sessions.<a href="/src/api/resources/internal/resources/sessions/client/Client.ts">getOrCreateByExternalId</a>({ ...params }) -> TrueForge.GetSessionResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Idempotent get-or-create: returns the existing session for this `external_id`, or creates one
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.internal.sessions.getOrCreateByExternalId({
+ agent: {
+ name: "name"
+ },
+ externalId: "external_id"
+});
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**request:** `TrueForge.internal.GetOrCreateSessionByExternalIdRequest`
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `SessionsClient.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
</dd>
</dl>
</details>
diff --git a/packages/trueforge-sdk/src/api/resources/internal/client/Client.ts b/packages/trueforge-sdk/src/api/resources/internal/client/Client.ts
index b2c95313c..6022e3c4d 100644
--- a/packages/trueforge-sdk/src/api/resources/internal/client/Client.ts
+++ b/packages/trueforge-sdk/src/api/resources/internal/client/Client.ts
@@ -3,6 +3,7 @@
import type { BaseClientOptions } from "../../../../BaseClient.js";
import { type NormalizedClientOptionsWithAuth, normalizeClientOptionsWithAuth } from "../../../../BaseClient.js";
import { AgentsClient } from "../resources/agents/client/Client.js";
+import { SessionsClient } from "../resources/sessions/client/Client.js";
export declare namespace InternalClient {
export type Options = BaseClientOptions;
@@ -11,6 +12,7 @@ export declare namespace InternalClient {
export class InternalClient {
protected readonly _options: NormalizedClientOptionsWithAuth<InternalClient.Options>;
protected _agents: AgentsClient | undefined;
+ protected _sessions: SessionsClient | undefined;
constructor(options: InternalClient.Options) {
this._options = normalizeClientOptionsWithAuth(options);
@@ -19,4 +21,8 @@ export class InternalClient {
public get agents(): AgentsClient {
return (this._agents ??= new AgentsClient(this._options));
}
+
+ public get sessions(): SessionsClient {
+ return (this._sessions ??= new SessionsClient(this._options));
+ }
}
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts
index a9be31949..1d299c7a3 100644
--- a/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/index.ts
@@ -1 +1,3 @@
export * as agents from "./agents/index.js";
+export * from "./sessions/client/requests/index.js";
+export * as sessions from "./sessions/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/Client.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/Client.ts
new file mode 100644
index 000000000..4e7727113
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/Client.ts
@@ -0,0 +1,165 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../../../BaseClient.js";
+import { type NormalizedClientOptionsWithAuth, normalizeClientOptionsWithAuth } from "../../../../../../BaseClient.js";
+import { mergeHeaders } from "../../../../../../core/headers.js";
+import * as core from "../../../../../../core/index.js";
+import { mergeAdditionalBodyParameters } from "../../../../../../core/requestBody.js";
+import { handleNonStatusCodeError } from "../../../../../../errors/handleNonStatusCodeError.js";
+import * as errors from "../../../../../../errors/index.js";
+import * as serializers from "../../../../../../serialization/index.js";
+import * as TrueForge from "../../../../../index.js";
+
+export declare namespace SessionsClient {
+ export type Options = BaseClientOptions;
+
+ export interface RequestOptions extends BaseRequestOptions {}
+}
+
+export class SessionsClient {
+ protected readonly _options: NormalizedClientOptionsWithAuth<SessionsClient.Options>;
+
+ constructor(options: SessionsClient.Options) {
+ this._options = normalizeClientOptionsWithAuth(options);
+ }
+
+ /**
+ * Idempotent get-or-create: returns the existing session for this `external_id`, or creates one
+ *
+ * @param {TrueForge.internal.GetOrCreateSessionByExternalIdRequest} request
+ * @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
+ *
+ * @throws {@link TrueForge.BadRequestError}
+ * @throws {@link TrueForge.ForbiddenError}
+ * @throws {@link TrueForge.NotFoundError}
+ * @throws {@link TrueForge.UnprocessableEntityError}
+ * @throws {@link errors.TrueForgeError}
+ * @throws {@link errors.TrueForgeTimeoutError}
+ *
+ * @example
+ * await client.internal.sessions.getOrCreateByExternalId({
+ * agent: {
+ * name: "name"
+ * },
+ * externalId: "external_id"
+ * })
+ */
+ public getOrCreateByExternalId(
+ request: TrueForge.internal.GetOrCreateSessionByExternalIdRequest,
+ requestOptions?: SessionsClient.RequestOptions,
+ ): core.HttpResponsePromise<TrueForge.GetSessionResponse> {
+ return core.HttpResponsePromise.fromPromise(this.__getOrCreateByExternalId(request, requestOptions));
+ }
+
+ private async __getOrCreateByExternalId(
+ request: TrueForge.internal.GetOrCreateSessionByExternalIdRequest,
+ requestOptions?: SessionsClient.RequestOptions,
+ ): Promise<core.WithRawResponse<TrueForge.GetSessionResponse>> {
+ const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+ _authRequest.headers,
+ this._options?.headers,
+ requestOptions?.headers,
+ );
+ const _response = await (this._options.fetcher ?? core.fetcher)({
+ url: core.url.join(
+ (await core.Supplier.get(this._options.baseUrl)) ??
+ (await core.Supplier.get(this._options.environment)),
+ "internal/sessions/get-or-create-by-external-id",
+ ),
+ method: "POST",
+ headers: _headers,
+ contentType: "application/json",
+ queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+ requestType: "json",
+ body: mergeAdditionalBodyParameters(
+ serializers.internal.GetOrCreateSessionByExternalIdRequest.jsonOrThrow(request, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ omitUndefined: true,
+ }),
+ requestOptions?.additionalBodyParameters,
+ ),
+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+ abortSignal: requestOptions?.abortSignal,
+ fetchFn: this._options?.fetch,
+ logging: this._options.logging,
+ });
+ if (_response.ok) {
+ return {
+ data: serializers.GetSessionResponse.parseOrThrow(_response.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ rawResponse: _response.rawResponse,
+ };
+ }
+
+ if (_response.error.reason === "status-code") {
+ switch (_response.error.statusCode) {
+ case 400:
+ throw new TrueForge.BadRequestError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 403:
+ throw new TrueForge.ForbiddenError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 404:
+ throw new TrueForge.NotFoundError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 422:
+ throw new TrueForge.UnprocessableEntityError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
+ }
+
+ return handleNonStatusCodeError(
+ _response.error,
+ _response.rawResponse,
+ "POST",
+ "/internal/sessions/get-or-create-by-external-id",
+ );
+ }
+}
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/index.ts
new file mode 100644
index 000000000..195f9aa8a
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/index.ts
@@ -0,0 +1 @@
+export * from "./requests/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/requests/GetOrCreateSessionByExternalIdRequest.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/requests/GetOrCreateSessionByExternalIdRequest.ts
new file mode 100644
index 000000000..2d0744219
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/requests/GetOrCreateSessionByExternalIdRequest.ts
@@ -0,0 +1,18 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../../../../../index.js";
+
+/**
+ * @example
+ * {
+ * agent: {
+ * name: "name"
+ * },
+ * externalId: "external_id"
+ * }
+ */
+export interface GetOrCreateSessionByExternalIdRequest {
+ agent: TrueForge.CreateSessionAgent;
+ /** Caller-supplied id unique within the tenant. */
+ externalId: string;
+}
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/requests/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/requests/index.ts
new file mode 100644
index 000000000..321e08b7b
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/client/requests/index.ts
@@ -0,0 +1 @@
+export type { GetOrCreateSessionByExternalIdRequest } from "./GetOrCreateSessionByExternalIdRequest.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/exports.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/exports.ts
new file mode 100644
index 000000000..989fb8a75
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/exports.ts
@@ -0,0 +1,4 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export { SessionsClient } from "./client/Client.js";
+export * from "./client/index.js";
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/index.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/index.ts
new file mode 100644
index 000000000..914b8c3c7
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/sessions/index.ts
@@ -0,0 +1 @@
+export * from "./client/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/index.ts b/packages/trueforge-sdk/src/serialization/resources/index.ts
index 38709c072..c0588507f 100644
--- a/packages/trueforge-sdk/src/serialization/resources/index.ts
+++ b/packages/trueforge-sdk/src/serialization/resources/index.ts
@@ -1,5 +1,6 @@
export * from "./agents/client/requests/index.js";
export * as agents from "./agents/index.js";
+export * as internal from "./internal/index.js";
export * from "./schedules/client/requests/index.js";
export * as schedules from "./schedules/index.js";
export * from "./sessions/client/requests/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/index.ts b/packages/trueforge-sdk/src/serialization/resources/internal/index.ts
new file mode 100644
index 000000000..e445af0d8
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/index.ts
@@ -0,0 +1 @@
+export * from "./resources/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/index.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/index.ts
new file mode 100644
index 000000000..e34ab841f
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/index.ts
@@ -0,0 +1,2 @@
+export * from "./sessions/client/requests/index.js";
+export * as sessions from "./sessions/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/client/index.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/client/index.ts
new file mode 100644
index 000000000..195f9aa8a
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/client/index.ts
@@ -0,0 +1 @@
+export * from "./requests/index.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/client/requests/GetOrCreateSessionByExternalIdRequest.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/client/requests/GetOrCreateSessionByExternalIdRequest.ts
new file mode 100644
index 000000000..a5eb94c45
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/client/requests/GetOrCreateSessionByExternalIdRequest.ts
@@ -0,0 +1,21 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../../../../../../api/index.js";
+import * as core from "../../../../../../../core/index.js";
+import type * as serializers from "../../../../../../index.js";
+import { CreateSessionAgent } from "../../../../../../types/CreateSessionAgent.js";
+
+export const GetOrCreateSessionByExternalIdRequest: core.serialization.Schema<
+ serializers.internal.GetOrCreateSessionByExternalIdRequest.Raw,
+ TrueForge.internal.GetOrCreateSessionByExternalIdRequest
+> = core.serialization.object({
+ agent: CreateSessionAgent,
+ externalId: core.serialization.property("external_id", core.serialization.string()),
+});
+
+export declare namespace GetOrCreateSessionByExternalIdRequest {
+ export interface Raw {
+ agent: CreateSessionAgent.Raw;
+ external_id: string;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/client/requests/index.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/client/requests/index.ts
new file mode 100644
index 000000000..431f6018e
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/client/requests/index.ts
@@ -0,0 +1 @@
+export { GetOrCreateSessionByExternalIdRequest } from "./GetOrCreateSessionByExternalIdRequest.js";
diff --git a/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/index.ts b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/index.ts
new file mode 100644
index 000000000..914b8c3c7
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/resources/internal/resources/sessions/index.ts
@@ -0,0 +1 @@
+export * from "./client/index.js";
diff --git a/packages/trueforge-sdk/tests/wire/internal/sessions.test.ts b/packages/trueforge-sdk/tests/wire/internal/sessions.test.ts
new file mode 100644
index 000000000..67b728e1f
--- /dev/null
+++ b/packages/trueforge-sdk/tests/wire/internal/sessions.test.ts
@@ -0,0 +1,156 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import * as TrueForgeTypes from "../../../src/api/index";
+import { TrueForge } from "../../../src/Client";
+import { mockServerPool } from "../../mock-server/MockServerPool";
+
+describe("SessionsClient", () => {
+ test("get_or_create_by_external_id (1)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { agent: { name: "name" }, external_id: "external_id" };
+ const rawResponseBody = {
+ data: {
+ agent: { spec: { model: { name: "name" } }, type: "inline" },
+ created_at: "created_at",
+ created_by: "created_by",
+ id: "id",
+ title: "title",
+ updated_at: "updated_at",
+ },
+ };
+
+ server
+ .mockEndpoint()
+ .post("/internal/sessions/get-or-create-by-external-id")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(200)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ const response = await client.internal.sessions.getOrCreateByExternalId({
+ agent: {
+ name: "name",
+ },
+ externalId: "external_id",
+ });
+ expect(response).toEqual({
+ data: {
+ agent: {
+ spec: {
+ model: {
+ name: "name",
+ },
+ },
+ type: "inline",
+ },
+ createdAt: "created_at",
+ createdBy: "created_by",
+ id: "id",
+ title: "title",
+ updatedAt: "updated_at",
+ },
+ });
+ });
+
+ test("get_or_create_by_external_id (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { agent: { name: "xy" }, external_id: "x" };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/internal/sessions/get-or-create-by-external-id")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(400)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.internal.sessions.getOrCreateByExternalId({
+ agent: {
+ name: "xy",
+ },
+ externalId: "x",
+ });
+ }).rejects.toThrow(TrueForgeTypes.BadRequestError);
+ });
+
+ test("get_or_create_by_external_id (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { agent: { name: "xy" }, external_id: "x" };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/internal/sessions/get-or-create-by-external-id")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(403)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.internal.sessions.getOrCreateByExternalId({
+ agent: {
+ name: "xy",
+ },
+ externalId: "x",
+ });
+ }).rejects.toThrow(TrueForgeTypes.ForbiddenError);
+ });
+
+ test("get_or_create_by_external_id (4)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { agent: { name: "xy" }, external_id: "x" };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/internal/sessions/get-or-create-by-external-id")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(404)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.internal.sessions.getOrCreateByExternalId({
+ agent: {
+ name: "xy",
+ },
+ externalId: "x",
+ });
+ }).rejects.toThrow(TrueForgeTypes.NotFoundError);
+ });
+
+ test("get_or_create_by_external_id (5)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
+ const rawRequestBody = { agent: { name: "xy" }, external_id: "x" };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/internal/sessions/get-or-create-by-external-id")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(422)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.internal.sessions.getOrCreateByExternalId({
+ agent: {
+ name: "xy",
+ },
+ externalId: "x",
+ });
+ }).rejects.toThrow(TrueForgeTypes.UnprocessableEntityError);
+ });
+});
diff --git a/packages/trueforge/src/apis/sessions.ts b/packages/trueforge/src/apis/sessions.ts
index eb92d3657..dd5b76227 100644
--- a/packages/trueforge/src/apis/sessions.ts
+++ b/packages/trueforge/src/apis/sessions.ts
@@ -1,5 +1,5 @@
/**
- * DB-backed sessions API (mounted at /api/v1/sessions).
+ * DB-backed sessions APIs (mounted at /api/v1/sessions and /internal/sessions).
*/
import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
import type { ISessionStore, SessionHandle, SessionRecord, Sessions } from '@truefoundry/trueforge-core/agent-session';
@@ -18,7 +18,6 @@ import {
type RequestReplyRouter,
} from '@truefoundry/trueforge-core/request-reply';
import type { RedisClientType } from 'redis';
-import { ulid } from 'ulid';
import type { Logger } from 'winston';
import { z } from 'zod';
import type { ResolveUserContext } from '../auth/identity';
@@ -32,6 +31,7 @@ import {
cancelSessionRoute,
createSessionRoute,
deleteSessionRoute,
+ getOrCreateSessionByExternalIdRoute,
getSessionRoute,
listSessionEventsRoute,
listSessionsRoute,
@@ -41,6 +41,7 @@ import type { ActiveTurnRegistry } from '../runtime/activeTurns';
import { executorFromTurnId } from '../runtime/peeringIds';
import { validateAgentSpec } from '../runtime/sessionResources';
import { isSessionAgentNameRef, type Session } from '../schemas/session';
+import { newId } from '../utils/id';
/** The server is single-tenant; every record lives under one fixed tenant scope. */
export const TENANT_ID = 'default';
@@ -217,11 +218,79 @@ function checkSessionAccess({ userRef, createdBy }: { userRef: string; createdBy
return userRef === createdBy;
}
+type InternalSessionsRouterDeps = Pick<
+ SessionsRouterDeps,
+ | 'sessions'
+ | 'modelProviderStore'
+ | 'mcpServerStore'
+ | 'skillStore'
+ | 'agentStore'
+ | 'sandboxProviderStore'
+ | 'resolveUserContext'
+>;
+
+function createGetOrCreateSessionByExternalIdHandler(
+ deps: InternalSessionsRouterDeps,
+): RouteHandler<typeof getOrCreateSessionByExternalIdRoute> {
+ return async c => {
+ const body = c.req.valid('json');
+ const user = deps.resolveUserContext(c);
+
+ const existing = await deps.sessions.getByExternalId({
+ tenant_id: TENANT_ID,
+ external_id: body.external_id,
+ });
+ if (existing !== undefined) {
+ if (!checkSessionAccess({ userRef: user.userRef, createdBy: existing.record.created_by })) {
+ return c.json({ error: { message: FORBIDDEN_SESSION_ACCESS } }, 403);
+ }
+ return c.json({ data: toWireSession(existing.record) }, 200);
+ }
+
+ let agent: SessionRecord['agent'];
+ if (isSessionAgentNameRef(body.agent)) {
+ const named = await deps.agentStore.getAgent({ tenant_id: TENANT_ID, name: body.agent.name });
+ if (named === undefined) {
+ return c.json({ error: { message: `Agent not found: ${body.agent.name}` } }, 404);
+ }
+ agent = { type: 'reference', id: named.id, name: named.name };
+ } else {
+ await validateAgentSpec({
+ spec: body.agent.spec,
+ tenant_id: TENANT_ID,
+ modelProviderStore: deps.modelProviderStore,
+ mcpServerStore: deps.mcpServerStore,
+ skillStore: deps.skillStore,
+ sandboxProviderStore: deps.sandboxProviderStore,
+ });
+ agent = { type: 'inline', spec: body.agent.spec };
+ }
+
+ const { session, created } = await deps.sessions.getOrCreateByExternalId({
+ tenant_id: TENANT_ID,
+ external_id: body.external_id,
+ created_by: user.userRef,
+ agent,
+ });
+ if (!created && !checkSessionAccess({ userRef: user.userRef, createdBy: session.record.created_by })) {
+ return c.json({ error: { message: FORBIDDEN_SESSION_ACCESS } }, 403);
+ }
+ return c.json({ data: toWireSession(session.record) }, created ? 201 : 200);
+ };
+}
+
+/** Internal session operations (mounted at /internal/sessions). */
+export function createInternalSessionsRouter(deps: InternalSessionsRouterDeps) {
+ const router = new OpenAPIHono();
+ router.openapi(getOrCreateSessionByExternalIdRoute, createGetOrCreateSessionByExternalIdHandler(deps));
+ return router;
+}
+
/** DB-backed sessions (mounted at /api/v1/sessions). */
export function createSessionsRouter(deps: SessionsRouterDeps) {
const createSessionHandler: RouteHandler<typeof createSessionRoute> = async c => {
const body = c.req.valid('json');
- const sessionId = ulid().toLowerCase();
+ const sessionId = newId();
if (isSessionAgentNameRef(body.agent)) {
const agent = await deps.agentStore.getAgent({ tenant_id: TENANT_ID, name: body.agent.name });
@@ -234,6 +303,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
session_id: sessionId,
created_by: user.userRef,
agent: { type: 'reference', id: agent.id, name: agent.name },
+ external_id: null,
});
return c.json({ data: toWireSession(session.record) }, 201);
}
@@ -252,6 +322,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
session_id: sessionId,
created_by: user.userRef,
agent: { type: 'inline', spec: body.agent.spec },
+ external_id: null,
});
return c.json({ data: toWireSession(session.record) }, 201);
};
diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.ts
index bb71b9779..3557888d1 100644
--- a/packages/trueforge/src/app.ts
+++ b/packages/trueforge/src/app.ts
@@ -18,7 +18,7 @@ import { createMcpOAuthRouter } from './apis/mcpOAuth';
import { createMcpServersRouter } from './apis/mcpServers';
import { createModelsRouter } from './apis/models';
import { createSchedulesRouter } from './apis/schedules';
-import { createSessionsRouter } from './apis/sessions';
+import { createInternalSessionsRouter, createSessionsRouter } from './apis/sessions';
import { createSettingsRouter } from './apis/settings';
import { createAvailableSkillsRouter } from './apis/skills';
import { createTurnsRouter } from './apis/turns';
@@ -277,6 +277,20 @@ export function createServerApp<TTransaction>(deps: ServerDeps<TTransaction>) {
}),
),
);
+ app.route(
+ '/internal/sessions',
+ withAuth(
+ createInternalSessionsRouter({
+ sessions: deps.sessions,
+ modelProviderStore: deps.modelProviderStore,
+ mcpServerStore: deps.mcpServerStore,
+ skillStore: deps.skillStore,
+ agentStore: deps.agentStore,
+ sandboxProviderStore: deps.sandboxProviderStore,
+ resolveUserContext,
+ }),
+ ),
+ );
app.route(
'/api/v1/sessions',
withAuth(
diff --git a/packages/trueforge/src/db/migrateSqlite.ts b/packages/trueforge/src/db/migrateSqlite.ts
index 2ddc04dc6..a17a1a8ab 100644
--- a/packages/trueforge/src/db/migrateSqlite.ts
+++ b/packages/trueforge/src/db/migrateSqlite.ts
@@ -29,9 +29,7 @@ export async function migrateSqliteToLatest(db: Kysely<Database>): Promise<void>
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') {
+ if (it.status === 'Error') {
console.error(`failed to execute migration "${it.migrationName}"`);
}
});
diff --git a/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts b/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts
index 5630e4342..c72c6e904 100644
--- a/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts
+++ b/packages/trueforge/src/db/postgres/agent-store/PostgresAgentStore.ts
@@ -1,5 +1,5 @@
import type { Kysely, Selectable, Transaction } from 'kysely';
-import { ulid } from 'ulid';
+import { newId } from '../../../utils/id';
import {
AgentNameConflictError,
parseStoredAgentSpec,
@@ -56,7 +56,7 @@ export class PostgresAgentStore implements IAgentStore<Transaction<Database>> {
const row = await db
.insertInto('agent')
.values({
- id: ulid().toLowerCase(),
+ id: newId(),
tenant_id: input.tenant_id,
name: input.name,
manifest: json(input.manifest),
diff --git a/packages/trueforge/src/db/postgres/client.ts b/packages/trueforge/src/db/postgres/client.ts
index 6a31fbc4c..84bdfaa1f 100644
--- a/packages/trueforge/src/db/postgres/client.ts
+++ b/packages/trueforge/src/db/postgres/client.ts
@@ -72,3 +72,11 @@ export function isPgErrorCode(err: unknown, code: string): boolean {
export function isUniqueViolation(err: unknown): boolean {
return isPgErrorCode(err, '23505');
}
+
+/** Match a Postgres unique/PK violation to a named constraint or index. */
+export function isPgConstraint(err: unknown, name: string): boolean {
+ if (typeof err !== 'object' || err === null || !('constraint' in err)) {
+ return false;
+ }
+ return err.constraint === name;
+}
diff --git a/packages/trueforge/src/db/postgres/mcp-server-store/PostgresMcpServerStore.ts b/packages/trueforge/src/db/postgres/mcp-server-store/PostgresMcpServerStore.ts
index 553c73ab2..148531257 100644
--- a/packages/trueforge/src/db/postgres/mcp-server-store/PostgresMcpServerStore.ts
+++ b/packages/trueforge/src/db/postgres/mcp-server-store/PostgresMcpServerStore.ts
@@ -1,6 +1,6 @@
import type { Kysely, Selectable, Transaction } from 'kysely';
-import { ulid } from 'ulid';
import type { OAuthClientRecord } from '../../../mcp/auth/types';
+import { newId } from '../../../utils/id';
import {
fromStoredOAuthClientRecord,
McpServerNameConflictError,
@@ -78,7 +78,7 @@ export class PostgresMcpServerStore implements IMcpServerStore<Transaction<Datab
const row = await db
.insertInto('mcp_server')
.values({
- id: ulid(),
+ id: newId(),
tenant_id: input.tenant_id,
name: input.name,
manifest: json(input.manifest),
@@ -103,7 +103,7 @@ export class PostgresMcpServerStore implements IMcpServerStore<Transaction<Datab
const row = await db
.insertInto('mcp_server')
.values({
- id: ulid(),
+ id: newId(),
tenant_id: input.tenant_id,
name: input.name,
manifest: json(input.manifest),
diff --git a/packages/trueforge/src/db/postgres/migrations/20260831_000001_session_external_id.ts b/packages/trueforge/src/db/postgres/migrations/20260831_000001_session_external_id.ts
new file mode 100644
index 000000000..2ea3cbf57
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20260831_000001_session_external_id.ts
@@ -0,0 +1,21 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Optional session `external_id`, unique within a tenant when set.
+ * NULLs are excluded so sessions 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('session').addColumn('external_id', 'text').execute();
+ await sql`
+ CREATE UNIQUE INDEX ${sql.raw('session_external_id_uq')}
+ ON session (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('session_external_id_uq')}`.execute(db);
+ await db.schema.alterTable('session').dropColumn('external_id').execute();
+}
diff --git a/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts b/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts
index 6557db7f5..f81bb8672 100644
--- a/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts
+++ b/packages/trueforge/src/db/postgres/schedule-store/PostgresScheduleStore.ts
@@ -1,6 +1,6 @@
import type { Kysely, Selectable, Transaction } from 'kysely';
-import { ulid } from 'ulid';
import { nextTriggerAfter } from '../../../runtime/cron';
+import { newId } from '../../../utils/id';
import {
cronRunName,
parseStoredScheduleManifest,
@@ -132,7 +132,7 @@ export class PostgresScheduleStore implements IScheduleStore<Transaction<Databas
row = await db
.insertInto('schedule')
.values({
- id: ulid().toLowerCase(),
+ id: newId(),
tenant_id: input.tenant_id,
agent_name: input.agent_name,
name: input.name,
@@ -270,7 +270,7 @@ export class PostgresScheduleStore implements IScheduleStore<Transaction<Databas
const row = await db
.insertInto('schedule_run')
.values({
- id: ulid().toLowerCase(),
+ id: newId(),
tenant_id: input.tenant_id,
schedule_id: input.schedule_id,
name: input.name,
diff --git a/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts b/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts
index 486594e9b..4d4ec73ed 100644
--- a/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts
+++ b/packages/trueforge/src/db/postgres/session-store/PostgresSessionStore.ts
@@ -10,6 +10,7 @@ import type {
CreateTurnInput,
DeleteSessionInput,
FreezeAndGetTurnInput,
+ GetSessionByExternalIdInput,
GetSessionInput,
GetTurnInput,
ISessionStore,
@@ -41,6 +42,7 @@ import {
import {
createSession as createSessionQuery,
deleteSession as deleteSessionQuery,
+ getSessionByExternalId as getSessionByExternalIdQuery,
getSession as getSessionQuery,
listSessions as listSessionsQuery,
updateSession as updateSessionQuery,
@@ -102,6 +104,10 @@ export class PostgresSessionStore implements ISessionStore<SessionCustom, TurnCu
return getSessionQuery(this.db, input);
}
+ getSessionByExternalId(input: GetSessionByExternalIdInput): Promise<SessionRecord<SessionCustom> | undefined> {
+ return getSessionByExternalIdQuery(this.db, input);
+ }
+
updateSession(input: UpdateSessionInput<SessionCustom>): Promise<void> {
return updateSessionQuery(this.db, input);
}
diff --git a/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts b/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts
index 6be30a46e..876e0d219 100644
--- a/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts
+++ b/packages/trueforge/src/db/postgres/session-store/queries/sessions.ts
@@ -3,6 +3,7 @@ import type { SessionRecord } from '@truefoundry/trueforge-core/agent-session/mo
import type {
CreateSessionInput,
DeleteSessionInput,
+ GetSessionByExternalIdInput,
GetSessionInput,
ListSessionsInput,
UpdateSessionInput,
@@ -13,24 +14,16 @@ import {
} from '@truefoundry/trueforge-core/agent-session/store/SessionListPageToken';
import {
SessionAlreadyExistsError,
+ SessionExternalIdConflictError,
SessionNotFoundError,
SessionStoreInvariantError,
} from '@truefoundry/trueforge-core/agent-session/store/SessionStoreErrors';
import { sql, type Kysely } from 'kysely';
import { sessionAgentFromColumns, sessionAgentToColumns } from '../../../sessionAgentColumns';
+import { isPgConstraint, isUniqueViolation } from '../../client';
import { json } from '../../sqlExpressions';
import type { Database } from '../../types';
-function isPgUniqueViolation(error: unknown): boolean {
- if (typeof error !== 'object' || error === null) {
- return false;
- }
- if (!('code' in error)) {
- return false;
- }
- return error.code === '23505';
-}
-
type SessionCustom = Record<string, never>;
type ProtoSessionRecord = SessionRecord<SessionCustom>;
@@ -57,6 +50,7 @@ function mapRowToSessionRecord(row: {
agent_spec: AgentSpec | null;
title: string | null;
last_turn_id: string | null;
+ external_id: string | null;
custom: Record<string, unknown> | null;
metrics: SessionMetrics;
created_at: Date;
@@ -75,6 +69,7 @@ function mapRowToSessionRecord(row: {
}),
title: row.title,
last_turn_id: row.last_turn_id,
+ external_id: row.external_id,
custom: parseSessionCustom(row.custom),
metrics: row.metrics,
created_at: row.created_at,
@@ -99,6 +94,7 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionIn
agent_spec: columns.agent_spec !== null ? json(columns.agent_spec) : null,
title: null,
custom: input.custom !== null ? json(input.custom) : null,
+ external_id: input.external_id,
metrics: json({
total_cost_in_usd: 0,
total_duration_ms: 0,
@@ -110,7 +106,10 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionIn
})
.execute();
} catch (error) {
- if (isPgUniqueViolation(error)) {
+ if (isUniqueViolation(error)) {
+ if (isPgConstraint(error, 'session_external_id_uq') && input.external_id) {
+ throw new SessionExternalIdConflictError(input.external_id, { cause: error });
+ }
throw new SessionAlreadyExistsError(input.session_id, { cause: error });
}
throw error;
@@ -143,6 +142,24 @@ export async function getSession(
return mapRowToSessionRecord(row);
}
+export async function getSessionByExternalId(
+ db: Kysely<Database>,
+ input: GetSessionByExternalIdInput,
+): Promise<ProtoSessionRecord | undefined> {
+ const row = await db
+ .selectFrom('session')
+ .selectAll()
+ .where('tenant_id', '=', input.tenant_id)
+ .where('external_id', '=', input.external_id)
+ .executeTakeFirst();
+
+ if (row === undefined) {
+ return undefined;
+ }
+
+ return mapRowToSessionRecord(row);
+}
+
export async function updateSession(db: Kysely<Database>, input: UpdateSessionInput<SessionCustom>): Promise<void> {
const agent = input.agent;
const title = input.title;
diff --git a/packages/trueforge/src/db/postgres/types.ts b/packages/trueforge/src/db/postgres/types.ts
index 07b88b216..3a84fea23 100644
--- a/packages/trueforge/src/db/postgres/types.ts
+++ b/packages/trueforge/src/db/postgres/types.ts
@@ -79,6 +79,11 @@ export interface SessionTable {
* tiny fixed-width column keeps the bump a cheap HOT update
*/
last_turn_id: string | null;
+ /**
+ * Optional unique key within `tenant_id` (`session_external_id_uq`,
+ * partial WHERE external_id IS NOT NULL).
+ */
+ external_id: string | null;
/** top: caller-owned opaque extension; never mixed with store state */
custom: JSONColumnType<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>> | null;
metrics: JSONColumnType<SessionMetrics, SessionMetrics, SessionMetrics>;
diff --git a/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts b/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts
index f4653c6e4..46143af88 100644
--- a/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts
+++ b/packages/trueforge/src/db/sqlite/agent-store/SqliteAgentStore.ts
@@ -1,6 +1,6 @@
import type { AgentSpec } from '@truefoundry/trueforge-core/agent-session';
import type { ExpressionBuilder, Kysely, Transaction } from 'kysely';
-import { ulid } from 'ulid';
+import { newId } from '../../../utils/id';
import {
AgentNameConflictError,
parseStoredAgentSpec,
@@ -75,7 +75,7 @@ export class SqliteAgentStore implements IAgentStore<Transaction<Database>> {
const row = await db
.insertInto('agent')
.values({
- id: ulid().toLowerCase(),
+ id: newId(),
tenant_id: input.tenant_id,
name: input.name,
manifest: jsonbBind(input.manifest),
diff --git a/packages/trueforge/src/db/sqlite/mcp-server-store/SqliteMcpServerStore.ts b/packages/trueforge/src/db/sqlite/mcp-server-store/SqliteMcpServerStore.ts
index 2ef987ad8..a4e13824c 100644
--- a/packages/trueforge/src/db/sqlite/mcp-server-store/SqliteMcpServerStore.ts
+++ b/packages/trueforge/src/db/sqlite/mcp-server-store/SqliteMcpServerStore.ts
@@ -1,7 +1,7 @@
import type { ExpressionBuilder, Kysely, Transaction } from 'kysely';
-import { ulid } from 'ulid';
import type { OAuthClientRecord } from '../../../mcp/auth/types';
import type { McpServerManifest } from '../../../schemas/mcpServer';
+import { newId } from '../../../utils/id';
import {
fromStoredOAuthClientRecord,
McpServerNameConflictError,
@@ -83,7 +83,7 @@ export class SqliteMcpServerStore implements IMcpServerStore<Transaction<Databas
return await db
.insertInto('mcp_server')
.values({
- id: ulid(),
+ id: newId(),
tenant_id: input.tenant_id,
name: input.name,
manifest: jsonbBind(input.manifest),
@@ -108,7 +108,7 @@ export class SqliteMcpServerStore implements IMcpServerStore<Transaction<Databas
return await db
.insertInto('mcp_server')
.values({
- id: ulid(),
+ id: newId(),
tenant_id: input.tenant_id,
name: input.name,
manifest: jsonbBind(input.manifest),
diff --git a/packages/trueforge/src/db/sqlite/migrations/20260831_000001_session_external_id.ts b/packages/trueforge/src/db/sqlite/migrations/20260831_000001_session_external_id.ts
new file mode 100644
index 000000000..9eb5bed47
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20260831_000001_session_external_id.ts
@@ -0,0 +1,23 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * Optional session `external_id`, unique within a tenant when set.
+ * NULLs are excluded so sessions 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 session ADD COLUMN external_id TEXT`.execute(trx);
+ await sql`
+ CREATE UNIQUE INDEX ${sql.raw('session_external_id_uq')}
+ ON session (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('session_external_id_uq')}`.execute(trx);
+ await sql`ALTER TABLE session DROP COLUMN external_id`.execute(trx);
+ });
+}
diff --git a/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts b/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts
index d99585239..22b8c6de5 100644
--- a/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts
+++ b/packages/trueforge/src/db/sqlite/schedule-store/SqliteScheduleStore.ts
@@ -1,7 +1,7 @@
import type { ExpressionBuilder, Kysely, Transaction } from 'kysely';
-import { ulid } from 'ulid';
import { nextTriggerAfter } from '../../../runtime/cron';
import type { ScheduleManifest, ScheduleRunStatus, ScheduleStatus } from '../../../schemas/schedule';
+import { newId } from '../../../utils/id';
import {
cronRunName,
parseStoredScheduleManifest,
@@ -129,7 +129,7 @@ export class SqliteScheduleStore implements IScheduleStore<Transaction<Database>
row = await db
.insertInto('schedule')
.values({
- id: ulid().toLowerCase(),
+ id: newId(),
tenant_id: input.tenant_id,
agent_name: input.agent_name,
name: input.name,
@@ -309,7 +309,7 @@ export class SqliteScheduleStore implements IScheduleStore<Transaction<Database>
const row = await db
.insertInto('schedule_run')
.values({
- id: ulid().toLowerCase(),
+ id: newId(),
tenant_id: input.tenant_id,
schedule_id: input.schedule_id,
name: input.name,
diff --git a/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts b/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts
index 3166ee5a9..171e6e651 100644
--- a/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts
+++ b/packages/trueforge/src/db/sqlite/session-store/SqliteSessionStore.ts
@@ -10,6 +10,7 @@ import type {
CreateTurnInput,
DeleteSessionInput,
FreezeAndGetTurnInput,
+ GetSessionByExternalIdInput,
GetSessionInput,
GetTurnInput,
ISessionStore,
@@ -41,6 +42,7 @@ import {
import {
createSession as createSessionQuery,
deleteSession as deleteSessionQuery,
+ getSessionByExternalId as getSessionByExternalIdQuery,
getSession as getSessionQuery,
listSessions as listSessionsQuery,
updateSession as updateSessionQuery,
@@ -100,6 +102,10 @@ export class SqliteSessionStore implements ISessionStore<SessionCustom, TurnCust
return getSessionQuery(this.db, input);
}
+ getSessionByExternalId(input: GetSessionByExternalIdInput): Promise<SessionRecord<SessionCustom> | undefined> {
+ return getSessionByExternalIdQuery(this.db, input);
+ }
+
updateSession(input: UpdateSessionInput<SessionCustom>): Promise<void> {
return updateSessionQuery(this.db, input);
}
diff --git a/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts b/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts
index e651364a3..784d292a9 100644
--- a/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts
+++ b/packages/trueforge/src/db/sqlite/session-store/queries/sessions.ts
@@ -3,6 +3,7 @@ import type { SessionRecord } from '@truefoundry/trueforge-core/agent-session/mo
import type {
CreateSessionInput,
DeleteSessionInput,
+ GetSessionByExternalIdInput,
GetSessionInput,
ListSessionsInput,
UpdateSessionInput,
@@ -13,6 +14,7 @@ import {
} from '@truefoundry/trueforge-core/agent-session/store/SessionListPageToken';
import {
SessionAlreadyExistsError,
+ SessionExternalIdConflictError,
SessionNotFoundError,
SessionStoreInvariantError,
} from '@truefoundry/trueforge-core/agent-session/store/SessionStoreErrors';
@@ -48,6 +50,7 @@ function mapRowToSessionRecord(row: {
agent_spec: AgentSpec | null;
title: string | null;
last_turn_id: string | null;
+ external_id: string | null;
custom: Record<string, unknown> | null;
metrics: SessionMetrics;
created_at: string;
@@ -66,6 +69,7 @@ function mapRowToSessionRecord(row: {
}),
title: row.title,
last_turn_id: row.last_turn_id,
+ external_id: row.external_id,
custom: parseSessionCustom(row.custom),
metrics: row.metrics,
created_at: new Date(row.created_at),
@@ -84,6 +88,7 @@ function sessionSelectColumns() {
jsonText<AgentSpec | null>(sql.ref('agent_spec')).as('agent_spec'),
'title' as const,
'last_turn_id' as const,
+ 'external_id' as const,
jsonText<Record<string, unknown> | null>(sql.ref('custom')).as('custom'),
jsonText<SessionMetrics>(sql.ref('metrics')).as('metrics'),
'created_at' as const,
@@ -108,6 +113,7 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionIn
agent_spec: columns.agent_spec !== null ? jsonbBind(columns.agent_spec) : null,
title: null,
custom: input.custom !== null ? jsonbBind(input.custom) : null,
+ external_id: input.external_id,
metrics: jsonbBind({
total_cost_in_usd: 0,
total_duration_ms: 0,
@@ -120,6 +126,19 @@ export async function createSession(db: Kysely<Database>, input: CreateSessionIn
.execute();
} catch (error) {
if (isUniqueViolation(error)) {
+ // Which index fired is resolved by lookup, not by parsing the driver
+ // message: SQLite describes a partial unique index by column list or by
+ // index name depending on version. The failed INSERT already rolled back,
+ // so a hit here is the pre-existing row that owns this external id.
+ if (input.external_id !== null) {
+ const owner = await getSessionByExternalId(db, {
+ tenant_id: input.tenant_id,
+ external_id: input.external_id,
+ });
+ if (owner !== undefined) {
+ throw new SessionExternalIdConflictError(input.external_id, { cause: error });
+ }
+ }
throw new SessionAlreadyExistsError(input.session_id, { cause: error });
}
throw error;
@@ -152,6 +171,24 @@ export async function getSession(
return mapRowToSessionRecord(row);
}
+export async function getSessionByExternalId(
+ db: Kysely<Database>,
+ input: GetSessionByExternalIdInput,
+): Promise<ProtoSessionRecord | undefined> {
+ const row = await db
+ .selectFrom('session')
+ .select(sessionSelectColumns)
+ .where('tenant_id', '=', input.tenant_id)
+ .where('external_id', '=', input.external_id)
+ .executeTakeFirst();
+
+ if (row === undefined) {
+ return undefined;
+ }
+
+ return mapRowToSessionRecord(row);
+}
+
export async function updateSession(db: Kysely<Database>, input: UpdateSessionInput<SessionCustom>): Promise<void> {
const agent = input.agent;
const title = input.title;
diff --git a/packages/trueforge/src/db/sqlite/types.ts b/packages/trueforge/src/db/sqlite/types.ts
index 2a8a17278..c6869a4ce 100644
--- a/packages/trueforge/src/db/sqlite/types.ts
+++ b/packages/trueforge/src/db/sqlite/types.ts
@@ -68,6 +68,8 @@ export interface SessionTable {
agent_spec: JsonbColumn<AgentSpec> | null;
title: string | null;
last_turn_id: string | null;
+ /** Optional unique key within `tenant_id` when set. */
+ external_id: string | null;
custom: JsonbColumn<Record<string, unknown>> | null;
metrics: JsonbColumn<SessionMetrics>;
created_at: string;
diff --git a/packages/trueforge/src/routes/openapiTags.ts b/packages/trueforge/src/routes/openapiTags.ts
index 64709378c..1082e870b 100644
--- a/packages/trueforge/src/routes/openapiTags.ts
+++ b/packages/trueforge/src/routes/openapiTags.ts
@@ -1,5 +1,6 @@
/** Mintlify API Reference groups — the only OpenAPI `tags` values. */
export enum OpenApiTag {
+ INTERNAL = 'Internal',
AUTH = 'Auth',
CAPABILITIES = 'Capabilities',
MODELS = 'Models',
@@ -13,6 +14,7 @@ export enum OpenApiTag {
/** Document-level tag order for `/api/v1/docs` and Mintlify. */
export const OPENAPI_DOCUMENT_TAGS: { name: OpenApiTag }[] = [
+ { name: OpenApiTag.INTERNAL },
{ name: OpenApiTag.AUTH },
{ name: OpenApiTag.CAPABILITIES },
{ name: OpenApiTag.MODELS },
diff --git a/packages/trueforge/src/routes/sessionRoutes.ts b/packages/trueforge/src/routes/sessionRoutes.ts
index 441657579..ba9e320ae 100644
--- a/packages/trueforge/src/routes/sessionRoutes.ts
+++ b/packages/trueforge/src/routes/sessionRoutes.ts
@@ -1,6 +1,7 @@
/**
* Session route definitions.
- * DB-backed routes mount at /api/v1/sessions.
+ * Public DB-backed routes mount at /api/v1/sessions; internal operations mount
+ * at /internal/sessions.
* Handlers are registered in apis/sessions.ts.
*/
import { createRoute, z } from '@hono/zod-openapi';
@@ -8,6 +9,7 @@ import { RequestErrorResponseSchema } from '../schemas/errors';
import { ListSessionEventsRequestQuerySchema, ListSessionEventsResponseSchema } from '../schemas/events';
import {
CreateSessionRequestSchema,
+ GetOrCreateSessionByExternalIdRequestSchema,
GetSessionResponseSchema,
ListSessionsRequestQuerySchema,
ListSessionsResponseSchema,
@@ -57,6 +59,53 @@ export const createSessionRoute = createRoute({
},
});
+/**
+ * Idempotent get-or-create by tenant-scoped `external_id`. Internal callers
+ * (schedule dispatch) use this so a retried run reuses the same session.
+ */
+export const getOrCreateSessionByExternalIdRoute = createRoute({
+ method: 'post',
+ path: '/get-or-create-by-external-id',
+ tags: [OpenApiTag.INTERNAL],
+ summary: 'Get or create a session by external id',
+ description: 'Idempotent get-or-create: returns the existing session for this `external_id`, or creates one',
+ 'x-fern-sdk-group-name': ['internal', 'sessions'],
+ 'x-fern-sdk-method-name': 'get_or_create_by_external_id',
+ request: {
+ body: {
+ content: { 'application/json': { schema: GetOrCreateSessionByExternalIdRequestSchema } },
+ required: true,
+ },
+ },
+ responses: {
+ 200: {
+ content: { 'application/json': { schema: GetSessionResponseSchema } },
+ description: 'Session already existed for this external id.',
+ },
+ 201: {
+ content: { 'application/json': { schema: GetSessionResponseSchema } },
+ description: 'Session created.',
+ },
+ 400: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Invalid request body.',
+ },
+ 403: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Caller is not the session creator.',
+ },
+ 404: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'Named agent not found.',
+ },
+ 422: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description:
+ 'The agent spec is valid but references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox).',
+ },
+ },
+});
+
export const getSessionRoute = createRoute({
method: 'get',
path: '/{session_id}',
diff --git a/packages/trueforge/src/runtime/peeringIds.ts b/packages/trueforge/src/runtime/peeringIds.ts
index d384a5e8e..b32b24850 100644
--- a/packages/trueforge/src/runtime/peeringIds.ts
+++ b/packages/trueforge/src/runtime/peeringIds.ts
@@ -1,5 +1,5 @@
import { HTTPException } from 'hono/http-exception';
-import { ulid } from 'ulid';
+import { newId } from '../utils/id';
/**
* Mints a turn id owned by `executorId`. The server calls this at turn
@@ -7,7 +7,7 @@ import { ulid } from 'ulid';
* is the matching decoder on the routing path.
*/
export function mintPeeredTurnId(executorId: string): string {
- return `${ulid().toLowerCase()}.${executorId}`;
+ return `${newId()}.${executorId}`;
}
/** Decodes the owning executor; throws 400 for an id outside the grammar. */
diff --git a/packages/trueforge/src/sandbox/local/core/CodeModeUdsTransport.ts b/packages/trueforge/src/sandbox/local/core/CodeModeUdsTransport.ts
index 376c73031..5a3543182 100644
--- a/packages/trueforge/src/sandbox/local/core/CodeModeUdsTransport.ts
+++ b/packages/trueforge/src/sandbox/local/core/CodeModeUdsTransport.ts
@@ -20,7 +20,7 @@ import { chmodSync, existsSync, realpathSync, statSync } from 'node:fs';
import { chmod, mkdir, rm, symlink, unlink, writeFile } from 'node:fs/promises';
import { createServer, type Server, type Socket } from 'node:net';
import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { ulid } from 'ulid';
+import { newId } from '../../../utils/id';
import { sandboxScripts } from '../sandboxScripts.gen.js';
import { encodeJsonMessage, JsonMessageReader, MAX_MESSAGE_BYTES } from './frame.js';
@@ -94,7 +94,7 @@ export function assertCodeModeSocketParentPath(path: string): string {
*/
export async function probeCodeModeUnixSocket(parentPath: string): Promise<{ sockPath: string }> {
const realParent = assertCodeModeSocketParentPath(parentPath);
- const sockPath = join(realParent, ulid().toLowerCase());
+ const sockPath = join(realParent, newId());
await unlink(sockPath).catch(() => undefined);
const server = createServer();
try {
@@ -194,7 +194,7 @@ export class CodeModeUdsTransport implements CodeModeTransport {
// Re-check: caller owns the parent dir and may have removed it after construct.
assertCodeModeSocketParentPath(this.codeModeSocketParentPath);
- const sockPath = join(this.codeModeSocketParentPath, ulid().toLowerCase());
+ const sockPath = join(this.codeModeSocketParentPath, newId());
await unlink(sockPath).catch(() => undefined);
const server = createServer({ allowHalfOpen: true });
try {
diff --git a/packages/trueforge/src/sandbox/local/provider/LocalSandboxProvider.ts b/packages/trueforge/src/sandbox/local/provider/LocalSandboxProvider.ts
index a82c6e635..43c7c7d4a 100644
--- a/packages/trueforge/src/sandbox/local/provider/LocalSandboxProvider.ts
+++ b/packages/trueforge/src/sandbox/local/provider/LocalSandboxProvider.ts
@@ -23,8 +23,8 @@ import { mkdir, mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
import { promisify } from 'node:util';
-import { ulid } from 'ulid';
import type { Logger } from 'winston';
+import { newId } from '../../../utils/id';
import {
assertCodeModeSocketParentPath,
CodeModeUdsTransport,
@@ -589,7 +589,7 @@ export class LocalSandboxProvider implements SandboxProvider {
async createSandbox(): Promise<{ sandboxId: string }> {
await this.ensureSrt();
- const sandboxId = await createSandbox(join(this.sandboxRootPathParent, ulid().toLowerCase()));
+ const sandboxId = await createSandbox(join(this.sandboxRootPathParent, newId()));
this.logger.info('LocalSandboxProvider created sandbox', {
sandboxId,
shell: this.support.shell,
diff --git a/packages/trueforge/src/schemas/session.ts b/packages/trueforge/src/schemas/session.ts
index 0583bdf7f..ab4943fca 100644
--- a/packages/trueforge/src/schemas/session.ts
+++ b/packages/trueforge/src/schemas/session.ts
@@ -33,6 +33,14 @@ export const CreateSessionRequestSchema = z
.strict()
.openapi('CreateSessionRequest');
+export const GetOrCreateSessionByExternalIdRequestSchema = z
+ .object({
+ external_id: z.string().min(1).max(128).describe('Caller-supplied id unique within the tenant.'),
+ agent: CreateSessionAgentSchema,
+ })
+ .strict()
+ .openapi('GetOrCreateSessionByExternalIdRequest');
+
/** Only inline sessions may be updated; named (reference) sessions reject agent updates. */
export const UpdateSessionRequestSchema = z
.object({
diff --git a/packages/trueforge/src/utils/id.ts b/packages/trueforge/src/utils/id.ts
new file mode 100644
index 000000000..d9106e684
--- /dev/null
+++ b/packages/trueforge/src/utils/id.ts
@@ -0,0 +1,6 @@
+import { ulid } from 'ulid';
+
+/** Application-generated lowercase ULID for entity / resource ids. */
+export function newId(): string {
+ return ulid().toLowerCase();
+}
diff --git a/packages/trueforge/tests/db/postgres/testDatabase.ts b/packages/trueforge/tests/db/postgres/testDatabase.ts
index 4ea4b41f7..5e080d455 100644
--- a/packages/trueforge/tests/db/postgres/testDatabase.ts
+++ b/packages/trueforge/tests/db/postgres/testDatabase.ts
@@ -4,11 +4,11 @@
*/
import type { Kysely } from 'kysely';
import { Pool } from 'pg';
-import { ulid } from 'ulid';
import { migrateTo, migrateToLatest } from '../../../src/db/migratePostgres';
import { createDb } from '../../../src/db/postgres/client';
import type { Database } from '../../../src/db/postgres/types';
+import { newId } from '../../../src/utils/id';
const ADMIN_URL_ENV = 'PG_STORE_TESTS_ADMIN_URL';
@@ -59,7 +59,7 @@ export async function createPostgresTestDatabase(
return undefined;
}
- const databaseName = `test_${ulid().toLowerCase()}`;
+ const databaseName = `test_${newId()}`;
assertSafeDatabaseName(databaseName);
const adminPool = new Pool({ connectionString: adminUrl });
diff --git a/packages/trueforge/tests/sandbox/local/smoke.test.ts b/packages/trueforge/tests/sandbox/local/smoke.test.ts
index 9c01b5907..07be25cee 100644
--- a/packages/trueforge/tests/sandbox/local/smoke.test.ts
+++ b/packages/trueforge/tests/sandbox/local/smoke.test.ts
@@ -13,7 +13,6 @@ import { createServer } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
-import { ulid } from 'ulid';
import { createLogger } from 'winston';
import {
CodeModeUdsTransport,
@@ -29,6 +28,7 @@ import {
runSupervisorSession,
} from '../../../src/sandbox/local/core/hostRun.js';
import { LocalSandboxProvider } from '../../../src/sandbox/local/provider/LocalSandboxProvider.js';
+import { newId } from '../../../src/utils/id.js';
const ROOT = join(dirname(fileURLToPath(import.meta.url)), '../../..');
const SANDBOXES = join(ROOT, 'sandboxes');
@@ -81,8 +81,8 @@ async function smokeCodeModeSocketParentAllow(params: {
platform: 'darwin' | 'linux';
}): Promise<void> {
const parent = await realpath(params.codeModeSocketParentPath);
- const allowedSock = join(parent, ulid().toLowerCase());
- const leftoverSock = join('/tmp', `tfy-srt-leak-${ulid().toLowerCase().slice(0, 10)}`);
+ const allowedSock = join(parent, newId());
+ const leftoverSock = join('/tmp', `tfy-srt-leak-${newId().slice(0, 10)}`);
await unlink(allowedSock).catch(() => undefined);
await unlink(leftoverSock).catch(() => undefined);
@@ -630,7 +630,7 @@ function assertPeerSecretPresent(label: string, sample: string): void {
* Identity comes from the kernel, not from client-supplied fields.
*/
async function smokeUdsPeerCredentials(): Promise<void> {
- const sockPath = join(tmpdir(), `cm-pc-${ulid().toLowerCase().slice(0, 10)}`);
+ const sockPath = join(tmpdir(), `cm-pc-${newId().slice(0, 10)}`);
await unlink(sockPath).catch(() => undefined);
const script = [
diff --git a/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts b/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts
index 832d68ca5..039442ffe 100644
--- a/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts
+++ b/packages/trueforge/tests/unit/apis/deletedSessionCrud.test.ts
@@ -81,6 +81,7 @@ describe('public CRUD after session deletion', () => {
}),
},
custom: null,
+ external_id: null,
});
expect((await app.request('/s1', { method: 'DELETE' })).status).toBe(204);
diff --git a/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts b/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts
index fd80dee47..0d879082c 100644
--- a/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts
+++ b/packages/trueforge/tests/unit/apis/sandboxFileDownload.test.ts
@@ -113,6 +113,7 @@ describe('GET /{session_id}/turns/{turn_id}/download-sandbox-file', () => {
session_id: 'no-turn',
created_by: LOCAL_USER_CONTEXT.userRef,
agent: { type: 'inline', spec: agentSpec() },
+ external_id: null,
});
const response = await app.request(downloadUrl({ sessionId: session.session_id, path: '/workspace/report.pdf' }));
diff --git a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
index dd40b0027..4ceab3b02 100644
--- a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
+++ b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
@@ -3,7 +3,12 @@ import { AgentSpecSchema, Sessions } from '@truefoundry/trueforge-core/agent-ses
import { RequestReplyRouter } from '@truefoundry/trueforge-core/request-reply';
import { createClient } from 'redis';
import { createLogger } from 'winston';
-import { createSessionsRouter, TENANT_ID } from '../../../src/apis/sessions';
+import {
+ createInternalSessionsRouter,
+ createSessionsRouter,
+ TENANT_ID,
+ type SessionsRouterDeps,
+} from '../../../src/apis/sessions';
import { LOCAL_USER_CONTEXT } from '../../../src/auth/identity';
import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';
import { SqliteAgentStore } from '../../../src/db/sqlite/agent-store/SqliteAgentStore';
@@ -62,23 +67,22 @@ describe('sessions HTTP agent binding', () => {
});
app = new OpenAPIHono();
- app.route(
- '/',
- createSessionsRouter({
- sessions,
- sessionStore,
- activeTurns: new ActiveTurnRegistry(),
- modelProviderStore,
- mcpServerStore,
- skillStore,
- agentStore,
- sandboxProviderStore,
- redis: createClient(),
- requestReplyRouter: new RequestReplyRouter(),
- resolveUserContext: () => LOCAL_USER_CONTEXT,
- logger: createLogger({ silent: true }),
- }),
- );
+ const deps: SessionsRouterDeps = {
+ sessions,
+ sessionStore,
+ activeTurns: new ActiveTurnRegistry(),
+ modelProviderStore,
+ mcpServerStore,
+ skillStore,
+ agentStore,
+ sandboxProviderStore,
+ redis: createClient(),
+ requestReplyRouter: new RequestReplyRouter(),
+ resolveUserContext: () => LOCAL_USER_CONTEXT,
+ logger: createLogger({ silent: true }),
+ };
+ app.route('/', createSessionsRouter(deps));
+ app.route('/internal/sessions', createInternalSessionsRouter(deps));
});
it('creates a session from an inline AgentSpec', async () => {
@@ -134,6 +138,7 @@ describe('sessions HTTP agent binding', () => {
created_by: 'someone-else',
agent: { type: 'inline', spec: inlineSpec },
custom: null,
+ external_id: null,
});
const created = await app.request('/', jsonInit('POST', { agent: { spec: inlineSpec } }));
@@ -210,6 +215,55 @@ describe('sessions HTTP agent binding', () => {
expect(patchedJson.data.agent.spec.instructions).toBe('updated');
});
+ it('POST get-or-create-by-external-id is idempotent and 403s for another creator', async () => {
+ const publicPath = await app.request(
+ '/get-or-create-by-external-id',
+ jsonInit('POST', { external_id: 'run-abc', agent: { spec: inlineSpec } }),
+ );
+ expect(publicPath.status).toBe(404);
+
+ const created = await app.request(
+ '/internal/sessions/get-or-create-by-external-id',
+ jsonInit('POST', { external_id: 'run-abc', agent: { spec: inlineSpec } }),
+ );
+ expect(created.status).toBe(201);
+ const createdJson = (await created.json()) as {
+ data: { id: string; agent: { type: 'inline'; spec: { instructions?: string } } };
+ };
+ expect(createdJson.data.agent.spec.instructions).toBe('inline');
+
+ const again = await app.request(
+ '/internal/sessions/get-or-create-by-external-id',
+ jsonInit('POST', {
+ external_id: 'run-abc',
+ agent: { spec: { ...inlineSpec, instructions: 'ignored-on-get' } },
+ }),
+ );
+ expect(again.status).toBe(200);
+ const againJson = (await again.json()) as {
+ data: { id: string; agent: { type: 'inline'; spec: { instructions?: string } } };
+ };
+ expect(againJson.data.id).toBe(createdJson.data.id);
+ expect(againJson.data.agent.spec.instructions).toBe('inline');
+
+ await sessionStore.createSession({
+ tenant_id: TENANT_ID,
+ session_id: 'someone-elses-session',
+ created_by: 'someone-else',
+ agent: { type: 'inline', spec: inlineSpec },
+ custom: null,
+ external_id: 'run-theirs',
+ });
+ const forbidden = await app.request(
+ '/internal/sessions/get-or-create-by-external-id',
+ jsonInit('POST', { external_id: 'run-theirs', agent: { spec: inlineSpec } }),
+ );
+ expect(forbidden.status).toBe(403);
+ expect(await forbidden.json()).toEqual({
+ error: { message: 'Only the session creator can access this session' },
+ });
+ });
+
it('rejects create bodies that mix name and AgentSpec fields', async () => {
const both = await app.request('/', jsonInit('POST', { agent: { name: 'named-agent', ...inlineSpec } }));
expect(both.status).toBe(400);
diff --git a/packages/trueforge/tests/unit/apis/turns.test.ts b/packages/trueforge/tests/unit/apis/turns.test.ts
index a15ab0bda..0a00896ab 100644
--- a/packages/trueforge/tests/unit/apis/turns.test.ts
+++ b/packages/trueforge/tests/unit/apis/turns.test.ts
@@ -41,6 +41,7 @@ describe('turns', () => {
}),
},
custom: null,
+ external_id: null,
});
const app = new OpenAPIHono();