@octavus/docs 3.2.0 → 3.4.0

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/08-computer.md

@@ -180,6 +180,68 @@ await computer.stop();
 
 Always call `stop()` when the session ends to clean up MCP subprocesses. For managed processes (like Chrome), pass them in the config for automatic cleanup.
 
+## Dynamic Entries
+
+You can add or remove MCP entries on a running `Computer` after `start()` has returned. This is useful when MCP configurations arrive after construction - for example, when a session-manager receives per-session entries from a dispatch payload and wants to wire them into the existing computer instead of rebuilding it.
+
+### `addEntry(namespace, entry, options?)`
+
+Registers a new MCP entry under `namespace`. By default, connects immediately:
+
+```typescript
+await computer.addEntry(
+  'github',
+  Computer.stdio('@modelcontextprotocol/server-github', [], {
+    env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GH_TOKEN! },
+  }),
+);
+```
+
+Pass `{ deferred: true }` to register the entry without connecting. The entry starts in a degraded state and connects on the next `restartEntry(namespace)` call - useful for lazy MCPs the agent activates on demand:
+
+```typescript
+await computer.addEntry('github', githubEntry, { deferred: true });
+
+// Later, when the agent decides it needs GitHub:
+await computer.restartEntry('github');
+```
+
+`addEntry` throws if the namespace already exists. To replace an entry, call `removeEntry` first.
+
+If the immediate connection fails, `addEntry` does not throw - the entry is registered as degraded with the error message attached. Inspect via `getHealth()` or `restartEntry()` to retry.
+
+### `removeEntry(namespace)`
+
+Closes the entry's connection (if any) and drops it from the configuration. No-op when the namespace doesn't exist:
+
+```typescript
+await computer.removeEntry('github');
+```
+
+### `restartEntry(namespace)`
+
+Closes the existing connection (if any) and reconnects with the current configuration:
+
+```typescript
+await computer.restartEntry('github');
+```
+
+Use this to bring a deferred entry online for the first time, or to recover an entry that became degraded mid-session.
+
+### Detecting dynamic-entry support
+
+Consumers that work with arbitrary `ToolProvider` implementations can detect dynamic-entry capability with `isDynamicMcpProvider`:
+
+```typescript
+import { isDynamicMcpProvider } from '@octavus/server-sdk';
+
+if (isDynamicMcpProvider(provider)) {
+  await provider.addEntry('github', githubEntry);
+}
+```
+
+`Computer` always passes this check.
+
 ## Chrome Launch Helper
 
 For desktop applications that need to control a browser, `Computer.launchChrome()` launches Chrome with remote debugging enabled:
@@ -384,10 +446,38 @@ class Computer implements ToolProvider {
   start(): Promise<{ errors: string[] }>;
   stop(): Promise<void>;
 
+  // Dynamic entries
+  addEntry(namespace: string, entry: McpEntry, options?: { deferred?: boolean }): Promise<void>;
+  removeEntry(namespace: string): Promise<void>;
+  restartEntry(namespace: string): Promise<void>;
+  stopEntry(namespace: string): Promise<void>;
+
+  // Health
+  getHealth(): Promise<ComputerHealth>;
+  ensureReady(): Promise<EnsureReadyResult>;
+  retryDegraded(): Promise<{ recovered: string[]; stillDegraded: string[] }>;
+
   // ToolProvider implementation
   toolHandlers(): Record<string, ToolHandler>;
   toolSchemas(): ToolSchema[];
 }
