pi-better-subagents 0.27.1 → 0.28.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/README.md +20 -8
- package/agent-commands.ts +29 -10
- package/agent-inspection.ts +116 -5
- package/agents-catalog-tool.ts +5 -3
- package/batch.mjs +6 -0
- package/catalog-resolver.ts +28 -0
- package/catalog-runtime.ts +8 -0
- package/catalog-schema.ts +110 -8
- package/catalog-skill-edits.ts +116 -0
- package/catalog-ui.ts +172 -27
- package/child-ownership.ts +21 -2
- package/config.ts +35 -3
- package/continuation.ts +3 -0
- package/docs/agent-catalog-operations.md +47 -4
- package/docs/agent-catalog.md +12 -1
- package/docs/usage.md +81 -8
- package/effective-settings.ts +61 -8
- package/index.ts +217 -16
- package/package.json +1 -1
- package/registry.ts +11 -0
- package/settings-page.ts +220 -47
- package/shared-execution-policy.ts +54 -14
- package/shared-worktree-context.ts +158 -0
- package/skill-picker.ts +349 -0
- package/skills.ts +183 -0
package/README.md
CHANGED
|
@@ -15,7 +15,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
|
|
|
15
15
|
- Continue a saved conversation with `subagent_spawn({ session_id, prompt })`, or use `session_name` for a unique name in the current folder. Sessions persist by default. Lists show session IDs and search locally; `all:true` searches globally. Batch jobs use the same selectors. See [continuing a saved conversation](docs/usage.md#continuing-a-saved-conversation).
|
|
16
16
|
- Typed foreground `subagent_spawn_batch` launch receipts for native Pi codemode (Pi 0.99.1+), preserving direct tool calls, per-run callbacks, and batch capacity/catalog guarantees. See [codemode batch launches](docs/usage.md#codemode-batch-launches).
|
|
17
17
|
- Opt-in OS task sandboxing on macOS and Linux.
|
|
18
|
-
- Explicit tool allowlists for child sessions.
|
|
18
|
+
- Explicit tool allowlists for child sessions, and `skills` for prompt exposure: omit it to keep user-catalog discovery, pass `[]` for no skills, or pass absolute `SKILL.md` paths for exactly those. See [skill exposure](docs/usage.md#skill-exposure).
|
|
19
19
|
- Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
|
|
20
20
|
- Live background-work navigator for active runs.
|
|
21
21
|
- Harness-owned run timing: every run gets a no-progress wake (10 min), while wall-clock soft deadlines and hard ceilings are opt-in so productive agents are not stopped solely for taking a long time. Configure per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`, or globally in `config.json` / `PI_SUBAGENT_*_MINUTES`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-stuck).
|
|
@@ -80,13 +80,23 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
|
|
|
80
80
|
|
|
81
81
|
The user config sets `delegationMode` to `manual`, `adaptive` (default), or
|
|
82
82
|
`coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
|
|
83
|
-
for delegation mode
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
83
|
+
for delegation mode, the concurrent-subagent cap (default 6), and the default
|
|
84
|
+
skill exposure. Skill exposure cycles between Discover automatically and No skill
|
|
85
|
+
catalog. The Selected skills row opens the same searchable checkbox picker used
|
|
86
|
+
by `/agents`: it lists loaded skills by name and description, Space toggles one,
|
|
87
|
+
Enter applies, and typing filters without dropping checked items. Saved paths
|
|
88
|
+
missing from discovery stay visible as unavailable and survive apply. Zero
|
|
89
|
+
checked applies No skill catalog, not discovery. Manual Add skill path remains
|
|
90
|
+
available. The page names whether the current value comes from the saved config
|
|
91
|
+
or this session. The session choice controls the next launch before Ctrl+S, and
|
|
92
|
+
edits persist across reloads. Ctrl+S saves mode, cap, and skill exposure as
|
|
93
|
+
defaults, and Reset to defaults clears session overrides, including the skill
|
|
94
|
+
list. Agents opens the same catalog as `/agents`; a definition that inherits
|
|
95
|
+
skill exposure shows whether the live value comes from this session, saved
|
|
96
|
+
config, or discovery, and an invalid draft is marked invalid rather than shown
|
|
97
|
+
as discovery. `/subagents mode manual|adaptive|coordinator` and
|
|
88
98
|
`/subagents cap <number>` are command equivalents; `/subagents save` persists
|
|
89
|
-
|
|
99
|
+
the current settings. Lowering the cap blocks new single and batch launches, including launches
|
|
90
100
|
still preparing, without stopping running work. Saved configuration changes are
|
|
91
101
|
picked up on subsequent reads; explicit session overrides still take precedence.
|
|
92
102
|
Before every model request, including continuations after tool calls,
|
|
@@ -112,7 +122,9 @@ Saved defaults live in global `~/.pi/agent/settings.json` under
|
|
|
112
122
|
`piBetterHarness.subagents` (or under `PI_CODING_AGENT_DIR`) and survive package
|
|
113
123
|
reinstalls and upgrades. The old user config migrates on first use. Global values
|
|
114
124
|
override the package's `config.json`, which remains a compatibility fallback.
|
|
115
|
-
Save existing mode and
|
|
125
|
+
Save existing mode, cap, and skill choices with `/subagents save` or Ctrl+S.
|
|
126
|
+
Discovery is saved as `defaultSkills: null`, which clears a previously saved
|
|
127
|
+
path list. Put other
|
|
116
128
|
custom config keys in `piBetterHarness.subagents` as well; edits made only inside
|
|
117
129
|
the installed package can be lost on upgrade.
|
|
118
130
|
|
package/agent-commands.ts
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from "node:fs";
|
|
10
10
|
import { isAbsolute, resolve } from "node:path";
|
|
11
11
|
import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
|
|
12
|
-
import { presentCatalog, presentCatalogEntry, type LaunchEnricher, type OperationView } from "./agent-inspection.ts";
|
|
12
|
+
import { presentCatalog, presentCatalogEntry, type LaunchEnricher, type OperationView, type ReadSkillDefaults } from "./agent-inspection.ts";
|
|
13
13
|
import { createCatalogComponent } from "./catalog-ui.ts";
|
|
14
14
|
import type { ScopedModelLike } from "./catalog-editor.ts";
|
|
15
15
|
import {
|
|
@@ -51,6 +51,8 @@ import {
|
|
|
51
51
|
} from "./codex-import.ts";
|
|
52
52
|
import { resolveRoleAssignment } from "./role-assignment.ts";
|
|
53
53
|
import { saveAgentSessionDefaults, withAgentSessionSettings, type AgentSessionOverrides, type AgentSessionSettings } from "./agent-session-settings.ts";
|
|
54
|
+
import { saveSkillExposure } from "./catalog-skill-edits.ts";
|
|
55
|
+
import type { DiscoveredSkill } from "./skill-picker.ts";
|
|
54
56
|
|
|
55
57
|
const MODEL_PATTERN = /^[a-z0-9][a-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._+-]*$/;
|
|
56
58
|
const TIER_PATTERN = /^[a-z][a-z0-9-]{0,32}$/;
|
|
@@ -72,6 +74,12 @@ export interface AgentCommandDeps {
|
|
|
72
74
|
now?: () => string;
|
|
73
75
|
/** Resolution unit injects availability, actual model/effort, and launchability. */
|
|
74
76
|
enrich?: LaunchEnricher;
|
|
77
|
+
/** Live session/config default skill choice; absent keeps the legacy config read. */
|
|
78
|
+
readSkillDefaults?: ReadSkillDefaults;
|
|
79
|
+
/** Read loaded Pi skill metadata for the checkbox picker. */
|
|
80
|
+
discoverSkills?: (ctx: ExtensionCommandContext) => readonly DiscoveredSkill[];
|
|
81
|
+
/** Snapshot captured for this invocation. */
|
|
82
|
+
discoveredSkills?: readonly DiscoveredSkill[];
|
|
75
83
|
sessionSettings?: AgentSessionSettings;
|
|
76
84
|
/** Available foreground registry models, as provider/id. */
|
|
77
85
|
editableModels?: () => readonly string[];
|
|
@@ -153,6 +161,7 @@ export function registerAgentCommands(pi: Pick<ExtensionAPI, "registerCommand">,
|
|
|
153
161
|
/** Slash commands and settings shortcuts must resolve against the same live context. */
|
|
154
162
|
export function executeAgentsCommandContext(args: string, ctx: ExtensionCommandContext, deps: AgentCommandDeps = {}): Promise<AgentCommandResult> {
|
|
155
163
|
deps.propagateCommandContext?.(ctx);
|
|
164
|
+
const discoveredSkills = deps.discoverSkills?.(ctx) ?? deps.discoveredSkills;
|
|
156
165
|
return executeAgentsCommand(args, {
|
|
157
166
|
cwd: ctx.cwd,
|
|
158
167
|
hasUI: ctx.hasUI,
|
|
@@ -160,7 +169,7 @@ export function executeAgentsCommandContext(args: string, ctx: ExtensionCommandC
|
|
|
160
169
|
isProjectTrusted: () => ctx.isProjectTrusted(),
|
|
161
170
|
scopedModels: scopedModelsFromContext(ctx),
|
|
162
171
|
ui: ctx.ui,
|
|
163
|
-
}, deps);
|
|
172
|
+
}, discoveredSkills ? { ...deps, discoveredSkills } : deps);
|
|
164
173
|
}
|
|
165
174
|
|
|
166
175
|
/**
|
|
@@ -231,7 +240,7 @@ export function parseCommandArgs(input: string): ParsedArgs {
|
|
|
231
240
|
|
|
232
241
|
async function runList(parsed: ParsedArgs, loc: CatalogLocation, deps: AgentCommandDeps): Promise<AgentCommandResult> {
|
|
233
242
|
if (parsed.positionals.length > 1) return result("error", "list", false, "list does not take extra arguments. Use /agents show <id> to inspect one definition.");
|
|
234
|
-
const listed = presentCatalog(readCatalog(loc), deps.enrich);
|
|
243
|
+
const listed = presentCatalog(readCatalog(loc), deps.enrich, deps.readSkillDefaults);
|
|
235
244
|
return {
|
|
236
245
|
...result("ok", "list", false, `Listed from a fresh catalog read. File edits show up on the next list or launch; /agents reload is not required for that.\n${listed.text}`),
|
|
237
246
|
diagnostics: listed.diagnostics,
|
|
@@ -241,7 +250,7 @@ async function runList(parsed: ParsedArgs, loc: CatalogLocation, deps: AgentComm
|
|
|
241
250
|
|
|
242
251
|
async function runReload(parsed: ParsedArgs, loc: CatalogLocation, deps: AgentCommandDeps): Promise<AgentCommandResult> {
|
|
243
252
|
if (parsed.positionals.length > 1) return result("error", "reload", false, "reload does not take extra arguments.");
|
|
244
|
-
const listed = presentCatalog(withAgentSessionSettings(refreshCatalog(loc), loc.sessionSettings), deps.enrich);
|
|
253
|
+
const listed = presentCatalog(withAgentSessionSettings(refreshCatalog(loc), loc.sessionSettings), deps.enrich, deps.readSkillDefaults);
|
|
245
254
|
return {
|
|
246
255
|
...result("ok", "reload", false, `Reloaded revision ${listed.revision} for inspection. The next launch reads the files again on its own; this command is not a prerequisite.\n${listed.text}`),
|
|
247
256
|
diagnostics: listed.diagnostics,
|
|
@@ -263,7 +272,7 @@ async function runShow(
|
|
|
263
272
|
return clarification(command, `${command} needs an id. UI is unavailable, so none was selected. Run /agents list and pass the id. Nothing was written.`);
|
|
264
273
|
}
|
|
265
274
|
if (host.mode === "tui" && host.ui.custom) {
|
|
266
|
-
const listed = presentCatalog(readCatalog(loc), deps.enrich);
|
|
275
|
+
const listed = presentCatalog(readCatalog(loc), deps.enrich, deps.readSkillDefaults);
|
|
267
276
|
return { ...result("ok", command, false, listed.text), diagnostics: listed.diagnostics, data: listed };
|
|
268
277
|
}
|
|
269
278
|
const ids = listCatalog(readCatalog(loc)).map((entry) => entry.id);
|
|
@@ -272,7 +281,7 @@ async function runShow(
|
|
|
272
281
|
if (!selected) return clarification(command, "Inspect was dismissed. Nothing was written.");
|
|
273
282
|
id = selected;
|
|
274
283
|
}
|
|
275
|
-
const view = presentCatalogEntry(readCatalog(loc), id, deps.enrich);
|
|
284
|
+
const view = presentCatalogEntry(readCatalog(loc), id, deps.enrich, deps.readSkillDefaults);
|
|
276
285
|
return {
|
|
277
286
|
ok: view.found,
|
|
278
287
|
status: view.found ? "ok" : "error",
|
|
@@ -375,7 +384,7 @@ async function runCreate(
|
|
|
375
384
|
if (!saved.ok || !saved.path) {
|
|
376
385
|
return { ...result("error", "create", false, saved.diagnostics.map((item) => item.message).join("\n") || "Create did not write a file."), diagnostics: saved.diagnostics };
|
|
377
386
|
}
|
|
378
|
-
const view = presentCatalogEntry(readCatalog(loc), id, deps.enrich);
|
|
387
|
+
const view = presentCatalogEntry(readCatalog(loc), id, deps.enrich, deps.readSkillDefaults);
|
|
379
388
|
return {
|
|
380
389
|
ok: true,
|
|
381
390
|
status: "ok",
|
|
@@ -525,7 +534,7 @@ async function runImport(
|
|
|
525
534
|
if (!saved.ok || !saved.path) {
|
|
526
535
|
return { ...result("error", "import-codex", false, saved.diagnostics.map((item) => item.message).join("\n") || "Import did not write a file."), diagnostics: [...parsedSource.diagnostics, ...built.diagnostics, ...saved.diagnostics] };
|
|
527
536
|
}
|
|
528
|
-
const view = presentCatalogEntry(readCatalog(loc), built.definition.id, deps.enrich);
|
|
537
|
+
const view = presentCatalogEntry(readCatalog(loc), built.definition.id, deps.enrich, deps.readSkillDefaults);
|
|
529
538
|
const launchNote = view.catalogLaunchable
|
|
530
539
|
? "Catalog validation passed. Definition validity is not launchability."
|
|
531
540
|
: "The file was saved and is not launchable.";
|
|
@@ -745,11 +754,21 @@ async function finishInspection(host: AgentCommandHost, commandResult: AgentComm
|
|
|
745
754
|
let viewportHeight = 30;
|
|
746
755
|
await host.ui.custom<void>((tui, theme, _keys, done) =>
|
|
747
756
|
createCatalogComponent(entries, theme, () => tui.requestRender(), () => done(), view?.id, deps.sessionSettings ? {
|
|
748
|
-
get: () => presentCatalog(readCatalog(location(host, deps)), deps.enrich),
|
|
757
|
+
get: () => presentCatalog(readCatalog(location(host, deps)), deps.enrich, deps.readSkillDefaults),
|
|
749
758
|
models: () => deps.editableModels?.() ?? [],
|
|
750
759
|
scopedModels: () => host.scopedModels ?? [],
|
|
751
760
|
settings: () => deps.sessionSettings!.snapshot(),
|
|
752
761
|
change: (id, key, value) => deps.sessionSettings!.change(id, key, value),
|
|
762
|
+
changeSkills(entry, edit) {
|
|
763
|
+
const result = saveSkillExposure({ ...location(host, deps), entry }, edit);
|
|
764
|
+
if (result.ok && result.path) {
|
|
765
|
+
commandResult.wrote = true;
|
|
766
|
+
commandResult.path = result.path;
|
|
767
|
+
commandResult.scope = result.scope;
|
|
768
|
+
}
|
|
769
|
+
return { ok: result.ok, message: result.message };
|
|
770
|
+
},
|
|
771
|
+
discoverSkills: () => deps.discoveredSkills ?? [],
|
|
753
772
|
save(id) {
|
|
754
773
|
const loc = location(host, deps);
|
|
755
774
|
const saved = saveAgentSessionDefaults(loadCatalog(loc), id, deps.sessionSettings!.snapshot(), loc);
|
|
@@ -800,7 +819,7 @@ async function finishInspection(host: AgentCommandHost, commandResult: AgentComm
|
|
|
800
819
|
});
|
|
801
820
|
if (deps.sessionSettings) {
|
|
802
821
|
const current = readCatalog(location(host, deps));
|
|
803
|
-
const refreshed = view ? presentCatalogEntry(current, view.id, deps.enrich) : presentCatalog(current, deps.enrich);
|
|
822
|
+
const refreshed = view ? presentCatalogEntry(current, view.id, deps.enrich, deps.readSkillDefaults) : presentCatalog(current, deps.enrich, deps.readSkillDefaults);
|
|
804
823
|
commandResult.data = refreshed;
|
|
805
824
|
commandResult.message = refreshed.text;
|
|
806
825
|
}
|
package/agent-inspection.ts
CHANGED
|
@@ -12,17 +12,17 @@ import { formatDiagnostic, shortRoleName, type Diagnostic } from "./catalog-sche
|
|
|
12
12
|
import type { CatalogSnapshot } from "./catalog-store.ts";
|
|
13
13
|
import { loadConfig, normalizeTools, SAFE_DEFAULT_TOOLS, type SubagentConfig } from "./config.ts";
|
|
14
14
|
import { resolveExtensions } from "./extensions.ts";
|
|
15
|
+
import { configuredSkillExposure } from "./skills.ts";
|
|
15
16
|
import type { PermissionProfile } from "./permission-policy.ts";
|
|
16
17
|
|
|
17
18
|
export const LEGACY_CAPABILITY_CONTROLS = [
|
|
18
19
|
"tool selection",
|
|
19
20
|
"extension loading",
|
|
20
|
-
"skills setup",
|
|
21
21
|
"sandbox and workspace",
|
|
22
22
|
"nested delegation",
|
|
23
23
|
] as const;
|
|
24
24
|
|
|
25
|
-
export const CAPABILITY_NOTE = "Tool selection, extension loading,
|
|
25
|
+
export const CAPABILITY_NOTE = "Tool selection, extension loading, sandbox and workspace, and nested delegation stay on the existing spawn path. Skill exposure is the one launch value a definition carries (`defaults.skills` / `overrides.skills`) because the launcher reproduces it exactly; like those controls it grants no extra tools or permissions, it only narrows which skills the child can see. A role name or instruction that says read-only is not enforcement.";
|
|
26
26
|
|
|
27
27
|
/** Existing spawn defaults a catalog launch uses when the caller does not override them. Not grants. */
|
|
28
28
|
export interface EffectiveLaunchCapabilities {
|
|
@@ -75,6 +75,16 @@ export type LaunchEnricher = (input: {
|
|
|
75
75
|
snapshotDigest: string;
|
|
76
76
|
}) => LaunchEnrichment | undefined;
|
|
77
77
|
|
|
78
|
+
/** The active default a launch would use when the definition chooses nothing. */
|
|
79
|
+
export interface SkillDefaultsSnapshot {
|
|
80
|
+
/** Explicit session discovery is `undefined`; none is `[]`. */
|
|
81
|
+
value?: readonly string[] | null;
|
|
82
|
+
source: "session" | "config" | "default";
|
|
83
|
+
error?: string;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export type ReadSkillDefaults = () => SkillDefaultsSnapshot;
|
|
87
|
+
|
|
78
88
|
export interface OperationField {
|
|
79
89
|
value: string | null;
|
|
80
90
|
source: "agent-override" | "role-default" | "absent";
|
|
@@ -133,6 +143,22 @@ export interface OperationView {
|
|
|
133
143
|
preferenceSources?: Partial<Record<"model" | "effort", { scope: "user" | "project"; path: string; bundled?: boolean }>>;
|
|
134
144
|
instructions?: string;
|
|
135
145
|
fields?: { model: OperationField; effort: OperationField; tier: OperationField };
|
|
146
|
+
/** Skill exposure the definition resolves to; absent is discovery. */
|
|
147
|
+
skills?: {
|
|
148
|
+
value: string[] | null;
|
|
149
|
+
source: OperationField["source"];
|
|
150
|
+
explicit: boolean;
|
|
151
|
+
inherited: boolean;
|
|
152
|
+
/** Global `defaultSkills`; null when the current config sets none. */
|
|
153
|
+
global: string[] | null;
|
|
154
|
+
/** What a launch with no `skills` option would use for this definition. */
|
|
155
|
+
effective: {
|
|
156
|
+
mode: "discovery" | "none" | "explicit" | "error";
|
|
157
|
+
paths: string[];
|
|
158
|
+
source: "agent-override" | "role-default" | "session" | "global" | "discovery";
|
|
159
|
+
error?: string;
|
|
160
|
+
};
|
|
161
|
+
};
|
|
136
162
|
/** The definition's own default model and effort (role default, or the agent's override or inherited value). Null when neither is set. */
|
|
137
163
|
defaults: DefinitionDefaults | null;
|
|
138
164
|
requestedModel: string | null;
|
|
@@ -225,8 +251,12 @@ export function describeDefaultLaunchCapabilities(input: {
|
|
|
225
251
|
};
|
|
226
252
|
}
|
|
227
253
|
|
|
228
|
-
export function presentCatalog(
|
|
229
|
-
|
|
254
|
+
export function presentCatalog(
|
|
255
|
+
snapshot: CatalogSnapshot,
|
|
256
|
+
enrich?: LaunchEnricher,
|
|
257
|
+
readSkillDefaults?: ReadSkillDefaults,
|
|
258
|
+
): OperationList {
|
|
259
|
+
const entries = listCatalog(snapshot).map((entry) => presentCatalogEntry(snapshot, entry.id, enrich, readSkillDefaults));
|
|
230
260
|
const lines = [
|
|
231
261
|
`Catalog revision ${snapshot.digest}.`,
|
|
232
262
|
"Definition validity is not launchability. Model availability is decided only by the injected resolver.",
|
|
@@ -239,7 +269,12 @@ export function presentCatalog(snapshot: CatalogSnapshot, enrich?: LaunchEnriche
|
|
|
239
269
|
return { revision: snapshot.digest, entries, diagnostics: [...snapshot.diagnostics], text: lines.join("\n") };
|
|
240
270
|
}
|
|
241
271
|
|
|
242
|
-
export function presentCatalogEntry(
|
|
272
|
+
export function presentCatalogEntry(
|
|
273
|
+
snapshot: CatalogSnapshot,
|
|
274
|
+
id: string,
|
|
275
|
+
enrich?: LaunchEnricher,
|
|
276
|
+
readSkillDefaults?: ReadSkillDefaults,
|
|
277
|
+
): OperationView {
|
|
243
278
|
const inspection = inspectCatalog(snapshot, id);
|
|
244
279
|
const entry = snapshot.roles.get(id) ?? snapshot.agents.get(id) ?? snapshot.blocked.find((item) => item.id === id);
|
|
245
280
|
const definitionValid = Boolean(entry?.structurallyValid && entry.definition);
|
|
@@ -309,6 +344,9 @@ export function presentCatalogEntry(snapshot: CatalogSnapshot, id: string, enric
|
|
|
309
344
|
const metadata = entry?.definition && "metadata" in entry.definition ? entry.definition.metadata : undefined;
|
|
310
345
|
const codex = metadata && typeof metadata === "object" ? (metadata as { codex?: { model?: unknown } }).codex : undefined;
|
|
311
346
|
const codexProvenanceModel = typeof codex?.model === "string" ? codex.model : null;
|
|
347
|
+
const skillDefaults = readSkillDefaults?.() ?? configuredSkillDefaults();
|
|
348
|
+
const globalSkills = skillDefaults.value === undefined || skillDefaults.value === null
|
|
349
|
+
? null : [...skillDefaults.value];
|
|
312
350
|
const view: OperationView = {
|
|
313
351
|
id,
|
|
314
352
|
found: inspection.found,
|
|
@@ -340,6 +378,14 @@ export function presentCatalogEntry(snapshot: CatalogSnapshot, id: string, enric
|
|
|
340
378
|
})),
|
|
341
379
|
instructions: inspection.instructions,
|
|
342
380
|
fields,
|
|
381
|
+
skills: inspection.skills ? {
|
|
382
|
+
value: inspection.skills.value ? [...inspection.skills.value] : null,
|
|
383
|
+
source: inspection.skills.source,
|
|
384
|
+
explicit: inspection.skills.explicit,
|
|
385
|
+
inherited: inspection.skills.source === "role-default",
|
|
386
|
+
global: globalSkills,
|
|
387
|
+
effective: effectiveSkillExposure(inspection.skills, skillDefaults),
|
|
388
|
+
} : undefined,
|
|
343
389
|
defaults: definitionDefaults(fields),
|
|
344
390
|
requestedModel: enrichment?.requestedModel ?? fields?.model.value ?? null,
|
|
345
391
|
requestedEffort: enrichment?.requestedEffort ?? (fields?.effort.value ?? null),
|
|
@@ -412,6 +458,13 @@ export function renderOperationView(view: OperationView): string {
|
|
|
412
458
|
lines.push(`${key}: value=${JSON.stringify(fieldValue.value)} source=${fieldValue.source} explicit=${yesNo(fieldValue.explicit)} inherited=${yesNo(fieldValue.inherited)}`);
|
|
413
459
|
}
|
|
414
460
|
}
|
|
461
|
+
lines.push(view.skills
|
|
462
|
+
? `skills: value=${JSON.stringify(view.skills.value)} mode=${skillMode(view.skills.value)} source=${view.skills.source} explicit=${yesNo(view.skills.explicit)} inherited=${yesNo(view.skills.inherited)}`
|
|
463
|
+
: "skills: mode=discovery source=default");
|
|
464
|
+
if (view.skills) {
|
|
465
|
+
lines.push(`skills effective: mode=${view.skills.effective.mode} source=${view.skills.effective.source} paths=${JSON.stringify(view.skills.effective.paths)}${view.skills.effective.error ? ` error=${JSON.stringify(view.skills.effective.error)}` : ""}`);
|
|
466
|
+
lines.push(`skills default: ${view.skills.global === null ? "not set" : JSON.stringify(view.skills.global)}`);
|
|
467
|
+
}
|
|
415
468
|
lines.push(`requested model: ${JSON.stringify(view.requestedModel)}`);
|
|
416
469
|
lines.push(`actual model: ${JSON.stringify(view.actualModel)}`);
|
|
417
470
|
lines.push(`requested effort: ${JSON.stringify(view.requestedEffort)}`);
|
|
@@ -457,6 +510,64 @@ function field(value: { value: string | null; source: OperationField["source"];
|
|
|
457
510
|
};
|
|
458
511
|
}
|
|
459
512
|
|
|
513
|
+
/** The child's observable skill modes: discovery, none, or exactly these paths. */
|
|
514
|
+
function skillMode(value: string[] | null): "discovery" | "none" | "explicit" {
|
|
515
|
+
if (value === null) return "discovery";
|
|
516
|
+
return value.length === 0 ? "none" : "explicit";
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
/** Saved global `defaultSkills`; a malformed or unreadable config stays visible as an error. */
|
|
520
|
+
function configuredSkillDefaults(): SkillDefaultsSnapshot {
|
|
521
|
+
try {
|
|
522
|
+
const exposure = configuredSkillExposure(loadConfig().defaultSkills);
|
|
523
|
+
return {
|
|
524
|
+
value: exposure.mode === "inherit" ? null : exposure.paths,
|
|
525
|
+
source: exposure.source,
|
|
526
|
+
};
|
|
527
|
+
} catch (error) {
|
|
528
|
+
return {
|
|
529
|
+
source: "config",
|
|
530
|
+
error: error instanceof Error ? error.message : String(error),
|
|
531
|
+
};
|
|
532
|
+
}
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
/** Where the active default resolves: session choice, saved global config, or discovery. */
|
|
536
|
+
function defaultSkillSource(defaults: SkillDefaultsSnapshot): NonNullable<OperationView["skills"]>["effective"]["source"] {
|
|
537
|
+
if (defaults.source === "session") return "session";
|
|
538
|
+
if (defaults.source === "config" && (defaults.error || (defaults.value !== undefined && defaults.value !== null))) return "global";
|
|
539
|
+
return "discovery";
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
/**
|
|
543
|
+
* The exposure a launch with no `skills` option would resolve for this
|
|
544
|
+
* definition. A definition's own list wins; otherwise an explicit null or an
|
|
545
|
+
* absent key falls to the active default and then discovery. A session choice
|
|
546
|
+
* that means discovery stays a session source, not a false discovery fallback.
|
|
547
|
+
*/
|
|
548
|
+
function effectiveSkillExposure(
|
|
549
|
+
field: { value: readonly string[] | null; source: OperationField["source"] },
|
|
550
|
+
defaults: SkillDefaultsSnapshot,
|
|
551
|
+
): NonNullable<OperationView["skills"]>["effective"] {
|
|
552
|
+
if (field.value !== null) {
|
|
553
|
+
const paths = [...field.value];
|
|
554
|
+
return {
|
|
555
|
+
mode: paths.length === 0 ? "none" : "explicit",
|
|
556
|
+
paths,
|
|
557
|
+
source: field.source === "agent-override" ? "agent-override" : "role-default",
|
|
558
|
+
};
|
|
559
|
+
}
|
|
560
|
+
const source = defaultSkillSource(defaults);
|
|
561
|
+
if (defaults.error) {
|
|
562
|
+
return { mode: "error", paths: [], source, error: defaults.error };
|
|
563
|
+
}
|
|
564
|
+
if (defaults.value === undefined || defaults.value === null) {
|
|
565
|
+
return { mode: "discovery", paths: [], source };
|
|
566
|
+
}
|
|
567
|
+
const paths = [...defaults.value];
|
|
568
|
+
return { mode: paths.length === 0 ? "none" : "explicit", paths, source };
|
|
569
|
+
}
|
|
570
|
+
|
|
460
571
|
function yesNo(value: boolean): "yes" | "no" {
|
|
461
572
|
return value ? "yes" : "no";
|
|
462
573
|
}
|
package/agents-catalog-tool.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* Creation, import, and reload stay on `/agents`, where confirmation can be
|
|
4
4
|
* collected. This module does not write files.
|
|
5
5
|
*/
|
|
6
|
-
import { presentCatalog, presentCatalogEntry, type LaunchEnricher } from "./agent-inspection.ts";
|
|
6
|
+
import { presentCatalog, presentCatalogEntry, type LaunchEnricher, type ReadSkillDefaults } from "./agent-inspection.ts";
|
|
7
7
|
import { canonicalCatalogId } from "./catalog-schema.ts";
|
|
8
8
|
import { defaultUserRoot, loadCatalog } from "./catalog-store.ts";
|
|
9
9
|
import { withAgentSessionSettings, type AgentSessionOverrides, type AgentSessionSettings } from "./agent-session-settings.ts";
|
|
@@ -28,6 +28,8 @@ export interface DiscoveryDeps {
|
|
|
28
28
|
bundledRoot?: string;
|
|
29
29
|
projectConfigDirName?: string;
|
|
30
30
|
enrich?: LaunchEnricher;
|
|
31
|
+
/** Live session/config default skill choice; absent keeps the legacy config read. */
|
|
32
|
+
readSkillDefaults?: ReadSkillDefaults;
|
|
31
33
|
sessionSettings?: AgentSessionSettings;
|
|
32
34
|
resolveHost?: (ctx: { cwd: string; isProjectTrusted(): boolean }) => DiscoveryHost;
|
|
33
35
|
}
|
|
@@ -72,14 +74,14 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
|
|
|
72
74
|
const host = resolveHost(ctx, deps);
|
|
73
75
|
const snapshot = withAgentSessionSettings(loadCatalog(host), host.sessionSettings ?? deps.sessionSettings?.snapshot());
|
|
74
76
|
if (action === "list") {
|
|
75
|
-
const listed = presentCatalog(snapshot, deps.enrich);
|
|
77
|
+
const listed = presentCatalog(snapshot, deps.enrich, deps.readSkillDefaults);
|
|
76
78
|
return {
|
|
77
79
|
content: [{ type: "text" as const, text: listed.text }],
|
|
78
80
|
details: { action, wrote: false, revision: listed.revision, entries: listed.entries, diagnostics: listed.diagnostics },
|
|
79
81
|
};
|
|
80
82
|
}
|
|
81
83
|
if (!params.id?.trim()) return toolError("inspect needs a role name or agent id. Call agents_catalog with action list to see them. Nothing was written.");
|
|
82
|
-
const view = presentCatalogEntry(snapshot, canonicalCatalogId(params.id), deps.enrich);
|
|
84
|
+
const view = presentCatalogEntry(snapshot, canonicalCatalogId(params.id), deps.enrich, deps.readSkillDefaults);
|
|
83
85
|
return {
|
|
84
86
|
content: [{ type: "text" as const, text: view.text }],
|
|
85
87
|
details: { action, wrote: false, view },
|
package/batch.mjs
CHANGED
|
@@ -11,6 +11,7 @@ import { BUILTIN_TOOLS } from "./extensions.mjs";
|
|
|
11
11
|
import { SAFE_CLEAN_TOOLS } from "./config.ts";
|
|
12
12
|
import { assertThinkingLevel } from "./thinking.ts";
|
|
13
13
|
import { assertTimingParams } from "./timing.ts";
|
|
14
|
+
import { normalizeSkillExposure } from "./skills.ts";
|
|
14
15
|
|
|
15
16
|
const VALID_CAPACITY_MODES = new Set(["reject", "launch-available"]);
|
|
16
17
|
|
|
@@ -84,6 +85,8 @@ export function mergeJobOptions(shared, job) {
|
|
|
84
85
|
thinking: job.thinking ?? shared?.thinking,
|
|
85
86
|
tools: job.tools ?? shared?.tools,
|
|
86
87
|
exclude_tools: job.exclude_tools ?? shared?.exclude_tools,
|
|
88
|
+
// `[]` is a real choice ("no skills"), so only a missing value inherits.
|
|
89
|
+
skills: job.skills ?? shared?.skills,
|
|
87
90
|
clean: job.clean ?? shared?.clean,
|
|
88
91
|
sandbox: job.sandbox ?? shared?.sandbox,
|
|
89
92
|
sandbox_dir: job.sandbox_dir ?? shared?.sandbox_dir,
|
|
@@ -171,6 +174,9 @@ export function validateBatchPlan({ shared, jobs, onCapacity, config }) {
|
|
|
171
174
|
const merged = mergeJobOptions(shared, job);
|
|
172
175
|
assertThinkingLevel(merged.thinking, `job ${i + 1} thinking`);
|
|
173
176
|
assertTimingParams(merged, `job ${i + 1} `);
|
|
177
|
+
// Validate every job's skill exposure before any job launches, so a bad
|
|
178
|
+
// path list cannot leave a half-launched batch behind.
|
|
179
|
+
normalizeSkillExposure(merged.skills, `job ${i + 1} (${merged.name ?? i + 1}) skills`);
|
|
174
180
|
if (merged.clean === true) {
|
|
175
181
|
// Validate the effective tool allowlist, which resolves in this order:
|
|
176
182
|
// per-job tools → shared tools → config.defaultTools → clean-safe built-ins.
|
package/catalog-resolver.ts
CHANGED
|
@@ -45,6 +45,11 @@ export interface EffectiveDefinition {
|
|
|
45
45
|
model: FieldValue<string>;
|
|
46
46
|
effort: FieldValue<ThinkingLevel>;
|
|
47
47
|
tier: FieldValue<string>;
|
|
48
|
+
/**
|
|
49
|
+
* Skill exposure for a launch of this definition. Absent means the child
|
|
50
|
+
* discovers the user catalog; `[]` means no skills; paths mean exactly those.
|
|
51
|
+
*/
|
|
52
|
+
skills: FieldValue<readonly string[]>;
|
|
48
53
|
launchable: boolean;
|
|
49
54
|
diagnostics: readonly Diagnostic[];
|
|
50
55
|
source?: DefinitionOrigin;
|
|
@@ -101,6 +106,7 @@ export interface CatalogInspection {
|
|
|
101
106
|
effort: FieldValue<ThinkingLevel>;
|
|
102
107
|
tier: FieldValue<string>;
|
|
103
108
|
};
|
|
109
|
+
skills?: FieldValue<readonly string[]>;
|
|
104
110
|
validation: readonly Diagnostic[];
|
|
105
111
|
launchable: boolean;
|
|
106
112
|
restrictions: readonly ExecutionRestriction[];
|
|
@@ -203,6 +209,7 @@ export function inspectCatalog(snapshot: CatalogSnapshot, id: string): CatalogIn
|
|
|
203
209
|
instructionMode: effective?.instructionMode,
|
|
204
210
|
instructions: effective?.instructions,
|
|
205
211
|
fields: effective ? { model: effective.model, effort: effective.effort, tier: effective.tier } : undefined,
|
|
212
|
+
skills: effective?.skills,
|
|
206
213
|
validation: resolved.diagnostics,
|
|
207
214
|
launchable: resolved.launchable,
|
|
208
215
|
restrictions: effective?.restrictions ?? entry.definition?.executionRestrictions ?? [],
|
|
@@ -250,6 +257,7 @@ function resolveRole(snapshot: CatalogSnapshot, roleId: string): Resolution {
|
|
|
250
257
|
model: fieldFromRole(preferences.model),
|
|
251
258
|
effort: fieldFromRole(preferences.effort),
|
|
252
259
|
tier: fieldFromRole(preferences.tier),
|
|
260
|
+
skills: fieldFromRole(preferences.skills),
|
|
253
261
|
launchable,
|
|
254
262
|
diagnostics,
|
|
255
263
|
source: originOf(entry),
|
|
@@ -350,6 +358,7 @@ function baseEffective(
|
|
|
350
358
|
model: inheritance ? inheritField(overrides, defaults, "model") : absentField(),
|
|
351
359
|
effort: inheritance ? inheritField(overrides, defaults, "effort") : absentField(),
|
|
352
360
|
tier: inheritance ? inheritField(overrides, defaults, "tier") : absentField(),
|
|
361
|
+
skills: inheritance ? inheritSkillPaths(overrides.skills, defaults.skills) : absentField(),
|
|
353
362
|
launchable: inheritance?.launchable ?? false,
|
|
354
363
|
diagnostics,
|
|
355
364
|
source: originOf(entry),
|
|
@@ -392,6 +401,24 @@ function inheritField<K extends PreferenceKey>(
|
|
|
392
401
|
return absentField();
|
|
393
402
|
}
|
|
394
403
|
|
|
404
|
+
/**
|
|
405
|
+
* Skill exposure inherits exactly like a preference: an agent override wins —
|
|
406
|
+
* including an explicit null, which suppresses the role's list — and otherwise
|
|
407
|
+
* the role default applies. `[]` is a real value ("no skills"), not absence.
|
|
408
|
+
*/
|
|
409
|
+
function inheritSkillPaths(
|
|
410
|
+
override: readonly string[] | null | undefined,
|
|
411
|
+
roleDefault: readonly string[] | null | undefined,
|
|
412
|
+
): FieldValue<readonly string[]> {
|
|
413
|
+
if (override !== undefined) {
|
|
414
|
+
return { value: override === null ? null : [...override], source: "agent-override", explicit: true };
|
|
415
|
+
}
|
|
416
|
+
if (roleDefault !== undefined && roleDefault !== null) {
|
|
417
|
+
return { value: [...roleDefault], source: "role-default", explicit: false };
|
|
418
|
+
}
|
|
419
|
+
return absentField();
|
|
420
|
+
}
|
|
421
|
+
|
|
395
422
|
function fieldFromRole<T>(value: T | null | undefined): FieldValue<T> {
|
|
396
423
|
if (value === undefined || value === null) return absentField();
|
|
397
424
|
return { value, source: "role-default", explicit: false };
|
|
@@ -448,6 +475,7 @@ function blockedEntry(snapshot: CatalogSnapshot, entry: CatalogEntry, diagnostic
|
|
|
448
475
|
model: absentField(),
|
|
449
476
|
effort: absentField(),
|
|
450
477
|
tier: absentField(),
|
|
478
|
+
skills: absentField(),
|
|
451
479
|
launchable: false,
|
|
452
480
|
diagnostics: withSummary,
|
|
453
481
|
source: originOf(entry),
|
package/catalog-runtime.ts
CHANGED
|
@@ -85,6 +85,8 @@ export interface CatalogRunRecord {
|
|
|
85
85
|
model: { value: string | null; source: string; explicit: boolean };
|
|
86
86
|
effort: { value: string | null; source: string; explicit: boolean };
|
|
87
87
|
tier: { value: string | null; source: string; explicit: boolean };
|
|
88
|
+
/** Absent exposure is discovery; [] is none; paths are exactly those skills. */
|
|
89
|
+
skills: { value: string[] | null; source: string; explicit: boolean };
|
|
88
90
|
};
|
|
89
91
|
modelSelection: ModelSelection;
|
|
90
92
|
effortSelection: EffortSelection;
|
|
@@ -379,6 +381,7 @@ export async function prepareCatalogJob(snapshot: CatalogSnapshot, job: CatalogJ
|
|
|
379
381
|
model: field(resolved.effective.model),
|
|
380
382
|
effort: field(resolved.effective.effort),
|
|
381
383
|
tier: field(resolved.effective.tier),
|
|
384
|
+
skills: skillField(resolved.effective.skills),
|
|
382
385
|
},
|
|
383
386
|
modelSelection: decision.modelSelection,
|
|
384
387
|
effortSelection: decision.effortSelection,
|
|
@@ -654,6 +657,11 @@ function field(value: { value: string | null; source: string; explicit: boolean
|
|
|
654
657
|
return { value: value.value, source: value.source, explicit: value.explicit };
|
|
655
658
|
}
|
|
656
659
|
|
|
660
|
+
/** The catalog's skill exposure, frozen on the run record like model and effort. */
|
|
661
|
+
function skillField(value: EffectiveDefinition["skills"]): CatalogRunRecord["effective"]["skills"] {
|
|
662
|
+
return { value: value.value ? [...value.value] : null, source: value.source, explicit: value.explicit };
|
|
663
|
+
}
|
|
664
|
+
|
|
657
665
|
function origin(value: EffectiveDefinition["source"]): CatalogRunRecord["source"] {
|
|
658
666
|
if (!value) return undefined;
|
|
659
667
|
return { scope: value.scope, path: value.path, contentDigest: value.contentDigest, id: value.id };
|