@tduyng/pi-prewalk 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +68 -98
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,139 +1,100 @@
1
1
  # @tduyng/pi-prewalk
2
2
 
3
- A task goes to the frontier planner, the planner gives the cheap executor a plan to carry out, and the executor hands the work back if it hits a wall. The phase decides every boundary, and no model is asked to.
3
+ Plan on the frontier model, execute on the cheap one, in one unbroken context. The first edit swaps the model, and the planner returns only when the executor hits a wall.
4
4
 
5
- ## The problem
5
+ Most turns in a task are execution: applying a change the plan already describes, running the check, reading the error. Paying frontier prices for those is the largest avoidable cost in a long session.
6
6
 
7
- Stencil measured 1.81B tokens over ~2M tool calls and found edits are about 9% of them. Reads are the rest.
7
+ Writing the plan down and handing it to a fresh session does not fix it. Stencil measured 1.81B tokens over about 2M tool calls and found edits are roughly 9 percent of them. Reads are the rest, so an executor reopens the files the planner already read, and the plan document saves the thinking while paying twice for the exploration.
8
8
 
9
- A plan document does not help. Whoever executes it opens the same files again.
9
+ `prewalk_plan` is 716 tokens and only while prewalk is armed in plan mode. The router is one hook on `streamSimple` and registers no schema, so an unarmed session pays nothing.
10
10
 
11
- prewalk keeps one context instead. The planner explores and makes the first edit, then the cheap model carries on from the same history. On SWE-bench it reached 92 to 97% of the frontier pass rate for 53 to 61% of its cost.
11
+ ## One context, two models
12
12
 
13
- ## The router
14
-
15
- prewalk registers one virtual model, `prewalk/auto`. Select it with `/prewalk` or from `/model`. Pi calls the router before every request, so prewalk never moves the session's model itself and no `setModel` runs in the middle of a task. Every model change in the session file is one prewalk made.
16
-
17
- Each route returns one request's model, so the planner and the executor can differ per request inside one task.
18
-
19
- ## A task boundary
20
-
21
- prewalk asks one question, and only when a task is about to start. The boundary is the gap between one settled run and the next prompt typed after it, so a task is routed once and the turns inside it are never touched.
13
+ A prompt cache belongs to one model, so a swap costs exactly one cold read of the prefix, at the cheap model's input rate, once per task. Both models then read the transcript and keep their own cache warm across their own turns.
22
14
 
23
- Pi's own `reason: "user"` cannot carry that boundary. It fires for a steer and a follow-up too, because both arrive as a user message after the last assistant message. prewalk keeps its own flag, set from the `input` event, which reads `streamingBehavior` as the three cases it actually is: undefined when the session was idle, `steer` when the text joins the turn in flight, and `followUp` when it waits for that turn to settle and then opens a task of its own. The first router call that sees the flag consumes it, so one prompt routes once. The source does not matter: a message from another extension opens a task the same way, and the only text that opens nothing is prewalk's own nudge, recognized by its `[prewalk]` prefix.
15
+ Prompts are never rewritten and no message is edited afterwards. Rewriting one message invalidates the prefix for both.
24
16
 
25
- **A prompt inside the task in flight.** The model stays where it is, the prompt runs as written, and no routing call is made. This is the common case, and it is the one that makes the bill linear in the turn count rather than quadratic.
17
+ On SWE-bench this reached 92 to 97 percent of the frontier pass rate for 53 to 61 percent of its cost.
26
18
 
