@weave-os/router 0.2.14
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.
- package/LICENSE +90 -0
- package/README.md +172 -0
- package/bin.js +68 -0
- package/cc-statusline.sh +951 -0
- package/codex-skills/disable-routing/SKILL.md +22 -0
- package/codex-skills/fm/SKILL.md +15 -0
- package/codex-skills/fm/scripts/emit.sh +8 -0
- package/codex-skills/force-model/SKILL.md +15 -0
- package/codex-skills/force-model/scripts/emit.sh +9 -0
- package/codex-skills/rf/SKILL.md +15 -0
- package/codex-skills/rf/scripts/emit.sh +7 -0
- package/codex-skills/router-feedback/SKILL.md +15 -0
- package/codex-skills/router-feedback/scripts/emit.sh +9 -0
- package/codex-skills/router-models/SKILL.md +51 -0
- package/codex-skills/router-off/SKILL.md +22 -0
- package/codex-skills/router-on/SKILL.md +22 -0
- package/codex-skills/router-status/SKILL.md +19 -0
- package/codex-skills/ufm/SKILL.md +14 -0
- package/codex-skills/ufm/scripts/emit.sh +3 -0
- package/codex-skills/unforce-model/SKILL.md +14 -0
- package/codex-skills/unforce-model/scripts/emit.sh +4 -0
- package/codex-status.sh +378 -0
- package/commands/beta.md +5 -0
- package/commands/fm.md +6 -0
- package/commands/force-model.md +6 -0
- package/commands/models.md +46 -0
- package/commands/rf.md +6 -0
- package/commands/router-feedback.md +6 -0
- package/commands/router-models.md +46 -0
- package/commands/router-off.md +10 -0
- package/commands/router-on.md +10 -0
- package/commands/router-session.md +15 -0
- package/commands/router-status.md +10 -0
- package/commands/ufm.md +5 -0
- package/commands/unforce-model.md +5 -0
- package/directives.tsv +13 -0
- package/install.sh +5092 -0
- package/opencode-weave/README.md +78 -0
- package/opencode-weave/package.json +18 -0
- package/opencode-weave/src/index.ts +655 -0
- package/package.json +79 -0
- package/pi-router/README.md +123 -0
- package/pi-router/package.json +25 -0
- package/pi-router/skills/install-lsps/SKILL.md +75 -0
- package/pi-router/skills/lsp-guide/SKILL.md +63 -0
- package/pi-router/src/beta.ts +21 -0
- package/pi-router/src/compaction.ts +188 -0
- package/pi-router/src/config.ts +293 -0
- package/pi-router/src/context-window.ts +12 -0
- package/pi-router/src/dispatch.ts +377 -0
- package/pi-router/src/force-model.ts +126 -0
- package/pi-router/src/index.ts +62 -0
- package/pi-router/src/lsp-broker.ts +255 -0
- package/pi-router/src/lsp-client.ts +435 -0
- package/pi-router/src/lsp-format.ts +230 -0
- package/pi-router/src/lsp-install.ts +215 -0
- package/pi-router/src/lsp-protocol.ts +128 -0
- package/pi-router/src/lsp-servers.ts +361 -0
- package/pi-router/src/lsp.ts +529 -0
- package/pi-router/src/metadata.ts +32 -0
- package/pi-router/src/pricing.generated.ts +91 -0
- package/pi-router/src/provider.ts +64 -0
- package/pi-router/src/routed-model.ts +182 -0
- package/pi-router/src/safety.ts +66 -0
- package/pi-router/src/savings.ts +191 -0
- package/pi-router/src/ui.ts +91 -0
- package/pi-router/src/wooly.ts +408 -0
- package/registry.sh +102 -0
- package/uninstall.sh +788 -0
package/package.json
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@weave-os/router",
|
|
3
|
+
"version": "0.2.14",
|
|
4
|
+
"description": "One-command installer that points Claude Code, Codex, opencode, or pi at the Weave Router. For pi it also ships the routing extension, loaded via pi.extensions.",
|
|
5
|
+
"bin": {
|
|
6
|
+
"weave-router": "bin.js",
|
|
7
|
+
"router": "bin.js"
|
|
8
|
+
},
|
|
9
|
+
"pi": {
|
|
10
|
+
"extensions": [
|
|
11
|
+
"./pi-router/src/index.ts"
|
|
12
|
+
],
|
|
13
|
+
"skills": [
|
|
14
|
+
"./pi-router/skills"
|
|
15
|
+
]
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"bin.js",
|
|
19
|
+
"install.sh",
|
|
20
|
+
"uninstall.sh",
|
|
21
|
+
"cc-statusline.sh",
|
|
22
|
+
"codex-status.sh",
|
|
23
|
+
"registry.sh",
|
|
24
|
+
"directives.tsv",
|
|
25
|
+
"commands/",
|
|
26
|
+
"codex-skills/",
|
|
27
|
+
"pi-router/",
|
|
28
|
+
"opencode-weave/",
|
|
29
|
+
"README.md",
|
|
30
|
+
"LICENSE"
|
|
31
|
+
],
|
|
32
|
+
"scripts": {
|
|
33
|
+
"prepack": "node ./scripts/copy-installer.js"
|
|
34
|
+
},
|
|
35
|
+
"engines": {
|
|
36
|
+
"node": ">=18"
|
|
37
|
+
},
|
|
38
|
+
"peerDependencies": {
|
|
39
|
+
"@mariozechner/pi-agent-core": "*",
|
|
40
|
+
"@mariozechner/pi-ai": "*",
|
|
41
|
+
"@mariozechner/pi-coding-agent": "*",
|
|
42
|
+
"@mariozechner/pi-tui": "*",
|
|
43
|
+
"typebox": "*"
|
|
44
|
+
},
|
|
45
|
+
"peerDependenciesMeta": {
|
|
46
|
+
"@mariozechner/pi-agent-core": {
|
|
47
|
+
"optional": true
|
|
48
|
+
},
|
|
49
|
+
"@mariozechner/pi-ai": {
|
|
50
|
+
"optional": true
|
|
51
|
+
},
|
|
52
|
+
"@mariozechner/pi-coding-agent": {
|
|
53
|
+
"optional": true
|
|
54
|
+
},
|
|
55
|
+
"@mariozechner/pi-tui": {
|
|
56
|
+
"optional": true
|
|
57
|
+
},
|
|
58
|
+
"typebox": {
|
|
59
|
+
"optional": true
|
|
60
|
+
}
|
|
61
|
+
},
|
|
62
|
+
"repository": {
|
|
63
|
+
"type": "git",
|
|
64
|
+
"url": "git+https://github.com/weave-os/router.git",
|
|
65
|
+
"directory": "install/npm"
|
|
66
|
+
},
|
|
67
|
+
"homepage": "https://workweave.ai",
|
|
68
|
+
"license": "SEE LICENSE IN LICENSE",
|
|
69
|
+
"keywords": [
|
|
70
|
+
"weave",
|
|
71
|
+
"router",
|
|
72
|
+
"claude",
|
|
73
|
+
"claude-code",
|
|
74
|
+
"anthropic",
|
|
75
|
+
"llm-router",
|
|
76
|
+
"pi",
|
|
77
|
+
"pi-package"
|
|
78
|
+
]
|
|
79
|
+
}
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Weave Router pi extension
|
|
2
|
+
|
|
3
|
+
> Bundled inside the [`@weave-os/router`](https://www.npmjs.com/package/@weave-os/router) package — not published separately. `src/` here is the source of truth; `npm run prepack` copies it into the package.
|
|
4
|
+
|
|
5
|
+
A [pi](https://pi.dev) extension that routes every request through the
|
|
6
|
+
[WorkWeave Router](https://github.com/weave-os/router) — a trained, per-request
|
|
7
|
+
LLM proxy that picks the most cost-efficient model that still solves each task.
|
|
8
|
+
|
|
9
|
+
Installed automatically by the Weave Router installer:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
WEAVE_ROUTER_KEY=rk_… npx --package @weave-os/router -y -- weave-router --pi
|
|
13
|
+
WEAVE_ROUTER_KEY=rk_… npx --package @weave-os/router -y -- weave-router --pi --local # local router
|
|
14
|
+
WEAVE_ROUTER_KEY=rk_… npx --package @weave-os/router -y -- weave-router --pi --lsp go,typescript # + language servers for the lsp tool
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
That writes `~/.pi/agent/models.json` (the `weave` provider), adds
|
|
18
|
+
`npm:@weave-os/router` to `~/.pi/agent/settings.json` `packages`, and stores
|
|
19
|
+
the key in `~/.pi/agent/.weave_router_key`. pi auto-installs `@weave-os/router`
|
|
20
|
+
from npm on next start and loads this extension via its `pi.extensions` field.
|
|
21
|
+
|
|
22
|
+
## What it does
|
|
23
|
+
|
|
24
|
+
- **Loom experience on stock pi.** Replaces pi's startup header through the
|
|
25
|
+
public extension API, adds Wooly's responsive orange terminal animation, and
|
|
26
|
+
keeps pi's own runtime/footer intact. Wooly is visual only: there is no
|
|
27
|
+
dialogue box, narration, coaching request, or separate Loom runtime.
|
|
28
|
+
- **Automatic model selection.** All pi traffic flows through the router, which
|
|
29
|
+
selects the model per request. You don't pick a model — the router does.
|
|
30
|
+
- **Force-model commands.** `/fm <model>` and `/force-model <model>` pin the
|
|
31
|
+
current router session; `/ufm` and `/unforce-model` resume automatic routing.
|
|
32
|
+
The persistent status changes to `WEAVE ROUTER — <model> [forced]` after the
|
|
33
|
+
router validates and canonicalizes the requested model.
|
|
34
|
+
- **Beta routing toggle.** `/beta` toggles the router's beta HMM strategy for
|
|
35
|
+
the current session. The router confirms whether beta routing is enabled or
|
|
36
|
+
disabled; run `/beta` again to switch back.
|
|
37
|
+
- **Per-process routing bias.** Static `x-weave-routing-*` knob headers bias the
|
|
38
|
+
router: quality on the main loop and speed + cheap on subagents.
|
|
39
|
+
- **Long tool-loop compaction.** Pi can cross its context threshold inside an
|
|
40
|
+
uninterrupted tool loop before its normal post-run compaction check. The
|
|
41
|
+
extension preserves a usable output budget for the real continuation,
|
|
42
|
+
compacts once the loop settles, and resumes that extension-owned tool loop.
|
|
43
|
+
Ordinary Pi threshold compaction remains under Pi's control.
|
|
44
|
+
- **Sticky sessions.** `metadata.user_id = "pi:<sessionId>"` pins the main loop
|
|
45
|
+
to one model for the session; subagents get their own pins.
|
|
46
|
+
- **`dispatch` tool — parallel, context-isolated subagents.** pi has none
|
|
47
|
+
natively. `dispatch` spawns child `pi` processes (read-only by default), runs
|
|
48
|
+
them concurrently, and returns only each subagent's final answer — intermediate
|
|
49
|
+
tool output stays in the child, so the main context stays small.
|
|
50
|
+
- **`lsp` tool — code intelligence through a language server.** definition,
|
|
51
|
+
references, hover, documentSymbol, and diagnostics for Go, TypeScript/
|
|
52
|
+
JavaScript, Python, and Rust (gopls, typescript-language-server, pyright,
|
|
53
|
+
rust-analyzer). Servers are spawned lazily per workspace root, shut down
|
|
54
|
+
after idling, and shared with dispatch subagents through a parent-side local
|
|
55
|
+
socket — a fan-out reuses the parent's warm servers instead of cold-starting
|
|
56
|
+
its own. A bundled `lsp-guide` skill (`/skill:lsp-guide`) carries the usage
|
|
57
|
+
recipes (per-operation cookbook, the locate-then-references flow, caveats).
|
|
58
|
+
Disable with `WEAVE_PI_NO_LSP=1`.
|
|
59
|
+
- **Opt-in language-server install — nothing installs silently.** Two ways in:
|
|
60
|
+
pass `--lsp go,typescript` to the installer, or let the assistant offer.
|
|
61
|
+
When the workspace contains a language whose server is missing, the
|
|
62
|
+
assistant offers once in conversation ("I can enable go LSP support if
|
|
63
|
+
you'd like — just say the word!"); a yes runs the install through the
|
|
64
|
+
`lsp_enable` tool (main process only — subagents can't trigger installs), a
|
|
65
|
+
"don't ask again" is persisted per language in `<agentDir>/.weave_lsp.json`
|
|
66
|
+
and respected across sessions. Installs need that language's toolchain
|
|
67
|
+
(`go`, `npm`, or `rustup`) on PATH; when the toolchain itself is missing,
|
|
68
|
+
the bundled `install-lsps` skill (`/skill:install-lsps`) walks the agent
|
|
69
|
+
through installing it — again only with explicit consent.
|
|
70
|
+
- **Persistent route + savings display.** Shows
|
|
71
|
+
`WEAVE ROUTER — <routed> ← <selected> · saved $X.XX` below pi's native footer
|
|
72
|
+
data. Savings compare the selected and routed catalog prices against the same
|
|
73
|
+
input/output/cache usage, accumulate across the reachable session branch,
|
|
74
|
+
and survive resume. Unknown catalog prices are labeled `unpriced` instead of
|
|
75
|
+
silently contributing zero; costlier routing is labeled `extra`, not savings.
|
|
76
|
+
- **No duplicate in-band badge.** Sets `X-Weave-Routing-Marker: off` because the
|
|
77
|
+
persistent status already conveys the actual model.
|
|
78
|
+
- **Safety backstop.** Blocks a few catastrophic shell commands (`rm -rf /`,
|
|
79
|
+
`mkfs`, `dd of=/dev/…`, fork bombs, force-push to main). Disable with
|
|
80
|
+
`WEAVE_NO_SAFETY=1`.
|
|
81
|
+
|
|
82
|
+
## Configuration (environment)
|
|
83
|
+
|
|
84
|
+
| Variable | Default | Purpose |
|
|
85
|
+
|---|---|---|
|
|
86
|
+
| `WEAVE_ROUTER_URL` | `http://localhost:8080` | Router base URL (children inherit it) |
|
|
87
|
+
| `WEAVE_ROUTER_KEY` | — | Router key (else read from `.weave_router_key`) |
|
|
88
|
+
| `WEAVE_ROUTER_KEY_FILE` | `<agentDir>/.weave_router_key` | Override key file path |
|
|
89
|
+
| `WEAVE_USER_EMAIL` / `WEAVE_USER_NAME` | from `git config` | Identity headers for attribution |
|
|
90
|
+
| `WEAVE_PI_SUBAGENT_MODEL` | `claude-sonnet-4-6` | `weave/<model>` handle children launch with (router re-routes) |
|
|
91
|
+
| `WEAVE_PI_DISPATCH_CONCURRENCY` | `4` | Max concurrent subagents |
|
|
92
|
+
| `WEAVE_PI_SUBAGENT_TIMEOUT_MS` | `600000` | Per-subagent timeout |
|
|
93
|
+
| `WEAVE_PI_ALLOW_SUBAGENT_TOOLS` | unset | `1` lets `dispatch` grant subagents write/exec tools (bash, write, edit); default strips them |
|
|
94
|
+
| `WEAVE_ROUTING_ALPHA` / `…_SPEED_WEIGHT` / `…_OUTPUT_COST_RATIO` / `…_EXPECTED_OUTPUT_TOKENS` | role preset | Override individual routing knobs (main process only — children always use their role preset) |
|
|
95
|
+
| `WEAVE_NO_SAFETY` | unset | `1` disables the catastrophic-bash gate |
|
|
96
|
+
| `WEAVE_PI_AUTO_COMPACTION` | unset | `0` disables the routed tool-loop compaction safeguard |
|
|
97
|
+
| `WEAVE_PI_NO_LSP` | unset | `1` disables the `lsp` tool, the server pool, and the subagent broker |
|
|
98
|
+
| `WEAVE_PI_LSP_IDLE_MS` | `300000` | Idle window before an unused language server is shut down |
|
|
99
|
+
| `WEAVE_PI_LSP_REQUEST_TIMEOUT_MS` | `15000` | Per-request budget once a server is warm |
|
|
100
|
+
| `WEAVE_PI_LSP_WARMUP_TIMEOUT_MS` | `60000` | Budget for initialize + the first query (indexing) |
|
|
101
|
+
| `WEAVE_PI_LSP_DIAGNOSTICS_WAIT_MS` | `3000` | How long `diagnostics` waits for a fresh publish |
|
|
102
|
+
| `WEAVE_PI_LSP_MAX_SERVERS` | `4` | LRU cap on concurrently live language servers |
|
|
103
|
+
| `WEAVE_PI_LSP_MAX_REFERENCES` | `100` | Cap on reported reference sites |
|
|
104
|
+
|
|
105
|
+
Internal: `WEAVE_PI_SUBAGENT=1`, `WEAVE_PI_SUBAGENT_ID`, `WEAVE_PI_LSP_BROKER`,
|
|
106
|
+
and `WEAVE_PI_LSP_BROKER_TOKEN` are set by `dispatch` on child processes; don't
|
|
107
|
+
set them yourself.
|
|
108
|
+
|
|
109
|
+
## Billing
|
|
110
|
+
|
|
111
|
+
Routing through the router switches pi from Claude **subscription OAuth** to
|
|
112
|
+
**per-token** billing on the router deployment's key (or your BYOK key). BYOK
|
|
113
|
+
skips cross-provider failover; deployment-key billing is the default.
|
|
114
|
+
|
|
115
|
+
The displayed savings are a client-side estimate from the router's generated
|
|
116
|
+
model-price catalog. Cache writes use 1.25× input price and cache reads use 0.1×
|
|
117
|
+
input price, matching the Claude Code statusline. The ledger stores its catalog
|
|
118
|
+
version with each response so resumed totals remain auditable.
|
|
119
|
+
|
|
120
|
+
## Notes
|
|
121
|
+
|
|
122
|
+
- Actual SDK/router probes keep their small output budget. Only a probe-sized
|
|
123
|
+
request carrying a real tool-result continuation is repaired.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@workweave/router-pi-extension",
|
|
3
|
+
"private": true,
|
|
4
|
+
"type": "module",
|
|
5
|
+
"description": "The pi routing extension bundled into @workweave/router. NOT published separately: src/ is copied into the @workweave/router package at prepack and loaded via that package's pi.extensions. This manifest just marks the sources as ESM and declares the pi peer deps for local typecheck.",
|
|
6
|
+
"scripts": {
|
|
7
|
+
"typecheck": "tsc --project tsconfig.json"
|
|
8
|
+
},
|
|
9
|
+
"peerDependencies": {
|
|
10
|
+
"@mariozechner/pi-agent-core": "*",
|
|
11
|
+
"@mariozechner/pi-ai": "*",
|
|
12
|
+
"@mariozechner/pi-coding-agent": "*",
|
|
13
|
+
"@mariozechner/pi-tui": "*",
|
|
14
|
+
"typebox": "*"
|
|
15
|
+
},
|
|
16
|
+
"devDependencies": {
|
|
17
|
+
"@mariozechner/pi-agent-core": "0.73.1",
|
|
18
|
+
"@mariozechner/pi-ai": "0.73.1",
|
|
19
|
+
"@mariozechner/pi-coding-agent": "0.73.1",
|
|
20
|
+
"@mariozechner/pi-tui": "0.73.1",
|
|
21
|
+
"@types/node": "24.13.3",
|
|
22
|
+
"typebox": "1.3.25",
|
|
23
|
+
"typescript": "5.9.3"
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: install-lsps
|
|
3
|
+
description: Install language servers (gopls, typescript-language-server, pyright, rust-analyzer) and their prerequisite toolchains (Go, Node/npm, rustup) so the lsp tool works. Use when the user asks to enable or install LSP / language-server support, when lsp_enable reports a missing toolchain, or when the lsp tool reports no language server is installed.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Install LSPs
|
|
7
|
+
|
|
8
|
+
Enable the `lsp` tool for a language by installing its language server — and,
|
|
9
|
+
when the server install needs it, the underlying toolchain.
|
|
10
|
+
|
|
11
|
+
## Rules
|
|
12
|
+
|
|
13
|
+
- Everything here is consent-gated: only act on the user's explicit go-ahead,
|
|
14
|
+
and confirm each toolchain install separately — those are system-level
|
|
15
|
+
changes, not part of whatever task prompted this.
|
|
16
|
+
- If the user declines, stop. If they ask not to be offered again, call
|
|
17
|
+
`lsp_enable` with `{"language": "<language>", "action": "dismiss"}`.
|
|
18
|
+
- Prefer the `lsp_enable` tool over bash whenever the toolchain already
|
|
19
|
+
exists; reach for bash only for the prerequisites `lsp_enable` refuses to
|
|
20
|
+
install itself.
|
|
21
|
+
|
|
22
|
+
## Per language
|
|
23
|
+
|
|
24
|
+
Work the ladder for each language the user wants:
|
|
25
|
+
|
|
26
|
+
1. **Check what is missing.** Server binaries: `gopls`,
|
|
27
|
+
`typescript-language-server`, `pyright-langserver` (or
|
|
28
|
+
`basedpyright-langserver`), `rust-analyzer` — also look in `~/go/bin` and
|
|
29
|
+
`~/.cargo/bin`, which the lsp tool searches even when they are off PATH.
|
|
30
|
+
Toolchains: `go`, `npm`, `rustup`.
|
|
31
|
+
2. **Toolchain present** → call `lsp_enable` with
|
|
32
|
+
`{"language": "<go|typescript|python|rust>"}` and you are done; it runs the
|
|
33
|
+
right server install and verifies the binary resolves.
|
|
34
|
+
3. **Toolchain missing** → show the user the command you intend to run, get
|
|
35
|
+
their confirmation, run it in bash, then return to step 2.
|
|
36
|
+
4. **Verify** with a real `lsp` query (`documentSymbol` on an actual source
|
|
37
|
+
file). The first query per workspace can take up to a minute while the
|
|
38
|
+
server indexes; that is normal.
|
|
39
|
+
|
|
40
|
+
## Toolchain installs (step 3 reference)
|
|
41
|
+
|
|
42
|
+
Go (for gopls):
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
brew install go # macOS
|
|
46
|
+
sudo apt-get install -y golang-go # Debian/Ubuntu; or dnf install golang
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Or the official downloads at https://go.dev/dl for anything else.
|
|
50
|
+
|
|
51
|
+
Node/npm (for typescript-language-server and pyright):
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
brew install node # macOS
|
|
55
|
+
sudo apt-get install -y nodejs npm # Debian/Ubuntu
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Or nvm (https://github.com/nvm-sh/nvm) when the user prefers per-user installs.
|
|
59
|
+
|
|
60
|
+
rustup (for rust-analyzer):
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
This is the official rust installer; show the user the command before running
|
|
67
|
+
it and follow its printed PATH instructions afterwards.
|
|
68
|
+
|
|
69
|
+
## Notes
|
|
70
|
+
|
|
71
|
+
- `go install` drops gopls in `~/go/bin` and rustup drops rust-analyzer in
|
|
72
|
+
`~/.cargo/bin`. The lsp tool finds both without PATH changes; other tools
|
|
73
|
+
may still want a PATH entry.
|
|
74
|
+
- All of this can also happen at install time:
|
|
75
|
+
`npx @weave-os/router --pi --lsp go,typescript,python,rust`.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lsp-guide
|
|
3
|
+
description: Recipes for the lsp tool — resolving where a symbol is defined, every place it is used, type signatures and docs, file outlines, and compiler/type errors through a real language server (Go, TypeScript/JavaScript, Python, Rust). Use when navigating or explaining code by symbol, finding callers or usages, checking what broke after an edit, or deciding between lsp and text search.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Using the lsp tool
|
|
7
|
+
|
|
8
|
+
The `lsp` tool answers *semantic* questions through the language's own server:
|
|
9
|
+
it resolves through imports, types, and aliases, where grep only matches text.
|
|
10
|
+
Reach for it whenever the question is about a **symbol**; keep grep for plain
|
|
11
|
+
strings, comments, and file types no server supports.
|
|
12
|
+
|
|
13
|
+
## Operations
|
|
14
|
+
|
|
15
|
+
| Operation | Answers | Needs |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `definition` | where the symbol at a position is defined | `path`, `line`, `column` |
|
|
18
|
+
| `references` | every place the symbol at a position is used | `path`, `line`, `column` |
|
|
19
|
+
| `hover` | type signature + docs for the symbol at a position | `path`, `line`, `column` |
|
|
20
|
+
| `documentSymbol` | the outline (types, functions, methods) of one file | `path` |
|
|
21
|
+
| `diagnostics` | compiler/type errors and warnings for one file | `path` |
|
|
22
|
+
|
|
23
|
+
Positions are 1-based, and `column` must point **at the identifier** (its first
|
|
24
|
+
character works). All paths resolve against the working directory.
|
|
25
|
+
|
|
26
|
+
## Recipes
|
|
27
|
+
|
|
28
|
+
**"Where is X defined?"** — from any usage site of X:
|
|
29
|
+
`{"operation": "definition", "path": "<file>", "line": <L>, "column": <C>}`.
|
|
30
|
+
Don't know a usage site? Find one first (see next recipe's step 1).
|
|
31
|
+
|
|
32
|
+
**"Everywhere X is used"** — two steps, always:
|
|
33
|
+
|
|
34
|
+
1. Locate the declaration: `rg -n --column '\bX\b'` (the `--column` output is
|
|
35
|
+
exactly the coordinate the next call needs), or `documentSymbol` when you
|
|
36
|
+
already know the file.
|
|
37
|
+
2. `{"operation": "references", "path": "<decl file>", "line": <L>, "column": <C>}`.
|
|
38
|
+
|
|
39
|
+
A grep hit list is **not** a references answer: it includes comments and
|
|
40
|
+
strings, misses aliased imports, and can't distinguish same-named symbols.
|
|
41
|
+
Step 2 is what makes the answer authoritative.
|
|
42
|
+
|
|
43
|
+
**"What is this / what's its signature?"** — `hover` at the symbol. Prefer it
|
|
44
|
+
over reading the definition file when you only need the type or doc comment.
|
|
45
|
+
|
|
46
|
+
**"What's in this file?"** — `documentSymbol` before reading a large file; jump
|
|
47
|
+
straight to the line the outline gives you.
|
|
48
|
+
|
|
49
|
+
**"Did my edit break anything here?"** — `diagnostics` on the file after
|
|
50
|
+
editing. It reports the server's current analysis of the saved file.
|
|
51
|
+
|
|
52
|
+
## Behavior worth knowing
|
|
53
|
+
|
|
54
|
+
- **First query per workspace is slow** (the server indexes — up to a minute
|
|
55
|
+
in a big repo). Later queries on that workspace are fast; don't give up
|
|
56
|
+
after one timeout, retry once.
|
|
57
|
+
- **References are capped** (default 100, header says how many exist).
|
|
58
|
+
- **Unsupported file type or missing server** returns advice text, not an
|
|
59
|
+
error — fall back to grep for that file. A missing server can be installed
|
|
60
|
+
with the user's consent via `lsp_enable` (see the install-lsps skill for
|
|
61
|
+
toolchain prerequisites).
|
|
62
|
+
- Works inside dispatch subagents too (they share the parent's warm servers),
|
|
63
|
+
so symbol lookups are safe to fan out.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Forward Pi's local /beta command to the router as one canonical user turn.
|
|
3
|
+
*
|
|
4
|
+
* The router owns the session strategy state and the enabled/disabled reply;
|
|
5
|
+
* the client only validates the command shape and preserves busy-turn ordering.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
|
|
9
|
+
|
|
10
|
+
export function registerBetaCommand(pi: ExtensionAPI): void {
|
|
11
|
+
pi.registerCommand("beta", {
|
|
12
|
+
description: "Toggle beta HMM routing for this Weave Router session",
|
|
13
|
+
handler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
|
|
14
|
+
if (args.trim()) {
|
|
15
|
+
ctx.ui.notify("Usage: /beta", "warning");
|
|
16
|
+
return;
|
|
17
|
+
}
|
|
18
|
+
pi.sendUserMessage("/beta", ctx.isIdle() ? undefined : { deliverAs: "followUp" });
|
|
19
|
+
},
|
|
20
|
+
});
|
|
21
|
+
}
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Compaction safeguards for Pi's routed provider.
|
|
3
|
+
*
|
|
4
|
+
* Pi 0.74 checks automatic compaction only after an entire agent loop. A long
|
|
5
|
+
* tool loop can therefore cross the virtual model's context window between
|
|
6
|
+
* turns. Pi then clamps the next request to max_tokens=1, which looks exactly
|
|
7
|
+
* like an SDK quota probe to the router and produces a one-token response.
|
|
8
|
+
*
|
|
9
|
+
* Preserve real probes, but restore a usable budget for a clamped request that
|
|
10
|
+
* contains an actual tool result. Once the agent finishes, compact using the
|
|
11
|
+
* highest context reading seen during the run; routed providers tokenize and
|
|
12
|
+
* report caches differently, so the final response alone is not authoritative.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import type {
|
|
16
|
+
AgentEndEvent,
|
|
17
|
+
BeforeProviderRequestEvent,
|
|
18
|
+
ExtensionAPI,
|
|
19
|
+
ExtensionContext,
|
|
20
|
+
SessionCompactEvent,
|
|
21
|
+
TurnEndEvent,
|
|
22
|
+
} from "@mariozechner/pi-coding-agent";
|
|
23
|
+
import type { AssistantMessage } from "@mariozechner/pi-ai";
|
|
24
|
+
import { ROUTED_CONTEXT_WINDOW_HEADER } from "./config.js";
|
|
25
|
+
import { parseRoutedContextWindow } from "./context-window.js";
|
|
26
|
+
|
|
27
|
+
const PROBE_MAX_TOKENS = 4;
|
|
28
|
+
const CONTINUATION_MAX_TOKENS = 16_384;
|
|
29
|
+
const COMPACTION_RESERVE_TOKENS = 16_384;
|
|
30
|
+
const STATUS_KEY = "weave-compaction";
|
|
31
|
+
/** Pi does not retry threshold compaction automatically, so resume our tool loop explicitly. */
|
|
32
|
+
export const ROUTED_COMPACTION_CONTINUATION = "Continue from the compacted context. Pick up exactly where you left off.";
|
|
33
|
+
|
|
34
|
+
interface ProviderPayload {
|
|
35
|
+
max_tokens?: unknown;
|
|
36
|
+
messages?: unknown;
|
|
37
|
+
tools?: unknown;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
interface ProviderMessage {
|
|
41
|
+
content?: unknown;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
type Schedule = (callback: () => void) => unknown;
|
|
45
|
+
|
|
46
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
47
|
+
return typeof value === "object" && value !== null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function containsToolResult(messages: unknown): boolean {
|
|
51
|
+
if (!Array.isArray(messages)) return false;
|
|
52
|
+
return messages.some((message: unknown) => {
|
|
53
|
+
if (!isRecord(message)) return false;
|
|
54
|
+
const content = (message as ProviderMessage).content;
|
|
55
|
+
return Array.isArray(content) && content.some((block: unknown) => isRecord(block) && block.type === "tool_result");
|
|
56
|
+
});
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Repair only the Pi context-exhaustion shape. Genuine SDK probes have no tool
|
|
61
|
+
* result transcript and remain at max_tokens=1..4 for the router to hard-pin.
|
|
62
|
+
*/
|
|
63
|
+
export function repairClampedToolContinuation(payload: unknown): boolean {
|
|
64
|
+
if (!isRecord(payload)) return false;
|
|
65
|
+
const body = payload as ProviderPayload;
|
|
66
|
+
if (typeof body.max_tokens !== "number" || body.max_tokens < 1 || body.max_tokens > PROBE_MAX_TOKENS) return false;
|
|
67
|
+
if (!Array.isArray(body.tools) || body.tools.length === 0) return false;
|
|
68
|
+
if (!containsToolResult(body.messages)) return false;
|
|
69
|
+
body.max_tokens = CONTINUATION_MAX_TOKENS;
|
|
70
|
+
return true;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function contextTokens(message: AssistantMessage): number {
|
|
74
|
+
const usage = message.usage;
|
|
75
|
+
if (usage.totalTokens > 0) return usage.totalTokens;
|
|
76
|
+
return usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function latestCompactionId(ctx: ExtensionContext): string | undefined {
|
|
80
|
+
const branch = ctx.sessionManager.getBranch();
|
|
81
|
+
for (let i = branch.length - 1; i >= 0; i--) {
|
|
82
|
+
const entry = branch[i];
|
|
83
|
+
if (entry?.type === "compaction") return entry.id;
|
|
84
|
+
}
|
|
85
|
+
return undefined;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export function registerCompaction(pi: ExtensionAPI, schedule: Schedule = (callback) => setTimeout(callback, 0)): void {
|
|
89
|
+
let highWaterTokens = 0;
|
|
90
|
+
let lastTurnTokens = 0;
|
|
91
|
+
let repairedContinuation = false;
|
|
92
|
+
let compactionScheduled = false;
|
|
93
|
+
// Smallest served context window observed on a response this run. The router
|
|
94
|
+
// can reroute any request regardless of the requested model, so the served
|
|
95
|
+
// window is authoritative for the compaction budget. Tracking the minimum
|
|
96
|
+
// (not the latest or the max) is the conservative choice: if the router ever
|
|
97
|
+
// routed to a smaller window during the run, that window could clamp again,
|
|
98
|
+
// so the budget must respect it. Fall back to the registered model window
|
|
99
|
+
// until the first routed response.
|
|
100
|
+
let servedContextWindow: number | undefined;
|
|
101
|
+
|
|
102
|
+
const resetRun = () => {
|
|
103
|
+
highWaterTokens = 0;
|
|
104
|
+
lastTurnTokens = 0;
|
|
105
|
+
repairedContinuation = false;
|
|
106
|
+
servedContextWindow = undefined;
|
|
107
|
+
};
|
|
108
|
+
|
|
109
|
+
const finishCompaction = (ctx: ExtensionContext) => {
|
|
110
|
+
compactionScheduled = false;
|
|
111
|
+
resetRun();
|
|
112
|
+
if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, undefined);
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
pi.on("session_start", resetRun);
|
|
116
|
+
pi.on("agent_start", resetRun);
|
|
117
|
+
pi.on("session_compact", (_event: SessionCompactEvent, ctx: ExtensionContext) => finishCompaction(ctx));
|
|
118
|
+
|
|
119
|
+
pi.on("before_provider_request", (event: BeforeProviderRequestEvent) => {
|
|
120
|
+
if (repairClampedToolContinuation(event.payload)) repairedContinuation = true;
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
pi.on("after_provider_response", (event, _ctx: ExtensionContext) => {
|
|
124
|
+
if (event.status < 200 || event.status >= 300) return;
|
|
125
|
+
const contextWindow = parseRoutedContextWindow(event.headers?.[ROUTED_CONTEXT_WINDOW_HEADER]);
|
|
126
|
+
if (contextWindow === undefined) return;
|
|
127
|
+
if (servedContextWindow === undefined || contextWindow < servedContextWindow) {
|
|
128
|
+
servedContextWindow = contextWindow;
|
|
129
|
+
}
|
|
130
|
+
});
|
|
131
|
+
|
|
132
|
+
pi.on("turn_end", (event: TurnEndEvent) => {
|
|
133
|
+
if (event.message.role !== "assistant") return;
|
|
134
|
+
lastTurnTokens = contextTokens(event.message as AssistantMessage);
|
|
135
|
+
highWaterTokens = Math.max(highWaterTokens, lastTurnTokens);
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
pi.on("agent_end", (_event: AgentEndEvent, ctx: ExtensionContext) => {
|
|
139
|
+
if (process.env.WEAVE_PI_AUTO_COMPACTION === "0" || compactionScheduled) return;
|
|
140
|
+
const registeredWindow = ctx.model?.contextWindow ?? ctx.getContextUsage()?.contextWindow ?? 0;
|
|
141
|
+
const contextWindow = servedContextWindow ?? registeredWindow;
|
|
142
|
+
if (contextWindow <= COMPACTION_RESERVE_TOKENS) return;
|
|
143
|
+
const servedThreshold = contextWindow - COMPACTION_RESERVE_TOKENS;
|
|
144
|
+
const registeredThreshold = registeredWindow - COMPACTION_RESERVE_TOKENS;
|
|
145
|
+
// Pi's built-in check runs immediately after this event and budgets against
|
|
146
|
+
// the REGISTERED model window. If the final turn clears Pi's registered
|
|
147
|
+
// threshold, Pi will compact asynchronously — deferring is correct, and
|
|
148
|
+
// scheduling our own would race that async compaction. Otherwise Pi will not
|
|
149
|
+
// act, so we compact ourselves when the run crossed the SERVED threshold
|
|
150
|
+
// (which can be smaller than the registered window after a reroute).
|
|
151
|
+
if (lastTurnTokens > registeredThreshold) return;
|
|
152
|
+
if (!repairedContinuation && highWaterTokens <= servedThreshold) return;
|
|
153
|
+
|
|
154
|
+
compactionScheduled = true;
|
|
155
|
+
const previousCompactionId = latestCompactionId(ctx);
|
|
156
|
+
|
|
157
|
+
// Pi is still settling agent_end while extension handlers run. Schedule
|
|
158
|
+
// manual compaction for the next event-loop turn to avoid abort/wait
|
|
159
|
+
// recursion, and let Pi's own auto-compaction win if it already ran.
|
|
160
|
+
schedule(() => {
|
|
161
|
+
if (!compactionScheduled) return;
|
|
162
|
+
const currentCompactionId = latestCompactionId(ctx);
|
|
163
|
+
if (currentCompactionId !== previousCompactionId) {
|
|
164
|
+
finishCompaction(ctx);
|
|
165
|
+
return;
|
|
166
|
+
}
|
|
167
|
+
if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, "compacting routed context...");
|
|
168
|
+
ctx.compact({
|
|
169
|
+
onComplete: () => {
|
|
170
|
+
finishCompaction(ctx);
|
|
171
|
+
// Pi only auto-retries an overflow compaction. This compaction is
|
|
172
|
+
// extension-owned and follows a routed tool loop, so queue the next
|
|
173
|
+
// turn after its summary is committed rather than leaving the agent idle.
|
|
174
|
+
// A user may have started another turn while the compaction ran; in
|
|
175
|
+
// that case Pi requires an explicit follow-up delivery mode.
|
|
176
|
+
pi.sendUserMessage(
|
|
177
|
+
ROUTED_COMPACTION_CONTINUATION,
|
|
178
|
+
ctx.isIdle() ? undefined : { deliverAs: "followUp" },
|
|
179
|
+
);
|
|
180
|
+
},
|
|
181
|
+
onError: (error) => {
|
|
182
|
+
compactionScheduled = false;
|
|
183
|
+
if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, `compaction failed: ${error.message}`);
|
|
184
|
+
},
|
|
185
|
+
});
|
|
186
|
+
});
|
|
187
|
+
});
|
|
188
|
+
}
|