@xzzpig/pi-subagents 0.14.0 → 0.15.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/CHANGELOG.md +239 -0
- package/README.md +7 -6
- package/agents/evidence-auditor.md +34 -0
- package/agents/researcher.md +23 -13
- package/agents/reviewer.md +3 -2
- package/docs/agents.md +55 -136
- package/docs/configuration.md +92 -14
- package/docs/extension-api.md +132 -74
- package/docs/fork-extensions.md +184 -0
- package/docs/missions.md +10 -2
- package/docs/models.md +11 -22
- package/docs/observability.md +63 -11
- package/docs/standalone-background.md +59 -0
- package/docs/tool-reference.md +42 -23
- package/docs/watchdog.md +39 -10
- package/docs/workflows.md +58 -19
- package/index.ts +5 -2
- package/inspector-runner.mjs +2 -2
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
- package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
- package/package.json +9 -4
- package/prompts/parallel-review.md +1 -1
- package/runner-peer-loader.mjs +24 -0
- package/runner-peer-preload.mjs +36 -0
- package/skills/pi-subagents/SKILL.md +34 -22
- package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
- package/skills/pi-subagents/references/execution-controls.md +27 -8
- package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
- package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
- package/skills/pi-subagents/references/review-and-validation.md +3 -3
- package/src/agents/advertised-agent-prompt.ts +94 -0
- package/src/agents/agent-eject.ts +339 -0
- package/src/agents/agent-management.ts +79 -387
- package/src/agents/agent-serializer.ts +6 -3
- package/src/agents/agents.ts +198 -72
- package/src/agents/builtin-names.ts +1 -0
- package/src/agents/chain-serializer.ts +5 -0
- package/src/agents/runtime-agent-registry.ts +7 -6
- package/src/api/agent-management.ts +2 -2
- package/src/api/delegation.ts +4 -0
- package/src/api/preflight.ts +131 -86
- package/src/api/required-child-extensions.ts +6 -0
- package/src/api/shared-types.ts +3 -1
- package/src/api/workflow-resources.ts +6 -0
- package/src/extension/config.ts +14 -37
- package/src/extension/fanout-child.ts +68 -5
- package/src/extension/herdr-pi-bridge.ts +164 -0
- package/src/extension/index.ts +141 -51
- package/src/extension/public-execution.ts +7 -6
- package/src/extension/rpc.ts +8 -21
- package/src/extension/schemas.ts +86 -84
- package/src/extension/tool-description.ts +32 -79
- package/src/inspectors/actions.ts +148 -0
- package/src/inspectors/ghostty/actions.ts +74 -0
- package/src/inspectors/ghostty/plugin.ts +17 -0
- package/src/inspectors/herdr/actions.ts +99 -179
- package/src/inspectors/herdr/plugin.ts +20 -0
- package/src/inspectors/herdr/project-panes.ts +4 -1
- package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
- package/src/inspectors/plugins.ts +8 -0
- package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
- package/src/inspectors/types.ts +51 -0
- package/src/integrations/pi-web-session-liveness.ts +73 -0
- package/src/intercom/intercom-bridge.ts +50 -8
- package/src/intercom/native-supervisor-channel.ts +142 -115
- package/src/intercom/supervisor-ui.ts +3 -2
- package/src/missions/workflow-state.ts +37 -16
- package/src/policy/authority.ts +4 -0
- package/src/profiles/profiles.ts +12 -6
- package/src/runs/background/active-async-capacity.ts +22 -18
- package/src/runs/background/active-run-index.ts +17 -1
- package/src/runs/background/async-execution.ts +359 -176
- package/src/runs/background/async-job-tracker.ts +41 -7
- package/src/runs/background/async-resume.ts +19 -12
- package/src/runs/background/async-retention.ts +20 -0
- package/src/runs/background/async-status-snapshot.ts +10 -12
- package/src/runs/background/async-status.ts +38 -35
- package/src/runs/background/auto-drain.ts +59 -35
- package/src/runs/background/binary-bootstrap.ts +38 -0
- package/src/runs/background/chain-append.ts +1 -1
- package/src/runs/background/chain-root-attachment.ts +22 -33
- package/src/runs/background/control-channel.ts +78 -44
- package/src/runs/background/fleet-view.ts +30 -2
- package/src/runs/background/notify.ts +193 -19
- package/src/runs/background/owned-process-tree.ts +35 -8
- package/src/runs/background/process-terminal.ts +23 -23
- package/src/runs/background/result-files.ts +8 -4
- package/src/runs/background/result-watcher.ts +19 -2
- package/src/runs/background/retained-nested-route-tracker.ts +96 -0
- package/src/runs/background/run-child-session.ts +118 -41
- package/src/runs/background/run-status.ts +78 -5
- package/src/runs/background/runner-aliases.ts +22 -5
- package/src/runs/background/runner-child-launch.ts +93 -0
- package/src/runs/background/runner-child-sessions.ts +5 -4
- package/src/runs/background/runner-http-dispatcher.ts +119 -0
- package/src/runs/background/scheduled-runs.ts +51 -18
- package/src/runs/background/stale-run-reconciler.ts +38 -12
- package/src/runs/background/steering.ts +20 -2
- package/src/runs/background/subagent-runner.ts +770 -444
- package/src/runs/background/subagent-wait.ts +179 -28
- package/src/runs/background/wait-completions.ts +79 -27
- package/src/runs/background/wait-subscriptions.ts +9 -3
- package/src/runs/background/wait-tool.ts +5 -3
- package/src/runs/foreground/async-steering-action.ts +37 -7
- package/src/runs/foreground/async-stop-action.ts +93 -3
- package/src/runs/foreground/execution.ts +174 -194
- package/src/runs/foreground/foreground-history.ts +5 -2
- package/src/runs/foreground/prompt-audit.ts +12 -6
- package/src/runs/foreground/subagent-executor.ts +915 -411
- package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
- package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
- package/src/runs/shared/acceptance.ts +54 -14
- package/src/runs/shared/agent-contract.ts +1 -1
- package/src/runs/shared/async-status-projection.ts +172 -78
- package/src/runs/shared/capability-ceiling.ts +2 -0
- package/src/runs/shared/child-hooks.ts +167 -3
- package/src/runs/shared/child-launch-plan.ts +15 -3
- package/src/runs/shared/child-launch.ts +49 -85
- package/src/runs/shared/child-lifecycle.ts +6 -3
- package/src/runs/shared/child-runtime-config.ts +8 -1
- package/src/runs/shared/child-session.ts +130 -24
- package/src/runs/shared/child-tool-plan.ts +149 -112
- package/src/runs/shared/completion-evidence.ts +2 -2
- package/src/runs/shared/completion-guard.ts +6 -3
- package/src/runs/shared/dynamic-fanout.ts +2 -2
- package/src/runs/shared/effective-system-prompt.ts +33 -0
- package/src/runs/shared/external-cli-contract.ts +11 -1
- package/src/runs/shared/external-cli-preflight.ts +6 -2
- package/src/runs/shared/external-cli-runner.ts +9 -7
- package/src/runs/shared/herdr-connection.ts +134 -0
- package/src/runs/shared/herdr-external-adapters.ts +169 -0
- package/src/runs/shared/herdr-machine.ts +279 -0
- package/src/runs/shared/herdr-pi-protocol.ts +59 -0
- package/src/runs/shared/herdr-placed-run.ts +263 -0
- package/src/runs/shared/host-step-status.ts +11 -11
- package/src/runs/shared/llm-intent-arbiter.ts +40 -21
- package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
- package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
- package/src/runs/shared/model-scope.ts +1 -1
- package/src/runs/shared/nested-events.ts +27 -34
- package/src/runs/shared/orca-progress-tabs.ts +7 -1
- package/src/runs/shared/parallel-handoff.ts +57 -12
- package/src/runs/shared/parallel-utils.ts +10 -4
- package/src/runs/shared/pi-spawn.ts +10 -0
- package/src/runs/shared/profile-extensions.ts +134 -0
- package/src/runs/shared/profile-launch-env.ts +113 -0
- package/src/runs/shared/readonly-drain-observation.ts +42 -0
- package/src/runs/shared/run-fanout-budget.ts +8 -8
- package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
- package/src/runs/shared/sandbox-profile-guard.ts +34 -0
- package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
- package/src/runs/shared/task-intent.ts +46 -13
- package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
- package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
- package/src/runs/shared/worktree-setup-command.ts +213 -0
- package/src/runs/shared/worktree.ts +437 -214
- package/src/shared/child-cache-retention.ts +43 -0
- package/src/shared/fork-context.ts +15 -72
- package/src/shared/launch-contract.ts +70 -8
- package/src/shared/model-response-aliases.ts +13 -0
- package/src/shared/opencode-session-headers.ts +30 -0
- package/src/shared/permission-profile.ts +14 -0
- package/src/shared/pruned-fork.ts +1 -1
- package/src/shared/required-child-extensions.ts +81 -0
- package/src/shared/sandbox-profile.ts +14 -0
- package/src/shared/settings.ts +5 -2
- package/src/shared/shortcuts.ts +0 -4
- package/src/shared/types.ts +163 -90
- package/src/shared/utils.ts +10 -2
- package/src/shared/watch-strategy.ts +2 -0
- package/src/shared/workflow-child-permit.ts +18 -13
- package/src/slash/delegation-adapters.ts +3 -1
- package/src/slash/delegation-request.ts +14 -0
- package/src/slash/slash-commands.ts +2 -7
- package/src/slash/subagents-admin.ts +31 -14
- package/src/tui/fleet-status.ts +165 -20
- package/src/tui/fleet.ts +30 -19
- package/src/tui/render.ts +210 -50
- package/src/watchdog/child-status.ts +28 -28
- package/src/watchdog/lsp-diagnostics.ts +1 -1
- package/src/watchdog/model-selection.ts +21 -1
- package/src/watchdog/permission-arbiter.ts +5 -2
- package/src/watchdog/register-child.ts +10 -2
- package/src/watchdog/register-main.ts +39 -35
- package/src/watchdog/render.ts +1 -1
- package/src/watchdog/review.ts +122 -74
- package/src/watchdog/rules.ts +1 -1
- package/src/watchdog/runtime.ts +100 -27
- package/src/watchdog/scope.ts +1 -1
- package/src/watchdog/settings.ts +3 -0
- package/src/watchdog/tool-actions.ts +13 -12
- package/src/watchdog/turn-delta.ts +23 -0
- package/src/watchdog/types.ts +5 -3
- package/src/watchdog/warning-format.ts +1 -1
- package/src/workflows/chat-progress.ts +3 -3
- package/src/workflows/scripted-workflow.ts +349 -26
- package/src/workflows/workflow-checklist.ts +17 -20
- package/src/workflows/workflow-child-summary.ts +57 -8
- package/src/workflows/workflow-preflight.ts +19 -19
- package/src/workflows/workflow-receipt.ts +24 -6
- package/src/workflows/workflow-resources.ts +108 -22
- package/src/workflows/workflow-settlement.ts +3 -0
- package/src/runs/shared/model-exclusions.ts +0 -373
- /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
package/docs/extension-api.md
CHANGED
|
@@ -2,6 +2,97 @@
|
|
|
2
2
|
|
|
3
3
|
Public seams for other Pi extensions and host integrations: the in-process RPC, the structured delegation API, launch preflight, capability ceilings, the background-work provider contract, and the Herdr integration.
|
|
4
4
|
|
|
5
|
+
## Trusted workflow resources
|
|
6
|
+
|
|
7
|
+
Loaded trusted TypeScript extensions can import `registerWorkflowResource` from `pi-subagents/workflow-resources`. This subpath does not load the main extension and exposes no resolver or permit constructor. Its exported types are `RegisterWorkflowResourceInput`, `WorkflowResourceDefinition`, and `WorkflowResourceRegistration`:
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
registerWorkflowResource({
|
|
11
|
+
sessionId: string,
|
|
12
|
+
definition: {
|
|
13
|
+
name: string,
|
|
14
|
+
version: number,
|
|
15
|
+
resolve(args: Readonly<Record<string, unknown>>):
|
|
16
|
+
| { script: string; hostCommands?: readonly { key: string; command: string }[] }
|
|
17
|
+
| { error: string },
|
|
18
|
+
},
|
|
19
|
+
}): { dispose(): void }
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Names are case-sensitive, at most 128 characters, and match `[A-Za-z0-9][A-Za-z0-9._-]*`; use an extension prefix. Versions are positive safe integers. Registration throws for invalid input, protected builtins (`review`, `run-ci`), or duplicate names within the same session. Different sessions may register the same name. Dispose before replacement; there is no silent overwrite.
|
|
23
|
+
|
|
24
|
+
Register in `session_start` using **`ctx.sessionManager.getSessionId()`**, not the session file path or a tool argument. Dispose in `session_shutdown`. New/resumed/forked sessions and reloads need registration from the replacement runtime's `session_start`; do not retain old `pi`/`ctx` references. The extension owns cleanup, not an automatic registration lifecycle manager. Disposal is idempotent and cannot remove a newer replacement. Missing cleanup can cause a duplicate-registration failure on reload.
|
|
25
|
+
|
|
26
|
+
`resolve` must do synchronous, bounded validation and string construction, without I/O, SDK calls, timers or process work. Core deep-copies plain JSON args: at most 16 KiB encoded, nesting depth 8, 16 fields per object, 64 items per array, finite numbers, and nonempty strings of at most 16 KiB. The extension must additionally reject unsupported fields and validate resource-specific semantics. Throws, promises/thenables and malformed expansions fail before authority is issued; errors are bounded to 4096 characters.
|
|
27
|
+
|
|
28
|
+
Host grants bind **exact key/trimmed-command pairs**, not independent sets of keys and commands. At most 32 grants are accepted, with unique safe workflow keys and nonempty commands bounded to 16 KiB without NUL. Omitted grants give no host authority. Core snapshots the expansion and grants at resolution. Disposing stops future lookup, but already-admitted workflows retain captured grants, even after replacement. Use existing stop/deadline controls for cancellation; this does not promise survival of host shutdown or durable named scheduling. Existing child admission and capability ceilings still apply.
|
|
29
|
+
|
|
30
|
+
### Mixed child and finite host example
|
|
31
|
+
|
|
32
|
+
This extension owns two fixed commands; `scripts/finite-check.mjs` must be an existing trusted finite helper in the workflow cwd. It runs a reviewer first, then a check. No command or flags come from free-form public args.
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
36
|
+
import { registerWorkflowResource } from "pi-subagents/workflow-resources";
|
|
37
|
+
|
|
38
|
+
export default function (pi: ExtensionAPI) {
|
|
39
|
+
let registration: { dispose(): void } | undefined;
|
|
40
|
+
pi.on("session_start", (_event, ctx) => {
|
|
41
|
+
registration?.dispose();
|
|
42
|
+
registration = registerWorkflowResource({
|
|
43
|
+
sessionId: ctx.sessionManager.getSessionId(),
|
|
44
|
+
definition: {
|
|
45
|
+
name: "acme.review-check",
|
|
46
|
+
version: 1,
|
|
47
|
+
resolve(args) {
|
|
48
|
+
if (Object.keys(args).some(k => k !== "task" && k !== "check"))
|
|
49
|
+
return { error: "Only task and check are supported." };
|
|
50
|
+
if (typeof args.task !== "string" || !args.task.trim() || args.task.length > 4000)
|
|
51
|
+
return { error: "task must contain 1–4000 characters." };
|
|
52
|
+
if (args.check !== "quick" && args.check !== "full")
|
|
53
|
+
return { error: "check must be quick or full." };
|
|
54
|
+
const command = args.check === "quick"
|
|
55
|
+
? "node ./scripts/finite-check.mjs --mode quick"
|
|
56
|
+
: "node ./scripts/finite-check.mjs --mode full";
|
|
57
|
+
const host = { kind: "command", command, timeoutMs: 120000 };
|
|
58
|
+
return {
|
|
59
|
+
hostCommands: [{ key: "check", command }],
|
|
60
|
+
script: `
|
|
61
|
+
const review = await runs.run("review", {
|
|
62
|
+
agent: "reviewer", task: ${JSON.stringify(args.task)}
|
|
63
|
+
});
|
|
64
|
+
if (!review.ok) throw new Error("Review child failed");
|
|
65
|
+
const check = await runs.host("check", ${JSON.stringify(host)});
|
|
66
|
+
return { review: review.output, check };
|
|
67
|
+
`,
|
|
68
|
+
};
|
|
69
|
+
},
|
|
70
|
+
},
|
|
71
|
+
});
|
|
72
|
+
});
|
|
73
|
+
pi.on("session_shutdown", () => {
|
|
74
|
+
registration?.dispose();
|
|
75
|
+
registration = undefined;
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Invoke through the public `subagent` tool (use `async: false` for foreground):
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"workflow": "acme.review-check",
|
|
85
|
+
"args": { "task": "Review the current change; return findings only.", "check": "quick" },
|
|
86
|
+
"async": true
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The parent evaluates child findings and ordinary command logs/status/terminal receipts; child success is not approval or proof of a clean review. The timeout above bounds the host command, not the whole workflow.
|
|
91
|
+
|
|
92
|
+
**Trust boundary:** this API composes already-loaded trusted code; it is neither authentication nor a sandbox. Session IDs scope lookup, not authorization between malicious extensions. Core owns opaque permits and provenance; caller-supplied issuer/trust/permit metadata cannot grant authority. Raw public scripts and script paths do not gain host authority, and registration is not an arbitrary-command entry point for public args.
|
|
93
|
+
|
|
94
|
+
The existing shell runner uses workflow cwd and inherited environment. Exact matching does not pin PATH resolution, executable bytes, repository helpers, or credentials. Those remain operator/extension trust responsibilities. `JSON.stringify` embeds data in JavaScript source; **it is not shell escaping**. Keep commands fixed as above, or validate strictly bounded numeric/hex tokens before binding known positions; never concatenate arbitrary task text or flags into shell commands. No new runner, cwd confinement, CI/merge policy, or SDK lifecycle framework is provided.
|
|
95
|
+
|
|
5
96
|
## In-process event-bus RPC
|
|
6
97
|
|
|
7
98
|
Other Pi extensions can use the in-process event-bus RPC instead of scraping slash output or calling internal modules. Listen for `subagents:rpc:v1:ready`, send requests on `subagents:rpc:v1:request`, and read replies from `subagents:rpc:v1:reply:<requestId>`.
|
|
@@ -101,41 +192,6 @@ The installed owner applies the existing runtime-agent validation, collision che
|
|
|
101
192
|
|
|
102
193
|
This contract is process-local. It does not register agents in child sessions or other Pi processes, and it does not change package discovery or package resolution.
|
|
103
194
|
|
|
104
|
-
## Agent discovery from independent extensions
|
|
105
|
-
|
|
106
|
-
An extension that wants to offer the same agent list the subagent launcher uses
|
|
107
|
-
— a session role picker, for example — can call the exported discovery helper
|
|
108
|
-
instead of re-implementing agent loading:
|
|
109
|
-
|
|
110
|
-
```typescript
|
|
111
|
-
import { discoverAgentsWithRuntime } from "pi-subagents/agents";
|
|
112
|
-
|
|
113
|
-
const result = discoverAgentsWithRuntime(pi, cwd, "both");
|
|
114
|
-
for (const agent of result.agents) {
|
|
115
|
-
// agent.name, agent.description, agent.aliases, agent.source,
|
|
116
|
-
// agent.sandbox, agent.permissionProfile, agent.override?.scope, agent.disabled
|
|
117
|
-
}
|
|
118
|
-
result.agentDiagnostics; // loader problems, per source
|
|
119
|
-
result.projectAgentsDir; // where project agents came from
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
The result is the merged view: builtin, package, user, and project agent files
|
|
123
|
-
plus anything registered at runtime through the contract above. With nothing
|
|
124
|
-
registered, it is exactly `discoverAgents(cwd, scope)`.
|
|
125
|
-
|
|
126
|
-
`scope` is `"user" | "project" | "both"`. Pass the caller's `cwd` so project
|
|
127
|
-
layering resolves against the right tree, and pass the caller's `ExtensionAPI`
|
|
128
|
-
because the runtime registry is keyed on it.
|
|
129
|
-
|
|
130
|
-
Two notes for consumers of an optional dependency:
|
|
131
|
-
|
|
132
|
-
- Treat the module as optional. A package that is not installed cannot be
|
|
133
|
-
imported, so load it dynamically and report the failure rather than failing
|
|
134
|
-
extension load.
|
|
135
|
-
- `agent.source === "project"` (or `agent.override?.scope === "project"`) means
|
|
136
|
-
the definition comes from the current project. Gate such an agent behind the
|
|
137
|
-
host's project-trust decision before adopting it for anything.
|
|
138
|
-
|
|
139
195
|
## External jobs in FleetView
|
|
140
196
|
|
|
141
197
|
Use `pi-subagents/external-runs` to publish display-only current-session jobs owned by another extension:
|
|
@@ -170,7 +226,7 @@ unregisterExternalRun(ctx.sessionManager.getSessionId(), "dependency-review");
|
|
|
170
226
|
|
|
171
227
|
The API validates and caches bounded display fields when the caller registers or updates a job. FleetView reads that cache only. It does not poll caller code. `snapshotExternalRuns(sessionId)` and `listExternalRuns(sessionId)` return bounded current-session snapshots. Snapshots filter the session-qualified cache key before inspecting record fields; API-written records avoid repeated normalization through module-private provenance, while records replaced or mutated through the process-local registry are validated on demand. By default, malformed records for the requested session throw with the validation error. Display-only Fleet callers can pass `{ ignoreMalformed: true, onMalformedRecord }` to remove bad records and keep rendering with a programmatic diagnostic.
|
|
172
228
|
|
|
173
|
-
External jobs are observational. The caller owns execution, persistence, cancellation, and result delivery. FleetView does not expose stop, steer, resume, cancel, or
|
|
229
|
+
External jobs are observational. The caller owns execution, persistence, cancellation, and result delivery. FleetView does not expose stop, steer, resume, cancel, or inspector controls for them. Supplied report and transcript paths are shown as bounded text only; FleetView does not read arbitrary external paths.
|
|
174
230
|
|
|
175
231
|
## Launch contract preflight
|
|
176
232
|
|
|
@@ -190,7 +246,8 @@ const result = await resolveSubagentLaunchContract({
|
|
|
190
246
|
|
|
191
247
|
if (!result.ok) {
|
|
192
248
|
// missing_agent, ambiguous_agent, missing_skill, denied_required_tool,
|
|
193
|
-
// invalid_artifact_dir, invalid_cwd,
|
|
249
|
+
// invalid_artifact_dir, invalid_cwd, unsupported_mode, restricted_agent,
|
|
250
|
+
// thinking_ceiling, invalid_extension_bindings, or invalid_intercom_bridge
|
|
194
251
|
throw new Error(result.message);
|
|
195
252
|
}
|
|
196
253
|
|
|
@@ -200,11 +257,17 @@ console.log(result.contract.digest, result.contract.tools.effectiveAllowlist);
|
|
|
200
257
|
Preflight covers ordinary single-agent launch resolution:
|
|
201
258
|
|
|
202
259
|
- Selected agent identity and shadowed candidates.
|
|
203
|
-
- A parsed-definition digest, including system prompt and launch-affecting model, tool, skill, extension, output, and memory fields.
|
|
260
|
+
- A parsed-definition digest, including system prompt and launch-affecting model, tool, skill, extension, output, and memory fields. Runtime overlays such as the Intercom bridge never change it.
|
|
204
261
|
- Fresh/fork context, effective model and thinking, skill and tool resolution, direct MCP selections, runtime/configured extensions.
|
|
262
|
+
- The resolved Intercom bridge state (`intercomBridge.mode` and `intercomBridge.active`). An active bridge appends the bridge instruction to the child prompt and adds `contact_supervisor` to a declared tool list, exactly as execution does.
|
|
205
263
|
- Artifact/session paths, async lifecycle/status/result/event/process-terminal paths, package/lifecycle versions, capability-ceiling audit data, and stable digests.
|
|
206
264
|
|
|
207
|
-
`launchContractDigest` is the canonical digest of the caller task, effective system prompt, model candidates, effective tools/extensions/MCP (including inherited capability ceilings), output binding, and structured-output schema that ordinary foreground and async execution report in results/status/events and metadata.
|
|
265
|
+
`launchContractDigest` is the canonical digest of the caller task, effective system prompt (including an active bridge instruction), model candidates, effective tools/extensions/MCP (including inherited capability ceilings and the bridge tool), output binding, and structured-output schema that ordinary foreground and async execution report in results/status/events and metadata. Preflight and each execution path that reports the digest assemble it through one shared binding, so equal inputs produce equal digests.
|
|
266
|
+
|
|
267
|
+
Bridge inputs:
|
|
268
|
+
|
|
269
|
+
- `intercomBridge` replaces the global `intercomBridge` config for this launch, with the same semantics as the `subagent` tool and delegation overrides. Pass the same value to the launch you compare against. Preflight reads the global config from disk on each call while the running extension keeps the config it loaded at startup, so pass the override when the digest must not depend on that file.
|
|
270
|
+
- The default bridge instruction never names the parent session, so most hosts need no further input. When the configured `instructionFile` interpolates `{orchestratorTarget}`, preflight reports a `host_required` diagnostic unless the host supplies a non-empty `orchestratorTarget`; the executor derives that target with `resolveIntercomSessionTarget` from `pi-subagents/intercom-bridge`, given the parent session name and id.
|
|
208
271
|
|
|
209
272
|
Boundaries:
|
|
210
273
|
|
|
@@ -214,26 +277,6 @@ Boundaries:
|
|
|
214
277
|
- Some host-owned facts, such as exact fork snapshots, nested async roots, and live model registries, can only be proven by the Pi host; those appear as `host_required` diagnostics instead of silently pretending to be exact.
|
|
215
278
|
- Preflight reads the extension config, so `defaultSubagentContext: "fresh"` or `"fork"` affects omitted context in the same way as execution. Explicit `context` still wins.
|
|
216
279
|
|
|
217
|
-
## Agent ejection API
|
|
218
|
-
|
|
219
|
-
Use `@xzzpig/pi-subagents/agent-management` when an extension needs to make a bundled agent editable without parsing model-facing management output:
|
|
220
|
-
|
|
221
|
-
```ts
|
|
222
|
-
import { ejectAgentDefinition } from "@xzzpig/pi-subagents/agent-management";
|
|
223
|
-
|
|
224
|
-
const result = ejectAgentDefinition({
|
|
225
|
-
cwd: ctx.cwd,
|
|
226
|
-
agent: "reviewer",
|
|
227
|
-
scope: "project",
|
|
228
|
-
projectTrusted: ctx.isProjectTrusted(),
|
|
229
|
-
});
|
|
230
|
-
|
|
231
|
-
if (!result.ok) throw new Error(result.message);
|
|
232
|
-
console.log(result.targetPath, result.verification.launchPreflighted);
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
The operation never overwrites an existing agent, chain, or conflicting file. Package-relative tool, extension, and skill paths are normalized before writing. After rediscovery, it validates copied skills and the static child launch tool plan; if that check fails, it removes only the new file created by that call and returns `preflight_failed`. Host-dependent checks such as the live model registry and actual child process startup remain the responsibility of the caller's normal launch preflight/execution path.
|
|
236
|
-
|
|
237
280
|
## Structured delegation API
|
|
238
281
|
|
|
239
282
|
Other Pi extensions can ask `pi-subagents` to run one configured foreground leaf agent through the structured delegation API. It uses the established `prompt-template:subagent:*` event family and the same executor as the `subagent` tool; it does not add another launcher.
|
|
@@ -294,6 +337,7 @@ Bounds:
|
|
|
294
337
|
|
|
295
338
|
- Schemas are capped at 64 KiB; tasks and returned text/structured values are capped at 1 MiB, with smaller bounds on identity/configuration strings and a maximum `timeoutMs` of 2,147,483,647.
|
|
296
339
|
- Structured delegation accepts `toolBudget: { hard: 0, block: "*" }` to block the first tool call and run a zero-tool leaf; ordinary model-facing/configured budgets keep their existing minimum of one.
|
|
340
|
+
- `intercomBridge` optionally replaces the global bridge config for one delegation, for example `{ mode: "off" }` when no supervisor session will answer the child. Pass the same value to `resolveSubagentLaunchContract` to compare `launchContractDigest` against the terminal response.
|
|
297
341
|
- The foreground bridge retains up to 8,192 exact pending-cancellation and settled-attempt identities per extension context. If either history fills, it fails closed with `unavailable_context` for later starts rather than evicting identity facts; lifecycle reset clears the bounded history.
|
|
298
342
|
|
|
299
343
|
Constraints:
|
|
@@ -366,7 +410,7 @@ Semantics:
|
|
|
366
410
|
|
|
367
411
|
Children do not gain provider tools or extensions automatically. Add `bg_wait` to the child agent's `tools` allowlist and load each provider through `extensions` or `subagentOnlyExtensions`. The parent's effective `waitTool` setting reaches every child through its typed runtime config; `PI_SUBAGENT_WAIT_TOOL_ENABLED` keeps precedence in the parent.
|
|
368
412
|
|
|
369
|
-
|
|
413
|
+
Local foreground children never load the parent's ambient extensions: they share the parent's process, and loading them would start a second copy of every ambient extension, including this one, inside it. They do inherit the providers the parent's extensions registered, so a provider extension's models resolve in a local foreground child. Pane-native remote foreground children instead use the remote machine's provider discovery and configuration. Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) must run as background children (`async: true`), which load the ambient extensions inside the detached runner process unless the agent sets `extensions` or the capability ceiling denies extensions.
|
|
370
414
|
|
|
371
415
|
## External job provider bridge
|
|
372
416
|
|
|
@@ -391,6 +435,27 @@ The provider returns handles with `providerJobId`, `state`, optional `handleUrl`
|
|
|
391
435
|
|
|
392
436
|
The async runner process does not import provider internals. It writes operation requests into its async run directory. The parent Pi process services those requests against the registered provider and writes operation responses. If the provider is not registered, the bridge fails closed with an actionable error. If a run is recovered after provider job metadata exists, the runner calls `reattach` and `result`; it does not call `start` or `follow-up` again.
|
|
393
437
|
|
|
438
|
+
## Inspect integration
|
|
439
|
+
|
|
440
|
+
Inspect is the portable command and action surface for an existing async run. The public actions are:
|
|
441
|
+
|
|
442
|
+
```ts
|
|
443
|
+
subagent({ action: "inspector.command", id: "<run-id>", index: 0 })
|
|
444
|
+
subagent({ action: "inspector.open", id: "<run-id>", index: 0, focus: true })
|
|
445
|
+
subagent({ action: "inspector.status", id: "<run-id>", index: 0 })
|
|
446
|
+
subagent({ action: "inspector.close", id: "<run-id>", index: 0 })
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
`inspector.command` returns a standalone runner command without contacting a host or writing a binding. `inspector.open` selects an available bundled inspector plugin. `status` and `close` select the plugin that owns the run binding and report clearly when that plugin does not support the requested lifecycle action. Without an available plugin, `open` fails closed with an actionable message; ordinary launches remain headless. Closing an inspector never stops the run.
|
|
450
|
+
|
|
451
|
+
### Herdr inspector plugin
|
|
452
|
+
|
|
453
|
+
The bundled Herdr inspector plugin supports Herdr 0.7.5+. It opens a raw dashboard pane, not the child session and not a literal attach. It reads lifecycle, status, output, and mission artifacts; steer and stop continue through pi-subagents' existing control inbox. Use `focus` only with `inspector.open`; Herdr 0.7.5 cannot focus an arbitrary existing raw pane id.
|
|
454
|
+
|
|
455
|
+
### Ghostty inspector plugin
|
|
456
|
+
|
|
457
|
+
Ghostty 1.3+ on macOS is the second bundled open-only plugin, using Ghostty's preview AppleScript API. It splits the focused terminal and launches the read-only inspector command; status and close are unavailable because it writes no binding. Ghostty Automation permission is required.
|
|
458
|
+
|
|
394
459
|
## Herdr integration
|
|
395
460
|
|
|
396
461
|
When Pi runs inside [Herdr](https://herdr.dev), pi-subagents automatically reports active async-run counts through Herdr pane metadata.
|
|
@@ -410,20 +475,6 @@ rows = [
|
|
|
410
475
|
]
|
|
411
476
|
```
|
|
412
477
|
|
|
413
|
-
### Inspector panes
|
|
414
|
-
|
|
415
|
-
Herdr 0.7.5+ can open an on-demand inspector for an existing async run:
|
|
416
|
-
|
|
417
|
-
```ts
|
|
418
|
-
subagent({ action: "inspector.open", id: "<run-id>", index: 0, focus: true })
|
|
419
|
-
subagent({ action: "inspector.status", id: "<run-id>", index: 0 })
|
|
420
|
-
subagent({ action: "inspector.close", id: "<run-id>", index: 0 })
|
|
421
|
-
```
|
|
422
|
-
|
|
423
|
-
The inspector is a raw dashboard pane, not the child session and not a literal attach. It reads lifecycle/status/output/mission artifacts and sends `steer` or `stop` through pi-subagents' existing control inbox. Closing it never stops the run.
|
|
424
|
-
|
|
425
|
-
Herdr remains optional. Ordinary launches stay headless, and missing/older Herdr versions affect only Herdr-specific inspector and project-pane actions. FleetView opens the selected active async child with `H`. Use `focus` only with `inspector.open`; Herdr 0.7.5 cannot focus an arbitrary existing raw pane id.
|
|
426
|
-
|
|
427
478
|
### Project panes
|
|
428
479
|
|
|
429
480
|
For substantial work in another codebase, Herdr 0.7.5+ can open a project-owned Pi pane rooted in that repository:
|
|
@@ -469,6 +520,8 @@ Detached children do not stop when the session does. They are the host process's
|
|
|
469
520
|
|
|
470
521
|
This matters because "is the parent busy?" is the wrong idle signal. A parent that launches a detached run and hands control back — which is what the async launch output tells it to do — is not prompting, streaming, compacting, or running a shell command. A host that reaps sessions on those signals alone will dispose exactly the session that was waiting to be woken.
|
|
471
522
|
|
|
523
|
+
When pi-subagents runs inside a compatible pi-web host, it discovers the versioned `Symbol.for("@agegr/pi-web/session-liveness/v1")` registry and registers one provider for the current session. The provider reports live `queued`/`running` async jobs, active nested descendants (including foreground routes retained after their direct parent settles), foreground controls that still have a scheduling owner or active child, and completion notifications waiting for their batch-delivery timer. Retained terminal history, future schedules, and wait subscriptions do not make a session live by themselves. The registration is replaced on session changes and released during runtime shutdown or reload; other hosts remain unaffected.
|
|
524
|
+
|
|
472
525
|
If your host reclaims idle sessions, keep a session alive while it still has live detached work:
|
|
473
526
|
|
|
474
527
|
- Read run state from the status files under the async run directory rather than from event traffic. A long, quiet workflow sends almost nothing to the parent, so recent-activity heuristics conclude the wrong thing.
|
|
@@ -486,6 +539,7 @@ The main runtime files in this repository:
|
|
|
486
539
|
| File | Purpose |
|
|
487
540
|
|------|---------|
|
|
488
541
|
| `src/extension/index.ts` | Extension registration, tool registration, message/render wiring. |
|
|
542
|
+
| `src/integrations/pi-web-session-liveness.ts` | Optional pi-web idle-eviction liveness bridge. |
|
|
489
543
|
| `src/agents/agents.ts` | Agent and chain discovery, frontmatter parsing. |
|
|
490
544
|
| `src/runs/foreground/subagent-executor.ts` | Main execution routing for single, parallel, chain, management, status, interrupt, and doctor actions. |
|
|
491
545
|
| `src/runs/foreground/execution.ts` | Core foreground `runSync` handling: drives one in-process child session per attempt. |
|
|
@@ -505,3 +559,7 @@ The main runtime files in this repository:
|
|
|
505
559
|
| `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |
|
|
506
560
|
| `src/extension/schemas.ts` / `src/shared/types.ts` | Tool schemas, shared types, and event constants. |
|
|
507
561
|
| `test/unit/` / `test/integration/` | Unit and loader-based integration tests. |
|
|
562
|
+
|
|
563
|
+
### Published package vs source checkout
|
|
564
|
+
|
|
565
|
+
The npm tarball ships TypeScript compiler output with the same file layout and a compiled `index.js` entry. A Git checkout continues to run `index.ts` directly, so local extension development does not require a build step. Run `npm run pack:pkg` to build and pack the same artifact published to npm.
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# Fork extensions
|
|
2
|
+
|
|
3
|
+
Documentation for `@xzzpig/pi-subagents`-specific extensions that are not part
|
|
4
|
+
of upstream `pi-subagents`. These chapters were moved out of
|
|
5
|
+
[`agents.md`](agents.md) and [`extension-api.md`](extension-api.md) so those
|
|
6
|
+
files stay byte-identical to upstream.
|
|
7
|
+
|
|
8
|
+
## Sandbox profiles
|
|
9
|
+
|
|
10
|
+
Use `sandbox: <profile-name>` only for a native Pi child. The profile is resolved
|
|
11
|
+
from the global `pi-sandbox` configuration, never from an agent file or a project
|
|
12
|
+
profile registry:
|
|
13
|
+
|
|
14
|
+
```yaml
|
|
15
|
+
---
|
|
16
|
+
name: security-reviewer
|
|
17
|
+
description: Review changes with a constrained filesystem and no network
|
|
18
|
+
sandbox: reviewer-strict
|
|
19
|
+
extensions: ./review-tools.ts
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
Review the requested change.
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`pi-subagents` validates the scalar name and passes only that name to the child.
|
|
26
|
+
It automatically resolves and injects the installed `pi-sandbox` extension and a
|
|
27
|
+
startup guard even when `extensions` is an explicit allowlist; an explicit empty
|
|
28
|
+
allowlist does not remove these required runtime extensions. The guard requires
|
|
29
|
+
`pi-sandbox` to acknowledge successful profile initialization before the child
|
|
30
|
+
can enter its first model turn. The launch fails before the model's first turn when the package or manifest is missing, a capability ceiling denies child
|
|
31
|
+
extensions, the profile cannot be loaded, or sandbox initialization fails. A
|
|
32
|
+
blocked child publishes that reason through its startup diagnostics, so the
|
|
33
|
+
caller sees the profile error (and the available profile names) instead of a
|
|
34
|
+
generic empty-output message; a startup block is never recorded as a model
|
|
35
|
+
failure and never excludes the model from later runs.
|
|
36
|
+
|
|
37
|
+
The field is rejected for `external-cli` and `external-job` runners because they
|
|
38
|
+
do not host a Pi child extension. It also cannot be an object, `false`, an empty
|
|
39
|
+
value, or an inline allow/deny policy. Define the actual network and filesystem
|
|
40
|
+
rules in global `pi-sandbox` `profiles` instead.
|
|
41
|
+
|
|
42
|
+
A profile chosen by a project-scoped agent or project override is used only when
|
|
43
|
+
the host marks that project trusted. Otherwise the launch reports an actionable
|
|
44
|
+
trust error. In a headless child, accesses outside the profile's preconfigured
|
|
45
|
+
network/read/write rules are blocked; pi-sandbox does not use Permission System
|
|
46
|
+
or supervisor forwarding to ask the parent for an approval. See
|
|
47
|
+
[`pi-sandbox`'s README](https://github.com/xzzpig/pi-extensions/tree/main/packages/pi-sandbox#named-profiles-for-subagents)
|
|
48
|
+
for profile inheritance and merge rules.
|
|
49
|
+
|
|
50
|
+
## Permission profiles
|
|
51
|
+
|
|
52
|
+
Use `permission-profile: <name>` to select a named policy profile from the
|
|
53
|
+
**global-only** `profiles` registry in `pi-permission-system`'s config
|
|
54
|
+
(`<agentDir>/extensions/pi-permission-system/config.json`). It is a selector
|
|
55
|
+
only — the actual rules (tool scalars, `bash`/`mcp`/`skill`/`external_directory`
|
|
56
|
+
pattern maps, `'*'` fallback) live in that registry and always resolve from the
|
|
57
|
+
child's own global config:
|
|
58
|
+
|
|
59
|
+
```yaml
|
|
60
|
+
---
|
|
61
|
+
name: reviewer
|
|
62
|
+
description: Review changes without write access
|
|
63
|
+
permission-profile: reviewer
|
|
64
|
+
---
|
|
65
|
+
Review the requested change and report findings.
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`pi-subagents` validates the scalar name (same grammar as sandbox profiles),
|
|
69
|
+
passes only that name to the child via the transient
|
|
70
|
+
`PI_SUBAGENT_PERMISSION_PROFILE` environment variable, and injects the
|
|
71
|
+
installed `pi-permission-system` extension into the child launch even when
|
|
72
|
+
`extensions` is an explicit allowlist, so the child's permission system applies
|
|
73
|
+
the selected profile. The env channel carries a bare validated name — raw
|
|
74
|
+
policy is never transmitted — and the rules are always read from the child's
|
|
75
|
+
own global config, so the profile means the same policy regardless of which
|
|
76
|
+
host launches the agent. Selection precedence inside the permission system is
|
|
77
|
+
env > project agent file > global agent file.
|
|
78
|
+
|
|
79
|
+
The launch fails closed when a profile is declared but `pi-permission-system`
|
|
80
|
+
is not installed, when a capability ceiling denies child extensions, or when
|
|
81
|
+
the runner is not a native Pi child (the field is rejected for `external-cli`
|
|
82
|
+
and `external-job` runners). At runtime, selecting an unknown profile or an
|
|
83
|
+
empty ruleset clamps that agent's `allow` rules to `ask` with an explicit
|
|
84
|
+
`Permission profile '<name>' could not be resolved` diagnostic — it never
|
|
85
|
+
silently degrades to the unselected baseline. An agent without the field keeps
|
|
86
|
+
its pre-change behavior exactly.
|
|
87
|
+
|
|
88
|
+
The profile merges between the project config and the agent's own `permission:`
|
|
89
|
+
block: patterns the profile does not mention keep the lower scopes' rules
|
|
90
|
+
(global denies survive), and `permission:` overrides the profile per pattern.
|
|
91
|
+
A profile selected by a **project** agent file participates only when the host
|
|
92
|
+
marks that project trusted.
|
|
93
|
+
|
|
94
|
+
## Context injection
|
|
95
|
+
|
|
96
|
+
By default the parent agent learns which agents exist only by calling `subagent({ action: "list" })`. Context injection pre-declares selected agents in the parent system prompt through a compact `<available_subagents>` block, so routing decisions can happen without a discovery round trip.
|
|
97
|
+
|
|
98
|
+
Two sources contribute, and the union is advertised:
|
|
99
|
+
|
|
100
|
+
1. Agent files that opt in with `injectToContext: true` in their frontmatter.
|
|
101
|
+
2. The `subagents.injectAgents` setting, which lists agent names (canonical names or aliases; builtins allowed):
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"subagents": {
|
|
106
|
+
"injectAgents": ["worker", "reviewer", "security-reviewer"]
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Rendered block shape:
|
|
112
|
+
|
|
113
|
+
```text
|
|
114
|
+
<available_subagents>
|
|
115
|
+
The following pre-declared subagents are available.
|
|
116
|
+
Launch them with the subagent tool when a task matches their description.
|
|
117
|
+
|
|
118
|
+
- security-reviewer: Security review specialist
|
|
119
|
+
- worker: Implementation work, including approved oracle handoffs.
|
|
120
|
+
</available_subagents>
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Semantics and guarantees:
|
|
124
|
+
|
|
125
|
+
- **Snapshot per session.** The list resolves once at session start (and on reload) and stays byte-identical for every turn, so provider prompt caching is never invalidated mid-session. Edits to agent files or settings take effect in a new session, not the current one; `{ action: "list" }` remains the runtime source of truth.
|
|
126
|
+
- **Only executable agents are advertised.** Disabled agents and agents restricted by the session capability ceiling are never injected.
|
|
127
|
+
- **Children never see it.** Spawned child sessions do not load the parent injection; fanout children can still call `{ action: "list" }`.
|
|
128
|
+
- **Unknown setting names are ignored** and reported by `/subagents-doctor` instead of failing startup.
|
|
129
|
+
- The block is appended only when it is not already present, so forked or resumed sessions never duplicate it.
|
|
130
|
+
|
|
131
|
+
## Agent discovery from independent extensions
|
|
132
|
+
|
|
133
|
+
An extension that wants to offer the same agent list the subagent launcher uses
|
|
134
|
+
— a session role picker, for example — can call the exported discovery helper
|
|
135
|
+
instead of re-implementing agent loading:
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
import { discoverAgentsWithRuntime } from "pi-subagents/agents";
|
|
139
|
+
|
|
140
|
+
const result = discoverAgentsWithRuntime(pi, cwd, "both");
|
|
141
|
+
for (const agent of result.agents) {
|
|
142
|
+
// agent.name, agent.description, agent.aliases, agent.source,
|
|
143
|
+
// agent.sandbox, agent.permissionProfile, agent.override?.scope, agent.disabled
|
|
144
|
+
}
|
|
145
|
+
result.agentDiagnostics; // loader problems, per source
|
|
146
|
+
result.projectAgentsDir; // where project agents came from
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The result is the merged view: builtin, package, user, and project agent files
|
|
150
|
+
plus anything registered at runtime through the contract above. With nothing
|
|
151
|
+
registered, it is exactly `discoverAgents(cwd, scope)`.
|
|
152
|
+
|
|
153
|
+
`scope` is `"user" | "project" | "both"`. Pass the caller's `cwd` so project
|
|
154
|
+
layering resolves against the right tree, and pass the caller's `ExtensionAPI`
|
|
155
|
+
because the runtime registry is keyed on it.
|
|
156
|
+
|
|
157
|
+
Two notes for consumers of an optional dependency:
|
|
158
|
+
|
|
159
|
+
- Treat the module as optional. A package that is not installed cannot be
|
|
160
|
+
imported, so load it dynamically and report the failure rather than failing
|
|
161
|
+
extension load.
|
|
162
|
+
- `agent.source === "project"` (or `agent.override?.scope === "project"`) means
|
|
163
|
+
the definition comes from the current project. Gate such an agent behind the
|
|
164
|
+
host's project-trust decision before adopting it for anything.
|
|
165
|
+
|
|
166
|
+
## Agent ejection API
|
|
167
|
+
|
|
168
|
+
Use `@xzzpig/pi-subagents/agent-management` when an extension needs to make a bundled agent editable without parsing model-facing management output:
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
import { ejectAgentDefinition } from "@xzzpig/pi-subagents/agent-management";
|
|
172
|
+
|
|
173
|
+
const result = ejectAgentDefinition({
|
|
174
|
+
cwd: ctx.cwd,
|
|
175
|
+
agent: "reviewer",
|
|
176
|
+
scope: "project",
|
|
177
|
+
projectTrusted: ctx.isProjectTrusted(),
|
|
178
|
+
});
|
|
179
|
+
|
|
180
|
+
if (!result.ok) throw new Error(result.message);
|
|
181
|
+
console.log(result.targetPath, result.verification.launchPreflighted);
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
The operation never overwrites an existing agent, chain, or conflicting file. Package-relative tool, extension, and skill paths are normalized before writing. After rediscovery, it validates copied skills and the static child launch tool plan; if that check fails, it removes only the new file created by that call and returns `preflight_failed`. Host-dependent checks such as the live model registry and actual child process startup remain the responsibility of the caller's normal launch preflight/execution path.
|
package/docs/missions.md
CHANGED
|
@@ -103,10 +103,16 @@ subagent({
|
|
|
103
103
|
Create a fixed recurring workflow:
|
|
104
104
|
|
|
105
105
|
```ts
|
|
106
|
-
subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest", workflowScript: "
|
|
106
|
+
subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest", workflowScript: "return runs.run('main', { agent: 'worker', task: args.task })", args: { task: "Maintain core" } })
|
|
107
107
|
```
|
|
108
108
|
|
|
109
|
-
Fixed intervals support `m`, `h`, `d`, and `w` units and advance from the planned time without completion drift.
|
|
109
|
+
Fixed intervals support `m`, `h`, `d`, and `w` units and advance from the planned time without completion drift. Schedule arguments are normalized and persisted for exact replay after reload; do not put secrets in them.
|
|
110
|
+
|
|
111
|
+
Create a quiet recurring workflow whose successful completions stay visible but do not wake the parent session:
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
subagent({ action: "schedule.create", id: "nightly-sweep", every: "24h", quiet: true, workflowScript: "..." })
|
|
115
|
+
```
|
|
110
116
|
|
|
111
117
|
Manage schedules with `schedule.list`, `schedule.show`, `schedule.history`, `schedule.pause`, `schedule.resume`, `schedule.run`, `schedule.run-due`, and `schedule.delete`.
|
|
112
118
|
|
|
@@ -116,6 +122,8 @@ Behavior:
|
|
|
116
122
|
- An optional top-level `baseRef` selects the safe Git ref used by managed worktrees (default `HEAD`); it is persisted with the schedule and forwarded on every fire. The source checkout must still be clean.
|
|
117
123
|
- Definitions, bounded history, append-only events, and per-run receipts are stored with mode `0600`.
|
|
118
124
|
- `overlap` is currently fixed to `skip`; `catchUp` supports `latest` (default) and `none`.
|
|
125
|
+
- A successful `schedule.run` satisfies the next natural fire; a failed manual launch does not skip it.
|
|
126
|
+
- `quiet` persists only on recurring (`every`) schedules. Successful automatic fires stay visible without a parent turn; failed, stopped, or paused outcomes still wake the session. One-shot `at` schedules and `schedule.run` stay noisy unless that launch passes `quiet: true`.
|
|
119
127
|
- `schedule.run-due` lets an external launcher start due project work without making `pi-subagents` a daemon.
|
|
120
128
|
- Calendar recurrence, cron, queue/replace overlap, and the schedule TUI inspector are intentionally deferred to the next slice.
|
|
121
129
|
- The old `schedule`, `schedule-list`, `schedule-status`, and `schedule-cancel` actions were removed in a hard cutover.
|
package/docs/models.md
CHANGED
|
@@ -13,6 +13,8 @@ Builtin agents inherit your current Pi default model. This keeps new installs fr
|
|
|
13
13
|
|
|
14
14
|
Precedence, strongest first: per-run override → provider-scoped role override → `agentOverrides.<name>.model` → agent frontmatter `model` → `subagents.defaultModel` → the parent session model. A provider preference does not replace this order; it only resolves bare model ids when the active registry has more than one match. Fully qualified `provider/model` strings still win exactly.
|
|
15
15
|
|
|
16
|
+
Each launch resolves one model. Provider errors, including HTTP 429 responses, are returned from that model rather than selecting another one. Separately, a verified compaction abort after useful progress may continue the retained child session once on the same resolved model; this lifecycle recovery preserves work and is not model fallback.
|
|
17
|
+
|
|
16
18
|
Use `model: "inherit"` in agent frontmatter or `agentOverrides.<name>.model` to select the current parent session model explicitly.
|
|
17
19
|
|
|
18
20
|
## Setting defaults and overrides
|
|
@@ -57,7 +59,7 @@ To keep one role definition but configure it differently for work and personal p
|
|
|
57
59
|
}
|
|
58
60
|
```
|
|
59
61
|
|
|
60
|
-
The provider key comes from the active parent session model (or an explicit host `preferredProvider`)
|
|
62
|
+
The provider key comes from the active parent session model (or an explicit host `preferredProvider`). Provider-scoped fields layer over the ordinary override in the same settings file; project settings still win over user settings.
|
|
61
63
|
|
|
62
64
|
For one run, put the override in the command:
|
|
63
65
|
|
|
@@ -65,7 +67,7 @@ For one run, put the override in the command:
|
|
|
65
67
|
/run reviewer[model=anthropic/claude-sonnet-4:high] "Review this diff"
|
|
66
68
|
```
|
|
67
69
|
|
|
68
|
-
For a persistent role override
|
|
70
|
+
For a persistent role override:
|
|
69
71
|
|
|
70
72
|
```json
|
|
71
73
|
{
|
|
@@ -73,8 +75,7 @@ For a persistent role override with a backup model for provider failures:
|
|
|
73
75
|
"agentOverrides": {
|
|
74
76
|
"reviewer": {
|
|
75
77
|
"model": "anthropic/claude-sonnet-4",
|
|
76
|
-
"thinking": "high"
|
|
77
|
-
"fallbackModels": ["openai-codex/gpt-5.6-luna:low"]
|
|
78
|
+
"thinking": "high"
|
|
78
79
|
}
|
|
79
80
|
}
|
|
80
81
|
}
|
|
@@ -87,7 +88,7 @@ For a persistent role override with a backup model for provider failures:
|
|
|
87
88
|
|
|
88
89
|
Set `fast: true` on a run, in agent frontmatter, or in `subagents.agentOverrides.<name>.fast` to request the OpenAI priority service tier for supported native OpenAI-Codex children. This can use a higher quota tier or cost more. It is off by default.
|
|
89
90
|
|
|
90
|
-
Fast mode fails before launch unless
|
|
91
|
+
Fast mode fails before launch unless the resolved model is on the allowlist. The current allowlist is `openai-codex/gpt-5.6-luna` and `openai-codex/gpt-5.6-sol`. External runners, Anthropic models, and other providers do not use fast mode.
|
|
91
92
|
|
|
92
93
|
## Recommended model tiering (optional)
|
|
93
94
|
|
|
@@ -100,19 +101,7 @@ A setup that works well in practice: route agents by task shape instead of runni
|
|
|
100
101
|
|
|
101
102
|
The routing rule: use the capability tiers (1–3) when the task is well-scoped, and the intent tier (4) when scoping or judging is the task itself.
|
|
102
103
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
```yaml
|
|
106
|
-
---
|
|
107
|
-
name: shaper
|
|
108
|
-
description: Open-ended design/UX/product/planning agent for ambiguous tasks
|
|
109
|
-
model: anthropic/claude-fable-5
|
|
110
|
-
thinking: medium
|
|
111
|
-
fallbackModels: openai-codex/gpt-5.5:high
|
|
112
|
-
---
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
One interaction worth knowing for tier 4: forked context over an Anthropic parent transcript with signed thinking blocks forces the child's thinking off, so intent-tier agents work best with fresh context.
|
|
104
|
+
Each launch resolves one model and starts the child once. Provider, authentication, quota, rate-limit, stream, empty-response, context-overflow, and provisioning failures are returned from that attempt. To try another model, the parent or operator must issue a later explicit launch.
|
|
116
105
|
|
|
117
106
|
## Thinking level defaults
|
|
118
107
|
|
|
@@ -144,7 +133,7 @@ Set `subagents.maxThinking` to enforce a hard maximum for every native Pi child.
|
|
|
144
133
|
}
|
|
145
134
|
```
|
|
146
135
|
|
|
147
|
-
Requests above the ceiling fail before child startup; the setting covers frontmatter, `agentOverrides`, per-run overrides,
|
|
136
|
+
Requests above the ceiling fail before child startup; the setting covers frontmatter, `agentOverrides`, per-run overrides, parallel/chain children, nested launches, and resumed children. Project settings take precedence over user settings. External runners retain their existing behavior.
|
|
148
137
|
|
|
149
138
|
## Extension defaults
|
|
150
139
|
|
|
@@ -219,11 +208,11 @@ To keep subagents inside a budget or compliance profile, enforce a model scope.
|
|
|
219
208
|
- `agents.<name>` adds a second allow-list for that agent. The model must pass both the global list and the matching agent list, so an agent rule cannot weaken the global rule. Agent rules inherit `enforce` and `strict` when those fields are absent.
|
|
220
209
|
- A top-level `enforce: true` with only agent allow-lists restricts only those named agents. Unknown names are allowed so settings can be shared across projects and machines.
|
|
221
210
|
- Models you pass explicitly — the tool-call `model`, `--model`, or a clarify pick — error and abort the run.
|
|
222
|
-
- By default, models from agent frontmatter, `subagents.defaultModel`, the inherited parent session model
|
|
223
|
-
- Set `strict: true` with `enforce: true` to reject every resolved out-of-scope model
|
|
211
|
+
- By default, models from agent frontmatter, `subagents.defaultModel`, or the inherited parent session model only warn and remain available, so existing configurations keep working while you tighten the scope.
|
|
212
|
+
- Set `strict: true` with `enforce: true` to reject every resolved out-of-scope model, including inherited models.
|
|
224
213
|
- `enforce: true` requires at least one non-empty global or agent `allow` list; otherwise the config is rejected at load time.
|
|
225
214
|
|
|
226
|
-
Model scope is policy only. It rejects or warns; it does not select a cheaper model. Set `agentOverrides.worker.model` to choose a worker model and use `modelScope.agents.worker` to prevent a per-run override
|
|
215
|
+
Model scope is policy only. It rejects or warns; it does not select a cheaper model. Set `agentOverrides.worker.model` to choose a worker model and use `modelScope.agents.worker` to prevent a per-run override from escaping that restriction.
|
|
227
216
|
|
|
228
217
|
`inherit` expands in the parent process at each launch. It is never sent to the child as a model id. A nested child therefore inherits its immediate parent's current model, not the original top-level model. If no parent model is available, an enforced `inherit` entry does not match and fails closed.
|
|
229
218
|
|