pi-braid 0.43.40 → 0.43.42
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 +19 -0
- package/CONTRIBUTING.md +1 -1
- package/TOOLS.md +10 -15
- package/build-info.json +4 -4
- package/dist/extensions/heartbeat/analytics/index.js +41 -18
- package/dist/extensions/memory/three-memory-stores/index.js +34 -38
- package/dist/index.d.ts +0 -2
- package/dist/index.js +0 -2
- package/dist/lib/tools/tool-families.d.ts +119 -0
- package/dist/lib/tools/tool-families.js +172 -0
- package/dist/loader/api.d.ts +2 -5
- package/dist/loader/api.js +7 -48
- package/dist/loader/loader.d.ts +0 -2
- package/dist/loader/loader.js +0 -4
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -1
- package/package.json +1 -1
- package/skills/release-pipeline/SKILL.md +12 -0
- package/src/extensions/heartbeat/analytics/AGENTS.md +2 -2
- package/src/extensions/heartbeat/analytics/index.ts +50 -19
- package/src/extensions/memory/AGENTS.md +1 -2
- package/src/extensions/memory/three-memory-stores/index.ts +43 -41
- package/src/index.ts +0 -2
- package/src/lib/AGENTS.md +1 -0
- package/src/lib/tools/tool-families.ts +232 -0
- package/src/loader/AGENTS.md +4 -4
- package/src/loader/api.ts +9 -51
- package/src/loader/loader.ts +0 -5
package/CHANGELOG.md
CHANGED
|
@@ -96,6 +96,25 @@ record; the tag scheme above applies unchanged.
|
|
|
96
96
|
note that a clean disable releases it, because a refusal an operator cannot act on
|
|
97
97
|
is a support ticket.
|
|
98
98
|
|
|
99
|
+
## Core — 0.43.42 (2026-11-10: ten commands, one per object)
|
|
100
|
+
|
|
101
|
+
- **The six `/modules-*` names are gone.** They forwarded to `/modules` for three releases (0.43.39 to
|
|
102
|
+
0.43.41) and are now deleted, so one object answers to one name. `/modules` keeps its verbs (`on`, `off`,
|
|
103
|
+
`toggle`, `reset`, `all on|off`, `list`) and its text form in RPC mode; its header now says that a contrib
|
|
104
|
+
extension is toggled through `braid.contrib` in settings, because this list reads the core manifest only.
|
|
105
|
+
- **`/browser` replaces `browser-start`, `browser-connect`, `browser-disconnect` and `browser-tabs`.** No
|
|
106
|
+
argument opens one manager: the endpoint, the connection and the active tab as facts, then an action list
|
|
107
|
+
for connect, start, start with a profile, disconnect and the tabs. A headless caller gets the same facts as
|
|
108
|
+
text and never a component. With `braid.contrib.browserAdvanced` off the tab rows are absent by
|
|
109
|
+
configuration, and the manager says that and names the setting instead of leaving the reader to guess.
|
|
110
|
+
- **`/analytics` replaces `analytics`, `analytics:all` and `analytics:ab`.** No argument asks the scope (this
|
|
111
|
+
session, all sessions, A-B) and prints the same block as before; `session`, `all` and `ab` are the verbs a
|
|
112
|
+
script uses. Headless prints the session scope and names the two other verbs.
|
|
113
|
+
- **`/tools status` replaces `tool-status`**, printing exactly the line the old command printed; the
|
|
114
|
+
no-argument `/tools` list is unchanged.
|
|
115
|
+
- **The registered set is 22 names → 10**, and the four objects the inventory found carrying more than one
|
|
116
|
+
command (modules 7, browser 4, analytics 3, tools 2) carry one each.
|
|
117
|
+
|
|
99
118
|
## Core — 0.43.39 (2026-11-09: one command per object, and a menu bar for the services)
|
|
100
119
|
|
|
101
120
|
- **`/modules` replaces six commands.** A registry that offered `modules-list`, `-enable`, `-disable`,
|
package/CONTRIBUTING.md
CHANGED
|
@@ -207,7 +207,7 @@ Extensions are registered in the flat manifest at [`src/extensions/manifest.ts`]
|
|
|
207
207
|
|
|
208
208
|
Config resolution order (highest priority first):
|
|
209
209
|
|
|
210
|
-
1. Runtime subagent API (`/modules on`, `/modules off`, `/modules toggle`).
|
|
210
|
+
1. Runtime subagent API (`/modules on`, `/modules off`, `/modules toggle`). It covers the core manifest; a contrib extension is toggled through `braid.contrib.<name>` in settings.
|
|
211
211
|
2. `~/.pi/agent/settings.json` → `braid.modules`
|
|
212
212
|
3. `BRAID_MODULES` env var
|
|
213
213
|
4. Defaults (all non-opt-in extensions enabled)
|
package/TOOLS.md
CHANGED
|
@@ -35,7 +35,7 @@ fails until the other catches up.
|
|
|
35
35
|
## Enablement reference
|
|
36
36
|
|
|
37
37
|
Braid extension loading is resolved by `src/loader/loader.ts` (`resolveEnabledExtensions`, loader.ts:327)
|
|
38
|
-
with priority: runtime overrides (`/modules
|
|
38
|
+
with priority: runtime overrides (`/modules on|off`) → `braid.modules` from two sources, the later
|
|
39
39
|
winning per id (`~/.pi/agent/settings.json`, then braid's own module-overrides store where those
|
|
40
40
|
toggles persist) → `BRAID_MODULES` env var → manifest defaults (`src/extensions/manifest.ts`). Always-on extensions (`alwaysOn: true`)
|
|
41
41
|
can never be disabled; opt-in extensions (`disabledByDefault: true`) only load when explicitly enabled.
|
|
@@ -87,20 +87,15 @@ enablement (see appendix).
|
|
|
87
87
|
Extension commands the tool catalog does not cover: slash commands registered by
|
|
88
88
|
the core and contrib extensions and named in no other document. A command with
|
|
89
89
|
a home beside its extension is not repeated here - `/watchdog-status` lives in
|
|
90
|
-
the watchdog `AGENTS.md`,
|
|
91
|
-
|
|
92
|
-
| Command
|
|
93
|
-
|
|
|
94
|
-
| `/analytics`
|
|
95
|
-
| `/
|
|
96
|
-
| `/
|
|
97
|
-
| `/
|
|
98
|
-
| `/
|
|
99
|
-
| `/tool-status` | tool-config (contrib) | Show current tool configuration. |
|
|
100
|
-
| `/browser-start` | browser (contrib) | Spawn Chrome with remote debugging; `--profile` syncs cookies and logins. |
|
|
101
|
-
| `/browser-connect` | browser (contrib) | Connect to Chrome at :9222 (auto-starts if not running). |
|
|
102
|
-
| `/browser-disconnect` | browser (contrib) | Disconnect from the browser session. |
|
|
103
|
-
| `/utility-model` | polyfill (core) | Set or show the utility model for classification tasks; accepts one model or an ordered list (comma-separated), tried in order until the provider layer reports a route usable. |
|
|
90
|
+
the watchdog `AGENTS.md`, `/modules` in `SETUP.md`.
|
|
91
|
+
|
|
92
|
+
| Command | Registered by | What it does |
|
|
93
|
+
| ---------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
94
|
+
| `/analytics` | analytics (heartbeat module) | Show tool analytics. No argument asks the scope in the TUI; `session`, `all` and `ab` are the verbs. |
|
|
95
|
+
| `/browser` | browser (contrib) | One manager for Chrome: `connect`, `start [--profile]`, `disconnect`, `tabs`. No argument shows the endpoint, the connection state, the active tab and the actions. |
|
|
96
|
+
| `/context-stats` | context-manager (memory module) | Show context pruning statistics. |
|
|
97
|
+
| `/rate-cancel` | rate-limiter (contrib) | Cancel the rate limiter wait and reset its state. |
|
|
98
|
+
| `/utility-model` | polyfill (core) | Set or show the utility model for classification tasks; accepts one model or an ordered list (comma-separated), tried in order until the provider layer reports a route usable. |
|
|
104
99
|
|
|
105
100
|
## Appendix: standalone packages surfaced into the braid prompt
|
|
106
101
|
|
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.42",
|
|
4
|
+
"sha": "6f85454d78c4888c12976a2e363fbcbde6708e26",
|
|
5
|
+
"shaShort": "6f85454d",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-11-
|
|
8
|
+
"packedAt": "2026-11-10T08:50:03.400Z"
|
|
9
9
|
}
|
|
@@ -37,6 +37,33 @@ import { recordToolCall, flushAnalytics } from "./core.js";
|
|
|
37
37
|
import { formatCurrentSession, formatAllSessions } from "./format.js";
|
|
38
38
|
import { TURN_END, TOOL_EXECUTION_START, TOOL_EXECUTION_END, SESSION_SHUTDOWN, } from "../../../lib/core/event-names.js";
|
|
39
39
|
const log = createLogger("analytics");
|
|
40
|
+
/** The three reports one command prints, keyed by the verb a script types. */
|
|
41
|
+
const ANALYTICS_SCOPES = {
|
|
42
|
+
session: {
|
|
43
|
+
label: "This session",
|
|
44
|
+
render: (ctx) => formatCurrentSession(getAnalyticsStateInternal(ctx)),
|
|
45
|
+
},
|
|
46
|
+
all: { label: "All sessions", render: () => formatAllSessions() },
|
|
47
|
+
ab: { label: "A/B variants", render: () => formatABResults() },
|
|
48
|
+
};
|
|
49
|
+
/** Print one scope through the formatter that scope already owned. */
|
|
50
|
+
function showAnalyticsScope(scope, ctx) {
|
|
51
|
+
ctx.ui.notify(ANALYTICS_SCOPES[scope].render(ctx), "info");
|
|
52
|
+
}
|
|
53
|
+
/** No argument: ask the scope in the TUI; headless prints the default scope. */
|
|
54
|
+
async function pickAnalyticsScope(ctx) {
|
|
55
|
+
if (ctx.mode !== "tui") {
|
|
56
|
+
ctx.ui.notify(`${ANALYTICS_SCOPES.session.render(ctx)}\n\nOther scopes: /analytics all, /analytics ab`, "info");
|
|
57
|
+
return;
|
|
58
|
+
}
|
|
59
|
+
const labels = Object.values(ANALYTICS_SCOPES).map((scope) => scope.label);
|
|
60
|
+
const chosen = await ctx.ui.select("Analytics scope", labels);
|
|
61
|
+
if (chosen === undefined)
|
|
62
|
+
return;
|
|
63
|
+
const scope = Object.keys(ANALYTICS_SCOPES).find((key) => ANALYTICS_SCOPES[key].label === chosen);
|
|
64
|
+
if (scope)
|
|
65
|
+
showAnalyticsScope(scope, ctx);
|
|
66
|
+
}
|
|
40
67
|
export default function analyticsExtension(pi) {
|
|
41
68
|
registerSessionStartHandler(pi, SessionPhase.MemoryState, async (_event, ctx) => {
|
|
42
69
|
resetCriticStats();
|
|
@@ -323,29 +350,25 @@ export default function analyticsExtension(pi) {
|
|
|
323
350
|
flushAnalytics(state, false);
|
|
324
351
|
});
|
|
325
352
|
pi.registerCommand("analytics", {
|
|
326
|
-
description: "Show tool analytics
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
pi.registerCommand("analytics:ab", {
|
|
340
|
-
description: "Show A/B experiment results across variants",
|
|
341
|
-
handler: async (_args, ctx) => {
|
|
342
|
-
ctx.ui.notify(formatABResults(), "info");
|
|
353
|
+
description: "Show tool analytics. No argument asks the scope in the TUI. " +
|
|
354
|
+
"Usage: /analytics [session|all|ab]",
|
|
355
|
+
handler: async (args, ctx) => {
|
|
356
|
+
const scope = (args ?? "").trim().toLowerCase();
|
|
357
|
+
if (scope === "") {
|
|
358
|
+
await pickAnalyticsScope(ctx);
|
|
359
|
+
return;
|
|
360
|
+
}
|
|
361
|
+
if (!(scope in ANALYTICS_SCOPES)) {
|
|
362
|
+
ctx.ui.notify(`Unknown scope "${scope}". Usage: /analytics [session|all|ab]`, "warning");
|
|
363
|
+
return;
|
|
364
|
+
}
|
|
365
|
+
showAnalyticsScope(scope, ctx);
|
|
343
366
|
},
|
|
344
367
|
});
|
|
345
368
|
// No agent-callable observability tools here (session metrics / tool
|
|
346
369
|
// reliability): the agent rarely needs self-observability and no internal
|
|
347
370
|
// caller used them. Background tracking (toolMetrics, sessionStartTime)
|
|
348
|
-
// still runs and feeds event-bus alerts and the analytics
|
|
371
|
+
// still runs and feeds event-bus alerts and the analytics scopes; the
|
|
349
372
|
// A/B variant is set programmatically via
|
|
350
373
|
// getAnalyticsStateInternal(ctx).abVariant.
|
|
351
374
|
}
|
|
@@ -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
|
|
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
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
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();
|
package/dist/index.d.ts
CHANGED
|
@@ -18,8 +18,6 @@
|
|
|
18
18
|
* Subagent API:
|
|
19
19
|
* Researcher subagents can call `/modules` (verbs: on, off, toggle, reset,
|
|
20
20
|
* all on|off, list) to control extension loading during benchmark experiments.
|
|
21
|
-
* The six former names (modules-enable, modules-disable, modules-toggle,
|
|
22
|
-
* modules-reset, modules-list, modules-status) forward to it for one release.
|
|
23
21
|
*/
|
|
24
22
|
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
25
23
|
export default function braidExtension(pi: ExtensionAPI): Promise<void>;
|
package/dist/index.js
CHANGED
|
@@ -18,8 +18,6 @@
|
|
|
18
18
|
* Subagent API:
|
|
19
19
|
* Researcher subagents can call `/modules` (verbs: on, off, toggle, reset,
|
|
20
20
|
* all on|off, list) to control extension loading during benchmark experiments.
|
|
21
|
-
* The six former names (modules-enable, modules-disable, modules-toggle,
|
|
22
|
-
* modules-reset, modules-list, modules-status) forward to it for one release.
|
|
23
21
|
*/
|
|
24
22
|
import { readFileSync } from "node:fs";
|
|
25
23
|
import { dirname, join } from "node:path";
|
|
@@ -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/dist/loader/api.d.ts
CHANGED
|
@@ -17,11 +17,8 @@
|
|
|
17
17
|
* alone; argument completion and `list` are the places that enumerate what is
|
|
18
18
|
* accepted.
|
|
19
19
|
*
|
|
20
|
-
* The
|
|
21
|
-
*
|
|
22
|
-
* modules-reset, modules-list, modules-status. Each maps its whole argument
|
|
23
|
-
* onto the equivalent argv, so a script written against the old names keeps
|
|
24
|
-
* working until it is pointed at `/modules`.
|
|
20
|
+
* The list covers the core manifest only: a contrib extension is toggled
|
|
21
|
+
* through its `braid.contrib.<name>` key in settings, not from this command.
|
|
25
22
|
*/
|
|
26
23
|
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
27
24
|
export default function modulesApiExtension(pi: ExtensionAPI): Promise<void>;
|