27
- **A question typed while the executor is in play.** The text used to be dropped on the way in, so a mid-task question could never reach the planner. It does now: a steer long enough to be a question moves the task back to the planner, whatever reason pi carries the request under, and the planner stays in play until the next edit hands it to the executor again, and the session says so. No routing call is spent, because the phase answers it. A one-word steer is a redirect rather than a question and stays on the model in play.
28
-
29
- **A task routed to the planner.** The session moves to the planner before the first token. The planner explores, then must commit a structured plan through the `prewalk_plan` tool before it can edit: the first edit is blocked once with a message naming the tool, and a planner that ignores the block degrades to a plain edit-only swap. The first `edit`, `write`, `multiedit` or `notebookedit` after that swaps the session to the executor, and so does a bash command that writes a file outside the temp dir (a redirect, `sed -i`, `tee`, `patch`, `git apply`, or an inline script that writes), which also demands the plan first. The third tool call after the plan still hands over for a planner that writes in a way the check cannot see. An edit under the temp dir is scratch and swaps nothing. The plan tool returns the handoff brief itself: the goal, the facts with file:line, each step with file, anchor, change and verify command, the out-of-scope list, and the rules of engagement. Both roles read the same bytes, so neither cache is rewritten.
30
-
31
- **The cheap tier.** A task plans: the planner opens it, and the executor joins from the first edit on and runs the steps of the plan the planner gave, and nothing else. A prompt too short to be a task, under eight characters, is not a task: it holds whatever is in play rather than opening one. `/prewalk off` puts every task on the cheap model with no plan, and `/prewalk run <task>` does it for one task.
19
+ ## The router
32
20
 
33
- **A task the executor is stuck on.** Three failed tool results in a row are a wall. One miss does not hand the task back, and any success resets the count. The third failure appends a brief naming the step, and the planner takes the task back on the next request until its next edit. The task buys two upgrades, because each swap re-reads the whole prefix at the new model's rate, so a task cannot ping-pong between the models.
21
+ prewalk registers one virtual model, `prewalk/auto`. Pi calls the router before every request, so the session's model is never moved mid-task and every model change in the session file is one prewalk made. Each route returns one request's model, so planner and executor can differ inside a single task.
34
22
 
35
- **The review.** When the executor finishes the plan, or stalls after its nudge, the planner takes the task back once per plan. It reads the edits already in the transcript, runs the final check, and fixes what is wrong. Work the plan did not cover gets a new plan, which is how a long task runs in phases of up to 20 steps. `"review": false` in `prewalk.json` turns it off.
23
+ A task boundary is the gap between one settled run and the next prompt typed after it. A task routes once and the turns inside it are never routed.
36
24
 
37
- That is the one place a stuck cheap model hands the task over by itself: the wall is the evidence. The failing result carries a brief with the step and the failure count, and the planner decides whether to fix it here or commit the steps that are left. The session badge reads `prewalk replan` while it happens.
25
+ | Input | What happens |
26
+ | --- | --- |
27
+ | A prompt during the task in flight | The model stays, the prompt runs as written, no routing call |
28
+ | A question while the executor is in play | A steer long enough to be a question moves the task back to the planner, which stays until its next edit hands it over |
29
+ | A one-word steer | A redirect, so the task stays where it is |
30
+ | A new task | The session moves to the planner before the first token |
31
+ | A prompt under 8 characters | Not a task, so nothing moves |
38
32
 
39
- ## The score that is gone
33
+ Pi's own `reason: "user"` cannot carry that boundary, because it fires for a steer and a follow-up too. prewalk keeps its own flag from the `input` event, which reads `streamingBehavior` as the three cases it is: undefined when the session was idle, `steer` when the text joins the turn in flight, and `followUp` when it waits for that turn to settle and opens a task of its own.
40
34
 
41
- The routing call used to ask three questions over the prompt text and gate the boundary on the answer. `difficulty` asked how much a stronger model would improve the answer, scored across four levels from 0 to 3. `tool` asked whether the fix follows mechanically from what the code already says, and `needsTools` whether the work needs tools and live code, or only the repository's contents.
35
+ ## The plan is a tool call
42
36
 
43
- It did not separate. The difficulty expectation read 0.548 AUC against how long the turn ran, and the three tail readouts read 0.527 to 0.537, so the distribution shape held no more than its mean. Against the label that matters for routing, which model actually ran the turn, it read 0.755 AUC over 20 turns on the frontier model and 255 on the free one, and the four live prompts that mattered came out the way round: a bug analysis at 0.907 and a variable rename at 1.514.
37
+ The planner must call `prewalk_plan` before it can edit, and a guard blocks the first edit once with a message naming the tool. A planner that ignores the block degrades to a plain edit-only swap rather than stalling. The tool's result is the handoff brief, so both roles read the same bytes and neither cache is rewritten.
44
38
 
