The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Collapse API Reference groups and hide callbacks apis (#333)
Bhavesh Patel5e03c3d54102
diff --git a/.changeset/openapi-docs-groups.md b/.changeset/openapi-docs-groups.mdnew file mode 100644index 000000000..55fcfeca4--- /dev/null+++ b/.changeset/openapi-docs-groups.md@@ -0,0 +1,5 @@+---+'@truefoundry/trueforge': patch+---++Collapse Mintlify API Reference groups to Auth, Capabilities, Models, MCP Servers, Skills, Sandboxes, Agents, and Agent Sessions.diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.jsonindex 0c344c41b..5986edcf8 100644--- a/.github/fern/openapi/openapi.json+++ b/.github/fern/openapi/openapi.json@@ -4516,6 +4516,7 @@"tags": ["Auth"],+ "x-excluded": true,"x-fern-ignore": true}},@@ -4543,6 +4544,7 @@"tags": ["Auth"],+ "x-excluded": true,"x-fern-ignore": true}},@@ -4558,6 +4560,7 @@"tags": ["Auth"],+ "x-excluded": true,"x-fern-sdk-group-name": ["auth"],@@ -4661,7 +4664,7 @@},"summary": "Get the MCP catalog","tags": [- "Catalog"+ "MCP Servers"],"x-fern-sdk-group-name": ["catalogs",@@ -4697,7 +4700,7 @@},"summary": "Get the model catalog","tags": [- "Catalog"+ "Models"],"x-fern-sdk-group-name": ["catalogs",@@ -4733,7 +4736,7 @@},"summary": "Get the sandbox provider catalog","tags": [- "Catalog"+ "Sandboxes"],"x-fern-sdk-group-name": ["catalogs",@@ -4769,7 +4772,7 @@},"summary": "Get the skill catalog","tags": [- "Catalog"+ "Skills"],"x-fern-sdk-group-name": ["catalogs",@@ -4909,8 +4912,9 @@},"summary": "OAuth callback for MCP authorization","tags": [- "MCP OAuth"+ "MCP Servers"],+ "x-excluded": true,"x-fern-ignore": true}},@@ -5266,7 +5270,7 @@},"summary": "List sessions","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-pagination": {"cursor": "$request.page_token",@@ -5334,7 +5338,7 @@},"summary": "Create a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5376,7 +5380,7 @@},"summary": "Delete a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5433,7 +5437,7 @@},"summary": "Get a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5520,7 +5524,7 @@},"summary": "Update a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5599,7 +5603,7 @@},"summary": "Cancel a running turn in a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5701,7 +5705,7 @@},"summary": "List session events","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-pagination": {"cursor": "$request.page_token",@@ -5798,7 +5802,7 @@},"summary": "List turns in a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-pagination": {"cursor": "$request.page_token",@@ -5915,7 +5919,7 @@},"summary": "Create and execute a turn in a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5996,7 +6000,7 @@},"summary": "Get a turn","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -6128,7 +6132,7 @@},"summary": "Download a file from the turn sandbox","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -6240,7 +6244,7 @@},"summary": "List turn events","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-pagination": {"cursor": "$request.page_token",@@ -6349,7 +6353,7 @@},"summary": "Subscribe to a running turn","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -6611,7 +6615,7 @@},"summary": "List configured model providers","tags": [- "Model Providers"+ "Models"],"x-fern-sdk-group-name": ["settings",@@ -6665,7 +6669,7 @@},"summary": "Create a model provider","tags": [- "Model Providers"+ "Models"],"x-fern-sdk-group-name": ["settings",@@ -6709,7 +6713,7 @@},"summary": "Create or replace a model provider","tags": [- "Model Providers"+ "Models"],"x-fern-sdk-group-name": ["settings",@@ -6745,7 +6749,7 @@},"summary": "Get the configured sandbox provider","tags": [- "Sandbox Providers"+ "Sandboxes"],"x-fern-sdk-group-name": ["settings",@@ -6799,7 +6803,7 @@},"summary": "Create or replace the sandbox provider","tags": [- "Sandbox Providers"+ "Sandboxes"],"x-fern-sdk-group-name": ["settings",@@ -6993,5 +6997,31 @@"BearerAuth": []}],+ "tags": [+ {+ "name": "Auth"+ },+ {+ "name": "Capabilities"+ },+ {+ "name": "Models"+ },+ {+ "name": "MCP Servers"+ },+ {+ "name": "Skills"+ },+ {+ "name": "Sandboxes"+ },+ {+ "name": "Agents"+ },+ {+ "name": "Agent Sessions"+ }+ ],"webhooks": {}}diff --git a/docs/openapi.json b/docs/openapi.jsonindex 0c344c41b..5986edcf8 100644--- a/docs/openapi.json+++ b/docs/openapi.json@@ -4516,6 +4516,7 @@"tags": ["Auth"],+ "x-excluded": true,"x-fern-ignore": true}},@@ -4543,6 +4544,7 @@"tags": ["Auth"],+ "x-excluded": true,"x-fern-ignore": true}},@@ -4558,6 +4560,7 @@"tags": ["Auth"],+ "x-excluded": true,"x-fern-sdk-group-name": ["auth"],@@ -4661,7 +4664,7 @@},"summary": "Get the MCP catalog","tags": [- "Catalog"+ "MCP Servers"],"x-fern-sdk-group-name": ["catalogs",@@ -4697,7 +4700,7 @@},"summary": "Get the model catalog","tags": [- "Catalog"+ "Models"],"x-fern-sdk-group-name": ["catalogs",@@ -4733,7 +4736,7 @@},"summary": "Get the sandbox provider catalog","tags": [- "Catalog"+ "Sandboxes"],"x-fern-sdk-group-name": ["catalogs",@@ -4769,7 +4772,7 @@},"summary": "Get the skill catalog","tags": [- "Catalog"+ "Skills"],"x-fern-sdk-group-name": ["catalogs",@@ -4909,8 +4912,9 @@},"summary": "OAuth callback for MCP authorization","tags": [- "MCP OAuth"+ "MCP Servers"],+ "x-excluded": true,"x-fern-ignore": true}},@@ -5266,7 +5270,7 @@},"summary": "List sessions","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-pagination": {"cursor": "$request.page_token",@@ -5334,7 +5338,7 @@},"summary": "Create a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5376,7 +5380,7 @@},"summary": "Delete a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5433,7 +5437,7 @@},"summary": "Get a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5520,7 +5524,7 @@},"summary": "Update a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5599,7 +5603,7 @@},"summary": "Cancel a running turn in a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5701,7 +5705,7 @@},"summary": "List session events","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-pagination": {"cursor": "$request.page_token",@@ -5798,7 +5802,7 @@},"summary": "List turns in a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-pagination": {"cursor": "$request.page_token",@@ -5915,7 +5919,7 @@},"summary": "Create and execute a turn in a session","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -5996,7 +6000,7 @@},"summary": "Get a turn","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -6128,7 +6132,7 @@},"summary": "Download a file from the turn sandbox","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -6240,7 +6244,7 @@},"summary": "List turn events","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-pagination": {"cursor": "$request.page_token",@@ -6349,7 +6353,7 @@},"summary": "Subscribe to a running turn","tags": [- "Sessions"+ "Agent Sessions"],"x-fern-sdk-group-name": ["sessions"@@ -6611,7 +6615,7 @@},"summary": "List configured model providers","tags": [- "Model Providers"+ "Models"],"x-fern-sdk-group-name": ["settings",@@ -6665,7 +6669,7 @@},"summary": "Create a model provider","tags": [- "Model Providers"+ "Models"],"x-fern-sdk-group-name": ["settings",@@ -6709,7 +6713,7 @@},"summary": "Create or replace a model provider","tags": [- "Model Providers"+ "Models"],"x-fern-sdk-group-name": ["settings",@@ -6745,7 +6749,7 @@},"summary": "Get the configured sandbox provider","tags": [- "Sandbox Providers"+ "Sandboxes"],"x-fern-sdk-group-name": ["settings",@@ -6799,7 +6803,7 @@},"summary": "Create or replace the sandbox provider","tags": [- "Sandbox Providers"+ "Sandboxes"],"x-fern-sdk-group-name": ["settings",@@ -6993,5 +6997,31 @@"BearerAuth": []}],+ "tags": [+ {+ "name": "Auth"+ },+ {+ "name": "Capabilities"+ },+ {+ "name": "Models"+ },+ {+ "name": "MCP Servers"+ },+ {+ "name": "Skills"+ },+ {+ "name": "Sandboxes"+ },+ {+ "name": "Agents"+ },+ {+ "name": "Agent Sessions"+ }+ ],"webhooks": {}}diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.mdindex 653c51c92..aef46b71f 100644--- a/packages/trueforge-sdk/reference.md+++ b/packages/trueforge-sdk/reference.md@@ -495,7 +495,7 @@ await client.server.getCapabilities();</dl></details>-## McpServers+## MCP Servers<details><summary><code>client.mcpServers.<a href="/src/api/resources/mcpServers/client/Client.ts">list</a>() -> TrueForge.ListAvailableMcpServersResponse</code></summary><dl><dd>diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.tsindex 9e3a6b6a3..69a55d3a9 100644--- a/packages/trueforge/src/app.ts+++ b/packages/trueforge/src/app.ts@@ -36,6 +36,7 @@ import type { ISkillStore } from './db/skillStore';import type { WithTransaction } from './db/transaction';import type { IOAuthTokenStore } from './mcp/auth/types';import { PACKAGE_VERSION } from './packageVersion';+import { OPENAPI_DOCUMENT_TAGS } from './routes/openapiTags';import type { ActiveTurnRegistry } from './runtime/activeTurns';import type { EventSubscriptionRegistry } from './runtime/event-subscription';import { zodErrorResponse, zodValidationHook } from './zodErrorResponse';@@ -84,6 +85,7 @@ const openApiDocConfig = {'Covers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.',version: PACKAGE_VERSION,},+ tags: OPENAPI_DOCUMENT_TAGS,};/** Registers the Bearer ID-token scheme used by {@link buildOpenApiDocument}. */diff --git a/packages/trueforge/src/routes/agentRoutes.ts b/packages/trueforge/src/routes/agentRoutes.tsindex fea097bc7..da72aae21 100644--- a/packages/trueforge/src/routes/agentRoutes.ts+++ b/packages/trueforge/src/routes/agentRoutes.ts@@ -11,8 +11,7 @@ import {PutAgentRequestSchema,} from '../schemas/agent';import { RequestErrorResponseSchema } from '../schemas/errors';--const AGENTS_TAG = 'Agents';+import { OpenApiTag } from './openapiTags';export const AgentIdParamsSchema = z.object({agent_id: z.string().min(1).max(64).describe('Immutable agent identifier.'),@@ -21,7 +20,7 @@ export const AgentIdParamsSchema = z.object({export const listAgentsRoute = createRoute({method: 'get',path: '/',- tags: [AGENTS_TAG],+ tags: [OpenApiTag.AGENTS],summary: 'List agents',description: 'All configured agents for the tenant.','x-fern-sdk-group-name': ['agents'],@@ -41,7 +40,7 @@ export const listAgentsRoute = createRoute({export const createAgentRoute = createRoute({method: 'post',path: '/',- tags: [AGENTS_TAG],+ tags: [OpenApiTag.AGENTS],summary: 'Create an agent',description:'Creates an agent and allocates an immutable id. Fails if `name` is already taken. Name cannot be changed later.',@@ -77,7 +76,7 @@ export const createAgentRoute = createRoute({export const getAgentRoute = createRoute({method: 'get',path: '/{agent_id}',- tags: [AGENTS_TAG],+ tags: [OpenApiTag.AGENTS],summary: 'Get an agent',description: 'Fetch a configured agent by immutable id.','x-fern-sdk-group-name': ['agents'],@@ -100,7 +99,7 @@ export const getAgentRoute = createRoute({export const deleteAgentRoute = createRoute({method: 'delete',path: '/{agent_id}',- tags: [AGENTS_TAG],+ tags: [OpenApiTag.AGENTS],summary: 'Delete an agent',description: 'Delete a configured agent by immutable id. Idempotent if already gone.','x-fern-sdk-group-name': ['agents'],@@ -123,7 +122,7 @@ export const deleteAgentRoute = createRoute({export const putAgentRoute = createRoute({method: 'put',path: '/{agent_id}',- tags: [AGENTS_TAG],+ tags: [OpenApiTag.AGENTS],summary: 'Update an agent',description: 'Replaces the manifest for an existing agent keyed by immutable `agent_id`.','x-fern-sdk-group-name': ['agents'],diff --git a/packages/trueforge/src/routes/authRoutes.ts b/packages/trueforge/src/routes/authRoutes.tsindex 132850455..0e45109c5 100644--- a/packages/trueforge/src/routes/authRoutes.ts+++ b/packages/trueforge/src/routes/authRoutes.ts@@ -8,18 +8,18 @@import { createRoute } from '@hono/zod-openapi';import { AuthLoginQuerySchema, MeResponseSchema, OAuthCallbackQuerySchema } from '../schemas/auth';import { RequestErrorResponseSchema } from '../schemas/errors';--const AUTH_TAG = 'Auth';+import { OpenApiTag } from './openapiTags';export const authLoginRoute = createRoute({method: 'get',path: '/login',- tags: [AUTH_TAG],+ tags: [OpenApiTag.AUTH],summary: 'Start the login flow',description:'Redirects the browser to the configured identity provider. In local/single-binary mode, redirects straight ' +'back into the app — there is nothing to log into.','x-fern-ignore': true,+ 'x-excluded': true,request: { query: AuthLoginQuerySchema },responses: {302: { description: 'Redirect to the IdP authorization endpoint.' },@@ -29,12 +29,13 @@ export const authLoginRoute = createRoute({export const oAuthCallbackRoute = createRoute({method: 'get',path: '/callback',- tags: [AUTH_TAG],+ tags: [OpenApiTag.AUTH],summary: 'Login callback',description:'Browser-redirect target hit by the identity provider after login, never called directly by SDK consumers. ' +'In local/single-binary mode, redirects straight back into the app.','x-fern-ignore': true,+ 'x-excluded': true,request: { query: OAuthCallbackQuerySchema },responses: {302: { description: 'Redirect back into the app on success, or to /?error=<reason> on failure.' },@@ -44,13 +45,14 @@ export const oAuthCallbackRoute = createRoute({export const authLogoutRoute = createRoute({method: 'post',path: '/logout',- tags: [AUTH_TAG],+ tags: [OpenApiTag.AUTH],summary: 'Clear the local session',description:'Ends the local harness session only — does not hit the IdP end-session endpoint. A no-op in local/single-binary ' +'mode, since there is no real session to clear.','x-fern-sdk-group-name': ['auth'],'x-fern-sdk-method-name': 'logout',+ 'x-excluded': true,responses: {204: { description: 'Session cookie cleared.' },},@@ -59,7 +61,7 @@ export const authLogoutRoute = createRoute({export const meRoute = createRoute({method: 'get',path: '/me',- tags: [AUTH_TAG],+ tags: [OpenApiTag.AUTH],summary: 'Current session',description:'Returns the authenticated caller identity. When auth is enabled this requires a valid ' +diff --git a/packages/trueforge/src/routes/capabilityRoutes.ts b/packages/trueforge/src/routes/capabilityRoutes.tsindex a8f626038..714161ee5 100644--- a/packages/trueforge/src/routes/capabilityRoutes.ts+++ b/packages/trueforge/src/routes/capabilityRoutes.ts@@ -1,5 +1,6 @@import { createRoute, z } from '@hono/zod-openapi';import { RequestErrorResponseSchema } from '../schemas/errors';+import { OpenApiTag } from './openapiTags';const GetCapabilitiesResponseSchema = z.object({@@ -23,7 +24,7 @@ const GetCapabilitiesResponseSchema = zexport const getCapabilitiesRoute = createRoute({method: 'get',path: '/',- tags: ['Capabilities'],+ tags: [OpenApiTag.CAPABILITIES],summary: 'Get server capabilities','x-fern-sdk-group-name': ['server'],'x-fern-sdk-method-name': 'get_capabilities',diff --git a/packages/trueforge/src/routes/catalogRoutes.ts b/packages/trueforge/src/routes/catalogRoutes.tsindex 6300cbd1f..3eb95d688 100644--- a/packages/trueforge/src/routes/catalogRoutes.ts+++ b/packages/trueforge/src/routes/catalogRoutes.ts@@ -8,13 +8,12 @@ import { GetMcpServerCatalogResponseSchema } from '../schemas/mcpCatalog';import { GetModelProviderCatalogResponseSchema } from '../schemas/modelCatalog';import { GetSandboxProviderCatalogResponseSchema } from '../schemas/sandboxCatalog';import { GetSkillCatalogResponseSchema } from '../schemas/skillCatalog';--const CATALOG_TAG = 'Catalog';+import { OpenApiTag } from './openapiTags';export const listModelProviderCatalogRoute = createRoute({method: 'get',path: '/model-providers',- tags: [CATALOG_TAG],+ tags: [OpenApiTag.MODELS],summary: 'Get the model catalog',description:'Shipped model-provider presets (discovery-only). Copy into PUT /settings/model-providers to configure. ' +@@ -36,7 +35,7 @@ export const listModelProviderCatalogRoute = createRoute({export const listMcpServerCatalogRoute = createRoute({method: 'get',path: '/mcp-servers',- tags: [CATALOG_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'Get the MCP catalog',description: 'Shipped MCP server presets (discovery-only). Copy into PUT /settings/mcp-servers to configure.','x-fern-sdk-group-name': ['catalogs', 'mcpServers'],@@ -56,7 +55,7 @@ export const listMcpServerCatalogRoute = createRoute({export const listSkillCatalogRoute = createRoute({method: 'get',path: '/skills',- tags: [CATALOG_TAG],+ tags: [OpenApiTag.SKILLS],summary: 'Get the skill catalog',description: 'Shipped skill presets (discovery-only). Copy into PUT /settings/skills to configure.','x-fern-sdk-group-name': ['catalogs', 'skills'],@@ -76,7 +75,7 @@ export const listSkillCatalogRoute = createRoute({export const listSandboxProviderCatalogRoute = createRoute({method: 'get',path: '/sandbox-providers',- tags: [CATALOG_TAG],+ tags: [OpenApiTag.SANDBOXES],summary: 'Get the sandbox provider catalog',description:'Shipped sandbox-provider presets (discovery-only). Copy into PUT /settings/sandbox-providers to configure.',diff --git a/packages/trueforge/src/routes/mcpOAuthRoutes.ts b/packages/trueforge/src/routes/mcpOAuthRoutes.tsindex ea60206ed..9fe6610a3 100644--- a/packages/trueforge/src/routes/mcpOAuthRoutes.ts+++ b/packages/trueforge/src/routes/mcpOAuthRoutes.ts@@ -1,13 +1,12 @@import { createRoute } from '@hono/zod-openapi';import { OAuthCallbackQuerySchema, OAuthCallbackSuccessSchema } from '../schemas/auth';import { RequestErrorResponseSchema } from '../schemas/errors';--const MCP_OAUTH_TAG = 'MCP OAuth';+import { OpenApiTag } from './openapiTags';export const mcpOAuthCallbackRoute = createRoute({method: 'get',path: '/callback',- tags: [MCP_OAUTH_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'OAuth callback for MCP authorization',description:'Browser redirect target for MCP server OAuth. The authorization server redirects here with `code`/`state` (or `error`). ' +@@ -15,6 +14,7 @@ export const mcpOAuthCallbackRoute = createRoute({'Not called by the SDK — browsers hit this URL directly.',// Browser-redirect target hit directly by the authorization server, never called by SDK.'x-fern-ignore': true,+ 'x-excluded': true,request: {query: OAuthCallbackQuerySchema,},diff --git a/packages/trueforge/src/routes/mcpServerRoutes.ts b/packages/trueforge/src/routes/mcpServerRoutes.tsindex 1efd668e5..7ef1d7e4c 100644--- a/packages/trueforge/src/routes/mcpServerRoutes.ts+++ b/packages/trueforge/src/routes/mcpServerRoutes.ts@@ -13,14 +13,13 @@ import {McpAuthStatusSchema,PutMcpServerRequestSchema,} from '../schemas/mcpServer';--const MCP_SERVERS_TAG = 'MCP Servers';+import { OpenApiTag } from './openapiTags';/** Chat/composer read view — mounted at /api/v1/mcp-servers (not under settings). */export const listAvailableMcpServersRoute = createRoute({method: 'get',path: '/',- tags: [MCP_SERVERS_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'List MCP servers for chat',description: 'MCP servers as a slim name/url list for the composer. No auth or auth_status.','x-fern-sdk-group-name': ['mcpServers'],@@ -40,7 +39,7 @@ export const listAvailableMcpServersRoute = createRoute({export const listMcpServersRoute = createRoute({method: 'get',path: '/',- tags: [MCP_SERVERS_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'List MCP servers',description:'All MCP servers with nested auth_status (settings / admin projection). Header auth values are redacted.',@@ -69,7 +68,7 @@ const McpServerNameParamsSchema = z.object({export const getMcpServerRoute = createRoute({method: 'get',path: '/{name}',- tags: [MCP_SERVERS_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'Get a single MCP server by name',description:'A single MCP server by name, with nested auth_status (settings / admin projection). Header auth values are redacted.',@@ -93,7 +92,7 @@ export const getMcpServerRoute = createRoute({export const createMcpServerRoute = createRoute({method: 'post',path: '/',- tags: [MCP_SERVERS_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'Create an MCP server',description:'Creates an MCP server by `name`. Fails if `name` is already taken. Runs DCR registration when `auth.type` is `dcr`. ' +@@ -129,7 +128,7 @@ export const createMcpServerRoute = createRoute({export const putMcpServerRoute = createRoute({method: 'put',path: '/',- tags: [MCP_SERVERS_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'Create or replace an MCP server',description:'Create or replace by `name`. Does not start DCR or change oauth client columns. ' +@@ -170,7 +169,7 @@ const ListMcpServerToolsResponseSchema = zexport const listMcpServerToolsRoute = createRoute({method: 'get',path: '/{name}/tools',- tags: [MCP_SERVERS_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'List tools of an MCP server','x-fern-sdk-group-name': ['mcpServers'],'x-fern-sdk-method-name': 'list_tools',@@ -214,7 +213,7 @@ const McpAuthorizeQuerySchema = z.object({export const authorizeMcpServerRoute = createRoute({method: 'get',path: '/{name}/authorize',- tags: [MCP_SERVERS_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'Start (or short-circuit) the auth flow for an MCP server','x-fern-sdk-group-name': ['mcpServers'],'x-fern-sdk-method-name': 'authorize',@@ -258,7 +257,7 @@ export const authorizeMcpServerRoute = createRoute({export const deleteAuthorizationMcpServerRoute = createRoute({method: 'delete',path: '/{name}/authorize',- tags: [MCP_SERVERS_TAG],+ tags: [OpenApiTag.MCP_SERVERS],summary: 'Disconnect OAuth for an MCP server','x-fern-sdk-group-name': ['mcpServers'],'x-fern-sdk-method-name': 'delete_authorization',diff --git a/packages/trueforge/src/routes/modelProviderRoutes.ts b/packages/trueforge/src/routes/modelProviderRoutes.tsindex ee7879f3e..e2a3ffd1c 100644--- a/packages/trueforge/src/routes/modelProviderRoutes.ts+++ b/packages/trueforge/src/routes/modelProviderRoutes.ts@@ -11,13 +11,12 @@ import {ListModelProvidersResponseSchema,PutModelProviderRequestSchema,} from '../schemas/modelProvider';--const MODEL_PROVIDERS_TAG = 'Model Providers';+import { OpenApiTag } from './openapiTags';export const listModelProvidersRoute = createRoute({method: 'get',path: '/',- tags: [MODEL_PROVIDERS_TAG],+ tags: [OpenApiTag.MODELS],summary: 'List configured model providers',description: 'All configured providers with nested manifests.','x-fern-sdk-group-name': ['settings', 'modelProviders'],@@ -41,7 +40,7 @@ export const listModelProvidersRoute = createRoute({export const createModelProviderRoute = createRoute({method: 'post',path: '/',- tags: [MODEL_PROVIDERS_TAG],+ tags: [OpenApiTag.MODELS],summary: 'Create a model provider',description:'Creates a provider (models included). Fails if `name` is already taken. Well-known types use `type` as `name` (one each); ' +@@ -73,7 +72,7 @@ export const createModelProviderRoute = createRoute({export const putModelProviderRoute = createRoute({method: 'put',path: '/',- tags: [MODEL_PROVIDERS_TAG],+ tags: [OpenApiTag.MODELS],summary: 'Create or replace a model provider',description:'Create or replace a provider (models included). Well-known types use `type` as `name` (one each); ' +diff --git a/packages/trueforge/src/routes/modelRoutes.ts b/packages/trueforge/src/routes/modelRoutes.tsindex d89d53bc2..750e9f6aa 100644--- a/packages/trueforge/src/routes/modelRoutes.ts+++ b/packages/trueforge/src/routes/modelRoutes.ts@@ -1,11 +1,12 @@import { createRoute } from '@hono/zod-openapi';import { RequestErrorResponseSchema } from '../schemas/errors';import { ListModelsResponseSchema } from '../schemas/modelProvider';+import { OpenApiTag } from './openapiTags';export const listModelsRoute = createRoute({method: 'get',path: '/',- tags: ['Models'],+ tags: [OpenApiTag.MODELS],summary: 'List models','x-fern-sdk-group-name': ['models'],'x-fern-sdk-method-name': 'list',diff --git a/packages/trueforge/src/routes/openapiTags.ts b/packages/trueforge/src/routes/openapiTags.tsnew file mode 100644index 000000000..549f94b58--- /dev/null+++ b/packages/trueforge/src/routes/openapiTags.ts@@ -0,0 +1,23 @@+/** Mintlify API Reference groups — the only OpenAPI `tags` values. */+export enum OpenApiTag {+ AUTH = 'Auth',+ CAPABILITIES = 'Capabilities',+ MODELS = 'Models',+ MCP_SERVERS = 'MCP Servers',+ SKILLS = 'Skills',+ SANDBOXES = 'Sandboxes',+ AGENTS = 'Agents',+ AGENT_SESSIONS = 'Agent Sessions',+}++/** Document-level tag order for `/api/v1/docs` and Mintlify. */+export const OPENAPI_DOCUMENT_TAGS: { name: OpenApiTag }[] = [+ { name: OpenApiTag.AUTH },+ { name: OpenApiTag.CAPABILITIES },+ { name: OpenApiTag.MODELS },+ { name: OpenApiTag.MCP_SERVERS },+ { name: OpenApiTag.SKILLS },+ { name: OpenApiTag.SANDBOXES },+ { name: OpenApiTag.AGENTS },+ { name: OpenApiTag.AGENT_SESSIONS },+];diff --git a/packages/trueforge/src/routes/sandboxProviderRoutes.ts b/packages/trueforge/src/routes/sandboxProviderRoutes.tsindex 3c83ebc18..5c9144b3c 100644--- a/packages/trueforge/src/routes/sandboxProviderRoutes.ts+++ b/packages/trueforge/src/routes/sandboxProviderRoutes.ts@@ -6,13 +6,12 @@import { createRoute } from '@hono/zod-openapi';import { RequestErrorResponseSchema } from '../schemas/errors';import { GetSandboxProviderResponseSchema, PutSandboxProviderRequestSchema } from '../schemas/sandboxProvider';--const SANDBOX_PROVIDERS_TAG = 'Sandbox Providers';+import { OpenApiTag } from './openapiTags';export const getSandboxProviderRoute = createRoute({method: 'get',path: '/',- tags: [SANDBOX_PROVIDERS_TAG],+ tags: [OpenApiTag.SANDBOXES],summary: 'Get the configured sandbox provider',description: 'The single configured sandbox provider for this tenant. `auth.api_key` is redacted.','x-fern-sdk-group-name': ['settings', 'sandboxProviders'],@@ -32,7 +31,7 @@ export const getSandboxProviderRoute = createRoute({export const putSandboxProviderRoute = createRoute({method: 'put',path: '/',- tags: [SANDBOX_PROVIDERS_TAG],+ tags: [OpenApiTag.SANDBOXES],summary: 'Create or replace the sandbox provider',description:'Upserts the single sandbox provider for this tenant: creates it or replaces its entire configuration. ' +diff --git a/packages/trueforge/src/routes/sessionRoutes.ts b/packages/trueforge/src/routes/sessionRoutes.tsindex e87eb95bc..441657579 100644--- a/packages/trueforge/src/routes/sessionRoutes.ts+++ b/packages/trueforge/src/routes/sessionRoutes.ts@@ -15,8 +15,7 @@ import {} from '../schemas/session';import { CancelSessionRequestSchema, CancelSessionResponseSchema } from '../schemas/turn';import { TOKEN_PAGINATION } from './fernExtensions';--const SESSIONS_TAG = 'Sessions';+import { OpenApiTag } from './openapiTags';export const SessionIdParamsSchema = z.object({session_id: z.string().min(1).max(64).describe('Session identifier.'),@@ -25,7 +24,7 @@ export const SessionIdParamsSchema = z.object({export const createSessionRoute = createRoute({method: 'post',path: '/',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'Create a session',description:'Create a session with `agent` as either `{ name }` (named registry binding) or `{ spec: AgentSpec }` (inline). Named sessions snapshot the agent name at create and resolve the live agent on each turn. Responses use `{ type: "reference", name, id }` or `{ type: "inline", spec }`.',@@ -61,7 +60,7 @@ export const createSessionRoute = createRoute({export const getSessionRoute = createRoute({method: 'get',path: '/{session_id}',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'Get a session',description: 'Fetch a session by ID. Only the session creator (`created_by`) may fetch it.','x-fern-sdk-group-name': ['sessions'],@@ -88,7 +87,7 @@ export const getSessionRoute = createRoute({export const deleteSessionRoute = createRoute({method: 'delete',path: '/{session_id}',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'Delete a session',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.',@@ -111,7 +110,7 @@ export const deleteSessionRoute = createRoute({export const updateSessionRoute = createRoute({method: 'patch',path: '/{session_id}',- tags: [SESSIONS_TAG],+ 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 (`created_by`) may update it.',@@ -152,7 +151,7 @@ export const updateSessionRoute = createRoute({export const listSessionsRoute = createRoute({method: 'get',path: '/',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'List sessions',description:"List the caller's sessions (newest first by default), token-paginated. Results are scoped to the authenticated identity via the session store's `created_by` filter (not a client query param). Optional `agent_id` filters to sessions bound to that named agent. Pass `page_token` to fetch the next page, keeping the other query params constant.",@@ -177,7 +176,7 @@ export const listSessionsRoute = createRoute({export const cancelSessionRoute = createRoute({method: 'post',path: '/{session_id}/cancel',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'Cancel a running turn in a session',description: 'Cancel the running last turn for a session. Only the session creator (`created_by`) may cancel.','x-fern-sdk-group-name': ['sessions'],@@ -213,7 +212,7 @@ export const cancelSessionRoute = createRoute({export const listSessionEventsRoute = createRoute({method: 'get',path: '/{session_id}/events',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'List session events',description:'List session events as `{ turn_id, event }` across the active turn branch (newest first), including persisted events from a running tip. Each turn contributes turn.created, content events (model.message, tool.call, …), and turn.done when terminal; streaming deltas are not included. Use `page_token` to paginate backward toward older events while retaining the original branch anchor. Only the session creator (`created_by`) may list events.',diff --git a/packages/trueforge/src/routes/skillRoutes.ts b/packages/trueforge/src/routes/skillRoutes.tsindex 9dbbcb8aa..cd286e496 100644--- a/packages/trueforge/src/routes/skillRoutes.ts+++ b/packages/trueforge/src/routes/skillRoutes.ts@@ -13,14 +13,13 @@ import {ListSkillsResponseSchema,PutSkillRequestSchema,} from '../schemas/skill';--const SKILLS_TAG = 'Skills';+import { OpenApiTag } from './openapiTags';/** Chat/composer read view — mounted at /api/v1/skills (not under settings). */export const listAvailableSkillsRoute = createRoute({method: 'get',path: '/',- tags: [SKILLS_TAG],+ tags: [OpenApiTag.SKILLS],summary: 'List skills for chat',description: 'Configured skills as a slim name/description list for the composer.','x-fern-sdk-group-name': ['skills'],@@ -40,7 +39,7 @@ export const listAvailableSkillsRoute = createRoute({export const listConfiguredSkillsRoute = createRoute({method: 'get',path: '/',- tags: [SKILLS_TAG],+ tags: [OpenApiTag.SKILLS],summary: 'List configured skills',description: 'All configured skills with nested manifests (settings / admin projection).','x-fern-sdk-group-name': ['settings', 'skills'],@@ -64,7 +63,7 @@ export const listConfiguredSkillsRoute = createRoute({export const createSkillRoute = createRoute({method: 'post',path: '/',- tags: [SKILLS_TAG],+ tags: [OpenApiTag.SKILLS],summary: 'Create a skill',description: 'Creates a skill keyed by `name`. Fails if `name` is already taken.','x-fern-sdk-group-name': ['settings', 'skills'],@@ -94,7 +93,7 @@ export const createSkillRoute = createRoute({export const putSkillRoute = createRoute({method: 'put',path: '/',- tags: [SKILLS_TAG],+ tags: [OpenApiTag.SKILLS],summary: 'Create or replace a skill',description: 'Full upsert keyed by `name`: creates the skill or replaces its entire manifest.','x-fern-sdk-group-name': ['settings', 'skills'],diff --git a/packages/trueforge/src/routes/turnRoutes.ts b/packages/trueforge/src/routes/turnRoutes.tsindex 1c2dbf1ae..7bf74ab23 100644--- a/packages/trueforge/src/routes/turnRoutes.ts+++ b/packages/trueforge/src/routes/turnRoutes.ts@@ -17,10 +17,9 @@ import {SubscribeTurnQuerySchema,} from '../schemas/turn';import { TOKEN_PAGINATION } from './fernExtensions';+import { OpenApiTag } from './openapiTags';import { SessionIdParamsSchema } from './sessionRoutes';-const SESSIONS_TAG = 'Sessions';-export const TurnIdParamsSchema = SessionIdParamsSchema.extend({turn_id: z.string().min(1).describe('Turn identifier.'),});@@ -28,7 +27,7 @@ export const TurnIdParamsSchema = SessionIdParamsSchema.extend({export const listTurnsRoute = createRoute({method: 'get',path: '/{session_id}/turns',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'List turns in a session',description:'List turns for a session (newest first by default), token-paginated. Only the session creator (`created_by`) may list turns.',@@ -62,7 +61,7 @@ export const listTurnsRoute = createRoute({export const getTurnRoute = createRoute({method: 'get',path: '/{session_id}/turns/{turn_id}',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'Get a turn',description: 'Fetch a single turn by ID. Only the session creator (`created_by`) may fetch it.','x-fern-sdk-group-name': ['sessions'],@@ -89,7 +88,7 @@ export const getTurnRoute = createRoute({export const downloadSandboxFileRoute = createRoute({method: 'get',path: '/{session_id}/turns/{turn_id}/download-sandbox-file',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'Download a file from the turn sandbox',description:"Download a file from the sandbox this turn ran in. Paths come from the assistant's `sandbox_artifacts` block. Only the session creator (`created_by`) may download.",@@ -138,7 +137,7 @@ export const downloadSandboxFileRoute = createRoute({export const listTurnEventsRoute = createRoute({method: 'get',path: '/{session_id}/turns/{turn_id}/events',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'List turn events',description:'Paginated persisted events for a turn (insertion order by default). Only the session creator (`created_by`) may list events.',@@ -172,7 +171,7 @@ export const listTurnEventsRoute = createRoute({export const createAndExecuteTurnRoute = createRoute({method: 'post',path: '/{session_id}/turns',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'Create and execute a turn in a session',description: `Create a turn within a session and execute it.Only the session creator (\`created_by\`) may create turns.@@ -242,7 +241,7 @@ Use \`previous_turn_id\` to chain to the session's last turn (defaults to \`autoexport const subscribeTurnRoute = createRoute({method: 'get',path: '/{session_id}/turns/{turn_id}/subscribe',- tags: [SESSIONS_TAG],+ tags: [OpenApiTag.AGENT_SESSIONS],summary: 'Subscribe to a running turn',description:'Subscribe to the live SSE stream for a turn. Only the session creator (`created_by`) may subscribe. Pass `after_sequence_number` to resume after a disconnect (exclusive — events after this sequence number are replayed).',