pi-better-subagents 0.26.2 → 0.27.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.
@@ -2,7 +2,7 @@ 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
4
 
5
- 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.";
5
+ 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.";
6
6
  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
7
  const WATCH_SCRIPTS = new Set(["watch-pr-delivery.mjs", "watch-delivery.mjs", "watch-candidate-delivery.mjs"]);
8
8
  const nameOf = (value: string) => value.replaceAll("\\", "/").split("/").at(-1)!.replace(/\.exe$/i, "");
@@ -113,6 +113,17 @@ export function workerMonitoringRefusal(toolName: string, input: unknown): strin
113
113
  (value.args === undefined || (Array.isArray(value.args) && value.args.every((arg) => typeof arg === "string")))
114
114
  ? [value.executable, ...((value.args ?? []) as string[])] : undefined;
115
115
  if (argv && argvWatcher(argv)) return REFUSAL;
116
+ // A batch carries no shared command or argv, so every job has to be inspected
117
+ // on its own; otherwise one job can run a monitor past this refusal.
118
+ if (toolName === "bg_task_spawn_batch") {
119
+ for (const job of Array.isArray(value.jobs) ? value.jobs : []) {
120
+ if (!job || typeof job !== "object") continue;
121
+ const entry = job as Record<string, unknown>;
122
+ if (typeof entry.command === "string" && shellWatcher(entry.command, 0)) return REFUSAL;
123
+ if (Array.isArray(entry.argv) && entry.argv.every((arg) => typeof arg === "string") && argvWatcher(entry.argv)) return REFUSAL;
124
+ }
125
+ return;
126
+ }
116
127
  if (["bash", "remote_bash", "bg_task", "bg_task_spawn", "bg_task_watch"].includes(toolName)) {
117
128
  if (typeof value.command === "string" && shellWatcher(value.command, 0)) return REFUSAL;
118
129
  if (Array.isArray(value.argv) && value.argv.every((arg) => typeof arg === "string") && argvWatcher(value.argv)) return REFUSAL;
package/cleanup.ts CHANGED
@@ -8,8 +8,7 @@ import {
8
8
  writeFileSync,
9
9
  } from "node:fs";
10
10
  import { join, relative, sep } from "node:path";
11
- import {
12
- ABANDONED_LAUNCH_GRACE_MS,
11
+ import { ABANDONED_LAUNCH_GRACE_MS,
13
12
  abandonedLaunchRecord,
14
13
  baseDir,
15
14
  listMetas,
@@ -26,6 +25,7 @@ import {
26
25
  sessionsDir,
27
26
  type RunMeta,
28
27
  type RunStatus,
28
+ listPendingParkedRuns,
29
29
  } from "./registry.ts";
30
30
  import type { SubagentConfig } from "./config.ts";
31
31
  import {
@@ -337,6 +337,15 @@ function planCleanupOccupancy(
337
337
  }
338
338
  }
339
339
 
340
+ // A parked worker still owns its assignment: its saved conversation and its
341
+ // owned workspace must survive until the wait is consumed or cancelled,
342
+ // otherwise the automatic continuation would reopen nothing. The park
343
+ // disposition is the evidence, so an unprotected park cannot be swept.
344
+ for (const parked of listPendingParkedRuns(metas)) {
345
+ runIds.add(parked.id);
346
+ paths.push(...ownedResources(parked));
347
+ }
348
+
340
349
  const sessions = new Set<string>(protect?.sessionIds ?? []);
341
350
  for (const meta of metas) {
342
351
  if (runIds.has(meta.id)) sessions.add(meta.sessionId);
package/docs/usage.md CHANGED
@@ -178,6 +178,37 @@ If new parameters are missing after an npm upgrade, run `/reload` in Pi.
178
178
  Updating files on disk does not replace extension code already loaded in a live
179
179
  session.
180
180
 
181
+ ## Waiting without occupying a worker slot
182
+
183
+ When Background Tasks is loaded, eligible workers receive a guarded bridge to
184
+ supervised local commands. The bridge retains the worker's captured permissions
185
+ and applies the current Background Tasks policy as well. Explicit tool exclusions
186
+ and clean loadouts can withhold the bridge.
187
+
188
+ A worker starts a long validation command, continues independent work, then calls
189
+ `wait_for_operations` with its owned task ids. Call this tool directly as the only
190
+ tool call in its assistant message. A nested codemode call cannot deliver the
191
+ SDK termination boundary. The SDK must be 0.82.1 or later.
192
+
193
+ Parking saves the wait result at the end of the native conversation. The attempt
194
+ then exits cleanly and releases its capacity slot. Its attempt status remains
195
+ `completed`, but its park disposition means the assignment is unfinished. The
196
+ navigator shows the wait phase and retains the row while the wait is pending.
197
+ Closing that row cancels automatic resumption.
198
+
199
+ Once all dependencies are terminal, the same saved conversation can resume with
200
+ a new attempt id. The resumed worker can read operations launched by its earlier
201
+ attempt. It inspects status and logs, then calls `acknowledge_operation_result`
202
+ with the exact revisions and an interpretation note. Success, failure, cancellation,
203
+ timeout and lost execution all settle a dependency; the worker must interpret the
204
+ outcome before proceeding.
205
+
206
+ Resumption requires the owning parent session and eligible branch to be active.
207
+ Capacity, Goal, workflow, permissions, writer ownership and cancellation are
208
+ checked again. Full capacity leaves the wait ready. Missing or conflicting
209
+ recovery evidence leaves it held with a reason. The runner survives worker and Pi
210
+ exit, but v1 does not run an unattended model after Pi shuts down.
211
+
181
212
  ## Codemode batch launches
182
213
 
183
214
  On Pi 0.99.1 or newer, enable native codemode alongside the existing direct
@@ -643,9 +674,19 @@ mid-turn** — no `tool_execution_end`, no `agent_end`. Historically, exit 0 was
643
674
  indistinguishable from a clean finish, so all 17 observed mid-turn exits were
644
675
  reported as ✓ completed. Finalization now requires terminal agent evidence and
645
676
  no unmatched tool starts. Lifecycle validation classifies runs as `complete`,
646
- `incomplete_no_terminal_event`, `incomplete_open_tools`, `failed_exit`, or
647
- `killed`; incoherent exit-0 streams are recorded as failed with named lifecycle
648
- diagnostics on `subagent_result` and attention wording on completion callbacks.
677
+ `incomplete_no_terminal_event`, `incomplete_open_tools`, `failed_exit`,
678
+ `failed_model_error`, or `killed`; incoherent exit-0 streams are recorded as
679
+ failed with named lifecycle diagnostics on `subagent_result` and attention
680
+ wording on completion callbacks.
681
+
682
+ A stream whose **last** model request failed - and that no later assistant turn
683
+ superseded - is recorded as `failed_model_error`, never `complete`. Pi ends the
684
+ loop normally after a provider error, so such a child exits 0 with a terminal
685
+ event and used to look like a finished run that had simply produced very little
686
+ text. The result now reports the failure and repeats the provider error verbatim
687
+ (for example a virtual model that could not route: `Model router: no eligible
688
+ Flash model is available.`). An earlier failure that auto-retry recovered does
689
+ not fail the run.
649
690
 
650
691
  A tool allowlist alone cannot fix this. `--tools` restricts what the model may
651
692
  *call*; the package already overrode builtin `bash` at startup, so the `bash` in
@@ -28,19 +28,40 @@ export function effectiveSubagentSettings(
28
28
  }
29
29
 
30
30
  export function formatSubagentSettings(settings: EffectiveSubagentSettings): string {
31
+ const manual = settings.delegationMode === "manual";
32
+ const capacity = manual
33
+ ? "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."
34
+ : "The limit is a ceiling, not a target. Launch ready, independent, useful work when a suitable subagent is available.";
35
+ // No occupancy counters here. This text is injected into the conversation and
36
+ // may only ever be appended to, so anything volatile would force either a
37
+ // rewrite of already-sent content (which invalidates the provider's cached
38
+ // prefix) or one more copy per change. Admission rechecks capacity at the
39
+ // spawn anyway; live counts stay available through the subagent_settings tool.
31
40
  return [
32
41
  `Subagent settings: revision ${settings.revision}`,
33
42
  `Delegation: ${settings.delegationMode} (${settings.sources.delegationMode})`,
34
43
  `Concurrency limit: ${settings.maxConcurrent} (${settings.sources.maxConcurrent})`,
35
- `Running: ${settings.runningCount}; reserved: ${settings.pendingCount}`,
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.",
44
+ // Mode first: the policy governs the settings that follow it.
40
45
  delegationPrompt(settings.delegationMode),
46
+ capacity + " Spawn admission rechecks capacity; lower the limit without stopping existing runs.",
41
47
  ].join("\n");
42
48
  }
43
49
 
50
+ /**
51
+ * Append the delegation policy to the end of the system prompt.
52
+ *
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.
56
+ *
57
+ * Nothing volatile goes in here: live occupancy would rewrite the cached prefix
58
+ * on every run, and admission rechecks capacity at spawn anyway.
59
+ */
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
+ }
64
+
44
65
  export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSettings) {
45
66
  return {
46
67
  name: "subagent_settings",
package/finalization.ts CHANGED
@@ -19,10 +19,12 @@ import {
19
19
  effectiveStatus,
20
20
  isFinalResultStatus,
21
21
  readMeta,
22
+ updateParkRecord,
22
23
  writeMeta,
23
24
  type RunMeta,
24
25
  } from "./registry.ts";
25
26
  import { fmtElapsed, fmtSpend } from "./widget.ts";
27
+ import { evaluateParkDisposition, type ParkDisposition } from "./worker-waits.ts";
26
28
 
27
29
  export interface FinalizeHooks {
28
30
  renderWidget?: () => void;
@@ -38,6 +40,8 @@ export interface FinalizeResult {
38
40
  meta?: RunMeta;
39
41
  outcome?: ChildExitOutcome;
40
42
  delivery?: { content: string; options: Record<string, unknown> };
43
+ /** Present when this exit was a park or looked like one but could not be proven. */
44
+ park?: ParkDisposition;
41
45
  }
42
46
 
43
47
  /**
@@ -59,33 +63,71 @@ export function finalizeRun(
59
63
  const r = parseRunForLifecycle(id);
60
64
  const outcome = classifyChildExit(code, r);
61
65
  collectRunFailures(id, meta.cwd, true);
62
- if (!outcome.incomplete && code !== null) {
66
+ // A run can now end exit 0 as failed (a final request the model could not
67
+ // serve), so "not incomplete and has an exit code" no longer means success.
68
+ const completed = outcome.status === "completed";
69
+ if (completed && code !== null) {
63
70
  observeFailures(failurePath(id), ["orphaned", "lost"].map((status) => ({
64
71
  id: `supervision:${status}:exit-recovered`, operation: `supervision:${status}`,
65
72
  kind: "recovered" as const, incidents: [`supervision:${status}`],
66
73
  })));
67
74
  }
68
- if (code !== 0 || outcome.incomplete) {
75
+ if (!completed) {
76
+ const summary = outcome.incomplete ? "Child exit evidence is incomplete"
77
+ : outcome.diagnostics.modelError ? `Child exited with code ${code}: ${outcome.diagnostics.modelError}`
78
+ : `Child exited with code ${code}`;
69
79
  observeFailures(failurePath(id), [{ id: `exit:${code ?? "unknown"}:${outcome.classification}`,
70
80
  operation: "child-exit", kind: outcome.incomplete ? "incomplete" : "failure",
71
- category: "exit", summary: outcome.incomplete ? "Child exit evidence is incomplete" : `Child exited with code ${code}` }]);
81
+ category: "exit", summary }]);
72
82
  }
73
83
  meta.status = outcome.status;
74
84
  meta.lifecycleClassification = outcome.classification;
75
85
  if (outcome.incomplete) meta.failureReason = "incomplete-stream";
76
86
  meta.exitCode = code;
77
87
  meta.endedAt = Date.now();
88
+ // A clean park finishes this ATTEMPT, not the assignment. It is only accepted
89
+ // with a durable park record whose saved-conversation checkpoint still
90
+ // verifies; a failed, incoherent or unverifiable exit stays an ordinary exit
91
+ // and the recorded wait is held for its owner.
92
+ const park = evaluateParkDisposition({
93
+ runId: id,
94
+ cleanExit: code === 0 && !outcome.incomplete && !outcome.diagnostics.modelError,
95
+ });
96
+ const parked = park.parked && park.record !== undefined;
97
+ if (parked && park.record) {
98
+ meta.park = park.record;
99
+ // The rest of the attempt is complete; the assignment is still waiting.
100
+ meta.status = "completed";
101
+ }
78
102
  const callback = meta.callback !== false;
79
103
  if (callback
80
104
  && meta.completionCallbackPendingAt === undefined
81
105
  && meta.completionCallbackSentAt === undefined
82
106
  && meta.completionCallbackSuppressedAt === undefined) {
83
- meta.completionCallbackPendingAt = meta.endedAt;
107
+ if (parked) {
108
+ // A parked attempt owes no completion callback: the continuation
109
+ // resumes the same conversation and reports the assignment's result.
110
+ meta.completionCallbackSuppressedAt = meta.endedAt;
111
+ meta.completionCallbackSuppressedReason = `parked on wait ${park.record?.waitId} generation ${park.record?.generation}`;
112
+ } else {
113
+ meta.completionCallbackPendingAt = meta.endedAt;
114
+ }
84
115
  }
85
116
  writeMeta(meta);
117
+ if (!parked && park.record) {
118
+ // A park disposition existed but could not be proven on exit. Hold it in
119
+ // both durable copies (park.json + metadata) so nothing resumes it; the
120
+ // host wrapper reports the same state to the coordinator.
121
+ updateParkRecord(id, {
122
+ phase: "held",
123
+ heldReason: park.reason ?? "the exit was not a clean park",
124
+ });
125
+ }
86
126
 
87
127
  const label = meta.name ? `${meta.name} (${id})` : id;
88
- const verdict = outcome.verdict;
128
+ const verdict = parked
129
+ ? `parked · waiting for ${park.record?.waitId ?? "its dependency"}`
130
+ : outcome.verdict;
89
131
  const el = fmtElapsed(meta.endedAt - meta.startedAt);
90
132
  const spend = fmtSpend(r.usage);
91
133
  const humanStat = `${el}${spend ? ` · ${spend}` : ""}`;
@@ -98,8 +140,8 @@ export function finalizeRun(
98
140
  // Best-effort human toast. ctx may be stale by now; never let it throw.
99
141
  try {
100
142
  hooks.notify?.(
101
- `Subagent ${label} ${verdict} · ${humanStat}`,
102
- meta.status === "completed" ? "info" : "warning",
143
+ `Subagent ${label} ${parked ? verdict : `${verdict} · ${humanStat}`}`,
144
+ meta.status === "completed" || parked ? "info" : "warning",
103
145
  );
104
146
  } catch {
105
147
  /* ignore */
@@ -118,7 +160,9 @@ export function finalizeRun(
118
160
  lifecycleClassification: outcome.classification,
119
161
  resultText: r.finalText || r.lastActivity || "",
120
162
  });
121
- if (callback) {
163
+ // A parked attempt sends nothing to the model: its assignment is still open
164
+ // and the same conversation resumes to interpret the result.
165
+ if (callback && !parked) {
122
166
  hooks.sendMessage?.(
123
167
  { customType: "subagent-complete", content: delivery.content, display: true },
124
168
  delivery.options,
@@ -130,6 +174,7 @@ export function finalizeRun(
130
174
  meta: readMeta(id),
131
175
  outcome,
132
176
  delivery,
177
+ ...(park.parked || park.record ? { park } : {}),
133
178
  };
134
179
  }
135
180
 
package/goal-provider.ts CHANGED
@@ -1,10 +1,43 @@
1
1
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
2
- import { belongsToOrigin, effectiveStatus, listMetasForParent, onMetaChanged } from "./registry.ts";
2
+ import {
3
+ belongsToOrigin,
4
+ effectiveStatus,
5
+ isPendingPark,
6
+ listMetasForParent,
7
+ onMetaChanged,
8
+ readParkRecord,
9
+ } from "./registry.ts";
3
10
 
4
11
  const GOAL_READY_EVENT = "pi-better-goal:ready";
5
12
  const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
6
13
  const goalReadySubscriptions = new WeakSet<ExtensionAPI>();
7
14
 
15
+ /**
16
+ * Project a worker's park disposition for the Goal/navigator surface.
17
+ *
18
+ * A parked attempt is a completed ATTEMPT with an outstanding wait, not a
19
+ * completed assignment (ADR 0020). The row therefore stays non-terminal, keeps
20
+ * `status` as the attempt status, and carries the wait identity in `details` so
21
+ * `waiting for <wait>` and `ready, awaiting slot` can be shown without a second
22
+ * registry. A held or unattributable wait is unhealthy: it needs its owner.
23
+ */
24
+ function parkActivity(meta: Parameters<typeof effectiveStatus>[0]): Record<string, unknown> | undefined {
25
+ const record = meta.park ?? readParkRecord(meta.id);
26
+ if (!record) return undefined;
27
+ if (!isPendingPark(record)) return undefined;
28
+ return {
29
+ waitId: record.waitId,
30
+ generation: record.generation,
31
+ phase: record.phase,
32
+ waiting: record.phase === "parking" || record.phase === "waiting",
33
+ ready: record.phase === "ready",
34
+ held: record.phase === "held",
35
+ ...(record.heldReason ? { heldReason: record.heldReason } : {}),
36
+ ...(record.continuationNote ? { continuationNote: record.continuationNote } : {}),
37
+ ...(record.resumedBy ? { resumedBy: record.resumedBy } : {}),
38
+ };
39
+ }
40
+
8
41
  export function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
9
42
  const emitProvider = (): void => {
10
43
  pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
@@ -27,16 +60,21 @@ export function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
27
60
  .map((meta) => {
28
61
  const status = effectiveStatus(meta);
29
62
  const active = status === "running" || status === "orphaned";
63
+ const park = parkActivity(meta);
64
+ const held = park?.held === true;
30
65
  return {
31
66
  id: meta.id,
32
67
  ...(meta.name ? { label: meta.name } : {}),
33
68
  status,
34
69
  active,
35
- unhealthy: status === "orphaned",
36
- terminal: !active,
37
- attention: status === "orphaned" || status === "failed" || status === "killed" || status === "lost" || status === "exited",
70
+ // A parked attempt keeps its assignment open: name and
71
+ // evidence stay reachable, and it is not a finished row.
72
+ terminal: !active && park === undefined,
73
+ unhealthy: status === "orphaned" || held,
74
+ attention: status === "orphaned" || status === "failed" || status === "killed" || status === "lost" || status === "exited" || held,
38
75
  startedAt: meta.startedAt,
39
76
  ...(meta.endedAt !== undefined ? { endedAt: meta.endedAt } : {}),
77
+ ...(park ? { details: { park } } : {}),
40
78
  };
41
79
  }),
42
80
  };