# CopilotKit Rich Threads and the agent computer

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

## Rich Threads

Set the following **server-only** environment variable and restart the API:

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

Obtain the project key using [CopilotKit's runtime setup](https://docs.copilotkit.ai/intelligence/connect-your-runtime). Never put it in an `EXPO_PUBLIC_` 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.

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`.

When the key is unset, OpenMuse keeps its existing local conversation store. The menu explicitly identifies that mode. This is the entirely self-hosted open-source default; it does not emulate CopilotKit Intelligence or claim to provide its cloud sync. Existing local history remains available when returning to local mode. Historical local messages are 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.