pi-better-subagents 0.32.7 → 0.34.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.
Files changed (67) hide show
  1. package/README.md +13 -0
  2. package/agent-catalog.mjs +24 -0
  3. package/agent-commands.ts +71 -4
  4. package/agent-inspection.ts +2 -1
  5. package/agents-catalog-tool.ts +8 -1
  6. package/assignment-outcomes.ts +14 -3
  7. package/assignment-projection.mjs +12 -4
  8. package/assignment-report.ts +92 -0
  9. package/catalog-host-admission.ts +69 -0
  10. package/catalog-overlay.ts +10 -0
  11. package/catalog-runtime.ts +10 -2
  12. package/catalog-store.ts +23 -0
  13. package/catalog-ui.ts +26 -10
  14. package/child-operations.ts +2 -0
  15. package/child-ownership.ts +1 -1
  16. package/docs/agent-catalog-operations.md +38 -0
  17. package/health-observation.ts +9 -4
  18. package/index.ts +154 -84
  19. package/launch-abort.ts +21 -0
  20. package/list.mjs +1 -1
  21. package/navigator.mjs +2 -1
  22. package/operation-bridge-types.ts +18 -1
  23. package/output-payload.ts +2 -0
  24. package/package.json +4 -2
  25. package/parse.ts +7 -6
  26. package/registry.ts +4 -2
  27. package/runtime-client/artifacts/darwin-arm64.gz +0 -0
  28. package/runtime-client/artifacts/darwin-arm64.json +1 -0
  29. package/runtime-client/artifacts/darwin-x64.gz +0 -0
  30. package/runtime-client/artifacts/darwin-x64.json +1 -0
  31. package/runtime-client/artifacts/linux-arm64.gz +0 -0
  32. package/runtime-client/artifacts/linux-arm64.json +1 -0
  33. package/runtime-client/artifacts/linux-x64.gz +0 -0
  34. package/runtime-client/artifacts/linux-x64.json +1 -0
  35. package/runtime-client/scripts/private-runtime/format.mjs +90 -0
  36. package/runtime-client/src/daemon-owner.mjs +218 -0
  37. package/runtime-client/src/runtime/client.mjs +130 -0
  38. package/runtime-client/src/runtime/root.mjs +41 -0
  39. package/runtime-client/src/runtime/socket.mjs +9 -0
  40. package/runtime-client/src/runtime/status-cli.mjs +14 -0
  41. package/runtime-client/src/runtime/work-client.mjs +102 -0
  42. package/runtime-client/src/startup/artifact.mjs +76 -0
  43. package/runtime-client/src/startup/install.mjs +184 -0
  44. package/runtime-client/src/startup/managed-types.mjs +1 -0
  45. package/runtime-client/src/startup/runtime.mjs +120 -0
  46. package/session-store.ts +85 -30
  47. package/shared-catalog.ts +69 -0
  48. package/shared-harness-settings.ts +4 -2
  49. package/shared-log-utils.ts +18 -7
  50. package/shared-navigator.ts +16 -4
  51. package/shared-operation-coordinator/assignment-observation.mjs +80 -3
  52. package/shared-operation-coordinator/index.ts +2 -0
  53. package/shared-operation-coordinator/src/discovery.ts +9 -0
  54. package/shared-operation-coordinator/src/errors.ts +2 -0
  55. package/shared-operation-coordinator/src/operations.ts +6 -4
  56. package/shared-operation-coordinator/src/result-supervision.ts +128 -0
  57. package/shared-operation-coordinator/src/schema.ts +39 -1
  58. package/shared-operation-coordinator/src/store.ts +55 -0
  59. package/shared-operation-coordinator/src/task-cancellation.ts +224 -0
  60. package/shared-operation-coordinator/src/types.ts +6 -0
  61. package/shared-work-client.d.mts +12 -0
  62. package/shared-work-client.mjs +102 -0
  63. package/skill-picker.ts +6 -2
  64. package/tools.ts +39 -2
  65. package/work-observation.ts +177 -0
  66. package/worker-operations-host.ts +3 -0
  67. package/worker-waits.ts +50 -13
