@dumbmice/pi-todo-loop 0.1.1 → 0.2.1

package/docs/behaviour.md

@@ -4,6 +4,10 @@ The mechanics behind [README](../README.md). Read this when you are debugging be
 whether to change a default, or wondering why the loop did something. It assumes you know that a
 **settle** is a model response with no tool calls — the only turn that can end a run.
 
+The rule the whole design follows: **the extension never edits your prompt.** It appends one hidden
+nudge at a stop and otherwise keeps out of the conversation. Reading and updating the list is the
+agent's job, through the todo tool it already has.
+
 ## The turn it adds
 
 `rpiv-todo` renders and stores the list but never asks pi for another turn. Pi ends a run when the model
@@ -13,51 +17,54 @@ requests one more turn, so the model continues instead of handing control back.
 Two consequences follow from that being the only mechanism available:
 
 - **A continuation is a persisted entry.** pi has no "resume without appending anything", so each
-  continuation writes one `custom_message` with `display: false` and a constant body that states the
-  instruction (`Continue with the open todo tasks…`). It is invisible in the TUI, but it is in the
-  session file and, when no block is injected, it is what the model reads.
+  continuation writes one `custom_message` with `display: false` and one of two constant bodies:
+  *"Continue with the open todo tasks; use the todo tool to read and update the list. If the human's
+  latest instruction says to stop or limits what to do, do that instead."* It is invisible in the TUI,
+  but it is in the session file, it is what the model reads, and it is the only text this extension
+  ever adds.
 - **Only a settle spends a round.** `turn_end` fires after every assistant response, including one that
   ended in a tool call; those already cause pi's next request, so they cost nothing and write no marker.
-  A round, a strike and a marker therefore always concern a turn that would otherwise have ended the run.
+  A round, a stall and a marker therefore always concern a turn that would otherwise have ended the run.
 
 ## Markers and role alternation
 
 A marker sits between two assistant turns, which is what keeps the conversation alternating: a request
 that contained `assistant → assistant` in a row is rejected by alternation-requiring providers.
 
