Skip to content

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

feat: Allow renaming sessions (#780)

harshil-20964a91f4748082
diff --git a/.changeset/20260917043123-regenerate-sdk-from-openapi.md b/.changeset/20260917043123-regenerate-sdk-from-openapi.md
new file mode 100644
index 000000000..efd8ff00f
--- /dev/null
+++ b/.changeset/20260917043123-regenerate-sdk-from-openapi.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Regenerate SDK from updated OpenAPI spec.
diff --git a/.changeset/session-rename-api.md b/.changeset/session-rename-api.md
new file mode 100644
index 000000000..a71c250a2
--- /dev/null
+++ b/.changeset/session-rename-api.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Allow renaming sessions via `PATCH /api/v1/sessions/{session_id}` with an optional `title` (trimmed, 1–50 chars).
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 91b9285c1..1ae21eca9 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -5489,6 +5489,12 @@
},
"metadata": {
"$ref": "#/components/schemas/SessionMetadata"
+ },
+ "title": {
+ "description": "Human-readable session title.",
+ "maxLength": 50,
+ "minLength": 1,
+ "type": "string"
}
},
"type": "object"
@@ -8232,7 +8238,7 @@
"x-fern-sdk-method-name": "get"
},
"patch": {
- "description": "Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.",
+ "description": "Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.",
"parameters": [
{
"description": "Session identifier.",
diff --git a/docs/openapi.json b/docs/openapi.json
index 91b9285c1..1ae21eca9 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -5489,6 +5489,12 @@
},
"metadata": {
"$ref": "#/components/schemas/SessionMetadata"
+ },
+ "title": {
+ "description": "Human-readable session title.",
+ "maxLength": 50,
+ "minLength": 1,
+ "type": "string"
}
},
"type": "object"
@@ -8232,7 +8238,7 @@
"x-fern-sdk-method-name": "get"
},
"patch": {
- "description": "Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.",
+ "description": "Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.",
"parameters": [
{
"description": "Session identifier.",
diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.md
index 7ce8fb760..0936210ae 100644
--- a/packages/trueforge-sdk/reference.md
+++ b/packages/trueforge-sdk/reference.md
@@ -1678,7 +1678,7 @@ await client.sessions.delete("session_id");
<dl>
<dd>
-Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
+Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
</dd>
</dl>
</dd>
diff --git a/packages/trueforge-sdk/src/api/resources/sessions/client/Client.ts b/packages/trueforge-sdk/src/api/resources/sessions/client/Client.ts
index acd4b93ab..422c38ef2 100644
--- a/packages/trueforge-sdk/src/api/resources/sessions/client/Client.ts
+++ b/packages/trueforge-sdk/src/api/resources/sessions/client/Client.ts
@@ -453,7 +453,7 @@ export class SessionsClient {
}
/**
- * Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
+ * Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
*
* @param {string} session_id - Session identifier.
* @param {TrueForge.UpdateSessionRequest} request
diff --git a/packages/trueforge-sdk/src/api/resources/sessions/client/requests/UpdateSessionRequest.ts b/packages/trueforge-sdk/src/api/resources/sessions/client/requests/UpdateSessionRequest.ts
index 07a555dbd..247dc69bc 100644
--- a/packages/trueforge-sdk/src/api/resources/sessions/client/requests/UpdateSessionRequest.ts
+++ b/packages/trueforge-sdk/src/api/resources/sessions/client/requests/UpdateSessionRequest.ts
@@ -9,4 +9,6 @@ import type * as TrueForge from "../../../../index.js";
export interface UpdateSessionRequest {
agent?: TrueForge.SessionAgentSpecBody;
metadata?: TrueForge.SessionMetadata;
+ /** Human-readable session title. */
+ title?: string;
}
diff --git a/packages/trueforge-sdk/src/serialization/resources/sessions/client/requests/UpdateSessionRequest.ts b/packages/trueforge-sdk/src/serialization/resources/sessions/client/requests/UpdateSessionRequest.ts
index baefd7753..9bd3e18ad 100644
--- a/packages/trueforge-sdk/src/serialization/resources/sessions/client/requests/UpdateSessionRequest.ts
+++ b/packages/trueforge-sdk/src/serialization/resources/sessions/client/requests/UpdateSessionRequest.ts
@@ -12,11 +12,13 @@ export const UpdateSessionRequest: core.serialization.Schema<
> = core.serialization.object({
agent: SessionAgentSpecBody.optional(),
metadata: SessionMetadata.optional(),
+ title: core.serialization.string().optional(),
});
export declare namespace UpdateSessionRequest {
export interface Raw {
agent?: SessionAgentSpecBody.Raw | null;
metadata?: SessionMetadata.Raw | null;
+ title?: string | null;
}
}
diff --git a/packages/trueforge/src/apis/sessions.ts b/packages/trueforge/src/apis/sessions.ts
index 5e275a30f..8d4e680aa 100644
--- a/packages/trueforge/src/apis/sessions.ts
+++ b/packages/trueforge/src/apis/sessions.ts
@@ -460,7 +460,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {
tenant_id: requestContext.tenant_id,
session_id: sessionId,
agent: body.agent === undefined ? undefined : { type: 'inline', spec: body.agent.spec },
- title: undefined,
+ title: body.title,
metadata: body.metadata,
});
} catch (error) {
diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts
index 42480a5a5..be5bef3d3 100644
--- a/packages/trueforge/src/apis/turns.ts
+++ b/packages/trueforge/src/apis/turns.ts
@@ -62,6 +62,7 @@ import {
X_TFY_METADATA,
} from '../runtime/sessionResources';
import { checkSnapshotStatus } from '../sandbox/providerUtils';
+import { MAX_SESSION_TITLE_LENGTH } from '../schemas/session';
import { canReadAgentBoundResource } from './agentAccess';
export function toWireTurn(record: TurnRecordWithoutSnapshot): Turn {
@@ -271,8 +272,6 @@ function createTurnResolver(deps: {
});
}
-const MAX_SESSION_TITLE_LENGTH = 50;
-
/**
* Derives a session title from the first user message of the first turn. Returns the
* trimmed text (capped at {@link MAX_SESSION_TITLE_LENGTH}) or `undefined` when no usable
diff --git a/packages/trueforge/src/routes/sessionRoutes.ts b/packages/trueforge/src/routes/sessionRoutes.ts
index 39afff87a..331b0e8d1 100644
--- a/packages/trueforge/src/routes/sessionRoutes.ts
+++ b/packages/trueforge/src/routes/sessionRoutes.ts
@@ -163,7 +163,7 @@ export const updateSessionRoute = createRoute({
tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Update a session',
description:
- 'Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.',
+ 'Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.',
'x-fern-sdk-group-name': ['sessions'],
'x-fern-sdk-method-name': 'update',
request: {
diff --git a/packages/trueforge/src/schemas/session.ts b/packages/trueforge/src/schemas/session.ts
index cf3cd3265..2dc7b4530 100644
--- a/packages/trueforge/src/schemas/session.ts
+++ b/packages/trueforge/src/schemas/session.ts
@@ -52,10 +52,21 @@ export const GetOrCreateSessionByExternalIdRequestSchema = z
.strict()
.openapi('GetOrCreateSessionByExternalIdRequest');
-/** Only inline sessions may be updated; named (reference) sessions reject agent updates. */
+/** Matches auto-derived titles from the first user message on turn 1. */
+export const MAX_SESSION_TITLE_LENGTH = 50;
+
+export const SessionTitleSchema = z
+ .string()
+ .trim()
+ .min(1)
+ .max(MAX_SESSION_TITLE_LENGTH)
+ .describe('Human-readable session title.');
+
+/** Only inline sessions may replace `agent`; named (reference) sessions reject agent updates. Title/metadata apply to both. */
export const UpdateSessionRequestSchema = z
.object({
agent: SessionAgentSpecBodySchema.optional(),
+ title: SessionTitleSchema.optional(),
metadata: SessionMetadataSchema.optional(),
})
.strict()
diff --git a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
index 2ed5ed6fa..43e94f0b4 100644
--- a/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
+++ b/packages/trueforge/tests/unit/apis/sessionHttp.test.ts
@@ -500,6 +500,66 @@ describe('sessions HTTP agent binding', () => {
expect(omittedJson.data.metadata).toEqual({});
});
+ it('PATCH title renames a session and omission preserves it', async () => {
+ const created = await app.request('/', jsonInit('POST', { agent: { spec: inlineSpec } }));
+ expect(created.status).toBe(201);
+ const { data } = (await created.json()) as { data: { id: string; title: string | null } };
+ expect(data.title).toBeNull();
+
+ const renamed = await app.request(`/${data.id}`, jsonInit('PATCH', { title: ' Acme onboarding ' }));
+ expect(renamed.status).toBe(200);
+ const renamedJson = (await renamed.json()) as { data: { title: string | null } };
+ expect(renamedJson.data.title).toBe('Acme onboarding');
+
+ const omit = await app.request(`/${data.id}`, jsonInit('PATCH', {}));
+ expect(omit.status).toBe(200);
+ const omitJson = (await omit.json()) as { data: { title: string | null } };
+ expect(omitJson.data.title).toBe('Acme onboarding');
+
+ const got = await app.request(`/${data.id}`);
+ expect(got.status).toBe(200);
+ expect(((await got.json()) as { data: { title: string | null } }).data.title).toBe('Acme onboarding');
+ });
+
+ it('PATCH title works on named (reference) sessions', async () => {
+ const agent = await agentStore.createAgent({
+ tenant_id: 'default',
+ created_by_subject: {
+ subject_id: STANDALONE_REQUEST_CONTEXT.subject.id,
+ subject_type: STANDALONE_REQUEST_CONTEXT.subject.type,
+ subject_display_name: STANDALONE_REQUEST_CONTEXT.subject.display_name,
+ },
+ name: 'rename-agent',
+ description: 'Test agent.',
+ manifest: inlineSpec,
+ external_id: null,
+ });
+
+ const created = await app.request('/', jsonInit('POST', { agent: { name: agent.name } }));
+ expect(created.status).toBe(201);
+ const { data } = (await created.json()) as { data: { id: string } };
+
+ const renamed = await app.request(`/${data.id}`, jsonInit('PATCH', { title: 'Customer A support' }));
+ expect(renamed.status).toBe(200);
+ const renamedJson = (await renamed.json()) as {
+ data: { title: string | null; agent: { type: string } };
+ };
+ expect(renamedJson.data.title).toBe('Customer A support');
+ expect(renamedJson.data.agent.type).toBe('reference');
+ });
+
+ it('rejects blank or over-limit session titles on PATCH', async () => {
+ const created = await app.request('/', jsonInit('POST', { agent: { spec: inlineSpec } }));
+ expect(created.status).toBe(201);
+ const { data } = (await created.json()) as { data: { id: string } };
+
+ const blank = await app.request(`/${data.id}`, jsonInit('PATCH', { title: ' ' }));
+ expect(blank.status).toBe(400);
+
+ const tooLong = await app.request(`/${data.id}`, jsonInit('PATCH', { title: 'x'.repeat(51) }));
+ expect(tooLong.status).toBe(400);
+ });
+
it('rejects invalid session metadata on create', async () => {
const tooLongKey = await app.request(
'/',
diff --git a/python/trueforge_sdk/.fern/metadata.json b/python/trueforge_sdk/.fern/metadata.json
index 952f21eff..9b44c3fd9 100644
--- a/python/trueforge_sdk/.fern/metadata.json
+++ b/python/trueforge_sdk/.fern/metadata.json
@@ -21,7 +21,7 @@
},
"pyproject_python_version": ">=3.10"
},
- "originGitCommit": "32a0e5caf6bb938fd95c2325789d6b58977dabe4",
+ "originGitCommit": "cd4e388af4a643e6e9b4c7df40ab488fb2059b1e",
"originGitCommitIsDirty": true,
"invokedBy": "ci",
"requestedVersion": "0.2.0-rc.8",
diff --git a/python/trueforge_sdk/reference.md b/python/trueforge_sdk/reference.md
index 6fb8dd5dd..aa8c83132 100644
--- a/python/trueforge_sdk/reference.md
+++ b/python/trueforge_sdk/reference.md
@@ -2015,7 +2015,7 @@ client.sessions.delete(
<dl>
<dd>
-Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
+Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
</dd>
</dl>
</dd>
@@ -2079,6 +2079,14 @@ client.sessions.update(
<dl>
<dd>
+**title:** `typing.Optional[str]` — Human-readable session title.
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
</dd>
diff --git a/python/trueforge_sdk/src/trueforge_sdk/sessions/client.py b/python/trueforge_sdk/src/trueforge_sdk/sessions/client.py
index de65b8365..ce744a779 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/sessions/client.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/sessions/client.py
@@ -245,10 +245,11 @@ class SessionsClient:
session_id: str,
agent: typing.Optional[SessionAgentSpecBody] = OMIT,
metadata: typing.Optional[SessionMetadata] = OMIT,
+ title: typing.Optional[str] = OMIT,
request_options: typing.Optional[RequestOptions] = None,
) -> GetSessionResponse:
"""
- Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
+ Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
Parameters
----------
@@ -259,6 +260,9 @@ class SessionsClient:
metadata : typing.Optional[SessionMetadata]
+ title : typing.Optional[str]
+ Human-readable session title.
+
request_options : typing.Optional[RequestOptions]
Request-specific configuration.
@@ -280,7 +284,7 @@ class SessionsClient:
)
"""
_response = self._raw_client.update(
- session_id=session_id, agent=agent, metadata=metadata, request_options=request_options
+ session_id=session_id, agent=agent, metadata=metadata, title=title, request_options=request_options
)
return _response.data
@@ -986,10 +990,11 @@ class AsyncSessionsClient:
session_id: str,
agent: typing.Optional[SessionAgentSpecBody] = OMIT,
metadata: typing.Optional[SessionMetadata] = OMIT,
+ title: typing.Optional[str] = OMIT,
request_options: typing.Optional[RequestOptions] = None,
) -> GetSessionResponse:
"""
- Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
+ Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
Parameters
----------
@@ -1000,6 +1005,9 @@ class AsyncSessionsClient:
metadata : typing.Optional[SessionMetadata]
+ title : typing.Optional[str]
+ Human-readable session title.
+
request_options : typing.Optional[RequestOptions]
Request-specific configuration.
@@ -1029,7 +1037,7 @@ class AsyncSessionsClient:
asyncio.run(main())
"""
_response = await self._raw_client.update(
- session_id=session_id, agent=agent, metadata=metadata, request_options=request_options
+ session_id=session_id, agent=agent, metadata=metadata, title=title, request_options=request_options
)
return _response.data
diff --git a/python/trueforge_sdk/src/trueforge_sdk/sessions/raw_client.py b/python/trueforge_sdk/src/trueforge_sdk/sessions/raw_client.py
index 8cf90eb06..1a8065d01 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/sessions/raw_client.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/sessions/raw_client.py
@@ -389,10 +389,11 @@ class RawSessionsClient:
session_id: str,
agent: typing.Optional[SessionAgentSpecBody] = OMIT,
metadata: typing.Optional[SessionMetadata] = OMIT,
+ title: typing.Optional[str] = OMIT,
request_options: typing.Optional[RequestOptions] = None,
) -> HttpResponse[GetSessionResponse]:
"""
- Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
+ Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
Parameters
----------
@@ -403,6 +404,9 @@ class RawSessionsClient:
metadata : typing.Optional[SessionMetadata]
+ title : typing.Optional[str]
+ Human-readable session title.
+
request_options : typing.Optional[RequestOptions]
Request-specific configuration.
@@ -419,6 +423,7 @@ class RawSessionsClient:
object_=agent, annotation=SessionAgentSpecBody, direction="write"
),
"metadata": metadata,
+ "title": title,
},
headers={
"content-type": "application/json",
@@ -1909,10 +1914,11 @@ class AsyncRawSessionsClient:
session_id: str,
agent: typing.Optional[SessionAgentSpecBody] = OMIT,
metadata: typing.Optional[SessionMetadata] = OMIT,
+ title: typing.Optional[str] = OMIT,
request_options: typing.Optional[RequestOptions] = None,
) -> AsyncHttpResponse[GetSessionResponse]:
"""
- Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
+ Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
Parameters
----------
@@ -1923,6 +1929,9 @@ class AsyncRawSessionsClient:
metadata : typing.Optional[SessionMetadata]
+ title : typing.Optional[str]
+ Human-readable session title.
+
request_options : typing.Optional[RequestOptions]
Request-specific configuration.
@@ -1939,6 +1948,7 @@ class AsyncRawSessionsClient:
object_=agent, annotation=SessionAgentSpecBody, direction="write"
),
"metadata": metadata,
+ "title": title,
},
headers={
"content-type": "application/json",