ollie/kde/README.md

# ollie-kde

KDE integration for [ollie](../README.md). The directory contains a Qt/QML desktop client, KDE plugins, a KIO worker, and Dolphin service-menu helpers. Components communicate with `olliesrv` through the Ollie 9P namespace.

## Architecture

```text
Plasma / KDE applications
  ├─ ollie-gui (Qt Quick) ───────┐
  ├─ KRunner plugin               │
  ├─ Kate plugin                  ├─ Ollie 9P namespace ── olliesrv
  ├─ KIO worker (`ollie://`)     │       (Unix socket)
  └─ Dolphin helper scripts ─────┘
```

There are two transport paths:

- `ollie-gui`, the Kate plugin, and the KIO worker link to `libollie9p.so` through the shared `gui/lib9pclient` wrapper.
- KRunner and the Dolphin scripts invoke a 9P command-line client (`9p` or `ollie-9p`) and address the server at the default Ollie namespace.

The KDE clients do not start `olliesrv`; start the server using the instructions in the repository root before using them.

## Components

- **`ollie-gui`** — Qt Quick application for browsing sessions and agents, sending prompts, viewing streamed chat, interrupting or killing agents, and creating, renaming, and configuring sessions and agents. It includes light/dark/system theme handling, font settings, a collapsible session sidebar (`Ctrl+B`), and clipboard support.
- **KRunner plugin (`krunner_ollie.so`)** — Handles queries beginning with `ollie`. It lists sessions, offers session termination, runs one-shot prompts through the `generate` 9P file, and opens `ollie-gui` when a session is selected.
- **Kate plugin (`ollie_kate.so`)** — Adds context actions, agent/session management, status and connection recovery, and ghost-text completion. It deliberately has no chat panel; use `ollie-gui` for the full conversation.
- **KIO worker (`kio_ollie.so`)** — Provides the `ollie://` virtual filesystem. It supports listing, stat, reading, writing, directory creation, deletion, and renaming in the Ollie 9P namespace.
- **Dolphin service menus** — `ollie-ask` performs a one-shot `generate` request for a selected file or directory and displays the result; `ollie-session-here` idempotently creates the `default` session and an agent named after the selected directory.

There is no system-tray component.

## Dependencies

- Qt 6 (Core, Widgets, Quick, QuickControls2, Network), or Qt 5 equivalents when `OLLIE_KF5=ON`
- ECM (Extra CMake Modules)
- KF6/KF5 Runner and CoreAddons for KRunner
- KF6/KF5 TextEditor and SyntaxHighlighting for Kate
- KF6/KF5 KIO for the `ollie://` worker
- `libollie9p.so` and its header from `kde/lib9p/`
- A 9P CLI named `9p` (KRunner) and `ollie-9p` (Dolphin scripts)

KF6/Qt6 is selected by default when KF6 Runner and CoreAddons are available. Set `-DOLLIE_KF5=ON` to force the KF5/Qt5 build.

## Build

The KDE directory is a CMake project. From `kde/`:

```sh
cmake -S . -B build-cmake
cmake --build build-cmake -j
```

For KF5/Qt5:

```sh
cmake -S . -B build-kf5 -DOLLIE_KF5=ON
cmake --build build-kf5 -j
```

The build produces:

- `ollie-gui`
- `lib/kf6/krunner/krunner_ollie.so` and `lib/kf6/ktexteditor/ollie_kate.so` (or `kf5` paths)
- `lib/kf6/kio/kio_ollie.so` (or `kf5` paths)
- `libollie9p.so`, installed to `${CMAKE_INSTALL_LIBDIR}` (normally `lib` or `lib64`)

The CMake project installs `ollie-gui` and `libollie9p.so`. The plugins, KIO metadata, desktop files, Dolphin scripts, icon, and Plasma environment files are source-tree assets and must be installed or packaged separately; the `just kde` and `just install-kde` commands described by older documentation are not provided in this repository.

## Install

Choose an install prefix, for example `~/.local`:

```sh
cmake -S . -B build-cmake -DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build build-cmake -j
cmake --install build-cmake
```

That installs `ollie-gui` and `libollie9p.so` to the prefix's KDE bindir and `${CMAKE_INSTALL_LIBDIR}`, respectively. To use the other components, install the matching built plugin and source assets into the locations used by your KDE/Qt installation:

- KRunner: the `kf6/krunner` (or `kf5/krunner`) plugin directory, plus `krunner/metadata.json`
- Kate: the `kf6/ktexteditor` (or `kf5/ktexteditor`) plugin directory, plus `kate/metadata.json`
- KIO: the corresponding KIO plugin directory, `kio/ollie.protocol`, and `kio/ollie.json`
- Dolphin: `dolphin/*.desktop` in `~/.local/share/kio/servicemenus/` and both helper scripts in `~/.local/bin/`
- GUI integration: `gui/org.ollie.gui.desktop`, `gui/ollie.svg`, and the appropriate `99-ollie*.sh` environment file

The exact plugin directories are distribution- and Qt-version-dependent. After installing KDE metadata or plugins, rebuild the relevant service cache (for example `kbuildsycoca6` or `kbuildsycoca5`) and restart the affected KDE application.

## Usage

### GUI Application (`ollie-gui`)

Launch from application menu or terminal:
```sh
ollie-gui
```

Features:
- Session list with state indicators (idle, thinking, tool call)
- Collapsible sidebar (Ctrl+B to toggle)
- Live chat view with auto-scroll
- Inline prompt input
- Real-time updates via 9P polling
- Theme support (light/dark/system)
- Font customization