+
+interface ComputerHealth {
+  healthy: boolean;
+  entries: EntryHealth[];
+  totalTools: number;
+}
+
+interface EntryHealth {
+  name: string;
+  healthy: boolean;
+  error?: string;
+}
+
+interface EnsureReadyResult extends ComputerHealth {
+  recovered?: string[];
+  failedEntries?: string[];
+}
 ```
 
 ### ComputerConfig
@@ -396,6 +486,8 @@ class Computer implements ToolProvider {
 interface ComputerConfig {
   mcpServers: Record<string, McpEntry>;
   managedProcesses?: { process: ChildProcess }[];
+  /** Namespaces to skip during start() - they begin as degraded and can be connected on demand via restartEntry(). */
+  deferredEntries?: string[];
 }
 
 type McpEntry = StdioConfig | HttpConfig | ShellConfig;

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/03-client-sdk/08-file-uploads.md

@@ -285,11 +285,17 @@ The `file` type is a built-in type representing uploaded files. Use `file[]` for
 
 ## Supported File Types
 
-| Type      | Media Types                                                          |
-| --------- | -------------------------------------------------------------------- |
-| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |
-| Video     | `video/mp4`, `video/webm`, `video/quicktime`, `video/mpeg`           |
-| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |
+| Type             | Media Types                                                                                                                                                                                                                                                                                                                                                             |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Images           | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                                                                                                                                                                                                                                                                                                                    |
+| Video            | `video/mp4`, `video/webm`, `video/quicktime`, `video/mpeg`                                                                                                                                                                                                                                                                                                              |
+| Documents        | `application/pdf`, `text/plain`, `text/markdown`, `text/csv`, `application/json`                                                                                                                                                                                                                                                                                        |
+| Office documents | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` (`.docx`), `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` (`.xlsx`), `application/vnd.openxmlformats-officedocument.presentationml.presentation` (`.pptx`), `application/msword` (`.doc`), `application/vnd.ms-excel` (`.xls`), `application/vnd.ms-powerpoint` (`.ppt`) |
+
+Images, video, PDFs, and text-based formats are sent directly to the model as
+file parts. Office documents are not natively readable by LLM providers, so
+they are surfaced to the agent as presigned download URLs - the agent fetches
+and parses them with code or skills (e.g. via a sandboxed computer).
 
 ## File Limits
 

package/content/04-protocol/05-skills.md

@@ -5,7 +5,7 @@ description: Using Octavus skills for code execution and specialized capabilitie
 
 # Skills
 
-Skills are knowledge packages that enable agents to execute code and generate files in isolated sandbox environments. Unlike external tools (which you implement in your backend), skills are self-contained packages with documentation and scripts that run in secure sandboxes.
+Skills are knowledge packages that enable agents to execute code and generate files. Unlike external tools (which you implement in your backend), skills are self-contained packages with documentation and scripts. By default, skills run in isolated sandbox environments, but they can also run directly on the agent's computer.
 
 ## Overview
 
@@ -15,8 +15,8 @@ Octavus Skills provide **provider-agnostic** code execution. They work with any
 
 1. **Skill Definition**: Skills are defined in the protocol's `skills:` section
 2. **Skill Resolution**: Skills are resolved from available sources (see below)
-3. **Sandbox Execution**: When a skill is used, code runs in an isolated sandbox environment
-4. **File Generation**: Files saved to `/output/` are automatically captured and made available for download
+3. **Execution**: Code runs in an isolated sandbox (default) or on the agent's computer
+4. **File Generation**: Files saved to `/output/` are automatically captured and made available for download (sandbox skills)
 
 ### Skill Sources
 
