pi-better-subagents 0.23.2 → 0.24.0
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/agent-commands.ts +33 -0
- package/agent-inspection.ts +6 -0
- package/agent-session-settings.ts +42 -13
- package/catalog-preferences.ts +139 -0
- package/catalog-resolver.ts +3 -3
- package/catalog-store.ts +187 -1
- package/catalog-ui.ts +112 -15
- package/config.ts +1 -0
- package/docs/agent-catalog-lifecycle.md +14 -5
- package/docs/agent-catalog-operations.md +22 -2
- package/docs/agent-catalog.md +4 -2
- package/docs/usage.md +7 -1
- package/extensions.mjs +16 -2
- package/index.ts +2 -0
- package/package.json +1 -1
- package/roles/role.developer.md +3 -1
- package/shared-navigator-panels.ts +250 -0
- package/shared-navigator.ts +5 -5
package/catalog-ui.ts
CHANGED
|
@@ -15,6 +15,8 @@ export interface CatalogEditor {
|
|
|
15
15
|
settings(): AgentSessionOverrides;
|
|
16
16
|
change(id: string, key: AgentSettingKey, value: string | null): void;
|
|
17
17
|
save(id: string): { ok: boolean; message: string };
|
|
18
|
+
resetToBundled?(entry: OperationView): { ok: boolean; message: string };
|
|
19
|
+
resetDefinition?(entry: OperationView): { ok: boolean; message: string };
|
|
18
20
|
}
|
|
19
21
|
|
|
20
22
|
function stateLabel(entry: OperationView): string {
|
|
@@ -137,11 +139,15 @@ export function createCatalogComponent(
|
|
|
137
139
|
getHeight: () => number = () => 30,
|
|
138
140
|
) {
|
|
139
141
|
let selectedId = initialId ?? catalog.entries[0]?.id;
|
|
140
|
-
let mode: "list" | "detail" | "prompt" = initialId ? "detail" : "list";
|
|
142
|
+
let mode: "list" | "detail" | "prompt" | "files" = initialId ? "detail" : "list";
|
|
141
143
|
let query = "";
|
|
142
144
|
let scroll = 0;
|
|
143
145
|
let settingRow = 0;
|
|
144
146
|
let settingPositions: number[] = [];
|
|
147
|
+
let resetPointerRows: number[] = [];
|
|
148
|
+
let resetPointerEntry: OperationView | undefined;
|
|
149
|
+
let pressedReset: OperationView | undefined;
|
|
150
|
+
let pressedResetMode: "detail" | "prompt" | undefined;
|
|
145
151
|
let revealSetting = false;
|
|
146
152
|
let picker: SelectList | undefined;
|
|
147
153
|
let filterPicker: ((filter: string) => void) | undefined;
|
|
@@ -162,9 +168,30 @@ export function createCatalogComponent(
|
|
|
162
168
|
report(result.message, !result.ok);
|
|
163
169
|
} catch (cause) { report(String(cause instanceof Error ? cause.message : cause), true); }
|
|
164
170
|
}
|
|
171
|
+
function canReset(entry: OperationView | undefined): boolean {
|
|
172
|
+
return !!editor?.resetToBundled && !!entry && !Object.values(entry.preferenceSources ?? {}).some(source => source.scope === "project")
|
|
173
|
+
&& (entry.identity.scope === "bundled" || entry.identity.scope === "user" && entry.shadowed.some(source => source.scope === "bundled"));
|
|
174
|
+
}
|
|
175
|
+
function canResetDefinition(entry: OperationView | undefined): boolean {
|
|
176
|
+
return !!editor?.resetDefinition && !!entry && (entry.identity.scope === "bundled"
|
|
177
|
+
|| entry.identity.scope === "user" && entry.shadowed.some(source => source.scope === "bundled"));
|
|
178
|
+
}
|
|
179
|
+
function reset(entry = selected(), definition = false) {
|
|
180
|
+
if (!entry || !(definition ? canResetDefinition(entry) : canReset(entry))) return;
|
|
181
|
+
try {
|
|
182
|
+
const result = definition ? editor!.resetDefinition!(entry) : editor!.resetToBundled!(entry);
|
|
183
|
+
refresh();
|
|
184
|
+
settingRow = 0;
|
|
185
|
+
scroll = 0;
|
|
186
|
+
resetPointerRows = [];
|
|
187
|
+
resetPointerEntry = undefined;
|
|
188
|
+
report(result.message, !result.ok);
|
|
189
|
+
} catch (cause) { report(cause instanceof Error ? cause.message : String(cause), true); }
|
|
190
|
+
}
|
|
165
191
|
function edit() {
|
|
166
192
|
const current = selected();
|
|
167
193
|
if (!current || !editor) return;
|
|
194
|
+
if (settingRow === 2) { reset(current); return; }
|
|
168
195
|
if (!current.definitionValid) { report("Repair the catalog definition before editing.", true); return; }
|
|
169
196
|
const key: AgentSettingKey = settingRow === 0 ? "model" : "effort";
|
|
170
197
|
// Pi treats an empty scope as unrestricted. Scoped choices never include
|
|
@@ -211,22 +238,47 @@ export function createCatalogComponent(
|
|
|
211
238
|
[entry.id, entry.identity.name, entry.identity.description, entry.role?.id]
|
|
212
239
|
.some((value) => value?.toLowerCase().includes(query.toLowerCase())));
|
|
213
240
|
const selected = () => filtered().find((entry) => entry.id === selectedId);
|
|
214
|
-
const detailRows = (entry: OperationView, width: number, controls: string[] = []) =>
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
241
|
+
const detailRows = (entry: OperationView, width: number, controls: string[] = []) => {
|
|
242
|
+
let lines: string[];
|
|
243
|
+
if (mode === "prompt") lines = [
|
|
244
|
+
...(canResetDefinition(entry) ? [theme.fg("accent", "> Reset to bundled"), theme.fg("dim", " Restores the prompt; keeps model/effort choices."), ""] : []),
|
|
245
|
+
theme.fg("muted", `Source: ${entry.identity.scope ?? "unknown"} definition`), "", ...(entry.instructions?.split("\n") ?? ["(No resolved instructions)"]),
|
|
246
|
+
];
|
|
247
|
+
else if (mode === "files") lines = [
|
|
248
|
+
theme.fg("muted", "Definition"), entry.identity.path ?? "(none)", "",
|
|
249
|
+
theme.fg("muted", "Saved preferences"),
|
|
250
|
+
...([...new Set(Object.values(entry.preferenceSources ?? {}).map(source => `${source.scope}: ${source.path}`))].length
|
|
251
|
+
? [...new Set(Object.values(entry.preferenceSources ?? {}).map(source => `${source.scope}: ${source.path}`))] : ["No saved preferences for this definition."]),
|
|
252
|
+
"", theme.fg("muted", "Session edits"), ...JSON.stringify(editor?.settings()[entry.id] ?? {}, null, 2).split("\n"),
|
|
253
|
+
...(entry.shadowed.length ? ["", theme.fg("muted", "Shadowed definitions"), ...entry.shadowed.map(source => `${source.scope}: ${source.path}`)] : []),
|
|
254
|
+
];
|
|
255
|
+
else lines = [
|
|
256
|
+
...(editor ? controls : (["model", "effort"] as const).flatMap(key => settingLines(key === "model" ? "Model" : "Effort", entry.fields?.[key].value ?? "(unset)", entry.fields?.[key].inherited || entry.fields?.[key].source === "role-default" ? "inherited" : "catalog", Math.max(1, width - 4), " ", theme))),
|
|
257
|
+
"", theme.fg("dim", "Model and effort save separately from instructions."), "",
|
|
258
|
+
`ID ${entry.id}`, `Scope ${entry.identity.scope ?? "unknown"}`,
|
|
259
|
+
...(entry.role?.id && entry.identity.kind === "agent" ? [`Role ${entry.role.id}`] : []),
|
|
260
|
+
`Tier ${entry.fields?.tier.value ?? "(unset)"}`,
|
|
261
|
+
`Actual ${entry.actualModel ?? "not resolved"}${entry.actualEffort ? ` · ${entry.actualEffort}` : ""}`,
|
|
262
|
+
"", theme.fg("muted", "Launch resolution"), entry.launchabilityReason,
|
|
263
|
+
...(entry.validation.length ? ["", theme.fg("muted", "Diagnostics"), ...entry.validation.map(item => `${item.blocking ? "!" : "·"} ${item.message}`)] : []),
|
|
264
|
+
...(entry.restrictions.length ? ["", theme.fg("muted", "Execution restrictions"), ...entry.restrictions.map(item => `${item.honored ? "honored" : "not honored"} ${item.name}`)] : []),
|
|
265
|
+
];
|
|
266
|
+
return lines.flatMap(text => text ? wrapLine(text, Math.max(1, width - 4)).map(row => ` ${row}`) : [""]);
|
|
267
|
+
};
|
|
218
268
|
|
|
219
269
|
|
|
220
270
|
return {
|
|
221
271
|
get focused() { return focused; },
|
|
222
272
|
set focused(value: boolean) { focused = value; search.focused = value && !!picker && pickerKey === "model"; },
|
|
223
273
|
render(width: number): string[] {
|
|
274
|
+
resetPointerRows = [];
|
|
275
|
+
resetPointerEntry = undefined;
|
|
224
276
|
const safeWidth = Math.max(1, width);
|
|
225
277
|
const height = Math.max(1, Math.floor(getHeight()));
|
|
226
|
-
const footerRows = (editor
|
|
278
|
+
const footerRows = (editor ? 2 : 0) + (message ? 2 : 0);
|
|
227
279
|
const diagnosticRows = Math.min(catalog.diagnostics.length, 3);
|
|
228
280
|
const listSize = Math.max(1, height - 5 - footerRows - diagnosticRows - 1);
|
|
229
|
-
const detailSize = Math.max(1, height -
|
|
281
|
+
const detailSize = Math.max(1, height - 6 - footerRows);
|
|
230
282
|
const fit = (lines: string[]) => {
|
|
231
283
|
const result = lines.slice(0, height).map(line);
|
|
232
284
|
while (result.length < height) result.push("");
|
|
@@ -254,13 +306,18 @@ export function createCatalogComponent(
|
|
|
254
306
|
const own = editor?.settings()[current.id];
|
|
255
307
|
const ownSession = Object.hasOwn(own ?? {}, key);
|
|
256
308
|
const roleSession = field?.inherited && Object.hasOwn(editor?.settings()[current.role?.id ?? ""] ?? {}, key);
|
|
257
|
-
const
|
|
309
|
+
const saved = current.preferenceSources?.[key];
|
|
310
|
+
const inherited = current.identity.kind === "agent" && field?.inherited;
|
|
311
|
+
const origin = ownSession && own?.[key] === null ? "inherit / session" : ownSession ? "session" : roleSession ? "inherited / session"
|
|
312
|
+
: saved?.bundled ? "bundled" : saved ? `${inherited ? "inherited / " : ""}${saved.scope} config`
|
|
313
|
+
: current.identity.scope === "bundled" && !inherited ? "bundled" : field?.inherited ? "inherited" : "catalog";
|
|
258
314
|
return settingLines(label, field?.value ?? "(unset)", origin, Math.max(1, safeWidth - 4), settingRow === index ? "> " : " ", theme);
|
|
259
315
|
}),
|
|
316
|
+
...(canReset(current) ? [theme.fg(settingRow === 2 ? "accent" : "muted", `${settingRow === 2 ? "> " : " "}Reset to bundled`), theme.fg("dim", " Restores model/effort; keeps the role prompt.")] : []),
|
|
260
317
|
] : [];
|
|
261
318
|
const detailLines = current ? detailRows(current, safeWidth, controls) : [];
|
|
262
319
|
if (editor && mode === "detail") {
|
|
263
|
-
settingPositions = ["Model", "Effort"].map((label) => detailLines.findIndex((text) =>
|
|
320
|
+
settingPositions = ["Model", "Effort", ...(canReset(current) ? ["Reset to bundled"] : [])].map((label) => detailLines.findIndex((text) =>
|
|
264
321
|
new RegExp(`^ [> ] ${label}(?:\\s|$)`).test(text.replace(/\x1b\[[0-9;]*m/g, ""))));
|
|
265
322
|
if (revealSetting && settingPositions[settingRow] >= 0) {
|
|
266
323
|
const position = settingPositions[settingRow];
|
|
@@ -270,9 +327,21 @@ export function createCatalogComponent(
|
|
|
270
327
|
revealSetting = false;
|
|
271
328
|
}
|
|
272
329
|
scroll = Math.max(0, Math.min(scroll, detailLines.length - detailSize));
|
|
330
|
+
if (mode === "detail" && current && canReset(current)) {
|
|
331
|
+
const position = settingPositions[2];
|
|
332
|
+
if (position >= scroll && position < scroll + detailSize) {
|
|
333
|
+
resetPointerRows = [4 + position - scroll];
|
|
334
|
+
resetPointerEntry = current;
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
if (mode === "prompt" && current && canResetDefinition(current) && scroll === 0) {
|
|
338
|
+
resetPointerRows = [4];
|
|
339
|
+
resetPointerEntry = current;
|
|
340
|
+
}
|
|
273
341
|
const lines = mode !== "list" && current ? [
|
|
274
|
-
theme.fg("accent",
|
|
275
|
-
|
|
342
|
+
theme.fg("accent", `Agents / ${current.identity.name || current.id}`),
|
|
343
|
+
([['detail', 'Settings'], ['prompt', 'Instructions'], ['files', 'Files']] as const).map(([tab, label]) => theme.fg(mode === tab ? "accent" : "dim", mode === tab ? `[${label}]` : label)).join(" "),
|
|
344
|
+
theme.fg("dim", safeWidth < 60 ? "Tab switch · ↑↓ move · Enter · Esc" : `Tab / Shift+Tab switch · ↑↓ ${mode === "detail" && editor ? "select / scroll · Enter change" : mode === "prompt" && canResetDefinition(current) ? "scroll · Enter reset at top" : "scroll"} · Esc list`),
|
|
276
345
|
"",
|
|
277
346
|
|
|
278
347
|
...detailLines.slice(scroll, scroll + detailSize).map((text, i) =>
|
|
@@ -297,7 +366,7 @@ export function createCatalogComponent(
|
|
|
297
366
|
...catalog.diagnostics.slice(0, 2).map((diagnostic) => theme.fg("warning", `! ${diagnostic.message}`)),
|
|
298
367
|
...(catalog.diagnostics.length > 2 ? [theme.fg("warning", `! ${catalog.diagnostics.length - 2} more catalog diagnostics`)] : []),
|
|
299
368
|
];
|
|
300
|
-
if (editor
|
|
369
|
+
if (editor) lines.push("", theme.fg("dim", "Ctrl+S Save defaults"));
|
|
301
370
|
if (message) lines.push("", theme.fg(error ? "error" : "muted", message));
|
|
302
371
|
return fit(lines);
|
|
303
372
|
},
|
|
@@ -312,15 +381,25 @@ export function createCatalogComponent(
|
|
|
312
381
|
return;
|
|
313
382
|
}
|
|
314
383
|
if (editor && matchesKey(data, "ctrl+s")) { save(); return; }
|
|
384
|
+
if (mode !== "list" && (matchesKey(data, "tab") || matchesKey(data, "shift+tab"))) {
|
|
385
|
+
const tabs = ["detail", "prompt", "files"] as const;
|
|
386
|
+
const index = tabs.indexOf(mode);
|
|
387
|
+
mode = tabs[(index + (matchesKey(data, "shift+tab") ? 2 : 1)) % 3];
|
|
388
|
+
scroll = 0;
|
|
389
|
+
revealSetting = mode === "detail";
|
|
390
|
+
pressedReset = undefined;
|
|
391
|
+
requestRender();
|
|
392
|
+
return;
|
|
393
|
+
}
|
|
315
394
|
if (matchesKey(data, "escape") || matchesKey(data, "left")) {
|
|
316
|
-
if (mode === "prompt") { mode = "detail"; scroll = 0; }
|
|
395
|
+
if (mode === "prompt" || mode === "files") { mode = "detail"; scroll = 0; revealSetting = true; }
|
|
317
396
|
else if (mode === "detail") { mode = "list"; scroll = 0; }
|
|
318
397
|
else if (query) { query = ""; selectedId = catalog.entries[0]?.id; }
|
|
319
398
|
else { close(); return; }
|
|
320
399
|
} else if (matchesKey(data, "up") || matchesKey(data, "down")) {
|
|
321
400
|
const delta = matchesKey(data, "down") ? 1 : -1;
|
|
322
|
-
if (mode === "detail" && editor && scroll <= (settingPositions
|
|
323
|
-
&& ((delta > 0 && settingRow
|
|
401
|
+
if (mode === "detail" && editor && scroll <= (settingPositions.at(-1) ?? 0)
|
|
402
|
+
&& ((delta > 0 && settingRow < settingPositions.length - 1) || (delta < 0 && settingRow > 0))) {
|
|
324
403
|
settingRow += delta;
|
|
325
404
|
revealSetting = true;
|
|
326
405
|
}
|
|
@@ -339,6 +418,8 @@ export function createCatalogComponent(
|
|
|
339
418
|
revealSetting = true;
|
|
340
419
|
} else if (editor && mode === "detail" && (matchesKey(data, "enter") || data === " ")) {
|
|
341
420
|
try { edit(); } catch (cause) { report(cause instanceof Error ? cause.message : String(cause), true); }
|
|
421
|
+
} else if (editor && mode === "prompt" && scroll === 0 && (matchesKey(data, "enter") || data === " ")) {
|
|
422
|
+
reset(selected(), true);
|
|
342
423
|
} else if (mode === "list" && matchesKey(data, "backspace")) {
|
|
343
424
|
query = query.slice(0, -1);
|
|
344
425
|
selectedId = filtered()[0]?.id;
|
|
@@ -348,6 +429,22 @@ export function createCatalogComponent(
|
|
|
348
429
|
}
|
|
349
430
|
requestRender();
|
|
350
431
|
},
|
|
432
|
+
handleMouse(event: { type: string; button: string; x: number; y: number; width: number; shift?: boolean; alt?: boolean; ctrl?: boolean }) {
|
|
433
|
+
const entry = resetPointerEntry;
|
|
434
|
+
const hit = !picker && (mode === "detail" || mode === "prompt") && entry && event.button === "left" && !event.shift && !event.alt && !event.ctrl
|
|
435
|
+
&& event.x >= 0 && event.x < event.width && resetPointerRows.includes(event.y);
|
|
436
|
+
if (event.type === "press") {
|
|
437
|
+
pressedReset = hit ? entry : undefined;
|
|
438
|
+
pressedResetMode = hit ? mode as "detail" | "prompt" : undefined;
|
|
439
|
+
return hit ? { handled: true as const, render: false } : undefined;
|
|
440
|
+
}
|
|
441
|
+
if (event.type !== "click") return undefined;
|
|
442
|
+
const pressed = pressedReset;
|
|
443
|
+
pressedReset = undefined;
|
|
444
|
+
if (!hit || !pressed || pressedResetMode !== mode || pressed.id !== entry.id || pressed.winningSource?.contentDigest !== entry.winningSource?.contentDigest) return undefined;
|
|
445
|
+
reset(pressed, mode === "prompt");
|
|
446
|
+
return { handled: true as const, render: true };
|
|
447
|
+
},
|
|
351
448
|
invalidate() { picker?.invalidate(); search.invalidate(); },
|
|
352
449
|
};
|
|
353
450
|
}
|
package/config.ts
CHANGED
|
@@ -33,6 +33,7 @@ export interface SubagentConfig extends TimingSettings {
|
|
|
33
33
|
/**
|
|
34
34
|
* Provider → extension package(s) that authenticate it. Model auth is not
|
|
35
35
|
* tool-shaped: `xai/grok-4.5` needs pi-xai-oauth loaded whatever the tools.
|
|
36
|
+
* A built-in entry covers `ollama-cloud`; an entry here replaces it.
|
|
36
37
|
*/
|
|
37
38
|
providerExtensions?: Record<string, string | string[]> | null;
|
|
38
39
|
/**
|
|
@@ -55,11 +55,20 @@ already-admitted jobs. Model choices come from the session's Pi model scope
|
|
|
55
55
|
(`ctx.scopedModels`); an empty scope is no restriction, so they fall back to the
|
|
56
56
|
current Pi model registry's available models.
|
|
57
57
|
|
|
58
|
-
Ctrl+S saves only the selected definition's
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
58
|
+
Ctrl+S saves only the selected definition's model/effort edits in catalog
|
|
59
|
+
`settings.json`, preserving other saved fields without copying Markdown or
|
|
60
|
+
flattening inherited defaults. `loadCatalog` reads definition files and saved
|
|
61
|
+
preferences from disk; the branch overlay stays separate. User preferences apply
|
|
62
|
+
to user and bundled definitions; trusted project preferences take precedence.
|
|
63
|
+
Project-owned definitions do not consume user preferences.
|
|
64
|
+
|
|
65
|
+
Settings, Instructions, and Files have separate TUI tabs; Ctrl+S is the only
|
|
66
|
+
save control. **Reset to bundled** in Settings restores model/effort preferences
|
|
67
|
+
and clears branch-local edits without changing Markdown. The same action in
|
|
68
|
+
Instructions restores the bundled prompt while preserving model/effort choices;
|
|
69
|
+
a user Markdown override is archived. Session reset entries replay on reload and
|
|
70
|
+
branch navigation. Existing launch snapshots remain unchanged. Project-owned
|
|
71
|
+
definitions are excluded; runtime reset also excludes active project config.
|
|
63
72
|
|
|
64
73
|
Headless callers can inject a session controller or immutable
|
|
65
74
|
`CatalogHost.sessionSettings`. Hosts without these hooks retain inspection-only
|
|
@@ -6,7 +6,7 @@ Commands, the read-only discovery tool, and the Codex importer for `pi-agent/v1`
|
|
|
6
6
|
|
|
7
7
|
`/agents` is one Pi command. Dialogs use `ctx.ui.select`, `confirm`, `input`, and `editor`. `ctx.hasUI` is false in print and JSON mode. When a choice or confirmation is required there, the command returns `clarification-needed` and writes nothing.
|
|
8
8
|
|
|
9
|
-
In an interactive TUI, `/agents`, `/agents list`, and `/agents show` open a focused catalog view instead of leaving the listing in a persistent widget. Rows align name, effective model, source, and launch state; narrow terminals retain name and model. The model is the resolved actual model when available, otherwise the requested or inherited preference, or `not resolved`. Type to filter by id, name, description, or base role; use Up/Down and Enter to inspect. The detail view
|
|
9
|
+
In an interactive TUI, `/agents`, `/agents list`, and `/agents show` open a focused catalog view instead of leaving the listing in a persistent widget. Rows align name, effective model, source, and launch state; narrow terminals retain name and model. The model is the resolved actual model when available, otherwise the requested or inherited preference, or `not resolved`. Type to filter by id, name, description, or base role; use Up/Down and Enter to inspect. The detail view opens **Settings**, with Model, Effort, launch resolution, and diagnostics. **Instructions** contains the complete effective prompt (role plus agent in add mode, agent text in replace mode); this is not the task-specific launch prompt. **Files** shows definition and saved-config sources plus current session edits. Tab and Shift+Tab cycle between these pages; `p` opens Instructions. Up/Down selects settings or scrolls the current page. Left or Escape returns to Settings, then list, clears the filter, then closes. `/agents show <id>` opens that definition directly. Print/JSON callers still receive the complete text and structured result; bare `/agents` still returns help outside the custom TUI.
|
|
10
10
|
|
|
11
11
|
### Model and effort edits
|
|
12
12
|
|
|
@@ -16,7 +16,27 @@ The scope affects only the picker. Launch and runtime model resolution keep read
|
|
|
16
16
|
|
|
17
17
|
A selected value immediately appends a custom entry to the current session branch. It does not write a catalog file. Reloading the extension or session restores the active branch's edits. Branches share their common ancestor settings but subsequent edits do not cross to siblings. Role edits flow into named agents that inherit that field. Choosing `Inherit` removes the selected definition's own value, including a saved agent override, instead of storing an explicit null preference. For a role with no parent, that removes its default. Later role/file edits remain live.
|
|
18
18
|
|
|
19
|
-
Ctrl+S
|
|
19
|
+
Ctrl+S saves the selected definition's model and effort edits to `agents/settings.json` in user scope, or the corresponding trusted project catalog. It never copies or rewrites a Markdown definition, so changing a bundled role's model does not freeze its prompt or its untouched defaults. Existing saved preferences for other definitions are preserved. Writes validate the config and use a lock plus atomic replacement; malformed config is not overwritten. Both successful and failed saves leave branch edits intact.
|
|
20
|
+
|
|
21
|
+
The dedicated config has this shape:
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"version": 1,
|
|
26
|
+
"defaults": {
|
|
27
|
+
"role.developer": { "model": "openai/gpt-6.1-sol", "effort": "high" }
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Saved fields override definition defaults one field at a time; branch edits override saved fields. A record with `bundled: true` takes model/effort defaults from the current bundled definition before applying any explicit fields in that record. Trusted project config wins over user config. User config does not override a project-owned Markdown definition. The detail view labels saved fields as `user config` or `project config`.
|
|
33
|
+
|
|
34
|
+
Both Settings and Instructions offer **Reset to bundled**, with independent effects:
|
|
35
|
+
|
|
36
|
+
- **Settings:** follows the current bundled model and effort, clears that id's current-session choices, and leaves its Markdown prompt unchanged. A user definition records `{ "bundled": true }` instead of copied default values; the UI shows `bundled`, and later bundle updates apply automatically. An explicit model/effort choice can override one field while the other keeps following the bundle. Project-owned definitions and active project config are excluded.
|
|
37
|
+
- **Instructions:** archives a user Markdown override in a hidden `.backup` file beside the original and reveals the bundled role prompt. Its model/effort choices move to the config where needed, and session choices remain unchanged. An already-bundled prompt needs no change. Project definitions are excluded.
|
|
38
|
+
|
|
39
|
+
Click the action once, or select it in Settings and press Enter. In Instructions, Enter activates the reset when scrolled to the top. The action requires a valid bundled fallback and refuses stale selections, duplicates, and symlink redirects. Other definitions stay unchanged. Saving remains **Ctrl+S** only; there is no Save button or selectable save row. Existing overrides remain intact until explicitly reset.
|
|
20
40
|
|
|
21
41
|
New launches and `agents_catalog` discovery use the same session overlay. Explicit per-run model/effort choices still win, a batch retains one immutable snapshot, and active/completed runs do not change. Role effort remains an inherited default with the existing nearest-supported adjustment; named-agent effort remains explicit and blocks when unsupported. The lifecycle wiring required to enable this surface is in [agent-catalog-lifecycle.md](./agent-catalog-lifecycle.md#session-settings-integration).
|
|
22
42
|
|
package/docs/agent-catalog.md
CHANGED
|
@@ -78,7 +78,9 @@ For external consumers, the repo-root `agent-catalog.yaml` publishes the shared
|
|
|
78
78
|
definitions through a [Git subscription contract](catalog-subscription.md).
|
|
79
79
|
This publication mechanism does not change local source precedence below.
|
|
80
80
|
|
|
81
|
-
|
|
81
|
+
Markdown definition precedence is project, then personal, then bundled. The higher source replaces the whole definition. Omitted agent fields inherit from the effective role, not from the shadowed agent.
|
|
82
|
+
|
|
83
|
+
Model and effort choices saved through `/agents` live separately in the catalog's `settings.json` (`version: 1`, with a `defaults` map keyed by role/agent id). They override only those fields, without shadowing the Markdown prompt. Branch edits win over saved preferences; trusted project preferences win over user preferences. User preferences do not override project-owned definitions. Existing Markdown overrides stay whole definitions until explicitly archived through **Reset to bundled** in Instructions. See [catalog operations](agent-catalog-operations.md#model-and-effort-edits).
|
|
82
84
|
|
|
83
85
|
| Scope | Path |
|
|
84
86
|
| --- | --- |
|
|
@@ -94,7 +96,7 @@ Role references use the same precedence. A missing or unusable role leaves the a
|
|
|
94
96
|
|
|
95
97
|
## Snapshots
|
|
96
98
|
|
|
97
|
-
`loadCatalog` / `refreshCatalog` read the disk every time and return a new frozen snapshot. `digest` / `revision` is a sha256 of the canonical entries, unused sources, and snapshot diagnostics. `loadedAt` is not part of the digest. Callers must reuse one snapshot for every job in a batch. Later file edits do not mutate a snapshot already taken. `/agents reload` is an inspection operation owned by the operations unit; it is not required for the next `loadCatalog` to see edits.
|
|
99
|
+
`loadCatalog` / `refreshCatalog` read the disk every time and return a new frozen snapshot. `digest` / `revision` is a sha256 of the canonical entries, unused sources, saved preferences and their sources, and snapshot diagnostics. `loadedAt` is not part of the digest. Callers must reuse one snapshot for every job in a batch. Later file edits do not mutate a snapshot already taken. `/agents reload` is an inspection operation owned by the operations unit; it is not required for the next `loadCatalog` to see edits.
|
|
98
100
|
|
|
99
101
|
File diagnostics for an id live on that catalog entry. `snapshot.diagnostics` carries directory, trust, duplicate, and no-id failures. `resolveSelection`, `listCatalog`, and `inspectCatalog` are the launchability view; `schemaLaunchable` does not yet know whether an agent's role exists.
|
|
100
102
|
|
package/docs/usage.md
CHANGED
|
@@ -512,13 +512,19 @@ so a package that backs no requested tool never loads. With the default
|
|
|
512
512
|
allowlist (`read, bash, edit, write, web_search, web_fetch`) exactly one package
|
|
513
513
|
loads — the web-tools one — and `web_fetch` works normally.
|
|
514
514
|
|
|
515
|
-
Two maps in `config.json` drive it:
|
|
515
|
+
Two maps in `config.json` drive it, with a built-in default for provider auth:
|
|
516
516
|
|
|
517
517
|
- `toolExtensions` — tool name → package(s) providing it. Built-ins (`read`,
|
|
518
518
|
`bash`, `edit`, `write`) need no entry.
|
|
519
519
|
- `providerExtensions` — provider → auth package. Model auth is not tool-shaped:
|
|
520
520
|
`xai/grok-4.5` needs `pi-xai-oauth` loaded whatever tools it was granted.
|
|
521
521
|
|
|
522
|
+
The built-in map loads `pi-ollama-cloud` for `ollama-cloud` models, so a role
|
|
523
|
+
resolved against that provider works without a manual entry. An entry for the
|
|
524
|
+
same provider replaces the built-in one, and an empty list disables it. A mapped
|
|
525
|
+
package that is not installed still fails the launch with the explicit
|
|
526
|
+
missing-extension error rather than starting without provider auth.
|
|
527
|
+
|
|
522
528
|
Ask for a tool with no mapping and the spawn still succeeds, but says so at
|
|
523
529
|
launch — the tool simply will not exist in the child.
|
|
524
530
|
|
package/extensions.mjs
CHANGED
|
@@ -38,6 +38,17 @@ export const BUILTIN_TOOLS = ["read", "bash", "edit", "write"];
|
|
|
38
38
|
/** Marker spec meaning "this extension's own package" (for allow_nested). */
|
|
39
39
|
export const SELF_SPEC = "self";
|
|
40
40
|
|
|
41
|
+
/**
|
|
42
|
+
* Provider packages Pi does not ship itself. A provider's models exist in a
|
|
43
|
+
* child only when the package registering them is loaded; without this map, a
|
|
44
|
+
* role that resolves e.g. `ollama-cloud/...` in the foreground fails in its
|
|
45
|
+
* isolated child with "model not found". User `providerExtensions` entries
|
|
46
|
+
* replace these per provider (an empty list disables the built-in entry).
|
|
47
|
+
*/
|
|
48
|
+
export const BUILTIN_PROVIDER_EXTENSIONS = {
|
|
49
|
+
"ollama-cloud": "npm:pi-ollama-cloud",
|
|
50
|
+
};
|
|
51
|
+
|
|
41
52
|
/** Split "xai/grok-4.5" -> "xai". Returns undefined when there is no provider. */
|
|
42
53
|
export function providerOf(model) {
|
|
43
54
|
if (typeof model !== "string") return undefined;
|
|
@@ -116,10 +127,13 @@ export function resolveExtensions(a = {}) {
|
|
|
116
127
|
}
|
|
117
128
|
|
|
118
129
|
// Model auth is not tool-shaped: xai/grok needs pi-xai-oauth loaded or the
|
|
119
|
-
// child cannot authenticate at all, whatever tools it was granted.
|
|
130
|
+
// child cannot authenticate at all, whatever tools it was granted. A user
|
|
131
|
+
// entry for a provider wins over the built-in one, including an empty list
|
|
132
|
+
// that opts out of loading the provider's package.
|
|
133
|
+
const providerMap = { ...BUILTIN_PROVIDER_EXTENSIONS, ...(cfg.providerExtensions ?? {}) };
|
|
120
134
|
const provider = providerOf(a.model);
|
|
121
135
|
if (provider) {
|
|
122
|
-
for (const spec of toSpecList(
|
|
136
|
+
for (const spec of toSpecList(providerMap[provider])) {
|
|
123
137
|
add(spec, `provider:${provider}`);
|
|
124
138
|
}
|
|
125
139
|
}
|
package/index.ts
CHANGED
|
@@ -17,6 +17,7 @@ import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@e
|
|
|
17
17
|
import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
|
|
18
18
|
import * as PiTui from "@earendil-works/pi-tui";
|
|
19
19
|
import { CustomEditor } from "@earendil-works/pi-coding-agent";
|
|
20
|
+
import { initializeNavigatorPanels } from "./shared-navigator-panels.ts";
|
|
20
21
|
import { matchesKey, Key, truncateToWidth, type AutocompleteItem } from "@earendil-works/pi-tui";
|
|
21
22
|
import { Type } from "@earendil-works/pi-ai";
|
|
22
23
|
import {
|
|
@@ -1465,6 +1466,7 @@ function catalogRoleSchema(purpose: string) {
|
|
|
1465
1466
|
}
|
|
1466
1467
|
|
|
1467
1468
|
export default function (pi: ExtensionAPI) {
|
|
1469
|
+
initializeNavigatorPanels(pi);
|
|
1468
1470
|
const agentSessionSettings = createAgentSessionSettings(pi);
|
|
1469
1471
|
let catalogModelRegistry: ExtensionContext["modelRegistry"] | undefined;
|
|
1470
1472
|
let delegationOverride: DelegationMode | undefined;
|
package/package.json
CHANGED
package/roles/role.developer.md
CHANGED
|
@@ -3,12 +3,14 @@ schema: pi-agent/v1
|
|
|
3
3
|
kind: role
|
|
4
4
|
id: role.developer
|
|
5
5
|
name: Developer
|
|
6
|
-
description: Owns implementation and focused tests; excludes architecture policy and independent review.
|
|
6
|
+
description: Owns implementation and focused tests, including release metadata preparation; excludes delivery, publishing, architecture policy, and independent review.
|
|
7
7
|
defaults:
|
|
8
8
|
model: openai/gpt-6.1-sol
|
|
9
9
|
effort: high
|
|
10
10
|
tier: balanced
|
|
11
11
|
---
|
|
12
12
|
Implement the requested change in the existing system and own focused tests. Preserve behavior the task did not ask to change, and record what you verified.
|
|
13
|
+
For a release, prepare and test metadata under the coordinator's approved plan: version files, dependency pins, lockfile, changelog, and package checks. Hand back the local changes or commit, verification evidence, and remaining blockers.
|
|
14
|
+
Delivery and publishing belong to the coordinator: remote pushes, PR creation and merge, queue admission, release tags, publisher dispatch, and publication verification. Do not perform those operations or take ownership of external waits. The coordinator uses background watchers for CI, merge queues, publishers, registry propagation, and deployments. If an assignment crosses this boundary, report the mismatch and hand it back before proceeding.
|
|
13
15
|
When a check fails, report the failing step, the error message and where the evidence is; an exit code alone is not a failure report. Keep the first failure separate from later cleanup errors. Send long command output to a file and read only the tail or the matching lines.
|
|
14
16
|
Do not define product policy or own broad architecture decisions; route those to Product Manager or Architect. Independent critique belongs to Reviewer, not the implementer.
|