pi-better-subagents 0.27.1 → 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.
@@ -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
- pi.on("before_agent_start", (event) => ({ systemPrompt: `${event.systemPrompt}\n\n${WORKER_HANDOFF}` }));
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 };
@@ -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 {
@@ -48,18 +50,42 @@ export function formatSubagentSettings(settings: EffectiveSubagentSettings): str
48
50
  }
49
51
 
50
52
  /**
51
- * Append the delegation policy to the end of the system prompt.
53
+ * Publish the delegation policy as its own prompt section.
52
54
  *
53
- * The system prompt is not part of the compaction window, so the policy survives
54
- * a summary that rewrites the conversation. It is also part of the cached
55
- * prefix, so it costs nothing per request while it stays unchanged.
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.
56
59
  *
57
60
  * Nothing volatile goes in here: live occupancy would rewrite the cached prefix
58
61
  * on every run, and admission rechecks capacity at spawn anyway.
59
62
  */
60
- export function appendSubagentSettings(systemPrompt: string, settings: EffectiveSubagentSettings): string {
61
- const policy = formatSubagentSettings(settings);
62
- return systemPrompt.includes(policy) ? systemPrompt : `${systemPrompt}\n\n${policy}`;
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;
63
89
  }
64
90
 
65
91
  export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSettings) {
@@ -81,4 +107,31 @@ export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSet
81
107
  details: settings, structuredContent: settings };
82
108
  },
83
109
  };
84
- }
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 { appendSubagentSettings, 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,12 +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
- pi.on("before_agent_start", (event) => ({
3606
- systemPrompt: appendSubagentSettings(
3607
- `${appendExecutionPolicy(event.systemPrompt)}\n\nTreat the Subagent settings block at the end of this prompt 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.`,
3608
- effectiveSettings(),
3609
- ),
3610
- }));
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()));
3611
3608
 
3612
3609
  // ---- live-status lifecycle -----------------------------------------
3613
3610
  pi.on("agent_start", async (_event, ctx) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-subagents",
3
- "version": "0.27.1",
3
+ "version": "0.27.2",
4
4
  "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -1,21 +1,61 @@
1
1
  // Generated from packages/pi-better-harness/extensions/execution-policy.ts. Do not edit directly.
2
- /** Harness-wide scheduling guidance, vendored so standalone extensions share it. */
3
- const EXECUTION_POLICY = [
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 deliverables (such as each host migration) separately in the plan; do not hide them in one serial rollout step or create dependencies merely from list order.",
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 (for example, draining all hosts could leave no available runners), ask the user once before the affected operations. Continue independent preparation meanwhile. Existing authorization, safety checks, workflow prerequisites, and human-approved rollout constraints remain binding; urgency does not waive them.",
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. Use available batch or parallel tool interfaces where appropriate and inspect every launch receipt for failures or skipped work.",
10
- "Established command-only jobs and external waits belong to background operations, including in coordinator mode. Use bg_task_spawn for a long command and bg_task_watch for a repeated check; use watch_delivery for supported merge delivery so a stateful domain watcher observes the queue. A subagent assignment must require reasoning or implementation beyond launching and waiting. Workers retain their assigned validation: use supervised background tools and wait_for_operations to park, then resume the same conversation to interpret and acknowledge the terminal result. A linked external wait must have a registered observer and an execution owner. Continue independent work while it runs; a task launch or a completed parked attempt is not completion of the assignment.",
11
- "If a worker hands back a command, the coordinator launches it through background tools with the supplied cwd and inspects its terminal result before claiming verification. Workers may run focused implementation checks; moving a command to a worker does not make it a background task.",
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
- export function appendExecutionPolicy(systemPrompt: string): string {
16
- // Inspect the prompt, not module-global state: vendored copies have separate
17
- // module identities, and every fresh turn or reload needs the policy again.
18
- return systemPrompt.includes(EXECUTION_POLICY)
19
- ? systemPrompt
20
- : `${systemPrompt}\n\n${EXECUTION_POLICY}`;
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
+ }