# KDE Integration

The `kde/` directory contains optional KDE/Qt clients for Ollie. They are 9P clients, not part of the Ollie agent runtime. Every component reaches `olliesrv` through the shared 9P boundary, using either the native `libollie9p` client library or the `ollie-9p` command. They do not use D-Bus, FUSE, or a parallel session store.

## Components

| Component | Description |
|---|---|
| `ollie-gui` | Qt/QML desktop application for sessions, agents, chat, prompts, and controls. It runs outside Plasma with Qt6 and falls back to Qt Quick Basic styling. |
| KRunner plugin | Starts one-shot generation and exposes session-oriented actions. |
| Kate plugin | Provides editor integration and ghost-text assistance through 9P. |
| KIO worker | Exposes Ollie through the `ollie://` protocol. |
| Dolphin actions | Shell helpers for asking Ollie about selected files or the current directory. |
| Plasma environment script | Exports the Ollie 9P namespace for desktop clients. |

The KDE clients do not embed provider selection, prompt assembly, tool execution, or agent-loop logic. Those remain in `olliesrv`; the clients read and write the namespace described in [`architecture-9p.md`](architecture-9p.md).

## GUI

`ollie-gui` displays active sessions and agents, streams chat, submits prompts, and exposes common controls:

- Session tree with agent indicators:
  - State dot (right of name): green=idle, blue=thinking, orange=calling, gray=paused
  - Bypass indicator (left of name): ⚠ when pending approval needed
- Chat rendering for assistant, tool, reasoning, and markdown-block output.
- Bypass approval banner with Approve/Deny buttons.
- Prompt entry with slash-command support.
- Session and agent creation dialogs.
- Model, backend, profile, stop, kill, compact, and help actions.
- Background processes manager (Procs button).
- Peer connections manager (Peers button) — canvas-based graph visualization.
- KDE Plasma palette detection with a Qt Quick Basic fallback outside Plasma.

The application communicates through 9P and the event stream. It does not need a running desktop daemon beyond `olliesrv` and the 9P client/socket environment.

## Build and installation

Prerequisites are a running Ollie installation, a C++17 compiler, CMake, Qt, KDE Frameworks, and the native 9P client library installed under `~/.local`.

Build the KDE integration from the repository root:

```sh
make kde
```

Build and install it:

```sh
make
```

The KDE build is delegated to `kde/CMakeLists.txt` and targets KF6/Qt6.

Install targets include:

- `ollie-gui` under `~/.local/bin`.
- Qt/KDE plugins for KRunner, Kate, and KIO.
- The `ollie://` KIO protocol definition.
- Dolphin service-menu actions and helper scripts.
- Plasma environment setup under `~/.config/plasma-workspace/env`.

Restart or refresh Plasma/KDE service caches after installation when required.

## Architecture

```text
┌──────────────┐     libollie9p / ollie-9p     ┌──────────────┐
│ KDE clients  │ ────────────────────────────▶ │  olliesrv    │
│ Qt/QML/KF    │       authenticated 9P        │ agent + 9P   │
└──────────────┘                               └──────────────┘
```

The GUI uses native client code for streaming and session operations. Other integrations may invoke `ollie-9p` or plan9port’s `9p` client. All use the same namespace, file operations, blocking reads, and control semantics.

## Source map

| Area | Location |
|---|---|
| Build and install | `Makefile`, `kde/CMakeLists.txt` |
| Qt/QML GUI | `kde/gui/` |
| Native 9P client | `kde/lib9p/`, `kde/gui/lib9pclient.*` |
| KRunner | `kde/krunner/` |
| Kate | `kde/kate/` |
| KIO | `kde/kio/` |
| Dolphin actions | `kde/dolphin/` |
| Plasma environment | `kde/99-ollie.sh` |

For the public protocol and namespace, see [`architecture-9p.md`](architecture-9p.md). For the core agent runtime, see [`architecture-core.md`](architecture-core.md).

## Plan 9 Plumber Integration

`ollie-gui` integrates with the Plan 9 plumber for context-aware navigation. The GUI listens on the `ollie` plumb port for `ollie://` URLs.

### URL Scheme

```
ollie://session/agent#blockId
ollie://session/agent
ollie://session
```

| Part | Description |
|---|---|
| `session` | Session name (required) |
| `agent` | Agent name (optional) |
| `#blockId` | 8-character hex block ID to fetch (optional) |

Block IDs are deterministic SHA256-derived identifiers. Use `log.raw` (JSONL) to see block IDs in the `"id"` field.

Examples:
- `ollie://default/main#a1b2c3d4` — fetch block "a1b2c3d4" from agent "main" in session "default"
- `ollie://myproject/src:kate-custom` — switch to agent "src:kate-custom" in session "myproject"
- `ollie://default` — switch to session "default"

### Setup

1. Add the ollie plumb rule to `$HOME/lib/plumbing`:

```
# ollie:// URLs go to the ollie port
type is text
data matches 'ollie://[a-zA-Z0-9_\-.:]+(/[a-zA-Z0-9_\-.:]+)?(#[a-f0-9]+)?'
plumb to ollie
```

Or include the bundled rules file:

```
include /path/to/ollie/data/plumbing
```

2. Reload plumber rules:

```sh
cat $HOME/lib/plumbing | 9p write plumb/rules
```

3. Ensure `ollie-gui` is running — it opens the `ollie` port for reading.

### Usage

From any Plan 9 application (acme, sam, rc, etc.):

```sh
plumb 'ollie://default/main#a1b2c3d4'
```

Or right-click an `ollie://` URL in acme/sam and plumb it.

The GUI also provides a 📋 button on bookmarks to copy the `ollie://` link to the clipboard, making bookmarks plumbable from anywhere.