pi-braid 0.43.41 → 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/index.d.ts +0 -2
- package/dist/index.js +0 -2
- 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/src/extensions/heartbeat/analytics/AGENTS.md +2 -2
- package/src/extensions/heartbeat/analytics/index.ts +50 -19
- package/src/index.ts +0 -2
- 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
|
}
|
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";
|
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>;
|
package/dist/loader/api.js
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 { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
|
|
27
24
|
import { Container, SettingsList, } from "@earendil-works/pi-tui";
|
|
@@ -39,6 +36,8 @@ const VERBS = {
|
|
|
39
36
|
};
|
|
40
37
|
const USAGE = "Usage: /modules [on|off|toggle|reset|all|list] <ref>\n" +
|
|
41
38
|
"A ref is an extension id or a module group name. Tab completes both.";
|
|
39
|
+
/** Why a contrib extension is absent from this list, stated where it shows. */
|
|
40
|
+
const CONTRIB_NOTE = "Contrib extensions are toggled through braid.contrib in settings, not from this list.";
|
|
42
41
|
export default async function modulesApiExtension(pi) {
|
|
43
42
|
const run = async (argv, ctx) => {
|
|
44
43
|
const notify = (message, type = "info") => {
|
|
@@ -132,34 +131,7 @@ export default async function modulesApiExtension(pi) {
|
|
|
132
131
|
getArgumentCompletions: completeModules,
|
|
133
132
|
handler: (args, ctx) => run(splitArgs(args), ctx),
|
|
134
133
|
});
|
|
135
|
-
|
|
136
|
-
description: "Alias of /modules on <ref>. Retained for one release.",
|
|
137
|
-
getArgumentCompletions: completeRefs("on"),
|
|
138
|
-
handler: (args, ctx) => run([...forwarded("on", args)], ctx),
|
|
139
|
-
});
|
|
140
|
-
pi.registerCommand("modules-disable", {
|
|
141
|
-
description: "Alias of /modules off <ref>. Retained for one release.",
|
|
142
|
-
getArgumentCompletions: completeRefs("off"),
|
|
143
|
-
handler: (args, ctx) => run([...forwarded("off", args)], ctx),
|
|
144
|
-
});
|
|
145
|
-
pi.registerCommand("modules-toggle", {
|
|
146
|
-
description: "Alias of /modules toggle <ref>. Retained for one release.",
|
|
147
|
-
getArgumentCompletions: completeRefs("toggle"),
|
|
148
|
-
handler: (args, ctx) => run([...forwarded("toggle", args)], ctx),
|
|
149
|
-
});
|
|
150
|
-
pi.registerCommand("modules-reset", {
|
|
151
|
-
description: "Alias of /modules reset. Retained for one release.",
|
|
152
|
-
handler: async (_args, ctx) => run(["reset"], ctx),
|
|
153
|
-
});
|
|
154
|
-
pi.registerCommand("modules-list", {
|
|
155
|
-
description: "Alias of /modules list. Retained for one release.",
|
|
156
|
-
handler: async (_args, ctx) => run(["list"], ctx),
|
|
157
|
-
});
|
|
158
|
-
pi.registerCommand("modules-status", {
|
|
159
|
-
description: "Alias of /modules list. Retained for one release.",
|
|
160
|
-
handler: async (_args, ctx) => run(["list"], ctx),
|
|
161
|
-
});
|
|
162
|
-
log.info("Module API registered: /modules (+ six forwarding aliases)");
|
|
134
|
+
log.info("Module API registered: /modules");
|
|
163
135
|
}
|
|
164
136
|
// ── Argument parsing ────────────────────────────────────────────────────────
|
|
165
137
|
/** Split a command's argument string into argv; quoted runs stay one token. */
|
|
@@ -175,10 +147,6 @@ function splitArgs(args) {
|
|
|
175
147
|
}
|
|
176
148
|
return argv;
|
|
177
149
|
}
|
|
178
|
-
/** The argv an old name forwards: its whole argument is the ref. */
|
|
179
|
-
function forwarded(verb, args) {
|
|
180
|
-
return [verb, (args ?? "").trim()];
|
|
181
|
-
}
|
|
182
150
|
/** Why a reference was refused, naming the rule instead of listing refs. */
|
|
183
151
|
function refusal(ref, verb) {
|
|
184
152
|
if (!getModuleRefs().includes(ref)) {
|
|
@@ -212,15 +180,6 @@ function completeModules(prefix) {
|
|
|
212
180
|
}
|
|
213
181
|
return null;
|
|
214
182
|
}
|
|
215
|
-
/** Completion for an old name: the whole argument text is the reference. */
|
|
216
|
-
function completeRefs(verb) {
|
|
217
|
-
return (prefix) => {
|
|
218
|
-
const typed = (prefix ?? "").toLowerCase();
|
|
219
|
-
return getModuleRefs()
|
|
220
|
-
.filter((ref) => ref.startsWith(typed))
|
|
221
|
-
.map((ref) => ({ value: ref, label: ref, description: `Forwarded to /modules ${verb}` }));
|
|
222
|
-
};
|
|
223
|
-
}
|
|
224
183
|
function completeValues(prefix, values) {
|
|
225
184
|
const typed = (prefix ?? "").toLowerCase();
|
|
226
185
|
return values
|
|
@@ -248,7 +207,7 @@ function describe(desc, origin, enabled, loaded) {
|
|
|
248
207
|
/** The rows as text, for RPC mode and the `list` verb. */
|
|
249
208
|
function renderRows() {
|
|
250
209
|
const { rows, source } = moduleRows();
|
|
251
|
-
const lines = [`Extensions (${rows.length}, config: ${source})
|
|
210
|
+
const lines = [`Extensions (${rows.length}, config: ${source}):`, CONTRIB_NOTE];
|
|
252
211
|
const width = Math.min(28, Math.max(...rows.map((row) => row.id.length)));
|
|
253
212
|
for (const row of rows) {
|
|
254
213
|
lines.push(` ${row.value.padEnd(3)} ${row.id.padEnd(width)} ${row.description}`);
|
|
@@ -266,7 +225,7 @@ async function openModuleList(ctx) {
|
|
|
266
225
|
const container = new Container();
|
|
267
226
|
container.addChild(new (class {
|
|
268
227
|
render(_width) {
|
|
269
|
-
return [theme.fg("accent", theme.bold("Extensions"))];
|
|
228
|
+
return [theme.fg("accent", theme.bold("Extensions")), theme.fg("muted", CONTRIB_NOTE)];
|
|
270
229
|
}
|
|
271
230
|
invalidate() { }
|
|
272
231
|
})());
|
package/dist/loader/loader.d.ts
CHANGED
|
@@ -96,6 +96,4 @@ export declare function getModuleStates(_ctx?: ExtensionContext): Record<string,
|
|
|
96
96
|
export declare function resetModuleOverrides(_ctx?: ExtensionContext): void;
|
|
97
97
|
/** Get all valid config reference names for API completion/docs. */
|
|
98
98
|
export declare function getModuleRefs(): string[];
|
|
99
|
-
/** @deprecated Use getModuleRefs. Kept as an alias for existing callers. */
|
|
100
|
-
export declare function getAllRefNames(): string[];
|
|
101
99
|
//# sourceMappingURL=loader.d.ts.map
|
package/dist/loader/loader.js
CHANGED
|
@@ -571,8 +571,4 @@ function topologicalSort(extIds) {
|
|
|
571
571
|
export function getModuleRefs() {
|
|
572
572
|
return allConfigRefs();
|
|
573
573
|
}
|
|
574
|
-
/** @deprecated Use getModuleRefs. Kept as an alias for existing callers. */
|
|
575
|
-
export function getAllRefNames() {
|
|
576
|
-
return getModuleRefs();
|
|
577
|
-
}
|
|
578
574
|
//# sourceMappingURL=loader.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 -
|
|
141
|
+
file uses - 117 of the core suite's 353 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
|
@@ -397,7 +397,7 @@ braid's loader follows a four-tier precedence (high → low):
|
|
|
397
397
|
| `/modules list` | Print every extension, its description and where its state came from |
|
|
398
398
|
| `/modules reset` | Clear in-process overrides (persisted `braid.modules` stays) |
|
|
399
399
|
|
|
400
|
-
The
|
|
400
|
+
The list covers the core manifest only. A contrib extension has no entry here: it is toggled through its `braid.contrib.<name>` key in `~/.pi/agent/settings.json`.
|
|
401
401
|
|
|
402
402
|
### `BRAID_MODULES` syntax
|
|
403
403
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.42",
|
|
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",
|
|
@@ -30,8 +30,8 @@ and emits alerts on degradation/anomaly.
|
|
|
30
30
|
|
|
31
31
|
_(None - both `get_session_metrics` and `get_tool_reliability` removed in <!-- doc-ref-exempt: removed tool named as history -->
|
|
32
32
|
2026-06 tool-inventory audit. They were passive observability with no
|
|
33
|
-
internal consumers. Background tracking and the
|
|
34
|
-
|
|
33
|
+
internal consumers. Background tracking and the `/analytics all` scope
|
|
34
|
+
remain.)_
|
|
35
35
|
|
|
36
36
|
## Event-bus contract
|
|
37
37
|
|
|
@@ -17,7 +17,7 @@ import {
|
|
|
17
17
|
} from "../../../lib/state/session-start-queue.js";
|
|
18
18
|
import { existsSync, mkdirSync } from "node:fs";
|
|
19
19
|
import { metricsDir, metricsFilePath } from "../../../lib/config/braid-paths.js";
|
|
20
|
-
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
20
|
+
import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
|
|
21
21
|
import { safeSessionManagerTyped } from "../../../lib/state/extension-state.js";
|
|
22
22
|
import { emitSignal } from "../../../lib/reasoning/belief-policy-engine.js";
|
|
23
23
|
import { eventBus } from "../../../lib/events/event-bus.js";
|
|
@@ -53,6 +53,40 @@ import {
|
|
|
53
53
|
|
|
54
54
|
const log = createLogger("analytics");
|
|
55
55
|
|
|
56
|
+
/** The three reports one command prints, keyed by the verb a script types. */
|
|
57
|
+
const ANALYTICS_SCOPES: Record<
|
|
58
|
+
string,
|
|
59
|
+
{ label: string; render: (ctx: ExtensionCommandContext) => string }
|
|
60
|
+
> = {
|
|
61
|
+
session: {
|
|
62
|
+
label: "This session",
|
|
63
|
+
render: (ctx) => formatCurrentSession(getAnalyticsStateInternal(ctx)),
|
|
64
|
+
},
|
|
65
|
+
all: { label: "All sessions", render: () => formatAllSessions() },
|
|
66
|
+
ab: { label: "A/B variants", render: () => formatABResults() },
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
/** Print one scope through the formatter that scope already owned. */
|
|
70
|
+
function showAnalyticsScope(scope: string, ctx: ExtensionCommandContext): void {
|
|
71
|
+
ctx.ui.notify(ANALYTICS_SCOPES[scope].render(ctx), "info");
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** No argument: ask the scope in the TUI; headless prints the default scope. */
|
|
75
|
+
async function pickAnalyticsScope(ctx: ExtensionCommandContext): Promise<void> {
|
|
76
|
+
if (ctx.mode !== "tui") {
|
|
77
|
+
ctx.ui.notify(
|
|
78
|
+
`${ANALYTICS_SCOPES.session.render(ctx)}\n\nOther scopes: /analytics all, /analytics ab`,
|
|
79
|
+
"info",
|
|
80
|
+
);
|
|
81
|
+
return;
|
|
82
|
+
}
|
|
83
|
+
const labels = Object.values(ANALYTICS_SCOPES).map((scope) => scope.label);
|
|
84
|
+
const chosen = await ctx.ui.select("Analytics scope", labels);
|
|
85
|
+
if (chosen === undefined) return;
|
|
86
|
+
const scope = Object.keys(ANALYTICS_SCOPES).find((key) => ANALYTICS_SCOPES[key].label === chosen);
|
|
87
|
+
if (scope) showAnalyticsScope(scope, ctx);
|
|
88
|
+
}
|
|
89
|
+
|
|
56
90
|
export default function analyticsExtension(pi: ExtensionAPI) {
|
|
57
91
|
registerSessionStartHandler(pi, SessionPhase.MemoryState, async (_event, ctx) => {
|
|
58
92
|
resetCriticStats();
|
|
@@ -344,30 +378,27 @@ export default function analyticsExtension(pi: ExtensionAPI) {
|
|
|
344
378
|
});
|
|
345
379
|
|
|
346
380
|
pi.registerCommand("analytics", {
|
|
347
|
-
description:
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
description: "Show A/B experiment results across variants",
|
|
362
|
-
handler: async (_args, ctx) => {
|
|
363
|
-
ctx.ui.notify(formatABResults(), "info");
|
|
381
|
+
description:
|
|
382
|
+
"Show tool analytics. No argument asks the scope in the TUI. " +
|
|
383
|
+
"Usage: /analytics [session|all|ab]",
|
|
384
|
+
handler: async (args, ctx) => {
|
|
385
|
+
const scope = (args ?? "").trim().toLowerCase();
|
|
386
|
+
if (scope === "") {
|
|
387
|
+
await pickAnalyticsScope(ctx);
|
|
388
|
+
return;
|
|
389
|
+
}
|
|
390
|
+
if (!(scope in ANALYTICS_SCOPES)) {
|
|
391
|
+
ctx.ui.notify(`Unknown scope "${scope}". Usage: /analytics [session|all|ab]`, "warning");
|
|
392
|
+
return;
|
|
393
|
+
}
|
|
394
|
+
showAnalyticsScope(scope, ctx);
|
|
364
395
|
},
|
|
365
396
|
});
|
|
366
397
|
|
|
367
398
|
// No agent-callable observability tools here (session metrics / tool
|
|
368
399
|
// reliability): the agent rarely needs self-observability and no internal
|
|
369
400
|
// caller used them. Background tracking (toolMetrics, sessionStartTime)
|
|
370
|
-
// still runs and feeds event-bus alerts and the analytics
|
|
401
|
+
// still runs and feeds event-bus alerts and the analytics scopes; the
|
|
371
402
|
// A/B variant is set programmatically via
|
|
372
403
|
// getAnalyticsStateInternal(ctx).abVariant.
|
|
373
404
|
}
|
package/src/index.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
|
|
|
25
23
|
import { readFileSync } from "node:fs";
|
package/src/loader/AGENTS.md
CHANGED
|
@@ -12,10 +12,10 @@ that it contains the **loader** (and the related subagent API), not
|
|
|
12
12
|
|
|
13
13
|
## Files
|
|
14
14
|
|
|
15
|
-
| File | Purpose
|
|
16
|
-
| ----------- |
|
|
17
|
-
| `loader.ts` | Resolves `BRAID_MODULES` / `braid.modules` (pi global, pi project, braid's store) / runtime overrides into an enabled set, topologically sorts by dependency, and invokes each factory.
|
|
18
|
-
| `api.ts` | Registers `/modules` (verbs: `on`, `off`, `toggle`, `reset`, `all on
|
|
15
|
+
| File | Purpose |
|
|
16
|
+
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
17
|
+
| `loader.ts` | Resolves `BRAID_MODULES` / `braid.modules` (pi global, pi project, braid's store) / runtime overrides into an enabled set, topologically sorts by dependency, and invokes each factory. |
|
|
18
|
+
| `api.ts` | Registers `/modules` (verbs: `on`, `off`, `toggle`, `reset`, `all on` / `off`, `list`) for the subagent API, and states that a contrib extension is toggled through `braid.contrib`, not from this list. |
|
|
19
19
|
|
|
20
20
|
## Layer position
|
|
21
21
|
|
package/src/loader/api.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
|
|
|
27
24
|
import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
|
|
@@ -67,6 +64,10 @@ const USAGE =
|
|
|
67
64
|
"Usage: /modules [on|off|toggle|reset|all|list] <ref>\n" +
|
|
68
65
|
"A ref is an extension id or a module group name. Tab completes both.";
|
|
69
66
|
|
|
67
|
+
/** Why a contrib extension is absent from this list, stated where it shows. */
|
|
68
|
+
const CONTRIB_NOTE =
|
|
69
|
+
"Contrib extensions are toggled through braid.contrib in settings, not from this list.";
|
|
70
|
+
|
|
70
71
|
export default async function modulesApiExtension(pi: ExtensionAPI): Promise<void> {
|
|
71
72
|
const run = async (argv: string[], ctx: ExtensionCommandContext): Promise<void> => {
|
|
72
73
|
const notify = (message: string, type: "info" | "warning" | "error" = "info"): void => {
|
|
@@ -168,35 +169,7 @@ export default async function modulesApiExtension(pi: ExtensionAPI): Promise<voi
|
|
|
168
169
|
handler: (args, ctx) => run(splitArgs(args), ctx),
|
|
169
170
|
});
|
|
170
171
|
|
|
171
|
-
|
|
172
|
-
description: "Alias of /modules on <ref>. Retained for one release.",
|
|
173
|
-
getArgumentCompletions: completeRefs("on"),
|
|
174
|
-
handler: (args, ctx) => run([...forwarded("on", args)], ctx),
|
|
175
|
-
});
|
|
176
|
-
pi.registerCommand("modules-disable", {
|
|
177
|
-
description: "Alias of /modules off <ref>. Retained for one release.",
|
|
178
|
-
getArgumentCompletions: completeRefs("off"),
|
|
179
|
-
handler: (args, ctx) => run([...forwarded("off", args)], ctx),
|
|
180
|
-
});
|
|
181
|
-
pi.registerCommand("modules-toggle", {
|
|
182
|
-
description: "Alias of /modules toggle <ref>. Retained for one release.",
|
|
183
|
-
getArgumentCompletions: completeRefs("toggle"),
|
|
184
|
-
handler: (args, ctx) => run([...forwarded("toggle", args)], ctx),
|
|
185
|
-
});
|
|
186
|
-
pi.registerCommand("modules-reset", {
|
|
187
|
-
description: "Alias of /modules reset. Retained for one release.",
|
|
188
|
-
handler: async (_args, ctx) => run(["reset"], ctx),
|
|
189
|
-
});
|
|
190
|
-
pi.registerCommand("modules-list", {
|
|
191
|
-
description: "Alias of /modules list. Retained for one release.",
|
|
192
|
-
handler: async (_args, ctx) => run(["list"], ctx),
|
|
193
|
-
});
|
|
194
|
-
pi.registerCommand("modules-status", {
|
|
195
|
-
description: "Alias of /modules list. Retained for one release.",
|
|
196
|
-
handler: async (_args, ctx) => run(["list"], ctx),
|
|
197
|
-
});
|
|
198
|
-
|
|
199
|
-
log.info("Module API registered: /modules (+ six forwarding aliases)");
|
|
172
|
+
log.info("Module API registered: /modules");
|
|
200
173
|
}
|
|
201
174
|
|
|
202
175
|
// ── Argument parsing ────────────────────────────────────────────────────────
|
|
@@ -214,11 +187,6 @@ function splitArgs(args: string | undefined): string[] {
|
|
|
214
187
|
return argv;
|
|
215
188
|
}
|
|
216
189
|
|
|
217
|
-
/** The argv an old name forwards: its whole argument is the ref. */
|
|
218
|
-
function forwarded(verb: string, args: string | undefined): string[] {
|
|
219
|
-
return [verb, (args ?? "").trim()];
|
|
220
|
-
}
|
|
221
|
-
|
|
222
190
|
/** Why a reference was refused, naming the rule instead of listing refs. */
|
|
223
191
|
function refusal(ref: string, verb: string): string {
|
|
224
192
|
if (!getModuleRefs().includes(ref)) {
|
|
@@ -255,16 +223,6 @@ function completeModules(prefix: string): AutocompleteItem[] | null {
|
|
|
255
223
|
return null;
|
|
256
224
|
}
|
|
257
225
|
|
|
258
|
-
/** Completion for an old name: the whole argument text is the reference. */
|
|
259
|
-
function completeRefs(verb: string) {
|
|
260
|
-
return (prefix: string): AutocompleteItem[] | null => {
|
|
261
|
-
const typed = (prefix ?? "").toLowerCase();
|
|
262
|
-
return getModuleRefs()
|
|
263
|
-
.filter((ref) => ref.startsWith(typed))
|
|
264
|
-
.map((ref) => ({ value: ref, label: ref, description: `Forwarded to /modules ${verb}` }));
|
|
265
|
-
};
|
|
266
|
-
}
|
|
267
|
-
|
|
268
226
|
function completeValues(prefix: string, values: string[]): AutocompleteItem[] {
|
|
269
227
|
const typed = (prefix ?? "").toLowerCase();
|
|
270
228
|
return values
|
|
@@ -296,7 +254,7 @@ function describe(desc: string, origin: ModuleOrigin, enabled: boolean, loaded:
|
|
|
296
254
|
/** The rows as text, for RPC mode and the `list` verb. */
|
|
297
255
|
function renderRows(): string {
|
|
298
256
|
const { rows, source } = moduleRows();
|
|
299
|
-
const lines = [`Extensions (${rows.length}, config: ${source})
|
|
257
|
+
const lines = [`Extensions (${rows.length}, config: ${source}):`, CONTRIB_NOTE];
|
|
300
258
|
const width = Math.min(28, Math.max(...rows.map((row) => row.id.length)));
|
|
301
259
|
for (const row of rows) {
|
|
302
260
|
lines.push(` ${row.value.padEnd(3)} ${row.id.padEnd(width)} ${row.description}`);
|
|
@@ -319,7 +277,7 @@ async function openModuleList(ctx: ExtensionCommandContext): Promise<void> {
|
|
|
319
277
|
container.addChild(
|
|
320
278
|
new (class {
|
|
321
279
|
render(_width: number) {
|
|
322
|
-
return [theme.fg("accent", theme.bold("Extensions"))];
|
|
280
|
+
return [theme.fg("accent", theme.bold("Extensions")), theme.fg("muted", CONTRIB_NOTE)];
|
|
323
281
|
}
|
|
324
282
|
invalidate() {}
|
|
325
283
|
})(),
|
package/src/loader/loader.ts
CHANGED
|
@@ -656,8 +656,3 @@ function topologicalSort(extIds: string[]): string[] {
|
|
|
656
656
|
export function getModuleRefs(): string[] {
|
|
657
657
|
return allConfigRefs();
|
|
658
658
|
}
|
|
659
|
-
|
|
660
|
-
/** @deprecated Use getModuleRefs. Kept as an alias for existing callers. */
|
|
661
|
-
export function getAllRefNames(): string[] {
|
|
662
|
-
return getModuleRefs();
|
|
663
|
-
}
|