From 0facee4aee8d58ec509bcdacc8079b99e29b3c6e Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Fri, 1 May 2026 12:11:34 +0200 Subject: [PATCH] Add observations on system introspection and visibility --- doc/OBSERVATIONS.md | 43 +++++++------------------------------------ 1 file changed, 7 insertions(+), 36 deletions(-) diff --git a/doc/OBSERVATIONS.md b/doc/OBSERVATIONS.md index 1543789..7ffcb9f 100644 --- a/doc/OBSERVATIONS.md +++ b/doc/OBSERVATIONS.md @@ -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.