45
- Two cuts were fitted on it and both came out wrong, one above the range and one with a hold band that put every task on the cheap model. The score is deleted, and so is the call that produced it, because a router that cannot tell a bug from a rename is not a router. The phase already answers the same question: a task plans, and the cheap tier runs the steps of the plan it was given.
39
+ | Field | Meaning |
40
+ | --- | --- |
41
+ | `summary` | One-line goal |
42
+ | `facts` | Findings from exploration the executor cannot re-derive, each with file:line |
43
+ | `steps` | `{ file, change, anchor?, verify? }` in order, up to 20 |
44
+ | `check` | Final verification command |
45
+ | `outOfScope` | Files the executor must not touch |
46
46
 
47
- ## Grading the routes
47
+ The first `edit`, `write`, `multiedit` or `notebookedit` after the plan swaps to the executor. So does a bash command that writes a file outside the temp dir: a redirect, `sed -i`, `tee`, `patch`, `git apply`, or an inline script that writes, and that path demands the plan first too. A third tool call after the plan still hands over, for a planner that writes in a way the check cannot see. An edit under the temp dir is scratch and swaps nothing.
48
48
 
49
- The route is kept in the session's own state entry, so a session grades itself and the check needs no model. `just routes` reads every session under `sessions/`, splits the tasks by the route each one took, and prints what they cost, how many landed an edit, and how many ran the plan's own `check`.
49
+ ## When the executor is stuck
50
50
 
51
- Read it as a survey. The log grows while the run reads it, so the numbers move under you.
51
+ Three failed tool results in a row are a wall. One miss does not hand the task back, any success resets the count, and the third failure appends a brief naming the step. The planner takes the task back on the next request, until its next edit.
52
52
 
53
- A wrong swap costs a whole cache re-read at the new model's input rate, so a prompt too short to be a task keeps the model already in play.
53
+ A task buys two upgrades, because each swap re-reads the whole prefix at the new model's input rate and a task cannot ping-pong between the models. When the executor finishes the plan or stalls after its nudge, the planner returns once per plan: it reads the edits already in the transcript, runs the final check, and fixes what is wrong. Work the plan did not cover gets a new plan, so a long task runs in phases of up to 20 steps. `"review": false` in `prewalk.json` turns that off.
54
54
 
55
- ## Cache and context
55
+ ## The step counter
56
56
 
57
- A prompt cache belongs to one model. The swap is the only thing that has to be paid for, and a task pays it at most once: the executor meets a prefix it has never seen, at the cheap model's input rate.
57
+ After each edit the extension matches the path against the plan steps and advances a pointer, walking forward from the current step so batched edits and missed results catch up instead of freezing the count. The edit result gains a short footer: what was done, what comes next, the anchor, and the verify command.
58
58
 
59
- Prompts are never rewritten. There is no wrapper on your message and no message is edited after the fact, so both models read the transcript you wrote and each keeps its cache warm across its own turns. The single message prewalk writes is the plan tool's result, and it is written once at the swap. The `prewalk_plan` tool stays in the active set for as long as prewalk is armed in plan mode, because a toolset change rewrites the system prompt and the tool list, and the claude provider answers that by opening a new session that replays the whole transcript.
59
+ The badge reads `prewalk route` between tasks, `prewalk plan` or `prewalk run` on the first turn of one, `prewalk exec 3/7` while the plan runs, and `prewalk done 7/7` at the end.
60
60
 
61
- ## Model chains
61
+ ## Chains
62
62
 
63
- Each role is an ordered list, walked until one model resolves against pi's registry and has credentials. Two ordinary things break a single model: a provider with no API key, and a frontier model that runs out of its usage window part way through the day. The chain absorbs both without a config edit.
63
+ prewalk walks each role's list until one model resolves against pi's registry and has credentials. That absorbs the two ordinary breaks: a provider with no key, and a frontier model that runs out of its usage window partway through the day.
64
64
 