@@ -49,6 +49,7 @@ skills:
 | ------------- | -------- | ------------------------------------------------------------------------------------- |
 | `display`     | No       | How to show in UI: `hidden`, `name`, `description`, `stream` (default: `description`) |
 | `description` | No       | Custom description shown to users (overrides skill's built-in description)            |
+| `execution`   | No       | Where the skill runs: `sandbox` (default) or `device`                                 |
 
 ### Display Modes
 
@@ -107,19 +108,66 @@ This also works for named threads in interactive agents, allowing different thre
 
 When skills are enabled, the LLM has access to these tools:
 
-| Tool                 | Purpose                                 | Availability         |
-| -------------------- | --------------------------------------- | -------------------- |
-| `octavus_skill_read` | Read skill documentation (SKILL.md)     | All skills           |
-| `octavus_skill_list` | List available scripts in a skill       | All skills           |
-| `octavus_skill_run`  | Execute a pre-built script from a skill | All skills           |
-| `octavus_code_run`   | Execute arbitrary Python/Bash code      | Standard skills only |
-| `octavus_file_write` | Create files in the sandbox             | Standard skills only |
-| `octavus_file_read`  | Read files from the sandbox             | Standard skills only |
+| Tool                  | Purpose                                         | Availability                   |
+| --------------------- | ----------------------------------------------- | ------------------------------ |
+| `octavus_skill_read`  | Read skill documentation (SKILL.md)             | All skills                     |
+| `octavus_skill_list`  | List available scripts in a skill               | All skills                     |
+| `octavus_skill_run`   | Execute a pre-built script from a skill         | All skills                     |
+| `octavus_skill_setup` | Install a skill on the device for file browsing | Device skills only             |
+| `octavus_code_run`    | Execute arbitrary Python/Bash code              | Sandbox skills (standard) only |
+| `octavus_file_write`  | Create files in the sandbox                     | Sandbox skills (standard) only |
+| `octavus_file_read`   | Read files from the sandbox                     | Sandbox skills (standard) only |
 
 The LLM learns about available skills through system prompt injection and can use these tools to interact with skills.
 
 Skills that have [secrets](#skill-secrets) configured run in **secure mode**, where only `octavus_skill_read`, `octavus_skill_list`, and `octavus_skill_run` are available. See [Skill Secrets](#skill-secrets) below.
 
+## Device Execution
+
+By default, skills run in an isolated sandbox. When `execution: device` is set, the skill runs on the agent's computer (VM or desktop) instead.
+
+```yaml
+skills:
+  deploy-tool:
+    display: description
+    description: Deploy applications to production
+    execution: device
+  qr-code:
+    display: description
+    description: Generating QR codes
+    # execution defaults to sandbox
+```
+
+### How Device Skills Work
+
+Device skills are installed on the agent's computer so the agent can browse their files and run their scripts directly. After attaching a skill via integrations, the agent uses `octavus_skill_setup` to install it on the device. Once installed, the agent can:
+
+- Read the skill's documentation with `octavus_skill_read`
+- List available scripts with `octavus_skill_list`
+- Run pre-built scripts with `octavus_skill_run`
+
+The generic workspace tools (`octavus_code_run`, `octavus_file_write`, `octavus_file_read`) are **not available** for device skills. Instead, the agent uses the device's own shell and filesystem MCP servers to interact with files and run commands.
+
+### Sandbox vs Device Skills
+
+| Aspect              | Sandbox (default)                  | Device                                                 |
+| ------------------- | ---------------------------------- | ------------------------------------------------------ |
+| **Environment**     | Isolated sandbox                   | Agent's computer (VM or desktop)                       |
+| **Available tools** | All 6 skill tools                  | `skill_read`, `skill_list`, `skill_run`, `skill_setup` |
+| **File access**     | Via `octavus_file_read/write`      | Via device filesystem MCP                              |
+| **Code execution**  | Via `octavus_code_run`             | Via device shell MCP                                   |
+| **Isolation**       | Fully sandboxed                    | Runs alongside other device processes                  |
+| **File output**     | `/output/` directory auto-captured | Files written to device filesystem                     |
+
+### When to Use Device Execution
+
+Use `execution: device` when the skill needs to:
+
+- Access the agent's local filesystem or running processes
+- Use tools or CLIs installed on the device
+- Interact with services running on the device
+- Persist files beyond a single execution cycle
+
 ## Example: QR Code Generation
 
 ```yaml
@@ -297,14 +345,14 @@ skills:
 
 ## Comparison: Skills vs Tools vs Provider Options
 
-| Feature            | Octavus Skills    | External Tools      | Provider Tools/Skills |
-| ------------------ | ----------------- | ------------------- | --------------------- |
-| **Execution**      | Isolated sandbox  | Your backend        | Provider servers      |
-| **Provider**       | Any (agnostic)    | N/A                 | Provider-specific     |
-| **Code Execution** | Yes               | No                  | Yes (provider tools)  |
-| **File Output**    | Yes               | No                  | Yes (provider skills) |
-| **Implementation** | Skill packages    | Your code           | Built-in              |
-| **Cost**           | Sandbox + LLM API | Your infrastructure | Included in API       |
+| Feature            | Octavus Skills              | External Tools      | Provider Tools/Skills |
+| ------------------ | --------------------------- | ------------------- | --------------------- |
+| **Execution**      | Sandbox or agent's computer | Your backend        | Provider servers      |
+| **Provider**       | Any (agnostic)              | N/A                 | Provider-specific     |
+| **Code Execution** | Yes                         | No                  | Yes (provider tools)  |
+| **File Output**    | Yes                         | No                  | Yes (provider skills) |
+| **Implementation** | Skill packages              | Your code           | Built-in              |
+| **Cost**           | Sandbox + LLM API           | Your infrastructure | Included in API       |
 
 ## Uploading Custom Skills
 
@@ -343,9 +391,21 @@ agent:
   skills: [my-skill]
 ```
 
+## On-Demand Skills
+
+On-demand skills (`onDemandSkills`) also support the `execution` field:
+
+```yaml
+onDemandSkills:
+  display: description
+  execution: device
+```
+
+When `execution: device` is set on the on-demand skills declaration, any skill attached at runtime via integrations runs on the agent's computer instead of in a sandbox.
+
 ## Sandbox Timeout
 
-The default sandbox timeout is 5 minutes. You can configure a custom timeout using `sandboxTimeout` in the agent config or on individual `start-thread` blocks:
+The default sandbox timeout is 5 minutes (applies to sandbox skills only). You can configure a custom timeout using `sandboxTimeout` in the agent config or on individual `start-thread` blocks:
 
 ```yaml
 # Agent-level timeout (applies to main thread)
@@ -436,7 +496,7 @@ For standard skills (without secrets), scripts receive input as CLI arguments. F
 
 ## Security
 
-Skills run in isolated sandbox environments:
+Sandbox skills run in isolated environments:
 
 - **No network access** (unless explicitly configured)
 - **No persistent storage** (sandbox destroyed after each `next-message` execution)
@@ -444,6 +504,8 @@ Skills run in isolated sandbox environments:
 - **Time limits** enforced (5-minute default, configurable via `sandboxTimeout`)
 - **Secret redaction** - output from secure skills is automatically scanned for secret values
 
+Device skills run on the agent's computer and share its environment. They do not have sandbox isolation but benefit from restricted tool access (only slug-bearing tools are available).
+
 ## Next Steps
 
 - [Agent Config](/docs/protocol/agent-config) - Configuring skills in agent settings

package/content/04-protocol/09-skills-advanced.md

@@ -66,6 +66,24 @@ steps:
     maxSteps: 10
 ```
 
+### Execution Mode
+
+The `execution` field is set at the skill definition level and applies to all threads that use the skill:
+
+```yaml
+skills:
+  deploy-tool:
+    display: description
+    description: Deploy applications
+    execution: device # All threads using this skill run it on the device
+  qr-code:
+    display: description
+    description: Generating QR codes
+    # Defaults to sandbox execution
+```
+
+You don't set `execution` per-thread - a skill's execution mode is consistent wherever it's used.
+
 ### Match Skills to Use Cases
 
 Different threads can have different skills. Define all skills at the protocol level, then scope them to each thread:
@@ -311,15 +329,15 @@ Pattern:
 
 When a skill declares secrets and an organization configures them, the skill runs in secure mode with its own isolated sandbox.
 
-### Standard vs Secure Skills
+### Standard vs Secure vs Device Skills
 
-| Aspect              | Standard Skills                   | Secure Skills                                       |
-| ------------------- | --------------------------------- | --------------------------------------------------- |
-| **Sandbox**         | Shared with other standard skills | Isolated (one per skill)                            |
-| **Available tools** | All 6 skill tools                 | `skill_read`, `skill_list`, `skill_run` only        |
-| **Script input**    | CLI arguments via `args`          | JSON via stdin (use `input` parameter)              |
-| **Environment**     | No secrets                        | Secrets as env vars                                 |
-| **Output**          | Raw stdout/stderr                 | Redacted (secret values replaced with `[REDACTED]`) |
+| Aspect              | Standard Skills          | Secure Skills                                       | Device Skills                                          |
+| ------------------- | ------------------------ | --------------------------------------------------- | ------------------------------------------------------ |
+| **Environment**     | Shared sandbox           | Isolated sandbox (one per skill)                    | Agent's computer (VM or desktop)                       |
+| **Available tools** | All 6 skill tools        | `skill_read`, `skill_list`, `skill_run` only        | `skill_read`, `skill_list`, `skill_run`, `skill_setup` |
+| **Script input**    | CLI arguments via `args` | JSON via stdin (use `input` parameter)              | CLI arguments via `args`                               |
+| **Secrets**         | No secrets               | Secrets as env vars                                 | No secrets                                             |
+| **Output**          | Raw stdout/stderr        | Redacted (secret values replaced with `[REDACTED]`) | Raw stdout/stderr                                      |
 
 ### Writing Scripts for Secure Skills
 

package/content/04-protocol/11-workers.md

@@ -416,7 +416,9 @@ steps:
     maxSteps: 10
 ```
 
-Workers define their own skills independently -- they don't inherit skills from a parent interactive agent. Each thread gets its own sandbox scoped to only its listed skills.
+Workers define their own skills independently - they don't inherit skills from a parent interactive agent. Each thread gets its own sandbox scoped to only its listed skills.
+
+Skills with `execution: device` work the same way in workers as in interactive agents - the skill runs on the agent's computer. Workers resolve their device execution independently, so a worker can use device skills even if the parent agent does not.
 
 See [Skills](/docs/protocol/skills) for full documentation.