diff --git a/README.md b/README.md index 2da62e1..c202a85 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,6 @@ Single Go module with one Git submodule (kde). | `fs/` | Go | 9P filesystem tree for session namespace | | `detach/` | Go | Background process management | | `elevate/` | Go | Elevation broker (privilege escalation) | -| `mount/` | Go | FUSE-based 9P mount for network transparency | | `sandbox/` | Go | Landlock sandbox config | | `cmd/olliesrv/` | Go | The main binary | | `cmd/ollie-9p/` | Go | 9P client | diff --git a/doc/architecture.md b/doc/architecture.md index 35da6e2..9d19a98 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -41,7 +41,6 @@ ollie/ ├── env/ Environment variable loading ├── log/ Structured logging ├── paths/ XDG path resolution -├── mount/ 9P FUSE mount client ├── cmd/ Binaries: │ ├── olliesrv/ 9P server │ ├── ollie-9p/ 9P client @@ -51,7 +50,7 @@ ollie/ ├── data/prompts/ Prompt templates (markdown) ├── data/tools/ Tool scripts + .meta sidecar files ├── data/skills/ Domain knowledge modules (markdown) -├── data/scripts/ Helper scripts (ollie-remount, ollie-watchdog) +├── data/scripts/ Helper scripts (ollie-remount, o) ├── data/services/ Systemd/xdg-autostart service files ├── prompts/ Embedded prompt templates (compiled into binary) └── doc/ Documentation diff --git a/doc/evolution.md b/doc/evolution.md index 6c13d4e..87fb27e 100644 --- a/doc/evolution.md +++ b/doc/evolution.md @@ -651,7 +651,7 @@ ollie/ ← single Go module ├── data/agents/ ← agent configs (JSON) ├── data/prompts/ ← system prompt fragments (markdown) ├── data/skills/ ← domain knowledge modules (markdown) -├── data/scripts/ ← ollie-remount, ollie-watchdog +├── data/scripts/ ← ollie-remount, o CLI ├── data/services/ ← systemd, xdg-autostart ├── prompts/ ← embedded prompt templates ├── sandbox/ ← landrun sandbox profiles (YAML) diff --git a/doc/usage.md b/doc/usage.md index 2f10663..27975da 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -509,36 +509,53 @@ See each repo's README for installation and usage. ## `o` — Terminal CLI -`o` is a multi-call shell script that wraps `ollie-9p` into a human-friendly interface. Installed to `~/bin/o` by `just install-scripts`. +`o` is a multi-call shell script that wraps `ollie-9p` into a human-friendly interface. Installed to `~/bin/o` by `just install-data`. ### Quick start ```sh -# If only one session exists, it's auto-selected: +# Set context first: +export session=myproject agent=default +# or use the env helper: +eval $(o env myproject default) + +# Then interact: o tail # stream chat output o prompt # interactive prompt REPL o stop # interrupt the agent o kill # kill the session - -# Multiple sessions — pick one: -eval $(o env myproject) -# or: -export session=myproject agent=default ``` ### Commands | Command | Description | |---|---| -| `o read ` | Read a file from the active agent's namespace | -| `o ls [path]` | List namespace entries (defaults to agent dir) | -| `o ctl ` | Send raw control command | +| `o read ` | Read a file from the namespace | +| `o write [data]` | Write to a file (args or stdin) | +| `o readloop ` | Read in a loop (re-reads after return) | +| `o ls [path]` | List namespace entries | +| `o ctl ` | Send raw control command to agent | | `o stop` | Interrupt the running agent | | `o kill` | Kill the active session | | `o prompt` | Interactive multi-line prompt REPL | | `o tail` | Stream chat output | | `o tui` | Launch tmux TUI (see below) | -| `o env [session] [agent]` | Print eval-able env vars | +| `o env [session] [agent]` | Print export statements for context | + +### Path resolution + +Paths are resolved based on context (`$session`, `$agent`): +- **Root paths** (`session/*`, `agents`, `models`, `help`, `ctl`) → used as-is +- **Agent files** (`chat`, `state`, `prompt`, etc.) → require `$session` + `$agent` +- **Session files** (`env`, `ctl`, `name`, etc.) → require `$session` only + +```sh +o read models # root-level, no context needed +o ls session # list all sessions +export session=foo agent=bar +o read chat # → session/foo/agent/bar/chat +o readloop statewait # blocks until agent state changes +``` ### Prompt REPL slash commands @@ -564,7 +581,7 @@ Multi-line input: type lines, press Enter on a blank line to send. Ctrl+D exits. | `session` | Active session name | | `agent` | Active agent name | -If exactly one session/agent exists, it is auto-selected. If multiple exist, `o` lists them and exits with an error telling you to choose. +Context must be set explicitly via `export` or `eval $(o env ...)`. Commands that require context will fail fast with a clear error message if not set. --- @@ -594,14 +611,15 @@ If exactly one session/agent exists, it is auto-selected. If multiple exist, `o` ### How it works ```sh +export session=myproject agent=default o tui ``` -1. Resolves session and agent from environment (or auto-selects). +1. Requires `$session` and `$agent` to be set (fails with error if missing). 2. Creates a tmux session named `o-`. 3. Splits into 4 panes, each with `session` and `agent` exported: - **Pane 0** (left, large): `o tail` — blocking read on `chat`, streams tokens as they arrive. - - **Pane 1** (top-right): `o read statewait` — blocks until agent state changes (`idle` → `thinking` → `calling: tool` → `idle`), then prints and blocks again. + - **Pane 1** (top-right): `o readloop statewait` — blocks until agent state changes (`idle` → `thinking` → `calling: tool` → `idle`), then prints and blocks again. - **Pane 2** (bottom-right): bare shell with context set — run `o stop`, `o read cost`, `o ctl compact`, etc. - **Pane 3** (bottom, full-width): `o prompt` — multi-line REPL with slash commands. 4. Focuses the prompt pane and attaches.