token-pilot 0.24.0 → 0.24.1
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/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +15 -0
- package/dist/agents/tp-api-surface-tracker.md +1 -1
- package/dist/agents/tp-audit-scanner.md +1 -1
- package/dist/agents/tp-commit-writer.md +1 -1
- package/dist/agents/tp-dead-code-finder.md +1 -1
- package/dist/agents/tp-debugger.md +1 -1
- package/dist/agents/tp-dep-health.md +1 -1
- package/dist/agents/tp-history-explorer.md +1 -1
- package/dist/agents/tp-impact-analyzer.md +1 -1
- package/dist/agents/tp-incident-timeline.md +1 -1
- package/dist/agents/tp-migration-scout.md +1 -1
- package/dist/agents/tp-onboard.md +1 -1
- package/dist/agents/tp-pr-reviewer.md +1 -1
- package/dist/agents/tp-refactor-planner.md +1 -1
- package/dist/agents/tp-review-impact.md +1 -1
- package/dist/agents/tp-run.md +1 -1
- package/dist/agents/tp-session-restorer.md +1 -1
- package/dist/agents/tp-test-coverage-gapper.md +1 -1
- package/dist/agents/tp-test-triage.md +1 -1
- package/dist/agents/tp-test-writer.md +1 -1
- package/dist/handlers/read-symbols.js +26 -13
- package/docs/token-pilot-dir.md +61 -0
- package/package.json +2 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "token-pilot",
|
|
3
|
-
"version": "0.24.
|
|
3
|
+
"version": "0.24.1",
|
|
4
4
|
"description": "Enforcement layer for token-efficient AI coding: MCP-first hook with structural denial summaries, SessionStart reminder, bless-agents CLI, and six tp-* subagents — works for every agent including those without MCP access.",
|
|
5
5
|
"author": "token-pilot",
|
|
6
6
|
"license": "MIT",
|
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,21 @@ All notable changes to Token Pilot will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.24.1] - 2026-04-18
|
|
9
|
+
|
|
10
|
+
### Fixed — two findings from v0.23.6 field verification
|
|
11
|
+
|
|
12
|
+
**1. `read_symbols` guard missed on real Vue / TS files.** The field report showed a 6-symbols-from-6-exports request where the v0.23.6 guard failed to trip. Root cause: the guard used `sum(lineCount) / fileLines ≥ 0.7`, but ast-index's parser returns **overlapping ranges** on arrow functions / `export function` / Vue SFCs / TypeScript type-vs-function — so `sum(lineCount)` gets inflated past the file size and ratios become meaningless. Switched to a **count-based** guard: if ≥ 3 symbols AND ≥ 70% of the file's top-level symbol count, refuse and advise `smart_read`. Immune to parser line-range bugs.
|
|
13
|
+
|
|
14
|
+
**2. `docs/token-pilot-dir.md` was not shipped in the npm package.** I added the file in v0.23.6 but forgot the `docs/*.md` glob in `package.json` `files:`. Now included.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **Parser-overlap warning.** If the handler sees `sum(symbol.lineCount) > file.lineCount × 1.5` (definite parser mis-parse — symbols claiming more lines than the file has), it logs one stderr warning pointing at the upstream `defendend/Claude-ast-index-search` issue tracker. Doesn't fail the request; gives users a signal when ast-index is the real culprit for weird results.
|
|
19
|
+
|
|
20
|
+
### Numbers
|
|
21
|
+
- 911 tests green (+1 regression test for overlapping-ranges guard), `tsc --noEmit` clean.
|
|
22
|
+
|
|
8
23
|
## [0.24.0] - 2026-04-18
|
|
9
24
|
|
|
10
25
|
### Added — Tier 3 combo-agents (TP-z64 delivered)
|
|
@@ -10,7 +10,7 @@ tools:
|
|
|
10
10
|
- mcp__token-pilot__smart_read
|
|
11
11
|
- mcp__token-pilot__smart_read_many
|
|
12
12
|
- mcp__token-pilot__read_section
|
|
13
|
-
token_pilot_version: "0.24.
|
|
13
|
+
token_pilot_version: "0.24.1"
|
|
14
14
|
token_pilot_body_hash: ae0b86eaffaf34bf283b94b5572481fa8c2d6a2a25193f1173b70bef0fbe1919
|
|
15
15
|
---
|
|
16
16
|
|
|
@@ -7,7 +7,7 @@ tools:
|
|
|
7
7
|
- mcp__token-pilot__read_diff
|
|
8
8
|
- mcp__token-pilot__outline
|
|
9
9
|
- mcp__token-pilot__read_symbol
|
|
10
|
-
token_pilot_version: "0.24.
|
|
10
|
+
token_pilot_version: "0.24.1"
|
|
11
11
|
token_pilot_body_hash: a058518619fd6e2def0c9226f6c70438a5e0a80efe680c935414ecd7e1b14a4f
|
|
12
12
|
---
|
|
13
13
|
|
package/dist/agents/tp-run.md
CHANGED
|
@@ -7,7 +7,7 @@ tools:
|
|
|
7
7
|
- mcp__token-pilot__read_range
|
|
8
8
|
- mcp__token-pilot__find_usages
|
|
9
9
|
- mcp__token-pilot__read_symbol
|
|
10
|
-
token_pilot_version: "0.24.
|
|
10
|
+
token_pilot_version: "0.24.1"
|
|
11
11
|
token_pilot_body_hash: 255912c47661d203c8f9a735237bc419f97e937f788a01811bbe126ee3dd5878
|
|
12
12
|
---
|
|
13
13
|
|
|
@@ -21,22 +21,22 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
|
|
|
21
21
|
}
|
|
22
22
|
const N = args.symbols.length;
|
|
23
23
|
const sections = [];
|
|
24
|
-
// v0.
|
|
25
|
-
//
|
|
26
|
-
//
|
|
27
|
-
//
|
|
28
|
-
|
|
24
|
+
// v0.24.1 — anti-pattern guard. When the caller requests most of the
|
|
25
|
+
// symbols in the file, a batch read costs more than one smart_read.
|
|
26
|
+
// Earlier versions used sum(lineCount), but ast-index parser bugs
|
|
27
|
+
// (arrow functions / export function / Vue SFC / TS types) return
|
|
28
|
+
// overlapping ranges that inflate the sum and let the guard miss. The
|
|
29
|
+
// count-based check (requested symbols / total top-level symbols) is
|
|
30
|
+
// immune to those parser issues.
|
|
31
|
+
if (structure && structure.symbols && structure.symbols.length >= 3) {
|
|
29
32
|
const uniqueRequested = new Set(args.symbols.map((s) => s.split(".")[0]));
|
|
30
33
|
const matchedTopLevel = structure.symbols.filter((s) => uniqueRequested.has(s.name));
|
|
31
|
-
const
|
|
32
|
-
|
|
33
|
-
if (totalTopLevelLines > 0 &&
|
|
34
|
-
requestedLines / totalTopLevelLines >= 0.7 &&
|
|
35
|
-
matchedTopLevel.length >= 3) {
|
|
34
|
+
const total = structure.symbols.length;
|
|
35
|
+
if (matchedTopLevel.length >= 3 && matchedTopLevel.length / total >= 0.7) {
|
|
36
36
|
const text = `FILE: ${args.path} | SYMBOLS: ${N} requested\n\n` +
|
|
37
|
-
`ADVISORY: You requested ${matchedTopLevel.length} symbols
|
|
38
|
-
|
|
39
|
-
`
|
|
37
|
+
`ADVISORY: You requested ${matchedTopLevel.length}/${total} symbols ` +
|
|
38
|
+
`(≥70% of the file's top-level symbols). A batch read here costs ` +
|
|
39
|
+
`more than reading the whole file once.\n\n` +
|
|
40
40
|
`Cheaper alternatives:\n` +
|
|
41
41
|
` - smart_read("${args.path}") for a structural overview\n` +
|
|
42
42
|
` - read_for_edit("${args.path}", "<symbol>") when you need exact edit context\n` +
|
|
@@ -45,6 +45,19 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
|
|
|
45
45
|
`or use raw Read (bounded).`;
|
|
46
46
|
return { content: [{ type: "text", text }] };
|
|
47
47
|
}
|
|
48
|
+
// v0.24.1 — sanity-check for parser-produced overlapping ranges. When
|
|
49
|
+
// the sum of symbol lineCounts exceeds the actual file line count by
|
|
50
|
+
// >1.5× we're almost certainly seeing ast-index getting confused by
|
|
51
|
+
// arrow functions / Vue SFCs / type-vs-function. Log once so users
|
|
52
|
+
// can report upstream; don't fail the request.
|
|
53
|
+
const totalSymbolLines = structure.symbols.reduce((sum, s) => sum + (s.location.lineCount ?? 0), 0);
|
|
54
|
+
const fileLines = lines.length;
|
|
55
|
+
if (fileLines > 0 && totalSymbolLines > fileLines * 1.5) {
|
|
56
|
+
process.stderr.write(`[token-pilot] ast-index parser produced overlapping symbol ranges for ${args.path} ` +
|
|
57
|
+
`(sum=${totalSymbolLines} lines vs file=${fileLines}). ` +
|
|
58
|
+
`Results may mis-classify symbols; consider smart_read + read_for_edit instead. ` +
|
|
59
|
+
`Upstream issue: https://github.com/defendend/Claude-ast-index-search/issues\n`);
|
|
60
|
+
}
|
|
48
61
|
}
|
|
49
62
|
// Show mode constants (same as read_symbol.ts)
|
|
50
63
|
const MAX_SYMBOL_LINES = 300;
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# `.token-pilot/` directory layout
|
|
2
|
+
|
|
3
|
+
Token Pilot writes state and telemetry to a `.token-pilot/` directory in your project root. Nothing is created eagerly — each sub-path appears only when a feature that needs it fires for the first time. Committing the directory is optional; most users add it to `.gitignore`.
|
|
4
|
+
|
|
5
|
+
## Files & directories
|
|
6
|
+
|
|
7
|
+
| Path | Who writes | When it appears | Purpose | Commit? |
|
|
8
|
+
|---|---|---|---|---|
|
|
9
|
+
| `hook-events.jsonl` | Read hook | First `Read` of a code file ≥ the `denyThreshold` | JSONL telemetry — one entry per hook decision (denied / allowed / bypass). Read by `session_analytics` and the adaptive-threshold logic. Auto-rotates at 10 MB, keeps 30-day history with 100 MB total cap. | **No** |
|
|
10
|
+
| `hook-denied.jsonl` | Read hook (legacy) | Historical, from before v0.20 | Older-format event log kept for backward compatibility with pre-v0.20 `loadDeniedReads()` readers. Safe to delete. | No |
|
|
11
|
+
| `snapshots/` | `session_snapshot` MCP tool | First call to `session_snapshot` | Archived + `latest.md` copy of each snapshot. Retention: last 10 archives. Surfaced by the SessionStart hook when `latest.md` is < 2h old. | Optional — commit `latest.md` if you want a next-session pointer to persist across clones |
|
|
12
|
+
| `context-registries/<session-id>.json` | MCP server | First dedup-aware tool call (`smart_read`, `read_symbol`, `read_range`, `smart_read_many`) with a `session_id` arg | Per-session dedup state — what was loaded, content hashes, load times. LRU cap 8 sessions in memory; older ones live only on disk. | **No** — session-local |
|
|
13
|
+
| `docs/<name>.md` | `token-pilot save-doc` CLI | Explicit user invocation | User-saved research / notes (curl output, WebFetch, long paste) that should survive compaction. Read back cheaply with `smart_read` / `read_range`. | Optional — commit if the doc is team-wide knowledge |
|
|
14
|
+
| `over-budget.log` | PostToolUse:Task hook | First time a `tp-*` subagent exceeds its frontmatter budget by > 10 % | JSONL audit trail for budget overages. Used by future `session_analytics` views. Empty file means no overages so far — good. | **No** |
|
|
15
|
+
| `tp-refactor-planner-<timestamp>.md` | `tp-refactor-planner` agent | Only when the agent's plan exceeds its response budget | Full step list spilled from the agent's response when it would have exceeded ~500 tokens inline. Response in chat points at this file. | Usually **no** — review and delete after the refactor lands |
|
|
16
|
+
|
|
17
|
+
## Quick rules
|
|
18
|
+
|
|
19
|
+
- **Nothing appears until you use it.** If you only ever ran the Read hook, only `hook-events.jsonl` will exist.
|
|
20
|
+
- **Safe to delete the whole folder** — everything rebuilds from the next tool call. You'll lose: dedup memory, snapshot history, saved research. You'll keep: installed hooks, agents, configs (those live elsewhere).
|
|
21
|
+
- **Add to `.gitignore`** unless your team uses snapshots or saved-docs as shared context.
|
|
22
|
+
|
|
23
|
+
Recommended `.gitignore` stanza:
|
|
24
|
+
|
|
25
|
+
```gitignore
|
|
26
|
+
# Token Pilot — session-local telemetry & state
|
|
27
|
+
.token-pilot/hook-events*.jsonl
|
|
28
|
+
.token-pilot/hook-denied.jsonl
|
|
29
|
+
.token-pilot/context-registries/
|
|
30
|
+
.token-pilot/over-budget.log
|
|
31
|
+
.token-pilot/tp-refactor-planner-*.md
|
|
32
|
+
|
|
33
|
+
# Keep these if you want shared snapshots / notes:
|
|
34
|
+
# !.token-pilot/snapshots/latest.md
|
|
35
|
+
# !.token-pilot/docs/
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Inspecting live state
|
|
39
|
+
|
|
40
|
+
Useful one-liners to audit a session in progress:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# How many hook events this session
|
|
44
|
+
wc -l .token-pilot/hook-events.jsonl
|
|
45
|
+
|
|
46
|
+
# Token savings so far (sum of savedTokens)
|
|
47
|
+
cat .token-pilot/hook-events.jsonl | python3 -c "
|
|
48
|
+
import sys, json
|
|
49
|
+
print(sum(json.loads(l).get('savedTokens', 0) for l in sys.stdin if l.strip()))"
|
|
50
|
+
|
|
51
|
+
# Any subagent blew its budget?
|
|
52
|
+
cat .token-pilot/over-budget.log 2>/dev/null || echo "no overages"
|
|
53
|
+
|
|
54
|
+
# Latest session snapshot (if any)
|
|
55
|
+
cat .token-pilot/snapshots/latest.md 2>/dev/null | head -20
|
|
56
|
+
|
|
57
|
+
# What dedup state is persisted
|
|
58
|
+
ls .token-pilot/context-registries/ 2>/dev/null
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Or ask the agent — `mcp__token-pilot__session_analytics` returns the same signals in a structured form.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "token-pilot",
|
|
3
|
-
"version": "0.24.
|
|
3
|
+
"version": "0.24.1",
|
|
4
4
|
"description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
"dist/**/*.js",
|
|
12
12
|
"dist/**/*.d.ts",
|
|
13
13
|
"dist/agents/*.md",
|
|
14
|
+
"docs/*.md",
|
|
14
15
|
"scripts/postinstall.mjs",
|
|
15
16
|
"start.sh",
|
|
16
17
|
".claude-plugin/",
|