@octavus/docs 3.6.0 → 4.0.0

package/content/02-server-sdk/09-inline-mcp.md

@@ -106,6 +106,36 @@ tools: {
 
 The handler also receives Zod-validated arguments. Invalid inputs throw before reaching your code, with the failed paths and messages joined into the error.
 
+## Declaring an Output Schema
+
+`defineInlineMcpTool()` accepts an optional `output` Zod schema. When provided, two things happen:
+
+1. The schema is converted to JSON Schema and forwarded to the LLM as `outputSchema`. Providers that support structured tool outputs (e.g. OpenAI strict mode) can use it to validate the tool result they reason over.
+2. Handler return values are validated against the schema at runtime. A handler returning a malformed result throws before the result reaches the LLM, with the failed paths and messages joined into the error.
+
+```typescript
+'get-pr-overview': defineInlineMcpTool({
+  description: 'Get pull request metadata and file changes',
+  parameters: z.object({
+    owner: z.string(),
+    repo: z.string(),
+    pullNumber: z.number(),
+  }),
+  output: z.object({
+    title: z.string(),
+    state: z.enum(['open', 'closed', 'merged']),
+    additions: z.number(),
+    deletions: z.number(),
+  }),
+  handler: async (args) => {
+    // Return type is type-checked against the `output` schema.
+    return await githubService.getPrOverview(args.owner, args.repo, args.pullNumber);
+  },
+}),
+```
+
+Omitting `output` preserves the previous behavior - the handler return type is unconstrained and the LLM sees no `outputSchema` on the tool.
+
 ## Attaching to a Session
 
 Pass inline MCP servers via `mcpServers` on `attach()`. They merge with `tools` and survive across `setDynamicTools()` calls:

package/content/03-client-sdk/02-messages.md

@@ -33,7 +33,8 @@ type UIMessagePart =
   | UIFilePart
   | UIObjectPart
   | UITodoPart
-  | UIWorkerPart;
+  | UIWorkerPart
+  | UIStepStartPart;
 
 // Text content
 interface UITextPart {
@@ -60,7 +61,7 @@ interface UIToolCallPart {
   args: Record<string, unknown>;
   result?: unknown;
   error?: string;
-  status: 'pending' | 'running' | 'done' | 'error';
+  status: 'pending' | 'running' | 'done' | 'error' | 'cancelled';
   thread?: string;
 }
 
@@ -134,6 +135,11 @@ interface UIWorkerPart {
   error?: string;
   status: 'running' | 'done' | 'error';
 }
+
+// Step boundary marker (structural, not rendered visually)
+interface UIStepStartPart {
+  type: 'step-start';
+}
 ```
 
 ## Sending Messages
@@ -316,6 +322,9 @@ function PartRenderer({ part }: { part: UIMessagePart }) {
       // See Structured Output guide for more details
       return <ObjectPartRenderer part={part} />;
 
+    case 'step-start':
+      return null;
+
     default:
       return null;
   }

package/content/05-api-reference/01-overview.md

@@ -24,6 +24,23 @@ curl -H "Authorization: Bearer YOUR_API_KEY" \
 
 API keys can be created in the Octavus Platform under your project's **API Keys** page.
 
+## Wire-Format Versioning
+
+The platform negotiates wire shape via the `X-Octavus-Sdk-Version` header. The Server SDK sets this automatically; direct API users only need to send it when they want the latest format.
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "X-Octavus-Sdk-Version: 4" \
+  https://octavus.ai/api/agent-sessions/SESSION_ID
+```
+
+| Header value | Wire shape                                                                                               |
+| ------------ | -------------------------------------------------------------------------------------------------------- |
+| (missing)    | Legacy (v3) - matches `@octavus/server-sdk@^3`                                                           |
+| `4`          | Current (v4) - matches `@octavus/server-sdk@^4`. Adds `step-start` parts to `UIMessage` / `ChatMessage`. |
+
+The header value is the major version the client can parse, not the SDK release version. Future wire-incompatible additions bump it again.
+
 ## API Key Permissions
 
 API keys have two permission scopes: