@octavus/docs 5.0.0 → 5.1.0

package/content/04-protocol/04-tools.md

@@ -34,22 +34,24 @@ tools:
 
 ### Tool Fields
 
-| Field         | Required | Description                                                  |
-| ------------- | -------- | ------------------------------------------------------------ |
-| `description` | Yes      | What the tool does (shown to LLM and optionally user)        |
-| `display`     | No       | How to show in UI: `hidden`, `name`, `description`, `stream` |
-| `parameters`  | No       | Input parameters the tool accepts                            |
+| Field         | Required | Description                                                                |
+| ------------- | -------- | -------------------------------------------------------------------------- |
+| `description` | Yes      | What the tool does (shown to LLM and optionally user)                      |
+| `display`     | No       | How to show in UI: `hidden`, `name`, `description`, `stream`, `title`      |
+| `title`       | No       | UI label shown when `display: title` (hides the description and arguments) |
+| `parameters`  | No       | Input parameters the tool accepts                                          |
 
 ### Display Modes
 
 Controls what the client sees about tool execution. The default is `description`.
 
-| Mode          | Behavior                                                                                                                                                           |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `hidden`      | No UI events emitted. The tool executes silently and the user has no awareness it was called. Use for internal plumbing tools (title setting, context management). |
-| `name`        | Shows the raw tool name while executing. Arguments and result are not displayed.                                                                                   |
-| `description` | Shows the tool's description while executing (default). Arguments are visible during live streaming but the result is not preserved after page refresh.            |
-| `stream`      | Full visibility. Arguments stream progressively as the LLM generates them, and the result is shown after execution. The result is preserved after page refresh.    |
+| Mode          | Behavior                                                                                                                                                                                                                                                         |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hidden`      | No UI events emitted. The tool executes silently and the user has no awareness it was called. Use for internal plumbing tools (title setting, context management).                                                                                               |
+| `name`        | Shows the raw tool name while executing. Arguments and result are not displayed.                                                                                                                                                                                 |
+| `description` | Shows the tool's description while executing (default). Arguments are visible during live streaming but the result is not preserved after page refresh.                                                                                                          |
+| `stream`      | Full visibility. Arguments stream progressively as the LLM generates them, and the result is shown after execution. The result is preserved after page refresh.                                                                                                  |
+| `title`       | Shows the tool's `title` plus the tool name only. The description, arguments, and result are hidden in the UI; the `description` is still sent to the LLM. Use for server-side tools that should appear as a labeled step without exposing their inputs/outputs. |
 
 **When to use `stream`:**
 
@@ -64,6 +66,14 @@ Controls what the client sees about tool execution. The default is `description`
 - Context-setting tools that would clutter the UI
 - Tools that are implementation details of the agent's protocol
 
+**When to use `title`:**
+
+- Server-side tools that should appear in the UI as a clean, labeled step (e.g. "Looking up your account") without exposing their arguments or result
+- Tools whose `description` is written for the LLM and shouldn't be shown verbatim to the user
+- This is the recommended mode for server-executed tools that should be visible: give them a human-readable `title` for the UI and keep `description` focused on instructing the model
+
+`title` is the preferred choice for server-side tools that should surface in the UI. `name` and `description` remain supported for backward compatibility, but for new server-side tools prefer `title` (a clean UI label) - or `stream` for client tools where the user benefits from seeing the arguments and result.
+
 **Refresh and restore behavior:**
 
 `stream` is the only mode that preserves the tool result after a page refresh. For all other modes, the result is available during the live session but stripped on refresh. On session restore (when the session expires and is rebuilt from stored `UIMessage[]`), `stream` tools retain their original result while other modes receive a placeholder.

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

@@ -45,11 +45,12 @@ skills:
 
 ### Skill Fields
 
-| Field         | Required | Description                                                                           |
-| ------------- | -------- | ------------------------------------------------------------------------------------- |
-| `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`                                 |
+| Field         | Required | Description                                                                                    |
+| ------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `display`     | No       | How to show in UI: `hidden`, `name`, `description`, `stream`, `title` (default: `description`) |
+| `title`       | No       | UI label shown when `display: title` (hides the description and arguments)                     |
+| `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
 

