pi-btw 0.1.0 → 0.2.0

package/README.md

@@ -1,20 +1,21 @@
 # pi-btw
 
-A small [pi](https://github.com/badlogic/pi-mono) extension that adds a `/btw` command for side questions.
+A small [pi](https://github.com/badlogic/pi-mono) extension that adds a `/btw` side conversation channel.
 
-`/btw` runs immediately, even while the main agent is still busy.
+`/btw` opens a real pi sub-session with coding-tool access, and it runs immediately even while the main agent is still busy.
 
 ![BTW overlay example](docs/btw-overlay.png)
 
 ## What it does
 
-- asks a one-off side question using the current session context
-- returns an answer immediately in an overlay
-- does **not** disturb the running agent
-- does **not** save anything by default
-- optionally saves the result into the session with `--save`
-
-Saved BTW notes are visible in the session transcript, but excluded from future LLM context.
+- opens a parallel side conversation without interrupting the main run
+- runs that side conversation as a real pi sub-session with `read` / `bash` / `edit` / `write` tool access
+- keeps a continuous BTW thread by default
+- supports `/btw:tangent` for a contextless side thread that does not inherit the current main-session conversation
+- opens a focused BTW modal shell with its own composer and transcript
+- keeps BTW thread entries out of the main agent's future context
+- lets you inject the full thread, or a summary of it, back into the main agent
+- optionally saves an individual BTW exchange as a visible session note with `--save`
 
 ## Install
 
@@ -46,31 +47,111 @@ pi install /absolute/path/to/pi-btw
 
 ```text
 /btw what file defines this route?
-/btw --save what file defines this route?
-/btw -s summarize the last error in one sentence
+/btw how would you refactor this parser?
+/btw --save summarize the last error in one sentence
+/btw:new let's start a fresh thread about auth
+/btw:tangent brainstorm from first principles without using the current chat context
+/btw:inject implement the plan we just discussed
+/btw:summarize turn that side thread into a short handoff
+/btw:clear
 ```
 
-## Behavior
+## Commands
 
-### `/btw <question>`
+### `/btw [--save] <question>`
 
 - runs right away
-- shows the answer in an overlay
-- does not save it to the session
+- works while pi is busy
+- creates or reuses a real BTW sub-session instead of a one-off completion call
+- continues the current BTW thread
+- opens or refreshes the focused BTW modal shell
+- streams into the BTW modal transcript/status surface
+- persists the BTW exchange as hidden thread state
+- with `--save`, also saves that single exchange as a visible session note
+
+### `/btw:new [question]`
+
+- clears the current BTW thread
+- starts a fresh thread that still inherits the current main-session context
+- optionally asks the first question in the new thread immediately
+- if no question is provided, opens a fresh BTW modal ready for the next prompt
+
+### `/btw:tangent [--save] <question>`
+
+- starts or continues a contextless tangent thread
+- does not inherit the current main-session conversation
+- if you switch from `/btw` to `/btw:tangent` (or back), the previous side thread is cleared so the modes do not mix
+- opens or refreshes the same focused BTW modal shell
+- with `--save`, also saves that single exchange as a visible session note
+
+### `/btw:clear`
+
+- dismisses the BTW modal/widget
+- clears the current BTW thread
+
+### `/btw:inject [instructions]`
+
+- sends the full BTW thread back to the main agent as a user message
+- if pi is busy, queues it as a follow-up
+- clears the BTW thread after sending
+
+### `/btw:summarize [instructions]`
+
+- summarizes the BTW thread with the current model
+- injects the summary into the main agent
+- if pi is busy, queues it as a follow-up
+- clears the BTW thread after sending
+
+## Behavior
+
+### Real sub-session model
+
+BTW is implemented as an actual pi sub-session with its own in-memory session state, transcript events, and tool surface.
 
-### `/btw --save <question>`
+- contextual `/btw` threads seed that sub-session from the current main-session branch while filtering out BTW-visible notes from the parent context
+- `/btw:tangent` starts the same BTW UI in a contextless mode with no inherited main-session conversation
+- the overlay transcript/status line is driven from sub-session events, so tool activity, streaming deltas, failures, and recovery are all visible without scraping rendered output
+- handoff commands (`/btw:inject` and `/btw:summarize`) read from the BTW sub-session thread rather than maintaining a separate manual transcript model
 
-- if pi is idle: saves the BTW note immediately
-- if pi is busy: queues the BTW note and saves it after the current turn finishes
-- does not steer or interrupt the current agent run
+### In-modal slash behavior
+
+Inside the BTW modal composer, slash handling is split at the BTW/session boundary:
+
+- `/btw:new`, `/btw:tangent`, `/btw:clear`, `/btw:inject`, and `/btw:summarize` stay owned by BTW because they control BTW lifecycle or handoff behavior
+- any other slash-prefixed input is routed through the BTW sub-session's normal `prompt()` path
+- this means ordinary pi slash commands like `/help` are handled by the sub-session instead of being rejected by a modal-only fallback
+- if the sub-session cannot handle a slash command, BTW surfaces the real sub-session failure through the transcript/status state instead of inventing an "unsupported slash input" warning
+
+This keeps BTW-owned lifecycle commands explicit while giving the side conversation the same slash-command surface as the underlying sub-session.
+
+## Behavior
+
+### Hidden BTW thread state
+
+BTW exchanges are persisted in the session as hidden custom entries so they:
+
+- survive reloads and restarts
+- rehydrate the BTW modal shell for the current branch
+- preserve whether the current side thread is a normal `/btw` thread or a contextless `/btw:tangent`
+- stay out of the main agent's LLM context
+
+### Visible saved notes
+
+If you use `--save`, that one BTW exchange is also written as a visible custom message in the session transcript.
 
 ## Why
 
-Sometimes you want to ask a quick side question without:
+Sometimes you want to:
+
+- ask a clarifying question while the main agent keeps working
+- think through next steps without derailing the current turn
+- explore an idea, then inject it back once it's ready
+
+## Included skill
 
-- interrupting the current turn
-- adding noise to the main transcript
-- waiting for another user turn
+This package also ships a small `btw` skill so pi can better recognize when a side-conversation workflow is appropriate.
+
+It helps with discoverability and guidance, but it is not required for the extension itself to work.
 
 ## Development
 
@@ -78,6 +159,10 @@ The extension entrypoint is:
 
 - `extensions/btw.ts`
 
+The included skill is:
+
+- `skills/btw/SKILL.md`
+
 To use it without installing:
 
 ```bash