pi-better-subagents 0.26.0 → 0.26.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/tools.ts CHANGED
@@ -109,6 +109,7 @@ function normalizeOutputRequest<T extends Record<string, unknown>>(params: T): T
109
109
 
110
110
  const MAX_BYTES_ALIAS_DESCRIPTION = "Deprecated alias for max_bytes. max_bytes wins when both are given.";
111
111
  const HISTORY_DESCRIPTION = "If true, return an incident page that also lists failure history: unclassified child tool errors, expected failures, and recovered or superseded incidents. Default output lists only failures that need action and counts the rest.";
112
+ const TAIL_DESCRIPTION = "With mode=raw: read from the newest retained byte first instead of byte 0. The page is end-anchored and nextCursor then pages toward the oldest bytes; once the start is reached the cursor reads only bytes appended later. Use this to reach the end of a multi-MB log without paging from byte zero.";
112
113
  const INCLUDE_DESCRIPTION = "Explicit opt-in facts omitted by default: \"cost\" adds one token/cost spend line, \"tools\" adds one tool-call count line with the distinct tool names.";
113
114
 
114
115
  /** pi's tool-result text shape. */
@@ -385,6 +386,7 @@ export function subagentListTool(Type: TypeModule, baseSession: SubagentToolSess
385
386
  scopeKey,
386
387
  statusesKey,
387
388
  unreadable: index.unreadable,
389
+ abandonedLaunches: index.abandoned,
388
390
  indexError: index.indexError,
389
391
  incidentRuns,
390
392
  }));
@@ -400,6 +402,7 @@ export function subagentOutputTool(Type: TypeModule, baseSession: SubagentToolSe
400
402
  description:
401
403
  "Read a subagent run's current output without waiting. Default is a 1 KiB / 10-line excerpt of the current session. " +
402
404
  "Pass all:true to read a foreign-session id. Pass mode=raw for retained-log pages (16 KiB default, 64 KiB cap). " +
405
+ "Pass tail:true with mode=raw to start from the newest retained bytes and page toward the oldest. " +
403
406
  "Pass cursor to continue or to poll for failure-only changes. Missing or unreadable logs are reported as gaps, not as empty healthy output. " +
404
407
  "Spend and tool counts are omitted unless include:[\"cost\",\"tools\"] asks for them.",
405
408
  promptSnippet: "Peek at a subagent's current output without waiting",
@@ -415,13 +418,14 @@ export function subagentOutputTool(Type: TypeModule, baseSession: SubagentToolSe
415
418
  max_bytes: Type.Optional(Type.Number({ description: "UTF-8 byte budget for this page (default 1 KiB, max 4 KiB; raw default 16 KiB, max 64 KiB)." })),
416
419
  maxBytes: Type.Optional(Type.Number({ description: MAX_BYTES_ALIAS_DESCRIPTION })),
417
420
  mode: Type.Optional(Type.String({ description: "raw = page retained log bytes. Default is the bounded assembled excerpt." })),
421
+ tail: Type.Optional(Type.Boolean({ description: TAIL_DESCRIPTION })),
418
422
  include: Type.Optional(Type.Array(Type.String(), { description: INCLUDE_DESCRIPTION })),
419
423
  history: Type.Optional(Type.Boolean({ description: HISTORY_DESCRIPTION })),
420
424
  all: Type.Optional(Type.Boolean({ description: "If true, allow a foreign-session id. Default is current session only." })),
421
425
  }),
