Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions pi-subagents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ Read-only roles receive a restricted tool allowlist plus ACP context tools so th
- **Interactive (TUI) & RPC modes**: `async:true` (default) runs the child in the background; a short completion notification is injected into the chat when it finishes — **unless the model already read the result file after the run finished** (detected via the `read` tool or a bash command referencing the file), in which case the notification is skipped: the model already has the result, so re-injecting it would only waste context. Set `delegate: { notifyIfRead: "always" }` in `acp.json` to restore always-inject.
- **Print / JSON modes** (`pi -p`, SDK): `async:true` auto-downgrades to **synchronous** — the result returns as the tool result in the same turn.
- **Failures are loud, never silent.** A failed run (nonzero exit, spawn error, watchdog timeout) injects a `FAILED ⚠️` notification carrying a short error excerpt. If a notification cannot be delivered at all, a recovery notice is attached to the next delegate notification or tool result.
- **A watchdog timeout is a failure, not a partial success.** When the watchdog force-kills a run whose agent has not reached its terminal state, the run is reported `FAILED ⚠️` with the partial output kept in the result file for inspection — leftover progress text or stderr does not count as delivery. A run whose agent DID settle but whose process then hangs in teardown/EOF still counts as completed (output was delivered); this matches the sync path, where every timeout is a failure. Budget-conflict hint: a nested sync delegate whose own `timeoutMinutes` exceeds the outer run's remaining budget will be cut off by the outer watchdog first.
- **Result delivery**: the full delegate output is saved to `$TMPDIR/acp-delegate/<runId>.out`; the tool result and notification carry only the **task title + file path** (no preview) — use `read` for the details.
- **Live visibility (TUI)**: async runs show a status widget below the editor and a footer line with cumulative token/cost usage; a running row appends `⚠ no activity Nm` when the child has been silent for over 2 minutes. `/acp-fleet` (or the `ctrl+alt+d` shortcut) opens the interactive fleet inspector: live list + transcript overlay. Disabled automatically in RPC/print/JSON.
- **Compact tool blocks (TUI)**: when the host supports custom tool rendering (pi-coding-agent ≥ 0.62; borderless self-shell since 0.67.3), `acp_delegate*` calls render as compact blocks — the call line shows agent + first task line, the result line shows a status icon, exit label, duration and up to 3 preview lines of the run's output (`Ctrl+O` expands to 40). The preview is screen-only: the model-facing text is unchanged (task title + file path). Older hosts ignore the renderers and show the default tool output.
Expand Down
4 changes: 2 additions & 2 deletions pi-subagents/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion pi-subagents/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "billion-context-pi-subagents",
"version": "0.2.3",
"version": "0.2.4",
"description": "acp_delegate sub-agent tools for the Pi coding agent — split out of billion-context-pi (#612); vendored in-repo (#2384).",
"main": "dist/index.js",
"types": "dist/index.d.ts",
Expand Down
69 changes: 66 additions & 3 deletions pi-subagents/src/delegate-events.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,34 @@ export interface Usage {

export interface UsageUpdateEvent {
kind: "usage-update";
usage: Usage;
/** Absent when the message carried no usable usage block. */
usage?: Usage;
/** Present when the message carried terminal-state fields (#4359). */
terminal?: AssistantTerminalInfo;
}

/** Terminal state of an assistant message as reported by the upstream provider
* on message_end (#4359): distinguishes an upstream error/incomplete stop from
* a completed-but-empty response. Absent fields stay undefined — the consumer
* renders them as unknown rather than guessing. */
export interface AssistantTerminalInfo {
stopReason?: string;
rawStopReason?: string;
errorMessage?: string;
textBlocks: number;
thinkingBlocks: number;
}

/** Merged view of the LAST assistant message_end (terminal state + that
* turn's usage) used for empty-reply diagnostics (#4359). */
export interface EmptyReplyDiagnostics {
stopReason?: string;
rawStopReason?: string;
errorMessage?: string;
textBlocks: number;
thinkingBlocks: number;
usageIn?: number;
usageOut?: number;
}

export interface AgentSettledEvent {
Expand All @@ -33,6 +60,34 @@ function safeNumber(v: unknown): number | undefined {
return typeof v === "number" && Number.isFinite(v) ? v : undefined;
}

/** Extract the terminal-state fields from an assistant message_end payload
* (#4359). Returns undefined when nothing is known (no stop reason and no
* content array) so callers can distinguish "observed" from "unknown". */
export function extractAssistantTerminal(msg: Record<string, unknown>): AssistantTerminalInfo | undefined {
let textBlocks = 0;
let thinkingBlocks = 0;
let hasContent = false;
if (Array.isArray(msg.content)) {
hasContent = true;
for (const b of msg.content) {
if (!b || typeof b !== "object") continue;
const t = (b as Record<string, unknown>).type;
if (t === "text") textBlocks++;
else if (t === "thinking" || t === "reasoning") thinkingBlocks++;
}
}
const stopReason = typeof msg.stopReason === "string" ? msg.stopReason : undefined;
const rawStopReason = typeof msg.rawStopReason === "string" ? msg.rawStopReason : undefined;
const errorMessage =
typeof msg.errorMessage === "string"
? msg.errorMessage
: typeof msg.error === "string"
? msg.error
: undefined;
if (!hasContent && stopReason === undefined && rawStopReason === undefined && errorMessage === undefined) return undefined;
return { stopReason, rawStopReason, errorMessage, textBlocks, thinkingBlocks };
}

export function handleMessageEnd(
event: Record<string, unknown>
): UsageUpdateEvent | null {
Expand Down Expand Up @@ -145,7 +200,7 @@ export class ThinkingCollector {
if (ev.kind === "thinking-delta") {
this.push(ev.delta);
}
if (ev.kind === "usage-update") {
if (ev.kind === "usage-update" && ev.usage) {
this.usage = ev.usage;
}
}
Expand Down Expand Up @@ -240,7 +295,15 @@ export function parseEventLine(line: string): ParsedEvent | null {
};
}
if (e.type === "message_end") {
return handleMessageEnd(e);
const ev = handleMessageEnd(e);
const msg = e.message as Record<string, unknown> | undefined;
const terminal = msg && msg.role === "assistant" ? extractAssistantTerminal(msg) : undefined;
if (!ev && !terminal) return null;
if (ev) {
if (terminal) ev.terminal = terminal;
return ev;
}
return { kind: "usage-update", terminal };
}
if (e.type === "agent_settled") {
return { kind: "agent-settled" };
Expand Down
117 changes: 99 additions & 18 deletions pi-subagents/src/delegate-tool.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,15 @@ import type {
import { debug, logError, logInfo, logWarn } from "./log.js";
import { DEFAULT_DELEGATE_POLICY, type DelegatePolicy, type DelegateRoleConfig } from "./config.js";
import { attachWatchdogs } from "./delegate-watchdog.js";
import { parseEventLine, activityLines, newPortion, ThinkingCollector, type Usage } from "./delegate-events.js";
import {
parseEventLine,
activityLines,
newPortion,
ThinkingCollector,
type Usage,
type AssistantTerminalInfo,
type EmptyReplyDiagnostics,
} from "./delegate-events.js";
import { isPiHost } from "./host.js";
import {
exitLabel,
Expand Down Expand Up @@ -499,6 +507,9 @@ export interface EventApplier {
/** omp fallback: `-p` prints the plain reply as raw stdout; append it
* straight through (no event parsing). */
appendRaw(text: string): void;
/** Terminal state of the last assistant message_end (#4359); undefined when
* none was observed (print-mode hosts, kills before any message_end). */
getEmptyReplyDiagnostics(): EmptyReplyDiagnostics | undefined;
}

/** Applies parsed delegate JSON-event lines to the live reply/activity files.
Expand All @@ -517,6 +528,8 @@ export function makeEventApplier(
let msgWritten = 0;
const lastToolText = new Map<string, string>();
const thinking = new ThinkingCollector(opts.showThinking);
let lastTerminal: AssistantTerminalInfo | undefined;
let lastUsage: Usage | undefined;
const flushThinking = (): void => {
const line = thinking.flush();
if (line) writers.activity?.write(line);
Expand All @@ -525,7 +538,11 @@ export function makeEventApplier(
const ev = parseEventLine(line);
if (!ev) return;
if (ev.kind === "usage-update") {
opts.onUsage?.(ev.usage);
if (ev.usage) {
opts.onUsage?.(ev.usage);
lastUsage = ev.usage;
}
if (ev.terminal) lastTerminal = ev.terminal;
return;
}
if (ev.kind === "thinking-delta") {
Expand Down Expand Up @@ -581,6 +598,18 @@ export function makeEventApplier(
replyText += text;
writers.reply.write(text);
},
getEmptyReplyDiagnostics(): EmptyReplyDiagnostics | undefined {
if (!lastTerminal) return undefined;
return {
stopReason: lastTerminal.stopReason,
rawStopReason: lastTerminal.rawStopReason,
errorMessage: lastTerminal.errorMessage,
textBlocks: lastTerminal.textBlocks,
thinkingBlocks: lastTerminal.thinkingBlocks,
usageIn: lastUsage?.input,
usageOut: lastUsage?.output,
};
},
};
}

Expand Down Expand Up @@ -1189,7 +1218,7 @@ function withUndeliveredNotice<T>(result: AgentToolResult<T>): AgentToolResult<T
* once via this tool result). Returns null when the run was NOT injected,
* in which case the caller delivers the full payload via formatRunResult(). */
export function injectedWaitMessage(
run: { injected?: boolean; readSuppressed?: boolean; result?: { file: string } },
run: { injected?: boolean; readSuppressed?: boolean; result?: { file?: string } },
runId: string,
remainingLine: string,
): string | null {
Expand Down Expand Up @@ -1617,6 +1646,7 @@ async function runDelegate(
body = output || "(no output)";
} else if (noOutput) {
const parts: string[] = [NO_FINAL_OUTPUT_BODY];
parts.push(formatEmptyReplyDiagnostics(applier.getEmptyReplyDiagnostics()) || NO_FINAL_OUTPUT_DIAG_UNKNOWN);
const err = stderrText.trim();
if (err) parts.push(`stderr:\n${err}`);
const tail = activityStream ? await readActivityTail(activityFile) : "";
Expand Down Expand Up @@ -1657,21 +1687,22 @@ async function runDelegate(
if (output === "") {
if (noOutput) {
const err = stderrText.trim();
await appendFile(file, `${NO_FINAL_OUTPUT_BODY}\n${err ? `\n${err}` : ""}\n`);
const diag = formatEmptyReplyDiagnostics(applier.getEmptyReplyDiagnostics()) || NO_FINAL_OUTPUT_DIAG_UNKNOWN;
await appendFile(file, `${NO_FINAL_OUTPUT_BODY}\n${diag}${err ? `\n${err}` : ""}\n`);
} else {
const fallback = stderrText.trim();
await appendFile(file, fallback ? `${fallback}\n` : "(no output)\n");
}
}
// EOF-watchdog finalize has no exit code; if the output was delivered,
// treat it as a completed result (the process is killed afterwards).
const effectiveCode = effectiveExitCode(code, output, stderrText);
// Watchdog/EOF finalizes arrive with code === null; classification
// decides completed vs failed from exit state + settle evidence
// (#4359) — see classifyDelegateOutcome.
// Atomically flip status + result together: until this point the run
// is still "running" to any observer, so a concurrent wait cannot
// see "finished but result missing".
run.result = { code, file, body };
run.status = effectiveCode === 0 && !noOutput ? "completed" : "failed";
if (noOutput) logWarn("delegate", { event: "no-final-output", runId, agent: args.agent, code });
run.status = classifyDelegateOutcome(code, Boolean(run.timedOut), Boolean(run.agentSettled), output, stderrText);
if (noOutput) logWarn("delegate", { event: "no-final-output", runId, agent: args.agent, code, terminal: formatEmptyReplyDiagnostics(applier.getEmptyReplyDiagnostics()) || "unknown" });
run.finishedAt = Date.now();
// If a wait is parked on this run, wake it — it owns the result now
// (and marks consumed so we don't double-deliver by injecting).
Expand Down Expand Up @@ -1816,7 +1847,7 @@ async function runDelegate(
body = result.stderr.trim() || "(no stderr)";
} else if (syncNoOutput) {
const err = result.stderr.trim();
body = err ? `${NO_FINAL_OUTPUT_BODY}\n\nstderr:\n${err}` : NO_FINAL_OUTPUT_BODY;
body = err ? `${NO_FINAL_OUTPUT_BODY}\n${NO_FINAL_OUTPUT_DIAG_PRINT}\n\nstderr:\n${err}` : `${NO_FINAL_OUTPUT_BODY}\n${NO_FINAL_OUTPUT_DIAG_PRINT}`;
} else {
body = result.stdout;
}
Expand Down Expand Up @@ -2031,23 +2062,49 @@ export function formatSyncResult(agent: string, runId: string, task: string, r:
if (r.code === 0 && !r.timedOut && !noOutput) {
return formatPayload(header, file, task);
}
const body = r.timedOut ? "(timed out)" : r.code === 0 ? NO_FINAL_OUTPUT_BODY : (r.stderr.trim() || "(no stderr)");
const body = r.timedOut ? "(timed out)" : r.code === 0 ? `${NO_FINAL_OUTPUT_BODY}\n${NO_FINAL_OUTPUT_DIAG_PRINT}` : (r.stderr.trim() || "(no stderr)");
return formatPayload(header, file, task, body);
}

/** Exit-0 runs that produced no final reply text did not deliver anything
* actionable (#506): a thinking-only stop (thinking budget exhausted) or a
* silent no-op termination must not be announced as a plain completion — the
* parent would trust the notification and never re-dispatch the task. Real
* non-zero exits and watchdog kills (code null / timedOut) are handled by the
* existing failure paths and stay excluded here. */
* actionable (#506/#4359): a thinking-only stop, a silent no-op termination,
* or an upstream error/incomplete response must not be announced as a plain
* completion — the parent would trust the notification and never re-dispatch
* the task. Real non-zero exits and watchdog kills are handled by the failure
* paths; the appended "upstream terminal state" line separates the causes. */
export function genuineNoOutput(code: number | null, timedOut: boolean, output: string): boolean {
return !timedOut && code === 0 && output.trim().length === 0;
}

export const NO_FINAL_OUTPUT_BODY =
"child exited 0 but produced NO final reply text — likely a thinking-only stop (thinking budget exhausted) " +
"or a no-op termination. Treat the task as NOT delivered: inspect the activity log and session file, then re-dispatch if needed.";
"child exited 0 but produced NO final reply text. Treat the task as NOT delivered: inspect the activity log and session file, then re-dispatch if needed.";

/** Diagnostic line for empty-reply failures when no terminal state was ever
* observed in the event stream (killed before any message_end, or a host
* without json event mode). #4359 */
export const NO_FINAL_OUTPUT_DIAG_UNKNOWN =
"upstream terminal state: unknown (no terminal assistant message observed)";

/** Same line for sync/print runs, which have no event stream at all. #4359 */
export const NO_FINAL_OUTPUT_DIAG_PRINT =
"upstream terminal state: unavailable (print mode — no event stream)";

/** Render the captured upstream terminal state as the empty-reply diagnostic
* line (#4359): distinguishes an upstream error/incomplete stop from a
* completed-but-empty response. Unobserved fields render as unknown. "" when
* nothing was observed — callers substitute their own unavailable-note. */
export function formatEmptyReplyDiagnostics(d: EmptyReplyDiagnostics | undefined): string {
if (!d) return "";
const bits: string[] = [];
bits.push(`stopReason=${d.stopReason ?? "unknown"}`);
if (d.rawStopReason !== undefined) bits.push(`rawStopReason=${d.rawStopReason}`);
if (d.errorMessage !== undefined) bits.push(`errorMessage=${JSON.stringify(d.errorMessage)}`);
bits.push(`text_blocks=${d.textBlocks}`, `thinking_blocks=${d.thinkingBlocks}`);
if (d.usageIn !== undefined || d.usageOut !== undefined) {
bits.push(`last_turn_usage(in=${d.usageIn ?? "?"}, out=${d.usageOut ?? "?"})`);
}
return `upstream terminal state: ${bits.join(", ")}`;
}

/** Watchdog/EOF finalize arrives with code === null (the child was killed or
* never exited). If a result was delivered (non-empty reply or stderr), the
Expand All @@ -2056,6 +2113,30 @@ export function effectiveExitCode(code: number | null, output: string, stderr: s
return code ?? (output || stderr ? 0 : null);
}

/** Terminal status of a finished async delegate run (#4359). "completed"
* requires BOTH a successful effective exit AND positive completion evidence:
* a real (non-null) exit code without a watchdog timeout, OR the agent having
* settled (agent_settled observed). A watchdog kill records timedOut ONLY
* while the agent has not settled (the onKill/onEofGrace callbacks gate on
* agentSettled), so a timed-out non-settled run is a FAILURE regardless of
* partial progress text or stderr — those prove the agent was cut off
* mid-work, they are not a delivered result. Null-code closes without settle
* evidence (external kills, spawn errors) fail too. The settled exception
* keeps its old semantics: delivered output whose process hung in teardown/EOF
* (code null, settled) still counts completed. With agentSettled=false this
* rule projects exactly onto the sync ternary, keeping async/sync aligned. */
export function classifyDelegateOutcome(
code: number | null,
timedOut: boolean,
agentSettled: boolean,
output: string,
stderr: string,
): "completed" | "failed" {
const noOutput = genuineNoOutput(code, timedOut, output);
const effectiveCode = effectiveExitCode(code, output, stderr);
return effectiveCode === 0 && !noOutput && (agentSettled || (!timedOut && code !== null)) ? "completed" : "failed";
}

/** Pure read-after-finish predicate: should the completion notification be
* suppressed because the model already read the final result file? Only a
* read at/after finishedAt counts — a read while the run was still in flight
Expand Down
Loading
Loading