pi-better-subagents 0.19.1 → 0.20.1
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 +6 -4
- package/agent-commands.ts +9 -2
- package/agent-inspection.ts +18 -14
- package/catalog-runtime.ts +3 -1
- package/catalog-ui.ts +47 -30
- package/docs/usage.md +15 -11
- package/goal-provider.ts +52 -0
- package/index.ts +6 -43
- package/package.json +1 -1
- package/permission-policy.ts +2 -2
- package/sandbox.ts +2 -2
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# pi-better-subagents
|
|
2
2
|
|
|
3
|
-
`pi-better-subagents` is a Pi extension for detached, sandboxed subagent runs that keep the foreground Pi session free.
|
|
3
|
+
`pi-better-subagents` is a Pi extension for detached, optionally sandboxed subagent runs that keep the foreground Pi session free.
|
|
4
4
|
|
|
5
5
|
## Quick Answer
|
|
6
6
|
|
|
@@ -13,7 +13,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
|
|
|
13
13
|
## Core Features
|
|
14
14
|
- Non-blocking subagent launches, with an optional role and named-agent catalog (`docs/agent-catalog.md`, `docs/agent-catalog-lifecycle.md`).
|
|
15
15
|
- 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).
|
|
16
|
-
-
|
|
16
|
+
- Opt-in OS task sandboxing on macOS and Linux.
|
|
17
17
|
- Explicit tool allowlists for child sessions.
|
|
18
18
|
- 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`.
|
|
19
19
|
- Live background-work navigator for active runs.
|
|
@@ -31,6 +31,8 @@ Try it for one run:
|
|
|
31
31
|
pi -e npm:pi-better-subagents
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
+
Sandboxing starts Off for fresh settings, including standalone subagents without published settings. Explicit saved profiles and session choices remain unchanged. Set `sandbox:true` for a confined launch; `sandbox:false` cannot bypass a human-enabled Subagents profile.
|
|
35
|
+
|
|
34
36
|
Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or newer. `/sandbox` controls the independent Subagents profile, which each launch freezes. Pi handles its own startup, authentication, and provider connection; task tools obey the selected file, command, and network permissions. Outside project defaults to Write: tasks write across home and temp but can remove files outside the workspace only in temp, hidden home directories, and worktree folders (Linux keeps ordinary home folders read-only instead). Confined children admit `read`, `write`, `edit`, and `bash`, the guarded `apply_patch` (Codex patches that follow the file rules), and the trusted tools ticked in `/sandbox` → Subagents · Tools (default `web_fetch` and `web_search`), which run outside the file rules. Other requested tools are reported as unavailable, with the reason. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox) for the runtime boundary and supported configurations.
|
|
35
37
|
|
|
36
38
|
## Delegation Modes
|
|
@@ -92,8 +94,8 @@ Use this package for independent coding, review, research, or verification work
|
|
|
92
94
|
|-------------|---------|
|
|
93
95
|
| Pi | Required |
|
|
94
96
|
| Install method | `pi install npm:pi-better-subagents` |
|
|
95
|
-
| macOS sandboxing | Supported
|
|
96
|
-
| Linux sandboxing |
|
|
97
|
+
| macOS sandboxing | Supported when enabled |
|
|
98
|
+
| Linux sandboxing | Requires usable `bubblewrap` when enabled |
|
|
97
99
|
| Development runtime | Node.js 22+ |
|
|
98
100
|
|
|
99
101
|
## Update Or Remove
|
package/agent-commands.ts
CHANGED
|
@@ -87,7 +87,7 @@ export interface AgentCommandUi {
|
|
|
87
87
|
editor(title: string, prefill?: string): Promise<string | undefined>;
|
|
88
88
|
notify(message: string, type?: "info" | "warning" | "error"): void;
|
|
89
89
|
setWidget?(key: string, content: string[] | undefined): void;
|
|
90
|
-
custom?<T>(factory: (tui: { requestRender(): void }, theme: { fg(color: string, text: string): string }, keybindings: unknown, done: (value: T) => void) => unknown, options?: { overlay: boolean }): Promise<T>;
|
|
90
|
+
custom?<T>(factory: (tui: { requestRender(): void }, theme: { fg(color: string, text: string): string }, keybindings: unknown, done: (value: T) => void) => unknown, options?: { overlay: boolean; overlayOptions?: import("@earendil-works/pi-tui").OverlayOptions }): Promise<T>;
|
|
91
91
|
}
|
|
92
92
|
|
|
93
93
|
export interface AgentCommandHost {
|
|
@@ -724,6 +724,7 @@ async function finishInspection(host: AgentCommandHost, commandResult: AgentComm
|
|
|
724
724
|
const entries = catalog ?? { entries: [view!], diagnostics: commandResult.diagnostics, revision: "", text: "" };
|
|
725
725
|
try {
|
|
726
726
|
host.ui.setWidget?.("agents-catalog", undefined);
|
|
727
|
+
let viewportHeight = 30;
|
|
727
728
|
await host.ui.custom<void>((tui, theme, _keys, done) =>
|
|
728
729
|
createCatalogComponent(entries, theme, () => tui.requestRender(), () => done(), view?.id, deps.sessionSettings ? {
|
|
729
730
|
get: () => presentCatalog(readCatalog(location(host, deps)), deps.enrich),
|
|
@@ -740,7 +741,13 @@ async function finishInspection(host: AgentCommandHost, commandResult: AgentComm
|
|
|
740
741
|
}
|
|
741
742
|
return { ok: saved.ok, message: saved.ok ? `Defaults saved (${saved.scope}): ${id}.` : saved.diagnostics.map((item) => item.message).join(" ") };
|
|
742
743
|
},
|
|
743
|
-
} : undefined
|
|
744
|
+
} : undefined, () => viewportHeight), {
|
|
745
|
+
overlay: true,
|
|
746
|
+
overlayOptions: {
|
|
747
|
+
anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0,
|
|
748
|
+
visible: (_width, height) => { viewportHeight = height; return true; },
|
|
749
|
+
},
|
|
750
|
+
});
|
|
744
751
|
if (deps.sessionSettings) {
|
|
745
752
|
const current = readCatalog(location(host, deps));
|
|
746
753
|
const refreshed = view ? presentCatalogEntry(current, view.id, deps.enrich) : presentCatalog(current, deps.enrich);
|
package/agent-inspection.ts
CHANGED
|
@@ -12,7 +12,7 @@ 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 {
|
|
15
|
+
import type { PermissionProfile } from "./permission-policy.ts";
|
|
16
16
|
|
|
17
17
|
export const LEGACY_CAPABILITY_CONTROLS = [
|
|
18
18
|
"tool selection",
|
|
@@ -35,11 +35,13 @@ export interface EffectiveLaunchCapabilities {
|
|
|
35
35
|
providerExtensions: "resolved" | "unknown";
|
|
36
36
|
};
|
|
37
37
|
sandbox: {
|
|
38
|
-
/**
|
|
39
|
-
enabled:
|
|
40
|
-
/**
|
|
38
|
+
/** Current default spawn policy; sandbox:true can also request confinement. */
|
|
39
|
+
enabled: boolean;
|
|
40
|
+
/** Unknown for an enabled profile until launch verifies confinement. */
|
|
41
41
|
applied: boolean | "unknown";
|
|
42
42
|
writes: "working-directory" | "unconfined" | "unknown";
|
|
43
|
+
/** Published human profile, including retained details while disabled. Not catalog grants. */
|
|
44
|
+
permissions?: PermissionProfile;
|
|
43
45
|
};
|
|
44
46
|
workspace: {
|
|
45
47
|
cwd: string | "unknown";
|
|
@@ -171,12 +173,13 @@ const STATIC_CAPABILITIES = {
|
|
|
171
173
|
/**
|
|
172
174
|
* Values `spawnSubagentRun` uses when a catalog launch omits tools, sandbox,
|
|
173
175
|
* workspace, and nesting. A missing model does not invent provider extensions.
|
|
174
|
-
*
|
|
176
|
+
* Without a published profile, sandboxing defaults to off.
|
|
175
177
|
*/
|
|
176
178
|
export function describeDefaultLaunchCapabilities(input: {
|
|
177
179
|
config: SubagentConfig;
|
|
178
180
|
model?: string | null;
|
|
179
181
|
cwd?: string;
|
|
182
|
+
sandboxPermissions?: PermissionProfile;
|
|
180
183
|
}): EffectiveLaunchCapabilities {
|
|
181
184
|
const rawTools = input.config.defaultTools ?? SAFE_DEFAULT_TOOLS;
|
|
182
185
|
const toolAllowlist = typeof rawTools === "string" ? normalizeTools(rawTools) : "unknown";
|
|
@@ -199,22 +202,23 @@ export function describeDefaultLaunchCapabilities(input: {
|
|
|
199
202
|
providerExtensions: model ? "resolved" : "unknown",
|
|
200
203
|
};
|
|
201
204
|
}
|
|
202
|
-
let applied: boolean | "unknown" = "unknown";
|
|
203
|
-
try {
|
|
204
|
-
applied = sandboxSupported();
|
|
205
|
-
} catch {
|
|
206
|
-
applied = "unknown";
|
|
207
|
-
}
|
|
208
|
-
const writes = applied === true ? "working-directory" : applied === false ? "unconfined" : "unknown";
|
|
209
205
|
const cwd = typeof input.cwd === "string" && input.cwd.trim() !== "" ? input.cwd : "unknown";
|
|
206
|
+
const permissions = input.sandboxPermissions;
|
|
207
|
+
const enabled = permissions?.enabled ?? false;
|
|
210
208
|
return {
|
|
211
209
|
toolAllowlist,
|
|
212
210
|
extensions,
|
|
213
|
-
sandbox: {
|
|
211
|
+
sandbox: {
|
|
212
|
+
enabled,
|
|
213
|
+
applied: enabled ? "unknown" : false,
|
|
214
|
+
// Profiles can permit outside writes or disallow project writes.
|
|
215
|
+
writes: enabled ? "unknown" : "unconfined",
|
|
216
|
+
...(permissions ? { permissions } : {}),
|
|
217
|
+
},
|
|
214
218
|
workspace: {
|
|
215
219
|
cwd,
|
|
216
220
|
gitClone: false,
|
|
217
|
-
sandboxRoot:
|
|
221
|
+
sandboxRoot: enabled ? cwd : null,
|
|
218
222
|
},
|
|
219
223
|
nesting: { allowNested: false },
|
|
220
224
|
};
|
package/catalog-runtime.ts
CHANGED
|
@@ -24,6 +24,7 @@ import { resolveRoleAssignment, type RoleAssignment } from "./role-assignment.ts
|
|
|
24
24
|
import { configureTierPolicy, DEFAULT_TIER_POLICY, type TierPolicy, type TierSpec } from "./tier-policy.ts";
|
|
25
25
|
import { canonicalAgentId, canonicalRoleId, shortRoleName, type Diagnostic, type ThinkingLevel } from "./catalog-schema.ts";
|
|
26
26
|
import { withAgentSessionSettings, type AgentSessionOverrides } from "./agent-session-settings.ts";
|
|
27
|
+
import { currentSandboxPermissions } from "./permission-policy.ts";
|
|
27
28
|
|
|
28
29
|
export interface CatalogHost {
|
|
29
30
|
cwd: string;
|
|
@@ -161,7 +162,7 @@ export function loadLaunchSnapshot(host: CatalogHost): CatalogSnapshot {
|
|
|
161
162
|
}), host.getSessionSettings?.() ?? host.sessionSettings);
|
|
162
163
|
}
|
|
163
164
|
|
|
164
|
-
export function createLaunchEnricher(): LaunchEnricher {
|
|
165
|
+
export function createLaunchEnricher(pi?: unknown): LaunchEnricher {
|
|
165
166
|
let cache: { key: string; rows: Map<string, CatalogResolutionAttachment> } | undefined;
|
|
166
167
|
return ({ inspection, snapshotDigest }) => {
|
|
167
168
|
const host = notedHost.current;
|
|
@@ -207,6 +208,7 @@ export function createLaunchEnricher(): LaunchEnricher {
|
|
|
207
208
|
config,
|
|
208
209
|
model: enrichment.actualModel,
|
|
209
210
|
cwd: host.cwd,
|
|
211
|
+
sandboxPermissions: currentSandboxPermissions(pi)?.subagentPermissions,
|
|
210
212
|
}),
|
|
211
213
|
},
|
|
212
214
|
};
|
package/catalog-ui.ts
CHANGED
|
@@ -34,16 +34,18 @@ function cell(value: string, width: number): string {
|
|
|
34
34
|
|
|
35
35
|
export function catalogColumns(entry: OperationView | null, width: number): string {
|
|
36
36
|
const available = Math.max(1, width - 2);
|
|
37
|
-
const sourceWidth = available >=
|
|
38
|
-
const stateWidth = available >=
|
|
39
|
-
const
|
|
40
|
-
const
|
|
41
|
-
const
|
|
37
|
+
const sourceWidth = available >= 82 ? 11 : 0;
|
|
38
|
+
const stateWidth = available >= 60 ? 10 : 0;
|
|
39
|
+
const effortWidth = available >= 32 ? 7 : 0;
|
|
40
|
+
const gaps = (sourceWidth ? 2 : 0) + (stateWidth ? 2 : 0) + (effortWidth ? 2 : 0) + 2;
|
|
41
|
+
const modelWidth = Math.min(Math.max(1, available - gaps - effortWidth - sourceWidth - stateWidth - 1), Math.min(28, Math.max(20, Math.floor(available * 0.3))));
|
|
42
|
+
const nameWidth = Math.max(1, available - modelWidth - effortWidth - sourceWidth - stateWidth - gaps);
|
|
42
43
|
const name = entry ? entry.identity.name || entry.id : "NAME";
|
|
43
44
|
const model = entry ? modelLabel(entry) : "MODEL";
|
|
44
45
|
const source = entry ? entry.identity.scope ?? "unknown" : "SOURCE";
|
|
45
46
|
const status = entry ? stateLabel(entry) : "STATE";
|
|
46
|
-
|
|
47
|
+
const effort = entry ? entry.actualEffort ?? entry.fields?.effort.value ?? "(unset)" : "EFFORT";
|
|
48
|
+
return [cell(name, nameWidth), cell(model, modelWidth), ...(effortWidth ? [cell(effort, effortWidth)] : []), ...(sourceWidth ? [cell(source, sourceWidth)] : []), ...(stateWidth ? [cell(status, stateWidth)] : [])].join(" ").trimEnd();
|
|
47
49
|
}
|
|
48
50
|
|
|
49
51
|
function wrapLine(text: string, width: number): string[] {
|
|
@@ -60,7 +62,7 @@ function wrapLine(text: string, width: number): string[] {
|
|
|
60
62
|
return rows;
|
|
61
63
|
}
|
|
62
64
|
|
|
63
|
-
export function catalogDetailLines(entry: OperationView): string[] {
|
|
65
|
+
export function catalogDetailLines(entry: OperationView, editable = false): string[] {
|
|
64
66
|
const lines = [
|
|
65
67
|
`${entry.identity.name || entry.id} · ${entry.identity.kind ?? "unknown"}`,
|
|
66
68
|
entry.id,
|
|
@@ -73,8 +75,7 @@ export function catalogDetailLines(entry: OperationView): string[] {
|
|
|
73
75
|
"",
|
|
74
76
|
"Configuration",
|
|
75
77
|
...(entry.fields ? [
|
|
76
|
-
fieldLine("Model", entry.fields.model),
|
|
77
|
-
fieldLine("Effort", entry.fields.effort),
|
|
78
|
+
...(!editable ? [fieldLine("Model", entry.fields.model), fieldLine("Effort", entry.fields.effort)] : []),
|
|
78
79
|
fieldLine("Tier", entry.fields.tier),
|
|
79
80
|
] : []),
|
|
80
81
|
`Actual ${entry.actualModel ?? "not resolved"}${entry.actualEffort ? ` · ${entry.actualEffort}` : ""}`,
|
|
@@ -95,9 +96,10 @@ export function createCatalogComponent(
|
|
|
95
96
|
close: () => void,
|
|
96
97
|
initialId?: string,
|
|
97
98
|
editor?: CatalogEditor,
|
|
99
|
+
getHeight: () => number = () => 30,
|
|
98
100
|
) {
|
|
99
101
|
let selectedId = initialId ?? catalog.entries[0]?.id;
|
|
100
|
-
let mode: "list" | "detail" | "prompt"
|
|
102
|
+
let mode: "list" | "detail" | "prompt" = initialId ? "detail" : "list";
|
|
101
103
|
let query = "";
|
|
102
104
|
let scroll = 0;
|
|
103
105
|
let settingRow = 0;
|
|
@@ -159,7 +161,7 @@ export function createCatalogComponent(
|
|
|
159
161
|
const selected = () => filtered().find((entry) => entry.id === selectedId);
|
|
160
162
|
const detailRows = (entry: OperationView, width: number) => (mode === "prompt"
|
|
161
163
|
? [`${entry.identity.name || entry.id} · effective instructions`, "", ...(entry.instructions?.split("\n") ?? ["(none)"])]
|
|
162
|
-
: catalogDetailLines(entry))
|
|
164
|
+
: catalogDetailLines(entry, !!editor))
|
|
163
165
|
.flatMap((text) => text ? wrapLine(text, Math.max(1, width - 2)) : [""]);
|
|
164
166
|
let lastDetailWidth = 80;
|
|
165
167
|
|
|
@@ -168,21 +170,32 @@ export function createCatalogComponent(
|
|
|
168
170
|
set focused(value: boolean) { focused = value; search.focused = value && !!picker && pickerKey === "model"; },
|
|
169
171
|
render(width: number): string[] {
|
|
170
172
|
const safeWidth = Math.max(1, width);
|
|
173
|
+
const height = Math.max(1, Math.floor(getHeight()));
|
|
174
|
+
const footerRows = (editor && mode !== "prompt" ? 2 : 0) + (message ? 2 : 0);
|
|
175
|
+
const diagnosticRows = Math.min(catalog.diagnostics.length, 3);
|
|
176
|
+
const listSize = Math.max(1, height - 5 - footerRows - diagnosticRows - 1);
|
|
177
|
+
const controlRows = editor && mode === "detail" ? (safeWidth < 42 ? 5 : 3) : 0;
|
|
178
|
+
const detailSize = Math.max(1, height - 5 - footerRows - controlRows);
|
|
179
|
+
const fit = (lines: string[]) => {
|
|
180
|
+
const result = lines.slice(0, height).map(line);
|
|
181
|
+
while (result.length < height) result.push("");
|
|
182
|
+
return result;
|
|
183
|
+
};
|
|
171
184
|
lastDetailWidth = safeWidth;
|
|
172
185
|
const line = (text: string) => truncateToWidth(text, safeWidth);
|
|
173
186
|
const rows = filtered();
|
|
174
187
|
const current = selected();
|
|
175
188
|
const detailLines = current ? detailRows(current, safeWidth) : [];
|
|
176
189
|
const selectedIndex = rows.findIndex((entry) => entry.id === selectedId);
|
|
177
|
-
const start = Math.max(0, Math.min(selectedIndex -
|
|
178
|
-
|
|
190
|
+
const start = Math.max(0, Math.min(selectedIndex - Math.floor(listSize / 2), rows.length - listSize));
|
|
191
|
+
scroll = Math.max(0, Math.min(scroll, detailLines.length - detailSize));
|
|
192
|
+
if (picker) return fit([
|
|
179
193
|
theme.fg("accent", `Agents / ${pickerKey}`), "",
|
|
180
194
|
...(pickerKey === "model" ? search.render(safeWidth) : []),
|
|
181
195
|
...picker.render(safeWidth),
|
|
182
196
|
...(message ? [theme.fg(error ? "error" : "muted", message)] : []),
|
|
183
|
-
]
|
|
184
|
-
const
|
|
185
|
-
theme.fg("accent", `Agents / ${current.identity.name || current.id}`), "",
|
|
197
|
+
]);
|
|
198
|
+
const controls = editor && mode === "detail" && current ? [
|
|
186
199
|
...["Model", "Effort"].flatMap((label, index) => {
|
|
187
200
|
const key = index === 0 ? "model" : "effort";
|
|
188
201
|
const field = current.fields?.[key];
|
|
@@ -194,38 +207,41 @@ export function createCatalogComponent(
|
|
|
194
207
|
const text = `${settingRow === index ? "> " : " "}${label.padEnd(18)} ${value}`;
|
|
195
208
|
if (safeWidth < 42) {
|
|
196
209
|
const title = `${settingRow === index ? "> " : " "}${label}`;
|
|
197
|
-
return [settingRow === index ? highlight(title, safeWidth) : title,
|
|
210
|
+
return [settingRow === index ? highlight(title, safeWidth) : title, ` ${truncateToWidth(value, Math.max(1, safeWidth - 2))}`];
|
|
198
211
|
}
|
|
199
212
|
return [settingRow === index ? highlight(text, safeWidth) : text];
|
|
200
213
|
}),
|
|
201
|
-
] : mode !== "list" && current ? [
|
|
202
|
-
theme.fg("accent", mode === "prompt" ? "Agents / prompt" : "Agents / inspect"),
|
|
203
|
-
theme.fg("dim", mode === "prompt" ? "← details · ↑↓ scroll · Esc close" : `${editor ? "e settings · " : ""}p prompt · ← list · ↑↓ scroll · Esc close`),
|
|
204
214
|
"",
|
|
205
|
-
|
|
215
|
+
] : [];
|
|
216
|
+
const lines = mode !== "list" && current ? [
|
|
217
|
+
theme.fg("accent", mode === "prompt" ? "Agents / prompt" : editor ? `Agents / ${current.identity.name || current.id}` : "Agents / inspect"),
|
|
218
|
+
theme.fg("dim", mode === "prompt" ? "← details · ↑↓ scroll · Esc back" : `${editor ? "Enter change · " : ""}p prompt · ← list · ↑↓ ${editor ? "select / scroll" : "scroll"} · Esc back`),
|
|
219
|
+
"",
|
|
220
|
+
...controls,
|
|
221
|
+
...detailLines.slice(scroll, scroll + detailSize).map((text, i) =>
|
|
206
222
|
i === 0 && scroll === 0 ? theme.fg("accent", text) : text),
|
|
207
223
|
"",
|
|
208
|
-
theme.fg("dim", `Showing ${scroll + 1}-${Math.min(scroll +
|
|
224
|
+
theme.fg("dim", `Showing ${scroll + 1}-${Math.min(scroll + detailSize, detailLines.length)} of ${detailLines.length} lines`),
|
|
209
225
|
] : [
|
|
210
226
|
theme.fg("accent", `Agents · ${catalog.entries.length} definitions`),
|
|
211
227
|
theme.fg("dim", "Type to filter · ↑↓ select · Enter inspect · Esc close"),
|
|
212
228
|
`Search ${query || "(all roles and agents)"}`,
|
|
213
229
|
"",
|
|
214
230
|
theme.fg("dim", ` ${catalogColumns(null, safeWidth)}`),
|
|
215
|
-
...rows.slice(start, start +
|
|
231
|
+
...rows.slice(start, start + listSize).map((entry) => {
|
|
216
232
|
const active = selectedId === entry.id;
|
|
217
233
|
const marker = active ? "›" : " ";
|
|
218
234
|
const text = `${marker} ${catalogColumns(entry, safeWidth)}`;
|
|
219
235
|
return active ? highlight(text, safeWidth) : text;
|
|
220
236
|
}),
|
|
221
237
|
...(rows.length === 0 ? [" No matching definitions"] : []),
|
|
222
|
-
...(rows.length >
|
|
238
|
+
...(rows.length > listSize ? [theme.fg("dim", ` ${start + 1}-${Math.min(start + listSize, rows.length)} of ${rows.length}`)] : []),
|
|
223
239
|
...catalog.diagnostics.slice(0, 2).map((diagnostic) => theme.fg("warning", `! ${diagnostic.message}`)),
|
|
224
240
|
...(catalog.diagnostics.length > 2 ? [theme.fg("warning", `! ${catalog.diagnostics.length - 2} more catalog diagnostics`)] : []),
|
|
225
241
|
];
|
|
226
|
-
if (editor && mode !== "prompt") lines.push("", theme.fg("dim",
|
|
242
|
+
if (editor && mode !== "prompt") lines.push("", theme.fg("dim", "ctrl+s Save selected defaults"));
|
|
227
243
|
if (message) lines.push("", theme.fg(error ? "error" : "muted", message));
|
|
228
|
-
return lines
|
|
244
|
+
return fit(lines);
|
|
229
245
|
},
|
|
230
246
|
handleInput(data: string): void {
|
|
231
247
|
const rows = filtered();
|
|
@@ -239,25 +255,26 @@ export function createCatalogComponent(
|
|
|
239
255
|
}
|
|
240
256
|
if (editor && matchesKey(data, "ctrl+s")) { save(); return; }
|
|
241
257
|
if (matchesKey(data, "escape") || matchesKey(data, "left")) {
|
|
242
|
-
if (mode === "prompt"
|
|
258
|
+
if (mode === "prompt") { mode = "detail"; scroll = 0; }
|
|
243
259
|
else if (mode === "detail") { mode = "list"; scroll = 0; }
|
|
244
260
|
else if (query) { query = ""; selectedId = catalog.entries[0]?.id; }
|
|
245
261
|
else { close(); return; }
|
|
246
262
|
} else if (matchesKey(data, "up") || matchesKey(data, "down")) {
|
|
247
263
|
const delta = matchesKey(data, "down") ? 1 : -1;
|
|
248
|
-
if (mode === "
|
|
264
|
+
if (mode === "detail" && editor && scroll === 0 && (delta < 0 || settingRow === 0)) settingRow = Math.max(0, Math.min(1, settingRow + delta));
|
|
249
265
|
else if (mode !== "list" && selected()) scroll = Math.max(0, Math.min(detailRows(selected()!, lastDetailWidth).length - 1, scroll + delta));
|
|
250
266
|
else if (rows.length) selectedId = rows[Math.max(0, Math.min(rows.length - 1, rows.findIndex((entry) => entry.id === selectedId) + delta))]?.id;
|
|
251
267
|
} else if (matchesKey(data, "enter") && mode === "list" && selected()) {
|
|
252
268
|
mode = "detail";
|
|
269
|
+
settingRow = 0;
|
|
253
270
|
scroll = 0;
|
|
254
271
|
} else if ((data === "p" || data === "P") && mode === "detail" && selected()) {
|
|
255
272
|
mode = "prompt";
|
|
256
273
|
scroll = 0;
|
|
257
274
|
} else if (editor && (data === "e" || data === "E") && mode === "detail" && selected()) {
|
|
258
|
-
mode = "settings";
|
|
259
275
|
settingRow = 0;
|
|
260
|
-
|
|
276
|
+
scroll = 0;
|
|
277
|
+
} else if (editor && mode === "detail" && (matchesKey(data, "enter") || data === " ")) {
|
|
261
278
|
try { edit(); } catch (cause) { report(cause instanceof Error ? cause.message : String(cause), true); }
|
|
262
279
|
} else if (mode === "list" && matchesKey(data, "backspace")) {
|
|
263
280
|
query = query.slice(0, -1);
|
package/docs/usage.md
CHANGED
|
@@ -75,10 +75,10 @@ is present; without this extension it uses adaptive guidance.
|
|
|
75
75
|
completion and **returns a result**. There is no mid-task child→parent blocking
|
|
76
76
|
call for a subagent to waste wall-clock on — a child missing a piece of info
|
|
77
77
|
resolves it from what it was given, or records it unavailable and returns.
|
|
78
|
-
- **
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
78
|
+
- **Sandboxing is opt-in.** Fresh Subagents settings start Off. Enable the
|
|
79
|
+
Subagents profile in `/sandbox` or request `sandbox:true` for kernel confinement.
|
|
80
|
+
An enabled human profile cannot be bypassed with `sandbox:false`. Explicit
|
|
81
|
+
saved profiles and session choices retain their values.
|
|
82
82
|
- **Observable.** A live status widget and on-demand queries show each run's
|
|
83
83
|
elapsed time and token/cost spend.
|
|
84
84
|
|
|
@@ -285,13 +285,16 @@ given.
|
|
|
285
285
|
|
|
286
286
|
## Autonomy & safety
|
|
287
287
|
|
|
288
|
-
|
|
289
|
-
|
|
288
|
+
Subagents start unconfined in fresh settings. Without published settings, an
|
|
289
|
+
omitted `sandbox` also starts unconfined. Explicit `sandbox:true` enables task
|
|
290
|
+
confinement without requiring another extension; `sandbox:false` cannot bypass
|
|
291
|
+
an enabled human profile. Saved enabled profiles and session choices stay enabled.
|
|
290
292
|
|
|
291
|
-
- **Task sandbox (
|
|
293
|
+
- **Task sandbox (opt-in, macOS and Linux).** Pi startup, authentication,
|
|
292
294
|
provider transport, and session persistence run as trusted runtime operations.
|
|
293
295
|
Admitted task tools run under `sandbox-exec` or Linux Bubblewrap. Project files
|
|
294
|
-
default to
|
|
296
|
+
default to Write & delete and outside files to Write. Task access to `~/.pi`
|
|
297
|
+
follows the outside and credential-file rules; runtime
|
|
295
298
|
control files remain protected. Commands use private scratch plus explicit
|
|
296
299
|
runtime exceptions for `/tmp` and the current user's macOS temporary and MDS
|
|
297
300
|
cache directories when Outside is Read or Read/write. Credential and control
|
|
@@ -306,7 +309,8 @@ it does not depend on any other extension being installed.
|
|
|
306
309
|
### Write sandbox
|
|
307
310
|
|
|
308
311
|
The shared `sandbox-core` and `task-sandbox` modules enforce task operations in
|
|
309
|
-
|
|
312
|
+
Main, Subagents, and Background tasks. All three sandbox switches default Off.
|
|
313
|
+
When enabled, Subagents
|
|
310
314
|
use Project files = Write & delete and Outside project = **Write**: tasks write
|
|
311
315
|
across home and temp (tool caches such as `~/.gradle` and `~/.npm` just work), but
|
|
312
316
|
outside the workspace they can only remove or rename files in temp, hidden home
|
|
@@ -741,8 +745,8 @@ sudo dnf install bubblewrap
|
|
|
741
745
|
sudo pacman -S bubblewrap
|
|
742
746
|
```
|
|
743
747
|
|
|
744
|
-
When `bwrap` is absent, explicit sandbox requests
|
|
745
|
-
|
|
748
|
+
When `bwrap` is absent, explicit sandbox requests and enabled human profiles
|
|
749
|
+
fail with an installation hint. Unconfined launches need no backend. Once
|
|
746
750
|
`bwrap` is selected, a launch failure fails closed rather than retrying the child
|
|
747
751
|
without confinement.
|
|
748
752
|
|
package/goal-provider.ts
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { belongsToOrigin, effectiveStatus, listMetasForParent, onMetaChanged } from "./registry.ts";
|
|
3
|
+
|
|
4
|
+
const GOAL_READY_EVENT = "pi-better-goal:ready";
|
|
5
|
+
const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
|
|
6
|
+
const goalReadySubscriptions = new WeakSet<ExtensionAPI>();
|
|
7
|
+
|
|
8
|
+
export function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
|
|
9
|
+
const emitProvider = (): void => {
|
|
10
|
+
pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
|
|
11
|
+
id: "subagents",
|
|
12
|
+
label: "Subagents",
|
|
13
|
+
scope: "session",
|
|
14
|
+
getActivity: (ctx?: ExtensionContext) => {
|
|
15
|
+
let sessionId: string | undefined;
|
|
16
|
+
try {
|
|
17
|
+
sessionId = ctx?.sessionManager?.getSessionId();
|
|
18
|
+
} catch {
|
|
19
|
+
sessionId = undefined;
|
|
20
|
+
}
|
|
21
|
+
const origin = ctx ? { cwd: ctx.cwd, sessionId } : undefined;
|
|
22
|
+
return {
|
|
23
|
+
providerId: "subagents",
|
|
24
|
+
label: "Subagents",
|
|
25
|
+
items: listMetasForParent(process.pid)
|
|
26
|
+
.filter((meta) => !origin || belongsToOrigin(meta, origin))
|
|
27
|
+
.map((meta) => {
|
|
28
|
+
const status = effectiveStatus(meta);
|
|
29
|
+
const active = status === "running" || status === "orphaned";
|
|
30
|
+
return {
|
|
31
|
+
id: meta.id,
|
|
32
|
+
...(meta.name ? { label: meta.name } : {}),
|
|
33
|
+
status,
|
|
34
|
+
active,
|
|
35
|
+
unhealthy: status === "orphaned",
|
|
36
|
+
terminal: !active,
|
|
37
|
+
attention: status === "orphaned" || status === "failed" || status === "killed" || status === "lost" || status === "exited",
|
|
38
|
+
startedAt: meta.startedAt,
|
|
39
|
+
...(meta.endedAt !== undefined ? { endedAt: meta.endedAt } : {}),
|
|
40
|
+
};
|
|
41
|
+
}),
|
|
42
|
+
};
|
|
43
|
+
},
|
|
44
|
+
onActivityChanged: onMetaChanged,
|
|
45
|
+
});
|
|
46
|
+
};
|
|
47
|
+
if (!goalReadySubscriptions.has(pi)) {
|
|
48
|
+
pi.events?.on?.(GOAL_READY_EVENT, emitProvider);
|
|
49
|
+
goalReadySubscriptions.add(pi);
|
|
50
|
+
}
|
|
51
|
+
emitProvider();
|
|
52
|
+
}
|
package/index.ts
CHANGED
|
@@ -163,6 +163,7 @@ import {
|
|
|
163
163
|
type CatalogJobFields,
|
|
164
164
|
type CatalogRunRecord,
|
|
165
165
|
} from "./catalog-runtime.ts";
|
|
166
|
+
import { registerSubagentsGoalProvider } from "./goal-provider.ts";
|
|
166
167
|
import { defaultUserRoot, type CatalogSnapshot } from "./catalog-store.ts";
|
|
167
168
|
|
|
168
169
|
const SUBAGENT_MODE_ACTIONS: readonly AutocompleteItem[] = [
|
|
@@ -211,44 +212,6 @@ const SUBAGENT_ORCHESTRATION_GUIDELINES = [
|
|
|
211
212
|
"Do not treat launching a subagent as completion of the parent milestone; relevant terminal results must be inspected and integrated before verification or completion.",
|
|
212
213
|
];
|
|
213
214
|
|
|
214
|
-
const GOAL_READY_EVENT = "pi-better-goal:ready";
|
|
215
|
-
const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
|
|
216
|
-
const goalReadySubscriptions = new WeakSet<ExtensionAPI>();
|
|
217
|
-
|
|
218
|
-
function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
|
|
219
|
-
const emitProvider = (): void => {
|
|
220
|
-
pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
|
|
221
|
-
id: "subagents",
|
|
222
|
-
label: "Subagents",
|
|
223
|
-
getActivity: () => ({
|
|
224
|
-
providerId: "subagents",
|
|
225
|
-
label: "Subagents",
|
|
226
|
-
items: listMetasForParent(process.pid).map((meta) => {
|
|
227
|
-
const status = effectiveStatus(meta);
|
|
228
|
-
const active = status === "running" || status === "orphaned";
|
|
229
|
-
return {
|
|
230
|
-
id: meta.id,
|
|
231
|
-
...(meta.name ? { label: meta.name } : {}),
|
|
232
|
-
status,
|
|
233
|
-
active,
|
|
234
|
-
unhealthy: status === "orphaned",
|
|
235
|
-
terminal: !active,
|
|
236
|
-
attention: status === "orphaned" || status === "failed" || status === "killed" || status === "lost" || status === "exited",
|
|
237
|
-
startedAt: meta.startedAt,
|
|
238
|
-
...(meta.endedAt !== undefined ? { endedAt: meta.endedAt } : {}),
|
|
239
|
-
};
|
|
240
|
-
}),
|
|
241
|
-
}),
|
|
242
|
-
onActivityChanged: onMetaChanged,
|
|
243
|
-
});
|
|
244
|
-
};
|
|
245
|
-
if (!goalReadySubscriptions.has(pi)) {
|
|
246
|
-
pi.events?.on?.(GOAL_READY_EVENT, emitProvider);
|
|
247
|
-
goalReadySubscriptions.add(pi);
|
|
248
|
-
}
|
|
249
|
-
emitProvider();
|
|
250
|
-
}
|
|
251
|
-
|
|
252
215
|
// ---- retired live status widget ------------------------------------------
|
|
253
216
|
//
|
|
254
217
|
// The shared background-work navigator owns the active subagent list. This
|
|
@@ -1732,7 +1695,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
1732
1695
|
const callbackOrigin = callbackOriginFromContext(ctx);
|
|
1733
1696
|
activeCallbackOrigin = callbackOrigin;
|
|
1734
1697
|
|
|
1735
|
-
// Sandbox is
|
|
1698
|
+
// Sandbox is opt-in. sandbox_dir moves the confinement + working
|
|
1736
1699
|
// dir elsewhere. git_clone_workspace prepares a disposable clone with
|
|
1737
1700
|
// .git/ inside the writable root for Git-mutating sandboxed subagents.
|
|
1738
1701
|
const sandboxEnabled = permissionPlan.sandboxEnabled;
|
|
@@ -1949,7 +1912,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
1949
1912
|
...SUBAGENT_ORCHESTRATION_GUIDELINES,
|
|
1950
1913
|
"The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Without an agent or role, pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
|
|
1951
1914
|
...CATALOG_GUIDELINES,
|
|
1952
|
-
"
|
|
1915
|
+
"Subagent sandboxing defaults to off. Human settings in /sandbox control file, credential-file, command, and network permissions; sandbox:false cannot override an enabled human profile. Set sandbox:true to request kernel confinement, including without published settings. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
|
|
1953
1916
|
"Every run has harness-owned stall detection: no progress for stuck_minutes (default 10) wakes you once without stopping the run. Elapsed-time limits are opt-in: deadline_minutes steers the child to wrap up and later stops it after grace_minutes, while max_minutes stops it without grace. Do not set elapsed-time limits merely because a task may take a while; use them only when the work needs a real wall-clock bound.",
|
|
1954
1917
|
"Use git_clone_workspace:true when the subagent will mutate Git in a sandbox. The parent prepares a disposable, self-contained clone with a real .git/ directory inside the sandbox root, so linked-worktree metadata outside the sandbox cannot stall the child.",
|
|
1955
1918
|
],
|
|
@@ -1964,7 +1927,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
1964
1927
|
tools: Type.Optional(Type.String({ description: "Tool allowlist: comma-separated names the child may use (e.g. 'read,bash,web_fetch'). This ALSO selects which extensions load — only packages backing a requested tool are loaded. Defaults to the configured safe set." })),
|
|
1965
1928
|
exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist, applied on top of the allowlist." })),
|
|
1966
1929
|
clean: Type.Optional(Type.Boolean({ description: "Run a hermetic child with NO extensions at all (only built-ins: read, bash, edit, write). Default false — the extensions backing the requested tools load, so web_fetch and model auth (e.g. xai) work." })),
|
|
1967
|
-
sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile from /sandbox.
|
|
1930
|
+
sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile from /sandbox. Defaults to off without published settings. True requests kernel confinement; false cannot bypass an enabled human profile." })),
|
|
1968
1931
|
sandbox_dir: Type.Optional(Type.String({ description: "Confine writes to (and run the child in) this directory instead of the working dir. Created if missing." })),
|
|
1969
1932
|
callback: Type.Optional(Type.Boolean({ description: "Default TRUE: on completion, trigger a turn that calls subagent_result and presents the result. Set false to finish quietly — the result is then read on demand via subagent_result." })),
|
|
1970
1933
|
cwd: Type.Optional(Type.String({ description: "Working directory (default: current)." })),
|
|
@@ -2072,7 +2035,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
2072
2035
|
thinking: Type.Optional(Type.String({ description: "Reasoning effort applied to every job: off, minimal, low, medium, high, xhigh, or max." })),
|
|
2073
2036
|
tools: Type.Optional(Type.String({ description: "Tool allowlist applied to every job." })),
|
|
2074
2037
|
exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist applied to every job." })),
|
|
2075
|
-
sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile; false cannot override an enabled profile.
|
|
2038
|
+
sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile; false cannot override an enabled profile. Defaults to off without published settings; true requests kernel confinement." })),
|
|
2076
2039
|
sandbox_dir: Type.Optional(Type.String({ description: "Writable root for every job." })),
|
|
2077
2040
|
callback: Type.Optional(Type.Boolean({ description: "Default TRUE: post result back on completion." })),
|
|
2078
2041
|
clean: Type.Optional(Type.Boolean({ description: "Hermetic builtins-only child; no extensions load." })),
|
|
@@ -2306,7 +2269,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
2306
2269
|
sessionSettings: agentSessionSettings.snapshot(),
|
|
2307
2270
|
};
|
|
2308
2271
|
},
|
|
2309
|
-
enrich: createLaunchEnricher(),
|
|
2272
|
+
enrich: createLaunchEnricher(pi),
|
|
2310
2273
|
});
|
|
2311
2274
|
const openSettings = async (ctx: ExtensionCommandContext): Promise<void> => {
|
|
2312
2275
|
if (ctx.mode === "tui" && ctx.hasUI && typeof ctx.ui.custom === "function") {
|
package/package.json
CHANGED
package/permission-policy.ts
CHANGED
|
@@ -88,7 +88,7 @@ export function currentSandboxPermissions(pi: unknown): PermissionSnapshot | und
|
|
|
88
88
|
return mirror?.policy;
|
|
89
89
|
}
|
|
90
90
|
|
|
91
|
-
/** Resolve before allocating a run. Absent settings
|
|
91
|
+
/** Resolve before allocating a run. Absent settings require an explicit sandbox request. */
|
|
92
92
|
export function resolveSubagentPermissions(pi: unknown, requestedSandbox: boolean | undefined): {
|
|
93
93
|
sandboxEnabled: boolean;
|
|
94
94
|
enforced: boolean;
|
|
@@ -102,7 +102,7 @@ export function resolveSubagentPermissions(pi: unknown, requestedSandbox: boolea
|
|
|
102
102
|
throw new Error("Main sandbox profile disables commands. Enable commands in the sandbox UI before launching a subagent.");
|
|
103
103
|
}
|
|
104
104
|
const child = snapshot?.subagentPermissions;
|
|
105
|
-
if (!child) return { sandboxEnabled: requestedSandbox
|
|
105
|
+
if (!child) return { sandboxEnabled: requestedSandbox === true, enforced: false, tools };
|
|
106
106
|
if (child.enabled && requestedSandbox === false) {
|
|
107
107
|
throw new Error("Subagent sandbox is enforced by the human-enabled profile; sandbox:false cannot bypass it. Change Subagents permissions in the sandbox UI.");
|
|
108
108
|
}
|
package/sandbox.ts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* vendored here as `shared-sandbox-core.ts`. This file holds only the subagent
|
|
7
7
|
* shape of that call: the detached child's writable directory is the whole
|
|
8
8
|
* policy, and the wrapped executable is always the pi binary. Detached spawning
|
|
9
|
-
* policy (
|
|
9
|
+
* policy (opt-in or human-enabled profile) stays in permission-policy.ts and
|
|
10
10
|
* is passed through unchanged.
|
|
11
11
|
*/
|
|
12
12
|
|
|
@@ -61,7 +61,7 @@ export function sandboxSupported(): boolean {
|
|
|
61
61
|
}
|
|
62
62
|
|
|
63
63
|
/**
|
|
64
|
-
* Resolve the caller's
|
|
64
|
+
* Resolve the caller's activation and explicit-request policy before
|
|
65
65
|
* spawning. A selected backend always returns its wrapper; callers never retry
|
|
66
66
|
* the child directly when that wrapper exits or cannot initialize.
|
|
67
67
|
*/
|