From c88a176fd1b2d8dac516d1294f47de0f5a298efa Mon Sep 17 00:00:00 2001
From: Levi Neely <141506390+lneely@users.noreply.github.com>
Date: Sat, 18 Jul 2026 22:29:11 +0200
Subject: [PATCH] readme: document D-Bus interface; add missing introspection
 entries

---
 README.md | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 main.go   |  32 +++++++++++++
 2 files changed, 165 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e818668
--- /dev/null
+++ b/README.md
@@ -0,0 +1,133 @@
+# ollie-dbus
+
+D-Bus daemon exposing the ollie agent runtime on the session bus as `org.ollie.SessionManager`. Used by the KDE Plasma widget and other desktop clients.
+
+## Building
+
+```sh
+mk
+```
+
+Installs `ollie-dbus` to `$HOME/bin`.
+
+## Usage
+
+```sh
+ollie-dbus   # starts daemon, connects to session bus
+```
+
+The daemon claims the bus name `org.ollie.SessionManager` and exports a single object at `/org/ollie/SessionManager`. It persists active sessions to `~/.local/share/ollie/active-sessions/` and restores them on restart. Desktop notifications are sent via `org.freedesktop.Notifications` when a turn completes.
+
+A `.desktop` file (`org.ollie.SessionManager.desktop`) is included for D-Bus activation.
+
+## Interface
+
+Bus name: `org.ollie.SessionManager`  
+Object path: `/org/ollie/SessionManager`  
+Interface: `org.ollie.SessionManager`
+
+### Session lifecycle
+
+| Method | Args | Returns |
+|--------|------|---------|
+| `CreateSession` | `cwd`, `backend`, `model`, `agent` | `session_id` (string) |
+| `ListSessions` | — | `[]string` (tab-separated: id, state, model, agent) |
+| `KillSession` | `session_id` | `bool` |
+| `RenameSession` | `session_id`, `new_name` | `bool` |
+
+### Interaction
+
+| Method | Args | Returns |
+|--------|------|---------|
+| `Submit` | `session_id`, `prompt` | `bool` |
+| `Interrupt` | `session_id` | `bool` |
+| `Compact` | `session_id` | `bool` |
+| `ClearContext` | `session_id` | `bool` |
+
+### State queries
+
+| Method | Args | Returns |
+|--------|------|---------|
+| `GetState` | `session_id` | state string (idle, thinking, calling:X) |
+| `GetChat` | `session_id`, `offset` (int64) | `text`, `new_offset` |
+| `GetUsage` | `session_id` | usage string |
+| `GetCost` | `session_id` | cost string |
+| `GetEnv` | `session_id` | env string (key=value lines) |
+| `GetConfig` | `session_id` | config string (key=value lines) |
+| `SetConfig` | `session_id`, `key`, `value` | `bool` |
+| `GetContext` | `session_id` | JSONL message history |
+| `GetPlan` | `session_id` | plan string |
+| `SetPlan` | `session_id`, `plan` | `bool` |
+| `GetSystemPrompt` | `session_id` | rendered system prompt |
+| `GetContextSize` | `session_id` | context size string |
+| `GetPreviousPrompt` | `session_id` | last submitted prompt |
+
+### Enumeration
+
+| Method | Args | Returns |
+|--------|------|---------|
+| `ListBackends` | — | `[]string` |
+| `ListModels` | `session_id` | `[]string` |
+| `ListAgents` | — | `[]string` |
+
+### Peers
+
+| Method | Args | Returns |
+|--------|------|---------|
+| `PeerAdd` | `session_id`, `peer_id` | `bool` |
+| `PeerRemove` | `session_id`, `peer_id` | `bool` |
+| `PeerList` | `session_id` | `[]string` |
+| `PeerSubmit` | `session_id`, `peer_id`, `prompt` | `bool` |
+
+### Detached processes
+
+| Method | Args | Returns |
+|--------|------|---------|
+| `DetachProcess` | `session_id` | `bool` |
+| `ListDetached` | `session_id` | `[]string` (tab-separated: pid, command, started, status) |
+| `SignalDetached` | `session_id`, `pid` (int32), `signal` | `bool` |
+| `GetDetachedOutput` | `session_id`, `pid` (int32) | output string |
+| `DismissDetached` | `session_id`, `pid` (int32) | `bool` |
+
+### Stateless operations
+
+| Method | Args | Returns |
+|--------|------|---------|
+| `Generate` | `prompt`, `system`, `backend`, `model` | result string |
+| `Route` | `task`, `backend` | `"backend=X model=Y"` |
+| `Complete` | `cwd`, `file`, `prefix`, `suffix`, `context` | completion string |
+
+`Complete` uses env vars `OLLIE_COMPLETE_MODEL` and `OLLIE_COMPLETE_BACKEND` to select the model. It manages a persistent copilot session per working directory.
+
+### Signals
+
+| Signal | Args |
+|--------|---------|
+| `SessionCreated` | `session_id` |
+| `SessionKilled` | `session_id` |
+| `SessionRenamed` | `old_id`, `new_id` |
+| `StateChanged` | `session_id`, `new_state` |
+| `ChatUpdated` | `session_id`, `offset` (int64), `new_text` |
+| `ProcessDetached` | `session_id` |
+| `ProcessExited` | `session_id`, `pid` (int32), `exit_code` (int32) |
+
+`ChatUpdated` is coalesced (emitted at most every 150ms) to avoid flooding the bus during streaming.
+
+## Example (gdbus)
+
+```sh
+# Create a session
+gdbus call -e -d org.ollie.SessionManager \
+  -o /org/ollie/SessionManager \
+  -m org.ollie.SessionManager.CreateSession \
+  "$PWD" "" "" ""
+
+# Submit a prompt
+gdbus call -e -d org.ollie.SessionManager \
+  -o /org/ollie/SessionManager \
+  -m org.ollie.SessionManager.Submit \
+  "<session_id>" "hello"
+
+# Monitor signals
+gdbus monitor -e -d org.ollie.SessionManager
+```
diff --git a/main.go b/main.go
index af00c52..3083f11 100644
--- a/main.go
+++ b/main.go
@@ -1487,6 +1487,30 @@ const introspectXML = `<node>
       <arg name="context" type="s" direction="in"/>
       <arg name="result" type="s" direction="out"/>
     </method>
+    <method name="DetachProcess">
+      <arg name="session_id" type="s" direction="in"/>
+      <arg name="success" type="b" direction="out"/>
+    </method>
+    <method name="ListDetached">
+      <arg name="session_id" type="s" direction="in"/>
+      <arg name="processes" type="as" direction="out"/>
+    </method>
+    <method name="SignalDetached">
+      <arg name="session_id" type="s" direction="in"/>
+      <arg name="pid" type="i" direction="in"/>
+      <arg name="signal" type="s" direction="in"/>
+      <arg name="success" type="b" direction="out"/>
+    </method>
+    <method name="GetDetachedOutput">
+      <arg name="session_id" type="s" direction="in"/>
+      <arg name="pid" type="i" direction="in"/>
+      <arg name="output" type="s" direction="out"/>
+    </method>
+    <method name="DismissDetached">
+      <arg name="session_id" type="s" direction="in"/>
+      <arg name="pid" type="i" direction="in"/>
+      <arg name="success" type="b" direction="out"/>
+    </method>
     <signal name="SessionCreated">
       <arg name="session_id" type="s"/>
     </signal>
@@ -1506,6 +1530,14 @@ const introspectXML = `<node>
       <arg name="offset" type="x"/>
       <arg name="new_text" type="s"/>
     </signal>
+    <signal name="ProcessDetached">
+      <arg name="session_id" type="s"/>
+    </signal>
+    <signal name="ProcessExited">
+      <arg name="session_id" type="s"/>
+      <arg name="pid" type="i"/>
+      <arg name="exit_code" type="i"/>
+    </signal>
   </interface>
   ` + introspect.IntrospectDataString + `
 </node>`