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

Add observations on system introspection and visibility

This commit is contained in:
Levi Neely 2026-05-01 12:11:34 +02:00
parent 645b37753c
commit 0facee4aee
1 changed files with 7 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
doc/OBSERVATIONS.md
View File

@ -1,40 +1,11 @@
# Observations
# System Observations
**Filesystem as interface** — if you know how to operate a filesystem, you know how to operate ollie. Any tool that reads and writes files — `ed`, `vim`, Python, `cat`, a shell script — is already a fully capable ollie client. No SDK, no API, no protocol to learn.
## Introspection and State Visibility
**Simple front-ends** — A front-end reads `chat`, writes `prompt`, polls `state`. There is no protocol to implement.
A significant architectural strength of Ollie is the total transparency of agent state via the 9P filesystem. When tasked with "introspecting" on a complex, multi-agent session, the orchestrator demonstrated the ability to:
**Crash resiliency** — Memory (`m/`) is written to persistent storage outside the session. If a session crashes or is killed mid-task, it is not lost — a fresh session picks up where the previous one left off.
1. **Direct Log Inspection**: Use standard file tools (`tail`, `grep`) to read the `chat` and `prompt` files of subagents. This allowed for the recovery of semantic state even when agents failed to use established notification protocols.
2. **Context Synthesis**: Combine current session memory (what the orchestrator "knew" it had done) with data extracted from peer sessions.
3. **Cross-Session Verification**: Directly verify that requested changes (e.g., commits, file deletions) were actually performed by inspecting the state of the relevant worktrees and `git` history, rather than merely taking the subagent's word for it.
**[Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)** — Anthropic describes code execution as "a foundational primitive for building high-performance agents." ollie takes that literally: `execute_code` is the only built-in tool. It is a pipeline executor — single stage, multi-stage, and parallel fan-out are all the same primitive. New capabilities are added by dropping a script into `t/` and a skill in `sk/`.
**Parallel execution** — `execute_code` accepts a `steps` array of pipeline stages. A `{parallel: [...]}` stage fans out concurrently within the pipeline. Sequential stages chain stdout → stdin. All stages accept inline code and named tool scripts interchangeably.
**Radical transparency** — The rendered system prompt for any session is readable at `s/{id}/systemprompt` — the prompt the agent is actually running with, not a reconstruction. The prompt parts that compose it live in `p/`; the agent can read its own instructions but cannot modify them.
**Discoverability** — `ls s/{id}/` shows every control surface. `cat t/idx` and `cat sk/idx` list available tools and skills. `cat help` explains the rest.
**Composability** — `execute_code` stages chain the same way Unix pipes chain programs. Sessions chain by reading `s/{id}/chat` and writing to another session's `prompt` or `fifo.in`.
**Passive memory** — Every session's chat history accumulates at `s/{id}/chat`, searchable with `grep`. An agent doesn't need to actively decide what to remember. This extends across sessions: an agent can search another session's chat for answers that have already been worked through.
**Sub-agents** — `subagent_spawn` creates an independent session under `s/`, submits a prompt, and returns immediately with the session path. Subagents coordinate with the parent and each other by writing to each other's `prompt` files — direct async message passing over the filesystem. For parallel spawn, a `{parallel: [...]}` stage in `execute_code` starts multiple subagents simultaneously.
**No MCP** — MCP (Model Context Protocol) adds a JSON-RPC client, transport layer, initialization handshake, and subprocess lifecycle management to do what `execute_code {tool: "name"}` already does. Every MCP server can be replaced by a tool script in `t/` and a skill in `sk/`. `x/elevate` proved this: it replaced an MCP server with a shell script. See [doc/NO_MCP.md](NO_MCP.md) for the full justification.
**AI pipelines with standard tools** — ollie scripts compose into multi-stage AI pipelines via Unix pipes. Proof-of-concept:
```
; u/optimize -n 2 -cm qwen/qwen3-8b -jm 'anthropic/claude-opus-4.6' 'generate a hello world program. use c++.' >[2]/dev/null | s/bfg
```
`u/optimize` generates and judges candidate prompts, emitting the best to stdout; `s/bfg` acts on it. Any tool that reads stdin and writes stdout is already a pipeline stage.
**Prompt composition** — `s/bfg` outputs can be nested to arbitrary depth using shell command substitution. The inner prompt completes, its output becomes part of the outer prompt:
```
; echo 'translate to japanese: '`echo 'say hello' | s/bfg` | s/bfg
こんにちは！👋
```
This enables prompt pipelines where each stage transforms, filters, or augments the previous stage's output — all with standard shell syntax.
This "God-mode" visibility ensures that "stuck" states or "hallucinations" are not black boxes; they are observable system states that can be diagnosed and corrected through standard administrative primitives.