docs: update filesystem spec to match current implementation (cfg, remove stale files)

This commit is contained in:
Levi Neely 2026-05-01 10:37:58 +02:00
parent b95cfb632a
commit 8d0c0c51a3
3 changed files with 20 additions and 20 deletions

View File

@ -13,10 +13,9 @@ Every session lives under `/s/{id}/`:
| `/s/new` | Create a session (write `name`, `backend`, `model`, `agent`, `cwd`) |
| `/s/{id}/prompt` | Submit a prompt (dispatched async on close) |
| `/s/{id}/chat` | Cumulative conversation history (append-only read) |
| `/s/{id}/state` | Current state: `idle`, `thinking`, `calling:<tool>` |
| `/s/{id}/cfg` | Session config (KV): state, backend, model, agent, cwd, params |
| `/s/{id}/statewait` | **Blocking read** — returns when state changes |
| `/s/{id}/ctl` | Control commands: `stop`, `kill`, `compact`, model/backend switches |
| `/s/{id}/cfg` | Mutable session config (KV pairs) |
| `/s/{id}/ctl` | Control commands: `stop`, `kill`, `compact`, `rn <name>` |
Utility files at the session root (`/s/`) provide higher-level operations:

View File

@ -135,7 +135,7 @@ Schedule regular cleanup with a cron job:
```sh
cat $OLLIE/s/new # show the spec template
printf 'cwd=%s\n---\nSummarize this.\n' "$PWD" > $OLLIE/s/new
cat $OLLIE/s/<session-id>/state # running | idle | failed: <reason>
cat $OLLIE/s/<session-id>/cfg # state, backend, model, agent, cwd, params
cat $OLLIE/s/<session-id>/chat
rm -r $OLLIE/s/<session-id> # cancel and remove
```
@ -288,10 +288,10 @@ send() {
while true; do
read -r _ <&3 && { exec 3<&-; break; }
exec 3<&-
[ "$(cat s/$sid/state)" != "idle" ] && break
[ "$(awk -F= '/^state=/{print $2}' s/$sid/cfg)" != "idle" ] && break
exec 3< s/$sid/statewait
done
until [ "$(cat s/$sid/state)" = "idle" ]; do sleep 0.5; done
until [ "$(awk -F= '/^state=/{print $2}' s/$sid/cfg)" = "idle" ]; do sleep 0.5; done
tail -c +$(($(cat s/$sid/offset) + 1)) s/$sid/chat
}

View File

@ -21,7 +21,6 @@ ollie/
backends available backends (ro) cat
help this file (ro) cat
m/ memories (r/w) ls, cat, edit
idx memory index (ro) cat
p/ prompt templates (ro) ls, cat
s/ sessions ls
idx session index (ro) cat: id state cwd backend model, one per line
@ -34,25 +33,24 @@ ollie/
bbg background query (x) exec s/bbg [flags] [prompt...]
cleanup kill idle sessions (x) exec s/cleanup
<id>/ session directory rm -r to kill; mv to rename
agent active agent (r/w)
backend active backend (r/w)
cfg session config (r/w) cat: KV (state, backend, model, agent, cwd, maxTokens, temperature, frequencyPenalty, presencePenalty); write KV to change
chat conversation log (r/w; write to save transcript to tr/)
offset byte offset of chat after last user prompt; tail -c +$((offset+1)) gives model response (ro)
context rendered context window (ro)
cost estimated cost (ro)
ctl control (w) stop, kill, clear, compact, rn <name>
ctxsz context size (ro)
ctxszwait blocks until ctxsz changes (ro)
cwd working directory (r/w)
cwdwait blocks until cwd changes (ro)
env session environment (ro)
fifo.in queue a prompt (w)
fifo.out pop queued prompt (ro)
model active model (r/w)
models available models (ro)
offset byte offset after last user prompt (ro)
plan plan scratchpad (r/w)
prompt submit prompt (w)
state agent state (ro) idle | thinking | calling: <tool>
prompt.prev previous prompt (ro)
statewait blocks until state changes (ro)
systemprompt rendered system prompt (ro)
tail tail helper (x)
usage token counts (ro)
usagewait blocks until usage changes (ro)
sk/ skills (r/w) ls, cat, edit
idx skill index (ro) cat
<name>.md skill content (r/w)
@ -60,6 +58,9 @@ ollie/
idx tool index (ro) cat
tr/ transcripts (ro) ls, cat
<YYYYMMddTHHmmss>-chat.md saved transcripts
u/ utility scripts (x) ls, exec
x/ system scripts (x) ls, exec
tmp/ scratch space (r/w) ls, cat, edit, rm
```
## Session management
@ -76,12 +77,12 @@ echo stop > ~/mnt/ollie/s/<id>/ctl # interrupt current turn
```sh
cat ~/mnt/ollie/backends # list backends
cat ~/mnt/ollie/s/<id>/models # list models for current backend
echo ollama > ~/mnt/ollie/s/<id>/backend
echo qwen3:8b > ~/mnt/ollie/s/<id>/model
echo myagent > ~/mnt/ollie/s/<id>/agent
echo backend=ollama > ~/mnt/ollie/s/<id>/cfg
echo model=qwen3:8b > ~/mnt/ollie/s/<id>/cfg
echo agent=myagent > ~/mnt/ollie/s/<id>/cfg
```
Writes to backend, model, and agent are rejected while the agent is running.
Writes to cfg are rejected while the agent is running.
## Environment