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.mdnew file mode 100644index 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 './SessionLiimport {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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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/ISessionStoimport { 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.tsindex 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.jsonindex 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.mdindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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; createdByreturn 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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<Databconst 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<Databconst 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.tsnew file mode 100644index 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.tsindex 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<Databasrow = 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<Databasconst 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.tsindex 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, TurnCureturn 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.tsindex 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/moimport 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: CreateSessionInagent_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.tsindex 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.tsindex 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.tsindex 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<Databasreturn 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<Databasreturn 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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, TurnCustreturn 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.tsindex 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/moimport 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: CreateSessionInagent_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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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-sesimport { 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.tsindex 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();