# D-Bus Operational Model

Fallback interface when 9P is unavailable. If the 9P filesystem is mounted, use it instead.

The `org.ollie.SessionManager` D-Bus service runs on the session bus. Your session ID is `${OLLIE_SESSION_ID}`.

**Service coordinates:**
- Service: `org.ollie.SessionManager`
- Object: `/org/ollie/SessionManager`
- Interface: `org.ollie.SessionManager`

**Data directories** (local filesystem, read-only to the agent):
- `~/.config/ollie/prompts/` — Prompt templates
- `~/.config/ollie/skills/` — Domain-specific knowledge files
- `~/.config/ollie/tools/` — Tool scripts
- `~/.config/ollie/memory/` — Persistent memory files
- `~/.config/ollie/agents/` — Agent definitions (JSON)

**Peer Agent Discovery**: Use `ListSessions` to discover other active sessions:

```sh
dbus-send --session --dest=org.ollie.SessionManager --type=method_call --print-reply \
  /org/ollie/SessionManager org.ollie.SessionManager.ListSessions
```

Each entry: `id\tstate\tmodel\tagent`

**Inter-Agent Communication**: Use `PeerSubmit` to send a prompt to another session. Always provide a return path (e.g., [message from $OLLIE_SESSION_ID]).

## Methods

All session operations go through the D-Bus interface.

### Session Lifecycle

| Method | Args | Returns | Purpose |
|---|---|---|---|
| `CreateSession` | cwd, backend, model, agent, system_prompt, remote | session_id | Create a new session |
| `ListSessions` | — | array of "id\tstate\tmodel\tagent" | Discover sessions |
| `KillSession` | session_id | bool | Terminate a session |
| `RenameSession` | session_id, new_name | bool | Rename a session |

### Agent Interaction

| Method | Args | Returns | Purpose |
|---|---|---|---|
| `Submit` | session_id, prompt | bool | Submit a prompt to an agent |
| `Interrupt` | session_id | bool | Interrupt current agent turn |
| `Compact` | session_id | bool | Compact conversation history |
| `ClearContext` | session_id | bool | Clear conversation history |

### Session State

| Method | Args | Returns | Purpose |
|---|---|---|---|
| `GetState` | session_id | state | Current state: `idle`, `thinking`, `calling: <tool>` |
| `GetChat` | session_id, offset | text, new_offset | Read chat output from byte offset |
| `GetConfig` | session_id | key=value text | Read session config (model, backend, agent, cwd, state) |
| `SetConfig` | session_id, key, value | bool | Change a config setting (model, cwd) |
| `GetContext` | session_id | JSONL | Full conversation context as JSONL messages |
| `GetContextSize` | session_id | string | Context token size |
| `GetUsage` | session_id | string | Token usage stats |
| `GetCost` | session_id | string | Cost tracking |
| `GetEnv` | session_id | key=value text | Session environment variables |
| `GetPlan` | session_id | string | Read session plan |
| `SetPlan` | session_id, plan | bool | Write session plan |
| `GetSystemPrompt` | session_id | string | Rendered system prompt |
| `GetPreviousPrompt` | session_id | string | Previous prompt text |

### Peers

| Method | Args | Returns | Purpose |
|---|---|---|---|
| `PeerAdd` | session_id, peer_id | bool | Add bidirectional peer link (both sides updated) |
| `PeerRemove` | session_id, peer_id | bool | Remove bidirectional peer link (both sides updated) |
| `PeerList` | session_id | array of peer_ids | List peers |
| `PeerSubmit` | session_id, peer_id, prompt | bool | Send prompt to peer |

### Detached Processes

| Method | Args | Returns | Purpose |
|---|---|---|---|
| `DetachProcess` | session_id | bool | Detach current running process to background |
| `ListDetached` | session_id | array of "pid\tcmd\tstarted\tstatus" | List background processes |
| `SignalDetached` | session_id, pid, signal | bool | Send signal (TERM, KILL) to detached process |
| `GetDetachedOutput` | session_id, pid | string | Read output from detached process |
| `DismissDetached` | session_id, pid | bool | Dismiss a finished detached process |

### Global Services

| Method | Args | Returns | Purpose |
|---|---|---|---|
| `ListBackends` | — | array of names | Available backends |
| `ListModels` | session_id | array of names | Models for session's backend |
| `ListAgents` | — | array of names | Available agent definitions |
| `Generate` | prompt, system, backend, model | string | One-shot LLM generation (no session needed) |
| `Route` | task, backend | "backend=X model=Y" | Pick a backend+model for a task |
| `Complete` | cwd, file, prefix, suffix, context | string | Code completion |

## Signals

| Signal | Args | Purpose |
|---|---|---|
| `SessionCreated` | session_id | New session appeared |
| `SessionKilled` | session_id | Session terminated |
| `SessionRenamed` | old_id, new_id | Session renamed |
| `StateChanged` | session_id, state | Agent state transition |
| `ChatUpdated` | session_id, offset, text | New chat output available |
| `ProcessDetached` | session_id | A process was detached |
| `ProcessExited` | session_id, pid, exit_code | A detached process finished |

## Operations

```bash
# Discover sessions
dbus-send --session --dest=org.ollie.SessionManager --type=method_call --print-reply \
  /org/ollie/SessionManager org.ollie.SessionManager.ListSessions

# Create a session
dbus-send --session --dest=org.ollie.SessionManager --type=method_call --print-reply \
  /org/ollie/SessionManager org.ollie.SessionManager.CreateSession \
  string:"$PWD" string:"" string:"" string:"default" string:"" string:""

# Submit a prompt
dbus-send --session --dest=org.ollie.SessionManager --type=method_call \
  /org/ollie/SessionManager org.ollie.SessionManager.Submit \
  string:"SESSION_ID" string:"your prompt here"

# Get chat output (use gdbus for multi-return)
gdbus call --session --dest org.ollie.SessionManager \
  --object-path /org/ollie/SessionManager \
  --method org.ollie.SessionManager.GetChat "SESSION_ID" 0

# One-shot generation (no session)
gdbus call --session --dest org.ollie.SessionManager \
  --object-path /org/ollie/SessionManager \
  --method org.ollie.SessionManager.Generate "summarize this" "" "" ""

# Route a task
gdbus call --session --dest org.ollie.SessionManager \
  --object-path /org/ollie/SessionManager \
  --method org.ollie.SessionManager.Route "implement login page" ""

# Code completion
gdbus call --session --dest org.ollie.SessionManager \
  --object-path /org/ollie/SessionManager \
  --method org.ollie.SessionManager.Complete "$PWD" "main.go" "func " "" ""

# Send prompt to peer
dbus-send --session --dest=org.ollie.SessionManager --type=method_call \
  /org/ollie/SessionManager org.ollie.SessionManager.PeerSubmit \
  string:"MY_SESSION" string:"PEER_SESSION" string:"your prompt"

# Kill a session
dbus-send --session --dest=org.ollie.SessionManager --type=method_call \
  /org/ollie/SessionManager org.ollie.SessionManager.KillSession \
  string:"SESSION_ID"
```