-The `context` hook therefore keeps a marker only where it separates two assistant turns, and drops it
-when either neighbour is user-role: at the tail, immediately before your own message, or in a run of
-markers. The block replaces a marker tail, merges into a `user`/`custom` tail, and is appended after an
-assistant or toolResult tail.
-
-One exception is documented: `bashExecution`, `branchSummary` and `compactionSummary` tails cannot take
-a merge — pi rebuilds those from their own fields and ignores `content` — so the block becomes a
-separate message there and the request briefly holds two user-role messages. Losing the list on a
-compaction summary would be worse.
-
-## The injected block
-
-While tasks are open, every request ends with an ephemeral `<todo_loop_state>` block: the open tasks with
-their ids and statuses, and an instruction that yields to you. It is never persisted, which is why
-compaction cannot remove it.
-
-- **The block is user-role text and the last thing in the request.** It sits after your newest message
-  and says that your latest instruction outranks it. Models vary in how readily they take that
-  concession: one that reads your "stop" as authoritative will refuse, and those refusals cost up to
-  `maxRounds` turns. That is the same reason `injectState: false` exists.
-- **Task text is sanitised, not interpolated.** Subject, `activeForm` and `status` are model-authored —
-  possibly from a fetched page or a repo file — so every Unicode line terminator flattens, `<` is
-  escaped, controls/bidi/zero-width characters and unpaired surrogates are dropped, and labels truncate
-  by code point. Without this, a task subject could close the tag and forge a directive.
-- **The ids are the todo tool's own**, except where the stored list supplies an unusable or duplicate
-  id: that row moves to a free number so each row can be addressed, which means a `todo` call using the
-  shown number can fail when the tool wrote the list that way.
-- **The block escalates once.** On the first request of a chain it only asks for status
-  moves; from the first continuation onwards it adds a reconciliation clause — *"if this
-  list has drifted from the work, reconcile it now: update statuses, add what is missing,
-  and remove what no longer applies"* — with removal last. A first sighting should not
-  invite reshaping the list; after a nudge that left the list untouched, a drifted list is
-  the likelier explanation. Verified: 115 tests, including both sides of the gate.
+The `context` hook may remove a marker and nothing else. It drops one when either non-marker neighbour
+is user-role — next to your own message, or in a run of markers — because that position would project to
+`user → user`. A marker at the tail always stays: it is the nudge, and dropping it would leave the
+continuation request ending on an assistant turn, which is the shape pi refuses to continue from.
+
+The hook returns `undefined` when nothing needs removing, so an ordinary request is passed through as
+the object it already was — not re-built, not extended.
+
+## Stalls, and the block tool
+
+Nothing here stops the loop for being quiet. A model that keeps answering without moving the list is
+kept alive until the round cap, because "stuck" and "waiting for a person" look identical from the
+outside — and one of them must not be punished.
+
+- A **settle** whose task signature is unchanged increments `stalled`; a settle that changed the list
+  resets it. The counter has no cap: it decides *when to ask*, not when to give up.
+- On the first settlement since progress that finds `stalled >= 1` — one stop that did not move the
+  list — the nudge is the variant that adds *"If you cannot proceed without a person, call
+  `todo_loop_block` with the reason."* It is offered **once per stall**; tool work re-arms it, so a
+  second, separate stall after real progress is a new question.
+- A **tool turn** clears `stalled`. Work is progress even when the list was not touched.
+- **`todo_loop_block`** is the agent's own exit. It is advertised in the prompt from the first turn —
+  pi lists it in `<tools>` and carries its guideline in `<rules>`, because the tool declares a
+  `promptSnippet` — and the nudge is the timed offer, not the only way to learn it exists. It takes a
+  reason, stores `{reason, anchor}` in memory and stops continuations for that message. The human is notified, `/todoloop` shows
+  `waiting for you: <reason>`, and the human's next message is a new anchor, so the block clears itself
+  — there is no unblock call.
+- A block with an empty reason is refused, and the loop keeps running: the reason is the whole point.
+  The tool also refuses while the loop is paused or a kill switch is present, and says so, so a
+  disabled extension never notifies or writes state.
+- **`staleSettles`** counts settles since the list last changed; a tool turn that leaves the list
+  unchanged does not clear it. It
+  never injects anything and never stops anything: it only decorates the reason string
+  (`, list unchanged for N settles`) so a burn through the round cap does not read like healthy work.
 - **A list cleared by `todo` calls alone is announced.** If every task goes from open to closed in a
   turn whose only tool results were `todo`, a warning says so once. The loop's success state and its
   failure state are the same observable.
@@ -67,18 +74,17 @@ compaction cannot remove it.
 | Counter | Meaning | Reset by |
 |---|---|---|
 | `rounds` | continuations spent for the current human message | a new human message, `/todoloop reset`, a new process |
