# CopilotKit Rich Threads and the agent computer

OpenMuse uses `@copilotkit/react-native/headless` for its custom native and web interface. Chat messages, tool cards and task-linked documents render through CopilotKit's AG-UI agent and tool hooks.

## Rich Threads

Every workspace mode requires a CopilotKit Intelligence project key before the API will start. Create or select a project:

```sh
npx copilotkit@latest login
npx copilotkit@latest project select
```

Keep the generated key in the API server environment and restart the API:

```dotenv
CPK_INTELLIGENCE_API_KEY=your-project-key
```

Never put the key in an `EXPO_PUBLIC_`, `NEXT_PUBLIC_`, or `VITE_` variable. The server constructs `CopilotKitIntelligence`, and `identifyUser` resolves the owner from the verified OpenMuse session. The existing deployment is a single-user workspace; its access key must not be shared as a multi-user login. See [CopilotKit's runtime setup](https://docs.copilotkit.ai/intelligence/connect-your-runtime) for project-key configuration.

With this configuration, the conversation menu uses CopilotKit's native `useThreads` hook to list, rename, archive, restore and paginate conversations. The server saves an owner-bound main thread ID and provisions it through Intelligence before the first message, so reloading during the first run retains the same conversation. Side chats create a fresh client thread ID and persist on their first run. Selecting a saved conversation mounts a private `useAgent({ agentId, runtimeAgentId, threadId })` instance and calls `copilotkit.connectAgent` to replay the thread. Visited chats remain mounted during navigation, preserving their drafts and queues. Stop explicitly requests `copilotkit.stopAgent`.

The composer stays editable during replies. Follow-ups enter a visible, removable queue and run in order after the current reply and its persistence finish. Stopping or failing a reply pauses the queue; SDK errors emitted without rejecting the run promise still stop subsequent sends. The queue lives in the open app, not a durable server inbox. Delegated tasks remain separate server work. See the [interaction design](EXPERIENCE.md).

Rich tool messages retain task IDs. The renderer fetches current task status, browser previews, PDF links and structured artifacts from the authenticated task endpoint. Expiring file/preview URLs are generated by the server rather than stored in thread messages. New Intelligence conversations never load or overwrite `/api/conversation`.

The API fails at startup with a missing-key error when the key is unset. Existing local sample history is not automatically uploaded to Intelligence.

Automatic thread naming is disabled; conversations can be renamed in the menu. Intelligence is a separately configured service, not bundled with this MIT-licensed application. See [headless threads](https://docs.copilotkit.ai/headless-threads) for the platform lifecycle and hosting options.

## Agent computer

The Computer control below the avatar opens a persistent workspace with browser sessions and files. Browser cards show actual worker screenshots; **Open browser** opens the existing interactive console for takeover. PDFs open in the native/web readers. Tasks can read public pages, monitor changes and collect PDFs using the same worker.

Opening a session renews its short-lived console access. **Refresh connection** renews access without navigating; **Reopen** keeps the saved profile and uses the address in the input. The console reports live/disconnected state, preserves unsent text after an error, and pauses preview polling when hidden. Closing a session retains its profile and downloads.

Run the browser worker using the `BROWSER_WORKER_URL` and `WORKER_TOKEN` setup in the [README](../README.md). Browser profiles persist on disk. The optional [Linux computer](COMPUTER.md) adds real command execution, saved output, editable files, and PDF transfer. CopilotKit's built-in conversation and task-worker tools use this same computer; remote AG-UI backends must supply their own equivalent tools. Interactive reservations still require user takeover; autonomous booking, checkout, graphical desktops and per-user VM isolation are not implemented. The OpenBot adapter remains an extension point for other computer backends.

## Validation scope

The Rich Threads route tests run against the real CopilotKit runtime with a mocked Intelligence service boundary. They cover session enforcement, owner scoping, pagination, rename, archive, rich message preservation and provider failures. They do not replace a live account test for Intelligence WebSocket persistence/replay. That test requires a configured project key.