pi-braid 0.43.44 → 0.43.46

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/CHANGELOG.md CHANGED
@@ -80,6 +80,32 @@ record; the tag scheme above applies unchanged.
80
80
  contract; a new fixture covers both trees, the scoping and the absent-versus-empty
81
81
  populations.
82
82
 
83
+ ## Contrib — the pi-braid-contrib bundle gains a `git` tool (2026-11-11)
84
+
85
+ A census of 4,387 session files counted 27,200 `git` calls through the shell, 9,551 of them a single
86
+ read-only subcommand: the largest class that needs no shell semantics at all. The new `git` tool takes
87
+ an argv array, never a command string, and refuses an argument carrying a shell metacharacter before
88
+ anything spawns. Read-only subcommands run freely; anything else needs `write: true`, which is gated
89
+ rather than trusted — the call refuses on a dirty tree and names the dirty paths, because that is the
90
+ state where an agent's tidy-up becomes someone's lost work. A data table refuses the destructive
91
+ shapes (`push --force`, `reset --hard`, `clean -fdx`, `filter-branch`, `reflog expire`,
92
+ `gc --prune=now`, `branch -D` of an unmerged branch) with its own message each. Output is bounded and
93
+ reports its truncation in bytes and lines; a non-zero exit is a result, not an exception.
94
+
95
+ Adding a thirteenth extension moves the counts six source claims pin to the manifest, and the
96
+ schema's recorded line for the `braid.contrib.*` reader; `check:doc-drift` and `check:schema` demanded
97
+ both repairs in the same commit.
98
+
99
+ ## Core — 0.43.45 (2026-11-11: a re-read is a covered range, not a repeated path)
100
+
101
+ The re-read whisper keyed `recentlyReadFiles` on the path, so a second slice of one document in a turn
102
+ was reported as already in context: over the session corpus, 238 of the checkable flags were different
103
+ ranges of the same file and 6 were the same range again. The record is now a bounded set of line
104
+ windows per path, and a read is waste only when the range it asks for is fully covered by what is
105
+ already in context since the last edit, write or command. A slice past the read tool's default window
106
+ is not covered by a read that returned only the first 2000 lines, and the per-path bound drops the
107
+ oldest window, which can hide a repeat but can never invent one.
108
+
83
109
  ## Core — 0.43.44 (2026-11-10: the version that carries the telegram release)
84
110
 
85
111
  No core change. The `pi-braid-telegram` bump to 0.1.9 rides on a core version so the release line
package/TOOLS.md CHANGED
@@ -29,7 +29,7 @@ fails until the other catches up.
29
29
  | Braid-registered tools | 24 | Registered via `pi.registerTool()` in `src/extensions/` - owned by this package |
30
30
  | pi-native core tools | 9 | `read`/`bash`/`edit`/`write`/`grep`/`find`/`ls`/`powershell` - pi builtins surfaced through the package with stable one-liners (`TOOL_GUIDELINES`, `prompt-builder/tool-guidelines.ts`); `tool_search` is pi's built-in tool-search extension, activated by braid at session start |
31
31
  | **Documented catalog** | **33** | the rows between the markers below |
32
- | In-repo sibling `pi-braid-contrib` | 12 extensions | browser, codebase, diff, healthcheck, observatory, repl, sleep, system-monitor - **not owned by this package**, see appendix |
32
+ | In-repo sibling `pi-braid-contrib` | 13 extensions | browser, codebase, diff, healthcheck, observatory, repl, sleep, system-monitor - **not owned by this package**, see appendix |
33
33
  | Third-party npm packages | web_search/fetch_content/source_check/get_search_content (pi-web-access); herdr\*\* (@ogulcancelik/pi-herdr) | **not owned by this package**, see appendix |
34
34
 
35
35
  ## Enablement reference
@@ -126,7 +126,7 @@ fall back to the first sentence of their description.
126
126
  ### pi-braid-contrib (in-repo workspace)