-| `strikes` | settles in a row that left the list unchanged | the list changing, a completed tool turn, a new human message |
+| `stalled` | settles in a row that left the list unchanged — no cap; it decides when the block hint is offered | the list changing, a completed tool turn, a new human message |
 | `staleSettles` | settles since the list last changed | the list changing, a new human message |
 
 - **One budget per human message.** A user-role message carrying a `customType` (this extension's
   marker, another extension's hidden message) is skipped when choosing the anchor, so it does not reset
   the budget; `/todoloop` prints the anchor it is using.
-- **A stop keeps the budget shut.** Hitting the cap or the strike limit does not clear the counters, so
+- **A stop keeps the budget shut.** Hitting the cap does not clear the counters, so
   another extension's continuation or a provider retry under the same message cannot re-arm 12 rounds.
   A queued human message is a new anchor and resets the budget the ordinary way.
-- **A stale list stops on the cap, not on strikes**, because any tool turn clears the strike budget.
-  That is why the cap reason appends `, list unchanged for N settles` — so a stale burn does not read
-  like healthy work.
+- **A stale list stops on the cap**, never earlier: any tool turn clears the stall. That is why the cap
+  reason appends `, list unchanged for N settles`.
 - **Errors do not close the budget.** A turn that ends `error` or `aborted` stops the loop for that turn
   and spends no round; the counters are left as they are, so the next settle under the same message can
   continue — which is what a provider retry hits.
@@ -94,18 +100,18 @@ compaction cannot remove it.
 |---|---|
 | `continuing: round 1/12, 2 open` | working as intended |
 | `stopped: list is clear` | every remaining task is `completed`; a list whose tasks are all `deleted` reports `no list` instead |
-| `stopped: no list` | no recognised todo state on the branch — see the four causes below |
-| `stopped: 2 consecutive turns with no progress, 2 open` | the last two settles ran no tool and left the list unchanged |
-| `stopped: round cap 12 reached, 2 open` | the budget is spent; with `, list unchanged for N settles` appended, the model worked without updating the list |
+| `stopped: no list` | no recognised todo state on the branch — see the five causes below |
+| `waiting for you: waiting on Dana's review` | the agent called `todo_loop_block`; your next message resumes |
+| `stopped: round cap 12 reached, 2 open` | the budget is spent; `, list unchanged for N settles` means it worked without updating the list, `, the agent stalled and may need a person` means the last round was one stop that did not move the list |
 | `stopped: turn outcome was error` / `aborted` | the provider failed, or you aborted the turn |
 | `paused by user` | `/todoloop pause`; `/todoloop resume` or restart |
-| `resumed by user` | `/todoloop resume`; the next settle may continue |
-| `counters reset` | `/todoloop reset` cleared the rounds, strikes and list signature |
+| `resumed by user` | `/todoloop resume`, or the human's next message clearing a pending block; the next settle may continue |
+| `counters reset` | `/todoloop reset` cleared the rounds, stalls, list signature and any pending block |
 | `idle` | nothing has run yet in this process |
 
 ## Where the list comes from
 
-The list is read from the session branch on every request, never cached: a `rpiv-todo-state` custom
+The list is read from the session branch on every turn, never cached: a `rpiv-todo-state` custom
 entry's `data.tasks`, or a `todo` toolResult's `details.tasks`, whichever is newer.
 
 That is deliberate. A cache would owe invalidation on session switch, branch, compaction, process start
@@ -117,13 +123,16 @@ Two deviations follow from it:
 
 - **The branch is not the model's context.** After a compaction the model's context drops older
   entries, but the reader still walks the whole branch, so `/todoloop` can report open work the model
-  has no list for. The panel and the model can disagree.
+  has no list for. This is the hole the removed injection used to paper over: a model that has been
+  compacted may not know the list exists until it calls `todo` or is nudged. The nudge is the reminder;
+  the tool is the source.
 - **A newer malformed entry is skipped** in favour of an older valid one, so after a shape change the
   reader serves the list as of that change. Reading an errored `todo` call as "list clear" would be
   worse.
 
-`no list` therefore has four causes: no todo tool installed, a tool that is not named `todo`, a shape
-this extension does not recognise, or every task `deleted`.
+`no list` therefore has five causes: the model never called the `todo` tool in this session, no todo
+tool installed, a tool that is not named `todo`, a shape this extension does not recognise, or every
+task `deleted`.
 
 ## Scope
 
@@ -143,23 +152,23 @@ this extension does not recognise, or every task `deleted`.
 
 Invalid config never fails a turn: missing, unreadable or invalid values fall back to the defaults.
 That includes values below `1` — `"maxRounds": 0` means "use 12", not "never continue". Numbers are
-clamped so a typo cannot defeat the cap it configures: `maxRounds` ≤ 1000, `maxStrikes` ≤ 100,
-`maxInjectedTasks` ≤ 50.
+clamped so a typo cannot defeat the cap it configures: `maxRounds` ≤ 1000.
 
 ## Cost
 
 - A continuation is a normal model turn: the whole conversation is sent again, so cost scales with the
   number of continuations × session size. `maxRounds` caps continuations, not turns — tool turns are
-  pi's own and unbounded, so a long tool-heavy stretch can be many turns for one round. That, not the
-  block, is the dominant term.
-- `context` reads the config and probes the kill switch, and walks the branch only when it is going to
-  inject. `turn_end` does all three on every turn. While tasks are open the block adds ~100 tokens at
-  the tail; `injectState: false` adds none and leaves the model to call the todo tool's `list` action.
-- One small measurement on `deepseek-flash` (a 2.7k-token session, five turns): ~1,050 uncached input
-  tokens per turn with injection on against ~405 with `injectState: false`, and cache reads occurred in
-  both runs (16.0k vs 36.1k total). The block does not disable the prompt cache, but it and the head
-  rebuild cost a few hundred uncached tokens per request. An order of magnitude, not a benchmark — the
-  two runs took different trajectories.
+  pi's own and unbounded, so a long tool-heavy stretch can be many turns for one round. That is the
+  dominant term.
+- The extension adds one short marker per continuation (~40 tokens), plus one constant tool declaration
+  and the prompt entries pi derives from it — `<tools>` line, `<rules>` guideline, description and
+  schema, roughly 700 characters together, in every request. None of it carries task state, and there
+  is no per-request block. Neither the snippet nor the guideline is gated by the kill switch or
+  `/todoloop pause`; only the hooks and the call itself are. Whatever the model needs it reads with the `todo` tool, and that result
+  is part of its own conversation rather than a parallel copy.
+- `context` walks the branch and returns `undefined` unless a marker actually has to be removed, so on
+  a normal turn it costs one projection pass. `turn_end` reads the config, probes the kill switches and
+  walks the branch on every turn.
 
 ## More
 

package/docs/pi-api-alignment.md

@@ -7,13 +7,15 @@ versions that was established against.
 |---|---|---|
 | `@earendil-works/pi-coding-agent` | **1.5.0** | `PI_API_SNAPSHOT` in `src/index.ts` |
 | `@juicesharp/rpiv-todo` | **2.15.0** | this file (item 12) |
-| Node | 22.23.2 | README *Tested against* |
+| Node | 22.23.2 | README *Requirements* |
 
 Last verified **2026-11-04**. Bump a row here, its constant where one exists, and the README table in
 the same commit as the change that depends on it.
 
 The contract is followed where it is documented: `turn_end` boundary proposals, draft entry types,
-`context` hook ownership of the message list, `display: false`, and `registerCommand`. Nothing here
+`context` hook ownership of the message list, `display: false`, `registerCommand`, and `registerTool`
+with a hand-written JSON-schema `parameters` object (pi validates any JSON Schema; the `typebox`
+import in the docs is a convenience, and avoiding it keeps this package dependency-free). Nothing here
 calls pi internals; item 1 nonetheless depends on behaviour pi documents nowhere, which is why it is
 listed below rather than assumed.
 
@@ -28,7 +30,7 @@ full. Items that produce no signal in the transcript are marked _(silent)_.
    projection must end on a message whose role is not `assistant` — otherwise the boundary reports an
    invalid continuation and drops it. pi offers no `resume()` that appends nothing, so a continuation
    is always expressed as *one* appended entry. We append a `custom_message` with `display: false`:
-   invisible in the TUI, about 200 bytes per continuation in the journal _(silent in the transcript)_.
+   invisible in the TUI, about 220 bytes per continuation in the journal _(silent in the transcript)_.
 2. **Markers stay in history and are not stripped.** They sit between two assistant turns, so they are
    what keeps the conversation alternating: `assistant → marker(user) → assistant`. Removing them
    exposes runs of consecutive assistant messages, which alternation-requiring providers reject — a
@@ -45,14 +47,12 @@ full. Items that produce no signal in the transcript are marked _(silent)_.
    used by `pi-invisible-continue`'s `/continue`
    (<https://github.com/monotykamary/pi-invisible-continue>, not re-tested here). Conflating the two is
    the mistake this item exists to prevent.
-4. **The block is appended only where it is needed, and it never doubles the tail.** Three
-   configurations get no block: `injectState: false`, a list with no open task, and the kill switch. In
-   the first two the request keeps whatever tail the history has (a marker, an assistant turn, or the
-   human's own message) and the model must call the todo tool's `list` action to learn the list — the
-   one place this extension asks for compliance instead of enforcing state. When a block is added it
-   replaces a tail marker, is merged into a human-role tail, and is appended only after an assistant or
-   tool tail. No request ending on an assistant message has been exercised against a provider in this
-   repository's testing; the live runs used the default configuration.
+4. **The `context` hook only ever removes messages.** It returns a different list in exactly one
+   case: a marker of ours sits next to a human message, where it would project to `user → user`. Every
+   other request is passed through untouched (`undefined`), including the human's own message and every
+   tool turn, so the prompt a human sends is the prompt the model reads. Earlier versions appended a
+   state block to each request; that was removed because it rewrote the human's prompt on turns the
+   loop did not cause.
 5. **Returning a changed list rebuilds the request head.** pi documents that a `context` handler which
    returns a different message list causes it to replay the current prompt sections and tool
    declarations into one leading system message ahead of the returned list. The rebuild is lossless
@@ -71,7 +71,10 @@ full. Items that produce no signal in the transcript are marked _(silent)_.
 9. **`sendUserMessage` and `Agent.prompt` are deliberately not used.** `sendUserMessage` would add a
    visible user-role message per continuation and pollute the transcript; calling the agent directly
    bypasses `AgentSession` lifecycle handling (busy state, queuing, retry, abort).
-10. **The kill switch is checked in both hooks, not once at load.** Removing it or creating the file
+10. **The kill switch is checked in both hooks and in the block tool, not once at load.** It cannot
+    withdraw the tool's prompt entry: pi renders `<tools>`/`<rules>` from the registration, so a
+    disabled session still shows an exit whose call is then refused with "not running". Removing it
+    would need `pi.setActiveTools` from a hook — a new coupling we did not take for this. Removing it or creating the file
    takes effect on the next request, without `/reload`.
 11. **No dependency on `@earendil-works/pi-coding-agent`, and no peer declaration for it.** Nothing
     here imports the package: the boundary is typed `pi: any` and contexts are typed structurally
@@ -115,16 +118,13 @@ full. Items that produce no signal in the transcript are marked _(silent)_.
 14. **The loop's counters are not reconstructible from the session file** _(silent)_. A `turn_end`
     handler is handed `outcome`, `entries` and `continue`; what a `-p`/JSON run persists for the event
     carries only `{type, message, toolResults}`. A session file therefore shows which continuations happened and
-    when, not how many rounds or strikes were left, nor why the loop stopped; that is only visible live
+    when, not how many rounds or stalls were left, nor why the loop stopped; that is only visible live
     through `/todoloop`. Two runs that end for different reasons can look identical on disk.
 
-15. **Three user-role tails cannot take a merge, so the block becomes a second user message there.**
-    pi rebuilds the content of `bashExecution`, `branchSummary` and `compactionSummary` from their own
-    fields and ignores `content`, so writing the block into one of them would delete it. Those three
-    get a separate user message instead, which means the request briefly has two user-role messages in a
-    row. Accepted deliberately: a compaction summary is exactly when the model most needs the list, and
-    losing it silently is worse than an adjacency that providers merge anyway.
-
+15. _(Inapplicable since the state block was removed.)_ Three user-role tails —
+    `bashExecution`, `branchSummary`, `compactionSummary` — cannot take a merged `content`, because pi
+    rebuilds those from their own fields. Nothing is merged into them now: the only text this
+    extension adds is a standalone marker message, which needs no merge and creates no adjacency.
 16. **The reader walks `getBranch()`, which is not the model-visible context.** pi's compaction-aware
     projection is `buildContextEntries()`, and a `context_edit` can hide an entry from future model
     context while it stays on the branch. Reading the branch therefore means the extension can report a

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@dumbmice/pi-todo-loop",
-	"version": "0.1.1",
-	"description": "Keep pi working while a todo list still has open tasks, and keep that list in context across compaction.",
+	"version": "0.2.1",
+	"description": "Keep pi working while a todo list still has open tasks, and stop when the agent asks for a person.",
 	"type": "module",
 	"license": "MIT",
 	"author": {

package/scripts/check-pack.mjs

@@ -15,7 +15,6 @@ const REQUIRED = [
 	"src/index.ts",
 	"src/loop.ts",
 	"src/state.ts",
-	"src/inject.ts",
 	"src/config.ts",
 	"docs/pi-api-alignment.md",
 	"README.md",

package/src/config.ts

@@ -23,14 +23,6 @@ function coerce(raw: unknown): Partial<LoopConfig> {
 	const maxRounds = bounded(record.maxRounds, 1_000);
 	if (maxRounds !== undefined) out.maxRounds = maxRounds;
 
-	const maxStrikes = bounded(record.maxStrikes, 100);
-	if (maxStrikes !== undefined) out.maxStrikes = maxStrikes;
-
-	if (typeof record.injectState === "boolean") out.injectState = record.injectState;
-
-	const maxInjectedTasks = bounded(record.maxInjectedTasks, 50);
-	if (maxInjectedTasks !== undefined) out.maxInjectedTasks = maxInjectedTasks;
-
 	return out;
 }