pi-better-subagents 0.27.0 → 0.27.2
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/child-ownership.ts +14 -1
- package/effective-settings.ts +80 -6
- package/index.ts +5 -14
- package/package.json +1 -1
- package/shared-execution-policy.ts +54 -14
package/child-ownership.ts
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
import { parse } from "shell-quote";
|
|
3
3
|
import { STEER_FILE_ENV } from "./child-steer.ts";
|
|
4
|
+
import { supportsPromptSections } from "./shared-execution-policy.ts";
|
|
4
5
|
|
|
5
6
|
export const WORKER_HANDOFF = "Worker ownership: complete your assigned implementation or diagnosis, run focused checks, push only when authorized, write the requested result, then return. Pending CI is a handoff, not a failed implementation or a CI pass. The coordinator owns CI/PR monitoring, review scheduling, readiness, enqueueing and merge. Do not start external delivery watchers or background monitoring. Short status reads and failed-log retrieval for diagnosis are allowed. Legitimate local tests and builds may run to completion within their command limits. Use Bash for short diagnostic commands and focused checks needed to implement the change. When supervised background tools are available, retain ownership of assigned validation: launch a known long command with bg_task_spawn or repeated observation with bg_task_watch, continue independent work, then call wait_for_operations to park when no independent work remains. On continuation, inspect the operation's terminal evidence and acknowledge its interpretation before continuing the assignment. Parking is a saved-conversation dependency, not a request for the parent model to relay commands or results. An explicit restricted tool loadout may omit background support; return the exact command, cwd, required environment variable names (never secret values), current evidence and remaining validation to the coordinator. Do not emulate background execution with polling, sleep loops, nohup or shell detachment. Established command-only operations and external delivery monitoring belong to the coordinator's background tools.";
|
|
7
|
+
export const WORKER_HANDOFF_SECTION = "worker_handoff";
|
|
6
8
|
const REFUSAL = "Worker ownership: CI/PR monitoring belongs to the coordinator. Return the PR/run ID, pushed HEAD and current evidence with CI pending; do not retry the watcher through another tool or script. Local tests/builds and short diagnostic status/log reads remain allowed.";
|
|
7
9
|
const WATCH_SCRIPTS = new Set(["watch-pr-delivery.mjs", "watch-delivery.mjs", "watch-candidate-delivery.mjs"]);
|
|
8
10
|
const nameOf = (value: string) => value.replaceAll("\\", "/").split("/").at(-1)!.replace(/\.exe$/i, "");
|
|
@@ -133,7 +135,18 @@ export function workerMonitoringRefusal(toolName: string, input: unknown): strin
|
|
|
133
135
|
export default function childOwnership(pi: Pick<ExtensionAPI, "on">, env: NodeJS.ProcessEnv = process.env): void {
|
|
134
136
|
// This marker is supplied by the parent on every child launch, including clean/unsandboxed runs.
|
|
135
137
|
if (!env[STEER_FILE_ENV]) return;
|
|
136
|
-
|
|
138
|
+
// A section on hosts that render them; appended text on hosts that do not.
|
|
139
|
+
// Returning a prompt on a modern host would set forceSystemPrompt, and the
|
|
140
|
+
// request would carry a snapshot, so later sections never arrive.
|
|
141
|
+
pi.on("before_agent_start", (event) => {
|
|
142
|
+
if (!supportsPromptSections(event.systemPromptOptions)) {
|
|
143
|
+
return { systemPrompt: `${event.systemPrompt}\n\n${WORKER_HANDOFF}` };
|
|
144
|
+
}
|
|
145
|
+
const options = event.systemPromptOptions as { sections?: Record<string, string> };
|
|
146
|
+
const sections = (options.sections ??= {});
|
|
147
|
+
sections[WORKER_HANDOFF_SECTION] = WORKER_HANDOFF;
|
|
148
|
+
return undefined;
|
|
149
|
+
});
|
|
137
150
|
pi.on("tool_call", (event) => {
|
|
138
151
|
const reason = workerMonitoringRefusal(event.toolName, event.input);
|
|
139
152
|
if (reason) return { block: true, reason };
|
package/effective-settings.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
2
|
import { delegationPrompt, type DelegationMode } from "./delegation.ts";
|
|
3
3
|
|
|
4
|
+
import { EXECUTION_POLICY_TEXT, publishExecutionPolicy, supportsPromptSections } from "./shared-execution-policy.ts";
|
|
5
|
+
|
|
4
6
|
export const SUBAGENT_SETTINGS_CONTEXT = "pi-better-subagents-settings";
|
|
5
7
|
|
|
6
8
|
export interface EffectiveSubagentSettings {
|
|
@@ -28,19 +30,64 @@ export function effectiveSubagentSettings(
|
|
|
28
30
|
}
|
|
29
31
|
|
|
30
32
|
export function formatSubagentSettings(settings: EffectiveSubagentSettings): string {
|
|
33
|
+
const manual = settings.delegationMode === "manual";
|
|
34
|
+
const capacity = manual
|
|
35
|
+
? "The limit is a ceiling, not a target. In manual mode it bounds only work the user or an active workflow explicitly delegates; no slot count is an invitation to launch work."
|
|
36
|
+
: "The limit is a ceiling, not a target. Launch ready, independent, useful work when a suitable subagent is available.";
|
|
37
|
+
// No occupancy counters here. This text is injected into the conversation and
|
|
38
|
+
// may only ever be appended to, so anything volatile would force either a
|
|
39
|
+
// rewrite of already-sent content (which invalidates the provider's cached
|
|
40
|
+
// prefix) or one more copy per change. Admission rechecks capacity at the
|
|
41
|
+
// spawn anyway; live counts stay available through the subagent_settings tool.
|
|
31
42
|
return [
|
|
32
43
|
`Subagent settings: revision ${settings.revision}`,
|
|
33
44
|
`Delegation: ${settings.delegationMode} (${settings.sources.delegationMode})`,
|
|
34
45
|
`Concurrency limit: ${settings.maxConcurrent} (${settings.sources.maxConcurrent})`,
|
|
35
|
-
|
|
36
|
-
`Occupied slots: ${settings.occupiedSlots}`,
|
|
37
|
-
`Available slots: ${settings.availableSlots}`,
|
|
38
|
-
"The limit is a ceiling, not a target. Launch ready, independent, useful work within available capacity. " +
|
|
39
|
-
"This is a point-in-time snapshot; spawn admission rechecks capacity. Lowering the limit does not stop existing runs.",
|
|
46
|
+
// Mode first: the policy governs the settings that follow it.
|
|
40
47
|
delegationPrompt(settings.delegationMode),
|
|
48
|
+
capacity + " Spawn admission rechecks capacity; lower the limit without stopping existing runs.",
|
|
41
49
|
].join("\n");
|
|
42
50
|
}
|
|
43
51
|
|
|
52
|
+
/**
|
|
53
|
+
* Publish the delegation policy as its own prompt section.
|
|
54
|
+
*
|
|
55
|
+
* A section survives a summary that rewrites the conversation without being
|
|
56
|
+
* appended text, and it is part of the cached prefix, so it costs nothing per
|
|
57
|
+
* request while it stays unchanged. Assignment is idempotent: a repeated turn
|
|
58
|
+
* rewrites the same value and pi's section diff reports no change.
|
|
59
|
+
*
|
|
60
|
+
* Nothing volatile goes in here: live occupancy would rewrite the cached prefix
|
|
61
|
+
* on every run, and admission rechecks capacity at spawn anyway.
|
|
62
|
+
*/
|
|
63
|
+
export const SUBAGENT_SETTINGS_SECTION = "subagents";
|
|
64
|
+
|
|
65
|
+
/** `sections` is optional because the repo typechecks against older pi typings. */
|
|
66
|
+
export interface PromptSectionTarget {
|
|
67
|
+
sections?: Record<string, string>;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Published with the settings block: the block is the authority on delegation, so
|
|
72
|
+
* the sentence that says so has to sit beside it rather than in a separate section
|
|
73
|
+
* whose position would depend on package load order.
|
|
74
|
+
*
|
|
75
|
+
* The note must not say the block is at the end of the prompt. Custom sections
|
|
76
|
+
* render in publication order, so Background Tasks and Goal publish after this one;
|
|
77
|
+
* naming its own section keeps the sentence true whatever the load order.
|
|
78
|
+
*/
|
|
79
|
+
const SUBAGENT_DELEGATION_NOTE = "Treat the Subagent settings block in this section as the authoritative delegation mode and cap. Its delegation guidance replaces earlier mode-specific guidance, including guidance in a plan. Live occupancy is not pushed into context: inspect subagent_settings when it matters, and never treat the concurrency limit as a target number of agents.";
|
|
80
|
+
|
|
81
|
+
export function publishSubagentSettings<T extends object>(options: T, settings: EffectiveSubagentSettings): T {
|
|
82
|
+
// Note first, block last inside the section: the note introduces the block it
|
|
83
|
+
// describes. Section order in the prompt is a separate concern, decided by
|
|
84
|
+
// publication order, so the note never claims a position in the whole prompt.
|
|
85
|
+
const target = options as PromptSectionTarget;
|
|
86
|
+
const sections = (target.sections ??= {});
|
|
87
|
+
sections[SUBAGENT_SETTINGS_SECTION] = `${SUBAGENT_DELEGATION_NOTE}\n\n${formatSubagentSettings(settings)}`;
|
|
88
|
+
return options;
|
|
89
|
+
}
|
|
90
|
+
|
|
44
91
|
export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSettings) {
|
|
45
92
|
return {
|
|
46
93
|
name: "subagent_settings",
|
|
@@ -60,4 +107,31 @@ export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSet
|
|
|
60
107
|
details: settings, structuredContent: settings };
|
|
61
108
|
},
|
|
62
109
|
};
|
|
63
|
-
}
|
|
110
|
+
}
|
|
111
|
+
/** What a handler receives; only these two fields are used. */
|
|
112
|
+
export interface BeforeAgentStartEvent {
|
|
113
|
+
systemPrompt: string;
|
|
114
|
+
systemPromptOptions?: unknown;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Deliver the policy and the settings on both kinds of host.
|
|
119
|
+
*
|
|
120
|
+
* pi before 0.84.4+ renders no custom sections, so publishing alone would
|
|
121
|
+
* deliver nothing on a host this package still declares support for. There the
|
|
122
|
+
* guidance is appended as text, which is what those hosts did before sections.
|
|
123
|
+
*/
|
|
124
|
+
export function deliverSubagentPrompt(event: BeforeAgentStartEvent, settings: EffectiveSubagentSettings): { systemPrompt: string } | undefined {
|
|
125
|
+
if (!supportsPromptSections(event.systemPromptOptions)) {
|
|
126
|
+
// Both packages carry this policy, so appending blindly would print it
|
|
127
|
+
// once per publisher; keep the text path idempotent as it used to be.
|
|
128
|
+
const policy = event.systemPrompt.includes(EXECUTION_POLICY_TEXT) ? "" : `${EXECUTION_POLICY_TEXT}\n\n`;
|
|
129
|
+
const block = `${SUBAGENT_DELEGATION_NOTE}\n\n${formatSubagentSettings(settings)}`;
|
|
130
|
+
const guidance = event.systemPrompt.includes(block) ? "" : block;
|
|
131
|
+
return { systemPrompt: `${event.systemPrompt}\n\n${policy}${guidance}` };
|
|
132
|
+
}
|
|
133
|
+
const options = event.systemPromptOptions as PromptSectionTarget;
|
|
134
|
+
publishExecutionPolicy(options);
|
|
135
|
+
publishSubagentSettings(options, settings);
|
|
136
|
+
return undefined;
|
|
137
|
+
}
|
package/index.ts
CHANGED
|
@@ -38,7 +38,7 @@ import { selectSessionByName } from "./session-selection.ts";
|
|
|
38
38
|
import { isWithinWorkspace } from "./workspace-scope.ts";
|
|
39
39
|
import { loadConfig, writeDelegationMode, writeSubagentSettings, isConcurrencyCap, normalizeConcurrencyCap, normalizeTools, resolveExtensionPath, configPath, selfDir, SAFE_DEFAULT_TOOLS, SAFE_CLEAN_TOOLS } from "./config.ts";
|
|
40
40
|
import { createSubagentSettingsPage } from "./settings-page.ts";
|
|
41
|
-
import { effectiveSubagentSettings, formatSubagentSettings, subagentSettingsTool, SUBAGENT_SETTINGS_CONTEXT } from "./effective-settings.ts";
|
|
41
|
+
import { deliverSubagentPrompt, effectiveSubagentSettings, formatSubagentSettings, subagentSettingsTool, SUBAGENT_SETTINGS_CONTEXT } from "./effective-settings.ts";
|
|
42
42
|
import { STEER_FILE_ENV, readSteerReceipt } from "./child-steer.ts";
|
|
43
43
|
import {
|
|
44
44
|
decideTiming,
|
|
@@ -56,7 +56,6 @@ import {
|
|
|
56
56
|
} from "./timing.ts";
|
|
57
57
|
import { readAppendedLines, type LogCursor } from "./log-cursor.ts";
|
|
58
58
|
import { DELEGATION_MODES, DELEGATION_MODE_REQUEST, isDelegationMode, normalizeDelegationMode, type DelegationMode } from "./delegation.ts";
|
|
59
|
-
import { appendExecutionPolicy } from "./shared-execution-policy.ts";
|
|
60
59
|
import { resolveChildClosure, resolveChildLaunch, configSnapshot } from "./child-dependencies.mjs";
|
|
61
60
|
import { PREFLIGHT_ENV } from "./child-preflight.mjs";
|
|
62
61
|
import { resolveExtensions, extensionArgs } from "./extensions.ts";
|
|
@@ -3602,18 +3601,10 @@ export default function (pi: ExtensionAPI) {
|
|
|
3602
3601
|
const discoveryTool = agentOperations.createDiscoveryTool(Type as never);
|
|
3603
3602
|
pi.registerTool(discoveryTool as Parameters<ExtensionAPI["registerTool"]>[0]);
|
|
3604
3603
|
|
|
3605
|
-
|
|
3606
|
-
|
|
3607
|
-
|
|
3608
|
-
|
|
3609
|
-
pi.on("context", (event) => {
|
|
3610
|
-
const settings = effectiveSettings();
|
|
3611
|
-
return { messages: [
|
|
3612
|
-
...event.messages.filter(message => message.role !== "custom" || message.customType !== SUBAGENT_SETTINGS_CONTEXT),
|
|
3613
|
-
{ role: "custom" as const, customType: SUBAGENT_SETTINGS_CONTEXT,
|
|
3614
|
-
content: formatSubagentSettings(settings), display: false, details: settings, timestamp: Date.now() },
|
|
3615
|
-
] };
|
|
3616
|
-
});
|
|
3604
|
+
// Sections on a host that renders them; text only where it renders none.
|
|
3605
|
+
// Returning a prompt on modern pi would set forceSystemPrompt, and the request
|
|
3606
|
+
// would then carry a snapshot, so sections published after it never arrive.
|
|
3607
|
+
pi.on("before_agent_start", (event) => deliverSubagentPrompt(event, effectiveSettings()));
|
|
3617
3608
|
|
|
3618
3609
|
// ---- live-status lifecycle -----------------------------------------
|
|
3619
3610
|
pi.on("agent_start", async (_event, ctx) => {
|
package/package.json
CHANGED
|
@@ -1,21 +1,61 @@
|
|
|
1
1
|
// Generated from packages/pi-better-harness/extensions/execution-policy.ts. Do not edit directly.
|
|
2
|
-
/**
|
|
3
|
-
|
|
2
|
+
/**
|
|
3
|
+
* Harness-wide scheduling guidance, vendored so standalone extensions share it.
|
|
4
|
+
*
|
|
5
|
+
* Published as a named system-prompt section, never as appended text. A
|
|
6
|
+
* `before_agent_start` handler that returns `systemPrompt` sets
|
|
7
|
+
* `forceSystemPrompt`, and a forced prompt is opaque to pi: `buildSystemPromptState`
|
|
8
|
+
* returns `{ content }` with no sections while `diffSystemPromptSections` keeps
|
|
9
|
+
* diffing the sections the request therefore never shows. The request carries a
|
|
10
|
+
* rendered snapshot, so any section published after that snapshot never reaches
|
|
11
|
+
* it, so every package that speaks here publishes a section.
|
|
12
|
+
*/
|
|
13
|
+
export const EXECUTION_POLICY_SECTION = "harness_execution_policy";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* The minimum shape this module needs. `sections` stays optional because this
|
|
17
|
+
* repo typechecks against older pi typings whose event options predate sections;
|
|
18
|
+
* the shipped runtime always supplies the map.
|
|
19
|
+
*/
|
|
20
|
+
export interface PromptSectionTarget {
|
|
21
|
+
sections?: Record<string, string>;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export const EXECUTION_POLICY_TEXT: string = [
|
|
4
25
|
"Harness execution policy: concurrency is separate from subagent delegation.",
|
|
5
|
-
"Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent independently verifiable
|
|
26
|
+
"Before multi-unit work, identify ready, authorized, independent units, actual prerequisites, shared mutable resources, and capacity or availability constraints. Represent each independently verifiable deliverable as its own plan step; do not create dependencies from list order.",
|
|
6
27
|
"Start all ready, authorized, non-conflicting units concurrently within known resource limits before waiting for any one to finish. Reassess ready work after launches and results; continue unblocked foreground work instead of polling running tasks. Do not equate one background launch with scheduling all ready work.",
|
|
7
28
|
"Serialize only for a concrete dependency, conflicting writes or ownership, resource or concurrency limit, documented rollout gate, or explicit availability requirement. Record the reason in the plan or explain it to the user. Do not invent a canary or host-by-host availability requirement.",
|
|
8
|
-
"If concurrency raises an unresolved material operational trade-off
|
|
9
|
-
"Choose the execution mechanism after deciding what can run together: foreground tools for small, tightly coupled, or interactive work; subagents for bounded independent reasoning or implementation when the active delegation mode permits; background tasks for independent long-running commands or waits. Manual delegation forbids proactive subagents, not concurrent foreground tools or background commands.
|
|
10
|
-
"Established command-only jobs and external waits belong to background operations, including in coordinator mode. Use bg_task_spawn for a long command
|
|
11
|
-
"If a worker hands back a command,
|
|
29
|
+
"If concurrency raises an unresolved material operational trade-off, ask the user once before the affected operations and continue independent preparation meanwhile. Existing authorization, safety checks, workflow prerequisites, and human-approved rollout constraints remain binding; urgency does not waive them.",
|
|
30
|
+
"Choose the execution mechanism after deciding what can run together: foreground tools for small, tightly coupled, or interactive work; subagents for bounded independent reasoning or implementation when the active delegation mode permits; background tasks for independent long-running commands or waits. Manual delegation forbids proactive subagents, not concurrent foreground tools or background commands. Inspect every launch receipt for failures or skipped work.",
|
|
31
|
+
"Established command-only jobs and external waits belong to background operations, including in coordinator mode. Use bg_task_spawn for a long command, bg_task_watch for a repeated check, and watch_delivery for supported merge delivery. A subagent assignment must require reasoning or implementation beyond launching and waiting. Workers retain their assigned validation: launch or watch, continue independent work, then park with wait_for_operations and inspect the terminal evidence on continuation. Continue independent work while it runs; a task launch is not completion of the assignment.",
|
|
32
|
+
"If a worker hands back a command, launch it through bg_task_spawn or bg_task_watch with the supplied cwd, and inspect its terminal result before claiming verification.",
|
|
12
33
|
"A unit waiting or failing does not block other ready independent units unless the evidence shows a shared blocker. Preserve each unit's guards and rollback boundary. Before completing verification, the plan, or the goal, inspect and integrate every relevant terminal result or failure; launch is not completion.",
|
|
13
34
|
].join("\n");
|
|
14
35
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
36
|
+
/**
|
|
37
|
+
* True when this pi runtime renders custom prompt sections.
|
|
38
|
+
*
|
|
39
|
+
* pi gained `systemPromptOptions.sections` after 0.84.4, and the packages here
|
|
40
|
+
* declare support back to 0.84.4. A section-only publisher is a silent no-op on
|
|
41
|
+
* an older host: the handler runs, the map is populated, and the prompt the model
|
|
42
|
+
* receives is unchanged. Callers must fall back to appending text instead.
|
|
43
|
+
*/
|
|
44
|
+
export function supportsPromptSections(options: unknown): boolean {
|
|
45
|
+
const sections = (options as { sections?: unknown } | undefined)?.sections;
|
|
46
|
+
return typeof sections === "object" && sections !== null;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Publish the policy into `options.sections`.
|
|
51
|
+
*
|
|
52
|
+
* Assignment, not concatenation: two packages publishing the same section write
|
|
53
|
+
* identical text, so load order cannot duplicate or drop it, and a repeated turn
|
|
54
|
+
* rewrites the same value so pi's section diff reports no change.
|
|
55
|
+
*/
|
|
56
|
+
export function publishExecutionPolicy<T extends object>(options: T): T {
|
|
57
|
+
const target = options as PromptSectionTarget;
|
|
58
|
+
const sections = (target.sections ??= {});
|
|
59
|
+
sections[EXECUTION_POLICY_SECTION] = EXECUTION_POLICY_TEXT;
|
|
60
|
+
return options;
|
|
61
|
+
}
|