Skip to content
Merged
Show file tree
Hide file tree
Changes from 11 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/schedule-session-turn.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@truefoundry/trueforge": patch
---

Dispatch schedule runs through the session/turn API: get-or-create a session keyed by run id, then create a turn only when that session has none.
7 changes: 7 additions & 0 deletions .changeset/session-external-id.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
"@truefoundry/trueforge": patch
"@truefoundry/trueforge-core": patch
"@truefoundry/trueforge-sdk": patch
---

Add tenant-unique optional session `external_id` with an idempotent `POST /sessions/get-or-create-by-external-id` endpoint and SDK method.
104 changes: 104 additions & 0 deletions .github/fern/openapi/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -1278,6 +1278,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": {
Expand Down Expand Up @@ -6000,6 +6019,91 @@
"x-fern-sdk-method-name": "create"
}
},
"/api/v1/sessions/get-or-create-by-external-id": {
"post": {
"description": "Idempotent get-or-create: returns the existing session for this tenant-scoped `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": [
"Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
],
"x-fern-sdk-method-name": "get_or_create_by_external_id"
}
},
"/api/v1/sessions/{session_id}": {
"delete": {
"description": "Delete a session and all related turns, events, and internal state. Only the session creator (`created_by`) may delete it. Idempotent if already gone.",
Expand Down
104 changes: 104 additions & 0 deletions docs/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -1278,6 +1278,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": {
Expand Down Expand Up @@ -6000,6 +6019,91 @@
"x-fern-sdk-method-name": "create"
}
},
"/api/v1/sessions/get-or-create-by-external-id": {
"post": {
"description": "Idempotent get-or-create: returns the existing session for this tenant-scoped `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": [
"Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
],
"x-fern-sdk-method-name": "get_or_create_by_external_id"
}
},
"/api/v1/sessions/{session_id}": {
"delete": {
"description": "Delete a session and all related turns, events, and internal state. Only the session creator (`created_by`) may delete it. Idempotent if already gone.",
Expand Down
24 changes: 23 additions & 1 deletion packages/trueforge-core/src/agent-session/Sessions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,12 @@
* the resolver on {@link SessionHandle.createTurn}.
*/
import { SessionHandle } from './SessionHandle';
import type { CreateSessionInput, GetSessionInput, ISessionStore } from './store/ISessionStore';
import type {
CreateSessionInput,
GetSessionByExternalIdInput,
GetSessionInput,
ISessionStore,
} from './store/ISessionStore';

export type SessionsCreateInput<TSessionCustom extends object> = Omit<CreateSessionInput<TSessionCustom>, 'custom'> & {
custom?: TSessionCustom | undefined;
Expand Down Expand Up @@ -54,4 +59,21 @@ 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,
});
}
}
2 changes: 2 additions & 0 deletions packages/trueforge-core/src/agent-session/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ export type {
CreateTurnInput,
DeleteSessionInput,
FreezeAndGetTurnInput,
GetSessionByExternalIdInput,
GetSessionInput,
GetTurnInput,
ISessionStore,
Expand All @@ -78,6 +79,7 @@ export {
InvalidPageTokenError,
PreviousTurnRunningError,
SessionAlreadyExistsError,
SessionExternalIdConflictError,
SessionNotFoundError,
SessionStoreConflictError,
SessionStoreInvariantError,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
13 changes: 12 additions & 1 deletion packages/trueforge-core/src/agent-session/store/ISessionStore.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
};
Expand All @@ -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;
Expand Down Expand Up @@ -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).
Expand Down
Loading