pi-braid 0.43.39 → 0.43.41

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/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.39",
4
- "sha": "9a833277c0434574ccf169f716b2031cba83efdd",
5
- "shaShort": "9a833277",
3
+ "version": "0.43.41",
4
+ "sha": "3caa82c28469ebde9b6110fccf75e676fdc51194",
5
+ "shaShort": "3caa82c2",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-11-09T19:55:14.389Z"
8
+ "packedAt": "2026-11-09T22:40:43.361Z"
9
9
  }
@@ -40,7 +40,8 @@ import { compactEpisodesFile, flushEpisodeAppends } from "./episodes-disk.js";
40
40
  // Sub-module imports
41
41
  import { retrieveByRUMS, sanitizeEpisode } from "./episodes.js";
42
42
  import { addHeuristicRule, getPrioritizedHeuristics, BUILTIN_HEURISTICS } from "./heuristics.js";
43
- import { recordToolCall, getToolReliability } from "./tool-reliability.js";
43
+ import { recordToolCall } from "./tool-reliability.js";
44
+ import { allowFamilyHint, createFamilyHintGate, formatSuggestion, noteTurn, suggestAlternative, } from "../../../lib/tools/tool-families.js";
44
45
  import { whisperRecall, AUTO_RECALL_ENABLED, RECALL_COOLDOWN_MS, } from "./handlers/whisper-recall.js";
45
46
  import { TURN_END, SESSION_SHUTDOWN, AGENT_END } from "../../../lib/core/event-names.js";
46
47
  // Project Identifier
