pi-braid 0.43.38 → 0.43.40

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.
@@ -1,114 +1,317 @@
1
1
  /**
2
- * Subagent API for module/toggle.
2
+ * Subagent API for extension toggling.
3
3
  *
4
- * Registers commands that a researcher subagent can call during benchmarks
5
- * to enable/disable extensions (or module groups) and query their state:
4
+ * One command, `/modules`, with a verb as its first argument:
6
5
  *
7
- * modules-enable <id> - Enable an extension or module group
8
- * modules-disable <id> - Disable an extension or module group
9
- * modules-toggle <id> - Toggle an extension or module group
10
- * modules-list - Show all extensions and their state
11
- * modules-status - Show current session extension state
12
- * modules-reset - Reset all runtime overrides
6
+ * /modules - TUI: open the extension list; RPC: print its rows as text
7
+ * /modules on <ref> - Enable an extension or module group
8
+ * /modules off <ref> - Disable an extension or module group
9
+ * /modules toggle <ref> - Flip the effective state
10
+ * /modules all on|off - Apply to every extension in the manifest
11
+ * /modules reset - Clear in-process overrides (persisted state stays)
12
+ * /modules list - Print the rows as text in every mode
13
13
  *
14
- * Reference targets can be individual extension IDs (e.g. "enforcement")
15
- * or module group names (e.g. "memory" expands to all memory extensions).
14
+ * Reference targets are extension IDs (e.g. "enforcement") or module group
15
+ * names (e.g. "memory", which expands to every extension in the group). A
16
+ * reference the resolver does not know is refused with the offending text
17
+ * alone; argument completion and `list` are the places that enumerate what is
18
+ * accepted.
19
+ *
20
+ * The six command names this file used to register remain as forwarding
21
+ * aliases for one release: modules-enable, modules-disable, modules-toggle,
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`.
16
25
  */
26
+ import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
27
+ import { Container, SettingsList, } from "@earendil-works/pi-tui";
17
28
  import { createLogger } from "../lib/core/logger.js";
18
- import { enableModule, disableModule, toggleModule, getModuleStates, resetModuleOverrides, getAllRefNames, } from "./loader.js";
29
+ import { getModuleStates, getModuleRefs, resetModuleOverrides, setModuleEnabled, toggleModule, } from "./loader.js";
19
30
  const log = createLogger("modules-api");