422
426
  async execute(_id: string, params: unknown, _signal?: unknown, _onUpdate?: unknown, ctx?: unknown) {
423
427
  const session = forCall(baseSession, ctx);
424
- const p = normalizeOutputRequest(params as Record<string, unknown>) as { id: string; cursor?: string; maxBytes?: unknown; mode?: string; all?: boolean; lines?: unknown; include?: unknown; history?: boolean };
428
+ const p = normalizeOutputRequest(params as Record<string, unknown>) as { id: string; cursor?: string; maxBytes?: unknown; mode?: string; all?: boolean; lines?: unknown; include?: unknown; history?: boolean; tail?: boolean };
425
429
  const access = resolveRunAccess(p.id, p, session);
426
430
  if (access.kind === "missing") throw unknownRunError(p.id);
427
431
  if (access.kind === "unreadable") return text(assembleUnreadableMetadata(p.id, access.detail, p));
@@ -441,7 +445,7 @@ export function subagentResultTool(Type: TypeModule, baseSession: SubagentToolSe
441
445
  name: "subagent_result",
442
446
  label: "Subagent Result",
443
447
  description:
444
- "Read a subagent's final output if it has finished. NEVER waits. Default current session. Ordinary answers are preserved verbatim in a 2048-byte UTF-8 page (max_bytes up to 8192 bytes, optional lines cap); pass cursor to reconstruct the rest. Pass all:true for a foreign-session id. mode=raw pages retained log bytes (16 KiB default, 64 KiB cap). Failures and exceptional lifecycle facts come before progress. No tool-name histories or default cost lines; pass include:[\"cost\",\"tools\"] to opt in.",
448
+ "Read a subagent's final output if it has finished. NEVER waits. Default current session. Ordinary answers are preserved verbatim in a 2048-byte UTF-8 page (max_bytes up to 8192 bytes, optional lines cap); pass cursor to reconstruct the rest. Pass all:true for a foreign-session id. mode=raw pages retained log bytes (16 KiB default, 64 KiB cap) and tail:true with mode=raw starts from the newest bytes. Failures and exceptional lifecycle facts come before progress. No tool-name histories or default cost lines; pass include:[\"cost\",\"tools\"] to opt in.",
445
449
  promptSnippet: "Read a finished subagent's final result (never waits)",
446
450
  promptGuidelines: [
447
451
  "Use subagent_result to collect a finished run's output. If it reports the run is still going, stop — do not poll; you'll be notified when it finishes.",
@@ -455,6 +459,7 @@ export function subagentResultTool(Type: TypeModule, baseSession: SubagentToolSe
455
459
  lines: Type.Optional(Type.Number({ description: "Optional line cap for each answer page (default: bytes only). nextCursor continues after the last line shown." })),
456
460
  tail_lines: Type.Optional(Type.Number({ description: "Deprecated alias for lines. lines wins when both are given." })),
457
461
  mode: Type.Optional(Type.String({ description: "raw = page retained log bytes (16 KiB default, 64 KiB cap). Default is the bounded assembled result." })),
462
+ tail: Type.Optional(Type.Boolean({ description: TAIL_DESCRIPTION })),
458
463
  include: Type.Optional(Type.Array(Type.String(), { description: INCLUDE_DESCRIPTION })),
459
464
  history: Type.Optional(Type.Boolean({ description: HISTORY_DESCRIPTION })),
460
465
  all: Type.Optional(Type.Boolean({ description: "If true, allow a foreign-session id. Default is current session only." })),
@@ -464,7 +469,7 @@ export function subagentResultTool(Type: TypeModule, baseSession: SubagentToolSe
464
469
  },
465
470
  async execute(_id: string, params: unknown, _signal?: unknown, _onUpdate?: unknown, ctx?: unknown) {
466
471
  const session = forCall(baseSession, ctx);
467
- const p = normalizeOutputRequest(params as Record<string, unknown>) as { id: string; cursor?: string; maxBytes?: unknown; mode?: string; all?: boolean; lines?: unknown; include?: unknown; history?: boolean };
472
+ const p = normalizeOutputRequest(params as Record<string, unknown>) as { id: string; cursor?: string; maxBytes?: unknown; mode?: string; all?: boolean; lines?: unknown; include?: unknown; history?: boolean; tail?: boolean };
468
473
  const access = resolveRunAccess(p.id, p, session);
469
474
  if (access.kind === "missing") throw unknownRunError(p.id);
470
475
  if (access.kind === "unreadable") {
@@ -498,10 +503,12 @@ export function subagentResultTool(Type: TypeModule, baseSession: SubagentToolSe
498
503
  /**
499
504
  * Stop is the one tool with a UI side effect (widget redraw after a kill);
500
505
  * the caller injects it so the factory stays loadable without a TUI context.
506
+ * The hook receives the run id so the host can also queue the run's one
507
+ * terminal completion callback (#624).
501
508
  */
502
509
  export function subagentStopTool(
503
510
  Type: TypeModule,
504
- deps: { onStopped?: () => void } = {},
511
+ deps: { onStopped?: (id: string) => void } = {},
505
512
  ): ToolDefinition {
506
513
  return {
507
514
  name: "subagent_stop",
@@ -509,7 +516,10 @@ export function subagentStopTool(
509
516
  description:
510
517
  "Stop a running or orphaned subagent. Terminates identifiable related " +
511
518
  "process-group members when present; otherwise finalizes from log " +
512
- "evidence (completed/failed) or records lost.",
519
+ "evidence (completed/failed) or records lost. " +
520
+ "An abandoned launch record (a launch that never wrote metadata and never " +
521
+ "started a child) is removed instead; a launch that is still preparing or " +
522
+ "published concurrently is preserved.",
513
523
  promptSnippet: "Stop a running or orphaned background subagent",
514
524
  parameters: Type.Object({
515
525
  id: Type.String({ description: "Run id from subagent_spawn." }),
@@ -519,10 +529,23 @@ export function subagentStopTool(
519
529
  // Shared stop semantics with the TUI navigator close action (#44/#68):
520
530
  // stopRun rereads meta + effective status from disk before acting.
521
531
  const outcome = stopRun(p.id);
532
+ if (outcome.action === "purged") {
533
+ // No run record exists, so the stop hook's completion half is a
534
+ // no-op (#624); the widget/ticker refresh still applies.
535
+ deps.onStopped?.(p.id);
536
+ return text(`Removed abandoned launch record ${p.id} (no run metadata was written, so no child ever ran).`);
537
+ }
538
+ if (outcome.action === "preserved") {
539
+ // Nothing stopped: a live run owes no terminal completion, so the
540
+ // stop hook is deliberately not fired here (#624).
541
+ return text(outcome.status === "launching"
542
+ ? `Preserved ${p.id}: a launch is still preparing it (no metadata yet), so nothing was removed. Retry after it publishes, or after it fails.`
543
+ : `Preserved ${p.id}: a concurrent launch published this run (${outcome.status}), so nothing was removed. Call subagent_stop again to stop the run.`);
544
+ }
522
545
  if (outcome.action === "not-running") {
523
546
  return text(`Run ${p.id} is not running (${outcome.status}).`);
524
547
  }
525
- deps.onStopped?.();
548
+ deps.onStopped?.(p.id);
526
549
  if (outcome.action === "finalized") {
527
550
  return text(`Resolved orphaned subagent ${p.id} → ${outcome.status}.`);
528
551
  }