127
127
 
128
128
  `pi-braid-contrib` is the sibling `packages/contrib` workspace of this monorepo.
129
- Its 12 extensions are all enabled by default with a per-extension toggle via
129
+ Its 13 extensions are all enabled by default with a per-extension toggle via
130
130
  `braid.contrib.<name>` in
131
131
  `~/.pi/agent/settings.json` (e.g. `"browser": false` drops the whole browser family).
132
132
  Tool families it registers:
@@ -134,6 +134,7 @@ Tool families it registers:
134
134
  - **browser** - `browser_navigate`, `browser_snapshot`, `browser_eval`, `browser_screenshot` (plus `browser_content`, `browser_cookies`, `browser_tabs_*` in the full family). Drive a real browser tab for JS-heavy pages.
135
135
  - **codebase** - analyze a codebase's structure or module dependency graph (tree/graph/impact).
136
136
  - **diff** - `file_diff`: compare two files or git revisions (unified hunks and stats).
137
+ - **git** - `git`: one git subcommand from an argv array, read-only by default; `write: true` needs a clean tree and a fixed refusal list for the destructive shapes.
137
138
  - **healthcheck** - comprehensive health checks on tools, extensions, and system resources.
138
139
  - **observatory** - inspect the current pi session (status, registered tools, recorded events).
139
140
  - **repl** - execute JavaScript code with context (RLM mode for chunk/search/map/reduce).
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.44",
4
- "sha": "ced405d5d39735e56ba7b2079c95b75371153e99",
5
- "shaShort": "ced405d5",
3
+ "version": "0.43.46",
4
+ "sha": "a57f85f08833b98c46ae3b5b171cc0eec520bd25",
5
+ "shaShort": "a57f85f0",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-11-10T18:51:20.198Z"
8
+ "packedAt": "2026-11-11T08:48:25.856Z"
9
9
  }
@@ -1,6 +1,7 @@
1
1
  import type { EnforcementState } from "../state.js";
2
2
  /**
3
- * Record file paths from read/edit operations for re-read detection.
3
+ * Record the window each read asks for, so turn validation can name only the
4
+ * reads whose lines are already in context.
4
5
  * Called from tool_call event handler which has access to event.input.
5
6
  */
6
7
  export declare function recordToolInput(toolName: string, input: Record<string, unknown> | undefined, s: EnforcementState): void;
@@ -5,7 +5,99 @@ import { recordCodeChange } from "../detection/verification.js";
5
5
  import { PROGRESS_TOOLS } from "../substate/tool-tracking-state.js";
6
6
  import { getState, recordToolChainCall, recordMemoryAccess, recordContextTool, resetScratchpadNudge, } from "../state.js";
