pi-better-subagents 0.26.0 → 0.26.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.
- package/cleanup.ts +58 -2
- package/continuation.ts +58 -7
- package/docs/usage.md +76 -9
- package/finalization.ts +1 -1
- package/index.ts +595 -287
- package/output-payload.ts +40 -3
- package/package.json +1 -1
- package/registry.ts +215 -4
- package/shared-callback-batcher.ts +18 -1
- package/shared-failure-observations.ts +78 -24
- package/shared-log-utils.ts +277 -31
- package/stop.ts +60 -2
- package/timing.ts +45 -4
- package/tools.ts +29 -6
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
|
}
|