11# LocalPibox Fork Improvements
22
3- > Last updated: 2026-08-26
4- > Status: Qwen3.6 reasoning + vision fully operational
3+ > Last updated: 2026-09-03
4+ > Status: de-forked (2026-08-31) — mainstream pi from npm; Qwen thinking via
5+ > lemonade-pi-plugin with per-model ` maxTokens ` ceilings
56
67---
78
89## Repository Map
910
10- This stack uses 6 repositories under ` github.com/lpb-stack ` . The two forked
11- repos and their upstream origins:
11+ This stack uses 5 repositories under ` github.com/lpb-stack ` . Two are forks
12+ of upstream repos; pi itself is no longer a stack repo (de-forked
13+ 2026-08-31, see the retired-fork note below):
1214
1315| Repo | Type | Upstream | Purpose |
1416| ---| ---| ---| ---|
15- | ** ` lpb-stack/pi ` ** | Fork | ` earendil-works/pi ` | Pi monorepo — Qwen reasoning + overflow detection |
16- | ** ` lpb-stack/lemonade-pi-plugin ` ** | Fork | ` lemonade-sdk/lemonade-pi-plugin ` | Lemonade provider — Qwen model detection, vision |
17+ | ** ` lpb-stack/lemonade-pi-plugin ` ** | Fork | ` lemonade-sdk/lemonade-pi-plugin ` | Lemonade provider — Qwen thinking protocol, vision, model catalog |
1718| ** ` lpb-stack/pi-subagents ` ** | Fork | ` tintinweb/pi-subagents ` | Subagent model registry (local-first) |
1819| ** ` lpb-stack/config ` ** | Original | — | User settings, skills, agents |
1920| ** ` lpb-stack/devstack ` ** | Original | — | Docker dev environment + lpb launcher |
2021| ** ` lpb-stack/lpb-memory ` ** | Original | — | Persistent memory extension |
2122
22- ## The Pi Fork (` lpb-stack/pi ` )
23+ Pi (the coding agent itself) is installed from the npm registry at
24+ ` LPB_PI_VERSION ` (` @earendil-works/pi-coding-agent ` ) — no repo, no fork.
2325
24- ### Upstream Baseline
26+ ## The Pi Fork ( ` lpb-stack/pi ` ) — retired 2026-08-31
2527
26- ** Based on:** ` earendil-works/pi ` v0.84.3 (merged into ` lpb-dev ` branch)
28+ The ` lpb-stack/pi ` fork (based on ` earendil-works/pi ` , last state: tag
29+ ` pre-defork-0.0.71 ` ) is ** retired** . It was based on v0.84.3 with 8 lbp
30+ commits adding Qwen/Lemonade support: the ` reasoning_effort ` →
31+ ` chat_template_kwargs ` mapping, a ` reasoning_budget_tokens ` soft cap, Case 4
32+ reasoning overflow detection, ` allowScripts ` declarations for native addons,
33+ and fork versioning. Upstream pi has since picked up ` reasoning_effort `
34+ natively, which made the fork unnecessary.
2735
28- The original upstream repo is a ** TypeScript monorepo** with 11 packages:
29-
30- | Package | Description |
36+ | Fork change | Where it lives now |
3137| ---| ---|
32- | ` @earendil-works/pi-ai ` | Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.) |
33- | ` @earendil-works/pi-agent-core ` | Agent runtime with tool calling and state management |
34- | ` @earendil-works/pi-coding-agent ` | Interactive coding agent CLI |
35- | ` @earendil-works/pi-tui ` | Terminal UI library with differential rendering |
36- | ` @earendil-works/pi-client ` | Client library |
37- | ` @earendil-works/pi-protocol ` | Protocol definitions |
38- | ` @earendil-works/pi-server ` | Server component |
39- | ` @earendil-works/pi-session-backends ` | Session storage backends |
40- | ` @earendil-works/pi-telemetry ` | Vendor-neutral telemetry contracts |
41- | ` @earendil-works/pi-evals ` | Evaluation harness |
42-
43- For chat/workflows, see the companion project: [ earendil-works/pi-chat] ( https://github.com/earendil-works/pi-chat ) .
44-
45- ### Fork Patches (original set, introduced on v0.84.1/v0.84.2)
46-
47- The fork adds ** 6 lbp-specific commits** on top of the upstream merge:
48-
49- | Commit | What changed | Purpose |
50- | ---| ---| ---|
51- | ` 53c1dc2 ` | ** Critical** : Qwen/Lemonade-compatible patches on v0.84.1 | See details below |
52- | ` 3340960 ` | ` docs(lbp) ` : document what v0.84.1 provides vs lbp additions | Docs |
53- | ` 2a3e9bc ` | ` feat(coding-agent) ` : declare ` allowScripts ` for native addons | Allow native addons |
54- | ` 346947d ` | ` hooks ` : sync to latest (validation-only, skip when not in devstack) | Hook management |
55- | ` 8449290 ` | ` chore ` : install husky pre-commit hook, remove stale githooks wrapper | Dev tooling |
56- | ` 3fc4978 ` | ` Merge tag 'v0.84.2' into lbp-dev ` | Upstream merge |
57-
58- Since the v0.84.3 merge (` 13c6d72 ` ): ** 2 additional commits** —
59- ` 3c307d0 ` (fix: cloudflare gateway type, include workers) and
60- ` 6db652e ` (style: numeric literal normalization in overflow.ts, biome).
38+ | ` reasoning_effort ` support for Qwen | Mainstream pi ≥0.84.4 sends it natively; the plugin handles the ` enable_thinking ` protocol |
39+ | ` reasoning_budget_tokens ` soft cap | Replaced by per-model ` maxTokens ` ceilings in the plugin's model-params catalog |
40+ | Case 4 overflow detection | Replaced by raised ` reserveTokens ` (early compaction) + per-model ceilings |
41+ | ` allowScripts ` for native addons | Re-implemented by devstack: ` npm config set allow-scripts … ` (start.sh) + ` .npmrc ` (Dockerfile) |
42+ | ` LOCALPIB_VERSION ` env read | Replaced by the ` LPB_VERSION ` banner baked by the Dockerfile |
43+ | Last patch (Case 4 overflow) | Kept as ` patches/pi-case4-overflow.patch ` for reference |
6144
62- The ** critical commit** (` 53c1dc2 ` ) adds these surgical changes:
63-
64- | File | Change | Purpose |
65- | ---| ---| ---|
66- | ` packages/ai/src/api/openai-completions.ts ` | Maps ` reasoning_effort ` to ` chat_template_kwargs ` | Sends ` reasoning_effort: "high"\|"medium"\|"low" ` to Qwen models |
67- | ` packages/ai/src/api/openai-completions.ts ` | Adds ` reasoning_budget_tokens ` param | Sends soft-cap (0) to prevent runaway thinking blocks |
68- | ` packages/ai/src/types.ts ` | Adds ` reasoningBudgetTokens ` compat field | New compat flag for Qwen reasoning budget |
69- | ` packages/ai/src/utils/overflow.ts ` | Adds ** Case 4** reasoning overflow detection | Detects when thinking blocks consume output token budget |
70- | ` packages/coding-agent/src/config.ts ` | Adds ` LOCALPIB_VERSION ` env | Reads ` LPB_VERSION ` for fork identification |
71- | ` VERSION ` | New file: ` 0.0.1-lbp ` | Fork version marker |
72- | ` package.json ` | Version → ` 0.0.1-lbp ` | Fork version |
73-
74- ### Branch Strategy
75-
76- | Branch | Source | Content |
77- | ---| ---| ---|
78- | ` lpb-dev ` (default) | Upstream + patches | Active development, contains lbp patches |
79- | ` lpb ` (stable) | Derived from ` lpb-dev ` | Stable branch, receives clean merges |
80-
81- To update:
82- ``` bash
83- git fetch https://github.com/earendil-works/pi.git
84- git checkout lbp-dev
85- git rebase < upstream-tag> # e.g. v0.84.2
86- # apply lbp patches
87- git push --force-with-lease origin lbp-dev
88- ```
45+ Re-introducing a forked pi is only needed for changes upstream hasn't
46+ picked up — see ` doc/forking.md ` for the procedure. A local ` workspace/pi `
47+ reference clone may remain at the retired tag.
8948
9049---
9150
@@ -101,7 +60,7 @@ to support Qwen reasoning models on the Lemonade local provider.
10160| ** Qwen detection** | ` isQwenReasoningModel() ` — detects Qwen3.x, QwQ, Qwen2.5-thinking via regex |
10261| ** MTP detection** | ` isMtpModel() ` — detects Multi-Token Prediction models |
10362| ** FLM detection** | ` flmTemplateRejectsDeveloperRole() ` — disables reasoning for FLM backends |
104- | ** Dynamic maxTokens** | Reasoning: ` 0.06 × contextWindow ` . Non-reasoning: ` 0.125 ` — prevents context overflow |
63+ | ** Dynamic maxTokens** | Per-model ` maxTokens ` in the model-params catalog — prevents context overflow (see Configuration below) |
10564| ** Thinking protocol** | Adds ` enable_thinking ` , ` reasoning_budget_tokens ` , ` thinkingFormat: "qwen-chat-template" ` |
10665| ** Heuristic detection** | ` isReasoningByHeuristic() ` — catches models without ` recipe ` field |
10766
@@ -190,16 +149,20 @@ The delta is always visible as the diff between upstream and `lpb-dev`.
190149
191150## Known Issues & Mitigations
192151
193- ### Qwen3 Thinking Overflow (2026-08-02)
152+ ### Qwen Thinking Overflow (2026-08-02)
194153
195- Qwen3.6 with thinking enabled throws "context size exceeded" when
196- ` prompt + max_tokens ` exceeds the 262k window.
154+ Qwen with thinking enabled throws "context size exceeded" when
155+ ` prompt + max_tokens ` exceeds the window.
197156
198- ** Mitigations:**
199- - ` maxTokens ` reduced to ~ 15k (` ratio 0.06 ` ) — leaves room for 10-20k thinking blocks
200- - ` reserveTokens ` doubled to 32k — compaction fires at ~ 88% (230k) instead of ~ 94% (246k)
157+ ** Mitigations (current):**
158+ - Per-model ` maxTokens ` ceilings in the lemonade-pi-plugin model-params
159+ catalog (16384 for Qwen thinking models — exact values, no formula)
160+ - ` reserveTokens ` raised — compaction fires before the window overflows
201161- Thinking disabled during compaction — prevents meta-thinking waste
202- - ` LPB_MAX_TOKENS_CONTEXT_RATIO=0.06 ` set in ` start.sh ` and ` .env.example `
162+
163+ The original ratio-based mitigation (` LPB_MAX_TOKENS_CONTEXT_RATIO=0.06 `
164+ in ` start.sh ` / ` .env.example ` ) was retired 2026-09-02 — see Configuration
165+ above.
203166
204167### agent-browser-chat
205168
@@ -215,8 +178,7 @@ per-call. Cannot point at local Lemonade server. Not usable with this stack.
215178| Variable | Value | Purpose |
216179| ---| ---| ---|
217180| ` LEMONADE_BASE_URL ` | ` http://127.0.0.1:13305/v1 ` | Model API endpoint |
218- | ` VISION_MODEL ` | ` Qwen3.6-35B-A3B-MTP-GGUF ` | Vision model ID |
219- | ` LPB_MAX_TOKENS_CONTEXT_RATIO ` | ` 0.06 ` | Max tokens ratio for Qwen reasoning |
181+ | ` VISION_MODEL ` | * (configured)* | Vision model ID — see ` lpb-config show ` |
220182| ` AGENT_BROWSER_MAX_OUTPUT ` | ` 4000 ` | Max chars for snapshot output |
221183
222184### Admin Commands
0 commit comments