package/content/04-protocol/06-handlers.md

@@ -224,12 +224,13 @@ For agentic image generation where the LLM decides when to generate, configure `
 
 Every block has a `display` property:
 
-| Mode          | Default For               | Behavior          |
-| ------------- | ------------------------- | ----------------- |
-| `hidden`      | add-message               | Not shown to user |
-| `name`        | set-resource              | Shows block name  |
-| `description` | tool-call, generate-image | Shows description |
-| `stream`      | next-message              | Streams content   |
+| Mode          | Default For               | Behavior                        |
+| ------------- | ------------------------- | ------------------------------- |
+| `hidden`      | add-message               | Not shown to user               |
+| `name`        | set-resource              | Shows block name                |
+| `description` | tool-call, generate-image | Shows description               |
+| `stream`      | next-message              | Streams content                 |
+| `title`       | -                         | Shows the block's `title` field |
 
 ## Complete Example
 

package/content/04-protocol/08-provider-options.md

@@ -58,10 +58,11 @@ anthropic:
       description: Searching... # Custom display text
 ```
 
-| Field         | Required | Description                                                           |
-| ------------- | -------- | --------------------------------------------------------------------- |
-| `display`     | No       | `hidden`, `name`, `description`, or `stream` (default: `description`) |
-| `description` | No       | Custom text shown to users during execution                           |
+| Field         | Required | Description                                                                    |
+| ------------- | -------- | ------------------------------------------------------------------------------ |
+| `display`     | No       | `hidden`, `name`, `description`, `stream`, or `title` (default: `description`) |
+| `title`       | No       | UI label shown when `display: title` (hides description and arguments)         |
+| `description` | No       | Custom text shown to users during execution                                    |
 
 ### Web Search
 
@@ -120,12 +121,13 @@ anthropic:
       description: Processing PDF
 ```
 
-| Field         | Required | Description                                                           |
-| ------------- | -------- | --------------------------------------------------------------------- |
-| `type`        | Yes      | `anthropic` (built-in) or `custom` (uploaded)                         |
-| `version`     | No       | Skill version (default: `latest`)                                     |
-| `display`     | No       | `hidden`, `name`, `description`, or `stream` (default: `description`) |
-| `description` | No       | Custom text shown to users                                            |
+| Field         | Required | Description                                                                    |
+| ------------- | -------- | ------------------------------------------------------------------------------ |
+| `type`        | Yes      | `anthropic` (built-in) or `custom` (uploaded)                                  |
+| `version`     | No       | Skill version (default: `latest`)                                              |
+| `display`     | No       | `hidden`, `name`, `description`, `stream`, or `title` (default: `description`) |
+| `title`       | No       | UI label shown when `display: title` (hides description and arguments)         |
+| `description` | No       | Custom text shown to users                                                     |
 
 ### Built-in Skills
 

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

@@ -530,6 +530,7 @@ Controls how worker execution appears to users. The default for workers is `stre
 | `name`        | Shows a running/done indicator with the worker name. No nested content (text, tool calls, reasoning) is forwarded.                 |
 | `description` | Shows a running/done indicator with the worker description. No nested content is forwarded.                                        |
 | `stream`      | Full visibility. All nested events are forwarded - text, reasoning, tool calls, sources, files. Worker input is included on start. |
+| `title`       | Like `description`, but shows the worker's `title` field instead of its description. No nested content or input is forwarded.      |
 
 **Progressive input streaming:** When a worker with `display: stream` is invoked agentically (LLM calls it as a tool), the `UIWorkerPart` appears in the UI immediately as the LLM starts generating the worker's arguments. The worker input streams progressively into the worker part, the same way text tokens stream into a text part. Once input finishes, worker execution begins and nested content flows into the same worker part. There is no intermediate tool card.
 

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

