@octavus/docs 3.3.0 → 3.5.0

package/content/02-server-sdk/02-sessions.md

@@ -75,6 +75,67 @@ console.log({
 
 > **Note**: Use `getMessages()` for client-facing code. The `get()` method returns internal message format that includes hidden content not intended for end users.
 
+## Getting Execution Logs
+
+`getLogs()` returns the chronological execution trace for a session - triggers, messages, tool calls, LLM responses, errors, and other events emitted while the agent ran. Useful for debugging, observability, and building custom timeline views.
+
+```typescript
+const result = await client.agentSessions.getLogs(sessionId);
+
+if (result.status === 'expired') {
+  console.log('Session expired:', result.sessionId);
+} else {
+  for (const entry of result.entries) {
+    console.log(entry.type, entry.timestamp);
+  }
+}
+```
+
+Each entry is a typed variant of `ExecutionLogEntry` (a discriminated union) so consumers can narrow on `entry.type`:
+
+```typescript
+const result = await client.agentSessions.getLogs(sessionId);
+
+if (result.status !== 'expired') {
+  const toolCalls = result.entries.filter((e) => e.type === 'tool-call');
+  for (const call of toolCalls) {
+    // call.toolName, call.toolArguments are typed without optional chaining
+    console.log(call.toolName, call.toolArguments);
+  }
+}
+```
+
+### Excluding Model Request Payloads
+
+Model-request entries include the full provider request body and can be large. Pass `excludeModelRequests: true` to skip them:
+
+```typescript
+const result = await client.agentSessions.getLogs(sessionId, {
+  excludeModelRequests: true,
+});
+```
+
+### Truncation
+
+Responses are capped at 1000 entries (most recent). When the log exceeds that cap, the response includes `total` and `truncated` so consumers can detect this:
+
+```typescript
+const result = await client.agentSessions.getLogs(sessionId);
+
+if (result.status !== 'expired' && result.truncated) {
+  console.warn(`Showing latest 1000 of ${result.total} entries`);
+}
+```
+
+### Response Types
+
+| Status    | Type                  | Description                                                                                  |
+| --------- | --------------------- | -------------------------------------------------------------------------------------------- |
+| `active`  | `ExecutionLogsResult` | `{ sessionId, entries, total?, truncated? }`. `total` and `truncated` are present when known |
+| `expired` | `ExpiredSessionState` | `{ sessionId, agentId, status: 'expired', createdAt }`                                       |
+
+> **Forward-compatible types**: `ExecutionLogEntry` may gain new variants over time. Include a `default` case when switching on `entry.type` so unknown variants are handled gracefully.
+
 ## Attaching to Sessions
 
 To trigger actions on a session, you need to attach to it first:

package/content/02-server-sdk/03-tools.md

@@ -9,18 +9,19 @@ Tools extend what agents can do. In Octavus, tools can execute either on your se
 
 ## Server Tools vs Client Tools
 
-| Location   | Use Case                                          | Registration                                     |
-| ---------- | ------------------------------------------------- | ------------------------------------------------ |
-| **Server** | Database queries, API calls, sensitive operations | Register handler in `attach()`                   |
-| **MCP**    | Browser, filesystem, shell, external services     | Via `session.setDynamicTools()` after `attach()` |
-| **Client** | Browser APIs, interactive UIs, confirmations      | No server handler (forwarded to client)          |
+| Location       | Use Case                                          | Registration                                             |
+| -------------- | ------------------------------------------------- | -------------------------------------------------------- |
+| **Server**     | Database queries, API calls, sensitive operations | Register handler in `attach()`                           |
+| **Inline MCP** | Group an integration's tools (GitHub, Salesforce) | [`createInlineMcpServer()`](/docs/server-sdk/inline-mcp) |
+| **Computer**   | Browser, filesystem, shell, external services     | [`session.setDynamicTools()`](/docs/server-sdk/computer) |
+| **Client**     | Browser APIs, interactive UIs, confirmations      | No server handler (forwarded to client)                  |
 
 When the Server SDK encounters a tool call:
 
-1. **Handler exists** (server or dynamic) → Execute on server, continue automatically
+1. **Handler exists** (server, inline MCP, or dynamic) → Execute on server, continue automatically
 2. **No handler** → Forward to client via `client-tool-request` event
 
-MCP tool handlers registered via `session.setDynamicTools()` (e.g., from `@octavus/computer`) work identically to manual handlers from the platform's perspective. See [Computer](/docs/server-sdk/computer) for MCP tool integration.
+Inline MCP tools and dynamic tools registered via `session.setDynamicTools()` (e.g., from `@octavus/computer`) work identically to manual handlers from the platform's perspective. See [Inline MCP Servers](/docs/server-sdk/inline-mcp) for namespaced consumer-defined tool groups, and [Computer](/docs/server-sdk/computer) for device-side MCPs.
 
 For client-side tool handling, see [Client Tools](/docs/client-sdk/client-tools).
 

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

@@ -0,0 +1,204 @@
+---
+title: Inline MCP Servers
+description: Group an integration's tools into a Zod-typed bundle that runs in your server process.
+---
+
+# Inline MCP Servers
+
+Inline MCP servers let you group an integration's tools (e.g., GitHub, Salesforce, an internal microservice) into a namespaced bundle with Zod-typed handler arguments. The tools execute in your server process via the same tool-request/continue path as ordinary [server tools](/docs/server-sdk/tools), so authentication and credentials stay in your process.
+
+## When to Use
+
+Use an inline MCP server when:
+
+- You're integrating a third-party API and want a logical grouping (`github__list-prs`, `github__get-issue`).
+- You want type-safe handler arguments instead of casting `args` from `unknown`.
+- You want to evolve the toolset without protocol-yaml round trips - tool names and schemas are sent at runtime.
+- Tool calls need credentials your platform should never see (OAuth tokens, customer API keys).
+
+For comparison with the other tool registration paths, see the [tools overview](/docs/server-sdk/tools#server-tools-vs-client-tools).
+
+## Protocol Declaration
+
+Declare the namespace in `protocol.yaml` with `source: consumer`. The platform learns the namespace and routes tool calls to your process; tool names and JSON schemas are provided by the SDK at runtime.
+
+```yaml
+mcpServers:
+  github:
+    description: Repository management - issues, pull requests, code
+    source: consumer
+    display: name
+
+agent:
+  mcpServers:
+    - github
+```
+
+See [MCP Servers in the protocol reference](/docs/protocol/mcp-servers) for the full set of MCP source types and field semantics.
+
+## Defining the Server
+
+```typescript
+import { z } from 'zod';
+import { createInlineMcpServer, defineInlineMcpTool } from '@octavus/server-sdk';
+
+const github = createInlineMcpServer('github', {
+  tools: {
+    'get-pr-overview': defineInlineMcpTool({
+      description: 'Get pull request metadata and file changes',
+      parameters: z.object({
+        owner: z.string(),
+        repo: z.string(),
+        pullNumber: z.number(),
+      }),
+      handler: async (args) => {
+        // args is { owner: string; repo: string; pullNumber: number }
+        return await githubService.getPrOverview(args.owner, args.repo, args.pullNumber);
+      },
+    }),
+
+    'list-issues': defineInlineMcpTool({
+      description: 'List open issues for a repository',
+      parameters: z.object({
+        owner: z.string(),
+        repo: z.string(),
+        state: z.enum(['open', 'closed', 'all']).default('open'),
+      }),
+      handler: async (args) => {
+        return await githubService.listIssues(args.owner, args.repo, args.state);
+      },
+    }),
+  },
+});
+```
+
+The factory:
+
+1. Validates the namespace and each tool name (see [naming rules](#naming-rules)).
+2. Converts each Zod schema to JSON Schema once at creation time.
+3. Returns an `InlineMcpServer` exposing `toolSchemas()` and `toolHandlers()`.
+
+The resulting tool names are namespaced: `github__get-pr-overview`, `github__list-issues`.
+
+## Why `defineInlineMcpTool`
+
+`defineInlineMcpTool()` is a no-op at runtime, but it preserves Zod type inference. Without the wrapper, TypeScript collapses the per-tool generic when the tools are placed in a record literal, leaving `args` typed as `unknown`:
+
+```typescript
+// Without defineInlineMcpTool - args ends up as `unknown`
+tools: {
+  'get-pr-overview': {
+    description: '...',
+    parameters: z.object({ owner: z.string() }),
+    handler: async (args) => args.owner, // ❌ TS error: args is 'unknown'
+  },
+}
+
+// With defineInlineMcpTool - args inferred from the schema
+tools: {
+  'get-pr-overview': defineInlineMcpTool({
+    description: '...',
+    parameters: z.object({ owner: z.string() }),
+    handler: async (args) => args.owner, // ✓ args is { owner: string }
+  }),
+}
+```
+
+The handler also receives Zod-validated arguments. Invalid inputs throw before reaching your code, with the failed paths and messages joined into the error.
+
+## Attaching to a Session
+
+Pass inline MCP servers via `mcpServers` on `attach()`. They merge with `tools` and survive across `setDynamicTools()` calls:
+
+```typescript
+const session = client.agentSessions.attach(sessionId, {
+  tools: {
+    'get-user-account': async (args) => db.users.findById(args.userId as string),
+  },
+  mcpServers: [github, salesforce],
+});
+```
+
+Workers accept the same option:
+
+```typescript
+const { output } = await client.workers.generate(agentId, input, {
+  mcpServers: [github],
+});
+```
+
+## Authentication and Credentials
+
+Handlers close over your server's auth context, so credentials never leave your process. The platform receives the namespaced schema list and the tool call name; it never sees the keys you use to fulfill the call.
+
+A common pattern is to build the MCP server per-request when auth depends on the user:
+
+```typescript
+function buildGithubMcp(token: string) {
+  const client = new GithubClient({ token });
+  return createInlineMcpServer('github', {
+    tools: {
+      'get-pr-overview': defineInlineMcpTool({
+        description: 'Get pull request metadata and file changes',
+        parameters: z.object({
+          owner: z.string(),
+          repo: z.string(),
+          pullNumber: z.number(),
+        }),
+        handler: async (args) => client.pulls.get(args),
+      }),
+    },
+  });
+}
+
+export async function POST(request: Request) {
+  const user = await authenticate(request);
+  const session = client.agentSessions.attach(sessionId, {
+    mcpServers: [buildGithubMcp(user.githubToken)],
+  });
+
+  const events = session.execute(payload, { signal: request.signal });
+  return new Response(toSSEStream(events));
+}
+```
+
+For static credentials (one tenant per deployment), build the server once at module scope.
+
+## How Tool Calls Flow
+
+1. The agent emits a `tool-request` event for `github__get-pr-overview` (or another inline-MCP-namespaced tool).
+2. The Server SDK looks up the handler registered by `createInlineMcpServer()` and runs it. Zod validates `args` against the tool's schema; a validation failure becomes a tool error sent back to the LLM.
+3. The handler returns; the SDK posts the result back to the platform via the same continuation request used for ordinary server tools.
+4. The platform feeds the result to the LLM and streams the next response chunk.
+
+There is no separate transport - inline MCP tools ride on the same `dynamicToolSchemas` channel that device MCPs use, so no additional infrastructure is required.
+
+## Naming Rules
+
+`createInlineMcpServer()` validates the namespace and each tool name at construction time. Invalid values throw immediately:
+
+- **Namespace:** lowercase letters, digits, and hyphens; must start with a letter (`/^[a-z][a-z0-9-]*$/`).
+- **Tool name:** lowercase letters, digits, underscores, and hyphens; must start with a letter (`/^[a-z][a-z0-9_-]*$/`).
+
+The resulting `${namespace}__${toolName}` is what the LLM sees and what flows through the platform's MCP routing.
+
+## Collision Rules
+
+The resolver throws on the following conflicts so problems surface at attach time, not mid-stream:
+
+- Each inline MCP server's `namespace` must be unique across the array passed to `attach()` or the workers API.
+- A namespaced tool name (`namespace__tool`) cannot collide with a static tool handler key passed via `tools`.
+- A namespaced tool name cannot collide with a `dynamicToolSchemas` entry passed to the workers API.
+
+If a tool registered via `setDynamicTools()` later collides with an inline MCP tool name, the dynamic handler wins for the duration of that dynamic-tool set; the inline MCP handler is restored on the next `setDynamicTools()` call that doesn't re-register the same name.
+
+## Inline vs Computer
+
+Both inline MCP and the `Computer` integration register tools that flow through `dynamicToolSchemas`. Pick based on where the tool process runs:
+
+| Tool surface | Process location                 | Best for                                                                                                      |
+| ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Inline MCP   | Your server (in-process closure) | Third-party APIs, internal microservices, anything where credentials live in your backend.                    |
+| Computer     | The agent's machine (STDIO MCP)  | Browser automation, filesystem, shell - device-local capabilities. See [Computer](/docs/server-sdk/computer). |
+
+The two can coexist on the same session.

package/content/04-protocol/13-mcp-servers.md

@@ -7,12 +7,13 @@ description: Connecting agents to external tools via Model Context Protocol (MCP
 
 MCP servers extend your agent with tools from external services. Define them in your protocol, and agents automatically discover and use their tools at runtime.
 
-There are two types of MCP servers:
+There are three types of MCP servers:
 
-| Source   | Description                                                        | Example                        |
-| -------- | ------------------------------------------------------------------ | ------------------------------ |
-| `remote` | HTTP-based MCP servers, managed by the platform                    | Figma, Sentry, GitHub          |
-| `device` | Local MCP servers running on the consumer's machine via server-sdk | Browser automation, filesystem |
+| Source     | Description                                                                         | Example                               |
+| ---------- | ----------------------------------------------------------------------------------- | ------------------------------------- |
+| `remote`   | HTTP-based MCP servers, managed by the platform                                     | Figma, Sentry, GitHub                 |
+| `device`   | Local MCP servers running on the agent's machine via `@octavus/computer`            | Browser automation, filesystem        |
+| `consumer` | Inline MCP servers defined in your server-sdk process via `createInlineMcpServer()` | Custom integrations, third-party APIs |
 
 ## Defining MCP Servers
 
@@ -29,17 +30,22 @@ mcpServers:
     description: Chrome DevTools browser automation
     source: device
     display: name
+
+  github:
+    description: Repository management - issues, pull requests, code
+    source: consumer
+    display: name
 ```
 
 ### Fields
 
-| Field         | Required | Description                                                                                             |
-| ------------- | -------- | ------------------------------------------------------------------------------------------------------- |
-| `description` | Yes      | What the MCP server provides                                                                            |
-| `source`      | Yes      | `remote` (platform-managed) or `device` (consumer-provided)                                             |
-| `display`     | No       | How tool calls appear in UI: `hidden`, `name`, `description` (default: `description`)                   |
-| `connection`  | No       | When to connect: `eager` or `lazy` (default: `lazy`). Remote only.                                      |
-| `execution`   | No       | Where the MCP process runs: `sandbox` (default) or `device`. See [Device Execution](#device-execution). |
+| Field         | Required | Description                                                                                                            |
+| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `description` | Yes      | What the MCP server provides                                                                                           |
+| `source`      | Yes      | `remote`, `device`, or `consumer` (see source types above)                                                             |
+| `display`     | No       | How tool calls appear in UI: `hidden`, `name`, `description` (default: `description`)                                  |
+| `connection`  | No       | When to connect: `eager` or `lazy` (default: `lazy`). `remote` only.                                                   |
+| `execution`   | No       | Where the MCP process runs: `sandbox` (default) or `device`. `remote` only. See [Device Execution](#device-execution). |
 
 ### Display Modes
 
@@ -122,9 +128,13 @@ Device MCP tools (auto-discovered):
   filesystem__read_file
   filesystem__write_file
   filesystem__list_directory
+
+Consumer MCP tools (provided by the server-sdk):
+  github__get-pr-overview
+  github__list-issues
 ```
 
-You don't define individual MCP tool schemas in the protocol - they're auto-discovered from each MCP server at runtime.
+You don't define individual MCP tool schemas in the protocol - remote and device tools are auto-discovered from each MCP server at runtime, and consumer tools are supplied by the server-sdk.
 
 ## Remote MCP Servers
 
@@ -203,7 +213,7 @@ Use `execution: device` when the MCP server needs access to the agent's local en
 ### Rules
 
 - `execution` is only meaningful for `source: remote` MCPs that use STDIO transport. HTTP-transport remote MCPs always connect from the platform regardless of the `execution` setting.
-- `execution: device` is **invalid** on `source: device` MCPs (they already run on the device by definition). Using it produces a validation error.
+- `execution` is **invalid** on `source: device` and `source: consumer` MCPs - they already run outside the platform. Using it produces a validation error.
 - The `connection` field (`eager` or `lazy`) is respected for device-executed MCPs the same way as sandbox-executed MCPs.
 
 ## Device MCP Servers
@@ -243,6 +253,55 @@ const computer = new Computer({
 
 If the consumer provides a namespace not declared in the protocol, the platform rejects it.
 
+## Consumer MCP Servers
+
+Consumer MCP servers (`source: consumer`) are defined inline in your server-sdk process. Tool schemas and handlers live in your code; the platform learns the namespace from the protocol and routes tool calls to your process via the same `dynamicToolSchemas` channel that device MCPs use.
+
+```yaml
+mcpServers:
+  github:
+    description: Repository management - issues, pull requests, code
+    source: consumer
+    display: name
+
+agent:
+  mcpServers:
+    - github
+```
+
+The protocol declaration is intentionally minimal - the SDK supplies tool names and JSON schemas at runtime, so adding or evolving tools doesn't require a protocol change.
+
+Use consumer MCPs when:
+
+- The integration's credentials should never reach the platform (OAuth tokens, customer API keys).
+- You want to group an integration's tools (`github__list-prs`, `github__get-issue`) without enumerating each one in YAML.
+- You want type-safe handler arguments via Zod schemas.
+
+See [`createInlineMcpServer`](/docs/server-sdk/inline-mcp) in the server-sdk reference for the full implementation guide.
+
+### Namespace Matching
+
+The protocol namespace must match the namespace passed to `createInlineMcpServer()`:
+
+```yaml
+# protocol.yaml
+mcpServers:
+  github: # ← must match
+    source: consumer
+```
+
+```typescript
+const github = createInlineMcpServer('github', {
+  /* tools... */
+});
+
+session = client.agentSessions.attach(sessionId, {
+  mcpServers: [github],
+});
+```
+
+If the SDK provides a namespace not declared in the protocol, those tools are filtered out at the runtime boundary and the LLM never sees them.
+
 ## Thread-Level Scoping
 
 Threads can scope which MCP servers are available, the same way they scope [tools](/docs/protocol/handlers#start-thread):