65
65
  ```json
66
66
  {
67
67
  "planner": ["opencode-go/mimo-v2.6-pro", "anthropic/claude-opus-4-6"],
68
- "executor": ["opencode-z/space-bunny-free", "z-ai/glm-5.3-flash"]
69
- }
70
- ```
71
-
72
- `/prewalk models` prints both chains and marks each entry `router`, `ready`, or `unavailable` against the registry pi's `/model` reads, with the context window and input price the picker shows, and the mode underneath.
73
-
74
- ## Progress tracking
75
-
76
- After each edit, the extension matches the edited file path against the plan steps and auto-advances a step pointer. The match walks forward from the current step, so batched edits and missed results catch up instead of freezing the count. A short footer is appended to the edit result: what was done, what comes next, the anchor, and the verify command. No model cooperation is required.
77
-
78
- The status badge reads `prewalk route` between tasks, `prewalk plan` or `prewalk run` on the first turn of one, `prewalk exec 3/7` while the plan runs, and `prewalk done 7/7` at the end.
79
-
80
- If the planner commits a plan but the turn ends without an edit, the extension swaps anyway and nudges the executor to start step 1. When the executor settles with steps open, one steer resumes the plan. User input or progress re-arms it, so at most one nudge is spent per stall.
81
-
82
- ## The plan tool
83
-
84
- `prewalk_plan` is in the active set while prewalk is armed in plan mode, and the executor only meets it through tool search. Its description carries the planning brief, which is why nothing is prepended to your prompt. Its schema:
85
-
86
- - `summary`: one-line goal
87
- - `facts`: findings from exploration the executor cannot re-derive, each with file:line
88
- - `steps`: `{ file, change, anchor?, verify? }` in order, max 20
89
- - `check`: final verification command
90
- - `outOfScope`: files the executor must not touch
91
-
92
- ## Commands
93
-
94
- | Command | Effect |
95
- | -------------------------------------- | --------------------------------------------------------- |
96
- | `/prewalk` | status while armed, arm from `prewalk.json` when not |
97
- | `/prewalk off` | disarm |
98
- | `/prewalk status` | both chains, the mode, and where the task is |
99
- | `/prewalk models` | both chains, what resolves, what it costs, and the mode |
100
- | `/prewalk mode off` | nothing happens unless you ask |
101
- | `/prewalk mode plan` | every task plans (the default) |
102
- | `/prewalk planner <model>...` | replace the planner chain, or pick one from a list |
103
- | `/prewalk executor <model>...` | replace the executor chain, or pick one from a list |
104
- | `/prewalk plan [task]` | the next task plans, decided by hand |
105
- | `/prewalk run [task]` | the next task runs on the cheap model, decided by hand |
106
- | `/prewalk <executor> [task]` | set the executor. A task given here starts on the planner |
107
- | `/prewalk <planner> <executor> [task]` | set both roles and, with a task, start it |
108
-
109
- `plan` and `run` spend one routing decision, so they work with nothing else running. Slash commands and skill blocks (`<skill `) are left alone, so skill expansion still works.
110
-
111
- A role named with no model opens the same dialog pi's own model list is built from, `ctx.ui.select`, since pi keeps its selector private and no extension API opens it. Each line carries what a role choice turns on, `provider/id`, the context window, and the input price per million, sorted by price because the executor is the tier you pay for. A chain of several models still takes arguments, because a dialog picks one.
112
-
113
- An armed prewalk owns the session model, because every task routes through the router. A switch away from it is a session where nothing routes at all, for the rest of its life, and one press of the model cycle key used to make it silently: the `12:20` model change in the session that reported the router stuck on `mimo-v2.6-flash` left 130 assistant messages on `space-bunny-free` with no routing at all. prewalk now takes the router back on `model_select` and on every session start and branch switch, and says which model it took. `/prewalk off` is the mode that plans nothing and takes no model, so that is how a physical model is kept.
114
-
115
- Model naming is a bare id (`deepseek-v4-flash`) or provider/id (`google/gemini-3-flash`). Resolution is exact provider/id, then exact bare id, then unique id suffix. A bare id that several providers carry is an error rather than a guess.
116
-
117
- ## Configuration
118
-
119
- `~/.pi/agent/prewalk.json` holds the machine-wide settings. A project's `.pi/prewalk.json` overrides `planner`, `executor` and `mode` field by field. The commands write to the project file when one exists, otherwise to the agent dir. Edit either for anything they do not cover.
120
-
121
- ```json
122
- {
123
- "planner": ["opencode-go/mimo-v2.6-pro"],
124
- "executor": ["opencode-go/mimo-v2.6-flash"],
68
+ "executor": ["opencode-z/space-bunny-free", "z-ai/glm-5.3-flash"],
125
69
  "mode": "plan",
126
70
  "review": true
127
71
  }
128
72
  ```
