# Editor Integration

Ollie exposes editor integration through the 9P namespace. Acme and Kate are examples of clients, not separate Ollie workflows.

An integration reads editor state, writes a prompt to an agent, and reads the result. It does not embed the agent loop, prompt assembly, backend selection, tool execution, or session store.

```text
editor or IDE
  ├─ file, selection, cursor, project, or diff
  └─ 9P client → agent/.../prompt
                    ├─ log / log.raw
                    ├─ state
                    ├─ status
                    └─ ctl
```

## Integration pattern

This is a concrete pattern for extending an editor. It is not a required interface. People can add as much or as little integration as their editor and workflow warrant.

1. Read the current file, project root, selection, cursor, or diff.
2. Ensure `olliesrv` is running.
3. Select or create an agent with `cwd` set to the project root.
4. Construct a prompt containing the operation and source context.
5. Write it to `session/{sname}/agent/{aname}/prompt`.

Use `ollie-9p`, the `o` wrapper, or a native 9P client library. A native plugin is optional. The integration can stop after writing the prompt; the user can observe and control the agent through `ollie-gui`, a terminal, or another 9P client tiled beside the editor.

```sh
selection=$(...)  # editor-specific
file=$(...)

printf 'Read %s and explain this code:\n\n```\n%s\n```\n' \
  "$file" "$selection" |
  o project/agent prompt
```

## Prompt and edit pattern

A useful prompt and edit pattern is:

- State whether the operation is read-only or mutating.
- Include the source path and project working directory.
- Treat selections as context, not instructions or authoritative source.
- Require repository inspection before edits.
- Require formatting and relevant tests or diagnostics after edits.

The editor does not need to display agent output or reload files itself. Use the existing editor behavior for changed files and a separate Ollie client for chat, state, and control.

| Operation | 9P integration |
|---|---|
| Explain file or selection | Write a read-only prompt; read `chat`. |
| Fix, refactor, document, or add tests | Write a mutating prompt; subscribe to state events; reload the buffer on completion. |
| Review a diff | Send the diff as fenced `diff` context. |
| Inline completion | Send a bounded prefix/suffix request to root `generate`. |
| Agent control | Write a command to `ctl`. |

## Companion agents

A companion agent receives direct prompts while the coder works.

Automation level is a client policy:

- Manual queries minimize automation and token use.
- Selection actions provide human-triggered focused operations.
- Companion agents provide interactive assistance.
- Cursor completion uses bounded one-shot generation.
- External scripts or task systems can trigger agents and collect results.

Trigger frequency, context size, model, and step limits determine latency, token use, process cost, and energy use. They do not change the 9P integration boundary.

## Examples

Acme and Kate are two clients that implement the pattern above. The examples below describe their current behavior; they are not requirements or a canonical feature set.

### Acme

The Acme scripts use Acme's own 9P namespace to obtain the window filename and selection, then use the `o` wrapper to write a prompt to the project agent. They are ordinary shell scripts.

Setup:

```sh
export PATH="$PATH:/path/to/ollie/data/scripts/acme"
eval "$(o env mysession myagent)"
```

Add commands to an Acme window tag:

```text
OllieHere AskFile Explain Fix Refactor Document AddTests SendVerbatim
```

A selection command performs three operations:

```sh
echo 'addr=dot' | 9p write acme/$winid/ctl
selection=$(9p read acme/$winid/xdata)
echo "$prompt" | o "$OLLIE_SESSION/$OLLIE_AGENT" prompt
```

`Explain` constructs a read-only prompt containing the filename and selected code. `Fix`, `Refactor`, `Document`, and `AddTests` construct mutating prompts that tell the agent to inspect the repository, make a focused change, and run relevant verification. `SendVerbatim` sends a fenced selection as context without treating it as instructions. `AskFile` sends the current filename without requiring a selection. `OllieHere` selects or creates the project agent.

`OllieHere` is idempotent. It prints the project agent path, for example:

```text
OllieHere: acme/6c460de7
```

The path can be passed to `win`, which runs an ordinary command inside an embedded Acme terminal window:

```sh
win o acme/6c460de7 read chat
win o acme/6c460de7 prompt
```

`OllieHere` prints the `session/agent` path. `win` starts the command line in Acme. The remainder is the command and its arguments; `win` runs it and exits when the command exits. The first command displays the agent chat stream in the embedded terminal. The second runs the prompt REPL there. These are ordinary terminal commands, not special Acme UI components.

### Kate

The Kate plugin implements the same pattern natively. It obtains the active document and selection through KTextEditor, ensures a project agent, and writes directly to the agent's `prompt` file through `libollie9p`.

Its context-menu actions are concrete examples:

| Action | Prompt input |
|---|---|
| **Ask about file** | Active document path. |
| **Explain this** | Selection, or the current line when no selection exists, plus the file path. |
| **Fix this** | Selection and source location. |
| **Refactor this** | Selection and source location. |
| **Add tests for this** | Selection and source location. |
| **Document this** | Selection and source location. |
| **Send verbatim** | Selection in a language-tagged code fence. |
| **Review Diff** | Git++'s current diff, or the active diff document. |
| **Start Session** | Ensures the agent and updates its project working directory. |

Kate also provides an optional one-shot completion path. It sends a bounded prefix and suffix around the cursor to the root `generate` operation and displays the returned code as ghost text. This is separate from the project agent's prompt stream.

The Kate implementation is a native plugin, but the integration boundary is unchanged: obtain editor context and write a 9P prompt. The plugin does not provide an integrated chat or prompt window; select the corresponding Kate session in the KDE GUI and use its chat stream to interact with the agent. If preferred, run `o kate/{session} tui` in Kate's integrated terminal to use the TUI.

## Summary

An editor integration is a 9P client:

```text
editor context → agent/.../prompt → Ollie agent → files/chat/state
```

Read context from the editor, select an agent for the project, construct a prompt, and write it to `prompt`. The Kate plugin does not provide an integrated chat or prompt window; use the KDE GUI or TUI as the agent interaction surface.

A shell command is sufficient when the editor exposes the needed context and command execution. Otherwise, use its extension or plugin mechanism. Vim, Emacs, Acme, Kate, and other editors can use the same pattern through whatever integration mechanism they provide. The editor need only provide context and a way to issue a 9P request.