pi-better-subagents 0.28.1 → 0.29.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -12
- package/batch.mjs +1 -0
- package/config.ts +15 -2
- package/docs/usage.md +32 -20
- package/effective-settings.ts +51 -4
- package/index.ts +225 -44
- package/package.json +1 -1
- package/registry.ts +2 -1
- package/settings-page.ts +43 -6
- package/shared-navigator.ts +24 -3
- package/shared-operation-coordinator/src/validate.ts +3 -1
- package/timing.ts +172 -22
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
|
|
|
18
18
|
- Explicit tool allowlists for child sessions, and `skills` for prompt exposure: omit it to keep user-catalog discovery, pass `[]` for no skills, or pass absolute `SKILL.md` paths for exactly those. See [skill exposure](docs/usage.md#skill-exposure).
|
|
19
19
|
- Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
|
|
20
20
|
- Live background-work navigator for active runs.
|
|
21
|
-
- Harness-owned run timing: every run gets a no
|
|
21
|
+
- Harness-owned run timing: every run gets independent factual alerts for a tool call left open (5 min) and for no progress (10 min), while wall-clock soft deadlines and hard ceilings are opt-in so productive agents are not stopped solely for taking a long time. Configure per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `tool_wait_minutes`, `stuck_minutes`, globally in `config.json` / `PI_SUBAGENT_*_MINUTES`, or in `/subagents settings`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-tool-wait-stuck).
|
|
22
22
|
|
|
23
23
|
Every single or batch launch automatically joins one shared supervision watcher in the
|
|
24
24
|
foreground Pi process. The last active run's exit or stop tears it down; a later
|
|
@@ -80,8 +80,10 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
|
|
|
80
80
|
|
|
81
81
|
The user config sets `delegationMode` to `manual`, `adaptive` (default), or
|
|
82
82
|
`coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
|
|
83
|
-
for delegation mode, the concurrent-subagent cap (default 6),
|
|
84
|
-
|
|
83
|
+
for delegation mode, the concurrent-subagent cap (default 6), the tool-wait
|
|
84
|
+
alert (default 5 minutes), the no-progress alert (default 10 minutes), and the
|
|
85
|
+
default skill exposure. The two time values are edited independently; `0` turns
|
|
86
|
+
one alert off. Skill exposure cycles between Discover automatically and No skill
|
|
85
87
|
catalog. The Selected skills row opens the same searchable checkbox picker used
|
|
86
88
|
by `/agents`: it lists loaded skills by name and description, Space toggles one,
|
|
87
89
|
Enter applies, and typing filters without dropping checked items. Saved paths
|
|
@@ -89,25 +91,26 @@ missing from discovery stay visible as unavailable and survive apply. Zero
|
|
|
89
91
|
checked applies No skill catalog, not discovery. Manual Add skill path remains
|
|
90
92
|
available. The page names whether the current value comes from the saved config
|
|
91
93
|
or this session. The session choice controls the next launch before Ctrl+S, and
|
|
92
|
-
edits persist across reloads. Ctrl+S saves mode, cap, and skill
|
|
93
|
-
defaults, and Reset to defaults clears session overrides, including
|
|
94
|
-
list. Agents opens the same catalog as `/agents`; a definition that inherits
|
|
94
|
+
edits persist across reloads. Ctrl+S saves mode, cap, timing alerts, and skill
|
|
95
|
+
exposure as defaults, and Reset to defaults clears session overrides, including
|
|
96
|
+
the skill list. Agents opens the same catalog as `/agents`; a definition that inherits
|
|
95
97
|
skill exposure shows whether the live value comes from this session, saved
|
|
96
98
|
config, or discovery, and an invalid draft is marked invalid rather than shown
|
|
97
|
-
as discovery. `/subagents mode manual|adaptive|coordinator
|
|
98
|
-
`/subagents cap <number
|
|
99
|
+
as discovery. `/subagents mode manual|adaptive|coordinator`,
|
|
100
|
+
`/subagents cap <number>`, `/subagents tool-wait <minutes>`, and
|
|
101
|
+
`/subagents stuck <minutes>` are command equivalents; `/subagents save` persists
|
|
99
102
|
the current settings. Lowering the cap blocks new single and batch launches, including launches
|
|
100
103
|
still preparing, without stopping running work. Saved configuration changes are
|
|
101
104
|
picked up on subsequent reads; explicit session overrides still take precedence.
|
|
102
105
|
Before every model request, including continuations after tool calls,
|
|
103
106
|
the foreground receives one temporary settings block with the current mode, cap,
|
|
104
|
-
setting sources, revision, and running/reserved/available slots. The latest block
|
|
107
|
+
timing alerts, setting sources, revision, and running/reserved/available slots. The latest block
|
|
105
108
|
replaces older snapshots and delegation guidance; it is not saved as conversation
|
|
106
109
|
history. Changes reach the model at its next request, not during an in-flight
|
|
107
110
|
response, and are not broadcast to running children. The cap is a ceiling, not a
|
|
108
111
|
target number of agents. `subagent_settings` inspects the same effective state
|
|
109
|
-
without changing it. Its revision is a stable fingerprint of mode, cap,
|
|
110
|
-
sources; occupancy changes do not change the revision. Admission rechecks capacity
|
|
112
|
+
without changing it. Its revision is a stable fingerprint of mode, cap, timing
|
|
113
|
+
alerts, and sources; occupancy changes do not change the revision. Admission rechecks capacity
|
|
111
114
|
when spawning because the snapshot can become stale.
|
|
112
115
|
|
|
113
116
|
The navigator's `main` row retains its mode-only controls:
|
|
@@ -122,7 +125,8 @@ Saved defaults live in global `~/.pi/agent/settings.json` under
|
|
|
122
125
|
`piBetterHarness.subagents` (or under `PI_CODING_AGENT_DIR`) and survive package
|
|
123
126
|
reinstalls and upgrades. The old user config migrates on first use. Global values
|
|
124
127
|
override the package's `config.json`, which remains a compatibility fallback.
|
|
125
|
-
Save existing mode, cap, and skill choices with `/subagents save`
|
|
128
|
+
Save existing mode, cap, timing-alert, and skill choices with `/subagents save`
|
|
129
|
+
or Ctrl+S.
|
|
126
130
|
Discovery is saved as `defaultSkills: null`, which clears a previously saved
|
|
127
131
|
path list. Put other
|
|
128
132
|
custom config keys in `piBetterHarness.subagents` as well; edits made only inside
|
package/batch.mjs
CHANGED
|
@@ -105,6 +105,7 @@ export function mergeJobOptions(shared, job) {
|
|
|
105
105
|
deadline_minutes: job.deadline_minutes ?? shared?.deadline_minutes,
|
|
106
106
|
grace_minutes: job.grace_minutes ?? shared?.grace_minutes,
|
|
107
107
|
max_minutes: job.max_minutes ?? shared?.max_minutes,
|
|
108
|
+
tool_wait_minutes: job.tool_wait_minutes ?? shared?.tool_wait_minutes,
|
|
108
109
|
stuck_minutes: job.stuck_minutes ?? shared?.stuck_minutes,
|
|
109
110
|
// A per-job agent or role replaces the shared selector pair. Mixing
|
|
110
111
|
// shared.agent with job.role would invent an ambiguous run.
|
package/config.ts
CHANGED
|
@@ -17,7 +17,7 @@ import { SELF_SPEC } from "./extensions.ts";
|
|
|
17
17
|
import { installedPackage } from "./child-dependencies.mjs";
|
|
18
18
|
import { isDelegationMode, type DelegationMode } from "./delegation.ts";
|
|
19
19
|
import { normalizeSkillExposure } from "./skills.ts";
|
|
20
|
-
import type
|
|
20
|
+
import { validatedTimingMinutes, type TimingSettings } from "./timing.ts";
|
|
21
21
|
import { harnessSettingsPath, readHarnessSetting, updateHarnessSetting } from "./shared-harness-settings.ts";
|
|
22
22
|
|
|
23
23
|
export interface SubagentConfig extends TimingSettings {
|
|
@@ -197,12 +197,19 @@ export function writeSubagentSettings(
|
|
|
197
197
|
maxConcurrent: number;
|
|
198
198
|
/** Omit to preserve the saved value; `null` explicitly records discovery. */
|
|
199
199
|
defaultSkills?: string[] | null;
|
|
200
|
+
/** Omit to preserve the saved value. `0` disables that alert. */
|
|
201
|
+
toolWaitMinutes?: number;
|
|
202
|
+
/** Omit to preserve the saved value. `0` disables that alert. */
|
|
203
|
+
stuckMinutes?: number;
|
|
200
204
|
},
|
|
201
205
|
path = configPath(),
|
|
202
206
|
): void {
|
|
203
207
|
if (!isDelegationMode(settings.delegationMode)) throw new Error("Invalid delegation mode.");
|
|
204
208
|
if (!isConcurrencyCap(settings.maxConcurrent)) throw new Error("Concurrent subagents must be a positive whole number.");
|
|
205
|
-
const next: {
|
|
209
|
+
const next: {
|
|
210
|
+
delegationMode: DelegationMode; maxConcurrent: number; defaultSkills?: string[] | null;
|
|
211
|
+
toolWaitMinutes?: number; stuckMinutes?: number;
|
|
212
|
+
} = {
|
|
206
213
|
delegationMode: settings.delegationMode,
|
|
207
214
|
maxConcurrent: settings.maxConcurrent,
|
|
208
215
|
};
|
|
@@ -218,6 +225,12 @@ export function writeSubagentSettings(
|
|
|
218
225
|
next.defaultSkills = skills;
|
|
219
226
|
}
|
|
220
227
|
}
|
|
228
|
+
if (settings.toolWaitMinutes !== undefined) {
|
|
229
|
+
next.toolWaitMinutes = validatedTimingMinutes(settings.toolWaitMinutes, "toolWaitMinutes");
|
|
230
|
+
}
|
|
231
|
+
if (settings.stuckMinutes !== undefined) {
|
|
232
|
+
next.stuckMinutes = validatedTimingMinutes(settings.stuckMinutes, "stuckMinutes");
|
|
233
|
+
}
|
|
221
234
|
writeConfigSettings(next, path);
|
|
222
235
|
}
|
|
223
236
|
|
package/docs/usage.md
CHANGED
|
@@ -19,9 +19,11 @@ Set `delegationMode` in the user config described under
|
|
|
19
19
|
`coordinator` (default `adaptive`). This controls foreground delegation guidance,
|
|
20
20
|
not child permissions or catalog definitions. `/subagents settings` (or simply
|
|
21
21
|
`/subagents`) opens the terminal settings page with mode, concurrent-subagent
|
|
22
|
-
cap, and default skill-exposure controls, an
|
|
23
|
-
Reset to defaults. The
|
|
24
|
-
|
|
22
|
+
cap, tool-wait alert, no-progress alert, and default skill-exposure controls, an
|
|
23
|
+
Agents shortcut to `/agents`, and Reset to defaults. The two time values are
|
|
24
|
+
edited independently in minutes; `0` turns one alert off. The page uses the same
|
|
25
|
+
selected-row and active-cell styling as `/sandbox`, with one editable value
|
|
26
|
+
column. Skill exposure cycles between
|
|
25
27
|
Discover automatically and No skill catalog. The Selected skills row opens the
|
|
26
28
|
shared searchable checkbox picker, which lists loaded skills by name and
|
|
27
29
|
description, uses Space to toggle, Enter to apply, and Esc to cancel. Typing
|
|
@@ -33,15 +35,18 @@ absolute and exist. Invalid input stays in the editor with an explanation rather
|
|
|
33
35
|
than being dropped.
|
|
34
36
|
Edits automatically persist for this session, including across reloads; Escape
|
|
35
37
|
closes the page without undoing them.
|
|
36
|
-
Enter edits the cap as a positive whole number
|
|
37
|
-
Ctrl+S saves mode, cap,
|
|
38
|
-
|
|
38
|
+
Enter edits the cap as a positive whole number or a timing value in minutes;
|
|
39
|
+
Escape cancels an unfinished edit. Ctrl+S saves mode, cap, timing alerts, and
|
|
40
|
+
skill exposure as defaults. Reset to defaults restores them from the saved
|
|
41
|
+
config. Sandbox permissions remain in `/sandbox`.
|
|
39
42
|
|
|
40
43
|
Command equivalents also work outside the terminal UI:
|
|
41
44
|
|
|
42
45
|
```text
|
|
43
46
|
/subagents mode manual|adaptive|coordinator
|
|
44
47
|
/subagents cap 6
|
|
48
|
+
/subagents tool-wait 5
|
|
49
|
+
/subagents stuck 10
|
|
45
50
|
/subagents save
|
|
46
51
|
/subagents reset
|
|
47
52
|
```
|
|
@@ -51,8 +56,9 @@ below the running count leaves existing work untouched and blocks new admissions
|
|
|
51
56
|
until capacity becomes available. Slots already reserved by an in-flight launch
|
|
52
57
|
remain admitted. Settings apply to this parent Pi process, not
|
|
53
58
|
all Pi sessions on the machine. Saving preserves unrelated config keys and
|
|
54
|
-
clears the mode, cap, and skill session overrides. The command form
|
|
55
|
-
is available. Reset restores saved defaults
|
|
59
|
+
clears the mode, cap, timing-alert, and skill session overrides. The command form
|
|
60
|
+
asks for confirmation when a UI is available. Reset restores saved defaults
|
|
61
|
+
without changing config.
|
|
56
62
|
|
|
57
63
|
`/reload` retains session overrides; new sessions use config, while resuming or
|
|
58
64
|
navigating a branch restores its settings. On the navigator `main` sheet, `m`
|
|
@@ -106,9 +112,9 @@ thresholds continue to take precedence for subagent health.
|
|
|
106
112
|
|
|
107
113
|
| Tool | Blocks? | What it does |
|
|
108
114
|
|------|---------|--------------|
|
|
109
|
-
| `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `skills` ([skill exposure](#skill-exposure)), `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
|
|
115
|
+
| `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `skills` ([skill exposure](#skill-exposure)), `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-tool-wait-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `tool_wait_minutes`, `stuck_minutes`. |
|
|
110
116
|
| `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`; optional per-job `session_id` or `session_name` continues a saved conversation), `onCapacity` (`reject` or `launch-available`). |
|
|
111
|
-
| `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, per-setting `sources` (`session` or `
|
|
117
|
+
| `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, `toolWaitMinutes`, `stuckMinutes`, per-setting `sources`/`timingSources` (`environment`, `session`, `config`, or `default`), a stable settings `revision`, `runningCount`, `pendingCount`, `occupiedSlots`, and `availableSlots`. Timing values already account for the same environment precedence a launch uses. The limit is a ceiling, not a target; spawn admission rechecks live capacity. |
|
|
112
118
|
| `subagent_list` | never | Compact list for the current folder and descendants across foreground sessions (default 10 rows / 1 KiB page). Each row includes `session_id`. Params: `all` (machine-global search), `limit` (default 10, max 100), `cursor`, `max_bytes` (max 4 KiB), `status` (`running`, `completed`, `failed`, `killed`, `exited`, durable `orphaned`, `lost`). Incident counts are compact; no spend/tool histories. Abandoned launch records are reported separately and are never counted as runs. |
|
|
113
119
|
| `subagent_output` | never | Bounded current-session excerpt (default 1 KiB / 10 lines). Params: `id`, `lines` (`tail_lines` is a deprecated alias), `cursor` (a returned `nextCursor`, `statusCursor`, or `incidentCursor`), `max_bytes` (max 4 KiB; raw 16 KiB default, 64 KiB max), `mode` (`raw` pages retained log bytes), `tail` (raw mode: start from the newest retained byte and page backwards; the final step returns an append-ready cursor), `include` (`["cost"]`, `["tools"]`, or both: opt-in spend and tool-count lines), `all` (foreign-session id). Missing/unreadable logs are gaps, not empty healthy output. |
|
|
114
120
|
| `subagent_result` | never | Finished-run answer for the current session (2048-byte page). Params: `id`, `cursor` (a returned `nextCursor` continues the answer; `statusCursor` / `incidentCursor` also accepted), `max_bytes` (maximum 8192 bytes), `lines` (optional line cap per answer page), `mode` (`raw`), `tail` (raw mode: newest bytes first), `include` (`["cost"]`, `["tools"]`, or both), `all` (foreign-session id). Failures and exceptional lifecycle facts come before progress; no tool-name histories. TUI folding is display-only. |
|
|
@@ -272,21 +278,22 @@ completion callbacks with `subagent_result`; do not poll or keep a script open
|
|
|
272
278
|
waiting for completion. Callbacks and capacity/catalog guarantees remain owned
|
|
273
279
|
by the existing harness runtime.
|
|
274
280
|
|
|
275
|
-
## Run timing (deadline, ceiling, stuck)
|
|
281
|
+
## Run timing (deadline, ceiling, tool wait, stuck)
|
|
276
282
|
|
|
277
283
|
Timeout control belongs to the harness, not to the prompt or the skill that
|
|
278
284
|
launched the run. A time limit written into a prompt is enforced by nothing, and
|
|
279
285
|
a parent that only notices late tends to kill a child that was still making
|
|
280
|
-
progress. Every run gets stall detection by default.
|
|
281
|
-
opt-in because total runtime does not distinguish a slow
|
|
282
|
-
one.
|
|
286
|
+
progress. Every run gets a tool-wait alert and stall detection by default.
|
|
287
|
+
Elapsed-time limits are opt-in because total runtime does not distinguish a slow
|
|
288
|
+
agent from a stalled one.
|
|
283
289
|
|
|
284
290
|
| Control | Default | What happens |
|
|
285
291
|
|---------|---------|--------------|
|
|
286
292
|
| Soft deadline (`deadline_minutes`) | Off | When configured, the child gets one steering message (delivered through Pi's steer queue after its current tool call finishes): stop starting new work, commit or save what is done, and report what is complete, what is not, and where the work is. The parent gets one wake saying so. |
|
|
287
293
|
| Grace (`grace_minutes`) | 5 | Grace starts when the steering message actually reaches the child, which is after its current tool call. While the message is still waiting behind a running tool call, the deadline stop is held, so a test run that began just before the deadline is not killed mid-run. If the child has not finished by the end of grace, the harness stops it; the ordinary completion callback reports `killed; stopped: deadline`. A child that completes inside grace is not stopped; its surfaces say `deadline: finished in grace`. |
|
|
288
294
|
| Hard ceiling (`max_minutes`) | Off | When configured, the run is stopped at once, without grace or a steer, and reported as `stopped: ceiling`. The ceiling bounds the run, including a tool call that never ends and an orphaned run (child gone, its process group still alive). |
|
|
289
|
-
|
|
|
295
|
+
| Tool-wait window (`tool_wait_minutes`) | 5 | One tool call that stays open this long sends one factual parent wake for that call, including when it is a normal long test. Parallel calls alert independently. The alert never stops, cancels, or restarts the run, and a later call can alert on its own. |
|
|
296
|
+
| Stuck window (`stuck_minutes`) | 10 | No progress (see below) for this long wakes the parent once (`stuck`). It never stops the run. After new progress, a later stuck spell wakes again. Time inside a running tool call is excluded, so tool waiting and no-progress are reported separately. |
|
|
290
297
|
|
|
291
298
|
`0` turns a control off. `null` or an omitted value means "inherit": on
|
|
292
299
|
`subagent_spawn` that is the configured default; on a `subagent_spawn_batch` job
|
|
@@ -301,13 +308,14 @@ may be fractional. A job's own number (including `0`) wins over `shared`.
|
|
|
301
308
|
hung tool call is never delivered, the deadline stop stays held, and the run
|
|
302
309
|
is never stopped by that deadline. Opt into a ceiling to bound the whole run.
|
|
303
310
|
- The parent reads at most the last 32 MiB of a child log after `/reload`. It
|
|
304
|
-
also records the
|
|
311
|
+
also records the calls it last saw open in the run's metadata on each
|
|
305
312
|
supervision tick, so a reload normally keeps the hold and the not-stuck
|
|
306
313
|
accounting even when the call's start is outside that window. The record is
|
|
307
314
|
written by the tick, so a call that started less than one tick (15 s) before
|
|
308
315
|
the reload is not covered; and a record whose call ended while the window was
|
|
309
316
|
lost keeps the hold, and keeps the run from being reported stuck, until the
|
|
310
|
-
next observed
|
|
317
|
+
next observed turn proves that batch ended (a newer retained message followed
|
|
318
|
+
by its tool call start). Opt into a ceiling when the run needs a hard
|
|
311
319
|
wall-clock bound.
|
|
312
320
|
- The child confirms delivery by matching the steer's exact text in its
|
|
313
321
|
conversation. If another extension rewrites user input (an input-transform
|
|
@@ -329,7 +337,9 @@ long ago counts again. Time the child spends waiting on a running tool call does
|
|
|
329
337
|
stuck window, so a child in the middle of a 20-minute test run is waiting, not
|
|
330
338
|
stuck — including after `/reload`: the call the parent saw open is stored in the
|
|
331
339
|
run's metadata, so a bounded log read that no longer contains its start does not
|
|
332
|
-
turn it into "no progress".
|
|
340
|
+
turn it into "no progress". That same open-call evidence drives the independent
|
|
341
|
+
tool-wait alert: each call alerts once after its configured window, and the
|
|
342
|
+
durable marker survives `/reload`. A hanging command can be bounded by the sandbox command time limit; the run
|
|
333
343
|
ceiling separately bounds the whole run.
|
|
334
344
|
The other stuck signal is the existing escalation: the same operation failing
|
|
335
345
|
three times wakes the parent once as an `Action required` incident
|
|
@@ -349,11 +359,13 @@ example it crashed or a user stopped it), `stopped: ceiling`, or `stuck`. The sp
|
|
|
349
359
|
| Soft deadline | `PI_SUBAGENT_DEADLINE_MINUTES` | `deadlineMinutes` |
|
|
350
360
|
| Grace | `PI_SUBAGENT_GRACE_MINUTES` | `graceMinutes` |
|
|
351
361
|
| Hard ceiling | `PI_SUBAGENT_MAX_MINUTES` | `maxMinutes` |
|
|
362
|
+
| Tool-wait window | `PI_SUBAGENT_TOOL_WAIT_MINUTES` | `toolWaitMinutes` |
|
|
352
363
|
| Stuck window | `PI_SUBAGENT_STUCK_MINUTES` | `stuckMinutes` |
|
|
353
364
|
|
|
354
365
|
**Durability and delivery.** The policy and its one-shot markers (steer
|
|
355
|
-
requested, deadline wake, stuck wake, stop reason)
|
|
356
|
-
metadata at launch, so `/reload` keeps the deadline and
|
|
366
|
+
requested, deadline wake, tool-wait marker per call, stuck wake, stop reason)
|
|
367
|
+
are stored in the run's metadata at launch, so `/reload` keeps the deadline and
|
|
368
|
+
never repeats a wake.
|
|
357
369
|
The parent checks timing on its 15-second supervision tick. The steer travels
|
|
358
370
|
through a request file in the run directory, read by a small harness extension
|
|
359
371
|
loaded into every child (it registers no tools and runs no commands). When the
|
package/effective-settings.ts
CHANGED
|
@@ -1,15 +1,35 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
2
|
import { delegationPrompt, type DelegationMode } from "./delegation.ts";
|
|
3
|
+
import { DEFAULT_TIMING_MINUTES } from "./timing.ts";
|
|
3
4
|
|
|
4
5
|
import { EXECUTION_POLICY_TEXT, publishExecutionPolicy, supportsPromptSections } from "./shared-execution-policy.ts";
|
|
5
6
|
|
|
6
7
|
export const SUBAGENT_SETTINGS_CONTEXT = "pi-better-subagents-settings";
|
|
7
8
|
|
|
9
|
+
export type TimingSettingSource = "environment" | "session" | "config" | "default";
|
|
10
|
+
|
|
11
|
+
export interface EffectiveTimingSettings {
|
|
12
|
+
toolWaitMinutes: number;
|
|
13
|
+
stuckMinutes: number;
|
|
14
|
+
sources: {
|
|
15
|
+
toolWaitMinutes: TimingSettingSource;
|
|
16
|
+
stuckMinutes: TimingSettingSource;
|
|
17
|
+
};
|
|
18
|
+
error?: string;
|
|
19
|
+
}
|
|
20
|
+
|
|
8
21
|
export interface EffectiveSubagentSettings {
|
|
9
22
|
revision: string;
|
|
10
23
|
delegationMode: DelegationMode;
|
|
11
24
|
maxConcurrent: number;
|
|
12
25
|
sources: { delegationMode: "session" | "config"; maxConcurrent: "session" | "config" };
|
|
26
|
+
toolWaitMinutes: number;
|
|
27
|
+
stuckMinutes: number;
|
|
28
|
+
timingSources: {
|
|
29
|
+
toolWaitMinutes: TimingSettingSource;
|
|
30
|
+
stuckMinutes: TimingSettingSource;
|
|
31
|
+
};
|
|
32
|
+
timingError?: string;
|
|
13
33
|
runningCount: number;
|
|
14
34
|
pendingCount: number;
|
|
15
35
|
occupiedSlots: number;
|
|
@@ -17,18 +37,39 @@ export interface EffectiveSubagentSettings {
|
|
|
17
37
|
}
|
|
18
38
|
|
|
19
39
|
export function effectiveSubagentSettings(
|
|
20
|
-
settings: Pick<EffectiveSubagentSettings, "delegationMode" | "maxConcurrent" | "sources"
|
|
40
|
+
settings: Pick<EffectiveSubagentSettings, "delegationMode" | "maxConcurrent" | "sources"> & {
|
|
41
|
+
timing?: EffectiveTimingSettings;
|
|
42
|
+
},
|
|
21
43
|
runningCount: number,
|
|
22
44
|
pendingCount: number,
|
|
23
45
|
): EffectiveSubagentSettings {
|
|
46
|
+
const timing = settings.timing ?? {
|
|
47
|
+
toolWaitMinutes: DEFAULT_TIMING_MINUTES.toolWait,
|
|
48
|
+
stuckMinutes: DEFAULT_TIMING_MINUTES.stuck,
|
|
49
|
+
sources: { toolWaitMinutes: "default" as const, stuckMinutes: "default" as const },
|
|
50
|
+
};
|
|
24
51
|
const revision = createHash("sha256").update(JSON.stringify([
|
|
25
52
|
settings.delegationMode, settings.maxConcurrent, settings.sources.delegationMode, settings.sources.maxConcurrent,
|
|
53
|
+
timing.toolWaitMinutes, timing.stuckMinutes, timing.sources.toolWaitMinutes, timing.sources.stuckMinutes,
|
|
26
54
|
])).digest("hex").slice(0, 12);
|
|
27
55
|
const occupiedSlots = runningCount + pendingCount;
|
|
28
|
-
return {
|
|
56
|
+
return {
|
|
57
|
+
revision,
|
|
58
|
+
delegationMode: settings.delegationMode,
|
|
59
|
+
maxConcurrent: settings.maxConcurrent,
|
|
60
|
+
sources: settings.sources,
|
|
61
|
+
toolWaitMinutes: timing.toolWaitMinutes,
|
|
62
|
+
stuckMinutes: timing.stuckMinutes,
|
|
63
|
+
timingSources: timing.sources,
|
|
64
|
+
...(timing.error ? { timingError: timing.error } : {}),
|
|
65
|
+
runningCount, pendingCount, occupiedSlots,
|
|
29
66
|
availableSlots: Math.max(0, settings.maxConcurrent - occupiedSlots) };
|
|
30
67
|
}
|
|
31
68
|
|
|
69
|
+
function alertMinutes(value: number): string {
|
|
70
|
+
return value === 0 ? "off" : `${value}m`;
|
|
71
|
+
}
|
|
72
|
+
|
|
32
73
|
export function formatSubagentSettings(settings: EffectiveSubagentSettings): string {
|
|
33
74
|
const manual = settings.delegationMode === "manual";
|
|
34
75
|
const capacity = manual
|
|
@@ -43,6 +84,9 @@ export function formatSubagentSettings(settings: EffectiveSubagentSettings): str
|
|
|
43
84
|
`Subagent settings: revision ${settings.revision}`,
|
|
44
85
|
`Delegation: ${settings.delegationMode} (${settings.sources.delegationMode})`,
|
|
45
86
|
`Concurrency limit: ${settings.maxConcurrent} (${settings.sources.maxConcurrent})`,
|
|
87
|
+
`Timing alerts: tool wait ${alertMinutes(settings.toolWaitMinutes)} (${settings.timingSources.toolWaitMinutes}); ` +
|
|
88
|
+
`no progress ${alertMinutes(settings.stuckMinutes)} (${settings.timingSources.stuckMinutes}).`,
|
|
89
|
+
...(settings.timingError ? [`Timing alert settings error: ${settings.timingError}`] : []),
|
|
46
90
|
// Mode first: the policy governs the settings that follow it.
|
|
47
91
|
delegationPrompt(settings.delegationMode),
|
|
48
92
|
capacity + " Spawn admission rechecks capacity; lower the limit without stopping existing runs.",
|
|
@@ -76,7 +120,7 @@ export interface PromptSectionTarget {
|
|
|
76
120
|
* render in publication order, so Background Tasks and Goal publish after this one;
|
|
77
121
|
* naming its own section keeps the sentence true whatever the load order.
|
|
78
122
|
*/
|
|
79
|
-
const SUBAGENT_DELEGATION_NOTE = "Treat the Subagent settings block in this section as the authoritative delegation mode and
|
|
123
|
+
const SUBAGENT_DELEGATION_NOTE = "Treat the Subagent settings block in this section as the authoritative delegation mode, cap, and timing-alert settings. 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
124
|
|
|
81
125
|
export function publishSubagentSettings<T extends object>(options: T, settings: EffectiveSubagentSettings): T {
|
|
82
126
|
// Note first, block last inside the section: the note introduces the block it
|
|
@@ -92,12 +136,15 @@ export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSet
|
|
|
92
136
|
return {
|
|
93
137
|
name: "subagent_settings",
|
|
94
138
|
label: "Subagent Settings",
|
|
95
|
-
description: "Inspect effective subagent delegation mode, concurrency limit, setting sources, revision, and running/reserved/available slots. Read-only; does not change settings or launch work. The limit is a ceiling, not a target.",
|
|
139
|
+
description: "Inspect effective subagent delegation mode, concurrency limit, tool-wait and no-progress alert times, setting sources, revision, and running/reserved/available slots. Read-only; does not change settings or launch work. The limit is a ceiling, not a target.",
|
|
96
140
|
parameters: Type.Object({}),
|
|
97
141
|
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
|
|
98
142
|
outputSchema: Type.Object({
|
|
99
143
|
revision: Type.String(), delegationMode: Type.String(), maxConcurrent: Type.Number({ minimum: 1, multipleOf: 1 }),
|
|
100
144
|
sources: Type.Object({ delegationMode: Type.String(), maxConcurrent: Type.String() }),
|
|
145
|
+
toolWaitMinutes: Type.Number({ minimum: 0 }), stuckMinutes: Type.Number({ minimum: 0 }),
|
|
146
|
+
timingSources: Type.Object({ toolWaitMinutes: Type.String(), stuckMinutes: Type.String() }),
|
|
147
|
+
timingError: Type.Optional(Type.String()),
|
|
101
148
|
runningCount: Type.Number({ minimum: 0, multipleOf: 1 }), pendingCount: Type.Number({ minimum: 0, multipleOf: 1 }),
|
|
102
149
|
occupiedSlots: Type.Number({ minimum: 0, multipleOf: 1 }), availableSlots: Type.Number({ minimum: 0, multipleOf: 1 }),
|
|
103
150
|
}),
|