Skip to content

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

Update descriptions for openapi spec (#137)

Chirag Jain21a4d7d9ca8a
diff --git a/fern/openapi/openapi.json b/fern/openapi/openapi.json
index 0545640cc..b2e33eea3 100644
--- a/fern/openapi/openapi.json
+++ b/fern/openapi/openapi.json
@@ -53,21 +53,25 @@
"type": "object"
}
],
- "description": "Agent Definition"
+ "description": "Complete agent definition used inline on a session or saved as a named agent."
},
"AgentInfo": {
"properties": {
"input": {
+ "description": "Input prompt passed to the subagent.",
"type": "string"
},
"model": {
+ "description": "Optional model override for the subagent.",
"minLength": 1,
"type": "string"
},
"name": {
+ "description": "Display name of the dynamic subagent.",
"type": "string"
},
"type": {
+ "description": "Subagent kind.",
"enum": [
"dynamic"
],
@@ -84,9 +88,11 @@
"AgentParent": {
"properties": {
"thread_id": {
+ "description": "Parent thread that spawned the child agent.",
"type": "string"
},
"tool_call_id": {
+ "description": "Tool call on the parent thread that created the child.",
"type": "string"
}
},
@@ -97,21 +103,24 @@
"type": "object"
},
"AgentSpec": {
- "description": "Agent Definition",
+ "description": "Complete agent definition used inline on a session or saved as a named agent.",
"properties": {
"config": {
"$ref": "#/components/schemas/RuntimeConfig"
},
"instructions": {
+ "description": "Optional system prompt — the agent's role, behavior, and constraints.",
"type": "string"
},
"mcp_servers": {
+ "description": "Optional MCP servers attached by configured name.",
"items": {
"$ref": "#/components/schemas/MCPServer"
},
"type": "array"
},
"messages": {
+ "description": "Optional seed user messages injected at the start of every session.",
"items": {
"$ref": "#/components/schemas/AgentSpecUserMessage"
},
@@ -124,6 +133,7 @@
"$ref": "#/components/schemas/ResponseFormat"
},
"skills": {
+ "description": "Optional name-only skill references. Requires `config.sandbox.enabled: true`.",
"items": {
"$ref": "#/components/schemas/SkillNameRef"
},
@@ -133,6 +143,7 @@
"additionalProperties": {
"type": "string"
},
+ "description": "Optional string key–value map reserved for parameterizing agent definitions.",
"type": "object"
}
},
@@ -144,6 +155,7 @@
"AgentSpecModel": {
"properties": {
"name": {
+ "description": "Model FQN: `provider/model`, e.g. `openai/gpt-5.2`.",
"minLength": 1,
"type": "string"
},
@@ -159,10 +171,12 @@
"AgentSpecUserMessage": {
"properties": {
"content": {
+ "description": "Seed user message content injected at the start of every session.",
"minLength": 1,
"type": "string"
},
"type": {
+ "description": "Seed message type.",
"enum": [
"user.message"
],
@@ -192,7 +206,7 @@
"type": "object"
}
],
- "description": "Agent Definition"
+ "description": "Complete agent definition used inline on a session or saved as a named agent."
},
"AlibabaModelProvider": {
"additionalProperties": false,
@@ -207,6 +221,7 @@
"type": "string"
},
"models": {
+ "description": "Models exposed by this provider (at least one).",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -247,6 +262,7 @@
"type": "string"
},
"models": {
+ "description": "Models exposed by this provider (at least one).",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -277,6 +293,7 @@
"ApprovalAllow": {
"properties": {
"status": {
+ "description": "Allow the pending tool call(s).",
"enum": [
"allow"
],
@@ -308,9 +325,11 @@
"ApprovalDeny": {
"properties": {
"reason": {
+ "description": "Optional reason shown to the agent when denied.",
"type": "string"
},
"status": {
+ "description": "Deny the pending tool call(s).",
"enum": [
"deny"
],
@@ -329,6 +348,7 @@
"properties": {
"enabled": {
"default": true,
+ "description": "Enable the `ask_user_question` tool. Default: true.",
"type": "boolean"
}
},
@@ -337,13 +357,15 @@
"BaseMCPAuthRequiredEvent": {
"properties": {
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"thread_id": {
+ "description": "Always null — this is a run-level event.",
"type": [
"string",
"null"
@@ -363,9 +385,11 @@
"$ref": "#/components/schemas/AgentParent"
},
"thread_id": {
+ "description": "Thread that finished.",
"type": "string"
},
"title": {
+ "description": "Human-readable thread title.",
"type": "string"
}
},
@@ -376,10 +400,12 @@
"type": "object"
},
"CancelSessionRequest": {
+ "description": "Empty request body. Cancel identifies the session via the path only.",
"properties": {},
"type": "object"
},
"CancelSessionResponse": {
+ "description": "Empty success body. HTTP 200 means the cancel request was accepted (or nothing was running).",
"properties": {},
"type": "object"
},
@@ -387,14 +413,17 @@
"additionalProperties": false,
"properties": {
"auto_archive_interval_in_minutes": {
+ "description": "Minutes before Daytona auto-archives the sandbox (0 disables).",
"minimum": 0,
"type": "integer"
},
"auto_delete_interval_in_minutes": {
+ "description": "Minutes before Daytona auto-deletes the sandbox (0 disables).",
"minimum": 0,
"type": "integer"
},
"auto_stop_interval_in_minutes": {
+ "description": "Minutes of idle time before Daytona auto-stops the sandbox (0 disables).",
"minimum": 0,
"type": "integer"
},
@@ -409,6 +438,7 @@
"type": "string"
},
"type": {
+ "description": "Daytona sandbox provider.",
"enum": [
"daytona"
],
@@ -429,7 +459,14 @@
"additionalProperties": false,
"properties": {
"auth": {
- "$ref": "#/components/schemas/ConfiguredMcpServerAuth"
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/ConfiguredMcpServerAuth"
+ },
+ {
+ "description": "Optional default auth settings for the preset."
+ }
+ ]
},
"logo": {
"description": "URL of the MCP server logo asset.",
@@ -464,6 +501,7 @@
"type": "string"
},
"models": {
+ "description": "Preset models for this catalog provider.",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -474,6 +512,7 @@
"$ref": "#/components/schemas/ResourceName"
},
"type": {
+ "description": "Well-known provider type (catalog excludes `custom`).",
"enum": [
"openai",
"anthropic",
@@ -541,22 +580,27 @@
"function": {
"properties": {
"arguments": {
+ "description": "Partial or complete JSON arguments string.",
"type": "string"
},
"name": {
+ "description": "Partial or complete function name.",
"type": "string"
}
},
"type": "object"
},
"id": {
+ "description": "Tool call id (may arrive across multiple deltas).",
"type": "string"
},
"index": {
+ "description": "Index of this tool call in the streaming delta array.",
"minimum": 0,
"type": "integer"
},
"type": {
+ "description": "Tool call type when present on this delta.",
"enum": [
"function"
],
@@ -571,9 +615,11 @@
"ChatCompletionContentPartRefusal": {
"properties": {
"refusal": {
+ "description": "Refusal message text.",
"type": "string"
},
"type": {
+ "description": "Model refusal content part.",
"enum": [
"refusal"
],
@@ -589,9 +635,11 @@
"ChatCompletionContentPartText": {
"properties": {
"text": {
+ "description": "Plain-text content.",
"type": "string"
},
"type": {
+ "description": "Text content part.",
"enum": [
"text"
],
@@ -609,9 +657,11 @@
"function": {
"properties": {
"arguments": {
+ "description": "JSON-encoded function arguments string.",
"type": "string"
},
"name": {
+ "description": "Function/tool name.",
"type": "string"
}
},
@@ -622,9 +672,11 @@
"type": "object"
},
"id": {
+ "description": "Tool call id.",
"type": "string"
},
"type": {
+ "description": "Tool call type.",
"enum": [
"function"
],
@@ -668,6 +720,7 @@
"type": "object"
},
"ConfiguredMcpServerAuth": {
+ "description": "Optional auth settings. Omit when the server needs no credentials.",
"discriminator": {
"mapping": {
"dcr": "#/components/schemas/McpServerDcrAuth",
@@ -700,11 +753,13 @@
},
"properties": {
"compaction_threshold_tokens": {
+ "description": "Context size in tokens that triggers compaction. Default: 50000.",
"exclusiveMinimum": 0,
"type": "integer"
},
"enabled": {
"default": true,
+ "description": "Summarize older history when context grows too large. Default: true.",
"type": "boolean"
}
},
@@ -752,6 +807,7 @@
"CreateTurnRequest": {
"properties": {
"input": {
+ "description": "Turn input items: user messages and/or approval/tool-response resumes. Do not mix user messages with approval or tool-response items.",
"items": {
"$ref": "#/components/schemas/TurnInputItem"
},
@@ -780,6 +836,7 @@
"type": "string"
},
"models": {
+ "description": "Models exposed by this provider (at least one).",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -812,14 +869,17 @@
"$ref": "#/components/schemas/DaytonaSandboxProviderAuth"
},
"auto_archive_interval_in_minutes": {
+ "description": "Minutes before Daytona auto-archives the sandbox (0 disables).",
"minimum": 0,
"type": "integer"
},
"auto_delete_interval_in_minutes": {
+ "description": "Minutes before Daytona auto-deletes the sandbox (0 disables).",
"minimum": 0,
"type": "integer"
},
"auto_stop_interval_in_minutes": {
+ "description": "Minutes of idle time before Daytona auto-stops the sandbox (0 disables).",
"minimum": 0,
"type": "integer"
},
@@ -834,6 +894,7 @@
"type": "string"
},
"type": {
+ "description": "Daytona sandbox provider.",
"enum": [
"daytona"
],
@@ -853,8 +914,10 @@
},
"DaytonaSandboxProviderAuth": {
"additionalProperties": false,
+ "description": "Daytona authentication credentials.",
"properties": {
"api_key": {
+ "description": "Daytona API key.",
"minLength": 1,
"type": "string"
}
@@ -871,6 +934,7 @@
"properties": {
"enabled": {
"default": true,
+ "description": "Allow the agent to spawn dynamic subagents. Default: true.",
"type": "boolean"
}
},
@@ -902,9 +966,11 @@
"type": "string"
},
"name": {
+ "description": "Filename presented to the agent.",
"type": "string"
},
"type": {
+ "description": "File attachment content part.",
"enum": [
"file"
],
@@ -919,6 +985,7 @@
"type": "object"
},
"FinishReason": {
+ "description": "Why the model stopped generating.",
"enum": [
"stop",
"length",
@@ -941,6 +1008,7 @@
"type": "string"
},
"models": {
+ "description": "Models exposed by this provider (at least one).",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -975,6 +1043,7 @@
"properties": {
"enabled": {
"default": true,
+ "description": "Enable Generative UI (OpenUI blocks). Default: true.",
"type": "boolean"
}
},
@@ -1162,6 +1231,7 @@
"type": "string"
},
"models": {
+ "description": "Models exposed by this provider (at least one).",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -1196,6 +1266,7 @@
"properties": {
"enabled": {
"default": true,
+ "description": "Offload oversized tool responses to a sandbox file. Default: true.",
"type": "boolean"
}
},
@@ -1413,12 +1484,14 @@
{
"properties": {
"mcp_servers": {
+ "description": "Servers that need authorization, each with an auth_url.",
"items": {
"$ref": "#/components/schemas/MCPServerAuthInfo"
},
"type": "array"
},
"type": {
+ "description": "One or more MCP servers need OAuth before tools can run.",
"enum": [
"mcp.auth_required"
],
@@ -1436,22 +1509,26 @@
"MCPInitializeEvent": {
"properties": {
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"mcp_servers": {
+ "description": "Servers that were initialized.",
"items": {
"$ref": "#/components/schemas/MCPServerInitInfo"
},
"type": "array"
},
"thread_id": {
+ "description": "Thread that triggered initialization.",
"type": "string"
},
"type": {
+ "description": "MCP server(s) initialized for this turn.",
"enum": [
"mcp.initialize"
],
@@ -1471,6 +1548,7 @@
"properties": {
"disable_tools": {
"default": [],
+ "description": "Tools subtracted from the enabled set. Default: none.",
"items": {
"anyOf": [
{
@@ -1492,6 +1570,7 @@
"default": [
"@all"
],
+ "description": "Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. Default: `[\"@all\"]`.",
"items": {
"anyOf": [
{
@@ -1510,15 +1589,18 @@
"type": "array"
},
"name": {
+ "description": "Name of a configured MCP server (Settings → Connectors).",
"minLength": 1,
"type": "string"
},
"preload": {
"default": false,
+ "description": "When true, load all tool schemas upfront. Default: false (deferred discovery).",
"type": "boolean"
},
"preload_tools": {
"default": [],
+ "description": "Tools loaded eagerly into context while the rest stay deferred. A non-empty list implies `preload: false`.",
"items": {
"anyOf": [
{
@@ -1541,6 +1623,7 @@
"@write",
"@destructive"
],
+ "description": "Tools that pause for human approval: `@all`, `@write`, `@destructive`, or literal names. Default: `[\"@write\", \"@destructive\"]`.",
"items": {
"anyOf": [
{
@@ -1568,12 +1651,15 @@
"MCPServerAuthInfo": {
"properties": {
"auth_url": {
+ "description": "URL the user must visit to complete OAuth for this server.",
"type": "string"
},
"id": {
+ "description": "Internal MCP server id.",
"type": "string"
},
"name": {
+ "description": "Configured MCP server name.",
"type": "string"
}
},
@@ -1587,15 +1673,19 @@
"MCPServerInitInfo": {
"properties": {
"id": {
+ "description": "Internal MCP server id.",
"type": "string"
},
"name": {
+ "description": "Configured MCP server name.",
"type": "string"
},
"session_id": {
+ "description": "Optional MCP session id from the transport.",
"type": "string"
},
"transport_type": {
+ "description": "Transport used to connect to the MCP server.",
"enum": [
"streamable-http",
"sse"
@@ -1612,15 +1702,19 @@
"MCPToolInfo": {
"properties": {
"name": {
+ "description": "Tool name on the MCP server.",
"type": "string"
},
"server_id": {
+ "description": "Internal MCP server id.",
"type": "string"
},
"server_name": {
+ "description": "Configured MCP server name.",
"type": "string"
},
"type": {
+ "description": "Tool hosted on an MCP server.",
"enum": [
"mcp"
],
@@ -1644,6 +1738,7 @@
"type": "string"
},
"status": {
+ "description": "Current auth state for this MCP server.",
"enum": [
"authenticated",
"auth_required",
@@ -1661,6 +1756,7 @@
"additionalProperties": false,
"properties": {
"type": {
+ "description": "Authenticate via OAuth Dynamic Client Registration.",
"enum": [
"dcr"
],
@@ -1684,6 +1780,7 @@
"type": "object"
},
"type": {
+ "description": "Authenticate with static HTTP headers.",
"enum": [
"header"
],
@@ -1728,6 +1825,7 @@
"$ref": "#/components/schemas/ResourceName"
},
"url": {
+ "description": "URL of the remote MCP server.",
"format": "uri",
"type": "string"
}
@@ -1739,6 +1837,7 @@
"type": "object"
},
"McpServerType": {
+ "description": "MCP server kind (`remote` today).",
"enum": [
"remote"
],
@@ -1824,12 +1923,14 @@
"ModelMessageDeltaEvent": {
"properties": {
"content": {
+ "description": "Incremental assistant text content.",
"type": [
"string",
"null"
]
},
"created_at": {
+ "description": "Optional ISO 8601 event timestamp.",
"type": "string"
},
"finish_reason": {
@@ -1840,22 +1941,25 @@
{
"type": "null"
}
- ]
+ ],
+ "description": "Finish reason when this delta completes the stream."
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"reasoning_content": {
"type": "string"
},
"refusal": {
+ "description": "Incremental refusal text when present.",
"type": [
"string",
"null"
]
},
"thread_id": {
+ "description": "Thread that emitted this delta.",
"type": "string"
},
"tool_calls": {
@@ -1865,6 +1969,7 @@
"type": "array"
},
"type": {
+ "description": "Streaming delta for a model.message.",
"enum": [
"model.message.delta"
],
@@ -1904,9 +2009,11 @@
{
"type": "null"
}
- ]
+ ],
+ "description": "Assistant message content as text or content parts."
},
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"finish_reason": {
@@ -1917,25 +2024,29 @@
{
"type": "null"
}
- ]
+ ],
+ "description": "Model finish reason; null when the provider omitted it."
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"name": {
+ "description": "Optional participant name.",
"type": "string"
},
"reasoning_content": {
"type": "string"
},
"refusal": {
+ "description": "Optional refusal text.",
"type": [
"string",
"null"
]
},
"thread_id": {
+ "description": "Thread that emitted this message (`main` for the root agent).",
"type": "string"
},
"tool_calls": {
@@ -1945,6 +2056,7 @@
"type": "array"
},
"type": {
+ "description": "Complete assistant model message.",
"enum": [
"model.message"
],
@@ -1965,36 +2077,44 @@
"ModelMessageUsage": {
"properties": {
"cache_read_tokens": {
+ "description": "Optional cache-read tokens.",
"minimum": 0,
"type": "integer"
},
"cache_write_tokens": {
+ "description": "Optional cache-write tokens.",
"minimum": 0,
"type": "integer"
},
"input_tokens": {
+ "description": "Input tokens for this model call.",
"minimum": 0,
"type": "integer"
},
"input_tokens_breakdown": {
"properties": {
"harness": {
+ "description": "Tokens attributed to harness system framing.",
"minimum": 0,
"type": "integer"
},
"instructions": {
+ "description": "Tokens attributed to agent instructions.",
"minimum": 0,
"type": "integer"
},
"messages": {
+ "description": "Tokens attributed to conversation messages.",
"minimum": 0,
"type": "integer"
},
"skills": {
+ "description": "Tokens attributed to skill instructions.",
"minimum": 0,
"type": "integer"
},
"tool_definitions": {
+ "description": "Tokens attributed to tool schemas.",
"minimum": 0,
"type": "integer"
}
@@ -2009,6 +2129,7 @@
"type": "object"
},
"output_tokens": {
+ "description": "Output tokens for this model call.",
"minimum": 0,
"type": "integer"
}
@@ -2022,23 +2143,30 @@
},
"ModelParams": {
"additionalProperties": {},
+ "description": "Model call parameters passed through to the provider. Known keys are documented; extra keys are allowed and forwarded as-is.",
"properties": {
"max_tokens": {
+ "description": "Maximum tokens to generate in the model response.",
"type": "number"
},
"parallel_tool_calls": {
+ "description": "Whether the model may emit multiple tool calls in one response.",
"type": "boolean"
},
"reasoning_effort": {
+ "description": "Provider-specific reasoning effort (e.g. low/medium/high).",
"type": "string"
},
"temperature": {
+ "description": "Sampling temperature; higher values increase randomness.",
"type": "number"
},
"top_k": {
+ "description": "Top-k sampling; keep only the k highest-probability tokens.",
"type": "number"
},
"top_p": {
+ "description": "Nucleus sampling probability mass.",
"type": "number"
}
},
@@ -2046,16 +2174,20 @@
},
"ModelProperties": {
"additionalProperties": false,
+ "description": "Optional model capability metadata.",
"properties": {
"context_length": {
+ "description": "Maximum context window size in tokens.",
"exclusiveMinimum": 0,
"type": "integer"
},
"max_output_tokens": {
+ "description": "Maximum output tokens the model can generate.",
"exclusiveMinimum": 0,
"type": "integer"
},
"reasoning_efforts": {
+ "description": "Supported reasoning-effort values for this model.",
"items": {
"$ref": "#/components/schemas/ReasoningEffort"
},
@@ -2112,8 +2244,10 @@
},
"ModelProviderAuth": {
"additionalProperties": false,
+ "description": "Provider authentication credentials.",
"properties": {
"api_key": {
+ "description": "API key used to authenticate with the provider.",
"minLength": 1,
"type": "string"
}
@@ -2136,6 +2270,7 @@
"type": "string"
},
"models": {
+ "description": "Models exposed by this provider (at least one).",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -2176,6 +2311,7 @@
"type": "string"
},
"models": {
+ "description": "Models exposed by this provider (at least one).",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -2313,21 +2449,25 @@
"error": {
"properties": {
"code": {
+ "description": "Optional machine-readable error code; null when not applicable.",
"type": [
"string",
"null"
]
},
"message": {
+ "description": "Human-readable explanation of the failure.",
"type": "string"
},
"param": {
+ "description": "Optional request field that caused the error; null when not field-specific.",
"type": [
"string",
"null"
]
},
"type": {
+ "description": "Optional error category (e.g. validation vs conflict).",
"type": "string"
}
},
@@ -2372,8 +2512,10 @@
},
"ResponseFormatJsonObject": {
"additionalProperties": {},
+ "description": "JSON object response format. Extra provider fields are allowed.",
"properties": {
"type": {
+ "description": "Model must return a JSON object.",
"enum": [
"json_object"
],
@@ -2387,21 +2529,27 @@
},
"ResponseFormatJsonSchema": {
"additionalProperties": {},
+ "description": "JSON Schema response format. Extra provider fields are allowed.",
"properties": {
"json_schema": {
"additionalProperties": {},
+ "description": "JSON Schema payload. Extra provider fields are allowed.",
"properties": {
"description": {
+ "description": "Optional schema description for the model.",
"type": "string"
},
"name": {
+ "description": "Schema name sent to the provider.",
"type": "string"
},
"schema": {
"additionalProperties": {},
+ "description": "JSON Schema object for the response.",
"type": "object"
},
"strict": {
+ "description": "When true, ask the provider to enforce the schema strictly.",
"type": [
"boolean",
"null"
@@ -2414,6 +2562,7 @@
"type": "object"
},
"type": {
+ "description": "Model must return JSON matching a schema.",
"enum": [
"json_schema"
],
@@ -2428,8 +2577,10 @@
},
"ResponseFormatText": {
"additionalProperties": {},
+ "description": "Default text response format. Extra provider fields are allowed.",
"properties": {
"type": {
+ "description": "Unconstrained text output.",
"enum": [
"text"
],
@@ -2481,6 +2632,7 @@
},
"iteration_limit": {
"default": 100,
+ "description": "Max agent-loop iterations per turn (1–1024). Default: 100.",
"exclusiveMinimum": 0,
"maximum": 1024,
"type": "integer"
@@ -2498,10 +2650,12 @@
},
"properties": {
"enabled": {
+ "description": "Give the agent a sandbox. Required for skills and Code Mode.",
"type": "boolean"
},
"file_downloads": {
"default": true,
+ "description": "Allow downloading agent-produced files via the turn download endpoint. Default: true.",
"type": "boolean"
},
"network_policy": {
@@ -2516,22 +2670,26 @@
"SandboxCreatedEvent": {
"properties": {
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"sandbox_id": {
+ "description": "Provider sandbox id.",
"type": "string"
},
"thread_id": {
+ "description": "Always null — sandbox is session-scoped.",
"type": [
"string",
"null"
]
},
"type": {
+ "description": "A sandbox was created for this session.",
"enum": [
"sandbox.created"
],
@@ -2550,21 +2708,25 @@
"SandboxNetworkPolicy": {
"properties": {
"auth_inject": {
+ "description": "Up to one rule injecting git basic-auth credentials for exact hosts.",
"items": {
"properties": {
"auth_data": {
"properties": {
"password": {
+ "description": "Basic-auth password.",
"minLength": 1,
"type": "string"
},
"type": {
+ "description": "Basic auth credential type.",
"enum": [
"basic"
],
"type": "string"
},
"username": {
+ "description": "Basic-auth username (no whitespace).",
"pattern": "^\\S+$",
"type": "string"
}
@@ -2579,7 +2741,9 @@
"match": {
"properties": {
"hosts": {
+ "description": "Hostnames that receive injected credentials.",
"items": {
+ "description": "Exact hostname to match (no wildcards).",
"minLength": 1,
"type": "string"
},
@@ -2593,6 +2757,7 @@
"type": "object"
},
"type": {
+ "description": "Inject credentials for git HTTPS clones.",
"enum": [
"git"
],
@@ -2618,21 +2783,26 @@
"$ref": "#/components/schemas/SessionAgent"
},
"created_at": {
+ "description": "ISO 8601 creation timestamp.",
"type": "string"
},
"created_by": {
+ "description": "Caller identity that created the session (immutable).",
"type": "string"
},
"id": {
+ "description": "Unique session id.",
"type": "string"
},
"title": {
+ "description": "Optional human-readable title; null until set.",
"type": [
"string",
"null"
]
},
"updated_at": {
+ "description": "ISO 8601 last-update timestamp.",
"type": "string"
}
},
@@ -2670,6 +2840,7 @@
"$ref": "#/components/schemas/AgentSpec"
},
"type": {
+ "description": "Bind the session to an inline AgentSpec (not a registry id).",
"enum": [
"inline"
],
@@ -2698,16 +2869,19 @@
"additionalProperties": false,
"properties": {
"id": {
+ "description": "Registry agent id.",
"minLength": 1,
"type": "string"
},
"name": {
+ "description": "Create-time snapshot of the registry agent name; null for legacy or orphan rows.",
"type": [
"string",
"null"
]
},
"type": {
+ "description": "Bind the session to a named registry agent.",
"enum": [
"reference"
],
@@ -2792,6 +2966,7 @@
"$ref": "#/components/schemas/SessionEvent"
},
"turn_id": {
+ "description": "Turn that emitted this event.",
"type": "string"
}
},
@@ -2847,7 +3022,7 @@
"additionalProperties": false,
"properties": {
"name": {
- "description": "Name for the skill, used as directory name in sandbox.",
+ "description": "Name of a configured skill (also used as the skill directory name in the sandbox).",
"maxLength": 64,
"minLength": 1,
"pattern": "^[A-Za-z0-9._-]+$",
@@ -2886,9 +3061,11 @@
"TextContent": {
"properties": {
"text": {
+ "description": "Plain-text content.",
"type": "string"
},
"type": {
+ "description": "Text content part.",
"enum": [
"text"
],
@@ -2907,22 +3084,26 @@
"$ref": "#/components/schemas/AgentInfo"
},
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"parent": {
"$ref": "#/components/schemas/AgentParent"
},
"thread_id": {
+ "description": "Id of the new thread.",
"type": "string"
},
"title": {
+ "description": "Human-readable thread title.",
"type": "string"
},
"type": {
+ "description": "A dynamic subagent thread was created.",
"enum": [
"thread.created"
],
@@ -2948,16 +3129,18 @@
{
"properties": {
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"state": {
"$ref": "#/components/schemas/ThreadState"
},
"type": {
+ "description": "A thread reached a terminal state.",
"enum": [
"thread.done"
],
@@ -2997,6 +3180,7 @@
"$ref": "#/components/schemas/ModelMessageEvent"
},
"status": {
+ "description": "Thread completed successfully.",
"enum": [
"done"
],
@@ -3012,12 +3196,14 @@
"ThreadStateError": {
"properties": {
"error": {
+ "description": "Human-readable error message.",
"type": "string"
},
"output": {
"$ref": "#/components/schemas/ModelMessageEvent"
},
"status": {
+ "description": "Thread ended with an error.",
"enum": [
"error"
],
@@ -3043,6 +3229,7 @@
"type": "string"
},
"models": {
+ "description": "Models exposed by this provider (at least one).",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -3073,13 +3260,16 @@
"TokenPagination": {
"properties": {
"limit": {
+ "description": "Page size used for this response.",
"exclusiveMinimum": 0,
"type": "integer"
},
"next_page_token": {
+ "description": "Opaque token for the next page. Omit or absent when there is no next page.",
"type": "string"
},
"previous_page_token": {
+ "description": "Opaque token for the previous page. Omit or absent when there is no previous page.",
"type": "string"
}
},
@@ -3091,22 +3281,26 @@
"ToolApprovalRequiredEvent": {
"properties": {
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"thread_id": {
+ "description": "Thread that owns the pending tool calls.",
"type": "string"
},
"tool_calls": {
+ "description": "Tool calls waiting for approval.",
"items": {
"$ref": "#/components/schemas/ToolCallRef"
},
"type": "array"
},
"type": {
+ "description": "One or more tool calls need human approval.",
"enum": [
"tool.approval_required"
],
@@ -3143,9 +3337,11 @@
"ToolCallRef": {
"properties": {
"id": {
+ "description": "Tool call id awaiting action.",
"type": "string"
},
"source_event_id": {
+ "description": "Event id of the model.message that requested the tool call.",
"type": "string"
}
},
@@ -3178,19 +3374,23 @@
"type": "string"
},
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"thread_id": {
+ "description": "Thread that owns the tool call.",
"type": "string"
},
"tool_call_id": {
+ "description": "Id of the tool call this message responds to.",
"type": "string"
},
"type": {
+ "description": "Result of a tool execution.",
"enum": [
"tool.response"
],
@@ -3210,22 +3410,26 @@
"ToolResponseRequiredEvent": {
"properties": {
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"thread_id": {
+ "description": "Thread that owns the pending tool calls.",
"type": "string"
},
"tool_calls": {
+ "description": "Tool calls waiting for a client response.",
"items": {
"$ref": "#/components/schemas/ToolCallRef"
},
"type": "array"
},
"type": {
+ "description": "One or more client-side tool calls need a user/tool response.",
"enum": [
"tool.response_required"
],
@@ -3244,9 +3448,11 @@
"TrueFoundrySystemToolInfo": {
"properties": {
"name": {
+ "description": "System tool name.",
"type": "string"
},
"type": {
+ "description": "Built-in harness system tool.",
"enum": [
"truefoundry-system"
],
@@ -3262,24 +3468,29 @@
"Turn": {
"properties": {
"created_at": {
+ "description": "ISO 8601 creation timestamp.",
"type": "string"
},
"id": {
+ "description": "Unique turn id.",
"type": "string"
},
"input": {
+ "description": "Input items supplied when the turn was created.",
"items": {
"$ref": "#/components/schemas/TurnInputItem"
},
"type": "array"
},
"previous_turn_id": {
+ "description": "Prior turn this turn chains from; null for a root turn.",
"type": [
"string",
"null"
]
},
"session_id": {
+ "description": "Session that owns this turn.",
"type": "string"
},
"state": {
@@ -3298,19 +3509,22 @@
"TurnCreatedEvent": {
"properties": {
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"input": {
+ "description": "Input items supplied when the turn was created.",
"items": {
"$ref": "#/components/schemas/TurnInputItem"
},
"type": "array"
},
"previous_turn_id": {
+ "description": "Prior turn this turn chains from; null for a root turn.",
"type": [
"string",
"null"
@@ -3320,15 +3534,18 @@
"$ref": "#/components/schemas/TurnStateRunning"
},
"thread_id": {
+ "description": "Thread that owns the event; null for turn-level lifecycle events.",
"type": [
"string",
"null"
]
},
"turn_id": {
+ "description": "Id of the newly created turn.",
"type": "string"
},
"type": {
+ "description": "Emitted when a turn starts.",
"enum": [
"turn.created"
],
@@ -3349,13 +3566,15 @@
"TurnDoneEvent": {
"properties": {
"created_at": {
+ "description": "ISO 8601 event timestamp.",
"type": "string"
},
"id": {
- "description": "Unique identifier for the event",
+ "description": "Unique identifier for the event (monotonic ULID).",
"type": "string"
},
"state": {
+ "description": "Terminal turn state (done, cancelled, or error).",
"discriminator": {
"mapping": {
"cancelled": "#/components/schemas/TurnStateCancelled",
@@ -3377,12 +3596,14 @@
]
},
"thread_id": {
+ "description": "Thread that owns the event; null for turn-level lifecycle events.",
"type": [
"string",
"null"
]
},
"type": {
+ "description": "Emitted when a turn reaches a terminal state.",
"enum": [
"turn.done"
],
@@ -3420,32 +3641,40 @@
]
},
"TurnMetrics": {
+ "description": "Optional billable aggregate for the whole turn.",
"properties": {
"total_cache_read_tokens": {
+ "description": "Total cache-read tokens across model calls in this turn.",
"minimum": 0,
"type": "integer"
},
"total_cache_write_tokens": {
+ "description": "Total cache-write tokens across model calls in this turn.",
"minimum": 0,
"type": "integer"
},
"total_cost_in_usd": {
+ "description": "Estimated total cost in USD for this turn.",
"minimum": 0,
"type": "number"
},
"total_input_tokens": {
+ "description": "Total input tokens across model calls in this turn.",
"minimum": 0,
"type": "integer"
},
"total_output_tokens": {
+ "description": "Total output tokens across model calls in this turn.",
"minimum": 0,
"type": "integer"
},
"total_reasoning_tokens": {
+ "description": "Total reasoning tokens across model calls in this turn.",
"minimum": 0,
"type": "integer"
},
"total_tokens": {
+ "description": "Total tokens (input + output) across model calls in this turn.",
"minimum": 0,
"type": "integer"
}
@@ -3480,15 +3709,24 @@
"TurnStateCancelled": {
"properties": {
"completed_at": {
+ "description": "ISO 8601 time when cancellation completed.",
"type": "string"
},
"metrics": {
- "$ref": "#/components/schemas/TurnMetrics"
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/TurnMetrics"
+ },
+ {
+ "description": "Optional billable aggregate for work done before cancel."
+ }
+ ]
},
"reason": {
"$ref": "#/components/schemas/TurnStateCancelledReason"
},
"status": {
+ "description": "Turn was cancelled before completion.",
"enum": [
"cancelled"
],
@@ -3515,6 +3753,7 @@
"TurnStateDone": {
"properties": {
"completed_at": {
+ "description": "ISO 8601 time when the turn reached a terminal state.",
"type": "string"
},
"metrics": {
@@ -3528,15 +3767,18 @@
{
"type": "null"
}
- ]
+ ],
+ "description": "Final `model.message` for the turn, or null when the turn ended paused without a final message."
},
"required_actions": {
+ "description": "Pending actions (`tool.approval_required`, `tool.response_required`, `mcp.auth_required`); empty when none.",
"items": {
"$ref": "#/components/schemas/ActionRequiredEvent"
},
"type": "array"
},
"status": {
+ "description": "Turn finished (possibly paused for required actions).",
"enum": [
"done"
],
@@ -3554,15 +3796,25 @@
"TurnStateError": {
"properties": {
"completed_at": {
+ "description": "ISO 8601 time when the error state was recorded.",
"type": "string"
},
"message": {
+ "description": "Human-readable error message.",
"type": "string"
},
"metrics": {
- "$ref": "#/components/schemas/TurnMetrics"
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/TurnMetrics"
+ },
+ {
+ "description": "Optional billable aggregate for work done before the error."
+ }
+ ]
},
"status": {
+ "description": "Turn ended with an error.",
"enum": [
"error"
],
@@ -3579,6 +3831,7 @@
"TurnStateRunning": {
"properties": {
"status": {
+ "description": "Turn is still executing.",
"enum": [
"running"
],
@@ -3648,21 +3901,24 @@
]
},
"UpdateAgentRequest": {
- "description": "Agent Definition",
+ "description": "Complete agent definition used inline on a session or saved as a named agent.",
"properties": {
"config": {
"$ref": "#/components/schemas/RuntimeConfig"
},
"instructions": {
+ "description": "Optional system prompt — the agent's role, behavior, and constraints.",
"type": "string"
},
"mcp_servers": {
+ "description": "Optional MCP servers attached by configured name.",
"items": {
"$ref": "#/components/schemas/MCPServer"
},
"type": "array"
},
"messages": {
+ "description": "Optional seed user messages injected at the start of every session.",
"items": {
"$ref": "#/components/schemas/AgentSpecUserMessage"
},
@@ -3675,6 +3931,7 @@
"$ref": "#/components/schemas/ResponseFormat"
},
"skills": {
+ "description": "Optional name-only skill references. Requires `config.sandbox.enabled: true`.",
"items": {
"$ref": "#/components/schemas/SkillNameRef"
},
@@ -3684,6 +3941,7 @@
"additionalProperties": {
"type": "string"
},
+ "description": "Optional string key–value map reserved for parameterizing agent definitions.",
"type": "object"
}
},
@@ -3714,9 +3972,11 @@
},
"type": "array"
}
- ]
+ ],
+ "description": "Plain string or structured text/file content parts."
},
"type": {
+ "description": "User message input item.",
"enum": [
"user.message"
],
@@ -3752,14 +4012,17 @@
"$ref": "#/components/schemas/ApprovalDecision"
},
"thread_id": {
+ "description": "Thread that owns the pending tool call.",
"minLength": 1,
"type": "string"
},
"tool_call_id": {
+ "description": "Tool call id being approved or denied.",
"minLength": 1,
"type": "string"
},
"type": {
+ "description": "Client resume after tool.approval_required.",
"enum": [
"user.tool_approval"
],
@@ -3777,18 +4040,22 @@
"UserToolResponseEvent": {
"properties": {
"content": {
+ "description": "Client-side tool result content.",
"minLength": 1,
"type": "string"
},
"thread_id": {
+ "description": "Thread that owns the pending tool call.",
"minLength": 1,
"type": "string"
},
"tool_call_id": {
+ "description": "Tool call id receiving the client response.",
"minLength": 1,
"type": "string"
},
"type": {
+ "description": "Client resume after tool.response_required.",
"enum": [
"user.tool_response"
],
@@ -3816,6 +4083,7 @@
"type": "string"
},
"models": {
+ "description": "Models exposed by this provider (at least one).",
"items": {
"$ref": "#/components/schemas/ModelEntry"
},
@@ -3846,8 +4114,8 @@
}
},
"info": {
- "description": "Agent server with DB-backed sessions, agent registry, settings catalogs, and model/MCP/skill providers.",
- "title": "Agent Server",
+ "description": "HTTP API for the TrueForge agent server (`/api/v1`). Interactive docs are served at `/api/v1/docs` (OpenAPI JSON at `/api/v1/openapi.json`).\n\n**Authentication:** Standalone deployments (no OIDC) accept requests without credentials — middleware stamps a local default user. When OIDC is configured, browser login sets an httpOnly `id_token` cookie; protected routes read that cookie (not `Authorization: Bearer`). There is no built-in API-key scheme; pass custom headers only if your reverse proxy or IdP layer requires them.\n\nCovers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.",
+ "title": "TrueForge API",
"version": "0.1.0"
},
"openapi": "3.1.0",
@@ -3865,6 +4133,16 @@
}
},
"description": "All configured agents."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
}
},
"summary": "List agents",
@@ -3960,6 +4238,16 @@
"responses": {
"204": {
"description": "Agent deleted."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
}
},
"summary": "Delete an agent",
@@ -4139,10 +4427,12 @@
}
},
{
+ "description": "Human-readable error detail from the identity provider when `error` is set.",
"in": "query",
"name": "error_description",
"required": false,
"schema": {
+ "description": "Human-readable error detail from the identity provider when `error` is set.",
"type": "string"
}
}
@@ -4219,6 +4509,13 @@
"description": "Session type and identity for the current request."
},
"401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
"description": "OIDC is configured and the request has no valid session cookie."
}
},
@@ -4245,6 +4542,16 @@
}
},
"description": "Server capabilities."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
}
},
"summary": "Get server capabilities",
@@ -4270,6 +4577,16 @@
}
},
"description": "All MCP servers (chat projection)."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
}
},
"summary": "List MCP servers for chat",
@@ -4284,6 +4601,7 @@
},
"/api/v1/mcp-servers/oauth/callback": {
"get": {
+ "description": "Browser redirect target for MCP server OAuth. The authorization server redirects here with `code`/`state` (or `error`). Exchanges the code for tokens, then either returns JSON or redirects to the `redirect_url` supplied at authorize time. Not called by the SDK — browsers hit this URL directly.",
"parameters": [
{
"description": "Authorization code, present when the user granted consent.",
@@ -4318,10 +4636,12 @@
}
},
{
+ "description": "Human-readable error detail from the identity provider when `error` is set.",
"in": "query",
"name": "error_description",
"required": false,
"schema": {
+ "description": "Human-readable error detail from the identity provider when `error` is set.",
"type": "string"
}
}
@@ -4333,6 +4653,7 @@
"schema": {
"properties": {
"success": {
+ "description": "Present when the OAuth callback completed without a redirect_url.",
"enum": [
true
],
@@ -4537,6 +4858,16 @@
}
},
"description": "All models of all configured providers."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
}
},
"summary": "List models",
@@ -5648,10 +5979,12 @@
}
},
{
+ "description": "Exclusive resume cursor: replay only events with a sequence number greater than this value. Omit to start from the beginning of the live buffer.",
"in": "query",
"name": "after_sequence_number",
"required": false,
"schema": {
+ "description": "Exclusive resume cursor: replay only events with a sequence number greater than this value. Omit to start from the beginning of the live buffer.",
"minimum": 0,
"type": [
"integer",
@@ -5679,7 +6012,7 @@
}
}
},
- "description": "Invalid request body."
+ "description": "Invalid query parameters."
},
"403": {
"content": {
@@ -5739,6 +6072,26 @@
}
},
"description": "All MCP servers."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
+ },
+ "403": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the caller is authenticated but not an admin."
}
},
"summary": "List MCP servers",
@@ -5819,6 +6172,26 @@
}
},
"description": "The shipped catalog, verbatim."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
+ },
+ "403": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the caller is authenticated but not an admin."
}
},
"summary": "Get the MCP catalog",
@@ -5973,6 +6346,26 @@
}
},
"description": "All configured model providers."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
+ },
+ "403": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the caller is authenticated but not an admin."
}
},
"summary": "List configured model providers",
@@ -6043,6 +6436,26 @@
}
},
"description": "The shipped catalog, verbatim."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
+ },
+ "403": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the caller is authenticated but not an admin."
}
},
"summary": "Get the model catalog",
@@ -6149,6 +6562,26 @@
}
},
"description": "The shipped catalog, verbatim."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
+ },
+ "403": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the caller is authenticated but not an admin."
}
},
"summary": "Get the sandbox provider catalog",
@@ -6175,6 +6608,26 @@
}
},
"description": "All configured skills."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
+ },
+ "403": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the caller is authenticated but not an admin."
}
},
"summary": "List configured skills",
@@ -6245,6 +6698,26 @@
}
},
"description": "The shipped catalog, verbatim."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
+ },
+ "403": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the caller is authenticated but not an admin."
}
},
"summary": "Get the skill catalog",
@@ -6271,6 +6744,16 @@
}
},
"description": "All configured skills (chat projection)."
+ },
+ "401": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RequestErrorResponse"
+ }
+ }
+ },
+ "description": "OIDC is configured and the request has no valid session cookie."
}
},
"summary": "List skills for chat",
diff --git a/packages/harness/src/agent-session/schemas/agentSpec.ts b/packages/harness/src/agent-session/schemas/agentSpec.ts
index 277b34bb5..e15ed45f2 100644
--- a/packages/harness/src/agent-session/schemas/agentSpec.ts
+++ b/packages/harness/src/agent-session/schemas/agentSpec.ts
@@ -21,20 +21,29 @@ export const DEFAULT_AGENT_CONFIG_ITERATION_LIMIT = 100;
const ModelParamsSchema = z
.object({
- max_tokens: z.number().optional(),
- temperature: z.number().optional(),
- top_p: z.number().optional(),
- top_k: z.number().optional(),
- parallel_tool_calls: z.boolean().optional(),
- reasoning_effort: z.string().optional(),
+ max_tokens: z.number().optional().describe('Maximum tokens to generate in the model response.'),
+ temperature: z.number().optional().describe('Sampling temperature; higher values increase randomness.'),
+ top_p: z.number().optional().describe('Nucleus sampling probability mass.'),
+ top_k: z.number().optional().describe('Top-k sampling; keep only the k highest-probability tokens.'),
+ parallel_tool_calls: z
+ .boolean()
+ .optional()
+ .describe('Whether the model may emit multiple tool calls in one response.'),
+ reasoning_effort: z.string().optional().describe('Provider-specific reasoning effort (e.g. low/medium/high).'),
})
.loose() // this ensures extra model params are allowed
+ .describe(
+ 'Model call parameters passed through to the provider. Known keys are documented; extra keys are allowed and forwarded as-is.',
+ )
.openapi('ModelParams');
// Opaque runtime identifier; the hosting server owns naming conventions (e.g. provider/model).
const ModelSpecSchema = z
.object({
- name: z.string().min(1, 'model.name must not be empty'),
+ name: z
+ .string()
+ .min(1, 'model.name must not be empty')
+ .describe('Model FQN: `provider/model`, e.g. `openai/gpt-5.2`.'),
params: ModelParamsSchema.optional(),
})
.openapi('AgentSpecModel');
@@ -60,44 +69,86 @@ const RequireApprovalToolSelectorSchema = z.union([
// Auth headers are not part of the spec — they come from the configured MCP server store.
const MCPServerRequestSchema = z
.object({
- name: z.string().min(1, 'mcp_servers[].name must not be empty'),
+ name: z
+ .string()
+ .min(1, 'mcp_servers[].name must not be empty')
+ .describe('Name of a configured MCP server (Settings → Connectors).'),
// Which tools to enable. Default: all tools.
- enable_tools: z.array(EnableToolSelectorSchema).default(DEFAULT_ENABLE_TOOLS),
+ enable_tools: z
+ .array(EnableToolSelectorSchema)
+ .default(DEFAULT_ENABLE_TOOLS)
+ .describe('Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. Default: `["@all"]`.'),
// Which tools to disable (subtracted from enable_tools). Default: none.
- disable_tools: z.array(EnableToolSelectorSchema).default(DEFAULT_DISABLE_TOOLS),
+ disable_tools: z
+ .array(EnableToolSelectorSchema)
+ .default(DEFAULT_DISABLE_TOOLS)
+ .describe('Tools subtracted from the enabled set. Default: none.'),
// When the server is not fully preloaded (`preload: false`), which tools to
// still preload into context. A non-empty list implies `preload: false`.
- preload_tools: z.array(EnableToolSelectorSchema).default(DEFAULT_PRELOAD_TOOLS),
+ preload_tools: z
+ .array(EnableToolSelectorSchema)
+ .default(DEFAULT_PRELOAD_TOOLS)
+ .describe(
+ 'Tools loaded eagerly into context while the rest stay deferred. A non-empty list implies `preload: false`.',
+ ),
// Tools that require human approval before execution. Default: @write + @destructive.
- require_approval_for_tools: z.array(RequireApprovalToolSelectorSchema).default(DEFAULT_REQUIRE_APPROVAL_FOR_TOOLS),
+ require_approval_for_tools: z
+ .array(RequireApprovalToolSelectorSchema)
+ .default(DEFAULT_REQUIRE_APPROVAL_FOR_TOOLS)
+ .describe(
+ 'Tools that pause for human approval: `@all`, `@write`, `@destructive`, or literal names. Default: `["@write", "@destructive"]`.',
+ ),
// Whether this server's tools are preloaded into context. Default: false.
// When false, tools are discovered lazily and only `preload_tools` stay eager.
- preload: z.boolean().optional().default(false),
+ preload: z
+ .boolean()
+ .optional()
+ .default(false)
+ .describe('When true, load all tool schemas upfront. Default: false (deferred discovery).'),
})
.openapi('MCPServer');
// --- Runtime config ---
const CompactionSettingsSchema = z.object({
- enabled: z.boolean().default(true),
- compaction_threshold_tokens: z.number().int().positive().optional(),
+ enabled: z.boolean().default(true).describe('Summarize older history when context grows too large. Default: true.'),
+ compaction_threshold_tokens: z
+ .number()
+ .int()
+ .positive()
+ .optional()
+ .describe('Context size in tokens that triggers compaction. Default: 50000.'),
});
const LargeToolResponseSettingsSchema = z.object({
- enabled: z.boolean().default(true),
+ enabled: z.boolean().default(true).describe('Offload oversized tool responses to a sandbox file. Default: true.'),
individual_tool_response_token_threshold: z
.number()
.int()
.positive()
.optional()
- .default(DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD),
+ .default(DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD)
+ .describe(
+ `Token threshold for a single tool response before offloading. Default: ${String(DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD)}.`,
+ ),
total_tool_response_token_threshold: z
.number()
.int()
.positive()
.optional()
- .default(DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD),
- preview_number_of_characters: z.number().int().positive().optional().default(DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS),
+ .default(DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD)
+ .describe(
+ `Combined tool-response token threshold before offloading. Default: ${String(DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD)}.`,
+ ),
+ preview_number_of_characters: z
+ .number()
+ .int()
+ .positive()
+ .optional()
+ .default(DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS)
+ .describe(
+ `Characters of preview kept in context after offloading. Default: ${String(DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS)}.`,
+ ),
});
const BASIC_AUTH_USERNAME_PATTERN = /^\S+$/;
@@ -115,19 +166,24 @@ const SandboxAuthInjectMatchSchema = z.object({
.min(1)
.refine(host => !hostContainsWildcard(host), {
message: 'Hosts must be exact hostnames without wildcards',
- }),
+ })
+ .describe('Exact hostname to match (no wildcards).'),
)
- .min(1),
+ .min(1)
+ .describe('Hostnames that receive injected credentials.'),
});
const SandboxBasicAuthDataSchema = z.object({
- type: z.literal('basic'),
- username: z.string().regex(BASIC_AUTH_USERNAME_PATTERN, 'Username must be non-empty and contain no whitespace'),
- password: z.string().min(1),
+ type: z.literal('basic').describe('Basic auth credential type.'),
+ username: z
+ .string()
+ .regex(BASIC_AUTH_USERNAME_PATTERN, 'Username must be non-empty and contain no whitespace')
+ .describe('Basic-auth username (no whitespace).'),
+ password: z.string().min(1).describe('Basic-auth password.'),
});
const SandboxGitAuthInjectSchema = z.object({
- type: z.literal('git'),
+ type: z.literal('git').describe('Inject credentials for git HTTPS clones.'),
match: SandboxAuthInjectMatchSchema,
auth_data: SandboxBasicAuthDataSchema,
});
@@ -137,21 +193,25 @@ const SandboxNetworkPolicySchema = z
auth_inject: z
.array(SandboxGitAuthInjectSchema)
.max(1, 'At most one auth inject rule is supported (type: git)')
- .optional(),
+ .optional()
+ .describe('Up to one rule injecting git basic-auth credentials for exact hosts.'),
})
.openapi('SandboxNetworkPolicy');
const SandboxConfigSchema = z
.object({
- enabled: z.boolean(),
- file_downloads: z.boolean().default(true),
+ enabled: z.boolean().describe('Give the agent a sandbox. Required for skills and Code Mode.'),
+ file_downloads: z
+ .boolean()
+ .default(true)
+ .describe('Allow downloading agent-produced files via the turn download endpoint. Default: true.'),
network_policy: SandboxNetworkPolicySchema.optional(),
})
.openapi('SandboxConfig');
const DynamicSubAgentsConfigSchema = z
.object({
- enabled: z.boolean().default(true),
+ enabled: z.boolean().default(true).describe('Allow the agent to spawn dynamic subagents. Default: true.'),
})
.openapi('DynamicSubAgentsConfig');
@@ -168,19 +228,27 @@ const ContextManagementConfigSchema = z
const GenerativeUIConfigSchema = z
.object({
- enabled: z.boolean().default(true),
+ enabled: z.boolean().default(true).describe('Enable Generative UI (OpenUI blocks). Default: true.'),
})
.openapi('GenerativeUIConfig');
const AskUserQuestionsConfigSchema = z
.object({
- enabled: z.boolean().default(true),
+ enabled: z.boolean().default(true).describe('Enable the `ask_user_question` tool. Default: true.'),
})
.openapi('AskUserQuestionsConfig');
export const RuntimeConfigSchema = z
.object({
- iteration_limit: z.number().int().positive().max(1024).default(DEFAULT_AGENT_CONFIG_ITERATION_LIMIT),
+ iteration_limit: z
+ .number()
+ .int()
+ .positive()
+ .max(1024)
+ .default(DEFAULT_AGENT_CONFIG_ITERATION_LIMIT)
+ .describe(
+ `Max agent-loop iterations per turn (1–1024). Default: ${String(DEFAULT_AGENT_CONFIG_ITERATION_LIMIT)}.`,
+ ),
sandbox: SandboxConfigSchema.default(() => ({ enabled: false, file_downloads: true })),
dynamic_sub_agents: DynamicSubAgentsConfigSchema.default(() => ({ enabled: true })),
context_management: ContextManagementConfigSchema.default(() => ({
@@ -208,7 +276,7 @@ const SkillNameRefSchema = z
.regex(SKILL_NAME_REGEX, 'Name may only contain letters, numbers, ".", "_", and "-"')
.refine(v => v !== '.' && v !== '..', 'Name must not be "." or ".."')
.refine(v => !v.startsWith('.tfy-'), 'Name must not use the reserved ".tfy-" prefix')
- .describe('Name for the skill, used as directory name in sandbox.'),
+ .describe('Name of a configured skill (also used as the skill directory name in the sandbox).'),
})
.strict()
.openapi('SkillNameRef');
@@ -217,11 +285,12 @@ const SkillNameRefSchema = z
const AgentSpecUserMessageSchema = z
.object({
- type: z.literal('user.message'),
+ type: z.literal('user.message').describe('Seed message type.'),
content: z
.string()
.min(1, 'User message content must not be empty')
- .refine(content => content.trim().length > 0, 'User message content must not be empty'),
+ .refine(content => content.trim().length > 0, 'User message content must not be empty')
+ .describe('Seed user message content injected at the start of every session.'),
})
.openapi('AgentSpecUserMessage');
@@ -230,16 +299,31 @@ const AgentSpecUserMessageSchema = z
export const AgentSpecSchema = z
.object({
model: ModelSpecSchema,
- instructions: z.string().optional(),
- messages: z.array(AgentSpecUserMessageSchema).optional(),
- mcp_servers: z.array(MCPServerRequestSchema).optional(),
+ instructions: z
+ .string()
+ .optional()
+ .describe("Optional system prompt — the agent's role, behavior, and constraints."),
+ messages: z
+ .array(AgentSpecUserMessageSchema)
+ .optional()
+ .describe('Optional seed user messages injected at the start of every session.'),
+ mcp_servers: z
+ .array(MCPServerRequestSchema)
+ .optional()
+ .describe('Optional MCP servers attached by configured name.'),
response_format: ResponseFormatSchema.optional(),
- skills: z.array(SkillNameRefSchema).optional(),
+ skills: z
+ .array(SkillNameRefSchema)
+ .optional()
+ .describe('Optional name-only skill references. Requires `config.sandbox.enabled: true`.'),
// Factory must parse so nested RuntimeConfig field defaults materialize.
config: RuntimeConfigSchema.default(() => RuntimeConfigSchema.parse({})),
- variables: z.record(z.string(), z.string()).optional(),
+ variables: z
+ .record(z.string(), z.string())
+ .optional()
+ .describe('Optional string key–value map reserved for parameterizing agent definitions.'),
})
- .describe('Agent Definition')
+ .describe('Complete agent definition used inline on a session or saved as a named agent.')
.openapi('AgentSpec');
export type AgentSpec = z.infer<typeof AgentSpecSchema>;
diff --git a/packages/harness/src/agent-session/schemas/events.ts b/packages/harness/src/agent-session/schemas/events.ts
index 288ce88c2..9bdf31df7 100644
--- a/packages/harness/src/agent-session/schemas/events.ts
+++ b/packages/harness/src/agent-session/schemas/events.ts
@@ -35,24 +35,26 @@ export const EventType = {
export const TurnCreatedEventSchema = z
.object({
- type: z.literal(EventType.TURN_CREATED),
+ type: z.literal(EventType.TURN_CREATED).describe('Emitted when a turn starts.'),
id: EventIdSchema,
- turn_id: z.string(),
- previous_turn_id: z.string().nullable(),
- input: z.array(TurnInputItemSchema).optional(),
+ turn_id: z.string().describe('Id of the newly created turn.'),
+ previous_turn_id: z.string().nullable().describe('Prior turn this turn chains from; null for a root turn.'),
+ input: z.array(TurnInputItemSchema).optional().describe('Input items supplied when the turn was created.'),
state: TurnStateRunningSchema,
- created_at: z.string(),
- thread_id: z.string().nullable(),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
+ thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),
})
.openapi('TurnCreatedEvent');
export const TurnDoneEventSchema = z
.object({
- type: z.literal(EventType.TURN_DONE),
+ type: z.literal(EventType.TURN_DONE).describe('Emitted when a turn reaches a terminal state.'),
id: EventIdSchema,
- state: z.discriminatedUnion('status', [TurnStateDoneSchema, TurnStateCancelledSchema, TurnStateErrorSchema]),
- created_at: z.string(),
- thread_id: z.string().nullable(),
+ state: z
+ .discriminatedUnion('status', [TurnStateDoneSchema, TurnStateCancelledSchema, TurnStateErrorSchema])
+ .describe('Terminal turn state (done, cancelled, or error).'),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
+ thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),
})
.openapi('TurnDoneEvent');
@@ -76,7 +78,7 @@ export const SessionEventSchema = z
/** One row on the session timeline: which turn emitted the event plus the event payload. */
export const SessionEventItemSchema = z
.object({
- turn_id: z.string(),
+ turn_id: z.string().describe('Turn that emitted this event.'),
event: SessionEventSchema,
})
.openapi('SessionEventItem');
diff --git a/packages/harness/src/agent-session/schemas/pagination.ts b/packages/harness/src/agent-session/schemas/pagination.ts
index 6b1bba6d3..abb38225f 100644
--- a/packages/harness/src/agent-session/schemas/pagination.ts
+++ b/packages/harness/src/agent-session/schemas/pagination.ts
@@ -3,9 +3,15 @@ import { z } from '@hono/zod-openapi';
export const TokenPaginationSchema = z
.object({
- next_page_token: z.string().optional(),
- previous_page_token: z.string().optional(),
- limit: z.number().int().positive(),
+ next_page_token: z
+ .string()
+ .optional()
+ .describe('Opaque token for the next page. Omit or absent when there is no next page.'),
+ previous_page_token: z
+ .string()
+ .optional()
+ .describe('Opaque token for the previous page. Omit or absent when there is no previous page.'),
+ limit: z.number().int().positive().describe('Page size used for this response.'),
})
.openapi('TokenPagination');
diff --git a/packages/harness/src/agent-session/schemas/session.ts b/packages/harness/src/agent-session/schemas/session.ts
index 6a5deab16..23287efcd 100644
--- a/packages/harness/src/agent-session/schemas/session.ts
+++ b/packages/harness/src/agent-session/schemas/session.ts
@@ -7,17 +7,20 @@ import { AgentSpecSchema } from './agentSpec';
export const SessionAgentReferenceSchema = z
.object({
- type: z.literal('reference'),
- id: z.string().min(1),
+ type: z.literal('reference').describe('Bind the session to a named registry agent.'),
+ id: z.string().min(1).describe('Registry agent id.'),
/** Create-time snapshot of the registry agent name; null for legacy/orphan rows. */
- name: z.string().nullable(),
+ name: z
+ .string()
+ .nullable()
+ .describe('Create-time snapshot of the registry agent name; null for legacy or orphan rows.'),
})
.strict()
.openapi('SessionAgentReference');
export const SessionAgentInlineSchema = z
.object({
- type: z.literal('inline'),
+ type: z.literal('inline').describe('Bind the session to an inline AgentSpec (not a registry id).'),
spec: AgentSpecSchema,
})
.strict()
@@ -30,13 +33,13 @@ export const SessionAgentSchema = z
export const SessionSchema = z
.object({
- id: z.string(),
+ id: z.string().describe('Unique session id.'),
agent: SessionAgentSchema,
- title: z.string().nullable(),
+ title: z.string().nullable().describe('Optional human-readable title; null until set.'),
/** Caller identity that created the session (immutable). */
- created_by: z.string(),
- created_at: z.string(),
- updated_at: z.string(),
+ created_by: z.string().describe('Caller identity that created the session (immutable).'),
+ created_at: z.string().describe('ISO 8601 creation timestamp.'),
+ updated_at: z.string().describe('ISO 8601 last-update timestamp.'),
})
.openapi('Session');
diff --git a/packages/harness/src/agent-session/schemas/turn.ts b/packages/harness/src/agent-session/schemas/turn.ts
index 0cd28c9f1..bef32990d 100644
--- a/packages/harness/src/agent-session/schemas/turn.ts
+++ b/packages/harness/src/agent-session/schemas/turn.ts
@@ -21,7 +21,7 @@ export enum CancellationReason {
export const TurnStateRunningSchema = z
.object({
- status: z.literal('running'),
+ status: z.literal('running').describe('Turn is still executing.'),
})
.openapi('TurnStateRunning');
@@ -33,41 +33,77 @@ export const TurnStateCancelledReasonSchema = z
/** Billable aggregate for one turn. */
export const TurnMetricsSchema = z
.object({
- total_input_tokens: z.number().int().nonnegative().optional(),
- total_output_tokens: z.number().int().nonnegative().optional(),
- total_tokens: z.number().int().nonnegative().optional(),
- total_cache_read_tokens: z.number().int().nonnegative().optional(),
- total_cache_write_tokens: z.number().int().nonnegative().optional(),
- total_reasoning_tokens: z.number().int().nonnegative().optional(),
- total_cost_in_usd: z.number().nonnegative().optional(),
+ total_input_tokens: z
+ .number()
+ .int()
+ .nonnegative()
+ .optional()
+ .describe('Total input tokens across model calls in this turn.'),
+ total_output_tokens: z
+ .number()
+ .int()
+ .nonnegative()
+ .optional()
+ .describe('Total output tokens across model calls in this turn.'),
+ total_tokens: z
+ .number()
+ .int()
+ .nonnegative()
+ .optional()
+ .describe('Total tokens (input + output) across model calls in this turn.'),
+ total_cache_read_tokens: z
+ .number()
+ .int()
+ .nonnegative()
+ .optional()
+ .describe('Total cache-read tokens across model calls in this turn.'),
+ total_cache_write_tokens: z
+ .number()
+ .int()
+ .nonnegative()
+ .optional()
+ .describe('Total cache-write tokens across model calls in this turn.'),
+ total_reasoning_tokens: z
+ .number()
+ .int()
+ .nonnegative()
+ .optional()
+ .describe('Total reasoning tokens across model calls in this turn.'),
+ total_cost_in_usd: z.number().nonnegative().optional().describe('Estimated total cost in USD for this turn.'),
})
.openapi('TurnMetrics');
export const TurnStateCancelledSchema = z
.object({
- status: z.literal('cancelled'),
+ status: z.literal('cancelled').describe('Turn was cancelled before completion.'),
reason: TurnStateCancelledReasonSchema,
- completed_at: z.string(),
- metrics: TurnMetricsSchema.optional(),
+ completed_at: z.string().describe('ISO 8601 time when cancellation completed.'),
+ metrics: TurnMetricsSchema.optional().describe('Optional billable aggregate for work done before cancel.'),
})
.openapi('TurnStateCancelled');
export const TurnStateErrorSchema = z
.object({
- status: z.literal('error'),
- message: z.string(),
- completed_at: z.string(),
- metrics: TurnMetricsSchema.optional(),
+ status: z.literal('error').describe('Turn ended with an error.'),
+ message: z.string().describe('Human-readable error message.'),
+ completed_at: z.string().describe('ISO 8601 time when the error state was recorded.'),
+ metrics: TurnMetricsSchema.optional().describe('Optional billable aggregate for work done before the error.'),
})
.openapi('TurnStateError');
export const TurnStateDoneSchema = z
.object({
- status: z.literal('done'),
- output: z.union([ModelMessageEventSchema, z.null()]),
- required_actions: z.array(ActionRequiredEventSchema),
- completed_at: z.string(),
- metrics: TurnMetricsSchema.optional(),
+ status: z.literal('done').describe('Turn finished (possibly paused for required actions).'),
+ output: z
+ .union([ModelMessageEventSchema, z.null()])
+ .describe('Final `model.message` for the turn, or null when the turn ended paused without a final message.'),
+ required_actions: z
+ .array(ActionRequiredEventSchema)
+ .describe(
+ 'Pending actions (`tool.approval_required`, `tool.response_required`, `mcp.auth_required`); empty when none.',
+ ),
+ completed_at: z.string().describe('ISO 8601 time when the turn reached a terminal state.'),
+ metrics: TurnMetricsSchema.optional().describe('Optional billable aggregate for the whole turn.'),
})
.openapi('TurnStateDone');
@@ -90,12 +126,12 @@ export const TurnInputItemSchema = z
export const TurnSchema = z
.object({
- id: z.string(),
- session_id: z.string(),
- previous_turn_id: z.string().nullable(),
- input: z.array(TurnInputItemSchema).optional(),
+ id: z.string().describe('Unique turn id.'),
+ session_id: z.string().describe('Session that owns this turn.'),
+ previous_turn_id: z.string().nullable().describe('Prior turn this turn chains from; null for a root turn.'),
+ input: z.array(TurnInputItemSchema).optional().describe('Input items supplied when the turn was created.'),
state: TurnStateSchema,
- created_at: z.string(),
+ created_at: z.string().describe('ISO 8601 creation timestamp.'),
})
.openapi('Turn');
@@ -105,7 +141,12 @@ export const TurnSchema = z
*/
export const CreateTurnRequestSchema = z
.object({
- input: z.array(TurnInputItemSchema).optional(),
+ input: z
+ .array(TurnInputItemSchema)
+ .optional()
+ .describe(
+ 'Turn input items: user messages and/or approval/tool-response resumes. Do not mix user messages with approval or tool-response items.',
+ ),
previous_turn_id: z
.union([z.literal('auto'), z.literal('none'), z.string().min(1)])
.optional()
diff --git a/packages/harness/src/core/events/schema.ts b/packages/harness/src/core/events/schema.ts
index 8347ba2ed..bdced8eda 100644
--- a/packages/harness/src/core/events/schema.ts
+++ b/packages/harness/src/core/events/schema.ts
@@ -44,29 +44,34 @@ export const EventType = {
} as const;
export const EventIdSchema = z.string().openapi({
- description: 'Unique identifier for the event',
+ description: 'Unique identifier for the event (monotonic ULID).',
});
export const AgentParentSchema = z
.object({
- thread_id: z.string(),
- tool_call_id: z.string(),
+ thread_id: z.string().describe('Parent thread that spawned the child agent.'),
+ tool_call_id: z.string().describe('Tool call on the parent thread that created the child.'),
})
.openapi('AgentParent');
export const AgentInfoSchema = z
.object({
- type: z.literal('dynamic'),
- name: z.string(),
- input: z.string(),
- model: z.string().min(1).optional(),
+ type: z.literal('dynamic').describe('Subagent kind.'),
+ name: z.string().describe('Display name of the dynamic subagent.'),
+ input: z.string().describe('Input prompt passed to the subagent.'),
+ model: z.string().min(1).optional().describe('Optional model override for the subagent.'),
})
.openapi('AgentInfo');
-export const AgentApprovalDecisionAllowSchema = z.object({ status: z.literal('allow') }).openapi('ApprovalAllow');
+export const AgentApprovalDecisionAllowSchema = z
+ .object({ status: z.literal('allow').describe('Allow the pending tool call(s).') })
+ .openapi('ApprovalAllow');
export const AgentApprovalDecisionDenySchema = z
- .object({ status: z.literal('deny'), reason: z.string().optional() })
+ .object({
+ status: z.literal('deny').describe('Deny the pending tool call(s).'),
+ reason: z.string().optional().describe('Optional reason shown to the agent when denied.'),
+ })
.openapi('ApprovalDeny');
export const ApprovalDecisionSchema = z
@@ -75,34 +80,34 @@ export const ApprovalDecisionSchema = z
export const UserToolApprovalMessageSchema = z
.object({
- type: z.literal(EventType.USER_TOOL_APPROVAL),
- thread_id: z.string().min(1, 'thread_id is required'),
- tool_call_id: z.string().min(1, 'tool_call_id is required'),
+ type: z.literal(EventType.USER_TOOL_APPROVAL).describe('Client resume after tool.approval_required.'),
+ thread_id: z.string().min(1, 'thread_id is required').describe('Thread that owns the pending tool call.'),
+ tool_call_id: z.string().min(1, 'tool_call_id is required').describe('Tool call id being approved or denied.'),
approval: ApprovalDecisionSchema,
})
.openapi('UserToolApprovalEvent');
export const UserToolResponseMessageSchema = z
.object({
- type: z.literal(EventType.USER_TOOL_RESPONSE),
- thread_id: z.string().min(1, 'thread_id is required'),
- tool_call_id: z.string().min(1, 'tool_call_id is required'),
- content: z.string().min(1, 'content cannot be empty'),
+ type: z.literal(EventType.USER_TOOL_RESPONSE).describe('Client resume after tool.response_required.'),
+ thread_id: z.string().min(1, 'thread_id is required').describe('Thread that owns the pending tool call.'),
+ tool_call_id: z.string().min(1, 'tool_call_id is required').describe('Tool call id receiving the client response.'),
+ content: z.string().min(1, 'content cannot be empty').describe('Client-side tool result content.'),
})
.openapi('UserToolResponseEvent');
export const TextContentPartSchema = z
.object({
- type: z.literal('text'),
- text: z.string(),
+ type: z.literal('text').describe('Text content part.'),
+ text: z.string().describe('Plain-text content.'),
})
.openapi('TextContent');
export type TextContentPart = z.infer<typeof TextContentPartSchema>;
export const FileContentPartSchema = z
.object({
- type: z.literal('file'),
- name: z.string(),
+ type: z.literal('file').describe('File attachment content part.'),
+ name: z.string().describe('Filename presented to the agent.'),
data: z.string().describe('Data URI: `data:<mime>;base64,<payload>`. MIME type is parsed from the URI.'),
})
.openapi('FileContent');
@@ -115,8 +120,10 @@ export type UserContentPart = z.infer<typeof UserContentPartSchema>;
export const AgentInputUserMessageSchema = z
.object({
- type: z.literal(EventType.USER_MESSAGE),
- content: z.union([z.string(), z.array(UserContentPartSchema)]),
+ type: z.literal(EventType.USER_MESSAGE).describe('User message input item.'),
+ content: z
+ .union([z.string(), z.array(UserContentPartSchema)])
+ .describe('Plain string or structured text/file content parts.'),
})
.openapi('UserMessage');
export type AgentInputUserMessage = z.infer<typeof AgentInputUserMessageSchema>;
@@ -127,30 +134,33 @@ export const AgentApprovalDecisionMessageSchema = UserToolApprovalMessageSchema.
});
export const InputTokensBreakdownSchema = z.object({
- harness: z.number().int().nonnegative(),
- skills: z.number().int().nonnegative(),
- instructions: z.number().int().nonnegative(),
- tool_definitions: z.number().int().nonnegative(),
- messages: z.number().int().nonnegative(),
+ harness: z.number().int().nonnegative().describe('Tokens attributed to harness system framing.'),
+ skills: z.number().int().nonnegative().describe('Tokens attributed to skill instructions.'),
+ instructions: z.number().int().nonnegative().describe('Tokens attributed to agent instructions.'),
+ tool_definitions: z.number().int().nonnegative().describe('Tokens attributed to tool schemas.'),
+ messages: z.number().int().nonnegative().describe('Tokens attributed to conversation messages.'),
});
export const ModelMessageUsageSchema = z
.object({
- input_tokens: z.number().int().nonnegative(),
- output_tokens: z.number().int().nonnegative(),
- cache_read_tokens: z.number().int().nonnegative().optional(),
- cache_write_tokens: z.number().int().nonnegative().optional(),
+ input_tokens: z.number().int().nonnegative().describe('Input tokens for this model call.'),
+ output_tokens: z.number().int().nonnegative().describe('Output tokens for this model call.'),
+ cache_read_tokens: z.number().int().nonnegative().optional().describe('Optional cache-read tokens.'),
+ cache_write_tokens: z.number().int().nonnegative().optional().describe('Optional cache-write tokens.'),
input_tokens_breakdown: InputTokensBreakdownSchema,
})
.openapi('ModelMessageUsage');
export const ModelMessageEventSchema = EnrichedAssistantMessageSchema.omit({ role: true })
.extend({
- type: z.literal(EventType.MODEL_MESSAGE),
+ type: z.literal(EventType.MODEL_MESSAGE).describe('Complete assistant model message.'),
id: EventIdSchema,
- thread_id: z.string(),
- finish_reason: z.union([FinishReasonSchema, z.null()]).optional(),
- created_at: z.string(),
+ thread_id: z.string().describe('Thread that emitted this message (`main` for the root agent).'),
+ finish_reason: z
+ .union([FinishReasonSchema, z.null()])
+ .optional()
+ .describe('Model finish reason; null when the provider omitted it.'),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
usage: ModelMessageUsageSchema.optional(),
})
.openapi('ModelMessageEvent');
@@ -161,47 +171,50 @@ export const ModelMessageDeltaEventSchema = ExtendedChunkDeltaSchema.omit({
thinking_blocks: true,
})
.extend({
- type: z.literal(EventType.MODEL_MESSAGE_DELTA),
+ type: z.literal(EventType.MODEL_MESSAGE_DELTA).describe('Streaming delta for a model.message.'),
id: EventIdSchema,
- thread_id: z.string(),
- created_at: z.string().optional(),
- finish_reason: z.union([FinishReasonSchema, z.null()]).optional(),
+ thread_id: z.string().describe('Thread that emitted this delta.'),
+ created_at: z.string().optional().describe('Optional ISO 8601 event timestamp.'),
+ finish_reason: z
+ .union([FinishReasonSchema, z.null()])
+ .optional()
+ .describe('Finish reason when this delta completes the stream.'),
usage: ModelMessageUsageSchema.optional(),
})
.openapi('ModelMessageDeltaEvent');
export const ToolResponseEventSchema = LLMToolMessageSchema.omit({ role: true })
.extend({
- type: z.literal(EventType.TOOL_RESPONSE),
+ type: z.literal(EventType.TOOL_RESPONSE).describe('Result of a tool execution.'),
id: EventIdSchema,
- thread_id: z.string(),
- created_at: z.string(),
+ thread_id: z.string().describe('Thread that owns the tool call.'),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
})
.openapi('ToolResponseEvent');
export const ThreadCreatedEventSchema = z
.object({
- type: z.literal(EventType.THREAD_CREATED),
+ type: z.literal(EventType.THREAD_CREATED).describe('A dynamic subagent thread was created.'),
id: EventIdSchema,
agent_info: AgentInfoSchema,
- created_at: z.string(),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
parent: AgentParentSchema,
- thread_id: z.string(),
- title: z.string(),
+ thread_id: z.string().describe('Id of the new thread.'),
+ title: z.string().describe('Human-readable thread title.'),
})
.openapi('ThreadCreatedEvent');
export const ThreadStateDoneSchema = z
.object({
- status: z.literal('done'),
+ status: z.literal('done').describe('Thread completed successfully.'),
output: ModelMessageEventSchema,
})
.openapi('ThreadStateDone');
export const ThreadStateErrorSchema = z
.object({
- status: z.literal('error'),
- error: z.string(),
+ status: z.literal('error').describe('Thread ended with an error.'),
+ error: z.string().describe('Human-readable error message.'),
output: ModelMessageEventSchema.optional(),
})
.openapi('ThreadStateError');
@@ -213,15 +226,15 @@ export const ThreadStateSchema = z
export const BaseThreadDoneEventSchema = z
.object({
parent: AgentParentSchema.optional(),
- thread_id: z.string(),
- title: z.string(),
+ thread_id: z.string().describe('Thread that finished.'),
+ title: z.string().describe('Human-readable thread title.'),
})
.openapi('BaseThreadDoneEvent');
export const ThreadDoneEventSchema = BaseThreadDoneEventSchema.extend({
- type: z.literal(EventType.THREAD_DONE),
+ type: z.literal(EventType.THREAD_DONE).describe('A thread reached a terminal state.'),
id: EventIdSchema,
- created_at: z.string(),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
state: ThreadStateSchema,
}).openapi('ThreadDoneEvent');
@@ -251,81 +264,86 @@ export const ThreadOverwriteContextEventSchema = z.object({
export const MCPServerAuthInfoSchema = z
.object({
- id: z.string(),
- name: z.string(),
- auth_url: z.string(),
+ id: z.string().describe('Internal MCP server id.'),
+ name: z.string().describe('Configured MCP server name.'),
+ auth_url: z.string().describe('URL the user must visit to complete OAuth for this server.'),
})
.openapi('MCPServerAuthInfo');
export const BaseMCPAuthRequiredEventSchema = z
.object({
id: EventIdSchema,
- created_at: z.string(),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
// This is a run-level event, not tied to a single thread.
- thread_id: z.string().nullable(),
+ thread_id: z.string().nullable().describe('Always null — this is a run-level event.'),
})
.openapi('BaseMCPAuthRequiredEvent');
export const MCPAuthRequiredEventSchema = BaseMCPAuthRequiredEventSchema.extend({
- type: z.literal(EventType.MCP_AUTH_REQUIRED),
- mcp_servers: z.array(MCPServerAuthInfoSchema),
+ type: z.literal(EventType.MCP_AUTH_REQUIRED).describe('One or more MCP servers need OAuth before tools can run.'),
+ mcp_servers: z.array(MCPServerAuthInfoSchema).describe('Servers that need authorization, each with an auth_url.'),
}).openapi('MCPAuthRequiredEvent');
export const MCPServerInitInfoSchema = z
.object({
- id: z.string(),
- name: z.string(),
- session_id: z.string().optional(),
- transport_type: z.enum(['streamable-http', 'sse']).optional(),
+ id: z.string().describe('Internal MCP server id.'),
+ name: z.string().describe('Configured MCP server name.'),
+ session_id: z.string().optional().describe('Optional MCP session id from the transport.'),
+ transport_type: z
+ .enum(['streamable-http', 'sse'])
+ .optional()
+ .describe('Transport used to connect to the MCP server.'),
})
.openapi('MCPServerInitInfo');
export const MCPInitializeEventSchema = z
.object({
- type: z.literal(EventType.MCP_INITIALIZE),
+ type: z.literal(EventType.MCP_INITIALIZE).describe('MCP server(s) initialized for this turn.'),
id: EventIdSchema,
- created_at: z.string(),
- thread_id: z.string(),
- mcp_servers: z.array(MCPServerInitInfoSchema),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
+ thread_id: z.string().describe('Thread that triggered initialization.'),
+ mcp_servers: z.array(MCPServerInitInfoSchema).describe('Servers that were initialized.'),
})
.openapi('MCPInitializeEvent');
export const SandboxCreatedEventSchema = z
.object({
- type: z.literal(EventType.SANDBOX_CREATED),
+ type: z.literal(EventType.SANDBOX_CREATED).describe('A sandbox was created for this session.'),
id: EventIdSchema,
- created_at: z.string(),
- sandbox_id: z.string(),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
+ sandbox_id: z.string().describe('Provider sandbox id.'),
// This is a run-level event, sandbox once created is reused by all threads,
// and future turns as well.
- thread_id: z.string().nullable(),
+ thread_id: z.string().nullable().describe('Always null — sandbox is session-scoped.'),
})
.openapi('SandboxCreatedEvent');
export const ToolCallRefSchema = z
.object({
- id: z.string(),
- source_event_id: z.string(),
+ id: z.string().describe('Tool call id awaiting action.'),
+ source_event_id: z.string().describe('Event id of the model.message that requested the tool call.'),
})
.openapi('ToolCallRef');
export const ToolApprovalRequiredEventSchema = z
.object({
- type: z.literal(EventType.TOOL_APPROVAL_REQUIRED),
+ type: z.literal(EventType.TOOL_APPROVAL_REQUIRED).describe('One or more tool calls need human approval.'),
id: EventIdSchema,
- created_at: z.string(),
- thread_id: z.string(),
- tool_calls: z.array(ToolCallRefSchema),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
+ thread_id: z.string().describe('Thread that owns the pending tool calls.'),
+ tool_calls: z.array(ToolCallRefSchema).describe('Tool calls waiting for approval.'),
})
.openapi('ToolApprovalRequiredEvent');
export const ToolResponseRequiredEventSchema = z
.object({
- type: z.literal(EventType.TOOL_RESPONSE_REQUIRED),
+ type: z
+ .literal(EventType.TOOL_RESPONSE_REQUIRED)
+ .describe('One or more client-side tool calls need a user/tool response.'),
id: EventIdSchema,
- created_at: z.string(),
- thread_id: z.string(),
- tool_calls: z.array(ToolCallRefSchema),
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
+ thread_id: z.string().describe('Thread that owns the pending tool calls.'),
+ tool_calls: z.array(ToolCallRefSchema).describe('Tool calls waiting for a client response.'),
})
.openapi('ToolResponseRequiredEvent');
diff --git a/packages/harness/src/core/llm/LLMTypes.ts b/packages/harness/src/core/llm/LLMTypes.ts
index f77a37266..790a488c9 100644
--- a/packages/harness/src/core/llm/LLMTypes.ts
+++ b/packages/harness/src/core/llm/LLMTypes.ts
@@ -19,46 +19,46 @@ import {
export const ThinkingBlockSchema = z
.object({
- type: z.literal('thinking'),
- thinking: z.string(),
- signature: z.string().optional(),
+ type: z.literal('thinking').describe('Structured thinking block.'),
+ thinking: z.string().describe('Thinking text content.'),
+ signature: z.string().optional().describe('Optional provider signature for multi-turn replay.'),
})
.openapi('ThinkingBlock');
export const RedactedThinkingBlockSchema = z
.object({
- type: z.literal('redacted_thinking'),
- data: z.string(),
+ type: z.literal('redacted_thinking').describe('Redacted thinking block.'),
+ data: z.string().describe('Opaque redacted thinking payload from the provider.'),
})
.openapi('RedactedThinkingBlock');
export const ThinkingBlockUnionSchema = z.union([ThinkingBlockSchema, RedactedThinkingBlockSchema]);
export const InternalToolCallInfoSchema = z.object({
- type: z.enum(['truefoundry-system', 'mcp']),
- mcp_server_id: z.string(),
- mcp_server_name: z.string(),
- original_tool_name: z.string(),
- is_approval_required: z.boolean().optional(),
- is_deferred: z.boolean().optional(),
- is_client_side: z.boolean().optional(),
+ type: z.enum(['truefoundry-system', 'mcp']).describe('Whether the tool is a system tool or MCP tool.'),
+ mcp_server_id: z.string().describe('Internal MCP server id (empty for system tools).'),
+ mcp_server_name: z.string().describe('Configured MCP server name (empty for system tools).'),
+ original_tool_name: z.string().describe('Original tool name before any remapping.'),
+ is_approval_required: z.boolean().optional().describe('Whether this tool call requires human approval.'),
+ is_deferred: z.boolean().optional().describe('Whether the tool was loaded via deferred discovery.'),
+ is_client_side: z.boolean().optional().describe('Whether the client must supply the tool result.'),
// Runtime + wire: deviation from origin/main OpenAPI (which omitted this field) is accepted.
- is_thread_creation: z.boolean().optional(),
+ is_thread_creation: z.boolean().optional().describe('Whether this tool call creates a subagent thread.'),
});
export const TrueFoundrySystemToolInfoSchema = z
.object({
- type: z.literal('truefoundry-system'),
- name: z.string(),
+ type: z.literal('truefoundry-system').describe('Built-in harness system tool.'),
+ name: z.string().describe('System tool name.'),
})
.openapi('TrueFoundrySystemToolInfo');
export const MCPToolInfoSchema = z
.object({
- type: z.literal('mcp'),
- server_id: z.string(),
- server_name: z.string(),
- name: z.string(),
+ type: z.literal('mcp').describe('Tool hosted on an MCP server.'),
+ server_id: z.string().describe('Internal MCP server id.'),
+ server_name: z.string().describe('Configured MCP server name.'),
+ name: z.string().describe('Tool name on the MCP server.'),
})
.openapi('MCPToolInfo');
@@ -136,13 +136,13 @@ export const LLMToolMessageSchema = ChatCompletionToolMessageParamSchema.omit({
export const CompletionUsageSchema = z
.object({
- input_tokens: z.number().int().nonnegative(),
- output_tokens: z.number().int().nonnegative(),
- total_tokens: z.number().int().nonnegative(),
- cache_read_tokens: z.number().int().nonnegative().optional(),
- cache_write_tokens: z.number().int().nonnegative().optional(),
- reasoning_tokens: z.number().int().nonnegative().optional(),
- cost_in_usd: z.number().nonnegative().optional(),
+ input_tokens: z.number().int().nonnegative().describe('Input tokens for this completion.'),
+ output_tokens: z.number().int().nonnegative().describe('Output tokens for this completion.'),
+ total_tokens: z.number().int().nonnegative().describe('Total tokens (input + output).'),
+ cache_read_tokens: z.number().int().nonnegative().optional().describe('Optional cache-read tokens.'),
+ cache_write_tokens: z.number().int().nonnegative().optional().describe('Optional cache-write tokens.'),
+ reasoning_tokens: z.number().int().nonnegative().optional().describe('Optional reasoning tokens.'),
+ cost_in_usd: z.number().nonnegative().optional().describe('Optional estimated cost in USD.'),
})
.openapi('CompletionUsage');
diff --git a/packages/harness/src/core/llm/openaiSchemas.ts b/packages/harness/src/core/llm/openaiSchemas.ts
index 72f7218fa..c21f50991 100644
--- a/packages/harness/src/core/llm/openaiSchemas.ts
+++ b/packages/harness/src/core/llm/openaiSchemas.ts
@@ -6,45 +6,45 @@ import { z } from '@hono/zod-openapi';
export const ChatCompletionContentPartTextSchema = z
.object({
- type: z.literal('text'),
- text: z.string(),
+ type: z.literal('text').describe('Text content part.'),
+ text: z.string().describe('Plain-text content.'),
})
.openapi('ChatCompletionContentPartText');
export const ChatCompletionContentPartRefusalSchema = z
.object({
- type: z.literal('refusal'),
- refusal: z.string(),
+ type: z.literal('refusal').describe('Model refusal content part.'),
+ refusal: z.string().describe('Refusal message text.'),
})
.openapi('ChatCompletionContentPartRefusal');
export const ChatCompletionContentPartImageSchema = z
.object({
- type: z.literal('image_url'),
+ type: z.literal('image_url').describe('Image URL content part.'),
image_url: z.object({
- url: z.string(),
- detail: z.enum(['auto', 'low', 'high']).optional(),
+ url: z.string().describe('Image URL or data URI.'),
+ detail: z.enum(['auto', 'low', 'high']).optional().describe('Optional image detail level.'),
}),
})
.openapi('ChatCompletionContentPartImage');
export const ChatCompletionContentPartInputAudioSchema = z
.object({
- type: z.literal('input_audio'),
+ type: z.literal('input_audio').describe('Input audio content part.'),
input_audio: z.object({
- data: z.string(),
- format: z.enum(['wav', 'mp3']),
+ data: z.string().describe('Base64-encoded audio data.'),
+ format: z.enum(['wav', 'mp3']).describe('Audio encoding format.'),
}),
})
.openapi('ChatCompletionContentPartInputAudio');
export const ChatCompletionContentPartFileSchema = z
.object({
- type: z.literal('file'),
+ type: z.literal('file').describe('File content part.'),
file: z.object({
- file_data: z.string().optional(),
- file_id: z.string().optional(),
- filename: z.string().optional(),
+ file_data: z.string().optional().describe('Optional base64 file payload.'),
+ file_id: z.string().optional().describe('Optional provider file id.'),
+ filename: z.string().optional().describe('Optional filename.'),
}),
})
.openapi('ChatCompletionContentPartFile');
@@ -59,24 +59,24 @@ export const ChatCompletionContentPartSchema = z.union([
export const ChatCompletionMessageToolCallSchema = z
.object({
- id: z.string(),
- type: z.literal('function'),
+ id: z.string().describe('Tool call id.'),
+ type: z.literal('function').describe('Tool call type.'),
function: z.object({
- name: z.string(),
- arguments: z.string(),
+ name: z.string().describe('Function/tool name.'),
+ arguments: z.string().describe('JSON-encoded function arguments string.'),
}),
})
.openapi('ChatCompletionMessageToolCall');
export const ChatCompletionChunkDeltaToolCallSchema = z
.object({
- index: z.number().int().nonnegative(),
- id: z.string().optional(),
- type: z.literal('function').optional(),
+ index: z.number().int().nonnegative().describe('Index of this tool call in the streaming delta array.'),
+ id: z.string().optional().describe('Tool call id (may arrive across multiple deltas).'),
+ type: z.literal('function').optional().describe('Tool call type when present on this delta.'),
function: z
.object({
- name: z.string().optional(),
- arguments: z.string().optional(),
+ name: z.string().optional().describe('Partial or complete function name.'),
+ arguments: z.string().optional().describe('Partial or complete JSON arguments string.'),
})
.optional(),
})
@@ -84,60 +84,73 @@ export const ChatCompletionChunkDeltaToolCallSchema = z
export const ChatCompletionChunkDeltaSchema = z
.object({
- content: z.string().nullable().optional(),
- refusal: z.string().nullable().optional(),
- role: z.enum(['developer', 'system', 'user', 'assistant', 'tool']).optional(),
+ content: z.string().nullable().optional().describe('Incremental assistant text content.'),
+ refusal: z.string().nullable().optional().describe('Incremental refusal text when present.'),
+ role: z
+ .enum(['developer', 'system', 'user', 'assistant', 'tool'])
+ .optional()
+ .describe('Role when set on the delta.'),
function_call: z
.object({
- name: z.string().optional(),
- arguments: z.string().optional(),
+ name: z.string().optional().describe('Legacy function-call name fragment.'),
+ arguments: z.string().optional().describe('Legacy function-call arguments fragment.'),
})
.optional(),
- tool_calls: z.array(ChatCompletionChunkDeltaToolCallSchema).optional(),
+ tool_calls: z.array(ChatCompletionChunkDeltaToolCallSchema).optional().describe('Incremental tool-call deltas.'),
})
.openapi('ChatCompletionChunkDelta');
export const ChatCompletionAssistantMessageParamSchema = z
.object({
- role: z.literal('assistant'),
- audio: z.object({ id: z.string() }).nullable().optional(),
+ role: z.literal('assistant').describe('Assistant message role.'),
+ audio: z
+ .object({ id: z.string().describe('Provider audio id.') })
+ .nullable()
+ .optional(),
content: z
.union([
z.string(),
z.array(z.union([ChatCompletionContentPartTextSchema, ChatCompletionContentPartRefusalSchema])),
])
.nullable()
- .optional(),
+ .optional()
+ .describe('Assistant message content as text or content parts.'),
function_call: z
.object({
- name: z.string(),
- arguments: z.string(),
+ name: z.string().describe('Legacy function name.'),
+ arguments: z.string().describe('Legacy function arguments JSON string.'),
})
.nullable()
.optional(),
- name: z.string().optional(),
- refusal: z.string().nullable().optional(),
- tool_calls: z.array(ChatCompletionMessageToolCallSchema).optional(),
+ name: z.string().optional().describe('Optional participant name.'),
+ refusal: z.string().nullable().optional().describe('Optional refusal text.'),
+ tool_calls: z
+ .array(ChatCompletionMessageToolCallSchema)
+ .optional()
+ .describe('Tool calls requested by the assistant.'),
})
.openapi('ChatCompletionAssistantMessageParam');
// `content` is wider here than in our pipeline; `LLMToolMessageSchema` narrows it to string.
export const ChatCompletionToolMessageParamSchema = z
.object({
- role: z.literal('tool'),
- tool_call_id: z.string(),
- content: z.union([z.string(), z.array(ChatCompletionContentPartTextSchema)]),
+ role: z.literal('tool').describe('Tool message role.'),
+ tool_call_id: z.string().describe('Id of the tool call this message responds to.'),
+ content: z.union([z.string(), z.array(ChatCompletionContentPartTextSchema)]).describe('Tool result content.'),
})
.openapi('ChatCompletionToolMessageParam');
export const ChatCompletionUserMessageParamSchema = z
.object({
- role: z.literal('user'),
- content: z.union([z.string(), z.array(ChatCompletionContentPartSchema)]),
- name: z.string().optional(),
+ role: z.literal('user').describe('User message role.'),
+ content: z
+ .union([z.string(), z.array(ChatCompletionContentPartSchema)])
+ .describe('User message content as text or content parts.'),
+ name: z.string().optional().describe('Optional participant name.'),
})
.openapi('ChatCompletionUserMessageParam');
export const ChatCompletionChunkFinishReasonSchema = z
.enum(['stop', 'length', 'tool_calls', 'content_filter', 'function_call'])
+ .describe('Why the model stopped generating.')
.openapi('ChatCompletionChunkFinishReason');
diff --git a/packages/harness/src/core/llm/responseFormat.ts b/packages/harness/src/core/llm/responseFormat.ts
index a808b2d94..0e06b89ac 100644
--- a/packages/harness/src/core/llm/responseFormat.ts
+++ b/packages/harness/src/core/llm/responseFormat.ts
@@ -8,26 +8,34 @@ import type { ChatCompletionCreateParamsStreaming } from 'openai/resources/chat'
*/
const ResponseFormatTextSchema = z
- .object({ type: z.literal('text') })
+ .object({ type: z.literal('text').describe('Unconstrained text output.') })
.loose()
+ .describe('Default text response format. Extra provider fields are allowed.')
.openapi('ResponseFormatText');
const ResponseFormatJsonObjectSchema = z
- .object({ type: z.literal('json_object') })
+ .object({ type: z.literal('json_object').describe('Model must return a JSON object.') })
.loose()
+ .describe('JSON object response format. Extra provider fields are allowed.')
.openapi('ResponseFormatJsonObject');
const ResponseFormatJsonSchemaSchema = z
.object({
- type: z.literal('json_schema'),
+ type: z.literal('json_schema').describe('Model must return JSON matching a schema.'),
json_schema: z
.object({
- name: z.string(),
- description: z.string().optional(),
- schema: z.record(z.string(), z.unknown()).optional(),
- strict: z.boolean().nullable().optional(),
+ name: z.string().describe('Schema name sent to the provider.'),
+ description: z.string().optional().describe('Optional schema description for the model.'),
+ schema: z.record(z.string(), z.unknown()).optional().describe('JSON Schema object for the response.'),
+ strict: z
+ .boolean()
+ .nullable()
+ .optional()
+ .describe('When true, ask the provider to enforce the schema strictly.'),
})
- .loose(),
+ .loose()
+ .describe('JSON Schema payload. Extra provider fields are allowed.'),
})
.loose()
+ .describe('JSON Schema response format. Extra provider fields are allowed.')
.openapi('ResponseFormatJsonSchema');
export const ResponseFormatSchema = z
diff --git a/packages/harness/src/core/runtime/contextUsage.ts b/packages/harness/src/core/runtime/contextUsage.ts
index c8ac3390d..94a4bdd1f 100644
--- a/packages/harness/src/core/runtime/contextUsage.ts
+++ b/packages/harness/src/core/runtime/contextUsage.ts
@@ -8,8 +8,12 @@ import type { CompletionUsage } from '../llm/LLMTypes';
*/
export const CurrentContextUsageSchema = z
.object({
- prompt_tokens: z.number().int().nonnegative(),
- completion_tokens: z.number().int().nonnegative(),
+ prompt_tokens: z.number().int().nonnegative().describe('Live prompt-side context tokens for the next LLM call.'),
+ completion_tokens: z
+ .number()
+ .int()
+ .nonnegative()
+ .describe('Live completion-side context tokens for the next LLM call.'),
})
.openapi('CurrentContextUsage');
diff --git a/packages/sdk/.fern/metadata.json b/packages/sdk/.fern/metadata.json
index d6db0214b..bba644e85 100644
--- a/packages/sdk/.fern/metadata.json
+++ b/packages/sdk/.fern/metadata.json
@@ -27,8 +27,8 @@
"streamType": "web",
"useDefaultRequestParameterValues": true
},
- "originGitCommit": "60032ffbb02cf4a302dfaadcd1b27ee63115db92",
- "originGitCommitIsDirty": false,
+ "originGitCommit": "838559689e9ff839ee2524c696c240a68c4d3378",
+ "originGitCommitIsDirty": true,
"invokedBy": "ci",
"requestedVersion": "0.0.0",
"ciProvider": "github",
diff --git a/packages/sdk/pnpm-lock.yaml b/packages/sdk/pnpm-lock.yaml
index c254ec3d8..1e59d4181 100644
--- a/packages/sdk/pnpm-lock.yaml
+++ b/packages/sdk/pnpm-lock.yaml
@@ -392,13 +392,13 @@ packages:
resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
engines: {node: '>=12'}
- resolution: {integrity: sha512-r7WnVImvVCeFpf2DOXfy41aPWzeNg3H/A2X4dKmy1QL0MSyyk/e7z8ihJ3N6Nn2PsdhkVlqnEfnUE4a05P2aTA==}
+ resolution: {integrity: sha512-k9HNuUVMlqVjQ9UHzfPjIqiDbWw7WqT1AoT7GL8VwvF3r0ZfArtgiSPAlmupyNquNgOJHTuH4CKYf8ttMTWBTQ==}
engines: {node: '>=6.0.0'}
hasBin: true
- resolution: {integrity: sha512-JxV13hNrFxqjOc8alRbq9dK1MM79NEXYpma2B2J4wAtpWS5zIEIKqWPGCl7N4o7Uc7B7itylh7SuDujATRyyTw==}
+ resolution: {integrity: sha512-V2NpofLblG64mfOtSgDhOJESZEGogzDMBv/q+W6oc4LXWP/q75eOXoOaaOu1EOadB9U4Bwx/e0yzbvwKH8zalA==}
engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
hasBin: true
@@ -449,8 +449,8 @@ packages:
resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
engines: {node: '>=8'}
- resolution: {integrity: sha512-/oOpMaPT6Yg+6/1XQhyIPlzgj7Ye9zf+nNM2Uh6OcE2G2oNptWazFa+qB2Pdqqbsc9KnIDzgAntoYN0dbwOXwA==}
+ resolution: {integrity: sha512-MQsYmdaLzvaCX5j+ZZBr5Fm6uCCnPQcRtlvmvRlWqrXy+BH2O4ffXIAScF+JQznQWB9brWp4lSD9Z4yNmaf2BA==}
resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
@@ -1313,15 +1313,15 @@ snapshots:
dependencies:
- baseline-browser-mapping: 2.11.12
+ baseline-browser-mapping: 2.11.13
caniuse-lite: 1.0.30001809
- electron-to-chromium: 1.5.402
+ electron-to-chromium: 1.5.403
node-releases: 2.0.53
- update-browserslist-db: 1.3.0([email protected])
+ update-browserslist-db: 1.3.0([email protected])
@@ -1358,7 +1358,7 @@ snapshots:
@@ -1660,9 +1660,9 @@ snapshots:
dependencies:
- browserslist: 4.28.7
+ browserslist: 4.28.8
escalade: 3.2.0
picocolors: 1.1.1
@@ -1719,7 +1719,7 @@ snapshots:
'@webassemblyjs/wasm-edit': 1.14.1
'@webassemblyjs/wasm-parser': 1.14.1
acorn: 8.18.0
- browserslist: 4.28.7
+ browserslist: 4.28.8
chrome-trace-event: 1.0.4
enhanced-resolve: 5.24.5
es-module-lexer: 2.3.1
diff --git a/packages/sdk/src/api/errors/UnauthorizedError.ts b/packages/sdk/src/api/errors/UnauthorizedError.ts
index e17ea94be..6180fba73 100644
--- a/packages/sdk/src/api/errors/UnauthorizedError.ts
+++ b/packages/sdk/src/api/errors/UnauthorizedError.ts
@@ -2,9 +2,12 @@
import type * as core from "../../core/index.js";
import * as errors from "../../errors/index.js";
+import type * as TrueForge from "../index.js";
export class UnauthorizedError extends errors.TrueForgeError {
- constructor(body?: unknown, rawResponse?: core.RawResponse) {
+ public declare readonly body: TrueForge.RequestErrorResponse;
+
+ constructor(body: TrueForge.RequestErrorResponse, rawResponse?: core.RawResponse) {
super({
message: "UnauthorizedError",
statusCode: 401,
diff --git a/packages/sdk/src/api/resources/agents/client/Client.ts b/packages/sdk/src/api/resources/agents/client/Client.ts
index d6793dc21..1bc84ca96 100644
--- a/packages/sdk/src/api/resources/agents/client/Client.ts
+++ b/packages/sdk/src/api/resources/agents/client/Client.ts
@@ -28,6 +28,7 @@ export class AgentsClient {
*
* @param {AgentsClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -71,11 +72,25 @@ export class AgentsClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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, "GET", "/api/v1/agents");
@@ -283,6 +298,7 @@ export class AgentsClient {
* @param {string} agent_id - Immutable agent identifier.
* @param {AgentsClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -318,11 +334,25 @@ export class AgentsClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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, "DELETE", "/api/v1/agents/{agent_id}");
diff --git a/packages/sdk/src/api/resources/agents/client/requests/UpdateAgentRequest.ts b/packages/sdk/src/api/resources/agents/client/requests/UpdateAgentRequest.ts
index 3e3e1408c..68c1dbb37 100644
--- a/packages/sdk/src/api/resources/agents/client/requests/UpdateAgentRequest.ts
+++ b/packages/sdk/src/api/resources/agents/client/requests/UpdateAgentRequest.ts
@@ -12,11 +12,16 @@ import type * as TrueForge from "../../../../index.js";
*/
export interface UpdateAgentRequest {
config?: TrueForge.RuntimeConfig;
+ /** Optional system prompt — the agent's role, behavior, and constraints. */
instructions?: string;
+ /** Optional MCP servers attached by configured name. */
mcpServers?: TrueForge.McpServer[];
+ /** Optional seed user messages injected at the start of every session. */
messages?: TrueForge.AgentSpecUserMessage[];
model: TrueForge.AgentSpecModel;
responseFormat?: TrueForge.ResponseFormat;
+ /** Optional name-only skill references. Requires `config.sandbox.enabled: true`. */
skills?: TrueForge.SkillNameRef[];
+ /** Optional string key–value map reserved for parameterizing agent definitions. */
variables?: Record<string, string>;
}
diff --git a/packages/sdk/src/api/resources/auth/client/Client.ts b/packages/sdk/src/api/resources/auth/client/Client.ts
index 9ac2b4478..59dbccdbd 100644
--- a/packages/sdk/src/api/resources/auth/client/Client.ts
+++ b/packages/sdk/src/api/resources/auth/client/Client.ts
@@ -120,7 +120,16 @@ export class AuthClient {
if (_response.error.reason === "status-code") {
switch (_response.error.statusCode) {
case 401:
- throw new TrueForge.UnauthorizedError(_response.error.body, _response.rawResponse);
+ throw new TrueForge.UnauthorizedError(
+ 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,
diff --git a/packages/sdk/src/api/resources/mcpServers/client/Client.ts b/packages/sdk/src/api/resources/mcpServers/client/Client.ts
index fa1bddcee..5e64836eb 100644
--- a/packages/sdk/src/api/resources/mcpServers/client/Client.ts
+++ b/packages/sdk/src/api/resources/mcpServers/client/Client.ts
@@ -27,6 +27,7 @@ export class McpServersClient {
*
* @param {McpServersClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -72,11 +73,25 @@ export class McpServersClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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, "GET", "/api/v1/mcp-servers");
diff --git a/packages/sdk/src/api/resources/models/client/Client.ts b/packages/sdk/src/api/resources/models/client/Client.ts
index 1459cda1d..3598c4f7e 100644
--- a/packages/sdk/src/api/resources/models/client/Client.ts
+++ b/packages/sdk/src/api/resources/models/client/Client.ts
@@ -7,7 +7,7 @@ import * as core from "../../../../core/index.js";
import { handleNonStatusCodeError } from "../../../../errors/handleNonStatusCodeError.js";
import * as errors from "../../../../errors/index.js";
import * as serializers from "../../../../serialization/index.js";
-import type * as TrueForge from "../../../index.js";
+import * as TrueForge from "../../../index.js";
export declare namespace ModelsClient {
export type Options = BaseClientOptions;
@@ -27,6 +27,7 @@ export class ModelsClient {
*
* @param {ModelsClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -70,11 +71,25 @@ export class ModelsClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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, "GET", "/api/v1/models");
diff --git a/packages/sdk/src/api/resources/server/client/Client.ts b/packages/sdk/src/api/resources/server/client/Client.ts
index f4d237f15..8553b3fed 100644
--- a/packages/sdk/src/api/resources/server/client/Client.ts
+++ b/packages/sdk/src/api/resources/server/client/Client.ts
@@ -7,7 +7,7 @@ import * as core from "../../../../core/index.js";
import { handleNonStatusCodeError } from "../../../../errors/handleNonStatusCodeError.js";
import * as errors from "../../../../errors/index.js";
import * as serializers from "../../../../serialization/index.js";
-import type * as TrueForge from "../../../index.js";
+import * as TrueForge from "../../../index.js";
export declare namespace ServerClient {
export type Options = BaseClientOptions;
@@ -27,6 +27,7 @@ export class ServerClient {
*
* @param {ServerClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -72,11 +73,25 @@ export class ServerClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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, "GET", "/api/v1/capabilities");
diff --git a/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsRequest.ts b/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsRequest.ts
index 34c375525..8d13bdf06 100644
--- a/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsRequest.ts
+++ b/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsRequest.ts
@@ -7,6 +7,7 @@ import type * as TrueForge from "../../../../index.js";
* {}
*/
export interface CreateTurnSessionsRequest {
+ /** Turn input items: user messages and/or approval/tool-response resumes. Do not mix user messages with approval or tool-response items. */
input?: TrueForge.TurnInputItem[];
previousTurnId?: TrueForge.PreviousTurnIdInput;
}
diff --git a/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts b/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts
index dc1f9c17e..2ae8646cf 100644
--- a/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts
+++ b/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts
@@ -7,6 +7,7 @@ import type * as TrueForge from "../../../../index.js";
* {}
*/
export interface CreateTurnSessionsStreamRequest {
+ /** Turn input items: user messages and/or approval/tool-response resumes. Do not mix user messages with approval or tool-response items. */
input?: TrueForge.TurnInputItem[];
previousTurnId?: TrueForge.PreviousTurnIdInput;
}
diff --git a/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts b/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts
index e8523b8a5..03af7554c 100644
--- a/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts
+++ b/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts
@@ -5,5 +5,6 @@
* {}
*/
export interface SubscribeToTurnSessionsRequest {
+ /** Exclusive resume cursor: replay only events with a sequence number greater than this value. Omit to start from the beginning of the live buffer. */
afterSequenceNumber?: number | null;
}
diff --git a/packages/sdk/src/api/resources/settings/resources/mcpServers/client/Client.ts b/packages/sdk/src/api/resources/settings/resources/mcpServers/client/Client.ts
index 4e514a272..ce986df8c 100644
--- a/packages/sdk/src/api/resources/settings/resources/mcpServers/client/Client.ts
+++ b/packages/sdk/src/api/resources/settings/resources/mcpServers/client/Client.ts
@@ -28,6 +28,8 @@ export class McpServersClient {
*
* @param {McpServersClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.ForbiddenError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -73,11 +75,36 @@ export class McpServersClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
}
return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/api/v1/settings/mcp-servers");
@@ -195,6 +222,8 @@ export class McpServersClient {
*
* @param {McpServersClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.ForbiddenError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -240,11 +269,36 @@ export class McpServersClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
}
return handleNonStatusCodeError(
@@ -397,7 +451,16 @@ export class McpServersClient {
if (_response.error.reason === "status-code") {
switch (_response.error.statusCode) {
case 401:
- throw new TrueForge.UnauthorizedError(_response.error.body, _response.rawResponse);
+ throw new TrueForge.UnauthorizedError(
+ 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, {
diff --git a/packages/sdk/src/api/resources/settings/resources/modelProviders/client/Client.ts b/packages/sdk/src/api/resources/settings/resources/modelProviders/client/Client.ts
index 17f7dfe51..b73a6362c 100644
--- a/packages/sdk/src/api/resources/settings/resources/modelProviders/client/Client.ts
+++ b/packages/sdk/src/api/resources/settings/resources/modelProviders/client/Client.ts
@@ -28,6 +28,8 @@ export class ModelProvidersClient {
*
* @param {ModelProvidersClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.ForbiddenError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -73,11 +75,36 @@ export class ModelProvidersClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
}
return handleNonStatusCodeError(
@@ -197,6 +224,8 @@ export class ModelProvidersClient {
*
* @param {ModelProvidersClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.ForbiddenError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -242,11 +271,36 @@ export class ModelProvidersClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
}
return handleNonStatusCodeError(
diff --git a/packages/sdk/src/api/resources/settings/resources/sandboxProviders/client/Client.ts b/packages/sdk/src/api/resources/settings/resources/sandboxProviders/client/Client.ts
index fc32f4425..8c5f5d629 100644
--- a/packages/sdk/src/api/resources/settings/resources/sandboxProviders/client/Client.ts
+++ b/packages/sdk/src/api/resources/settings/resources/sandboxProviders/client/Client.ts
@@ -212,6 +212,8 @@ export class SandboxProvidersClient {
*
* @param {SandboxProvidersClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.ForbiddenError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -257,11 +259,36 @@ export class SandboxProvidersClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
}
return handleNonStatusCodeError(
diff --git a/packages/sdk/src/api/resources/settings/resources/skills/client/Client.ts b/packages/sdk/src/api/resources/settings/resources/skills/client/Client.ts
index 1cfed8980..0452de378 100644
--- a/packages/sdk/src/api/resources/settings/resources/skills/client/Client.ts
+++ b/packages/sdk/src/api/resources/settings/resources/skills/client/Client.ts
@@ -28,6 +28,8 @@ export class SkillsClient {
*
* @param {SkillsClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.ForbiddenError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -73,11 +75,36 @@ export class SkillsClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
}
return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/api/v1/settings/skills");
@@ -183,6 +210,8 @@ export class SkillsClient {
*
* @param {SkillsClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
+ * @throws {@link TrueForge.ForbiddenError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -228,11 +257,36 @@ export class SkillsClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
}
return handleNonStatusCodeError(
diff --git a/packages/sdk/src/api/resources/skills/client/Client.ts b/packages/sdk/src/api/resources/skills/client/Client.ts
index 39df73810..60ee6c9ff 100644
--- a/packages/sdk/src/api/resources/skills/client/Client.ts
+++ b/packages/sdk/src/api/resources/skills/client/Client.ts
@@ -7,7 +7,7 @@ import * as core from "../../../../core/index.js";
import { handleNonStatusCodeError } from "../../../../errors/handleNonStatusCodeError.js";
import * as errors from "../../../../errors/index.js";
import * as serializers from "../../../../serialization/index.js";
-import type * as TrueForge from "../../../index.js";
+import * as TrueForge from "../../../index.js";
export declare namespace SkillsClient {
export type Options = BaseClientOptions;
@@ -27,6 +27,7 @@ export class SkillsClient {
*
* @param {SkillsClient.RequestOptions} requestOptions - Request-specific configuration.
*
+ * @throws {@link TrueForge.UnauthorizedError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
@@ -72,11 +73,25 @@ export class SkillsClient {
}
if (_response.error.reason === "status-code") {
- throw new errors.TrueForgeError({
- statusCode: _response.error.statusCode,
- body: _response.error.body,
- rawResponse: _response.rawResponse,
- });
+ switch (_response.error.statusCode) {
+ case 401:
+ throw new TrueForge.UnauthorizedError(
+ 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, "GET", "/api/v1/skills");
diff --git a/packages/sdk/src/api/types/Agent.ts b/packages/sdk/src/api/types/Agent.ts
index 43c9ef2c1..830c4e96c 100644
--- a/packages/sdk/src/api/types/Agent.ts
+++ b/packages/sdk/src/api/types/Agent.ts
@@ -3,7 +3,7 @@
import type * as TrueForge from "../index.js";
/**
- * Agent Definition
+ * Complete agent definition used inline on a session or saved as a named agent.
*/
export interface Agent extends TrueForge.AgentSpec {
/** Immutable server-generated agent identifier. */
diff --git a/packages/sdk/src/api/types/AgentInfo.ts b/packages/sdk/src/api/types/AgentInfo.ts
index aa021cb62..286fa7b5f 100644
--- a/packages/sdk/src/api/types/AgentInfo.ts
+++ b/packages/sdk/src/api/types/AgentInfo.ts
@@ -1,8 +1,12 @@
// This file was auto-generated by Fern from our API Definition.
export interface AgentInfo {
+ /** Input prompt passed to the subagent. */
input: string;
+ /** Optional model override for the subagent. */
model?: string;
+ /** Display name of the dynamic subagent. */
name: string;
+ /** Subagent kind. */
type: "dynamic";
}
diff --git a/packages/sdk/src/api/types/AgentParent.ts b/packages/sdk/src/api/types/AgentParent.ts
index 95068fe93..8994f1ece 100644
--- a/packages/sdk/src/api/types/AgentParent.ts
+++ b/packages/sdk/src/api/types/AgentParent.ts
@@ -1,6 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
export interface AgentParent {
+ /** Parent thread that spawned the child agent. */
threadId: string;
+ /** Tool call on the parent thread that created the child. */
toolCallId: string;
}
diff --git a/packages/sdk/src/api/types/AgentSpec.ts b/packages/sdk/src/api/types/AgentSpec.ts
index 0040daf8a..3a5da033e 100644
--- a/packages/sdk/src/api/types/AgentSpec.ts
+++ b/packages/sdk/src/api/types/AgentSpec.ts
@@ -3,15 +3,20 @@
import type * as TrueForge from "../index.js";
/**
- * Agent Definition
+ * Complete agent definition used inline on a session or saved as a named agent.
*/
export interface AgentSpec {
config?: TrueForge.RuntimeConfig;
+ /** Optional system prompt — the agent's role, behavior, and constraints. */
instructions?: string;
+ /** Optional MCP servers attached by configured name. */
mcpServers?: TrueForge.McpServer[];
+ /** Optional seed user messages injected at the start of every session. */
messages?: TrueForge.AgentSpecUserMessage[];
model: TrueForge.AgentSpecModel;
responseFormat?: TrueForge.ResponseFormat;
+ /** Optional name-only skill references. Requires `config.sandbox.enabled: true`. */
skills?: TrueForge.SkillNameRef[];
+ /** Optional string key–value map reserved for parameterizing agent definitions. */
variables?: Record<string, string>;
}
diff --git a/packages/sdk/src/api/types/AgentSpecModel.ts b/packages/sdk/src/api/types/AgentSpecModel.ts
index 90d84ffd6..7c46d7a4a 100644
--- a/packages/sdk/src/api/types/AgentSpecModel.ts
+++ b/packages/sdk/src/api/types/AgentSpecModel.ts
@@ -3,6 +3,7 @@
import type * as TrueForge from "../index.js";
export interface AgentSpecModel {
+ /** Model FQN: `provider/model`, e.g. `openai/gpt-5.2`. */
name: string;
params?: TrueForge.ModelParams;
}
diff --git a/packages/sdk/src/api/types/AgentSpecUserMessage.ts b/packages/sdk/src/api/types/AgentSpecUserMessage.ts
index feda5f0e1..1370103e6 100644
--- a/packages/sdk/src/api/types/AgentSpecUserMessage.ts
+++ b/packages/sdk/src/api/types/AgentSpecUserMessage.ts
@@ -1,6 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
export interface AgentSpecUserMessage {
+ /** Seed user message content injected at the start of every session. */
content: string;
+ /** Seed message type. */
type: "user.message";
}
diff --git a/packages/sdk/src/api/types/AlibabaModelProvider.ts b/packages/sdk/src/api/types/AlibabaModelProvider.ts
index 82d700bf1..d89c6b7b8 100644
--- a/packages/sdk/src/api/types/AlibabaModelProvider.ts
+++ b/packages/sdk/src/api/types/AlibabaModelProvider.ts
@@ -6,6 +6,7 @@ export interface AlibabaModelProvider {
auth: TrueForge.ModelProviderAuth;
/** Override of the provider's default API base URL. */
baseUrl?: string;
+ /** Models exposed by this provider (at least one). */
models: TrueForge.ModelEntry[];
name?: "alibaba";
type: "alibaba";
diff --git a/packages/sdk/src/api/types/AnthropicModelProvider.ts b/packages/sdk/src/api/types/AnthropicModelProvider.ts
index 0197a2721..5a6fbb5f3 100644
--- a/packages/sdk/src/api/types/AnthropicModelProvider.ts
+++ b/packages/sdk/src/api/types/AnthropicModelProvider.ts
@@ -6,6 +6,7 @@ export interface AnthropicModelProvider {
auth: TrueForge.ModelProviderAuth;
/** Override of the provider's default API base URL. */
baseUrl?: string;
+ /** Models exposed by this provider (at least one). */
models: TrueForge.ModelEntry[];
name?: "anthropic";
type: "anthropic";
diff --git a/packages/sdk/src/api/types/ApprovalDeny.ts b/packages/sdk/src/api/types/ApprovalDeny.ts
index 690569d80..f91dd07e9 100644
--- a/packages/sdk/src/api/types/ApprovalDeny.ts
+++ b/packages/sdk/src/api/types/ApprovalDeny.ts
@@ -1,6 +1,7 @@
// This file was auto-generated by Fern from our API Definition.
export interface ApprovalDeny {
+ /** Optional reason shown to the agent when denied. */
reason?: string;
status: "deny";
}
diff --git a/packages/sdk/src/api/types/AskUserQuestionsConfig.ts b/packages/sdk/src/api/types/AskUserQuestionsConfig.ts
index 55a974aa2..0bd811197 100644
--- a/packages/sdk/src/api/types/AskUserQuestionsConfig.ts
+++ b/packages/sdk/src/api/types/AskUserQuestionsConfig.ts
@@ -1,5 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
export interface AskUserQuestionsConfig {
+ /** Enable the `ask_user_question` tool. Default: true. */
enabled?: boolean;
}
diff --git a/packages/sdk/src/api/types/BaseMcpAuthRequiredEvent.ts b/packages/sdk/src/api/types/BaseMcpAuthRequiredEvent.ts
index 5496faa7e..a52c758a7 100644
--- a/packages/sdk/src/api/types/BaseMcpAuthRequiredEvent.ts
+++ b/packages/sdk/src/api/types/BaseMcpAuthRequiredEvent.ts
@@ -1,8 +1,10 @@
// This file was auto-generated by Fern from our API Definition.
export interface BaseMcpAuthRequiredEvent {
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Always null — this is a run-level event. */
threadId: string | null;
}
diff --git a/packages/sdk/src/api/types/BaseThreadDoneEvent.ts b/packages/sdk/src/api/types/BaseThreadDoneEvent.ts
index 59c804d71..62a2afd4e 100644
--- a/packages/sdk/src/api/types/BaseThreadDoneEvent.ts
+++ b/packages/sdk/src/api/types/BaseThreadDoneEvent.ts
@@ -4,6 +4,8 @@ import type * as TrueForge from "../index.js";
export interface BaseThreadDoneEvent {
parent?: TrueForge.AgentParent;
+ /** Thread that finished. */
threadId: string;
+ /** Human-readable thread title. */
title: string;
}
diff --git a/packages/sdk/src/api/types/CancelSessionResponse.ts b/packages/sdk/src/api/types/CancelSessionResponse.ts
index c80fc0911..44b765221 100644
--- a/packages/sdk/src/api/types/CancelSessionResponse.ts
+++ b/packages/sdk/src/api/types/CancelSessionResponse.ts
@@ -1,3 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
+/**
+ * Empty success body. HTTP 200 means the cancel request was accepted (or nothing was running).
+ */
export type CancelSessionResponse = {};
diff --git a/packages/sdk/src/api/types/CatalogDaytonaSandboxProvider.ts b/packages/sdk/src/api/types/CatalogDaytonaSandboxProvider.ts
index 28f0c3a7a..b99311e42 100644
--- a/packages/sdk/src/api/types/CatalogDaytonaSandboxProvider.ts
+++ b/packages/sdk/src/api/types/CatalogDaytonaSandboxProvider.ts
@@ -1,12 +1,16 @@
// This file was auto-generated by Fern from our API Definition.
export interface CatalogDaytonaSandboxProvider {
+ /** Minutes before Daytona auto-archives the sandbox (0 disables). */
autoArchiveIntervalInMinutes: number;
+ /** Minutes before Daytona auto-deletes the sandbox (0 disables). */
autoDeleteIntervalInMinutes: number;
+ /** Minutes of idle time before Daytona auto-stops the sandbox (0 disables). */
autoStopIntervalInMinutes: number;
/** Default sandbox command exec timeout in milliseconds. */
execTimeoutMs: number;
/** Daytona snapshot used when creating sandboxes. */
snapshotName: string;
+ /** Daytona sandbox provider. */
type: "daytona";
}
diff --git a/packages/sdk/src/api/types/CatalogMcpServer.ts b/packages/sdk/src/api/types/CatalogMcpServer.ts
index ba1f23eb5..f966f80e2 100644
--- a/packages/sdk/src/api/types/CatalogMcpServer.ts
+++ b/packages/sdk/src/api/types/CatalogMcpServer.ts
@@ -3,7 +3,8 @@
import type * as TrueForge from "../index.js";
export interface CatalogMcpServer {
- auth?: TrueForge.ConfiguredMcpServerAuth;
+ /** Optional default auth settings for the preset. */
+ auth?: TrueForge.CatalogMcpServerAuth;
/** URL of the MCP server logo asset. */
logo?: string;
name: TrueForge.ResourceName;
diff --git a/packages/sdk/src/api/types/CatalogMcpServerAuth.ts b/packages/sdk/src/api/types/CatalogMcpServerAuth.ts
new file mode 100644
index 000000000..35cbd0181
--- /dev/null
+++ b/packages/sdk/src/api/types/CatalogMcpServerAuth.ts
@@ -0,0 +1,8 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+/**
+ * Optional default auth settings for the preset.
+ */
+export type CatalogMcpServerAuth = TrueForge.McpServerDcrAuth | TrueForge.McpServerHeaderAuth;
diff --git a/packages/sdk/src/api/types/CatalogProvider.ts b/packages/sdk/src/api/types/CatalogProvider.ts
index 49e75b7df..d419d6015 100644
--- a/packages/sdk/src/api/types/CatalogProvider.ts
+++ b/packages/sdk/src/api/types/CatalogProvider.ts
@@ -5,7 +5,9 @@ import type * as TrueForge from "../index.js";
export interface CatalogProvider {
/** URL of the provider logo asset. */
logo?: string;
+ /** Preset models for this catalog provider. */
models: TrueForge.ModelEntry[];
name: TrueForge.ResourceName;
+ /** Well-known provider type (catalog excludes `custom`). */
type: TrueForge.CatalogProviderType;
}
diff --git a/packages/sdk/src/api/types/CatalogProviderType.ts b/packages/sdk/src/api/types/CatalogProviderType.ts
index 36e8eb584..a03c1cb4a 100644
--- a/packages/sdk/src/api/types/CatalogProviderType.ts
+++ b/packages/sdk/src/api/types/CatalogProviderType.ts
@@ -1,5 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
+/** Well-known provider type (catalog excludes `custom`). */
export const CatalogProviderType = {
Openai: "openai",
Anthropic: "anthropic",
diff --git a/packages/sdk/src/api/types/ChatCompletionChunkDeltaToolCall.ts b/packages/sdk/src/api/types/ChatCompletionChunkDeltaToolCall.ts
index 8b444fe24..33fa61e6a 100644
--- a/packages/sdk/src/api/types/ChatCompletionChunkDeltaToolCall.ts
+++ b/packages/sdk/src/api/types/ChatCompletionChunkDeltaToolCall.ts
@@ -4,7 +4,10 @@ import type * as TrueForge from "../index.js";
export interface ChatCompletionChunkDeltaToolCall {
function?: TrueForge.ChatCompletionChunkDeltaToolCallFunction;
+ /** Tool call id (may arrive across multiple deltas). */
id?: string;
+ /** Index of this tool call in the streaming delta array. */
index: number;
+ /** Tool call type when present on this delta. */
type?: "function";
}
diff --git a/packages/sdk/src/api/types/ChatCompletionChunkDeltaToolCallFunction.ts b/packages/sdk/src/api/types/ChatCompletionChunkDeltaToolCallFunction.ts
index 42f259907..2a097d46a 100644
--- a/packages/sdk/src/api/types/ChatCompletionChunkDeltaToolCallFunction.ts
+++ b/packages/sdk/src/api/types/ChatCompletionChunkDeltaToolCallFunction.ts
@@ -1,6 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
export interface ChatCompletionChunkDeltaToolCallFunction {
+ /** Partial or complete JSON arguments string. */
arguments?: string;
+ /** Partial or complete function name. */
name?: string;
}
diff --git a/packages/sdk/src/api/types/ChatCompletionContentPartRefusal.ts b/packages/sdk/src/api/types/ChatCompletionContentPartRefusal.ts
index 89f40c259..98a0891d9 100644
--- a/packages/sdk/src/api/types/ChatCompletionContentPartRefusal.ts
+++ b/packages/sdk/src/api/types/ChatCompletionContentPartRefusal.ts
@@ -1,6 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
export interface ChatCompletionContentPartRefusal {
+ /** Refusal message text. */
refusal: string;
+ /** Model refusal content part. */
type: "refusal";
}
diff --git a/packages/sdk/src/api/types/ChatCompletionContentPartText.ts b/packages/sdk/src/api/types/ChatCompletionContentPartText.ts
index 19c8e828e..9b3a60073 100644
--- a/packages/sdk/src/api/types/ChatCompletionContentPartText.ts
+++ b/packages/sdk/src/api/types/ChatCompletionContentPartText.ts
@@ -1,6 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
export interface ChatCompletionContentPartText {
+ /** Plain-text content. */
text: string;
+ /** Text content part. */
type: "text";
}
diff --git a/packages/sdk/src/api/types/ChatCompletionMessageToolCall.ts b/packages/sdk/src/api/types/ChatCompletionMessageToolCall.ts
index 34191ba15..2ce1f0067 100644
--- a/packages/sdk/src/api/types/ChatCompletionMessageToolCall.ts
+++ b/packages/sdk/src/api/types/ChatCompletionMessageToolCall.ts
@@ -4,6 +4,8 @@ import type * as TrueForge from "../index.js";
export interface ChatCompletionMessageToolCall {
function: TrueForge.ChatCompletionMessageToolCallFunction;
+ /** Tool call id. */
id: string;
+ /** Tool call type. */
type: "function";
}
diff --git a/packages/sdk/src/api/types/ChatCompletionMessageToolCallFunction.ts b/packages/sdk/src/api/types/ChatCompletionMessageToolCallFunction.ts
index 1ae19cd66..6b235145a 100644
--- a/packages/sdk/src/api/types/ChatCompletionMessageToolCallFunction.ts
+++ b/packages/sdk/src/api/types/ChatCompletionMessageToolCallFunction.ts
@@ -1,6 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
export interface ChatCompletionMessageToolCallFunction {
+ /** JSON-encoded function arguments string. */
arguments: string;
+ /** Function/tool name. */
name: string;
}
diff --git a/packages/sdk/src/api/types/ConfiguredMcpServerAuth.ts b/packages/sdk/src/api/types/ConfiguredMcpServerAuth.ts
index 68836c916..7322b92bf 100644
--- a/packages/sdk/src/api/types/ConfiguredMcpServerAuth.ts
+++ b/packages/sdk/src/api/types/ConfiguredMcpServerAuth.ts
@@ -2,4 +2,7 @@
import type * as TrueForge from "../index.js";
+/**
+ * Optional auth settings. Omit when the server needs no credentials.
+ */
export type ConfiguredMcpServerAuth = TrueForge.McpServerDcrAuth | TrueForge.McpServerHeaderAuth;
diff --git a/packages/sdk/src/api/types/ContextManagementConfigCompaction.ts b/packages/sdk/src/api/types/ContextManagementConfigCompaction.ts
index 091d3d6b3..ee915dea9 100644
--- a/packages/sdk/src/api/types/ContextManagementConfigCompaction.ts
+++ b/packages/sdk/src/api/types/ContextManagementConfigCompaction.ts
@@ -1,6 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
export interface ContextManagementConfigCompaction {
+ /** Context size in tokens that triggers compaction. Default: 50000. */
compactionThresholdTokens?: number;
+ /** Summarize older history when context grows too large. Default: true. */
enabled?: boolean;
}
diff --git a/packages/sdk/src/api/types/CustomModelProvider.ts b/packages/sdk/src/api/types/CustomModelProvider.ts
index 2295019ab..2ff352baa 100644
--- a/packages/sdk/src/api/types/CustomModelProvider.ts
+++ b/packages/sdk/src/api/types/CustomModelProvider.ts
@@ -6,6 +6,7 @@ export interface CustomModelProvider {
auth: TrueForge.ModelProviderAuth;
/** Base URL of the provider's API. */
baseUrl: string;
+ /** Models exposed by this provider (at least one). */
models: TrueForge.ModelEntry[];
name: TrueForge.ResourceName;
type: "custom";
diff --git a/packages/sdk/src/api/types/DaytonaSandboxProvider.ts b/packages/sdk/src/api/types/DaytonaSandboxProvider.ts
index 0fcf67bcd..1d038ebba 100644
--- a/packages/sdk/src/api/types/DaytonaSandboxProvider.ts
+++ b/packages/sdk/src/api/types/DaytonaSandboxProvider.ts
@@ -4,12 +4,16 @@ import type * as TrueForge from "../index.js";
export interface DaytonaSandboxProvider {
auth: TrueForge.DaytonaSandboxProviderAuth;
+ /** Minutes before Daytona auto-archives the sandbox (0 disables). */
autoArchiveIntervalInMinutes: number;
+ /** Minutes before Daytona auto-deletes the sandbox (0 disables). */
autoDeleteIntervalInMinutes: number;
+ /** Minutes of idle time before Daytona auto-stops the sandbox (0 disables). */
autoStopIntervalInMinutes: number;
/** Default sandbox command exec timeout in milliseconds. */
execTimeoutMs: number;
/** Daytona snapshot used when creating sandboxes. */
snapshotName: string;
+ /** Daytona sandbox provider. */
type: "daytona";
}
diff --git a/packages/sdk/src/api/types/DaytonaSandboxProviderAuth.ts b/packages/sdk/src/api/types/DaytonaSandboxProviderAuth.ts
index e2d4ea2cc..d76d05f26 100644
--- a/packages/sdk/src/api/types/DaytonaSandboxProviderAuth.ts
+++ b/packages/sdk/src/api/types/DaytonaSandboxProviderAuth.ts
@@ -1,5 +1,9 @@
// This file was auto-generated by Fern from our API Definition.
+/**
+ * Daytona authentication credentials.
+ */
export interface DaytonaSandboxProviderAuth {
+ /** Daytona API key. */
apiKey: string;
}
diff --git a/packages/sdk/src/api/types/DynamicSubAgentsConfig.ts b/packages/sdk/src/api/types/DynamicSubAgentsConfig.ts
index 6748d2004..06c30bb74 100644
--- a/packages/sdk/src/api/types/DynamicSubAgentsConfig.ts
+++ b/packages/sdk/src/api/types/DynamicSubAgentsConfig.ts
@@ -1,5 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
export interface DynamicSubAgentsConfig {
+ /** Allow the agent to spawn dynamic subagents. Default: true. */
enabled?: boolean;
}
diff --git a/packages/sdk/src/api/types/FileContent.ts b/packages/sdk/src/api/types/FileContent.ts
index f65ce92f3..498498b7e 100644
--- a/packages/sdk/src/api/types/FileContent.ts
+++ b/packages/sdk/src/api/types/FileContent.ts
@@ -3,6 +3,7 @@
export interface FileContent {
/** Data URI: `data:<mime>;base64,<payload>`. MIME type is parsed from the URI. */
data: string;
+ /** Filename presented to the agent. */
name: string;
type: "file";
}
diff --git a/packages/sdk/src/api/types/FinishReason.ts b/packages/sdk/src/api/types/FinishReason.ts
index bf8b032aa..33d69db0a 100644
--- a/packages/sdk/src/api/types/FinishReason.ts
+++ b/packages/sdk/src/api/types/FinishReason.ts
@@ -1,5 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
+/** Why the model stopped generating. */
export const FinishReason = {
Stop: "stop",
Length: "length",
diff --git a/packages/sdk/src/api/types/FireworksModelProvider.ts b/packages/sdk/src/api/types/FireworksModelProvider.ts
index 0c627a9a3..2d1fac5cb 100644
--- a/packages/sdk/src/api/types/FireworksModelProvider.ts
+++ b/packages/sdk/src/api/types/FireworksModelProvider.ts
@@ -6,6 +6,7 @@ export interface FireworksModelProvider {
auth: TrueForge.ModelProviderAuth;
/** Override of the provider's default API base URL. */
baseUrl?: string;
+ /** Models exposed by this provider (at least one). */
models: TrueForge.ModelEntry[];
name?: "fireworks";
type: "fireworks";
diff --git a/packages/sdk/src/api/types/GenerativeUiConfig.ts b/packages/sdk/src/api/types/GenerativeUiConfig.ts
index f87d82473..ab8d6107f 100644
--- a/packages/sdk/src/api/types/GenerativeUiConfig.ts
+++ b/packages/sdk/src/api/types/GenerativeUiConfig.ts
@@ -1,5 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
export interface GenerativeUiConfig {
+ /** Enable Generative UI (OpenUI blocks). Default: true. */
enabled?: boolean;
}
diff --git a/packages/sdk/src/api/types/GoogleGeminiModelProvider.ts b/packages/sdk/src/api/types/GoogleGeminiModelProvider.ts
index 74c3a10d7..ad6f5680a 100644
--- a/packages/sdk/src/api/types/GoogleGeminiModelProvider.ts
+++ b/packages/sdk/src/api/types/GoogleGeminiModelProvider.ts
@@ -6,6 +6,7 @@ export interface GoogleGeminiModelProvider {
auth: TrueForge.ModelProviderAuth;
/** Override of the provider's default API base URL. */
baseUrl?: string;
+ /** Models exposed by this provider (at least one). */
models: TrueForge.ModelEntry[];
name?: "google-gemini";
type: "google-gemini";
diff --git a/packages/sdk/src/api/types/LargeToolResponseConfig.ts b/packages/sdk/src/api/types/LargeToolResponseConfig.ts
index 1b7949cc4..57ca05d19 100644
--- a/packages/sdk/src/api/types/LargeToolResponseConfig.ts
+++ b/packages/sdk/src/api/types/LargeToolResponseConfig.ts
@@ -1,5 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
export interface LargeToolResponseConfig {
+ /** Offload oversized tool responses to a sandbox file. Default: true. */
enabled?: boolean;
}
diff --git a/packages/sdk/src/api/types/McpAuthRequiredEvent.ts b/packages/sdk/src/api/types/McpAuthRequiredEvent.ts
index 776959bea..5670d0a8d 100644
--- a/packages/sdk/src/api/types/McpAuthRequiredEvent.ts
+++ b/packages/sdk/src/api/types/McpAuthRequiredEvent.ts
@@ -3,6 +3,7 @@
import type * as TrueForge from "../index.js";
export interface McpAuthRequiredEvent extends TrueForge.BaseMcpAuthRequiredEvent {
+ /** Servers that need authorization, each with an auth_url. */
mcpServers: TrueForge.McpServerAuthInfo[];
type: "mcp.auth_required";
}
diff --git a/packages/sdk/src/api/types/McpAuthStatus.ts b/packages/sdk/src/api/types/McpAuthStatus.ts
index e6ddc9b1e..2dd0f93e8 100644
--- a/packages/sdk/src/api/types/McpAuthStatus.ts
+++ b/packages/sdk/src/api/types/McpAuthStatus.ts
@@ -5,5 +5,6 @@ import type * as TrueForge from "../index.js";
export interface McpAuthStatus {
/** When auth is required, this contains the URL to redirect the user to for authorization. */
authorizationUrl?: string;
+ /** Current auth state for this MCP server. */
status: TrueForge.McpAuthStatusStatus;
}
diff --git a/packages/sdk/src/api/types/McpAuthStatusStatus.ts b/packages/sdk/src/api/types/McpAuthStatusStatus.ts
index 8383fdc35..8e7fd5c14 100644
--- a/packages/sdk/src/api/types/McpAuthStatusStatus.ts
+++ b/packages/sdk/src/api/types/McpAuthStatusStatus.ts
@@ -1,5 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
+/** Current auth state for this MCP server. */
export const McpAuthStatusStatus = {
Authenticated: "authenticated",
AuthRequired: "auth_required",
diff --git a/packages/sdk/src/api/types/McpInitializeEvent.ts b/packages/sdk/src/api/types/McpInitializeEvent.ts
index 3965223fd..9509565fd 100644
--- a/packages/sdk/src/api/types/McpInitializeEvent.ts
+++ b/packages/sdk/src/api/types/McpInitializeEvent.ts
@@ -3,10 +3,13 @@
import type * as TrueForge from "../index.js";
export interface McpInitializeEvent {
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Servers that were initialized. */
mcpServers: TrueForge.McpServerInitInfo[];
+ /** Thread that triggered initialization. */
threadId: string;
type: "mcp.initialize";
}
diff --git a/packages/sdk/src/api/types/McpServer.ts b/packages/sdk/src/api/types/McpServer.ts
index 2a5091cd0..900aaaf90 100644
--- a/packages/sdk/src/api/types/McpServer.ts
+++ b/packages/sdk/src/api/types/McpServer.ts
@@ -3,10 +3,16 @@
import type * as TrueForge from "../index.js";
export interface McpServer {
+ /** Tools subtracted from the enabled set. Default: none. */
disableTools?: TrueForge.McpServerDisableToolsItem[];
+ /** Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. Default: `["@all"]`. */
enableTools?: TrueForge.McpServerEnableToolsItem[];
+ /** Name of a configured MCP server (Settings → Connectors). */
name: string;
+ /** When true, load all tool schemas upfront. Default: false (deferred discovery). */
preload?: boolean;
+ /** Tools loaded eagerly into context while the rest stay deferred. A non-empty list implies `preload: false`. */
preloadTools?: TrueForge.McpServerPreloadToolsItem[];
+ /** Tools that pause for human approval: `@all`, `@write`, `@destructive`, or literal names. Default: `["@write", "@destructive"]`. */
requireApprovalForTools?: TrueForge.McpServerRequireApprovalForToolsItem[];
}
diff --git a/packages/sdk/src/api/types/McpServerAuthInfo.ts b/packages/sdk/src/api/types/McpServerAuthInfo.ts
index 0e4043b34..3a348fcfe 100644
--- a/packages/sdk/src/api/types/McpServerAuthInfo.ts
+++ b/packages/sdk/src/api/types/McpServerAuthInfo.ts
@@ -1,7 +1,10 @@
// This file was auto-generated by Fern from our API Definition.
export interface McpServerAuthInfo {
+ /** URL the user must visit to complete OAuth for this server. */
authUrl: string;
+ /** Internal MCP server id. */
id: string;
+ /** Configured MCP server name. */
name: string;
}
diff --git a/packages/sdk/src/api/types/McpServerInitInfo.ts b/packages/sdk/src/api/types/McpServerInitInfo.ts
index 51483d425..30121da6c 100644
--- a/packages/sdk/src/api/types/McpServerInitInfo.ts
+++ b/packages/sdk/src/api/types/McpServerInitInfo.ts
@@ -3,8 +3,12 @@
import type * as TrueForge from "../index.js";
export interface McpServerInitInfo {
+ /** Internal MCP server id. */
id: string;
+ /** Configured MCP server name. */
name: string;
+ /** Optional MCP session id from the transport. */
sessionId?: string;
+ /** Transport used to connect to the MCP server. */
transportType?: TrueForge.McpServerInitInfoTransportType;
}
diff --git a/packages/sdk/src/api/types/McpServerInitInfoTransportType.ts b/packages/sdk/src/api/types/McpServerInitInfoTransportType.ts
index 1f55335a2..ead35ae0a 100644
--- a/packages/sdk/src/api/types/McpServerInitInfoTransportType.ts
+++ b/packages/sdk/src/api/types/McpServerInitInfoTransportType.ts
@@ -1,5 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
+/** Transport used to connect to the MCP server. */
export const McpServerInitInfoTransportType = {
StreamableHttp: "streamable-http",
Sse: "sse",
diff --git a/packages/sdk/src/api/types/McpServerReadEntry.ts b/packages/sdk/src/api/types/McpServerReadEntry.ts
index 2755ee544..d6b1f3f6a 100644
--- a/packages/sdk/src/api/types/McpServerReadEntry.ts
+++ b/packages/sdk/src/api/types/McpServerReadEntry.ts
@@ -4,5 +4,6 @@ import type * as TrueForge from "../index.js";
export interface McpServerReadEntry {
name: TrueForge.ResourceName;
+ /** URL of the remote MCP server. */
url: string;
}
diff --git a/packages/sdk/src/api/types/McpServerType.ts b/packages/sdk/src/api/types/McpServerType.ts
index 01de5c507..611c0e4fd 100644
--- a/packages/sdk/src/api/types/McpServerType.ts
+++ b/packages/sdk/src/api/types/McpServerType.ts
@@ -1,3 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
+/**
+ * MCP server kind (`remote` today).
+ */
export type McpServerType = "remote";
diff --git a/packages/sdk/src/api/types/McpToolInfo.ts b/packages/sdk/src/api/types/McpToolInfo.ts
index da7b537a2..de1d6d42a 100644
--- a/packages/sdk/src/api/types/McpToolInfo.ts
+++ b/packages/sdk/src/api/types/McpToolInfo.ts
@@ -1,8 +1,11 @@
// This file was auto-generated by Fern from our API Definition.
export interface McpToolInfo {
+ /** Tool name on the MCP server. */
name: string;
+ /** Internal MCP server id. */
serverId: string;
+ /** Configured MCP server name. */
serverName: string;
type: "mcp";
}
diff --git a/packages/sdk/src/api/types/ModelMessageDeltaEvent.ts b/packages/sdk/src/api/types/ModelMessageDeltaEvent.ts
index 219fdc8ca..5fc5a1f51 100644
--- a/packages/sdk/src/api/types/ModelMessageDeltaEvent.ts
+++ b/packages/sdk/src/api/types/ModelMessageDeltaEvent.ts
@@ -3,13 +3,18 @@
import type * as TrueForge from "../index.js";
export interface ModelMessageDeltaEvent {
+ /** Incremental assistant text content. */
content?: string | null;
+ /** Optional ISO 8601 event timestamp. */
createdAt?: string;
+ /** Finish reason when this delta completes the stream. */
finishReason?: TrueForge.FinishReason | null;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
reasoningContent?: string;
+ /** Incremental refusal text when present. */
refusal?: string | null;
+ /** Thread that emitted this delta. */
threadId: string;
toolCalls?: TrueForge.ExtendedChunkDeltaToolCall[];
type: "model.message.delta";
diff --git a/packages/sdk/src/api/types/ModelMessageEvent.ts b/packages/sdk/src/api/types/ModelMessageEvent.ts
index e0202e7b8..65016a942 100644
--- a/packages/sdk/src/api/types/ModelMessageEvent.ts
+++ b/packages/sdk/src/api/types/ModelMessageEvent.ts
@@ -3,14 +3,20 @@
import type * as TrueForge from "../index.js";
export interface ModelMessageEvent {
+ /** Assistant message content as text or content parts. */
content?: TrueForge.ModelMessageEventContent | null;
+ /** ISO 8601 event timestamp. */
createdAt: string;
+ /** Model finish reason; null when the provider omitted it. */
finishReason?: TrueForge.FinishReason | null;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Optional participant name. */
name?: string;
reasoningContent?: string;
+ /** Optional refusal text. */
refusal?: string | null;
+ /** Thread that emitted this message (`main` for the root agent). */
threadId: string;
toolCalls?: TrueForge.ToolCall[];
type: "model.message";
diff --git a/packages/sdk/src/api/types/ModelMessageEventContent.ts b/packages/sdk/src/api/types/ModelMessageEventContent.ts
index 67e388d8c..849f38e47 100644
--- a/packages/sdk/src/api/types/ModelMessageEventContent.ts
+++ b/packages/sdk/src/api/types/ModelMessageEventContent.ts
@@ -2,4 +2,7 @@
import type * as TrueForge from "../index.js";
+/**
+ * Assistant message content as text or content parts.
+ */
export type ModelMessageEventContent = string | TrueForge.ModelMessageEventContentOneItem[];
diff --git a/packages/sdk/src/api/types/ModelMessageUsage.ts b/packages/sdk/src/api/types/ModelMessageUsage.ts
index c0aedbecd..4cf3a9679 100644
--- a/packages/sdk/src/api/types/ModelMessageUsage.ts
+++ b/packages/sdk/src/api/types/ModelMessageUsage.ts
@@ -3,9 +3,13 @@
import type * as TrueForge from "../index.js";
export interface ModelMessageUsage {
+ /** Optional cache-read tokens. */
cacheReadTokens?: number;
+ /** Optional cache-write tokens. */
cacheWriteTokens?: number;
+ /** Input tokens for this model call. */
inputTokens: number;
inputTokensBreakdown: TrueForge.ModelMessageUsageInputTokensBreakdown;
+ /** Output tokens for this model call. */
outputTokens: number;
}
diff --git a/packages/sdk/src/api/types/ModelMessageUsageInputTokensBreakdown.ts b/packages/sdk/src/api/types/ModelMessageUsageInputTokensBreakdown.ts
index 1d82eb72e..d2806b3ac 100644
--- a/packages/sdk/src/api/types/ModelMessageUsageInputTokensBreakdown.ts
+++ b/packages/sdk/src/api/types/ModelMessageUsageInputTokensBreakdown.ts
@@ -1,9 +1,14 @@
// This file was auto-generated by Fern from our API Definition.
export interface ModelMessageUsageInputTokensBreakdown {
+ /** Tokens attributed to harness system framing. */
harness: number;
+ /** Tokens attributed to agent instructions. */
instructions: number;
+ /** Tokens attributed to conversation messages. */
messages: number;
+ /** Tokens attributed to skill instructions. */
skills: number;
+ /** Tokens attributed to tool schemas. */
toolDefinitions: number;
}
diff --git a/packages/sdk/src/api/types/ModelParams.ts b/packages/sdk/src/api/types/ModelParams.ts
index 2e09c2308..f1b79d773 100644
--- a/packages/sdk/src/api/types/ModelParams.ts
+++ b/packages/sdk/src/api/types/ModelParams.ts
@@ -1,11 +1,20 @@
// This file was auto-generated by Fern from our API Definition.
+/**
+ * Model call parameters passed through to the provider. Known keys are documented; extra keys are allowed and forwarded as-is.
+ */
export interface ModelParams {
+ /** Maximum tokens to generate in the model response. */
maxTokens?: number;
+ /** Whether the model may emit multiple tool calls in one response. */
parallelToolCalls?: boolean;
+ /** Provider-specific reasoning effort (e.g. low/medium/high). */
reasoningEffort?: string;
+ /** Sampling temperature; higher values increase randomness. */
temperature?: number;
+ /** Top-k sampling; keep only the k highest-probability tokens. */
topK?: number;
+ /** Nucleus sampling probability mass. */
topP?: number;
/** Accepts any additional properties */
[key: string]: any;
diff --git a/packages/sdk/src/api/types/ModelProperties.ts b/packages/sdk/src/api/types/ModelProperties.ts
index 11f897915..3b6019ce3 100644
--- a/packages/sdk/src/api/types/ModelProperties.ts
+++ b/packages/sdk/src/api/types/ModelProperties.ts
@@ -2,8 +2,14 @@
import type * as TrueForge from "../index.js";
+/**
+ * Optional model capability metadata.
+ */
export interface ModelProperties {
+ /** Maximum context window size in tokens. */
contextLength?: number;
+ /** Maximum output tokens the model can generate. */
maxOutputTokens?: number;
+ /** Supported reasoning-effort values for this model. */
reasoningEfforts?: TrueForge.ReasoningEffort[];
}
diff --git a/packages/sdk/src/api/types/ModelProviderAuth.ts b/packages/sdk/src/api/types/ModelProviderAuth.ts
index 0a7eaa224..3d69b7dda 100644
--- a/packages/sdk/src/api/types/ModelProviderAuth.ts
+++ b/packages/sdk/src/api/types/ModelProviderAuth.ts
@@ -1,5 +1,9 @@
// This file was auto-generated by Fern from our API Definition.
+/**
+ * Provider authentication credentials.
+ */
export interface ModelProviderAuth {
+ /** API key used to authenticate with the provider. */
apiKey: string;
}
diff --git a/packages/sdk/src/api/types/MoonshotModelProvider.ts b/packages/sdk/src/api/types/MoonshotModelProvider.ts
index 4a2db888a..3e34fd362 100644
--- a/packages/sdk/src/api/types/MoonshotModelProvider.ts
+++ b/packages/sdk/src/api/types/MoonshotModelProvider.ts
@@ -6,6 +6,7 @@ export interface MoonshotModelProvider {
auth: TrueForge.ModelProviderAuth;
/** Override of the provider's default API base URL. */
baseUrl?: string;
+ /** Models exposed by this provider (at least one). */
models: TrueForge.ModelEntry[];
name?: "moonshot";
type: "moonshot";
diff --git a/packages/sdk/src/api/types/OpenAiModelProvider.ts b/packages/sdk/src/api/types/OpenAiModelProvider.ts
index 536816989..c2b1cafc0 100644
--- a/packages/sdk/src/api/types/OpenAiModelProvider.ts
+++ b/packages/sdk/src/api/types/OpenAiModelProvider.ts
@@ -6,6 +6,7 @@ export interface OpenAiModelProvider {
auth: TrueForge.ModelProviderAuth;
/** Override of the provider's default API base URL. */
baseUrl?: string;
+ /** Models exposed by this provider (at least one). */
models: TrueForge.ModelEntry[];
name?: "openai";
type: "openai";
diff --git a/packages/sdk/src/api/types/RequestErrorResponseError.ts b/packages/sdk/src/api/types/RequestErrorResponseError.ts
index e693e6719..440db84ed 100644
--- a/packages/sdk/src/api/types/RequestErrorResponseError.ts
+++ b/packages/sdk/src/api/types/RequestErrorResponseError.ts
@@ -1,8 +1,12 @@
// This file was auto-generated by Fern from our API Definition.
export interface RequestErrorResponseError {
+ /** Optional machine-readable error code; null when not applicable. */
code?: string | null;
+ /** Human-readable explanation of the failure. */
message: string;
+ /** Optional request field that caused the error; null when not field-specific. */
param?: string | null;
+ /** Optional error category (e.g. validation vs conflict). */
type?: string;
}
diff --git a/packages/sdk/src/api/types/ResponseFormatJsonObject.ts b/packages/sdk/src/api/types/ResponseFormatJsonObject.ts
index c88d58670..d07541c43 100644
--- a/packages/sdk/src/api/types/ResponseFormatJsonObject.ts
+++ b/packages/sdk/src/api/types/ResponseFormatJsonObject.ts
@@ -1,5 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
+/**
+ * JSON object response format. Extra provider fields are allowed.
+ */
export interface ResponseFormatJsonObject {
type: "json_object";
/** Accepts any additional properties */
diff --git a/packages/sdk/src/api/types/ResponseFormatJsonSchema.ts b/packages/sdk/src/api/types/ResponseFormatJsonSchema.ts
index 7a66afe83..4f8b550fd 100644
--- a/packages/sdk/src/api/types/ResponseFormatJsonSchema.ts
+++ b/packages/sdk/src/api/types/ResponseFormatJsonSchema.ts
@@ -2,7 +2,11 @@
import type * as TrueForge from "../index.js";
+/**
+ * JSON Schema response format. Extra provider fields are allowed.
+ */
export interface ResponseFormatJsonSchema {
+ /** JSON Schema payload. Extra provider fields are allowed. */
jsonSchema: TrueForge.ResponseFormatJsonSchemaJsonSchema;
type: "json_schema";
/** Accepts any additional properties */
diff --git a/packages/sdk/src/api/types/ResponseFormatJsonSchemaJsonSchema.ts b/packages/sdk/src/api/types/ResponseFormatJsonSchemaJsonSchema.ts
index a65cf9c1d..2d346b066 100644
--- a/packages/sdk/src/api/types/ResponseFormatJsonSchemaJsonSchema.ts
+++ b/packages/sdk/src/api/types/ResponseFormatJsonSchemaJsonSchema.ts
@@ -1,9 +1,16 @@
// This file was auto-generated by Fern from our API Definition.
+/**
+ * JSON Schema payload. Extra provider fields are allowed.
+ */
export interface ResponseFormatJsonSchemaJsonSchema {
+ /** Optional schema description for the model. */
description?: string;
+ /** Schema name sent to the provider. */
name: string;
+ /** JSON Schema object for the response. */
schema?: Record<string, unknown>;
+ /** When true, ask the provider to enforce the schema strictly. */
strict?: boolean | null;
/** Accepts any additional properties */
[key: string]: any;
diff --git a/packages/sdk/src/api/types/ResponseFormatText.ts b/packages/sdk/src/api/types/ResponseFormatText.ts
index f0ce1c26a..2a3012300 100644
--- a/packages/sdk/src/api/types/ResponseFormatText.ts
+++ b/packages/sdk/src/api/types/ResponseFormatText.ts
@@ -1,5 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
+/**
+ * Default text response format. Extra provider fields are allowed.
+ */
export interface ResponseFormatText {
type: "text";
/** Accepts any additional properties */
diff --git a/packages/sdk/src/api/types/RuntimeConfig.ts b/packages/sdk/src/api/types/RuntimeConfig.ts
index 0271e8e3c..75f66462f 100644
--- a/packages/sdk/src/api/types/RuntimeConfig.ts
+++ b/packages/sdk/src/api/types/RuntimeConfig.ts
@@ -7,6 +7,7 @@ export interface RuntimeConfig {
contextManagement?: TrueForge.ContextManagementConfig;
dynamicSubAgents?: TrueForge.DynamicSubAgentsConfig;
generativeUi?: TrueForge.GenerativeUiConfig;
+ /** Max agent-loop iterations per turn (1–1024). Default: 100. */
iterationLimit?: number;
sandbox?: TrueForge.SandboxConfig;
}
diff --git a/packages/sdk/src/api/types/SandboxConfig.ts b/packages/sdk/src/api/types/SandboxConfig.ts
index 00af4d4db..3f3a3a2e6 100644
--- a/packages/sdk/src/api/types/SandboxConfig.ts
+++ b/packages/sdk/src/api/types/SandboxConfig.ts
@@ -3,7 +3,9 @@
import type * as TrueForge from "../index.js";
export interface SandboxConfig {
+ /** Give the agent a sandbox. Required for skills and Code Mode. */
enabled: boolean;
+ /** Allow downloading agent-produced files via the turn download endpoint. Default: true. */
fileDownloads?: boolean;
networkPolicy?: TrueForge.SandboxNetworkPolicy;
}
diff --git a/packages/sdk/src/api/types/SandboxCreatedEvent.ts b/packages/sdk/src/api/types/SandboxCreatedEvent.ts
index b3a312b39..388e16b1f 100644
--- a/packages/sdk/src/api/types/SandboxCreatedEvent.ts
+++ b/packages/sdk/src/api/types/SandboxCreatedEvent.ts
@@ -1,10 +1,13 @@
// This file was auto-generated by Fern from our API Definition.
export interface SandboxCreatedEvent {
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Provider sandbox id. */
sandboxId: string;
+ /** Always null — sandbox is session-scoped. */
threadId: string | null;
type: "sandbox.created";
}
diff --git a/packages/sdk/src/api/types/SandboxNetworkPolicy.ts b/packages/sdk/src/api/types/SandboxNetworkPolicy.ts
index 3ab1b6594..d537d0ad9 100644
--- a/packages/sdk/src/api/types/SandboxNetworkPolicy.ts
+++ b/packages/sdk/src/api/types/SandboxNetworkPolicy.ts
@@ -3,5 +3,6 @@
import type * as TrueForge from "../index.js";
export interface SandboxNetworkPolicy {
+ /** Up to one rule injecting git basic-auth credentials for exact hosts. */
authInject?: TrueForge.SandboxNetworkPolicyAuthInjectItem[];
}
diff --git a/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItem.ts b/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItem.ts
index 7b60aa0e2..e41ddec6b 100644
--- a/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItem.ts
+++ b/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItem.ts
@@ -5,5 +5,6 @@ import type * as TrueForge from "../index.js";
export interface SandboxNetworkPolicyAuthInjectItem {
authData: TrueForge.SandboxNetworkPolicyAuthInjectItemAuthData;
match: TrueForge.SandboxNetworkPolicyAuthInjectItemMatch;
+ /** Inject credentials for git HTTPS clones. */
type: "git";
}
diff --git a/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItemAuthData.ts b/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItemAuthData.ts
index 34f9e80c8..c2a770a34 100644
--- a/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItemAuthData.ts
+++ b/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItemAuthData.ts
@@ -1,7 +1,10 @@
// This file was auto-generated by Fern from our API Definition.
export interface SandboxNetworkPolicyAuthInjectItemAuthData {
+ /** Basic-auth password. */
password: string;
+ /** Basic auth credential type. */
type: "basic";
+ /** Basic-auth username (no whitespace). */
username: string;
}
diff --git a/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItemMatch.ts b/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItemMatch.ts
index 352278363..97d1a238c 100644
--- a/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItemMatch.ts
+++ b/packages/sdk/src/api/types/SandboxNetworkPolicyAuthInjectItemMatch.ts
@@ -1,5 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
export interface SandboxNetworkPolicyAuthInjectItemMatch {
+ /** Hostnames that receive injected credentials. */
hosts: string[];
}
diff --git a/packages/sdk/src/api/types/Session.ts b/packages/sdk/src/api/types/Session.ts
index be14042e4..99b15ce05 100644
--- a/packages/sdk/src/api/types/Session.ts
+++ b/packages/sdk/src/api/types/Session.ts
@@ -4,9 +4,14 @@ import type * as TrueForge from "../index.js";
export interface Session {
agent: TrueForge.SessionAgent;
+ /** ISO 8601 creation timestamp. */
createdAt: string;
+ /** Caller identity that created the session (immutable). */
createdBy: string;
+ /** Unique session id. */
id: string;
+ /** Optional human-readable title; null until set. */
title: string | null;
+ /** ISO 8601 last-update timestamp. */
updatedAt: string;
}
diff --git a/packages/sdk/src/api/types/SessionAgentReference.ts b/packages/sdk/src/api/types/SessionAgentReference.ts
index a049a8850..be5b776f3 100644
--- a/packages/sdk/src/api/types/SessionAgentReference.ts
+++ b/packages/sdk/src/api/types/SessionAgentReference.ts
@@ -1,7 +1,9 @@
// This file was auto-generated by Fern from our API Definition.
export interface SessionAgentReference {
+ /** Registry agent id. */
id: string;
+ /** Create-time snapshot of the registry agent name; null for legacy or orphan rows. */
name: string | null;
type: "reference";
}
diff --git a/packages/sdk/src/api/types/SessionEventItem.ts b/packages/sdk/src/api/types/SessionEventItem.ts
index d712e95b2..eb1d12ac7 100644
--- a/packages/sdk/src/api/types/SessionEventItem.ts
+++ b/packages/sdk/src/api/types/SessionEventItem.ts
@@ -4,5 +4,6 @@ import type * as TrueForge from "../index.js";
export interface SessionEventItem {
event: TrueForge.SessionEvent;
+ /** Turn that emitted this event. */
turnId: string;
}
diff --git a/packages/sdk/src/api/types/SkillNameRef.ts b/packages/sdk/src/api/types/SkillNameRef.ts
index 26235394e..33c4d1af2 100644
--- a/packages/sdk/src/api/types/SkillNameRef.ts
+++ b/packages/sdk/src/api/types/SkillNameRef.ts
@@ -1,6 +1,6 @@
// This file was auto-generated by Fern from our API Definition.
export interface SkillNameRef {
- /** Name for the skill, used as directory name in sandbox. */
+ /** Name of a configured skill (also used as the skill directory name in the sandbox). */
name: string;
}
diff --git a/packages/sdk/src/api/types/TextContent.ts b/packages/sdk/src/api/types/TextContent.ts
index 9faa22de9..69387e361 100644
--- a/packages/sdk/src/api/types/TextContent.ts
+++ b/packages/sdk/src/api/types/TextContent.ts
@@ -1,6 +1,7 @@
// This file was auto-generated by Fern from our API Definition.
export interface TextContent {
+ /** Plain-text content. */
text: string;
type: "text";
}
diff --git a/packages/sdk/src/api/types/ThreadCreatedEvent.ts b/packages/sdk/src/api/types/ThreadCreatedEvent.ts
index 0768205e4..1bb51aa6a 100644
--- a/packages/sdk/src/api/types/ThreadCreatedEvent.ts
+++ b/packages/sdk/src/api/types/ThreadCreatedEvent.ts
@@ -4,11 +4,14 @@ import type * as TrueForge from "../index.js";
export interface ThreadCreatedEvent {
agentInfo: TrueForge.AgentInfo;
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
parent: TrueForge.AgentParent;
+ /** Id of the new thread. */
threadId: string;
+ /** Human-readable thread title. */
title: string;
type: "thread.created";
}
diff --git a/packages/sdk/src/api/types/ThreadDoneEvent.ts b/packages/sdk/src/api/types/ThreadDoneEvent.ts
index 5fda7bc25..2cd8345b9 100644
--- a/packages/sdk/src/api/types/ThreadDoneEvent.ts
+++ b/packages/sdk/src/api/types/ThreadDoneEvent.ts
@@ -3,8 +3,9 @@
import type * as TrueForge from "../index.js";
export interface ThreadDoneEvent extends TrueForge.BaseThreadDoneEvent {
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
state: TrueForge.ThreadState;
type: "thread.done";
diff --git a/packages/sdk/src/api/types/ThreadStateError.ts b/packages/sdk/src/api/types/ThreadStateError.ts
index 770c1fc73..0cbd26eb3 100644
--- a/packages/sdk/src/api/types/ThreadStateError.ts
+++ b/packages/sdk/src/api/types/ThreadStateError.ts
@@ -3,6 +3,7 @@
import type * as TrueForge from "../index.js";
export interface ThreadStateError {
+ /** Human-readable error message. */
error: string;
output?: TrueForge.ModelMessageEvent;
status: "error";
diff --git a/packages/sdk/src/api/types/TogetherAiModelProvider.ts b/packages/sdk/src/api/types/TogetherAiModelProvider.ts
index 2f349aeed..a94c7f0f3 100644
--- a/packages/sdk/src/api/types/TogetherAiModelProvider.ts
+++ b/packages/sdk/src/api/types/TogetherAiModelProvider.ts
@@ -6,6 +6,7 @@ export interface TogetherAiModelProvider {
auth: TrueForge.ModelProviderAuth;
/** Override of the provider's default API base URL. */
baseUrl?: string;
+ /** Models exposed by this provider (at least one). */
models: TrueForge.ModelEntry[];
name?: "together";
type: "together";
diff --git a/packages/sdk/src/api/types/TokenPagination.ts b/packages/sdk/src/api/types/TokenPagination.ts
index 3b859abdf..122244e1a 100644
--- a/packages/sdk/src/api/types/TokenPagination.ts
+++ b/packages/sdk/src/api/types/TokenPagination.ts
@@ -1,7 +1,10 @@
// This file was auto-generated by Fern from our API Definition.
export interface TokenPagination {
+ /** Page size used for this response. */
limit: number;
+ /** Opaque token for the next page. Omit or absent when there is no next page. */
nextPageToken?: string;
+ /** Opaque token for the previous page. Omit or absent when there is no previous page. */
previousPageToken?: string;
}
diff --git a/packages/sdk/src/api/types/ToolApprovalRequiredEvent.ts b/packages/sdk/src/api/types/ToolApprovalRequiredEvent.ts
index 60b06a9ee..7869617ca 100644
--- a/packages/sdk/src/api/types/ToolApprovalRequiredEvent.ts
+++ b/packages/sdk/src/api/types/ToolApprovalRequiredEvent.ts
@@ -3,10 +3,13 @@
import type * as TrueForge from "../index.js";
export interface ToolApprovalRequiredEvent {
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Thread that owns the pending tool calls. */
threadId: string;
+ /** Tool calls waiting for approval. */
toolCalls: TrueForge.ToolCallRef[];
type: "tool.approval_required";
}
diff --git a/packages/sdk/src/api/types/ToolCallRef.ts b/packages/sdk/src/api/types/ToolCallRef.ts
index fcb0119ce..e3245c4ab 100644
--- a/packages/sdk/src/api/types/ToolCallRef.ts
+++ b/packages/sdk/src/api/types/ToolCallRef.ts
@@ -1,6 +1,8 @@
// This file was auto-generated by Fern from our API Definition.
export interface ToolCallRef {
+ /** Tool call id awaiting action. */
id: string;
+ /** Event id of the model.message that requested the tool call. */
sourceEventId: string;
}
diff --git a/packages/sdk/src/api/types/ToolResponseEvent.ts b/packages/sdk/src/api/types/ToolResponseEvent.ts
index 87fc64d11..94f4402c3 100644
--- a/packages/sdk/src/api/types/ToolResponseEvent.ts
+++ b/packages/sdk/src/api/types/ToolResponseEvent.ts
@@ -2,10 +2,13 @@
export interface ToolResponseEvent {
content: string;
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Thread that owns the tool call. */
threadId: string;
+ /** Id of the tool call this message responds to. */
toolCallId: string;
type: "tool.response";
}
diff --git a/packages/sdk/src/api/types/ToolResponseRequiredEvent.ts b/packages/sdk/src/api/types/ToolResponseRequiredEvent.ts
index bb89f7b96..cc59a1d95 100644
--- a/packages/sdk/src/api/types/ToolResponseRequiredEvent.ts
+++ b/packages/sdk/src/api/types/ToolResponseRequiredEvent.ts
@@ -3,10 +3,13 @@
import type * as TrueForge from "../index.js";
export interface ToolResponseRequiredEvent {
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Thread that owns the pending tool calls. */
threadId: string;
+ /** Tool calls waiting for a client response. */
toolCalls: TrueForge.ToolCallRef[];
type: "tool.response_required";
}
diff --git a/packages/sdk/src/api/types/TrueFoundrySystemToolInfo.ts b/packages/sdk/src/api/types/TrueFoundrySystemToolInfo.ts
index ebe26f9cf..f15cf753c 100644
--- a/packages/sdk/src/api/types/TrueFoundrySystemToolInfo.ts
+++ b/packages/sdk/src/api/types/TrueFoundrySystemToolInfo.ts
@@ -1,6 +1,7 @@
// This file was auto-generated by Fern from our API Definition.
export interface TrueFoundrySystemToolInfo {
+ /** System tool name. */
name: string;
type: "truefoundry-system";
}
diff --git a/packages/sdk/src/api/types/Turn.ts b/packages/sdk/src/api/types/Turn.ts
index b437622a0..12abff4b1 100644
--- a/packages/sdk/src/api/types/Turn.ts
+++ b/packages/sdk/src/api/types/Turn.ts
@@ -3,10 +3,15 @@
import type * as TrueForge from "../index.js";
export interface Turn {
+ /** ISO 8601 creation timestamp. */
createdAt: string;
+ /** Unique turn id. */
id: string;
+ /** Input items supplied when the turn was created. */
input?: TrueForge.TurnInputItem[];
+ /** Prior turn this turn chains from; null for a root turn. */
previousTurnId: string | null;
+ /** Session that owns this turn. */
sessionId: string;
state: TrueForge.TurnState;
}
diff --git a/packages/sdk/src/api/types/TurnCreatedEvent.ts b/packages/sdk/src/api/types/TurnCreatedEvent.ts
index 99eb877de..4894c2db9 100644
--- a/packages/sdk/src/api/types/TurnCreatedEvent.ts
+++ b/packages/sdk/src/api/types/TurnCreatedEvent.ts
@@ -3,13 +3,18 @@
import type * as TrueForge from "../index.js";
export interface TurnCreatedEvent {
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Input items supplied when the turn was created. */
input?: TrueForge.TurnInputItem[];
+ /** Prior turn this turn chains from; null for a root turn. */
previousTurnId: string | null;
state: TrueForge.TurnStateRunning;
+ /** Thread that owns the event; null for turn-level lifecycle events. */
threadId: string | null;
+ /** Id of the newly created turn. */
turnId: string;
type: "turn.created";
}
diff --git a/packages/sdk/src/api/types/TurnDoneEvent.ts b/packages/sdk/src/api/types/TurnDoneEvent.ts
index 8070f57bc..a2a2d59dc 100644
--- a/packages/sdk/src/api/types/TurnDoneEvent.ts
+++ b/packages/sdk/src/api/types/TurnDoneEvent.ts
@@ -3,10 +3,13 @@
import type * as TrueForge from "../index.js";
export interface TurnDoneEvent {
+ /** ISO 8601 event timestamp. */
createdAt: string;
- /** Unique identifier for the event */
+ /** Unique identifier for the event (monotonic ULID). */
id: string;
+ /** Terminal turn state (done, cancelled, or error). */
state: TrueForge.TurnDoneEventState;
+ /** Thread that owns the event; null for turn-level lifecycle events. */
threadId: string | null;
type: "turn.done";
}
diff --git a/packages/sdk/src/api/types/TurnDoneEventState.ts b/packages/sdk/src/api/types/TurnDoneEventState.ts
index 079cf1f08..7938c8343 100644
--- a/packages/sdk/src/api/types/TurnDoneEventState.ts
+++ b/packages/sdk/src/api/types/TurnDoneEventState.ts
@@ -2,4 +2,7 @@
import type * as TrueForge from "../index.js";
+/**
+ * Terminal turn state (done, cancelled, or error).
+ */
export type TurnDoneEventState = TrueForge.TurnStateCancelled | TrueForge.TurnStateDone | TrueForge.TurnStateError;
diff --git a/packages/sdk/src/api/types/TurnMetrics.ts b/packages/sdk/src/api/types/TurnMetrics.ts
index a00ae81a6..5326abc69 100644
--- a/packages/sdk/src/api/types/TurnMetrics.ts
+++ b/packages/sdk/src/api/types/TurnMetrics.ts
@@ -1,11 +1,21 @@
// This file was auto-generated by Fern from our API Definition.
+/**
+ * Optional billable aggregate for the whole turn.
+ */
export interface TurnMetrics {
+ /** Total cache-read tokens across model calls in this turn. */
totalCacheReadTokens?: number;
+ /** Total cache-write tokens across model calls in this turn. */
totalCacheWriteTokens?: number;
+ /** Estimated total cost in USD for this turn. */
totalCostInUsd?: number;
+ /** Total input tokens across model calls in this turn. */
totalInputTokens?: number;
+ /** Total output tokens across model calls in this turn. */
totalOutputTokens?: number;
+ /** Total reasoning tokens across model calls in this turn. */
totalReasoningTokens?: number;
+ /** Total tokens (input + output) across model calls in this turn. */
totalTokens?: number;
}
diff --git a/packages/sdk/src/api/types/TurnStateCancelled.ts b/packages/sdk/src/api/types/TurnStateCancelled.ts
index 6ce29a903..318a66866 100644
--- a/packages/sdk/src/api/types/TurnStateCancelled.ts
+++ b/packages/sdk/src/api/types/TurnStateCancelled.ts
@@ -3,8 +3,10 @@
import type * as TrueForge from "../index.js";
export interface TurnStateCancelled {
+ /** ISO 8601 time when cancellation completed. */
completedAt: string;
- metrics?: TrueForge.TurnMetrics;
+ /** Optional billable aggregate for work done before cancel. */
+ metrics?: TrueForge.TurnStateCancelledMetrics;
reason: TrueForge.TurnStateCancelledReason;
status: "cancelled";
}
diff --git a/packages/sdk/src/api/types/TurnStateCancelledMetrics.ts b/packages/sdk/src/api/types/TurnStateCancelledMetrics.ts
new file mode 100644
index 000000000..f422a1135
--- /dev/null
+++ b/packages/sdk/src/api/types/TurnStateCancelledMetrics.ts
@@ -0,0 +1,21 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * Optional billable aggregate for work done before cancel.
+ */
+export interface TurnStateCancelledMetrics {
+ /** Total cache-read tokens across model calls in this turn. */
+ totalCacheReadTokens?: number;
+ /** Total cache-write tokens across model calls in this turn. */
+ totalCacheWriteTokens?: number;
+ /** Estimated total cost in USD for this turn. */
+ totalCostInUsd?: number;
+ /** Total input tokens across model calls in this turn. */
+ totalInputTokens?: number;
+ /** Total output tokens across model calls in this turn. */
+ totalOutputTokens?: number;
+ /** Total reasoning tokens across model calls in this turn. */
+ totalReasoningTokens?: number;
+ /** Total tokens (input + output) across model calls in this turn. */
+ totalTokens?: number;
+}
diff --git a/packages/sdk/src/api/types/TurnStateDone.ts b/packages/sdk/src/api/types/TurnStateDone.ts
index f231ca197..d8d10966a 100644
--- a/packages/sdk/src/api/types/TurnStateDone.ts
+++ b/packages/sdk/src/api/types/TurnStateDone.ts
@@ -3,9 +3,12 @@
import type * as TrueForge from "../index.js";
export interface TurnStateDone {
+ /** ISO 8601 time when the turn reached a terminal state. */
completedAt: string;
metrics?: TrueForge.TurnMetrics;
+ /** Final `model.message` for the turn, or null when the turn ended paused without a final message. */
output: TrueForge.ModelMessageEvent | null;
+ /** Pending actions (`tool.approval_required`, `tool.response_required`, `mcp.auth_required`); empty when none. */
requiredActions: TrueForge.ActionRequiredEvent[];
status: "done";
}
diff --git a/packages/sdk/src/api/types/TurnStateError.ts b/packages/sdk/src/api/types/TurnStateError.ts
index 1dcbf1bef..84b7d8059 100644
--- a/packages/sdk/src/api/types/TurnStateError.ts
+++ b/packages/sdk/src/api/types/TurnStateError.ts
@@ -3,8 +3,11 @@
import type * as TrueForge from "../index.js";
export interface TurnStateError {
+ /** ISO 8601 time when the error state was recorded. */
completedAt: string;
+ /** Human-readable error message. */
message: string;
- metrics?: TrueForge.TurnMetrics;
+ /** Optional billable aggregate for work done before the error. */
+ metrics?: TrueForge.TurnStateErrorMetrics;
status: "error";
}
diff --git a/packages/sdk/src/api/types/TurnStateErrorMetrics.ts b/packages/sdk/src/api/types/TurnStateErrorMetrics.ts
new file mode 100644
index 000000000..0195bcf03
--- /dev/null
+++ b/packages/sdk/src/api/types/TurnStateErrorMetrics.ts
@@ -0,0 +1,21 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * Optional billable aggregate for work done before the error.
+ */
+export interface TurnStateErrorMetrics {
+ /** Total cache-read tokens across model calls in this turn. */
+ totalCacheReadTokens?: number;
+ /** Total cache-write tokens across model calls in this turn. */
+ totalCacheWriteTokens?: number;
+ /** Estimated total cost in USD for this turn. */
+ totalCostInUsd?: number;
+ /** Total input tokens across model calls in this turn. */
+ totalInputTokens?: number;
+ /** Total output tokens across model calls in this turn. */
+ totalOutputTokens?: number;
+ /** Total reasoning tokens across model calls in this turn. */
+ totalReasoningTokens?: number;
+ /** Total tokens (input + output) across model calls in this turn. */
+ totalTokens?: number;
+}
diff --git a/packages/sdk/src/api/types/UserMessage.ts b/packages/sdk/src/api/types/UserMessage.ts
index 93343e51e..f2884034d 100644
--- a/packages/sdk/src/api/types/UserMessage.ts
+++ b/packages/sdk/src/api/types/UserMessage.ts
@@ -3,6 +3,7 @@
import type * as TrueForge from "../index.js";
export interface UserMessage {
+ /** Plain string or structured text/file content parts. */
content: TrueForge.UserMessageContent;
type: "user.message";
}
diff --git a/packages/sdk/src/api/types/UserMessageContent.ts b/packages/sdk/src/api/types/UserMessageContent.ts
index 60b7dfce9..85304d0a9 100644
--- a/packages/sdk/src/api/types/UserMessageContent.ts
+++ b/packages/sdk/src/api/types/UserMessageContent.ts
@@ -2,4 +2,7 @@
import type * as TrueForge from "../index.js";
+/**
+ * Plain string or structured text/file content parts.
+ */
export type UserMessageContent = string | TrueForge.UserMessageContentItem[];
diff --git a/packages/sdk/src/api/types/UserToolApprovalEvent.ts b/packages/sdk/src/api/types/UserToolApprovalEvent.ts
index 2f2d3b240..432dde181 100644
--- a/packages/sdk/src/api/types/UserToolApprovalEvent.ts
+++ b/packages/sdk/src/api/types/UserToolApprovalEvent.ts
@@ -4,7 +4,9 @@ import type * as TrueForge from "../index.js";
export interface UserToolApprovalEvent {
approval: TrueForge.ApprovalDecision;
+ /** Thread that owns the pending tool call. */
threadId: string;
+ /** Tool call id being approved or denied. */
toolCallId: string;
type: "user.tool_approval";
}
diff --git a/packages/sdk/src/api/types/UserToolResponseEvent.ts b/packages/sdk/src/api/types/UserToolResponseEvent.ts
index aaf75109c..d86330196 100644
--- a/packages/sdk/src/api/types/UserToolResponseEvent.ts
+++ b/packages/sdk/src/api/types/UserToolResponseEvent.ts
@@ -1,8 +1,11 @@
// This file was auto-generated by Fern from our API Definition.
export interface UserToolResponseEvent {
+ /** Client-side tool result content. */
content: string;
+ /** Thread that owns the pending tool call. */
threadId: string;
+ /** Tool call id receiving the client response. */
toolCallId: string;
type: "user.tool_response";
}
diff --git a/packages/sdk/src/api/types/ZaiModelProvider.ts b/packages/sdk/src/api/types/ZaiModelProvider.ts
index a34861fe2..c1a20ca27 100644
--- a/packages/sdk/src/api/types/ZaiModelProvider.ts
+++ b/packages/sdk/src/api/types/ZaiModelProvider.ts
@@ -6,6 +6,7 @@ export interface ZaiModelProvider {
auth: TrueForge.ModelProviderAuth;
/** Override of the provider's default API base URL. */
baseUrl?: string;
+ /** Models exposed by this provider (at least one). */
models: TrueForge.ModelEntry[];
name?: "zai";
type: "zai";
diff --git a/packages/sdk/src/api/types/index.ts b/packages/sdk/src/api/types/index.ts
index c62170262..d80565b2e 100644
--- a/packages/sdk/src/api/types/index.ts
+++ b/packages/sdk/src/api/types/index.ts
@@ -16,6 +16,7 @@ export * from "./BaseThreadDoneEvent.js";
export * from "./CancelSessionResponse.js";
export * from "./CatalogDaytonaSandboxProvider.js";
export * from "./CatalogMcpServer.js";
+export * from "./CatalogMcpServerAuth.js";
export * from "./CatalogProvider.js";
export * from "./CatalogProviderType.js";
export * from "./CatalogSkill.js";
@@ -161,9 +162,11 @@ export * from "./TurnInputItem.js";
export * from "./TurnMetrics.js";
export * from "./TurnState.js";
export * from "./TurnStateCancelled.js";
+export * from "./TurnStateCancelledMetrics.js";
export * from "./TurnStateCancelledReason.js";
export * from "./TurnStateDone.js";
export * from "./TurnStateError.js";
+export * from "./TurnStateErrorMetrics.js";
export * from "./TurnStateRunning.js";
export * from "./TurnStreamingEvent.js";
export * from "./UserMessage.js";
diff --git a/packages/sdk/src/serialization/types/CatalogMcpServer.ts b/packages/sdk/src/serialization/types/CatalogMcpServer.ts
index 9151b754c..7addfa9dc 100644
--- a/packages/sdk/src/serialization/types/CatalogMcpServer.ts
+++ b/packages/sdk/src/serialization/types/CatalogMcpServer.ts
@@ -3,7 +3,7 @@
import type * as TrueForge from "../../api/index.js";
import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
-import { ConfiguredMcpServerAuth } from "./ConfiguredMcpServerAuth.js";
+import { CatalogMcpServerAuth } from "./CatalogMcpServerAuth.js";
import { McpServerType } from "./McpServerType.js";
import { ResourceName } from "./ResourceName.js";
@@ -11,7 +11,7 @@ export const CatalogMcpServer: core.serialization.ObjectSchema<
serializers.CatalogMcpServer.Raw,
TrueForge.CatalogMcpServer
> = core.serialization.object({
- auth: ConfiguredMcpServerAuth.optional(),
+ auth: CatalogMcpServerAuth.optional(),
logo: core.serialization.string().optional(),
name: ResourceName,
type: McpServerType,
@@ -20,7 +20,7 @@ export const CatalogMcpServer: core.serialization.ObjectSchema<
export declare namespace CatalogMcpServer {
export interface Raw {
- auth?: ConfiguredMcpServerAuth.Raw | null;
+ auth?: CatalogMcpServerAuth.Raw | null;
logo?: string | null;
name: ResourceName.Raw;
type: McpServerType.Raw;
diff --git a/packages/sdk/src/serialization/types/CatalogMcpServerAuth.ts b/packages/sdk/src/serialization/types/CatalogMcpServerAuth.ts
new file mode 100644
index 000000000..e5881b763
--- /dev/null
+++ b/packages/sdk/src/serialization/types/CatalogMcpServerAuth.ts
@@ -0,0 +1,16 @@
+// 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 { McpServerDcrAuth } from "./McpServerDcrAuth.js";
+import { McpServerHeaderAuth } from "./McpServerHeaderAuth.js";
+
+export const CatalogMcpServerAuth: core.serialization.Schema<
+ serializers.CatalogMcpServerAuth.Raw,
+ TrueForge.CatalogMcpServerAuth
+> = core.serialization.undiscriminatedUnion([McpServerDcrAuth, McpServerHeaderAuth]);
+
+export declare namespace CatalogMcpServerAuth {
+ export type Raw = McpServerDcrAuth.Raw | McpServerHeaderAuth.Raw;
+}
diff --git a/packages/sdk/src/serialization/types/TurnStateCancelled.ts b/packages/sdk/src/serialization/types/TurnStateCancelled.ts
index 6e6f883b8..94547a473 100644
--- a/packages/sdk/src/serialization/types/TurnStateCancelled.ts
+++ b/packages/sdk/src/serialization/types/TurnStateCancelled.ts
@@ -3,7 +3,7 @@
import type * as TrueForge from "../../api/index.js";
import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
-import { TurnMetrics } from "./TurnMetrics.js";
+import { TurnStateCancelledMetrics } from "./TurnStateCancelledMetrics.js";
import { TurnStateCancelledReason } from "./TurnStateCancelledReason.js";
export const TurnStateCancelled: core.serialization.ObjectSchema<
@@ -11,7 +11,7 @@ export const TurnStateCancelled: core.serialization.ObjectSchema<
TrueForge.TurnStateCancelled
> = core.serialization.object({
completedAt: core.serialization.property("completed_at", core.serialization.string()),
- metrics: TurnMetrics.optional(),
+ metrics: TurnStateCancelledMetrics.optional(),
reason: TurnStateCancelledReason,
status: core.serialization.stringLiteral("cancelled"),
});
@@ -19,7 +19,7 @@ export const TurnStateCancelled: core.serialization.ObjectSchema<
export declare namespace TurnStateCancelled {
export interface Raw {
completed_at: string;
- metrics?: TurnMetrics.Raw | null;
+ metrics?: TurnStateCancelledMetrics.Raw | null;
reason: TurnStateCancelledReason.Raw;
status: "cancelled";
}
diff --git a/packages/sdk/src/serialization/types/TurnStateCancelledMetrics.ts b/packages/sdk/src/serialization/types/TurnStateCancelledMetrics.ts
new file mode 100644
index 000000000..8c4a85f14
--- /dev/null
+++ b/packages/sdk/src/serialization/types/TurnStateCancelledMetrics.ts
@@ -0,0 +1,36 @@
+// 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";
+
+export const TurnStateCancelledMetrics: core.serialization.ObjectSchema<
+ serializers.TurnStateCancelledMetrics.Raw,
+ TrueForge.TurnStateCancelledMetrics
+> = core.serialization.object({
+ totalCacheReadTokens: core.serialization.property(
+ "total_cache_read_tokens",
+ core.serialization.number().optional(),
+ ),
+ totalCacheWriteTokens: core.serialization.property(
+ "total_cache_write_tokens",
+ core.serialization.number().optional(),
+ ),
+ totalCostInUsd: core.serialization.property("total_cost_in_usd", core.serialization.number().optional()),
+ totalInputTokens: core.serialization.property("total_input_tokens", core.serialization.number().optional()),
+ totalOutputTokens: core.serialization.property("total_output_tokens", core.serialization.number().optional()),
+ totalReasoningTokens: core.serialization.property("total_reasoning_tokens", core.serialization.number().optional()),
+ totalTokens: core.serialization.property("total_tokens", core.serialization.number().optional()),
+});
+
+export declare namespace TurnStateCancelledMetrics {
+ export interface Raw {
+ total_cache_read_tokens?: number | null;
+ total_cache_write_tokens?: number | null;
+ total_cost_in_usd?: number | null;
+ total_input_tokens?: number | null;
+ total_output_tokens?: number | null;
+ total_reasoning_tokens?: number | null;
+ total_tokens?: number | null;
+ }
+}
diff --git a/packages/sdk/src/serialization/types/TurnStateError.ts b/packages/sdk/src/serialization/types/TurnStateError.ts
index 9d92da0d3..6b4cdc8d2 100644
--- a/packages/sdk/src/serialization/types/TurnStateError.ts
+++ b/packages/sdk/src/serialization/types/TurnStateError.ts
@@ -3,13 +3,13 @@
import type * as TrueForge from "../../api/index.js";
import * as core from "../../core/index.js";
import type * as serializers from "../index.js";
-import { TurnMetrics } from "./TurnMetrics.js";
+import { TurnStateErrorMetrics } from "./TurnStateErrorMetrics.js";
export const TurnStateError: core.serialization.ObjectSchema<serializers.TurnStateError.Raw, TrueForge.TurnStateError> =
core.serialization.object({
completedAt: core.serialization.property("completed_at", core.serialization.string()),
message: core.serialization.string(),
- metrics: TurnMetrics.optional(),
+ metrics: TurnStateErrorMetrics.optional(),
status: core.serialization.stringLiteral("error"),
});
@@ -17,7 +17,7 @@ export declare namespace TurnStateError {
export interface Raw {
completed_at: string;
message: string;
- metrics?: TurnMetrics.Raw | null;
+ metrics?: TurnStateErrorMetrics.Raw | null;
status: "error";
}
}
diff --git a/packages/sdk/src/serialization/types/TurnStateErrorMetrics.ts b/packages/sdk/src/serialization/types/TurnStateErrorMetrics.ts
new file mode 100644
index 000000000..d05edd421
--- /dev/null
+++ b/packages/sdk/src/serialization/types/TurnStateErrorMetrics.ts
@@ -0,0 +1,36 @@
+// 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";
+
+export const TurnStateErrorMetrics: core.serialization.ObjectSchema<
+ serializers.TurnStateErrorMetrics.Raw,
+ TrueForge.TurnStateErrorMetrics
+> = core.serialization.object({
+ totalCacheReadTokens: core.serialization.property(
+ "total_cache_read_tokens",
+ core.serialization.number().optional(),
+ ),
+ totalCacheWriteTokens: core.serialization.property(
+ "total_cache_write_tokens",
+ core.serialization.number().optional(),
+ ),
+ totalCostInUsd: core.serialization.property("total_cost_in_usd", core.serialization.number().optional()),
+ totalInputTokens: core.serialization.property("total_input_tokens", core.serialization.number().optional()),
+ totalOutputTokens: core.serialization.property("total_output_tokens", core.serialization.number().optional()),
+ totalReasoningTokens: core.serialization.property("total_reasoning_tokens", core.serialization.number().optional()),
+ totalTokens: core.serialization.property("total_tokens", core.serialization.number().optional()),
+});
+
+export declare namespace TurnStateErrorMetrics {
+ export interface Raw {
+ total_cache_read_tokens?: number | null;
+ total_cache_write_tokens?: number | null;
+ total_cost_in_usd?: number | null;
+ total_input_tokens?: number | null;
+ total_output_tokens?: number | null;
+ total_reasoning_tokens?: number | null;
+ total_tokens?: number | null;
+ }
+}
diff --git a/packages/sdk/src/serialization/types/index.ts b/packages/sdk/src/serialization/types/index.ts
index c62170262..d80565b2e 100644
--- a/packages/sdk/src/serialization/types/index.ts
+++ b/packages/sdk/src/serialization/types/index.ts
@@ -16,6 +16,7 @@ export * from "./BaseThreadDoneEvent.js";
export * from "./CancelSessionResponse.js";
export * from "./CatalogDaytonaSandboxProvider.js";
export * from "./CatalogMcpServer.js";
+export * from "./CatalogMcpServerAuth.js";
export * from "./CatalogProvider.js";
export * from "./CatalogProviderType.js";
export * from "./CatalogSkill.js";
@@ -161,9 +162,11 @@ export * from "./TurnInputItem.js";
export * from "./TurnMetrics.js";
export * from "./TurnState.js";
export * from "./TurnStateCancelled.js";
+export * from "./TurnStateCancelledMetrics.js";
export * from "./TurnStateCancelledReason.js";
export * from "./TurnStateDone.js";
export * from "./TurnStateError.js";
+export * from "./TurnStateErrorMetrics.js";
export * from "./TurnStateRunning.js";
export * from "./TurnStreamingEvent.js";
export * from "./UserMessage.js";
diff --git a/packages/sdk/tests/unit/events.test.ts b/packages/sdk/tests/unit/events.test.ts
deleted file mode 100644
index 32f8015b2..000000000
--- a/packages/sdk/tests/unit/events.test.ts
+++ /dev/null
@@ -1,164 +0,0 @@
-import type * as TrueForge from "../../src/api/index";
-import { isEventDelta, mergeEventDelta } from "../../src/events";
-
-function baseMessage(overrides: Partial<TrueForge.ModelMessageEvent> = {}): TrueForge.ModelMessageEvent {
- return {
- type: "model.message",
- id: "msg-1",
- threadId: "main",
- createdAt: "2026-06-24T10:00:00Z",
- content: "",
- ...overrides,
- };
-}
-
-function delta(overrides: Partial<TrueForge.ModelMessageDeltaEvent> = {}): TrueForge.ModelMessageDeltaEvent {
- return {
- type: "model.message.delta",
- id: "msg-1",
- threadId: "main",
- ...overrides,
- };
-}
-
-describe("isEventDelta", () => {
- it("returns true for model.message.delta", () => {
- expect(isEventDelta(delta())).toBe(true);
- });
-
- it("returns false for other event types", () => {
- expect(isEventDelta(baseMessage())).toBe(false);
- expect(isEventDelta({ type: "turn.done" })).toBe(false);
- });
-});
-
-describe("mergeEventDelta", () => {
- it("appends content and reasoningContent", () => {
- const base = baseMessage({ content: "Hel", reasoningContent: "think" });
- mergeEventDelta(base, delta({ content: "lo", reasoningContent: "ing" }));
- expect(base.content).toBe("Hello");
- expect(base.reasoningContent).toBe("thinking");
- });
-
- it("treats null/undefined content as empty string when appending", () => {
- const base = baseMessage({ content: null });
- mergeEventDelta(base, delta({ content: "Hi" }));
- expect(base.content).toBe("Hi");
- });
-
- it("does not append string content onto array content", () => {
- const parts: TrueForge.ModelMessageEventContentOneItem[] = [{ type: "text", text: "x" }];
- const base = baseMessage({ content: parts });
- mergeEventDelta(base, delta({ content: "y" }));
- expect(base.content).toBe(parts);
- });
-
- it("overwrites finishReason, usage, and refusal", () => {
- const base = baseMessage({
- finishReason: null,
- refusal: null,
- });
- const usage: TrueForge.ModelMessageUsage = {
- inputTokens: 1,
- outputTokens: 2,
- inputTokensBreakdown: {
- harness: 0,
- instructions: 0,
- messages: 1,
- skills: 0,
- toolDefinitions: 0,
- },
- };
- mergeEventDelta(
- base,
- delta({
- finishReason: "stop",
- refusal: "nope",
- usage,
- }),
- );
- expect(base.finishReason).toBe("stop");
- expect(base.refusal).toBe("nope");
- expect(base.usage).toEqual(usage);
- });
-
- it("merges tool call fragments by index", () => {
- const base = baseMessage();
- const toolInfo: TrueForge.McpToolInfo = {
- type: "mcp",
- name: "get_order",
- serverId: "orders-api",
- serverName: "orders-api",
- };
-
- mergeEventDelta(
- base,
- delta({
- toolCalls: [
- {
- index: 0,
- id: "call-1",
- type: "function",
- function: { name: "get_order", arguments: "" },
- toolInfo,
- },
- ],
- }),
- );
- mergeEventDelta(
- base,
- delta({
- toolCalls: [
- {
- index: 0,
- function: { arguments: '{"order_id":' },
- },
- ],
- }),
- );
- mergeEventDelta(
- base,
- delta({
- toolCalls: [
- {
- index: 0,
- function: { arguments: '"ORD-2031"}' },
- },
- ],
- }),
- );
-
- expect(base.toolCalls).toEqual([
- {
- id: "call-1",
- type: "function",
- function: { name: "get_order", arguments: '{"order_id":"ORD-2031"}' },
- toolInfo,
- },
- ]);
- });
-
- it("no-ops when ids do not match", () => {
- const base = baseMessage({ content: "keep" });
- mergeEventDelta(base, delta({ id: "other", content: "x" }));
- expect(base.content).toBe("keep");
- });
-
- it("no-ops when base is not a model.message", () => {
- const turnDone: TrueForge.TurnDoneEvent = {
- type: "turn.done",
- id: "msg-1",
- threadId: null,
- createdAt: "2026-06-24T10:00:00Z",
- state: { status: "done", output: null, requiredActions: [], completedAt: "2026-06-24T10:00:00Z" },
- };
- mergeEventDelta(turnDone, delta({ content: "x" }));
- expect(turnDone).toEqual({
- type: "turn.done",
- id: "msg-1",
- threadId: null,
- createdAt: "2026-06-24T10:00:00Z",
- state: { status: "done", output: null, requiredActions: [], completedAt: "2026-06-24T10:00:00Z" },
- });
- });
-});
diff --git a/packages/sdk/tests/wire/agents.test.ts b/packages/sdk/tests/wire/agents.test.ts
index cd3361ffb..1df0a6308 100644
--- a/packages/sdk/tests/wire/agents.test.ts
+++ b/packages/sdk/tests/wire/agents.test.ts
@@ -5,7 +5,7 @@ import { TrueForge } from "../../src/Client";
import { mockServerPool } from "../mock-server/MockServerPool";
describe("AgentsClient", () => {
- test("list", async () => {
+ test("list (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -64,6 +64,19 @@ describe("AgentsClient", () => {
});
});
+ test("list (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server.mockEndpoint().get("/api/v1/agents").respondWith().statusCode(401).jsonBody(rawResponseBody).build();
+
+ await expect(async () => {
+ return await client.agents.list();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
test("create (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -300,7 +313,7 @@ describe("AgentsClient", () => {
}).rejects.toThrow(TrueForgeTypes.NotFoundError);
});
- test("delete", async () => {
+ test("delete (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -310,6 +323,25 @@ describe("AgentsClient", () => {
expect(response).toEqual(undefined);
});
+ test("delete (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .delete("/api/v1/agents/agent_id")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.agents.delete("agent_id");
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
test("update (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
diff --git a/packages/sdk/tests/wire/auth.test.ts b/packages/sdk/tests/wire/auth.test.ts
index 1b873110d..2d73e751b 100644
--- a/packages/sdk/tests/wire/auth.test.ts
+++ b/packages/sdk/tests/wire/auth.test.ts
@@ -35,7 +35,7 @@ describe("AuthClient", () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
- const rawResponseBody = { key: "value" };
+ const rawResponseBody = { error: { message: "message" } };
server.mockEndpoint().get("/api/v1/auth/me").respondWith().statusCode(401).jsonBody(rawResponseBody).build();
diff --git a/packages/sdk/tests/wire/mcpServers.test.ts b/packages/sdk/tests/wire/mcpServers.test.ts
index 84ba2aaea..db6eb456c 100644
--- a/packages/sdk/tests/wire/mcpServers.test.ts
+++ b/packages/sdk/tests/wire/mcpServers.test.ts
@@ -5,7 +5,7 @@ import { TrueForge } from "../../src/Client";
import { mockServerPool } from "../mock-server/MockServerPool";
describe("McpServersClient", () => {
- test("list", async () => {
+ test("list (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -30,6 +30,25 @@ describe("McpServersClient", () => {
});
});
+ test("list (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/mcp-servers")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.mcpServers.list();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
test("authorize (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
diff --git a/packages/sdk/tests/wire/models.test.ts b/packages/sdk/tests/wire/models.test.ts
index 253258a8a..9a9217bf2 100644
--- a/packages/sdk/tests/wire/models.test.ts
+++ b/packages/sdk/tests/wire/models.test.ts
@@ -1,10 +1,11 @@
// 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("ModelsClient", () => {
- test("list", async () => {
+ test("list (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -23,4 +24,17 @@ describe("ModelsClient", () => {
],
});
});
+
+ test("list (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server.mockEndpoint().get("/api/v1/models").respondWith().statusCode(401).jsonBody(rawResponseBody).build();
+
+ await expect(async () => {
+ return await client.models.list();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
});
diff --git a/packages/sdk/tests/wire/server.test.ts b/packages/sdk/tests/wire/server.test.ts
index ac33ea6d2..e7fd48fa5 100644
--- a/packages/sdk/tests/wire/server.test.ts
+++ b/packages/sdk/tests/wire/server.test.ts
@@ -1,10 +1,11 @@
// 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("ServerClient", () => {
- test("get_capabilities", async () => {
+ test("get_capabilities (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -40,4 +41,23 @@ describe("ServerClient", () => {
},
});
});
+
+ test("get_capabilities (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/capabilities")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.server.getCapabilities();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
});
diff --git a/packages/sdk/tests/wire/settings/mcpServers.test.ts b/packages/sdk/tests/wire/settings/mcpServers.test.ts
index 82302936e..863ff2ccf 100644
--- a/packages/sdk/tests/wire/settings/mcpServers.test.ts
+++ b/packages/sdk/tests/wire/settings/mcpServers.test.ts
@@ -5,7 +5,7 @@ import { TrueForge } from "../../../src/Client";
import { mockServerPool } from "../../mock-server/MockServerPool";
describe("McpServersClient", () => {
- test("list", async () => {
+ test("list (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -47,6 +47,44 @@ describe("McpServersClient", () => {
});
});
+ test("list (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/mcp-servers")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.mcpServers.list();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("list (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/mcp-servers")
+ .respondWith()
+ .statusCode(403)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.mcpServers.list();
+ }).rejects.toThrow(TrueForgeTypes.ForbiddenError);
+ });
+
test("upsert (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -136,7 +174,7 @@ describe("McpServersClient", () => {
}).rejects.toThrow(TrueForgeTypes.UnprocessableEntityError);
});
- test("catalog", async () => {
+ test("catalog (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -168,6 +206,44 @@ describe("McpServersClient", () => {
});
});
+ test("catalog (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/mcp-servers/catalog")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.mcpServers.catalog();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("catalog (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/mcp-servers/catalog")
+ .respondWith()
+ .statusCode(403)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.mcpServers.catalog();
+ }).rejects.toThrow(TrueForgeTypes.ForbiddenError);
+ });
+
test("get (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -254,7 +330,7 @@ describe("McpServersClient", () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
- const rawResponseBody = { key: "value" };
+ const rawResponseBody = { error: { message: "message" } };
server
.mockEndpoint()
diff --git a/packages/sdk/tests/wire/settings/modelProviders.test.ts b/packages/sdk/tests/wire/settings/modelProviders.test.ts
index b6a86f757..37f336039 100644
--- a/packages/sdk/tests/wire/settings/modelProviders.test.ts
+++ b/packages/sdk/tests/wire/settings/modelProviders.test.ts
@@ -5,7 +5,7 @@ import { TrueForge } from "../../../src/Client";
import { mockServerPool } from "../../mock-server/MockServerPool";
describe("ModelProvidersClient", () => {
- test("list", async () => {
+ test("list (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -51,6 +51,44 @@ describe("ModelProvidersClient", () => {
});
});
+ test("list (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/model-providers")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.modelProviders.list();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("list (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/model-providers")
+ .respondWith()
+ .statusCode(403)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.modelProviders.list();
+ }).rejects.toThrow(TrueForgeTypes.ForbiddenError);
+ });
+
test("upsert (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -154,7 +192,7 @@ describe("ModelProvidersClient", () => {
}).rejects.toThrow(TrueForgeTypes.BadRequestError);
});
- test("catalog", async () => {
+ test("catalog (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -195,4 +233,42 @@ describe("ModelProvidersClient", () => {
],
});
});
+
+ test("catalog (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/model-providers/catalog")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.modelProviders.catalog();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("catalog (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/model-providers/catalog")
+ .respondWith()
+ .statusCode(403)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.modelProviders.catalog();
+ }).rejects.toThrow(TrueForgeTypes.ForbiddenError);
+ });
});
diff --git a/packages/sdk/tests/wire/settings/sandboxProviders.test.ts b/packages/sdk/tests/wire/settings/sandboxProviders.test.ts
index f8471578e..bc54c3465 100644
--- a/packages/sdk/tests/wire/settings/sandboxProviders.test.ts
+++ b/packages/sdk/tests/wire/settings/sandboxProviders.test.ts
@@ -161,7 +161,7 @@ describe("SandboxProvidersClient", () => {
}).rejects.toThrow(TrueForgeTypes.BadRequestError);
});
- test("catalog", async () => {
+ test("catalog (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -200,4 +200,42 @@ describe("SandboxProvidersClient", () => {
],
});
});
+
+ test("catalog (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/sandbox-providers/catalog")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.sandboxProviders.catalog();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("catalog (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/sandbox-providers/catalog")
+ .respondWith()
+ .statusCode(403)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.sandboxProviders.catalog();
+ }).rejects.toThrow(TrueForgeTypes.ForbiddenError);
+ });
});
diff --git a/packages/sdk/tests/wire/settings/skills.test.ts b/packages/sdk/tests/wire/settings/skills.test.ts
index f0dce3a55..d6b6084d6 100644
--- a/packages/sdk/tests/wire/settings/skills.test.ts
+++ b/packages/sdk/tests/wire/settings/skills.test.ts
@@ -5,7 +5,7 @@ import { TrueForge } from "../../../src/Client";
import { mockServerPool } from "../../mock-server/MockServerPool";
describe("SkillsClient", () => {
- test("list", async () => {
+ test("list (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -36,6 +36,44 @@ describe("SkillsClient", () => {
});
});
+ test("list (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/skills")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.skills.list();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("list (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/skills")
+ .respondWith()
+ .statusCode(403)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.skills.list();
+ }).rejects.toThrow(TrueForgeTypes.ForbiddenError);
+ });
+
test("upsert (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -98,7 +136,7 @@ describe("SkillsClient", () => {
}).rejects.toThrow(TrueForgeTypes.BadRequestError);
});
- test("catalog", async () => {
+ test("catalog (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -128,4 +166,42 @@ describe("SkillsClient", () => {
],
});
});
+
+ test("catalog (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/skills/catalog")
+ .respondWith()
+ .statusCode(401)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.skills.catalog();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
+
+ test("catalog (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .get("/api/v1/settings/skills/catalog")
+ .respondWith()
+ .statusCode(403)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.settings.skills.catalog();
+ }).rejects.toThrow(TrueForgeTypes.ForbiddenError);
+ });
});
diff --git a/packages/sdk/tests/wire/skills.test.ts b/packages/sdk/tests/wire/skills.test.ts
index 8d3dd7016..3435c4997 100644
--- a/packages/sdk/tests/wire/skills.test.ts
+++ b/packages/sdk/tests/wire/skills.test.ts
@@ -1,10 +1,11 @@
// 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("SkillsClient", () => {
- test("list", async () => {
+ test("list (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
@@ -22,4 +23,17 @@ describe("SkillsClient", () => {
],
});
});
+
+ test("list (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+
+ const rawResponseBody = { error: { message: "message" } };
+
+ server.mockEndpoint().get("/api/v1/skills").respondWith().statusCode(401).jsonBody(rawResponseBody).build();
+
+ await expect(async () => {
+ return await client.skills.list();
+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);
+ });
});
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index f8172cac4..4bc5ebcd3 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -38,9 +38,15 @@ import { zodErrorResponse, zodValidationHook } from './zodErrorResponse';
const openApiDocConfig = {
openapi: '3.1.0',
info: {
- title: 'Agent Server',
+ title: 'TrueForge API',
description:
- 'Agent server with DB-backed sessions, agent registry, settings catalogs, and model/MCP/skill providers.',
+ 'HTTP API for the TrueForge agent server (`/api/v1`). Interactive docs are served at `/api/v1/docs` ' +
+ '(OpenAPI JSON at `/api/v1/openapi.json`).\n\n' +
+ '**Authentication:** Standalone deployments (no OIDC) accept requests without credentials — middleware ' +
+ 'stamps a local default user. When OIDC is configured, browser login sets an httpOnly `id_token` cookie; ' +
+ 'protected routes read that cookie (not `Authorization: Bearer`). There is no built-in API-key scheme; ' +
+ 'pass custom headers only if your reverse proxy or IdP layer requires them.\n\n' +
+ 'Covers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.',
version: '0.1.0',
},
};
diff --git a/packages/server/src/routes/agentRoutes.ts b/packages/server/src/routes/agentRoutes.ts
index fbf2ffee9..e71e521ee 100644
--- a/packages/server/src/routes/agentRoutes.ts
+++ b/packages/server/src/routes/agentRoutes.ts
@@ -37,6 +37,10 @@ export const listAgentsRoute = createRoute({
content: { 'application/json': { schema: ListAgentsResponseSchema } },
description: 'All configured agents.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
},
});
@@ -114,6 +118,10 @@ export const deleteAgentRoute = createRoute({
204: {
description: 'Agent deleted.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
},
});
diff --git a/packages/server/src/routes/authRoutes.ts b/packages/server/src/routes/authRoutes.ts
index 85813a654..eec31180a 100644
--- a/packages/server/src/routes/authRoutes.ts
+++ b/packages/server/src/routes/authRoutes.ts
@@ -7,6 +7,7 @@
*/
import { createRoute } from '@hono/zod-openapi';
import { AuthLoginQuerySchema, MeResponseSchema, OAuthCallbackQuerySchema } from '../schemas/auth';
+import { RequestErrorResponseSchema } from '../schemas/errors';
const AUTH_TAG = 'Auth';
@@ -70,6 +71,9 @@ export const meRoute = createRoute({
content: { 'application/json': { schema: MeResponseSchema } },
description: 'Session type and identity for the current request.',
},
- 401: { description: 'OIDC is configured and the request has no valid session cookie.' },
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
},
});
diff --git a/packages/server/src/routes/capabilityRoutes.ts b/packages/server/src/routes/capabilityRoutes.ts
index 1bfe38d76..a8f626038 100644
--- a/packages/server/src/routes/capabilityRoutes.ts
+++ b/packages/server/src/routes/capabilityRoutes.ts
@@ -1,4 +1,5 @@
import { createRoute, z } from '@hono/zod-openapi';
+import { RequestErrorResponseSchema } from '../schemas/errors';
const GetCapabilitiesResponseSchema = z
.object({
@@ -32,5 +33,9 @@ export const getCapabilitiesRoute = createRoute({
content: { 'application/json': { schema: GetCapabilitiesResponseSchema } },
description: 'Server capabilities.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
},
});
diff --git a/packages/server/src/routes/mcpOAuthRoutes.ts b/packages/server/src/routes/mcpOAuthRoutes.ts
index 9e7c40758..5f0abb3bd 100644
--- a/packages/server/src/routes/mcpOAuthRoutes.ts
+++ b/packages/server/src/routes/mcpOAuthRoutes.ts
@@ -9,6 +9,10 @@ export const mcpOAuthCallbackRoute = createRoute({
path: '/callback',
tags: [MCP_OAUTH_TAG],
summary: 'OAuth callback for MCP authorization',
+ description:
+ 'Browser redirect target for MCP server OAuth. The authorization server redirects here with `code`/`state` (or `error`). ' +
+ 'Exchanges the code for tokens, then either returns JSON or redirects to the `redirect_url` supplied at authorize time. ' +
+ '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,
request: {
diff --git a/packages/server/src/routes/mcpServerRoutes.ts b/packages/server/src/routes/mcpServerRoutes.ts
index 8c76da4f9..3bde1f7d2 100644
--- a/packages/server/src/routes/mcpServerRoutes.ts
+++ b/packages/server/src/routes/mcpServerRoutes.ts
@@ -32,6 +32,14 @@ export const getMcpServerCatalogRoute = createRoute({
content: { 'application/json': { schema: GetMcpServerCatalogResponseSchema } },
description: 'The shipped catalog, verbatim.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
+ 403: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the caller is authenticated but not an admin.',
+ },
},
});
@@ -49,6 +57,10 @@ export const listAvailableMcpServersRoute = createRoute({
content: { 'application/json': { schema: ListAvailableMcpServersResponseSchema } },
description: 'All MCP servers (chat projection).',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
},
});
@@ -65,6 +77,14 @@ export const listMcpServersRoute = createRoute({
content: { 'application/json': { schema: ListMcpServersResponseSchema } },
description: 'All MCP servers.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
+ 403: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the caller is authenticated but not an admin.',
+ },
},
});
@@ -129,6 +149,7 @@ export const putMcpServerRoute = createRoute({
const ListMcpServerToolsResponseSchema = z
.object({
+ // TODO: Type tools/list entries to the MCP tool shape (name, description, inputSchema, …) for OpenAPI quality.
data: z
.array(z.record(z.string(), z.unknown()))
.describe('MCP `tools/list` entries, passed through verbatim from the MCP server.'),
diff --git a/packages/server/src/routes/modelProviderRoutes.ts b/packages/server/src/routes/modelProviderRoutes.ts
index 52d366fb5..8b9ef94c9 100644
--- a/packages/server/src/routes/modelProviderRoutes.ts
+++ b/packages/server/src/routes/modelProviderRoutes.ts
@@ -28,6 +28,14 @@ export const getModelProviderCatalogRoute = createRoute({
content: { 'application/json': { schema: GetModelProviderCatalogResponseSchema } },
description: 'The shipped catalog, verbatim.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
+ 403: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the caller is authenticated but not an admin.',
+ },
},
});
@@ -44,6 +52,14 @@ export const listModelProvidersRoute = createRoute({
content: { 'application/json': { schema: ListModelProvidersResponseSchema } },
description: 'All configured model providers.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
+ 403: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the caller is authenticated but not an admin.',
+ },
},
});
diff --git a/packages/server/src/routes/modelRoutes.ts b/packages/server/src/routes/modelRoutes.ts
index 72fa58de6..d89d53bc2 100644
--- a/packages/server/src/routes/modelRoutes.ts
+++ b/packages/server/src/routes/modelRoutes.ts
@@ -1,4 +1,5 @@
import { createRoute } from '@hono/zod-openapi';
+import { RequestErrorResponseSchema } from '../schemas/errors';
import { ListModelsResponseSchema } from '../schemas/modelProvider';
export const listModelsRoute = createRoute({
@@ -14,5 +15,9 @@ export const listModelsRoute = createRoute({
content: { 'application/json': { schema: ListModelsResponseSchema } },
description: 'All models of all configured providers.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
},
});
diff --git a/packages/server/src/routes/sandboxProviderRoutes.ts b/packages/server/src/routes/sandboxProviderRoutes.ts
index a3743fb1e..3b541240b 100644
--- a/packages/server/src/routes/sandboxProviderRoutes.ts
+++ b/packages/server/src/routes/sandboxProviderRoutes.ts
@@ -28,6 +28,14 @@ export const getSandboxProviderCatalogRoute = createRoute({
content: { 'application/json': { schema: GetSandboxProviderCatalogResponseSchema } },
description: 'The shipped catalog, verbatim.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
+ 403: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the caller is authenticated but not an admin.',
+ },
},
});
diff --git a/packages/server/src/routes/skillRoutes.ts b/packages/server/src/routes/skillRoutes.ts
index 31ca0cc64..7ea9ca5d7 100644
--- a/packages/server/src/routes/skillRoutes.ts
+++ b/packages/server/src/routes/skillRoutes.ts
@@ -30,6 +30,14 @@ export const getSkillCatalogRoute = createRoute({
content: { 'application/json': { schema: GetSkillCatalogResponseSchema } },
description: 'The shipped catalog, verbatim.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
+ 403: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the caller is authenticated but not an admin.',
+ },
},
});
@@ -47,6 +55,10 @@ export const listAvailableSkillsRoute = createRoute({
content: { 'application/json': { schema: ListAvailableSkillsResponseSchema } },
description: 'All configured skills (chat projection).',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
},
});
@@ -63,6 +75,14 @@ export const listConfiguredSkillsRoute = createRoute({
content: { 'application/json': { schema: ListConfiguredSkillsResponseSchema } },
description: 'All configured skills.',
},
+ 401: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the request has no valid session cookie.',
+ },
+ 403: {
+ content: { 'application/json': { schema: RequestErrorResponseSchema } },
+ description: 'OIDC is configured and the caller is authenticated but not an admin.',
+ },
},
});
diff --git a/packages/server/src/routes/turnRoutes.ts b/packages/server/src/routes/turnRoutes.ts
index 7aa6013b6..3c1759070 100644
--- a/packages/server/src/routes/turnRoutes.ts
+++ b/packages/server/src/routes/turnRoutes.ts
@@ -260,7 +260,7 @@ export const subscribeTurnRoute = createRoute({
},
400: {
content: { 'application/json': { schema: RequestErrorResponseSchema } },
- description: 'Invalid request body.',
+ description: 'Invalid query parameters.',
},
403: {
content: { 'application/json': { schema: RequestErrorResponseSchema } },
diff --git a/packages/server/src/schemas/auth.ts b/packages/server/src/schemas/auth.ts
index 647db1baa..756c74334 100644
--- a/packages/server/src/schemas/auth.ts
+++ b/packages/server/src/schemas/auth.ts
@@ -18,11 +18,14 @@ export const OAuthCallbackQuerySchema = z.object({
.string()
.optional()
.describe('Error code from the identity provider, present instead of `code` if the user denied consent.'),
- error_description: z.string().optional(),
+ error_description: z
+ .string()
+ .optional()
+ .describe('Human-readable error detail from the identity provider when `error` is set.'),
});
export const OAuthCallbackSuccessSchema = z.object({
- success: z.literal(true),
+ success: z.literal(true).describe('Present when the OAuth callback completed without a redirect_url.'),
});
export const MeResponseSchema = z
diff --git a/packages/server/src/schemas/errors.ts b/packages/server/src/schemas/errors.ts
index 957f13726..5bf9fdd35 100644
--- a/packages/server/src/schemas/errors.ts
+++ b/packages/server/src/schemas/errors.ts
@@ -4,10 +4,18 @@ import { z } from '@hono/zod-openapi';
export const RequestErrorResponseSchema = z
.object({
error: z.object({
- message: z.string(),
- type: z.string().optional(),
- code: z.string().nullable().optional(),
- param: z.string().nullable().optional(),
+ message: z.string().describe('Human-readable explanation of the failure.'),
+ type: z.string().optional().describe('Optional error category (e.g. validation vs conflict).'),
+ code: z
+ .string()
+ .nullable()
+ .optional()
+ .describe('Optional machine-readable error code; null when not applicable.'),
+ param: z
+ .string()
+ .nullable()
+ .optional()
+ .describe('Optional request field that caused the error; null when not field-specific.'),
}),
})
.openapi('RequestErrorResponse');
diff --git a/packages/server/src/schemas/mcpCatalog.ts b/packages/server/src/schemas/mcpCatalog.ts
index 1899f0aee..59e137d8f 100644
--- a/packages/server/src/schemas/mcpCatalog.ts
+++ b/packages/server/src/schemas/mcpCatalog.ts
@@ -9,11 +9,11 @@ import { McpServerAuthSettingsSchema, McpServerTypeSchema } from './mcpServer';
/** Catalog entry — discovery preset the settings UI copies into a PUT body. */
export const CatalogMcpServerSchema = z
.object({
- type: McpServerTypeSchema,
+ type: McpServerTypeSchema.describe('MCP server kind (`remote` today).'),
name: NameSchema,
logo: z.url().optional().describe('URL of the MCP server logo asset.'),
url: z.url().describe('URL of the remote MCP server.'),
- auth: McpServerAuthSettingsSchema.optional(),
+ auth: McpServerAuthSettingsSchema.optional().describe('Optional default auth settings for the preset.'),
})
.strict()
.openapi('CatalogMcpServer');
diff --git a/packages/server/src/schemas/mcpServer.ts b/packages/server/src/schemas/mcpServer.ts
index 5c9683d9f..2c75693fb 100644
--- a/packages/server/src/schemas/mcpServer.ts
+++ b/packages/server/src/schemas/mcpServer.ts
@@ -16,7 +16,7 @@ export const McpServerTypeSchema = z.enum(['remote']).openapi('McpServerType');
const McpServerHeaderAuthSchema = z
.object({
- type: z.literal('header'),
+ type: z.literal('header').describe('Authenticate with static HTTP headers.'),
headers: z
.record(z.string().min(1), z.string().min(1))
.refine(headers => Object.keys(headers).length > 0, {
@@ -30,7 +30,7 @@ const McpServerHeaderAuthSchema = z
/** OAuth Dynamic Client Registration — stub until authorize/token exchange is wired. */
const McpServerDcrAuthSchema = z
.object({
- type: z.literal('dcr'),
+ type: z.literal('dcr').describe('Authenticate via OAuth Dynamic Client Registration.'),
})
.strict()
.openapi('McpServerDcrAuth');
@@ -42,10 +42,12 @@ export const McpServerAuthSettingsSchema = z
/** Configured MCP server document persisted as `mcp_server.manifest`. */
export const McpServerManifestObjectSchema = z
.object({
- type: McpServerTypeSchema,
+ type: McpServerTypeSchema.describe('MCP server kind (`remote` today).'),
name: NameSchema,
url: z.url().describe('URL of the remote MCP server.'),
- auth: McpServerAuthSettingsSchema.optional(),
+ auth: McpServerAuthSettingsSchema.optional().describe(
+ 'Optional auth settings. Omit when the server needs no credentials.',
+ ),
})
.strict();
@@ -53,7 +55,9 @@ export const McpServerManifestSchema = McpServerManifestObjectSchema.openapi('Mc
export const McpAuthStatusSchema = z
.object({
- status: z.enum(['authenticated', 'auth_required', 'not_required']),
+ status: z
+ .enum(['authenticated', 'auth_required', 'not_required'])
+ .describe('Current auth state for this MCP server.'),
authorization_url: z
.url()
.optional()
@@ -78,7 +82,7 @@ export const ListMcpServersResponseSchema = z
export const McpServerReadEntrySchema = z
.object({
name: NameSchema,
- url: z.url(),
+ url: z.url().describe('URL of the remote MCP server.'),
})
.strict()
.openapi('McpServerReadEntry');
diff --git a/packages/server/src/schemas/modelCatalog.ts b/packages/server/src/schemas/modelCatalog.ts
index bab326859..034880da9 100644
--- a/packages/server/src/schemas/modelCatalog.ts
+++ b/packages/server/src/schemas/modelCatalog.ts
@@ -9,10 +9,10 @@ import { ModelEntrySchema, ProviderTypeSchema, refineUniqueModels } from './mode
/** Catalog entry: no `custom` providers — those exist only as tenant configuration. */
export const CatalogProviderSchema = z
.object({
- type: ProviderTypeSchema.exclude(['custom']),
+ type: ProviderTypeSchema.exclude(['custom']).describe('Well-known provider type (catalog excludes `custom`).'),
name: NameSchema,
logo: z.url().optional().describe('URL of the provider logo asset.'),
- models: z.array(ModelEntrySchema).min(1),
+ models: z.array(ModelEntrySchema).min(1).describe('Preset models for this catalog provider.'),
})
.strict()
.openapi('CatalogProvider');
diff --git a/packages/server/src/schemas/modelProvider.ts b/packages/server/src/schemas/modelProvider.ts
index 4857379bf..8b952ded0 100644
--- a/packages/server/src/schemas/modelProvider.ts
+++ b/packages/server/src/schemas/modelProvider.ts
@@ -18,9 +18,13 @@ export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
export const ModelPropertiesSchema = z
.object({
- context_length: z.number().int().positive().optional(),
- max_output_tokens: z.number().int().positive().optional(),
- reasoning_efforts: z.array(ReasoningEffortSchema).min(1).optional(),
+ context_length: z.number().int().positive().optional().describe('Maximum context window size in tokens.'),
+ max_output_tokens: z.number().int().positive().optional().describe('Maximum output tokens the model can generate.'),
+ reasoning_efforts: z
+ .array(ReasoningEffortSchema)
+ .min(1)
+ .optional()
+ .describe('Supported reasoning-effort values for this model.'),
})
.strict()
.openapi('ModelProperties');
@@ -29,7 +33,7 @@ export const ModelEntrySchema = z
.object({
model_id: z.string().min(1).describe('Upstream, provider-specific identifier sent to the provider API.'),
name: NameSchema.describe('Internal identifier; forms the fully qualified name `name/model_name`.'),
- properties: ModelPropertiesSchema,
+ properties: ModelPropertiesSchema.describe('Optional model capability metadata.'),
})
.strict()
.openapi('ModelEntry');
@@ -52,15 +56,15 @@ export function refineUniqueModels(models: { model_id: string; name: string }[],
const ModelProviderAuthSchema = z
.object({
- api_key: z.string().min(1),
+ api_key: z.string().min(1).describe('API key used to authenticate with the provider.'),
})
.strict()
.openapi('ModelProviderAuth');
const ModelProviderManifestBaseSchema = z
.object({
- auth: ModelProviderAuthSchema,
- models: z.array(ModelEntrySchema).min(1),
+ auth: ModelProviderAuthSchema.describe('Provider authentication credentials.'),
+ models: z.array(ModelEntrySchema).min(1).describe('Models exposed by this provider (at least one).'),
})
.strict();
@@ -181,7 +185,7 @@ export const ModelSchema = z
.string()
.describe('Fully qualified name `provider_name/model_name`, e.g. "openai/gpt-5-6-sol". Unique within a tenant.'),
model_id: z.string().describe('Upstream, provider-specific identifier sent to the provider API.'),
- properties: ModelPropertiesSchema,
+ properties: ModelPropertiesSchema.describe('Optional model capability metadata.'),
})
.strict()
.openapi('Model');
diff --git a/packages/server/src/schemas/sandboxProvider.ts b/packages/server/src/schemas/sandboxProvider.ts
index a5df0e89a..77a652635 100644
--- a/packages/server/src/schemas/sandboxProvider.ts
+++ b/packages/server/src/schemas/sandboxProvider.ts
@@ -10,7 +10,7 @@ import type { DaytonaSandboxProviderOptions } from '@truefoundry/utils-core/core
const DaytonaSandboxProviderAuthSchema = z
.object({
- api_key: z.string().min(1),
+ api_key: z.string().min(1).describe('Daytona API key.'),
})
.strict()
.openapi('DaytonaSandboxProviderAuth');
@@ -21,13 +21,25 @@ const DaytonaSandboxProviderAuthSchema = z
*/
export const DaytonaSandboxProviderSchema = z
.object({
- type: z.literal('daytona'),
+ type: z.literal('daytona').describe('Daytona sandbox provider.'),
snapshot_name: z.string().min(1).describe('Daytona snapshot used when creating sandboxes.'),
- auth: DaytonaSandboxProviderAuthSchema,
+ auth: DaytonaSandboxProviderAuthSchema.describe('Daytona authentication credentials.'),
exec_timeout_ms: z.number().int().positive().describe('Default sandbox command exec timeout in milliseconds.'),
- auto_stop_interval_in_minutes: z.number().int().nonnegative(),
- auto_archive_interval_in_minutes: z.number().int().nonnegative(),
- auto_delete_interval_in_minutes: z.number().int().nonnegative(),
+ auto_stop_interval_in_minutes: z
+ .number()
+ .int()
+ .nonnegative()
+ .describe('Minutes of idle time before Daytona auto-stops the sandbox (0 disables).'),
+ auto_archive_interval_in_minutes: z
+ .number()
+ .int()
+ .nonnegative()
+ .describe('Minutes before Daytona auto-archives the sandbox (0 disables).'),
+ auto_delete_interval_in_minutes: z
+ .number()
+ .int()
+ .nonnegative()
+ .describe('Minutes before Daytona auto-deletes the sandbox (0 disables).'),
})
.strict()
.openapi('DaytonaSandboxProvider');
diff --git a/packages/server/src/schemas/session.ts b/packages/server/src/schemas/session.ts
index 0639c83f6..fb04ee8fe 100644
--- a/packages/server/src/schemas/session.ts
+++ b/packages/server/src/schemas/session.ts
@@ -27,13 +27,17 @@ export function isSessionAgentNameRef(agent: CreateSessionAgent): agent is Sessi
}
export const CreateSessionRequestSchema = z
- .object({ agent: CreateSessionAgentSchema })
+ .object({
+ agent: CreateSessionAgentSchema,
+ })
.strict()
.openapi('CreateSessionRequest');
/** Only inline sessions may be updated; named (reference) sessions reject agent updates. */
export const UpdateSessionRequestSchema = z
- .object({ agent: SessionAgentSpecBodySchema.optional() })
+ .object({
+ agent: SessionAgentSpecBodySchema.optional(),
+ })
.strict()
.openapi('UpdateSessionRequest');
diff --git a/packages/server/src/schemas/turn.ts b/packages/server/src/schemas/turn.ts
index 6a8c41007..94810ed88 100644
--- a/packages/server/src/schemas/turn.ts
+++ b/packages/server/src/schemas/turn.ts
@@ -11,13 +11,28 @@ export const SubscribeTurnQuerySchema = z
// cannot silently become a resume cursor (and so OpenAPI does not advertise null).
after_sequence_number: z.preprocess(
val => (val === null || val === '' ? undefined : val),
- z.coerce.number().int().nonnegative().optional(),
+ z.coerce
+ .number()
+ .int()
+ .nonnegative()
+ .optional()
+ .describe(
+ 'Exclusive resume cursor: replay only events with a sequence number greater than this value. Omit to start from the beginning of the live buffer.',
+ ),
),
})
.openapi('SubscribeTurnQuery');
-export const CancelSessionRequestSchema = z.object({}).openapi('CancelSessionRequest');
-export const CancelSessionResponseSchema = z.object({}).openapi('CancelSessionResponse');
+/** Intentionally empty — cancel takes no body fields. */
+export const CancelSessionRequestSchema = z
+ .object({})
+ .describe('Empty request body. Cancel identifies the session via the path only.')
+ .openapi('CancelSessionRequest');
+/** Intentionally empty — success is signaled by HTTP 200 with `{}`. */
+export const CancelSessionResponseSchema = z
+ .object({})
+ .describe('Empty success body. HTTP 200 means the cancel request was accepted (or nothing was running).')
+ .openapi('CancelSessionResponse');
export const DEFAULT_TURNS_LIMIT = 10;
export const TURNS_MAX_LIMIT = 100;