From 64b10b72269047adf6d970cc4d005af59540ee6d Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Thu, 16 Apr 2026 22:17:33 +0200 Subject: [PATCH] doc: document offset file semantics offset points to chat position after the last user prompt; tail -c +$((offset+1)) yields the model response for that turn. Replace stale reply references in prompts, help, ideas, and skills. Document offset usage in concurrent sessions pattern and shell script. Co-Authored-By: Claude Sonnet 4.6 --- doc/IDEAS.md | 11 +++++++---- doc/help.md | 2 +- prompts/01_ollie.md | 2 +- skills | 2 +- 4 files changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/IDEAS.md b/doc/IDEAS.md index 4cf1d0a..4f51cc9 100644 --- a/doc/IDEAS.md +++ b/doc/IDEAS.md @@ -34,6 +34,8 @@ See `prompts/08_subagents.md` and `skills/session-management/SKILL.md` for usage For workflows where multiple long-lived agents work in parallel and need to coordinate, the mechanism is direct prompt passing. Each agent is told its own session ID and its peers' IDs at startup. When an agent finishes a step and wants to hand off, it writes the result to another session's `prompt` — a plain file write from within `execute_code`. Writing to `prompt` queues by default, so a busy agent will not drop a message. +When a peer needs to read back the response it triggered, it polls the target session's `state` until idle, then reads `offset` and extracts the new output: `tail -c +$((offset+1)) s/$peer/chat`. The server sets `offset` to the byte position immediately after the user prompt is appended, so everything from that position to EOF is exactly the model response for that turn. + No external coordinator is needed after the initial kickoff. The agents themselves route work based on context in their prompts. A human can intervene at any time by writing to any session's `prompt`. #### Example: develop → review → test @@ -70,7 +72,7 @@ Each agent can use a different backend, model, or tool configuration. The bounda #### Predefined workflows -When the coordination logic is known in advance, a shell script can drive the entire workflow externally. Named sessions make routing unambiguous. The script captures a chat offset before each prompt submission, waits for the agent to finish, and reads only the new output — no `reply` file needed. +When the coordination logic is known in advance, a shell script can drive the entire workflow externally. Named sessions make routing unambiguous. The server updates `offset` to the byte position immediately after the user prompt is appended to chat. After the agent goes idle, `tail -c +$((offset+1))` yields exactly the model response for that turn. ```sh #!/bin/sh @@ -81,14 +83,15 @@ echo "name=developer agent=developer cwd=$cwd" > s/new echo "name=reviewer agent=reviewer cwd=$cwd" > s/new echo "name=tester agent=tester cwd=$cwd" > s/new -# Send a prompt to a session and return only the new output. +# Send a prompt and return the model response. +# The server sets offset after the user prompt is appended to chat; +# everything from offset to EOF is the model response for that turn. send() { sid=$1; shift printf '%s' "$*" > s/$sid/prompt while [ "$(cat s/$sid/state)" = "idle" ]; do sleep 0.2; done while [ "$(cat s/$sid/state)" != "idle" ]; do sleep 1; done - offset=$(cat s/$sid/offset) - tail -c +$((offset + 1)) s/$sid/chat + tail -c +$(($(cat s/$sid/offset) + 1)) s/$sid/chat } reply=$(send developer "Implement a function that parses a JSON config file.") diff --git a/doc/help.md b/doc/help.md index c6b4263..6bb7a58 100644 --- a/doc/help.md +++ b/doc/help.md @@ -40,7 +40,7 @@ ollie/ agent active agent (r/w) backend active backend (r/w) chat conversation log (ro) - offset byte offset of chat EOF before last prompt submit (ro) + offset byte offset of chat after last user prompt; tail -c +$((offset+1)) gives model response (ro) ctl control (w) stop, kill, clear, compact, rn ctxsz context size (ro) cwd working directory (r/w) diff --git a/prompts/01_ollie.md b/prompts/01_ollie.md index 877ee8b..c913f53 100644 --- a/prompts/01_ollie.md +++ b/prompts/01_ollie.md @@ -30,7 +30,7 @@ Each session is a directory `{{.OllieMountPath}}/s/{session-id}/`. Your current | `{{.OllieMountPath}}/s/{id}/enqueue` | write | Queue a prompt for execution after the current turn | | `{{.OllieMountPath}}/s/{id}/dequeue` | read | Pop the next queued prompt | | `{{.OllieMountPath}}/s/{id}/chat` | read | Full cumulative chat history (tail-able) | -| `{{.OllieMountPath}}/s/{id}/reply` | read | Assistant text from the most recent turn (tail-able) | +| `{{.OllieMountPath}}/s/{id}/offset` | read | Byte offset of chat immediately after the last user prompt; `tail -c +$((offset+1))` yields the model response for that turn | | `{{.OllieMountPath}}/s/{id}/state` | read | Current agent state: `idle`, `thinking`, or `calling: ` | | `{{.OllieMountPath}}/s/{id}/backend` | r/w | Active backend name | | `{{.OllieMountPath}}/s/{id}/agent` | r/w | Active agent name | diff --git a/skills b/skills index f48f208..2dd6fea 160000 --- a/skills +++ b/skills @@ -1 +1 @@ -Subproject commit f48f2086824a27530872748e62ed1fa748360fcf +Subproject commit 2dd6fea2e63db4f74cb61d7b66eb7b28334d8bc9