package/catalog-store.ts CHANGED
@@ -37,6 +37,7 @@ import {
37
37
  parseDefinition,
38
38
  serializeDefinition,
39
39
  type CatalogDefinition,
40
+ type AgentDefinition,
40
41
  type CatalogKind,
41
42
  type CatalogScope,
42
43
  type Diagnostic,
@@ -151,6 +152,14 @@ class FrozenMap<K, V> extends Map<K, V> {
151
152
  }
152
153
  }
153
154
 
155
+ /** Rebuild the same immutable domain value after a JSON socket round trip. */
156
+ export function catalogSnapshotFromWire(wire: Omit<CatalogSnapshot, "roles" | "agents"> & {
157
+ roles: Iterable<readonly [string, CatalogEntry]>;
158
+ agents: Iterable<readonly [string, CatalogEntry]>;
159
+ }): CatalogSnapshot {
160
+ return deepFreeze({ ...wire, roles: FrozenMap.fill(wire.roles), agents: FrozenMap.fill(wire.agents) });
161
+ }
162
+
154
163
  export function defaultUserRoot(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
155
164
  const configured = env.PI_CODING_AGENT_DIR?.trim();
156
165
  return configured ? configured : join(home, ".pi", "agent");
@@ -178,6 +187,20 @@ export function contentDigest(raw: string): string {
178
187
  return createHash("sha256").update(raw).digest("hex");
179
188
  }
180
189
 
190
+ /** Import matching needs every source in the destination scope, including shadowed IDs. */
191
+ export function listScopedAgents(input: LoadCatalogInput, scope: "user" | "project"): { agents: { path: string; definition: AgentDefinition }[]; diagnostics: Diagnostic[] } {
192
+ const diagnostics: Diagnostic[] = [];
193
+ if (scope === "project" && !input.projectTrusted) throw new Error("Project catalog access requires a trusted host.");
194
+ const config = input.projectConfigDirName ?? DEFAULT_PROJECT_CONFIG_DIR_NAME;
195
+ if (!isSafeConfigDirName(config)) throw new Error("Unsafe project config directory");
196
+ const directory = scope === "project" ? projectCatalogPaths(input.cwd, config).agents : userCatalogPaths(input.userRoot).agents;
197
+ const occurrences = new Map<string, Occurrence[]>();
198
+ collectDirectory(directory, scope, "agent", occurrences, diagnostics);
199
+ const agents = [...occurrences.values()].flat().flatMap(item => item.parse.definition?.kind === "agent"
200
+ ? [{ path: item.path, definition: item.parse.definition }] : []);
201
+ return { agents, diagnostics };
202
+ }
203
+
181
204
  /** Read every source again. Identical bytes produce the same digest and a new object. */
182
205
  export function loadCatalog(input: LoadCatalogInput): CatalogSnapshot {
183
206
  const loadedAt = new Date().toISOString();
package/catalog-ui.ts CHANGED
@@ -6,8 +6,17 @@ import type { AgentSessionOverrides, AgentSettingKey } from "./agent-session-set
6
6
  import { createSkillPicker, type DiscoveredSkill } from "./skill-picker.ts";
7
7
 
8
8
  type Theme = { fg(color: string, text: string): string; bg?(color: string, text: string): string; bold?(text: string): string; inverse?(text: string): string };
9
+ type EditResult = { ok: boolean; message: string };
10
+ type PendingEdit = EditResult | Promise<EditResult>;
11
+
12
+ function settleEdit(result: PendingEdit, done: (result: EditResult) => void, failed: (error: unknown) => void) {
13
+ if (result instanceof Promise) void result.then(done, failed);
14
+ else done(result);
15
+ }
9
16
 
10
17
  export interface CatalogEditor {
18
+ beginEdit?(id: string): void;
19
+ onChange?(changed: () => void): void;
11
20
  get(): OperationList;
12
21
  /** Available foreground models, used only when the session scope is empty. */
13
22
  models(): readonly string[];
@@ -16,12 +25,12 @@ export interface CatalogEditor {
16
25
  settings(): AgentSessionOverrides;
17
26
  change(id: string, key: AgentSettingKey, value: string | null): void;
18
27
  /** Skill exposure is edited through the definition save path, not session settings. */
19
- changeSkills?(entry: OperationView, edit: SkillExposureEdit): { ok: boolean; message: string };
28
+ changeSkills?(entry: OperationView, edit: SkillExposureEdit): PendingEdit;
20
29
  /** Loaded Pi skill metadata for the checkbox picker. */
21
30
  discoverSkills?(): readonly DiscoveredSkill[];
22
- save(id: string): { ok: boolean; message: string };
23
- resetToBundled?(entry: OperationView): { ok: boolean; message: string };
24
- resetDefinition?(entry: OperationView): { ok: boolean; message: string };
31
+ save(id: string): PendingEdit;
32
+ resetToBundled?(entry: OperationView): PendingEdit;
33
+ resetDefinition?(entry: OperationView): PendingEdit;
25
34
  }
26
35
 
27
36
  function stateLabel(entry: OperationView): string {
@@ -208,12 +217,13 @@ export function createCatalogComponent(
208
217
  const highlight = (text: string, width: number) => theme.bg?.("selectedBg", theme.bold?.(cell(text, width)) ?? cell(text, width)) ?? theme.fg("accent", text);
209
218
  function report(text: string, failed = false) { message = text; error = failed; requestRender(); }
210
219
  function refresh() { if (editor) catalog = editor.get(); }
220
+ editor?.onChange?.(() => { refresh(); requestRender(); });
211
221
  function save() {
212
222
  if (!editor || !selected()) return;
213
223
  try {
214
- const result = editor.save(selected()!.id);
215
- refresh();
216
- report(result.message, !result.ok);
224
+ settleEdit(editor.save(selected()!.id), result => {
225
+ refresh(); report(result.message, !result.ok);
226
+ }, cause => report(String(cause), true));
217
227
  } catch (cause) { report(String(cause instanceof Error ? cause.message : cause), true); }
218
228
  }
219
229
  function canReset(entry: OperationView | undefined): boolean {
@@ -227,13 +237,14 @@ export function createCatalogComponent(
227
237
  function reset(entry = selected(), definition = false) {
228
238
  if (!entry || !(definition ? canResetDefinition(entry) : canReset(entry))) return;
229
239
  try {
230
- const result = definition ? editor!.resetDefinition!(entry) : editor!.resetToBundled!(entry);
240
+ settleEdit(definition ? editor!.resetDefinition!(entry) : editor!.resetToBundled!(entry), result => {
231
241
  refresh();
232
242
  settingRow = 0;
233
243
  scroll = 0;
234
244
  resetPointerRows = [];
235
245
  resetPointerEntry = undefined;
236
246
  report(result.message, !result.ok);
247
+ }, cause => report(String(cause), true));
237
248
  } catch (cause) { report(cause instanceof Error ? cause.message : String(cause), true); }
238
249
  }
239
250
  /** Selectable setting rows in display order; Reset is a row, not a save action. */
@@ -268,9 +279,10 @@ export function createCatalogComponent(
268
279
  apply(paths) {
269
280
  if (!editor?.changeSkills) return { ok: false, message: "Skill editing is unavailable." };
270
281
  try {
271
- const result = editor.changeSkills(current, paths.length === 0
282
+ const pending = editor.changeSkills(current, paths.length === 0
272
283
  ? { mode: "none" }
273
284
  : { mode: "explicit", paths: [...paths] });
285
+ const finish = (result: EditResult) => {
274
286
  if (result.ok) {
275
287
  refresh();
276
288
  report(paths.length === 0
@@ -278,6 +290,8 @@ export function createCatalogComponent(
278
290
  : result.message, false);
279
291
  }
280
292
  return { ok: result.ok, message: result.message };
293
+ };
294
+ return pending instanceof Promise ? pending.then(finish) : finish(pending);
281
295
  } catch (cause) {
282
296
  return { ok: false, message: cause instanceof Error ? cause.message : String(cause) };
283
297
  }
@@ -308,10 +322,11 @@ export function createCatalogComponent(
308
322
  picker.onSelect = (item) => {
309
323
  if (item.value === "select") { openSkillPaths(current); return; }
310
324
  try {
311
- const result = editor!.changeSkills!(current, item.value === "none" ? { mode: "none" } : { mode: "inherit" });
325
+ settleEdit(editor!.changeSkills!(current, item.value === "none" ? { mode: "none" } : { mode: "inherit" }), result => {
312
326
  refresh();
313
327
  picker = undefined;
314
328
  report(result.message, !result.ok);
329
+ }, cause => report(String(cause), true));
315
330
  } catch (cause) { report(cause instanceof Error ? cause.message : String(cause), true); }
316
331
  };
317
332
  const selectedIndex = skillChoiceIndex(current);
@@ -320,6 +335,7 @@ export function createCatalogComponent(
320
335
  function edit() {
321
336
  const current = selected();
322
337
  if (!current || !editor) return;
338
+ editor.beginEdit?.(current.id);
323
339
  const keys = settingKeys(current);
324
340
  const key = keys[settingRow];
325
341
  if (!key) { settingRow = 0; return; }
@@ -509,6 +509,7 @@ export function verifyDescriptor(value: unknown, config: Pick<ChildOperationBrid
509
509
  function validateCapabilities(value: unknown): OperationBridgeCapabilities {
510
510
  if (!value || typeof value !== "object") throw new OperationBridgeError("invalid-request", "parent handshake has no capabilities");
511
511
  const record = value as Record<string, unknown>;
512
+ if (record.reportAssignment !== undefined && typeof record.reportAssignment !== "boolean") throw new OperationBridgeError("invalid-request", "parent reporting capability is invalid");
512
513
  const background = record.background;
513
514
  if (!background || typeof background !== "object") throw new OperationBridgeError("invalid-request", "parent handshake has no background capabilities");
514
515
  const bg = background as Record<string, unknown>;
@@ -519,6 +520,7 @@ function validateCapabilities(value: unknown): OperationBridgeCapabilities {
519
520
  if (typeof record[key] !== "boolean") throw new OperationBridgeError("invalid-request", `parent capability ${key} is invalid`);
520
521
  }
521
522
  return Object.freeze({
523
+ ...(typeof record.reportAssignment === "boolean" ? { reportAssignment: record.reportAssignment } : {}),
522
524
  background: Object.freeze({
523
525
  spawn: bg.spawn as boolean,
524
526
  watch: bg.watch as boolean,
@@ -4,7 +4,7 @@ import { STEER_FILE_ENV } from "./child-steer.ts";
4
4
  import { supportsPromptSections } from "./shared-execution-policy.ts";
5
5
  import { restrictContextFilesToWorktree } from "./shared-worktree-context.ts";
6
6
 
7
- 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 = "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. When report_assignment_result is available, call it before your final answer with your explicit complete or incomplete judgment and retained workspace artifact evidence. Reporting does not interpret waits or record parent acceptance; do not report complete while required work remains.";
8
8
  export const WORKER_HANDOFF_SECTION = "worker_handoff";
9
9
  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.";
10
10
  const WATCH_SCRIPTS = new Set(["watch-pr-delivery.mjs", "watch-delivery.mjs", "watch-candidate-delivery.mjs"]);
@@ -4,6 +4,44 @@ Commands, the read-only discovery tool, and the Codex importer for `pi-agent/v1`
4
4
 
5
5
  ## Commands
6
6
 
7
+ ### Shared runtime writes
8
+
9
+ Production catalog reads and persistent edits use the canonical agent directory's
10
+ server. Each edit submits the content revision read by that invocation. If another
11
+ client changed the catalog, the server returns `catalog-conflict`; reopen the view
12
+ before trying again. A conflict does not overwrite the newer definition or discard
13
+ the current session branch's temporary choices. Model/effort still use the existing
14
+ `agents/settings.json`; skill changes still use the original Markdown definition.
15
+
16
+ The server serializes cooperating clients' comparison and atomic writes. A direct
17
+ external editor does not participate in this transaction and can race the revision
18
+ comparison and rename. This is not a filesystem-wide compare-and-swap guarantee.
19
+ Open catalog views subscribe to source revisions. The server shares filesystem
20
+ watches and reconciles at most 64 subscribed scopes once per second, including
21
+ paths created after subscription. Revoked subscriptions discard project data;
22
+ the fixed host revalidates its current context before resubscribing. A disconnected
23
+ or missing host requires reopening the view. External changes are
24
+ also visible on the next explicit catalog request. An admitted launch or
25
+ batch retains its frozen snapshot; later changes affect future admission only,
26
+ not an existing attempt, continuation recipe, tools, or sandbox permissions.
27
+
28
+ The fixed Pi host adapter reads the actual workspace, session, branch, overlay
29
+ revision, and `ctx.isProjectTrusted()` decision. It creates an unguessable grant
30
+ in the canonical agent directory's private `catalog-host-admission` directory
31
+ (0700; records 0600). The server checks the record, secret hash, generation,
32
+ exact scope, and live host connection on every request using that grant.
33
+ Issuance is not a socket operation or a tool. Session strings and wire trust
34
+ booleans cannot issue a grant. The CLI's fixed adapter uses the existing SDK
35
+ trust store rather than accepting a project trust argument.
36
+
37
+ The host revalidates its context before catalog operations and at a bounded
38
+ interval while connected. Trust or branch changes invalidate the old grant.
39
+ Host shutdown and connection loss revoke it; reconnect requires current host
40
+ validation and a new grant. Session-only trust does not update the user's trust
41
+ store. Grants remain control metadata, never definition fields, index rows,
42
+ protocol logs, or launch recipes. As in the server's existing security model,
43
+ a process fully controlling the same UID is outside this boundary.
44
+
7
45
  `/agents` is one Pi command. Dialogs use `ctx.ui.select`, `confirm`, `input`, and `editor`. `ctx.hasUI` is false in print and JSON mode. When a choice or confirmation is required there, the command returns `clarification-needed` and writes nothing.
8
46
 
9
47
  In an interactive TUI, `/agents`, `/agents list`, and `/agents show` open a focused catalog view instead of leaving the listing in a persistent widget. Rows align name, effective model, source, and launch state; narrow terminals retain name and model. The model is the resolved actual model when available, otherwise the requested or inherited preference, or `not resolved`. Type to filter by id, name, description, or base role; use Up/Down and Enter to inspect. The detail view opens **Settings**, with Model, Effort, Skills, launch resolution, and diagnostics. **Instructions** contains the complete effective prompt (role plus agent in add mode, agent text in replace mode); this is not the task-specific launch prompt. **Files** shows definition and saved-config sources plus current session edits. Tab and Shift+Tab cycle between these pages; `p` opens Instructions. Up/Down selects settings or scrolls the current page. Left or Escape returns to Settings, then list, clears the filter, then closes. `/agents show <id>` opens that definition directly. Print/JSON callers still receive the complete text and structured result; bare `/agents` still returns help outside the custom TUI.
@@ -71,6 +71,10 @@ export function resolveHealthThresholds(
71
71
 
72
72
  /** Load thresholds from extension config.json (best-effort). */
73
73
  export function loadHealthThresholdsFromConfig(config: SubagentConfig = loadConfig()): HealthThresholds {
74
+ return healthThresholdsForConfig(config);
75
+ }
76
+
77
+ export function healthThresholdsForConfig(config: SubagentConfig): HealthThresholds {
74
78
  return resolveHealthThresholds({
75
79
  ...config,
76
80
  healthQuietMs: config.healthQuietMs ?? envDuration("PI_BETTER_STALL_QUIET_MS"),
@@ -525,9 +529,9 @@ function trimToBudget(state: FactLogState): void {
525
529
  */
526
530
  export function extractChildEventFactsFromLog(
527
531
  id: string,
528
- opts: { now?: number; logText?: string } = {},
532
+ opts: { now?: number; logText?: string; logPath?: string } = {},
529
533
  ): { facts: ChildEventFacts; rawLog: RawLogDiagnostic } {
530
- const path = logPathFor(id);
534
+ const path = opts.logPath ?? logPathFor(id);
531
535
  const rawLog: RawLogDiagnostic = {};
532
536
  try {
533
537
  const st = statSync(path);
@@ -548,7 +552,8 @@ export function extractChildEventFactsFromLog(
548
552
  return { facts: extractChildEventFacts(events), rawLog };
549
553
  }
550
554
 
551
- const previous = factLogStates.get(id);
555
+ const key = opts.logPath ?? id;
556
+ const previous = factLogStates.get(key);
552
557
  const read = readAppendedLines(path, previous?.cursor, maxHealthReadBytes());
553
558
  if (read.error !== undefined) {
554
559
  rawLog.error = rawLog.error ?? read.error;
@@ -568,7 +573,7 @@ export function extractChildEventFactsFromLog(
568
573
  for (const size of parsed.sizes) state.bytes += size;
569
574
  trimToBudget(state);
570
575
  }
571
- rememberState(id, state);
576
+ rememberState(key, state);
572
577
 
573
578
  if (state.truncated) rawLog.windowTruncated = true;
574
579
  if (state.dropped) rawLog.eventsDropped = true;