129
73
 
130
- `mode` is how a task gets its model. `plan` is the default: every task starts on the frontier model and the executor carries the steps of the plan it was given. `off` plans nothing unless you ask, so every task runs on the executor. `/prewalk run [task]` still picks a single task for the cheap model. A file written before the score was removed, with `mode: "auto"`, reads as `plan`.
74
+ `~/.pi/agent/prewalk.json` holds the machine-wide settings, and a project's `.pi/prewalk.json` overrides `planner`, `executor` and `mode` field by field. The commands write to the project file when one exists, otherwise to the agent dir.
75
+
76
+ `/prewalk models` prints both chains, marks each entry `router`, `ready` or `unavailable` against the registry `/model` reads, with the context window and input price, sorted by price. A model named with no argument opens the model dialog, each line carrying `provider/id`, window and input price, sorted by price because the executor is the tier being paid for.
131
77
 
132
- The router must be selected for any of this to run. An armed session takes it back on session start and on a branch switch, and says which model it took. A session that was never armed stays on whatever model you chose.
78
+ An armed prewalk owns the session model, since every task routes through the router, so it takes the router back on `model_select` and on every session start and branch switch and says which model it took. A switch away used to leave a session where nothing routed, silently. `/prewalk off` is how a physical model is kept.
133
79
 
134
- A string is still accepted for either role, so a file written before the chains existed reads the same way. A missing, unparseable, or wrongly shaped file costs its settings and not the session.
80
+ ## Commands
135
81
 
136
- Mode is per project file, and `mode: "off"` still lets `/prewalk plan`, `/prewalk run`, and `/prewalk <planner> <executor> [task]` work.
82
+ | Command | Effect |
83
+ | --- | --- |
84
+ | `/prewalk` | Status while armed, arm from `prewalk.json` when not |
85
+ | `/prewalk off` | Disarm |
86
+ | `/prewalk status` | Both chains, the mode, and where the task is |
87
+ | `/prewalk models` | Both chains, what resolves, what it costs, and the mode |
88
+ | `/prewalk mode off` | Nothing happens unless asked |
89
+ | `/prewalk mode plan` | Every task plans (the default) |
90
+ | `/prewalk planner <model>...` | Replace the planner chain |
91
+ | `/prewalk executor <model>...` | Replace the executor chain |
92
+ | `/prewalk plan [task]` | The next task plans, decided by hand |
93
+ | `/prewalk run [task]` | The next task runs on the cheap model, decided by hand |
94
+ | `/prewalk <executor> [task]` | Set the executor |
95
+ | `/prewalk <planner> <executor> [task]` | Set both roles and, with a task, start it |
96
+
97
+ Model naming is a bare id (`deepseek-v4-flash`) or `provider/id`. Resolution is exact `provider/id`, then exact bare id, then unique id suffix, and a bare id that several providers carry is an error rather than a guess. Slash commands and skill blocks are left alone, so skill expansion still works.
137
98
 
138
99
  ## Install
139
100
 
@@ -142,3 +103,12 @@ pi install npm:@tduyng/pi-prewalk
142
103
  ```
143
104
 
144
105
  Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-prewalk`
106
+
107
+ Then select the router and write the chains above. Nothing routes until `prewalk/auto` is the session model.
108
+
109
+ ## Limits
110
+
111
+ - Plan steps cap at 20, and a fourth phase needs a new plan.
112
+ - A prompt under 8 characters never opens a task.
113
+ - `"mode": "auto"` in an older file reads as `plan`.
114
+ - A missing, unparseable or wrongly shaped `prewalk.json` costs its settings, not the session.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tduyng/pi-prewalk",
3
- "version": "0.0.2",
3
+ "version": "0.0.4",
4
4
  "description": "Plan on the frontier model, execute on the cheap one. The session model swaps the moment the first edit lands.",
5
5
  "keywords": [
6
6
  "pi",