@@ -43,7 +43,8 @@ mcpServers:
 | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
 | `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`)                                  |
+| `display`     | No       | How tool calls appear in UI: `hidden`, `name`, `description`, `stream`, `title` (default: `description`)               |
+| `title`       | No       | UI label shown when `display: title`; applies to every tool in this namespace (hides description and arguments)        |
 | `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). |
 

package/content/07-workforce-agents/01-overview.md

@@ -0,0 +1,60 @@
+---
+title: Overview
+description: What Workforce Agents are and how to drive them programmatically.
+---
+
+# Workforce Agents
+
+Workforce Agents are Octavus's autonomous AI teammates - specialized agents you hire and configure in the dashboard, each with its own computer, skills, and tools. Browse and hire them at [octavus.ai/agents](https://octavus.ai/agents), and see the full roster at [octavus.ai/agents/discover](https://octavus.ai/agents/discover).
+
+The **Workforce Agents API** lets you drive one of your agents without a browser: give it a task, wait for it to finish, and read what it did. It is built for automation - CI pipelines, scheduled jobs, and backend integrations that hand work to an agent and collect the result.
+
+> Workforce Agents are distinct from agents you build yourself with the SDK. The [Sessions API](/docs/api-reference/sessions) drives agents you define and host; the Workforce Agents API drives the managed agents you hire and configure in the dashboard.
+
+## How it works
+
+A run follows a simple dispatch-then-poll model - there is no stream or webhook to manage:
+
+1. **Dispatch** a message to an agent. This starts a **thread** (a conversation) and returns a `threadId` right away.
+2. **Poll** the thread until its `status` is terminal.
+3. **Read** the thread's messages to get the agent's work.
+
+```mermaid
+sequenceDiagram
+  participant C as Your code
+  participant A as Workforce Agent
+  C->>A: dispatch a task
+  A-->>C: threadId and status
+  loop until terminal status
+    C->>A: get thread
+    A-->>C: status and messages
+  end
+```
+
+### Thread status
+
+| Status      | Meaning                                                                             |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `pending`   | Dispatched, waiting to start                                                        |
+| `queued`    | Waiting for the agent to free up - an agent runs one task at a time on its computer |
+| `running`   | The agent is working                                                                |
+| `completed` | Finished successfully (terminal)                                                    |
+| `failed`    | Ended with an error - see `failureReason` (terminal)                                |
+| `cancelled` | Stopped (terminal)                                                                  |
+
+Poll while the status is `pending`, `queued`, or `running`, and stop once it is `completed`, `failed`, or `cancelled`.
+
+## Authentication
+
+Each agent has its own **API key**, created from the agent's settings in the dashboard (Settings -> API). The key:
+
+- Drives only that one agent - a key for one agent can never call another.
+- Is a secret. Use it from a backend, script, or CI, never in a browser or client app.
+- Is sent as a bearer token: `Authorization: Bearer oct_agt_...`.
+
+Create a key, copy it once (it is shown only at creation), and store it securely.
+
+## Next steps
+
+- [Using the SDK](/docs/workforce-agents/sdk) - the `@octavus/server-sdk` `workforce` client, including a run-and-wait helper.
+- [API reference](/docs/workforce-agents/api-reference) - the REST endpoints, for any language.

package/content/07-workforce-agents/02-sdk.md

@@ -0,0 +1,105 @@
+---
+title: Using the SDK
+description: Drive a Workforce Agent with the @octavus/server-sdk workforce client.
+---
+
+# Using the SDK
+
+`@octavus/server-sdk` ships a `workforce` client for driving an agent with its per-agent key.
+
+## Install
+
+```bash
+npm install @octavus/server-sdk@{{VERSION:@octavus/server-sdk}}
+```
+
+## Set up the client
+
+Construct `OctavusClient` with your agent's API key:
+
+```ts
+import { OctavusClient } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: 'https://octavus.ai',
+  apiKey: process.env.OCTAVUS_AGENT_KEY, // oct_agt_...
+});
+```
+
+## Run a task and wait for the result
+
+`run()` is the all-in-one method: it dispatches a message, polls until the run finishes, and returns the completed thread.
+
+```ts
+const thread = await client.workforce.run(agentId, 'Summarize the latest sales report');
+
+console.log(thread.status); // 'completed' | 'failed' | 'cancelled'
+console.log(thread.messages); // the full conversation, including the agent's reply
+```
+
+The agent's latest turn is at the end of `thread.messages`.
+
+## Dispatch and poll manually
+
+For more control, dispatch and read the thread yourself:
+
+```ts
+const { threadId } = await client.workforce.dispatch(agentId, 'Research our top 3 competitors');
+
+const thread = await client.workforce.getThread(agentId, threadId);
+if (thread.status === 'completed') {
+  // ...
+}
+```
+
+`waitForCompletion()` does the polling loop for you until the thread is terminal:
+
+```ts
+const { threadId } = await client.workforce.dispatch(agentId, 'Draft the Q3 board update');
+const thread = await client.workforce.waitForCompletion(agentId, threadId);
+```
+
+## Follow up in the same thread
+
+Continue a thread with another message. It runs after the current turn finishes.
+
+```ts
+await client.workforce.followUp(agentId, threadId, 'Now turn that into a slide deck');
+const thread = await client.workforce.waitForCompletion(agentId, threadId);
+```
+
+## Options
+
+`run()` and `waitForCompletion()` accept polling options. Full runs can take several minutes, so the defaults are generous.
+
+| Option           | Type        | Default  | Description                                   |
+| ---------------- | ----------- | -------- | --------------------------------------------- |
+| `pollIntervalMs` | number      | `3000`   | Delay between status checks                   |
+| `timeoutMs`      | number      | `900000` | Max time to wait before throwing (15 minutes) |
+| `signal`         | AbortSignal | -        | Cancel the wait early                         |
+
+`dispatch()`, `followUp()`, and `run()` also accept `files` (an array of `FileReference`) to attach hosted files to the message.
+
+```ts
+const thread = await client.workforce.run(agentId, 'Review this spec', {
+  timeoutMs: 30 * 60 * 1000, // 30 minutes
+  pollIntervalMs: 5000,
+});
+```
+
+If the timeout elapses first, `waitForCompletion()` and `run()` throw. The run keeps going on the server, so you can read it later with `getThread()`.
+
+## Result shape
+
+`getThread()`, `waitForCompletion()`, and `run()` return a thread:
+
+| Field           | Type           | Description                                                                                                    |
+| --------------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
+| `threadId`      | string         | The thread identifier                                                                                          |
+| `status`        | string         | `idle`, `queued`, `pending`, `running`, `completed`, `failed`, or `cancelled`                                  |
+| `failureReason` | string \| null | Why the run failed, when `status` is `failed`                                                                  |
+| `messages`      | UIMessage[]    | The conversation - text, tool and skill steps, and files (see [UIMessage parts](/docs/api-reference/sessions)) |
+
+Use `isTerminalThreadStatus(status)` to check whether a run has finished.
+
+The same operations are available as plain HTTP - see the [API reference](/docs/workforce-agents/api-reference).

package/content/07-workforce-agents/03-api-reference.md

@@ -0,0 +1,146 @@
+---
+title: API Reference
+description: REST endpoints for the Workforce Agents API.
+---
+
+# Workforce Agents API
+
+Drive a single agent over HTTP. Every request is authenticated with that agent's API key, sent as a bearer token:
+
+```
+Authorization: Bearer oct_agt_...
+```
+
+All endpoints are scoped to one agent through the `{agentId}` path segment - find the agent ID in the agent's page URL in the dashboard. A key only works for the agent it was created for.
+
+## Start a thread
+
+Dispatch a message to the agent. This starts a new thread and returns immediately.
+
+```
+POST /api/v1/workforce/agents/{agentId}/threads
+```
+
+### Request Body
+
+```json
+{
+  "message": "Summarize the latest sales report"
+}
+```
+
+| Field     | Type            | Required | Description                       |
+| --------- | --------------- | -------- | --------------------------------- |
+| `message` | string          | Yes      | The task or message for the agent |
+| `files`   | FileReference[] | No       | Hosted file attachments           |
+
+### Response
+
+Returns `201`.
+
+```json
+{
+  "threadId": "cm5xyz123abc456def",
+  "status": "pending"
+}
+```
+
+Poll the [Get a thread](#get-a-thread) endpoint until the status is terminal.
+
+### Example
+
+```bash
+curl -X POST https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads \
+  -H "Authorization: Bearer oct_agt_..." \
+  -H "Content-Type: application/json" \
+  -d '{ "message": "Summarize the latest sales report" }'
+```
+
+## Get a thread
+
+Read a thread's status and messages. Poll this until the run finishes.
+
+```
+GET /api/v1/workforce/agents/{agentId}/threads/{threadId}
+```
+
+### Response
+
+```json
+{
+  "threadId": "cm5xyz123abc456def",
+  "status": "completed",
+  "failureReason": null,
+  "messages": []
+}
+```
+
+| Field           | Type           | Description                                                                   |
+| --------------- | -------------- | ----------------------------------------------------------------------------- |
+| `threadId`      | string         | The thread identifier                                                         |
+| `status`        | string         | `idle`, `queued`, `pending`, `running`, `completed`, `failed`, or `cancelled` |
+| `failureReason` | string \| null | Why the run failed, when `status` is `failed`                                 |
+| `messages`      | UIMessage[]    | The conversation - see [UIMessage parts](/docs/api-reference/sessions)        |
+
+Keep polling while the status is `pending`, `queued`, or `running`. Stop when it is `completed`, `failed`, or `cancelled`.
+
+### Example
+
+```bash
+curl https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads/THREAD_ID \
+  -H "Authorization: Bearer oct_agt_..."
+```
+
+## Follow up in a thread
+
+Send another message into an existing thread. If the agent is still working the message runs after the current turn finishes; otherwise it starts immediately.
+
+```
+POST /api/v1/workforce/agents/{agentId}/threads/{threadId}/messages
+```
+
+### Request Body
+
+```json
+{
+  "message": "Now turn that into a slide deck"
+}
+```
+
+| Field     | Type            | Required | Description             |
+| --------- | --------------- | -------- | ----------------------- |
+| `message` | string          | Yes      | The follow-up message   |
+| `files`   | FileReference[] | No       | Hosted file attachments |
+
+### Response
+
+Returns `202`.
+
+```json
+{
+  "threadId": "cm5xyz123abc456def",
+  "status": "running"
+}
+```
+
+Poll [Get a thread](#get-a-thread) for the new run's result.
+
+### Example
+
+```bash
+curl -X POST https://octavus.ai/api/v1/workforce/agents/AGENT_ID/threads/THREAD_ID/messages \
+  -H "Authorization: Bearer oct_agt_..." \
+  -H "Content-Type: application/json" \
+  -d '{ "message": "Now turn that into a slide deck" }'
+```
+
+## Errors
+
+Errors return `{ "error": string, "code": string }` with an HTTP status:
+
+| Status | Meaning                                           |
+| ------ | ------------------------------------------------- |
+| `401`  | Missing or invalid API key                        |
+| `402`  | The agent is blocked by a usage or spending limit |
+| `403`  | The key is not authorized for this agent          |
+| `404`  | The thread does not exist for this agent          |

package/content/07-workforce-agents/_meta.md

@@ -0,0 +1,4 @@
+---
+title: Workforce Agents
+description: Automate Octavus Agents over the API - dispatch a task, poll for completion, and read the result.
+---