@@ -176,44 +177,36 @@ export default function threeMemoryStoresExtension(pi) {
176
177
  if (similarFailures.length > 0 && similarFailures[0].similarity > 0.35) {
177
178
  whisperRecall(state, ctx, pi, `Similar past issue with ${toolName}:`, similarFailures, project);
178
179
  }
180
+ // bash is never the tool to abandon: it runs anything, so a swipe
181
+ // against it is not advice a reader can act on.
179
182
  if (toolName !== "bash") {
180
- const currentReliability = getToolReliability(state, toolName, taskType);
181
- if (currentReliability < 0.4 && state.toolStats.size > 3) {
182
- let bestAlt = null;
183
- let bestRel = 0;
184
- for (const [key, stat] of state.toolStats) {
185
- const [t, tt] = key.split(":");
186
- if (t !== toolName && tt === taskType && stat.successes / stat.attempts > bestRel) {
187
- bestRel = stat.successes / stat.attempts;
188
- bestAlt = t;
189
- }
190
- }
191
- if (bestAlt && bestRel > currentReliability + 0.2) {
192
- sendTrackedMessage(pi, {
193
- // This body is TOOL-RELIABILITY ANALYTICS
194
- // (a stats-driven recommendation), not memory recall. It was
195
- // labeled customType "memory", which misattributed it to the
196
- // memory family. True family is analytics; the envelope
197
- // derives from the source below, so both now say analytics.
198
- customType: "analytics",
199
- display: true,
200
- content: [
201
- {
202
- type: "text",
203
- text: `${bestAlt} has better reliability (${(bestRel * 100).toFixed(0)}%) for "${taskType}" than ${toolName} (${(currentReliability * 100).toFixed(0)}%)`,
204
- },
205
- ],
206
- },
207
- // triggerTurn: true - significant reliability gap (>0.2)
208
- // means the current tool is consistently failing for this
209
- // task type. Wakes the agent so it can switch tools.
210
- { deliverAs: "steer", triggerTurn: true },
211
- // type "heartbeat" (not "other") keeps the _braidInjected /
212
- // _braidSource decoration; heartbeat is the analytics-alert
213
- // type (see heartbeat/analytics). Source root "analytics" so
214
- // envelope family == body family ().
215
- { type: "heartbeat", source: "analytics/reliability" });
216
- }
183
+ // `taskType` groups the statistics; only a declared substitute may be
184
+ // named (lib/tools/tool-families.ts). The suggestion carries its own
185
+ // sample, so the body prints the counts the claim rests on and thin
186
+ // data cannot reach a reader.
187
+ const suggestion = suggestAlternative({
188
+ stats: state.toolStats.values(),
189
+ tool: toolName,
190
+ taskType,
191
+ });
192
+ const hintGate = getExtensionState(ctx, "tool-family-hints", createFamilyHintGate);
193
+ if (suggestion && allowFamilyHint(hintGate, suggestion.family)) {
194
+ sendTrackedMessage(pi, {
195
+ // This body is TOOL-RELIABILITY ANALYTICS
196
+ // (a stats-driven recommendation), not memory recall. True
197
+ // family is analytics; the envelope derives from the source
198
+ // below, so both say analytics.
199
+ customType: "analytics",
200
+ display: true,
201
+ content: [{ type: "text", text: formatSuggestion(suggestion) }],
202
+ },
203
+ // An advisory hint rides the next turn; it does not create one.
204
+ { delivery: "park", deliverAs: "steer" },
205
+ // type "heartbeat" (not "other") keeps the _braidInjected /
206
+ // _braidSource decoration; heartbeat is the analytics-alert
207
+ // type (see heartbeat/analytics). Source root "analytics" so
208
+ // envelope family == body family.
209
+ { type: "heartbeat", source: "analytics/reliability" });
217
210
  }
218
211
  }
219
212
  }
@@ -226,6 +219,9 @@ export default function threeMemoryStoresExtension(pi) {
226
219
  pi.on(TURN_END, async (_event, ctx) => {
227
220
  try {
228
221
  const state = getState(ctx);
222
+ // The family-rate-limit clock runs on completed turns, so it advances
223
+ // before this handler's own early returns can skip it.
224
+ noteTurn(getExtensionState(ctx, "tool-family-hints", createFamilyHintGate));
229
225
  if (!AUTO_RECALL_ENABLED || state.currentSessionTools.length < 3)
230
226
  return;
231
227
  const now = Date.now();
@@ -0,0 +1,119 @@
1
+ /**
2
+ * Tool families - which tools may be compared on reliability.
3
+ *
4
+ * A reliability statistic answers "how often did this tool work?" only inside a
5
+ * population of attempts that could have been made by either tool. `taskType`
6
+ * (see `inferTaskType` in the memory extension) is not that population: it names
7
+ * a phase of work ("general", "file_edit", "search"), and a tool with no entry in
8
+ * its map falls through to "general". That label therefore groups
9
+ * `herdr_layout` (arranges terminal panes) with `fetch_content` (fetches a URL),
10
+ * and a comparison built on it reads as advice to fetch a web page with the
11
+ * layout tool.
12
+ *
13
+ * **`taskType` is a label, not a claim about what a tool does.** The claim lives
14
+ * here: a tool is substitutable only with tools in its own family. A tool with no
15
+ * entry in this map has no family, is not known to be comparable with anything,
16
+ * and never produces a recommendation - a new tool joins the family map by being
17
+ * declared, not by being observed.
18
+ *
19
+ * The module is pure: no state, no I/O, no imports. Callers own the statistics and
20
+ * the session-scoped hint gate.
21
+ */
22
+ export type ToolFamily = "web-fetch" | "terminal" | "files" | "agents" | "memory" | "orchestration";
23
+ /**
24
+ * Which tools do the same job. Membership is a declaration about purpose, not a
25
+ * statement that the tools are interchangeable in every argument shape: `read`
26
+ * and `edit` are both files tools, and one reads what the other writes.
27
+ */
28
+ export declare const TOOL_FAMILIES: Readonly<Record<string, ToolFamily>>;
29
+ /**
30
+ * The family of `tool`, or `null` when the tool is not declared. The own-property
31
+ * test is deliberate: an index lookup for a name like "toString" would otherwise
32
+ * return something off the prototype chain and read as a family.
33
+ */
34
+ export declare function familyOf(tool: string): ToolFamily | null;
35
+ /** The part of a tool statistic this module reads. */
36
+ export interface ToolStatLike {
37
+ tool: string;
38
+ taskType: string;
39
+ attempts: number;
40
+ successes: number;
41
+ }
42
+ export interface Sample {
43
+ attempts: number;
44
+ successes: number;
45
+ }
46
+ export interface ToolFamilySuggestion {
47
+ /** The tool to switch to. Same family as `tool`. */
48
+ alternative: string;
49
+ /** Reliability of `tool` for `taskType`, in [0, 1]. */
50
+ current: number;
51
+ /** Reliability of `alternative` for the same task type, in [0, 1]. */
52
+ better: number;
53
+ /** The failing tool's own sample. */
54
+ sample: Sample;
55
+ /** The alternative's sample. */
56
+ alternatives: Sample;
57
+ /** The tool whose failure prompted this. */
58
+ tool: string;
59
+ family: ToolFamily;
60
+ taskType: string;
61
+ }
62
+ /** Both sides must carry at least this many attempts for the task type. */
63
+ export declare const MIN_ATTEMPTS = 5;
64
+ /**
65
+ * The alternative must beat the failing tool by this margin. Held as the fraction
66
+ * 1/5 so the decision runs on integer counts (see `meetsGap`) instead of the
67
+ * subtraction of two rounded ratios.
68
+ */
69
+ export declare const MIN_GAP = 0.2;
70
+ /**
71
+ * The best substitute for `tool` on `taskType`, or `null` when there is none.
72
+ *
73
+ * Null whenever: the tool has no declared family; the tool's own sample for this
74
+ * task type is under `MIN_ATTEMPTS`; no same-family tool reaches `MIN_ATTEMPTS`
75
+ * on that task type; or no such tool clears `MIN_GAP`. Ties in reliability go to
76
+ * the lexicographically first tool name, so the same statistics always name the
77
+ * same alternative.
78
+ */
79
+ export declare function suggestAlternative(input: {
80
+ stats: Iterable<ToolStatLike>;
81
+ tool: string;
82
+ taskType: string;
83
+ }): ToolFamilySuggestion | null;
84
+ /**
85
+ * The sentence a reader receives. Both samples are on the line: a percentage
86
+ * without its counts is what made the old hint unreadable, and a reader must be
87
+ * able to watch the sample decide the claim. `taskType` is named because it is
88
+ * what the counts are grouped by; the family is named because it is what makes
89
+ * the comparison admissible in the first place.
90
+ */
91
+ export declare function formatSuggestion(suggestion: ToolFamilySuggestion): string;
92
+ /**
93
+ * One hint per family per this many turns.
94
+ *
95
+ * The statistics are cumulative for the session, so between two turns the sample
96
+ * grows while the direction of the claim does not change: a second copy of the
97
+ * same advice carries no fact the first lacked, and a reader who sees it every
98
+ * turn learns to filter the family out. Ten turns is long enough for a reader to
99
+ * act (switching tools shows up as new attempts on both sides) and short enough
100
+ * that a session which ignored the hint still sees it once more before it ends.
101
+ */
102
+ export declare const HINT_COOLDOWN_TURNS = 10;
103
+ /** Per-session hint limiter. Hold it in session state, never at module scope. */
104
+ export interface FamilyHintGate {
105
+ /** Turns completed in this session. */
106
+ turn: number;
107
+ /** Turn of the last emitted hint, per family. */
108
+ lastHintTurn: Partial<Record<ToolFamily, number>>;
109
+ }
110
+ export declare function createFamilyHintGate(): FamilyHintGate;
111
+ /** Advance the session's turn clock by one completed turn. */
112
+ export declare function noteTurn(gate: FamilyHintGate): void;
113
+ /**
114
+ * Claim the right to emit one hint for `family`. Returns `false` while the family
115
+ * is still inside its cooldown; a `true` return records the hint at the current
116
+ * turn, so the caller must emit when it gets one.
117
+ */
118
+ export declare function allowFamilyHint(gate: FamilyHintGate, family: ToolFamily): boolean;
119
+ //# sourceMappingURL=tool-families.d.ts.map
@@ -0,0 +1,172 @@
1
+ /**
2
+ * Tool families - which tools may be compared on reliability.
3
+ *
4
+ * A reliability statistic answers "how often did this tool work?" only inside a
5
+ * population of attempts that could have been made by either tool. `taskType`
6
+ * (see `inferTaskType` in the memory extension) is not that population: it names
7
+ * a phase of work ("general", "file_edit", "search"), and a tool with no entry in
8
+ * its map falls through to "general". That label therefore groups
9
+ * `herdr_layout` (arranges terminal panes) with `fetch_content` (fetches a URL),
10
+ * and a comparison built on it reads as advice to fetch a web page with the
11
+ * layout tool.
12
+ *
13
+ * **`taskType` is a label, not a claim about what a tool does.** The claim lives
14
+ * here: a tool is substitutable only with tools in its own family. A tool with no
15
+ * entry in this map has no family, is not known to be comparable with anything,
16
+ * and never produces a recommendation - a new tool joins the family map by being
17
+ * declared, not by being observed.
18
+ *
19
+ * The module is pure: no state, no I/O, no imports. Callers own the statistics and
20
+ * the session-scoped hint gate.
21
+ */
22
+ /**
23
+ * Which tools do the same job. Membership is a declaration about purpose, not a
24
+ * statement that the tools are interchangeable in every argument shape: `read`
25
+ * and `edit` are both files tools, and one reads what the other writes.
26
+ */
27
+ export const TOOL_FAMILIES = {
28
+ fetch_content: "web-fetch",
29
+ web_search: "web-fetch",
30
+ get_search_content: "web-fetch",
31
+ bash: "terminal",
32
+ herdr_pane: "terminal",
33
+ herdr_layout: "terminal",
34
+ read: "files",
35
+ write: "files",
36
+ edit: "files",
37
+ grep: "files",
38
+ find: "files",
39
+ ls: "files",
40
+ herdr_agent: "agents",
41
+ memory: "memory",
42
+ memory_store: "memory",
43
+ scratchpad: "memory",
44
+ session: "memory",
45
+ orchestrate: "orchestration",
46
+ timer: "orchestration",
47
+ };
48
+ /**
49
+ * The family of `tool`, or `null` when the tool is not declared. The own-property
50
+ * test is deliberate: an index lookup for a name like "toString" would otherwise
51
+ * return something off the prototype chain and read as a family.
52
+ */
53
+ export function familyOf(tool) {
54
+ return Object.prototype.hasOwnProperty.call(TOOL_FAMILIES, tool) ? TOOL_FAMILIES[tool] : null;
55
+ }
56
+ /** Both sides must carry at least this many attempts for the task type. */
57
+ export const MIN_ATTEMPTS = 5;
58
+ /**
59
+ * The alternative must beat the failing tool by this margin. Held as the fraction
60
+ * 1/5 so the decision runs on integer counts (see `meetsGap`) instead of the
61
+ * subtraction of two rounded ratios.
62
+ */
63
+ export const MIN_GAP = 0.2;
64
+ /**
65
+ * `alternative` beats `current` by at least `MIN_GAP`, decided exactly:
66
+ *
67
+ * alt.s/alt.a - cur.s/cur.a >= 1/5 <=> 5*(alt.s*cur.a - cur.s*alt.a) >= cur.a*alt.a
68
+ *
69
+ * The integer form matters because float subtraction puts a gap of exactly 0.2
70
+ * (3/5 vs 2/5) at 0.19999999999999996, which would refuse a comparison the stated
71
+ * rule allows.
72
+ */
73
+ function meetsGap(current, alternative) {
74
+ const numerator = alternative.successes * current.attempts - current.successes * alternative.attempts;
75
+ return numerator > 0 && 5 * numerator >= current.attempts * alternative.attempts;
76
+ }
77
+ /**
78
+ * The best substitute for `tool` on `taskType`, or `null` when there is none.
79
+ *
80
+ * Null whenever: the tool has no declared family; the tool's own sample for this
81
+ * task type is under `MIN_ATTEMPTS`; no same-family tool reaches `MIN_ATTEMPTS`
82
+ * on that task type; or no such tool clears `MIN_GAP`. Ties in reliability go to
83
+ * the lexicographically first tool name, so the same statistics always name the
84
+ * same alternative.
85
+ */
86
+ export function suggestAlternative(input) {
87
+ const family = familyOf(input.tool);
88
+ if (family === null)
89
+ return null;
90
+ let current = null;
91
+ const candidates = [];
92
+ for (const stat of input.stats) {
93
+ if (!stat || stat.taskType !== input.taskType)
94
+ continue;
95
+ if (stat.tool === input.tool) {
96
+ if (current === null)
97
+ current = stat;
98
+ continue;
99
+ }
100
+ if (familyOf(stat.tool) === family)
101
+ candidates.push(stat);
102
+ }
103
+ if (current === null || current.attempts < MIN_ATTEMPTS)
104
+ return null;
105
+ const failing = current;
106
+ const qualified = candidates.filter((candidate) => candidate.attempts >= MIN_ATTEMPTS && meetsGap(failing, candidate));
107
+ if (qualified.length === 0)
108
+ return null;
109
+ qualified.sort((a, b) => {
110
+ // Descending reliability by cross-multiplication; then by name for stability.
111
+ const byRate = b.successes * a.attempts - a.successes * b.attempts;
112
+ if (byRate !== 0)
113
+ return byRate;
114
+ return a.tool < b.tool ? -1 : a.tool > b.tool ? 1 : 0;
115
+ });
116
+ const best = qualified[0];
117
+ return {
118
+ alternative: best.tool,
119
+ current: failing.successes / failing.attempts,
120
+ better: best.successes / best.attempts,
121
+ sample: { attempts: failing.attempts, successes: failing.successes },
122
+ alternatives: { attempts: best.attempts, successes: best.successes },
123
+ tool: input.tool,
124
+ family,
125
+ taskType: input.taskType,
126
+ };
127
+ }
128
+ /**
129
+ * The sentence a reader receives. Both samples are on the line: a percentage
130
+ * without its counts is what made the old hint unreadable, and a reader must be
131
+ * able to watch the sample decide the claim. `taskType` is named because it is
132
+ * what the counts are grouped by; the family is named because it is what makes
133
+ * the comparison admissible in the first place.
134
+ */
135
+ export function formatSuggestion(suggestion) {
136
+ const better = suggestion.alternatives;
137
+ const current = suggestion.sample;
138
+ return (`${suggestion.alternative} succeeded ${better.successes} of ${better.attempts} on ` +
139
+ `"${suggestion.taskType}" where ${suggestion.tool} succeeded ${current.successes} of ` +
140
+ `${current.attempts} (same tool family: ${suggestion.family})`);
141
+ }
142
+ /**
143
+ * One hint per family per this many turns.
144
+ *
145
+ * The statistics are cumulative for the session, so between two turns the sample
146
+ * grows while the direction of the claim does not change: a second copy of the
147
+ * same advice carries no fact the first lacked, and a reader who sees it every
148
+ * turn learns to filter the family out. Ten turns is long enough for a reader to
149
+ * act (switching tools shows up as new attempts on both sides) and short enough
150
+ * that a session which ignored the hint still sees it once more before it ends.
151
+ */
152
+ export const HINT_COOLDOWN_TURNS = 10;
153
+ export function createFamilyHintGate() {
154
+ return { turn: 0, lastHintTurn: {} };
155
+ }
156
+ /** Advance the session's turn clock by one completed turn. */
157
+ export function noteTurn(gate) {
158
+ gate.turn += 1;
159
+ }
160
+ /**
161
+ * Claim the right to emit one hint for `family`. Returns `false` while the family
162
+ * is still inside its cooldown; a `true` return records the hint at the current
163
+ * turn, so the caller must emit when it gets one.
164
+ */
165
+ export function allowFamilyHint(gate, family) {
166
+ const last = gate.lastHintTurn[family];
167
+ if (last !== undefined && gate.turn - last < HINT_COOLDOWN_TURNS)
168
+ return false;
169
+ gate.lastHintTurn[family] = gate.turn;
170
+ return true;
171
+ }
172
+ //# sourceMappingURL=tool-families.js.map
package/docs/LOCAL_DEV.md CHANGED
@@ -138,7 +138,7 @@ before and after a full run. A non-zero delta is the leak this rule prevents.
138
138
  ### New fixtures: use `node:test`
139
139
 
140
140
  A new fixture is written on `node:test`. The runner does not care which style a
141
- file uses - 112 of the core suite's 349 fixtures already use `node:test` - so the
141
+ file uses - 113 of the core suite's 350 fixtures already use `node:test` - so the
142
142
  reason is the failure the other style produces. A hand-rolled helper that calls
143
143
  `fn()` without awaiting it discards the case's promise, so an `async` case runs
144
144
  detached and the file can print its green tally before that case settles, with
package/docs/SETUP.md CHANGED
@@ -317,6 +317,7 @@ The user-global file always exists; the project one is optional and belongs to p
317
317
  | `braid.skills.inform` | `off`/`inform` | `off` | At-use line. When `inform`, a completed call in a tool family a visible skill declares with `governs:` and no read of that body in the session emits one steer naming the file and the obligation, once per session per skill. It observes a call that already ran: it never refuses, delays or rewrites a tool result. Its conversion is reported by `skill_stats` (`inform.verdict`: `undecided` below 20 informs, `beats` when the lower Wilson bound clears the suggestion channel's 18.8%, `noise` otherwise). An unknown value falls back to `off`. |
318
318
  | `braid.telegram.sendMaxChars` | positive number | `4096` | Plain-text cap for `telegram_send`, re-read per call. |
319
319
  | `braid.telegram.notifyMaxChars` | positive number | `1200` | Craft target and guard for turn-end notifications. |
320
+ | `braid.telegram.pollerAutoStart` | boolean or string[] | `false` (nowhere) | Working directories that start the inbound poller by themselves: `true` for everywhere, an array of absolute cwds for those only, anything else for nowhere. Matching is exact, so a worktree beneath a listed directory does not inherit the channel. |
320
321
  | `braid.telegram.pauseStateFile` | path string | built-in default | Override for the `/telegram` pause-state file path. |
321
322
  | `braid.contrib.<name>` | boolean or object | enabled / per-extension | Per-contrib-extension config - see [§ Contrib extensions](#contrib-extensions). |
322
323
  | `braid.contrib.<extensionName>.enabled` | string[] | unset | Generic per-extension tool-enable list. The shared helper reads and writes string entries; the `/tools` surface stores its shared list in `braid.contrib._global.enabled`. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.39",
3
+ "version": "0.43.41",
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",
@@ -202,6 +202,18 @@ After release:
202
202
  - Commit stable package versions before remote npm publication. Local snapshots
203
203
  use the derived iteration version instead.
204
204
  - Use `npm version` for semver bumps in the target workspace.
205
+ - The bump is chosen by what a consumer can notice, not by how many patches
206
+ have accumulated:
207
+
208
+ | Bump | Trigger |
209
+ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
210
+ | patch | nothing a caller can observe: a fix, an internal refactor, docs, a test |
211
+ | minor | a caller must observe it: a new tool, command or flag; a new setting key; a changed default; a new required field in a contract; a deprecation |
212
+ | major | a break that needs a migration step: a renamed setting, a removed field, a changed wire or on-disk format |
213
+
214
+ A long patch line is not a reason to cut a minor on its own; it is a prompt to
215
+ ask whether one of the changes above already happened and was mislabelled.
216
+
205
217
  - A bare core release tag (`v<core version>`) runs the publish workflow. Publish
206
218
  a sibling package by dispatching from `main` with `only=<workspace directory>`
207
219
  (`core|skills|providers|telegram|contrib`, not the npm package name).
@@ -100,10 +100,9 @@ Whispers from compaction-retry, navigation, and memory hooks use `triggerTurn: t
100
100
 
101
101
  - **compaction-retry** (`context-manager/handlers/compaction-retry.ts`): exhausted / context-window / threshold errors all wake the agent. In-progress retry messages (`overflow`, `transient`, `threshold`, `summary-cap`) park (`delivery: "park"`, no forced continuation turn) because the agent is mid-retry; a summary-cap failure self-recovers on the retry cycle with a bounded chunked summary (compaction-chunked.ts), so only its exhausted path wakes.
102
102
  - **navigation** (`context-manager/handlers/navigation.ts`): "Context checkout prepared" with a direct action instruction wakes the agent.
103
- - **three-memory-stores** (`memory/three-memory-stores/index.ts`): tool reliability alerts (gap > 0.2) wake the agent so it can switch tools.
104
103
  - **rotation** (`context-manager/handlers/shared.ts:327`, `rotation.ts`): emergency rotation wakes. The size notice parks while a run is streaming (flushed at the same `turn_end`) and keeps its wake only when the session is idle; a notice still in flight suppresses a second emission through the unresolved-advisory registry in `lib/utils/injection-tracker.ts`.
105
104
 
106
- Advisory whispers (memory recall, past insights, hint injection, SOP suggestions) park (`delivery: "park"`) - they provide context for the agent's natural flow.
105
+ Advisory whispers (memory recall, past insights, hint injection, SOP suggestions, and the tool-reliability hint from `three-memory-stores`) park (`delivery: "park"`) - they provide context for the agent's natural flow. The reliability hint is scoped hard because it names a tool: the alternative must belong to the failing tool's declared family (`lib/tools/tool-families.ts`), both sides need at least 5 attempts, the gap must reach 0.2, the sentence prints both samples, and it fires at most once per family per `HINT_COOLDOWN_TURNS` turns.
107
106
 
108
107
  ## Re-entrancy safety
109
108
 
@@ -57,7 +57,14 @@ import type { MemoryStoresState, Episode } from "./types.js";
57
57
  // Sub-module imports
58
58
  import { retrieveByRUMS, sanitizeEpisode } from "./episodes.js";
59
59
  import { addHeuristicRule, getPrioritizedHeuristics, BUILTIN_HEURISTICS } from "./heuristics.js";
60
- import { recordToolCall, getToolReliability } from "./tool-reliability.js";
60
+ import { recordToolCall } from "./tool-reliability.js";
61
+ import {
62
+ allowFamilyHint,
63
+ createFamilyHintGate,
64
+ formatSuggestion,
65
+ noteTurn,
66
+ suggestAlternative,
67
+ } from "../../../lib/tools/tool-families.js";
61
68
  import {
62
69
  whisperRecall,
63
70
  AUTO_RECALL_ENABLED,
@@ -246,47 +253,39 @@ export default function threeMemoryStoresExtension(pi: ExtensionAPI) {
246
253
  );
247
254
  }
248
255
 
256
+ // bash is never the tool to abandon: it runs anything, so a swipe
257
+ // against it is not advice a reader can act on.
249
258
  if (toolName !== "bash") {
250
- const currentReliability = getToolReliability(state, toolName, taskType);
251
- if (currentReliability < 0.4 && state.toolStats.size > 3) {
252
- let bestAlt: string | null = null;
253
- let bestRel = 0;
254
- for (const [key, stat] of state.toolStats) {
255
- const [t, tt] = key.split(":");
256
- if (t !== toolName && tt === taskType && stat.successes / stat.attempts > bestRel) {
257
- bestRel = stat.successes / stat.attempts;
258
- bestAlt = t;
259
- }
260
- }
261
- if (bestAlt && bestRel > currentReliability + 0.2) {
262
- sendTrackedMessage(
263
- pi,
264
- {
265
- // This body is TOOL-RELIABILITY ANALYTICS
266
- // (a stats-driven recommendation), not memory recall. It was
267
- // labeled customType "memory", which misattributed it to the
268
- // memory family. True family is analytics; the envelope
269
- // derives from the source below, so both now say analytics.
270
- customType: "analytics",
271
- display: true,
272
- content: [
273
- {
274
- type: "text",
275
- text: `${bestAlt} has better reliability (${(bestRel * 100).toFixed(0)}%) for "${taskType}" than ${toolName} (${(currentReliability * 100).toFixed(0)}%)`,
276
- },
277
- ],
278
- },
279
- // triggerTurn: true - significant reliability gap (>0.2)
280
- // means the current tool is consistently failing for this
281
- // task type. Wakes the agent so it can switch tools.
282
- { deliverAs: "steer", triggerTurn: true },
283
- // type "heartbeat" (not "other") keeps the _braidInjected /
284
- // _braidSource decoration; heartbeat is the analytics-alert
285
- // type (see heartbeat/analytics). Source root "analytics" so
286
- // envelope family == body family ().
287
- { type: "heartbeat", source: "analytics/reliability" },
288
- );
289
- }
259
+ // `taskType` groups the statistics; only a declared substitute may be
260
+ // named (lib/tools/tool-families.ts). The suggestion carries its own
261
+ // sample, so the body prints the counts the claim rests on and thin
262
+ // data cannot reach a reader.
263
+ const suggestion = suggestAlternative({
264
+ stats: state.toolStats.values(),
265
+ tool: toolName,
266
+ taskType,
267
+ });
268
+ const hintGate = getExtensionState(ctx, "tool-family-hints", createFamilyHintGate);
269
+ if (suggestion && allowFamilyHint(hintGate, suggestion.family)) {
270
+ sendTrackedMessage(
271
+ pi,
272
+ {
273
+ // This body is TOOL-RELIABILITY ANALYTICS
274
+ // (a stats-driven recommendation), not memory recall. True
275
+ // family is analytics; the envelope derives from the source
276
+ // below, so both say analytics.
277
+ customType: "analytics",
278
+ display: true,
279
+ content: [{ type: "text", text: formatSuggestion(suggestion) }],
280
+ },
281
+ // An advisory hint rides the next turn; it does not create one.
282
+ { delivery: "park", deliverAs: "steer" },
283
+ // type "heartbeat" (not "other") keeps the _braidInjected /
284
+ // _braidSource decoration; heartbeat is the analytics-alert
285
+ // type (see heartbeat/analytics). Source root "analytics" so
286
+ // envelope family == body family.
287
+ { type: "heartbeat", source: "analytics/reliability" },
288
+ );
290
289
  }
291
290
  }
292
291
  }
@@ -299,6 +298,9 @@ export default function threeMemoryStoresExtension(pi: ExtensionAPI) {
299
298
  pi.on(TURN_END, async (_event: unknown, ctx: ExtensionContext) => {
300
299
  try {
301
300
  const state = getState(ctx);
301
+ // The family-rate-limit clock runs on completed turns, so it advances
302
+ // before this handler's own early returns can skip it.
303
+ noteTurn(getExtensionState(ctx, "tool-family-hints", createFamilyHintGate));
302
304
  if (!AUTO_RECALL_ENABLED || state.currentSessionTools.length < 3) return;
303
305
 
304
306
  const now = Date.now();
package/src/lib/AGENTS.md CHANGED
@@ -29,6 +29,7 @@ shared conventions.
29
29
  | [`harness/`](./harness/AGENTS.md) | Self-harness loop - failure-trace collection, weakness mining, candidate proposal and validation. |
30
30
  | `orchestrator/` | Multi-agent coordination - file-lock registry, worker registry with close-time gate-row well-formedness, the production-write preflight read, and the population-stamp read the merge path compares against the repo, worker branches, conflict detection, merge verification. |
31
31
  | [`telemetry/`](./telemetry/AGENTS.md) | Bounded telemetry accumulators for the degradation-detection loop (drift signals, context/RSS heartbeat). |
32
+ | `tools/` | Tool catalog - which tools may be compared on reliability, and the substitution rule built on it. |
32
33
  | `verification/` | Cross-file verification - downstream import tracing and derived-file coordination checks. |
33
34
 
34
35
  ## Conventions
@@ -0,0 +1,232 @@
1
+ /**
2
+ * Tool families - which tools may be compared on reliability.
3
+ *
4
+ * A reliability statistic answers "how often did this tool work?" only inside a
5
+ * population of attempts that could have been made by either tool. `taskType`
6
+ * (see `inferTaskType` in the memory extension) is not that population: it names
7
+ * a phase of work ("general", "file_edit", "search"), and a tool with no entry in
8
+ * its map falls through to "general". That label therefore groups
9
+ * `herdr_layout` (arranges terminal panes) with `fetch_content` (fetches a URL),
10
+ * and a comparison built on it reads as advice to fetch a web page with the
11
+ * layout tool.
12
+ *
13
+ * **`taskType` is a label, not a claim about what a tool does.** The claim lives
14
+ * here: a tool is substitutable only with tools in its own family. A tool with no
15
+ * entry in this map has no family, is not known to be comparable with anything,
16
+ * and never produces a recommendation - a new tool joins the family map by being
17
+ * declared, not by being observed.
18
+ *
19
+ * The module is pure: no state, no I/O, no imports. Callers own the statistics and
20
+ * the session-scoped hint gate.
21
+ */
22
+
23
+ export type ToolFamily = "web-fetch" | "terminal" | "files" | "agents" | "memory" | "orchestration";
24
+
25
+ /**
26
+ * Which tools do the same job. Membership is a declaration about purpose, not a
27
+ * statement that the tools are interchangeable in every argument shape: `read`
28
+ * and `edit` are both files tools, and one reads what the other writes.
29
+ */
30
+ export const TOOL_FAMILIES: Readonly<Record<string, ToolFamily>> = {
31
+ fetch_content: "web-fetch",
32
+ web_search: "web-fetch",
33
+ get_search_content: "web-fetch",
34
+
35
+ bash: "terminal",
36
+ herdr_pane: "terminal",
37
+ herdr_layout: "terminal",
38
+
39
+ read: "files",
40
+ write: "files",
41
+ edit: "files",
42
+ grep: "files",
43
+ find: "files",
44
+ ls: "files",
45
+
46
+ herdr_agent: "agents",
47
+
48
+ memory: "memory",
49
+ memory_store: "memory",
50
+ scratchpad: "memory",
51
+ session: "memory",
52
+
53
+ orchestrate: "orchestration",
54
+ timer: "orchestration",
55
+ };
56
+
57
+ /**
58
+ * The family of `tool`, or `null` when the tool is not declared. The own-property
59
+ * test is deliberate: an index lookup for a name like "toString" would otherwise
60
+ * return something off the prototype chain and read as a family.
61
+ */
62
+ export function familyOf(tool: string): ToolFamily | null {
63
+ return Object.prototype.hasOwnProperty.call(TOOL_FAMILIES, tool) ? TOOL_FAMILIES[tool] : null;
64
+ }
65
+
66
+ /** The part of a tool statistic this module reads. */
67
+ export interface ToolStatLike {
68
+ tool: string;
69
+ taskType: string;
70
+ attempts: number;
71
+ successes: number;
72
+ }
73
+
74
+ export interface Sample {
75
+ attempts: number;
76
+ successes: number;
77
+ }
78
+
79
+ export interface ToolFamilySuggestion {
80
+ /** The tool to switch to. Same family as `tool`. */
81
+ alternative: string;
82
+ /** Reliability of `tool` for `taskType`, in [0, 1]. */
83
+ current: number;
84
+ /** Reliability of `alternative` for the same task type, in [0, 1]. */
85
+ better: number;
86
+ /** The failing tool's own sample. */
87
+ sample: Sample;
88
+ /** The alternative's sample. */
89
+ alternatives: Sample;
90
+ /** The tool whose failure prompted this. */
91
+ tool: string;
92
+ family: ToolFamily;
93
+ taskType: string;
94
+ }
95
+
96
+ /** Both sides must carry at least this many attempts for the task type. */
97
+ export const MIN_ATTEMPTS = 5;
98
+
99
+ /**
100
+ * The alternative must beat the failing tool by this margin. Held as the fraction
101
+ * 1/5 so the decision runs on integer counts (see `meetsGap`) instead of the
102
+ * subtraction of two rounded ratios.
103
+ */
104
+ export const MIN_GAP = 0.2;
105
+
106
+ /**
107
+ * `alternative` beats `current` by at least `MIN_GAP`, decided exactly:
108
+ *
109
+ * alt.s/alt.a - cur.s/cur.a >= 1/5 <=> 5*(alt.s*cur.a - cur.s*alt.a) >= cur.a*alt.a
110
+ *
111
+ * The integer form matters because float subtraction puts a gap of exactly 0.2
112
+ * (3/5 vs 2/5) at 0.19999999999999996, which would refuse a comparison the stated
113
+ * rule allows.
114
+ */
115
+ function meetsGap(current: ToolStatLike, alternative: ToolStatLike): boolean {
116
+ const numerator =
117
+ alternative.successes * current.attempts - current.successes * alternative.attempts;
118
+ return numerator > 0 && 5 * numerator >= current.attempts * alternative.attempts;
119
+ }
120
+
121
+ /**
122
+ * The best substitute for `tool` on `taskType`, or `null` when there is none.
123
+ *
124
+ * Null whenever: the tool has no declared family; the tool's own sample for this
125
+ * task type is under `MIN_ATTEMPTS`; no same-family tool reaches `MIN_ATTEMPTS`
126
+ * on that task type; or no such tool clears `MIN_GAP`. Ties in reliability go to
127
+ * the lexicographically first tool name, so the same statistics always name the
128
+ * same alternative.
129
+ */
130
+ export function suggestAlternative(input: {
131
+ stats: Iterable<ToolStatLike>;
132
+ tool: string;
133
+ taskType: string;
134
+ }): ToolFamilySuggestion | null {
135
+ const family = familyOf(input.tool);
136
+ if (family === null) return null;
137
+
138
+ let current: ToolStatLike | null = null;
139
+ const candidates: ToolStatLike[] = [];
140
+ for (const stat of input.stats) {
141
+ if (!stat || stat.taskType !== input.taskType) continue;
142
+ if (stat.tool === input.tool) {
143
+ if (current === null) current = stat;
144
+ continue;
145
+ }
146
+ if (familyOf(stat.tool) === family) candidates.push(stat);
147
+ }
148
+ if (current === null || current.attempts < MIN_ATTEMPTS) return null;
149
+ const failing = current;
150
+
151
+ const qualified = candidates.filter(
152
+ (candidate) => candidate.attempts >= MIN_ATTEMPTS && meetsGap(failing, candidate),
153
+ );
154
+ if (qualified.length === 0) return null;
155
+
156
+ qualified.sort((a, b) => {
157
+ // Descending reliability by cross-multiplication; then by name for stability.
158
+ const byRate = b.successes * a.attempts - a.successes * b.attempts;
159
+ if (byRate !== 0) return byRate;
160
+ return a.tool < b.tool ? -1 : a.tool > b.tool ? 1 : 0;
161
+ });
162
+
163
+ const best = qualified[0];
164
+ return {
165
+ alternative: best.tool,
166
+ current: failing.successes / failing.attempts,
167
+ better: best.successes / best.attempts,
168
+ sample: { attempts: failing.attempts, successes: failing.successes },
169
+ alternatives: { attempts: best.attempts, successes: best.successes },
170
+ tool: input.tool,
171
+ family,
172
+ taskType: input.taskType,
173
+ };
174
+ }
175
+
176
+ /**
177
+ * The sentence a reader receives. Both samples are on the line: a percentage
178
+ * without its counts is what made the old hint unreadable, and a reader must be
179
+ * able to watch the sample decide the claim. `taskType` is named because it is
180
+ * what the counts are grouped by; the family is named because it is what makes
181
+ * the comparison admissible in the first place.
182
+ */
183
+ export function formatSuggestion(suggestion: ToolFamilySuggestion): string {
184
+ const better = suggestion.alternatives;
185
+ const current = suggestion.sample;
186
+ return (
187
+ `${suggestion.alternative} succeeded ${better.successes} of ${better.attempts} on ` +
188
+ `"${suggestion.taskType}" where ${suggestion.tool} succeeded ${current.successes} of ` +
189
+ `${current.attempts} (same tool family: ${suggestion.family})`
190
+ );
191
+ }
192
+
193
+ /**
194
+ * One hint per family per this many turns.
195
+ *
196
+ * The statistics are cumulative for the session, so between two turns the sample
197
+ * grows while the direction of the claim does not change: a second copy of the
198
+ * same advice carries no fact the first lacked, and a reader who sees it every
199
+ * turn learns to filter the family out. Ten turns is long enough for a reader to
200
+ * act (switching tools shows up as new attempts on both sides) and short enough
201
+ * that a session which ignored the hint still sees it once more before it ends.
202
+ */
203
+ export const HINT_COOLDOWN_TURNS = 10;
204
+
205
+ /** Per-session hint limiter. Hold it in session state, never at module scope. */
206
+ export interface FamilyHintGate {
207
+ /** Turns completed in this session. */
208
+ turn: number;
209
+ /** Turn of the last emitted hint, per family. */
210
+ lastHintTurn: Partial<Record<ToolFamily, number>>;
211
+ }
212
+
213
+ export function createFamilyHintGate(): FamilyHintGate {
214
+ return { turn: 0, lastHintTurn: {} };
215
+ }
216
+
217
+ /** Advance the session's turn clock by one completed turn. */
218
+ export function noteTurn(gate: FamilyHintGate): void {
219
+ gate.turn += 1;
220
+ }
221
+
222
+ /**
223
+ * Claim the right to emit one hint for `family`. Returns `false` while the family
224
+ * is still inside its cooldown; a `true` return records the hint at the current
225
+ * turn, so the caller must emit when it gets one.
226
+ */
227
+ export function allowFamilyHint(gate: FamilyHintGate, family: ToolFamily): boolean {
228
+ const last = gate.lastHintTurn[family];
229
+ if (last !== undefined && gate.turn - last < HINT_COOLDOWN_TURNS) return false;
230
+ gate.lastHintTurn[family] = gate.turn;
231
+ return true;
232
+ }