lkn
/
ollie
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ollie/doc/architecture-kde.md

5.6 KiB
Raw Blame History

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.

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:

make kde

Build and install it:

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

┌──────────────┐     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. For the core agent runtime, see 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
  1. Reload plumber rules:
cat $HOME/lib/plumbing | 9p write plumb/rules
  1. Ensure ollie-gui is running — it opens the ollie port for reading.

Usage

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

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.