7
7
  /**
8
- * Record file paths from read/edit operations for re-read detection.
8
+ * Lines a read brings into context when it names no `limit`: the read tool
9
+ * truncates to its own DEFAULT_MAX_LINES (2000) from the offset. Without the
10
+ * cap a read with no limit would look like it covered the whole file and every
11
+ * later line the tool never returned would read as already in context.
12
+ */
13
+ const READ_DEFAULT_LIMIT = 2000;
14
+ /**
15
+ * Windows kept per path, the oldest dropped past this. A dropped window only
16
+ * shrinks what counts as in context, so the bound can hide a repeat but can
17
+ * never invent one.
18
+ */
19
+ const READ_RANGES_PER_PATH = 8;
20
+ /** The line window a read asks for, `[start, end)`, from its own bounds and the tool's defaults. */
21
+ function readWindow(input) {
22
+ const offset = typeof input.offset === "number" && Number.isFinite(input.offset) ? input.offset : 0;
23
+ const limit = typeof input.limit === "number" && Number.isFinite(input.limit) && input.limit > 0
24
+ ? input.limit
25
+ : READ_DEFAULT_LIMIT;
26
+ const start = offset > 0 ? offset : 0;
27
+ return { start, end: start + limit };
28
+ }
29
+ /**
30
+ * Whether these windows leave no line of `[start, end)` out. They are merged
31
+ * and ascending, so one pass over this path's own windows settles it.
32
+ */
33
+ function coversWindow(windows, start, end) {
34
+ let coveredTo = start;
35
+ for (const w of windows) {
36
+ if (w.start > coveredTo)
37
+ return false;
38
+ if (w.end > coveredTo)
39
+ coveredTo = w.end;
40
+ if (coveredTo >= end)
41
+ return true;
42
+ }
43
+ return coveredTo >= end;
44
+ }
45
+ /** The newest position among a path's windows, for the path-population prune. */
46
+ function newestReadAt(windows) {
47
+ let newest = 0;
48
+ for (const w of windows)
49
+ if (w.at > newest)
50
+ newest = w.at;
51
+ return newest;
52
+ }
53
+ /**
54
+ * Record one `read` call: flag the path when every line it asks for is already
55
+ * in context, then keep the window for the reads that follow.
56
+ */
57
+ function recordRead(s, path, input) {
58
+ const { start, end } = readWindow(input);
59
+ // A window recorded before the last progress tool describes context an
60
+ // edit, write or command has since replaced: stale, not waste.
61
+ const windows = (s.recentlyReadFiles.get(path) ?? []).filter((w) => w.at >= s.lastProgressToolCall);
62
+ if (coversWindow(windows, start, end) && !s.turnReReadWastePaths.includes(path)) {
63
+ s.turnReReadWastePaths.push(path);
64
+ }
65
+ windows.push({ start, end, at: s.totalToolCalls });
66
+ windows.sort((a, b) => a.start - b.start);
67
+ // Keep a disjoint ascending set: reading one slice again then costs one
68
+ // window instead of consuming the per-path bound.
69
+ const merged = [];
70
+ for (const w of windows) {
71
+ const last = merged[merged.length - 1];
72
+ if (last && w.start <= last.end) {
73
+ last.end = Math.max(last.end, w.end);
74
+ last.at = Math.max(last.at, w.at);
75
+ }
76
+ else {
77
+ merged.push({ ...w });
78
+ }
79
+ }
80
+ while (merged.length > READ_RANGES_PER_PATH) {
81
+ let oldest = 0;
82
+ for (let i = 1; i < merged.length; i++) {
83
+ if (merged[i].at < merged[oldest].at)
84
+ oldest = i;
85
+ }
86
+ merged.splice(oldest, 1);
87
+ }
88
+ s.recentlyReadFiles.set(path, merged);
89
+ // Prune old entries (keep only last 50 files)
90
+ if (s.recentlyReadFiles.size > 50) {
91
+ const oldest = [...s.recentlyReadFiles.entries()]
92
+ .sort((a, b) => newestReadAt(a[1]) - newestReadAt(b[1]))
93
+ .slice(0, 10);
94
+ for (const [k] of oldest)
95
+ s.recentlyReadFiles.delete(k);
96
+ }
97
+ }
98
+ /**
99
+ * Record the window each read asks for, so turn validation can name only the
100
+ * reads whose lines are already in context.
9
101
  * Called from tool_call event handler which has access to event.input.
10
102
  */
11
103
  export function recordToolInput(toolName, input, s) {
@@ -15,23 +107,7 @@ export function recordToolInput(toolName, input, s) {
15
107
  if (!path)
16
108
  return;
17
109
  if (toolName === "read") {
18
- // Map value: the tool-call position of the last read of this path. A path
19
- // that is already mapped with no progress tool since was read before and
20
- // is being read again without anything changing in between; the list is
21
- // consumed by turn validation.
22
- const priorRead = s.recentlyReadFiles.get(path);
23
- if (priorRead !== undefined &&
24
- priorRead >= s.lastProgressToolCall &&
25
- !s.turnReReadWastePaths.includes(path)) {
26
- s.turnReReadWastePaths.push(path);
27
- }
28
- s.recentlyReadFiles.set(path, s.totalToolCalls);
29
- // Prune old entries (keep only last 50 files)
30
- if (s.recentlyReadFiles.size > 50) {
31
- const oldest = [...s.recentlyReadFiles.entries()].sort((a, b) => a[1] - b[1]).slice(0, 10);
32
- for (const [k] of oldest)
33
- s.recentlyReadFiles.delete(k);
34
- }
110
+ recordRead(s, path, input);
35
111
  }
36
112
  }
37
113
  export function recordToolCall(toolName, ctx) {
@@ -11,6 +11,24 @@ import type { ToolChainState, ToolSequencePattern } from "../types.js";
11
11
  * the same set.
12
12
  */
13
13
  export declare const PROGRESS_TOOLS: Set<string>;
14
+ /**
15
+ * One read's worth of context: the line window a single `read` call asked the
16
+ * tool to bring in.
17
+ *
18
+ * The window is what the re-read check compares, because a long file is read
19
+ * in slices: a second read of the same path repeats work only when every line
20
+ * it asks for is already in context. `at` is the tool-call position of the
21
+ * read that recorded the window, so a progress tool after it can mark the
22
+ * window as stale rather than waste.
23
+ */
24
+ export interface ReadRange {
25
+ /** First line the read asked for (the read tool's `offset`, or none). */
26
+ start: number;
27
+ /** One past the last line the read asked for. */
28
+ end: number;
29
+ /** `totalToolCalls` position of the read that recorded this window. */
30
+ at: number;
31
+ }
14
32
  export interface CalibrationPair {
15
33
  predicted: number;
16
34
  actual: number;
@@ -36,7 +54,10 @@ export interface ToolTrackingState {
36
54
  turnsSinceExplore: number;
37
55
  exploreBeforeActNudged: boolean;
38
56
  toolDiversityNudged: boolean;
39
- recentlyReadFiles: Map<string, number>;
57
+ /** Per path, the line windows read since the last progress tool, merged and
58
+ * ascending by start. Bounded by `READ_RANGES_PER_PATH` in
59
+ * handlers/tool-tracker.ts, the module that fills it. */
60
+ recentlyReadFiles: Map<string, ReadRange[]>;
40
61
  /** Paths re-read this turn while a prior read was still current (no
41
62
  * edit/write/bash since). Filled by recordToolInput; validateTurn consumes
42
63
  * the list and clears it. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.44",
3
+ "version": "0.43.46",
4
4
  "description": "🥨 Braid - Metacognitive extension suite for pi coding agent: Adds memory, plan tracking, structured cognitive signals and completion checks on top of pi core loop, so long sessions keep their context and stop claiming unfinished work.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -3,6 +3,7 @@
3
3
  */
4
4
  import { recordCodeChange } from "../detection/verification.js";
5
5
  import { PROGRESS_TOOLS } from "../substate/tool-tracking-state.js";
6
+ import type { ReadRange } from "../substate/tool-tracking-state.js";
6
7
  import {
7
8
  getState,
8
9
  recordToolChainCall,
@@ -13,7 +14,106 @@ import {
13
14
  import type { EnforcementState } from "../state.js";
14
15
 
15
16
  /**
16
- * Record file paths from read/edit operations for re-read detection.
17
+ * Lines a read brings into context when it names no `limit`: the read tool
18
+ * truncates to its own DEFAULT_MAX_LINES (2000) from the offset. Without the
19
+ * cap a read with no limit would look like it covered the whole file and every
20
+ * later line the tool never returned would read as already in context.
21
+ */
22
+ const READ_DEFAULT_LIMIT = 2000;
23
+
24
+ /**
25
+ * Windows kept per path, the oldest dropped past this. A dropped window only
26
+ * shrinks what counts as in context, so the bound can hide a repeat but can
27
+ * never invent one.
28
+ */
29
+ const READ_RANGES_PER_PATH = 8;
30
+
31
+ /** The line window a read asks for, `[start, end)`, from its own bounds and the tool's defaults. */
32
+ function readWindow(input: Record<string, unknown>): { start: number; end: number } {
33
+ const offset =
34
+ typeof input.offset === "number" && Number.isFinite(input.offset) ? input.offset : 0;
35
+ const limit =
36
+ typeof input.limit === "number" && Number.isFinite(input.limit) && input.limit > 0
37
+ ? input.limit
38
+ : READ_DEFAULT_LIMIT;
39
+ const start = offset > 0 ? offset : 0;
40
+ return { start, end: start + limit };
41
+ }
42
+
43
+ /**
44
+ * Whether these windows leave no line of `[start, end)` out. They are merged
45
+ * and ascending, so one pass over this path's own windows settles it.
46
+ */
47
+ function coversWindow(windows: ReadRange[], start: number, end: number): boolean {
48
+ let coveredTo = start;
49
+ for (const w of windows) {
50
+ if (w.start > coveredTo) return false;
51
+ if (w.end > coveredTo) coveredTo = w.end;
52
+ if (coveredTo >= end) return true;
53
+ }
54
+ return coveredTo >= end;
55
+ }
56
+
57
+ /** The newest position among a path's windows, for the path-population prune. */
58
+ function newestReadAt(windows: ReadRange[]): number {
59
+ let newest = 0;
60
+ for (const w of windows) if (w.at > newest) newest = w.at;
61
+ return newest;
62
+ }
63
+
64
+ /**
65
+ * Record one `read` call: flag the path when every line it asks for is already
66
+ * in context, then keep the window for the reads that follow.
67
+ */
68
+ function recordRead(s: EnforcementState, path: string, input: Record<string, unknown>): void {
69
+ const { start, end } = readWindow(input);
70
+
71
+ // A window recorded before the last progress tool describes context an
72
+ // edit, write or command has since replaced: stale, not waste.
73
+ const windows = (s.recentlyReadFiles.get(path) ?? []).filter(
74
+ (w) => w.at >= s.lastProgressToolCall,
75
+ );
76
+
77
+ if (coversWindow(windows, start, end) && !s.turnReReadWastePaths.includes(path)) {
78
+ s.turnReReadWastePaths.push(path);
79
+ }
80
+
81
+ windows.push({ start, end, at: s.totalToolCalls });
82
+ windows.sort((a, b) => a.start - b.start);
83
+
84
+ // Keep a disjoint ascending set: reading one slice again then costs one
85
+ // window instead of consuming the per-path bound.
86
+ const merged: ReadRange[] = [];
87
+ for (const w of windows) {
88
+ const last = merged[merged.length - 1];
89
+ if (last && w.start <= last.end) {
90
+ last.end = Math.max(last.end, w.end);
91
+ last.at = Math.max(last.at, w.at);
92
+ } else {
93
+ merged.push({ ...w });
94
+ }
95
+ }
96
+ while (merged.length > READ_RANGES_PER_PATH) {
97
+ let oldest = 0;
98
+ for (let i = 1; i < merged.length; i++) {
99
+ if (merged[i].at < merged[oldest].at) oldest = i;
100
+ }
101
+ merged.splice(oldest, 1);
102
+ }
103
+ s.recentlyReadFiles.set(path, merged);
104
+
105
+ // Prune old entries (keep only last 50 files)
106
+ if (s.recentlyReadFiles.size > 50) {
107
+ const oldest = [...s.recentlyReadFiles.entries()]
108
+ .sort((a, b) => newestReadAt(a[1]) - newestReadAt(b[1]))
109
+ .slice(0, 10);
110
+ for (const [k] of oldest) s.recentlyReadFiles.delete(k);
111
+ }
112
+ }
113
+
114
+ /**
115
+ * Record the window each read asks for, so turn validation can name only the
116
+ * reads whose lines are already in context.
17
117
  * Called from tool_call event handler which has access to event.input.
18
118
  */
19
119
  export function recordToolInput(
@@ -27,24 +127,7 @@ export function recordToolInput(
27
127
  if (!path) return;
28
128
 
29
129
  if (toolName === "read") {
30
- // Map value: the tool-call position of the last read of this path. A path
31
- // that is already mapped with no progress tool since was read before and
32
- // is being read again without anything changing in between; the list is
33
- // consumed by turn validation.
34
- const priorRead = s.recentlyReadFiles.get(path);
35
- if (
36
- priorRead !== undefined &&
37
- priorRead >= s.lastProgressToolCall &&
38
- !s.turnReReadWastePaths.includes(path)
39
- ) {
40
- s.turnReReadWastePaths.push(path);
41
- }
42
- s.recentlyReadFiles.set(path, s.totalToolCalls);
43
- // Prune old entries (keep only last 50 files)
44
- if (s.recentlyReadFiles.size > 50) {
45
- const oldest = [...s.recentlyReadFiles.entries()].sort((a, b) => a[1] - b[1]).slice(0, 10);
46
- for (const [k] of oldest) s.recentlyReadFiles.delete(k);
47
- }
130
+ recordRead(s, path, input);
48
131
  }
49
132
  }
50
133
 
@@ -14,6 +14,25 @@ import type { ToolChainState, ToolSequencePattern } from "../types.js";
14
14
  */
15
15
  export const PROGRESS_TOOLS = new Set<string>(["edit", "write", "bash"]);
16
16
 
17
+ /**
18
+ * One read's worth of context: the line window a single `read` call asked the
19
+ * tool to bring in.
20
+ *
21
+ * The window is what the re-read check compares, because a long file is read
22
+ * in slices: a second read of the same path repeats work only when every line
23
+ * it asks for is already in context. `at` is the tool-call position of the
24
+ * read that recorded the window, so a progress tool after it can mark the
25
+ * window as stale rather than waste.
26
+ */
27
+ export interface ReadRange {
28
+ /** First line the read asked for (the read tool's `offset`, or none). */
29
+ start: number;
30
+ /** One past the last line the read asked for. */
31
+ end: number;
32
+ /** `totalToolCalls` position of the read that recorded this window. */
33
+ at: number;
34
+ }
35
+
17
36
  export interface CalibrationPair {
18
37
  predicted: number;
19
38
  actual: number;
@@ -40,7 +59,10 @@ export interface ToolTrackingState {
40
59
  turnsSinceExplore: number;
41
60
  exploreBeforeActNudged: boolean;
42
61
  toolDiversityNudged: boolean;
43
- recentlyReadFiles: Map<string, number>;
62
+ /** Per path, the line windows read since the last progress tool, merged and
63
+ * ascending by start. Bounded by `READ_RANGES_PER_PATH` in
64
+ * handlers/tool-tracker.ts, the module that fills it. */
65
+ recentlyReadFiles: Map<string, ReadRange[]>;
44
66
  /** Paths re-read this turn while a prior read was still current (no
45
67
  * edit/write/bash since). Filled by recordToolInput; validateTurn consumes
46
68
  * the list and clears it. */
@@ -92,7 +114,7 @@ export function createToolTrackingState(): ToolTrackingState {
92
114
  turnsSinceExplore: 0,
93
115
  exploreBeforeActNudged: false,
94
116
  toolDiversityNudged: false,
95
- recentlyReadFiles: new Map<string, number>(),
117
+ recentlyReadFiles: new Map<string, ReadRange[]>(),
96
118
  turnReReadWastePaths: [],
97
119
  lastProgressToolCall: 0,
98
120