lkn
/
ollie
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document observer and companion patterns

This commit is contained in:
Ollie Agent 2026-08-16 20:21:48 +02:00
parent f02c5c45e7
commit 12575fbadf
1 changed files with 51 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
doc/architecture-ide.md
View File

@ -90,8 +90,58 @@ Kate also provides automatic ghost-text completion. When enabled, the plugin:
The completion request can use plugin-configured backend and model overrides. It is separate from the agent session prompt path: it is a one-shot generation request, not a turn queued into the project agent.
## Extending another editor
## Observer and companion patterns
An editor integration does not need to be an active operator. Ollie can assist along a spectrum of automation, context, token use, and environmental cost:
- **Manual query:** ask about a file or selection only when needed. Lowest automation and token use.
- **Selection actions:** explain, fix, refactor, document, or add tests from an editor action. The coder chooses each operation.
- **Companion agent:** keep a project agent available for prompts, chat, plans, and controls while the coder works. It is interactive but not continuously triggered.
- **Observer agent:** feed a second, usually read-only agent the current diff or editor state. It wakes only when the feed changes and reports bugs, missed error handling, security issues, or other requested concerns.
- **Completion assistant:** request bounded one-shot generation at the cursor. Kate’s ghost text is an example; it does not add every completion to the agent’s conversation history.
- **Automated workflow:** let scripts or external task systems trigger agents, collect `statewait`, and route results. This has the highest automation and potentially the highest token and process cost.
### Companion and observer wiring
Every agent has a change-detecting `feed` file. Writing new content stores it and signals waiters. A blocking read returns only when the content differs from the reader’s previous value. The agent’s feed consumer submits each new value as a prompt, so a companion or observer can be driven by editor state or `git diff` without polling the model continuously.
```sh
# Human coding session plus read-only observer
o myproj/obs new /path/to/repo
o myproj/obs ctl agent observer
while :; do
git diff HEAD -- | o myproj/obs write feed
sleep 5
done
```
A more event-driven driver can wait for the coder to finish a turn:
```sh
while :; do
o myproj/coder read statewait >/dev/null
git diff HEAD -- | o myproj/obs write feed
done
```
The observer does not need write access to the repository. It receives the diff as context, can inspect the checkout using read-only tools, and reports through `chat`. A companion can instead share the normal project agent and receive direct prompts.
### Choosing the level of assistance
The right pattern depends on more than convenience:
| Pattern | Automation | Typical cost | Good fit |
|---|---:|---:|---|
| Manual query | Low | Low | Occasional explanation or second opinion. |
| Selection action | Low | Low–medium | Focused edits with human initiation. |
| Companion | Medium | Medium | Interactive pair programming. |
| Observer | Medium–high | Medium–high | Continuous review while code changes. |
| Cursor completion | High frequency | Variable | Local, bounded implementation suggestions. |
| Automated workflow | High | High or bounded by policy | Repeatable checks, external task graphs, or CI-like work. |
Token use is a design parameter. Send focused selections instead of whole repositories, trigger observers on meaningful changes instead of every keystroke, use read-only profiles for review, and apply explicit step or model limits when automation is not worth the cost. The same choices reduce latency, process churn, and energy use. Lower automation is not a failure mode; it is often the responsible choice for simple work or expensive models.
These patterns are integrations over sessions, `feed`, `statewait`, `chat`, tools, and 9P. Ollie does not need a separate observer runtime, companion subsystem, or automation scheduler.
Ollie does not require a native plugin. Any editor that can run a command, read and write files, or open a Unix socket can use Ollie through the 9P namespace.
The general integration pattern is: