151 lines
5.6 KiB
Markdown
151 lines
5.6 KiB
Markdown
# 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.
|