31
+ /** The verb table, shared by the handler's usage lines and completion. */
32
+ const VERBS = {
33
+ on: "Enable an extension or module group",
34
+ off: "Disable an extension or module group",
35
+ toggle: "Flip the effective state",
36
+ all: "Apply on or off to every extension",
37
+ reset: "Clear in-process overrides (persisted state stays)",
38
+ list: "Print every extension as text",
39
+ };
40
+ const USAGE = "Usage: /modules [on|off|toggle|reset|all|list] <ref>\n" +
41
+ "A ref is an extension id or a module group name. Tab completes both.";
20
42
  export default async function modulesApiExtension(pi) {
21
- // ── enable ──────────────────────────────────────────────────────────
22
- pi.registerCommand("modules-enable", {
23
- description: "Enable an extension or module group. Usage: modules-enable <id>",
24
- handler: async (_args, ctx) => {
25
- const name = _args.trim().toLowerCase();
26
- const refs = getAllRefNames();
27
- if (!name || !refs.includes(name)) {
28
- ctx.ui.notify?.(`Usage: modules-enable <id>\nAvailable: ${refs.join(", ")}`, "warning");
43
+ const run = async (argv, ctx) => {
44
+ const notify = (message, type = "info") => {
45
+ ctx.ui.notify?.(message, type);
46
+ };
47
+ const verb = (argv[0] ?? "").toLowerCase();
48
+ if (argv.length === 0) {
49
+ if (ctx.mode === "tui") {
50
+ await openModuleList(ctx);
51
+ }
52
+ else {
53
+ notify(renderRows(), "info");
54
+ }
55
+ return;
56
+ }
57
+ switch (verb) {
58
+ case "list": {
59
+ notify(renderRows(), "info");
29
60
  return;
30
61
  }
31
- const ok = enableModule(name, ctx);
32
- ctx.ui.notify?.(ok ? `"${name}" enabled (next session startup).` : `Cannot enable "${name}".`, ok ? "info" : "error");
33
- },
34
- });
35
- // ── disable ─────────────────────────────────────────────────────────
36
- pi.registerCommand("modules-disable", {
37
- description: "Disable an extension or module group. Usage: modules-disable <id>",
38
- handler: async (_args, ctx) => {
39
- const name = _args.trim().toLowerCase();
40
- if (!name) {
41
- ctx.ui.notify?.("Usage: modules-disable <id>", "warning");
62
+ case "on":
63
+ case "off": {
64
+ const ref = argv[1]?.trim().toLowerCase();
65
+ if (!ref) {
66
+ notify(`Usage: /modules ${verb} <ref>\n${USAGE}`, "warning");
67
+ return;
68
+ }
69
+ const on = verb === "on";
70
+ if (!setModuleEnabled(ref, on)) {
71
+ notify(refusal(ref, verb), "error");
72
+ return;
73
+ }
74
+ notify(`"${ref}" ${on ? "enabled" : "disabled"} (applies at the next start).`, "info");
42
75
  return;
43
76
  }
44
- const ok = disableModule(name, ctx);
45
- ctx.ui.notify?.(ok
46
- ? `"${name}" disabled (next session).`
47
- : `Cannot disable "${name}" - it may be a core extension.`, ok ? "info" : "error");
48
- },
49
- });
50
- // ── toggle ──────────────────────────────────────────────────────────
51
- pi.registerCommand("modules-toggle", {
52
- description: "Toggle an extension or module group. Usage: modules-toggle <id>",
53
- handler: async (_args, ctx) => {
54
- const name = _args.trim().toLowerCase();
55
- if (!name) {
56
- ctx.ui.notify?.("Usage: modules-toggle <id>", "warning");
77
+ case "toggle": {
78
+ const ref = argv[1]?.trim().toLowerCase();
79
+ if (!ref) {
80
+ notify(`Usage: /modules toggle <ref>\n${USAGE}`, "warning");
81
+ return;
82
+ }
83
+ const before = getModuleStates();
84
+ const state = toggleModule(ref, ctx);
85
+ if (state === null) {
86
+ notify(refusal(ref, "toggle"), "error");
87
+ return;
88
+ }
89
+ const after = getModuleStates();
90
+ const changed = Object.keys(after).some((id) => before[id].enabled !== after[id].enabled);
91
+ if (!changed) {
92
+ notify(`"${ref}" is always on and cannot be changed.`, "error");
93
+ return;
94
+ }
95
+ notify(`"${ref}" toggled ${state ? "ON" : "OFF"} (applies at the next start).`, "info");
96
+ return;
97
+ }
98
+ case "all": {
99
+ const mode = argv[1]?.trim().toLowerCase();
100
+ if (mode !== "on" && mode !== "off") {
101
+ notify("Usage: /modules all <on|off>", "warning");
102
+ return;
103
+ }
104
+ const on = mode === "on";
105
+ let applied = 0;
106
+ let refused = 0;
107
+ for (const id of Object.keys(getModuleStates())) {
108
+ if (setModuleEnabled(id, on))
109
+ applied++;
110
+ else
111
+ refused++;
112
+ }
113
+ notify(`"${on ? "on" : "off"}" applied to ${applied} extension(s)` +
114
+ (refused > 0
115
+ ? `; ${refused} always-on extension(s) cannot be disabled.`
116
+ : " (applies at the next start)."), refused > 0 ? "warning" : "info");
57
117
  return;
58
118
  }
59
- const state = toggleModule(name, ctx);
60
- if (state === null)
61
- ctx.ui.notify?.(`"${name}" not found.`, "error");
62
- else
63
- ctx.ui.notify?.(`"${name}" toggled ${state ? "ON" : "OFF"} (next session).`, "info");
64
- },
119
+ case "reset": {
120
+ resetModuleOverrides(ctx);
121
+ notify("Runtime overrides reset. Persisted braid.modules entries (if any) still apply.", "info");
122
+ return;
123
+ }
124
+ default: {
125
+ notify(`Unknown verb "${verb}".\n${USAGE}`, "warning");
126
+ }
127
+ }
128
+ };
129
+ pi.registerCommand("modules", {
130
+ description: "Enable or disable extensions. No argument opens the list (text in RPC mode). " +
131
+ "Usage: /modules on|off|toggle <ref>, /modules all on|off, /modules reset, /modules list",
132
+ getArgumentCompletions: completeModules,
133
+ handler: (args, ctx) => run(splitArgs(args), ctx),
134
+ });
135
+ pi.registerCommand("modules-enable", {
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),
65
153
  });
66
- // ── list ────────────────────────────────────────────────────────────
67
154
  pi.registerCommand("modules-list", {
68
- description: "List all extensions with state, load status, and config source.",
69
- handler: async (_args, ctx) => {
70
- const states = getModuleStates(ctx);
71
- const lines = [];
72
- const source = Object.values(states)[0]?.source ?? "?";
73
- lines.push(`Extensions (config: ${source}):`);
74
- for (const [id, info] of Object.entries(states)) {
75
- const status = info.enabled ? (info.loaded ? "●" : "○ pending") : "- disabled";
76
- lines.push(` ${status.padEnd(12)} ${id}`);
77
- lines.push(` ${info.desc}`);
78
- }
79
- lines.push("");
80
- lines.push("Toggle: /modules-toggle <id>");
81
- lines.push("Enable: /modules-enable <id> Disable: /modules-disable <id>");
82
- lines.push("Reset: /modules-reset");
83
- ctx.ui.notify?.(lines.join("\n"), "info");
84
- },
155
+ description: "Alias of /modules list. Retained for one release.",
156
+ handler: async (_args, ctx) => run(["list"], ctx),
85
157
  });
86
- // ── status ──────────────────────────────────────────────────────────
87
158
  pi.registerCommand("modules-status", {
88
- description: "Show current runtime overrides and load state.",
89
- handler: async (_args, ctx) => {
90
- const states = getModuleStates(ctx);
91
- const loaded = Object.values(states).filter((s) => s.loaded).length;
92
- const enabled = Object.values(states).filter((s) => s.enabled).length;
93
- const lines = [
94
- `Extensions: ${loaded} loaded, ${enabled} enabled` +
95
- ` (config: ${Object.values(states)[0]?.source ?? "?"})`,
96
- ];
97
- for (const [id, info] of Object.entries(states)) {
98
- const status = info.enabled ? (info.loaded ? "●" : "○ pending") : "- disabled";
99
- lines.push(` ${status.padEnd(12)} ${id}`);
100
- }
101
- ctx.ui.notify?.(lines.join("\n"), "info");
102
- },
159
+ description: "Alias of /modules list. Retained for one release.",
160
+ handler: async (_args, ctx) => run(["list"], ctx),
103
161
  });
104
- // ── reset ──────────────────────────────────────────────────────────
105
- pi.registerCommand("modules-reset", {
106
- description: "Reset all runtime overrides (restore defaults).",
107
- handler: async (_args, ctx) => {
108
- resetModuleOverrides(ctx);
109
- ctx.ui.notify?.("Runtime overrides reset. Persisted braid.modules entries (if any) still apply.", "info");
110
- },
162
+ log.info("Module API registered: /modules (+ six forwarding aliases)");
163
+ }
164
+ // ── Argument parsing ────────────────────────────────────────────────────────
165
+ /** Split a command's argument string into argv; quoted runs stay one token. */
166
+ function splitArgs(args) {
167
+ const text = (args ?? "").trim();
168
+ if (!text)
169
+ return [];
170
+ const argv = [];
171
+ const pattern = /"([^"]*)"|'([^']*)'|(\S+)/g;
172
+ let match;
173
+ while ((match = pattern.exec(text)) !== null) {
174
+ argv.push(match[1] ?? match[2] ?? match[3]);
175
+ }
176
+ return argv;
177
+ }
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
+ /** Why a reference was refused, naming the rule instead of listing refs. */
183
+ function refusal(ref, verb) {
184
+ if (!getModuleRefs().includes(ref)) {
185
+ return (`Unknown reference "${ref}". Tab completes extension ids and module groups; ` +
186
+ "/modules list shows every extension.");
187
+ }
188
+ if (verb === "off")
189
+ return `Cannot disable "${ref}": every extension it names is always on.`;
190
+ return `Nothing to ${verb} for "${ref}".`;
191
+ }
192
+ // ── Completion ──────────────────────────────────────────────────────────────
193
+ /** Complete the first token with verbs, later tokens with references. */
194
+ function completeModules(prefix) {
195
+ const text = prefix ?? "";
196
+ const space = text.indexOf(" ");
197
+ if (space === -1) {
198
+ const typed = text.toLowerCase();
199
+ return Object.entries(VERBS)
200
+ .filter(([verb]) => verb.startsWith(typed))
201
+ .map(([verb, description]) => ({ value: verb, label: verb, description }));
202
+ }
203
+ const verb = text.slice(0, space).toLowerCase();
204
+ const tail = text.slice(space + 1);
205
+ if (verb === "all")
206
+ return completeValues(tail, ["on", "off"]);
207
+ if (verb === "on" || verb === "off" || verb === "toggle") {
208
+ const typed = tail.toLowerCase();
209
+ return getModuleRefs()
210
+ .filter((ref) => ref.startsWith(typed))
211
+ .map((ref) => ({ value: `${verb} ${ref}`, label: ref }));
212
+ }
213
+ return null;
214
+ }
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
+ function completeValues(prefix, values) {
225
+ const typed = (prefix ?? "").toLowerCase();
226
+ return values
227
+ .filter((value) => value.startsWith(typed))
228
+ .map((value) => ({ value, label: value }));
229
+ }
230
+ // ── Rows ────────────────────────────────────────────────────────────────────
231
+ /** Every extension as one row, plus the config source that resolved them. */
232
+ function moduleRows() {
233
+ const states = getModuleStates();
234
+ const rows = Object.entries(states).map(([id, info]) => ({
235
+ id,
236
+ description: describe(info.desc, info.origin, info.enabled, info.loaded),
237
+ value: (info.enabled ? "on" : "off"),
238
+ values: ["on", "off"],
239
+ }));
240
+ return { rows, source: Object.values(states)[0]?.source ?? "?" };
241
+ }
242
+ /** The one description both surfaces show: what it does, where its state came
243
+ * from, and whether a restart is still owed. */
244
+ function describe(desc, origin, enabled, loaded) {
245
+ const tail = enabled === loaded ? origin : `${origin}; restart to apply`;
246
+ return `${desc} (${tail})`;
247
+ }
248
+ /** The rows as text, for RPC mode and the `list` verb. */
249
+ function renderRows() {
250
+ const { rows, source } = moduleRows();
251
+ const lines = [`Extensions (${rows.length}, config: ${source}):`];
252
+ const width = Math.min(28, Math.max(...rows.map((row) => row.id.length)));
253
+ for (const row of rows) {
254
+ lines.push(` ${row.value.padEnd(3)} ${row.id.padEnd(width)} ${row.description}`);
255
+ }
256
+ lines.push("");
257
+ lines.push("Toggle: /modules toggle <ref> Enable: /modules on <ref> Disable: /modules off <ref>");
258
+ lines.push("Reset: /modules reset All: /modules all on|off");
259
+ return lines.join("\n");
260
+ }
261
+ // ── TUI ─────────────────────────────────────────────────────────────────────
262
+ /** The TUI list: one toggle per extension, written through the same resolver
263
+ * the verbs use. */
264
+ async function openModuleList(ctx) {
265
+ await ctx.ui.custom((tui, theme, _kb, done) => {
266
+ const container = new Container();
267
+ container.addChild(new (class {
268
+ render(_width) {
269
+ return [theme.fg("accent", theme.bold("Extensions"))];
270
+ }
271
+ invalidate() { }
272
+ })());
273
+ const rows = moduleRows().rows;
274
+ const items = rows.map((row) => ({
275
+ id: row.id,
276
+ label: row.id,
277
+ description: row.description,
278
+ currentValue: row.value,
279
+ values: [...row.values],
280
+ }));
281
+ const list = new SettingsList(items, Math.min(items.length + 2, 18), getSettingsListTheme(), (id, newValue) => {
282
+ const on = newValue === "on";
283
+ if (!setModuleEnabled(id, on)) {
284
+ // The list already flipped its own value; put it back so the row
285
+ // never claims a state the resolver refused.
286
+ list.updateValue(id, "on");
287
+ ctx.ui.notify?.(`"${id}" is always on and cannot be disabled.`, "error");
288
+ tui.requestRender();
289
+ return;
290
+ }
291
+ const info = getModuleStates()[id];
292
+ const item = items.find((candidate) => candidate.id === id);
293
+ if (info && item)
294
+ item.description = describe(info.desc, info.origin, on, info.loaded);
295
+ tui.requestRender();
296
+ }, () => done(undefined), { enableSearch: true });
297
+ container.addChild(list);
298
+ return {
299
+ render(width) {
300
+ return container.render(width);
301
+ },
302
+ invalidate() {
303
+ container.invalidate();
304
+ },
305
+ handleInput(data) {
306
+ list.handleInput?.(data);
307
+ tui.requestRender();
308
+ },
309
+ handleMouse(event) {
310
+ const result = list.handleMouse?.(event);
311
+ tui.requestRender();
312
+ return result;
313
+ },
314
+ };
111
315
  });
112
- log.info("Module API registered: enable/disable/toggle/list/status/reset");
113
316
  }
114
317
  //# sourceMappingURL=api.js.map
@@ -3,8 +3,8 @@
3
3
  *
4
4
  * Config layers (applied high -> low; runtime and settings override the
5
5
  * layers below per-id, the env var is a complete spec over the defaults):
6
- * 1. Runtime overrides - /modules-toggle, /modules-enable, /modules-disable
7
- * (in-session; the toggle commands also persist them into `braid.modules`)
6
+ * 1. Runtime overrides - /modules on|off|toggle|all|reset (in-session; the
7
+ * toggle verbs also persist them into `braid.modules`)
8
8
  * 2. `braid.modules` settings - two sources, later wins per id: pi's
9
9
  * agent-directory settings file (`<agent dir>/settings.json`) and braid's
10
10
  * own module-overrides store, which is where toggles persist
@@ -60,18 +60,32 @@ export interface LoadReport {
60
60
  * Calls each factory with the pi API.
61
61
  */
62
62
  export declare function loadModules(pi: ExtensionAPI, envOverride?: string): Promise<LoadReport>;
63
- /** Enable an extension (or module group). Persists to settings.json. */
63
+ /**
64
+ * Enable or disable an extension (or module group), persisting the choice.
65
+ * Returns false when the reference is unknown, or when the request would
66
+ * disable an always-on extension: always-on entries are loaded regardless of
67
+ * config, so a `false` for one would be a stored lie.
68
+ */
69
+ export declare function setModuleEnabled(ref: string, on: boolean): boolean;
70
+ /** Enable an extension (or module group). Persists to braid's override store. */
64
71
  export declare function enableModule(name: string, _ctx?: ExtensionContext): boolean;
65
- /** Disable an extension (or module group). Persists to settings.json. */
72
+ /** Disable an extension (or module group). Persists to braid's override store. */
66
73
  export declare function disableModule(name: string, _ctx?: ExtensionContext): boolean;
67
74
  /** Toggle an extension (or module group). Returns the new state or null. */
68
75
  export declare function toggleModule(name: string, _ctx?: ExtensionContext): boolean | null;
76
+ /**
77
+ * The layer that decides each extension's enabled state. Later layers win,
78
+ * matching resolveFromSources: manifest default, env spec, agent settings,
79
+ * braid's store, runtime override.
80
+ */
81
+ export type ModuleOrigin = "manifest" | "environment" | "agent settings" | "module toggles" | "runtime override";
69
82
  /** Get the current state of all extensions with loading status. */
70
83
  export declare function getModuleStates(_ctx?: ExtensionContext): Record<string, {
71
84
  enabled: boolean;
72
85
  loaded: boolean;
73
86
  source: string;
74
87
  desc: string;
88
+ origin: ModuleOrigin;
75
89
  }>;
76
90
  /**
77
91
  * Reset all runtime overrides. Persisted braid.modules settings are data the
@@ -81,5 +95,7 @@ export declare function getModuleStates(_ctx?: ExtensionContext): Record<string,
81
95
  */
82
96
  export declare function resetModuleOverrides(_ctx?: ExtensionContext): void;
83
97
  /** Get all valid config reference names for API completion/docs. */
98
+ export declare function getModuleRefs(): string[];
99
+ /** @deprecated Use getModuleRefs. Kept as an alias for existing callers. */
84
100
  export declare function getAllRefNames(): string[];
85
101
  //# sourceMappingURL=loader.d.ts.map
@@ -3,8 +3,8 @@
3
3
  *
4
4
  * Config layers (applied high -> low; runtime and settings override the
5
5
  * layers below per-id, the env var is a complete spec over the defaults):
6
- * 1. Runtime overrides - /modules-toggle, /modules-enable, /modules-disable
7
- * (in-session; the toggle commands also persist them into `braid.modules`)
6
+ * 1. Runtime overrides - /modules on|off|toggle|all|reset (in-session; the
7
+ * toggle verbs also persist them into `braid.modules`)
8
8
  * 2. `braid.modules` settings - two sources, later wins per id: pi's
9
9
  * agent-directory settings file (`<agent dir>/settings.json`) and braid's
10
10
  * own module-overrides store, which is where toggles persist
@@ -415,33 +415,32 @@ function resolveIds(ref) {
415
415
  return group.map((e) => e.id);
416
416
  return null;
417
417
  }
418
- /** Enable an extension (or module group). Persists to settings.json. */
419
- export function enableModule(name, _ctx) {
420
- const ids = resolveIds(name);
418
+ /**
419
+ * Enable or disable an extension (or module group), persisting the choice.
420
+ * Returns false when the reference is unknown, or when the request would
421
+ * disable an always-on extension: always-on entries are loaded regardless of
422
+ * config, so a `false` for one would be a stored lie.
423
+ */
424
+ export function setModuleEnabled(ref, on) {
425
+ const ids = resolveIds(ref);
421
426
  if (!ids)
422
427
  return false;
428
+ const mutable = ids.filter((id) => !getEntry(id)?.alwaysOn);
429
+ if (mutable.length === 0)
430
+ return on;
423
431
  const state = getLoaderState();
424
- const nonAlwaysOn = ids.filter((id) => !getEntry(id)?.alwaysOn);
425
- if (nonAlwaysOn.length === 0)
426
- return true;
427
- for (const id of nonAlwaysOn)
428
- state.runtimeConfig.set(id, true);
432
+ for (const id of mutable)
433
+ state.runtimeConfig.set(id, on);
429
434
  saveModuleOverridesToFile(state.runtimeConfig);
430
435
  return true;
431
436
  }
432
- /** Disable an extension (or module group). Persists to settings.json. */
437
+ /** Enable an extension (or module group). Persists to braid's override store. */
438
+ export function enableModule(name, _ctx) {
439
+ return setModuleEnabled(name, true);
440
+ }
441
+ /** Disable an extension (or module group). Persists to braid's override store. */
433
442
  export function disableModule(name, _ctx) {
434
- const ids = resolveIds(name);
435
- if (!ids)
436
- return false;
437
- const nonAlwaysOn = ids.filter((id) => !getEntry(id)?.alwaysOn);
438
- if (nonAlwaysOn.length === 0)
439
- return false;
440
- const state = getLoaderState();
441
- for (const id of nonAlwaysOn)
442
- state.runtimeConfig.set(id, false);
443
- saveModuleOverridesToFile(state.runtimeConfig);
444
- return true;
443
+ return setModuleEnabled(name, false);
445
444
  }
446
445
  /** Toggle an extension (or module group). Returns the new state or null. */
447
446
  export function toggleModule(name, _ctx) {
@@ -462,10 +461,50 @@ export function toggleModule(name, _ctx) {
462
461
  saveModuleOverridesToFile(state.runtimeConfig);
463
462
  return next;
464
463
  }
464
+ /** The settings layer that names each extension, when one does. */
465
+ function settingsOrigins() {
466
+ const origins = new Map();
467
+ const storePath = getModuleStorePath();
468
+ const layers = [
469
+ ["agent settings", readSettingsFile(GLOBAL_SETTINGS)],
470
+ ["module toggles", storePath ? readSettingsFile(storePath) : {}],
471
+ ];
472
+ for (const [origin, doc] of layers) {
473
+ const modules = doc[BRAID_KEY]?.modules ?? {};
474
+ for (const ref of Object.keys(modules)) {
475
+ for (const id of expandRef(ref))
476
+ origins.set(id, origin);
477
+ }
478
+ }
479
+ return origins;
480
+ }
481
+ /** Where every extension's effective state comes from, one entry each. */
482
+ function resolveOrigins() {
483
+ const origins = new Map();
484
+ for (const entry of MANIFEST)
485
+ origins.set(entry.id, "manifest");
486
+ const env = process.env.BRAID_MODULES;
487
+ if (env && env.trim()) {
488
+ for (const part of env
489
+ .split(",")
490
+ .map((s) => s.trim())
491
+ .filter(Boolean)) {
492
+ const ref = part.startsWith("+") || part.startsWith("-") ? part.slice(1) : part;
493
+ for (const id of expandRef(ref))
494
+ origins.set(id, "environment");
495
+ }
496
+ }
497
+ for (const [id, origin] of settingsOrigins())
498
+ origins.set(id, origin);
499
+ for (const id of getLoaderState().runtimeConfig.keys())
500
+ origins.set(id, "runtime override");
501
+ return origins;
502
+ }
465
503
  /** Get the current state of all extensions with loading status. */
466
504
  export function getModuleStates(_ctx) {
467
505
  const state = getLoaderState();
468
506
  const { enabled, source } = resolveEnabledExtensions();
507
+ const origins = resolveOrigins();
469
508
  const result = {};
470
509
  for (const entry of MANIFEST) {
471
510
  // One resolution path: the resolver already applies runtime overrides,
@@ -477,6 +516,7 @@ export function getModuleStates(_ctx) {
477
516
  loaded: state.loaded.includes(entry.id),
478
517
  source,
479
518
  desc: entry.desc,
519
+ origin: origins.get(entry.id) ?? "manifest",
480
520
  };
481
521
  }
482
522
  return result;
@@ -528,7 +568,11 @@ function topologicalSort(extIds) {
528
568
  return sorted;
529
569
  }
530
570
  /** Get all valid config reference names for API completion/docs. */
531
- export function getAllRefNames() {
571
+ export function getModuleRefs() {
532
572
  return allConfigRefs();
533
573
  }
574
+ /** @deprecated Use getModuleRefs. Kept as an alias for existing callers. */
575
+ export function getAllRefNames() {
576
+ return getModuleRefs();
577
+ }
534
578
  //# 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 - 112 of the core suite's 346 fixtures already use `node:test` - so the
141
+ file uses - 112 of the core suite's 349 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