### KRunner

- `ollie <prompt>` — one-shot generation via `Generate` (no session created); shows result in a popup
- `ollie list` — show active sessions
- `ollie kill <id>` — terminate a session

### Dolphin

Right-click any file or directory:
- **Ask Ollie about this** — one-shot prompt with file context, shows result in kdialog
- **Start Ollie session here** — creates a persistent session in that directory

### Kate

Enable the "Ollie" plugin in Settings → Configure Kate → Plugins. The plugin provides:

**Context menu actions** (right-click in editor):
- **Ask about file** — describe and explain the current file
- **Explain this** — explain selected code (or current line)
- **Fix this** — ask agent to fix selected code
- **Refactor this** — ask agent to refactor selected code
- **Add tests for this** — generate unit tests for selection
- **Document this** — add documentation comments to selection
- **Send verbatim** — send selected text wrapped in a code fence (language auto-detected)
- **Review Diff** — review a diff for issues (visible on Diff-highlighted documents)

- **Inline completion:** Ghost text is requested automatically after 500 ms of idle time at the end of a line. Suggestions can be accepted, cycled, dismissed, toggled, or requested manually with the shortcuts below. The completion implementation uses the configured Ollie completion backend; the current plugin source does not expose `OLLIE_COMPLETE_BACKEND` or `OLLIE_COMPLETE_MODEL` environment variables.

**Keyboard shortcuts:**

| Key | Action |
|-----|--------|
| Tab | Accept ghost suggestion |
| Meta+O, N | Next suggestion |
| Meta+O, P | Previous suggestion |
| Meta+O, C | Toggle completion on/off |
| Meta+O, D | Dismiss suggestion |
| Meta+O, Tab | Request completion manually |

**Agent management:**
- Auto-creates a "kate" session with one agent per project directory
- Auto-selects agent matching the current Kate project
- Connection health monitoring with auto-reconnect (5s heartbeat)
- Status bar shows state:
  - Red `✗ disconnected` — server unreachable
  - Gray `○ no agent` — connected, no agent
  - Green `● kate/ID` — connected with active agent

**Git++ integration:**
- "Ollie: Review Diff" action registered in Git++ plugin's diff context menu

**Tip:** Tile the `ollie-gui` window alongside Kate to see the full chat stream from context actions.

## File Layout

```text
kde/
├── CMakeLists.txt                  # Qt5/KF5 and Qt6/KF6 build configuration
├── README.md
├── gui/                            # ollie-gui (C++/QML) and desktop assets
│   ├── main.cpp, main.qml
│   ├── ollie9pclient.*             # GUI state/session client
│   ├── lib9pclient.*               # shared native 9P wrapper
│   ├── nativestreamer.*            # chat, state, and event streams
│   ├── sessionmodel.*, chatblockmodel.*
│   ├── thememanager.*, clipboardhelper.*
│   └── *.qml, qml.qrc, *.desktop, ollie.svg
├── krunner/                        # KRunner plugin and metadata
├── kate/                           # Kate context actions and ghost provider
├── kio/                            # `ollie://` KIO worker and protocol metadata
├── dolphin/                        # service menus and helper scripts
├── lib9p/                          # Go-built libollie9p shared library/header
└── 99-ollie*.sh                    # Qt/KF-specific Plasma environment snippets
```

`build/` and `build-cmake/` are local build directories and are not source components.


## Development Notes

- The native clients use `libollie9p.so` directly; KRunner and Dolphin are the exceptions and use a 9P CLI subprocess.
- The GUI maintains native chat, agent-state, and event streams and polls the daemon heartbeat every 2.5 seconds for recovery.
- The Kate plugin is lightweight: context actions, agent management, and ghost text; it has no chat panel.
- The KIO worker exposes the server's namespace as a mutable virtual filesystem, not as a local mirror.
- CMake supports KF6/Qt6 and KF5/Qt5 via `OLLIE_KF5`.
- The CMake install target installs `libollie9p.so` to `${CMAKE_INSTALL_LIBDIR}` (`lib` or `lib64`), alongside the executable rather than under the Qt plugin directory.

## Troubleshooting

**Plugins not appearing after installation:**
- Run `kbuildsycoca6` (KF6) or `kbuildsycoca5` (KF5) to rebuild system cache
- Restart Plasma: `plasmashell --replace` or log out/in

**"9p" or "ollie-9p" not found:**
- KRunner needs an executable named `9p` (or a `PLAN9` environment pointing to `bin/9p`).
- Dolphin helpers need `ollie-9p` in `PATH`.
- Build/install the main Ollie project or plan9port as appropriate.

**KDE client cannot connect:**
- Ensure `olliesrv` is running and its default 9P socket is available.
- The clients resolve the default namespace from `NAMESPACE`, or from `/tmp/ns.$USER.$DISPLAY/ollie` when `NAMESPACE` is unset.

**Kate plugin crashes or is rejected:**
- Check that Kate and the plugin use the same Qt major version (Qt5 vs Qt6).
- Verify that `libollie9p.so` and its runtime dependencies are discoverable.

**Ghost text not appearing:**
- Ensure `olliesrv` is running and the 9P socket is accessible
- Ghost text only shows when cursor is at end-of-line
- Check Meta+O, C hasn't toggled completion off

**Dolphin actions not working:**
- Ensure `ollie-ask` and `ollie-session-here` are installed in `~/.local/bin/`
- Check that the service menu desktop files are in `~/.local/share/kio/servicemenus/`