brl-subagent 2.3.6 → 2.3.8

package/src/transcript.ts

@@ -19,8 +19,9 @@ export function __setOutputDir(dir: string): void {
  * Ensure output directory exists
  */
 function ensureOutputDir(): void {
-  // F6 (issue #29): transcripts contain the full subagent conversation — the
-  // dir must be owner-only (0o700) so other local users cannot list the files.
+  // F6 (issue #29): transcripts may hold task/steering text — the dir must be
+  // owner-only (0o700) so other local users cannot list the files. NOTE: the
+  // transcript is NOT the full conversation (see appendEntry below).
   mkdirSync(OUTPUT_DIR, { recursive: true, mode: 0o700 });
 }
 
@@ -52,8 +53,9 @@ export function startTranscript(agentId: string, task: string): string {
     metadata: { task },
   };
   
-  // F6 (issue #29): transcripts hold the full conversation — append
-  // owner-only (0o600) on file CREATE (mode is not retroactive).
+  // F6 (issue #29): append owner-only (0o600) on file CREATE (mode is not
+  // retroactive). The file holds the system start entry plus any steering
+  // entries appended below — NOT the full conversation.
   appendFileSync(path, JSON.stringify(entry) + '\n', { encoding: 'utf-8', mode: 0o600 });
   return path;
 }
@@ -79,8 +81,11 @@ export function appendEntry(
     metadata,
   };
   
-  // F6 (issue #29): transcripts hold the full conversation — append
-  // owner-only (0o600) on file CREATE (mode is not retroactive).
+  // F6 (issue #29): append owner-only (0o600) on file CREATE (mode is not
+  // retroactive). NOTE (D5 / issue #179): this is NOT a conversation recorder —
+  // the only caller is steering (steerAgent), so the transcript holds the
+  // system start entry and steering lines. Do NOT describe it as the full
+  // conversation without actually recording one.
   appendFileSync(path, JSON.stringify(entry) + '\n', { encoding: 'utf-8', mode: 0o600 });
 }
 

package/src/tui.ts

@@ -1710,7 +1710,7 @@ export async function showAgentDetail(
 						// path persists it), mirroring the background path's
 						// `agent?.finalOutput` fallback.
 						const runOutput =
-							cachedTail || state.findRunById(ctx, agentId)?.fullOutput || "";
+							cachedTail || state.findTerminalRunById(ctx, agentId)?.fullOutput || "";
 						const tailLines = runOutput.split("\n").filter(Boolean).slice(-10);
 						if (tailLines.length > 0) {
 							container.addChild(new Spacer(1));
@@ -2190,10 +2190,7 @@ function renderSubTaskSummary(
 	},
 	maxLines: number,
 ): string {
-	const isError =
-		result.exitCode !== 0 ||
-		result.stopReason === "error" ||
-		result.stopReason === "aborted";
+	const isError = isSubagentError(result);
 	const icon = isError
 		? theme.fg("error", "\u2717")
 		: theme.fg("success", "\u2713");
@@ -2213,12 +2210,7 @@ function renderCollapsedChain(
 	details: ChainDetails,
 	theme: Theme,
 ): string {
-	const allSucceeded = details.results.every(
-		(r) =>
-			r.exitCode === 0 &&
-			r.stopReason !== "error" &&
-			r.stopReason !== "aborted",
-	);
+	const allSucceeded = details.results.every((r) => !isSubagentError(r));
 	const icon = allSucceeded
 		? theme.fg("success", "\u2713")
 		: theme.fg("error", "\u2717");
@@ -2226,10 +2218,7 @@ function renderCollapsedChain(
 	let text = `${icon} ${theme.fg("toolTitle", theme.bold("chain"))} ${theme.fg("muted", `${details.completedSteps}/${details.totalSteps} steps${stoppedEarly}`)}`;
 
 	for (const r of details.results) {
-		const isErr =
-			r.exitCode !== 0 ||
-			r.stopReason === "error" ||
-			r.stopReason === "aborted";
+		const isErr = isSubagentError(r);
 		const statusIcon = isErr
 			? theme.fg("error", "\u2717")
 			: theme.fg("success", "\u2713");
@@ -2263,10 +2252,7 @@ function renderCollapsedParallel(
 	let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel"))} ${theme.fg("muted", `${details.succeeded}/${details.failed}/${details.results.length} total`)}`;
 
 	for (const r of details.results) {
-		const isErr =
-			r.exitCode !== 0 ||
-			r.stopReason === "error" ||
-			r.stopReason === "aborted";
+		const isErr = isSubagentError(r);
 		const statusIcon = isErr
 			? theme.fg("error", "\u2717")
 			: theme.fg("success", "\u2713");
@@ -2312,10 +2298,7 @@ function renderExpandedChain(
 	container.addChild(new Spacer(1));
 
 	for (const r of details.results) {
-		const isErr =
-			r.exitCode !== 0 ||
-			r.stopReason === "error" ||
-			r.stopReason === "aborted";
+		const isErr = isSubagentError(r);
 		const statusIcon = isErr
 			? theme.fg("error", "\u2717")
 			: theme.fg("success", "\u2713");
@@ -2397,10 +2380,7 @@ function renderExpandedParallel(
 	container.addChild(new Spacer(1));
 
 	for (const r of details.results) {
-		const isErr =
-			r.exitCode !== 0 ||
-			r.stopReason === "error" ||
-			r.stopReason === "aborted";
+		const isErr = isSubagentError(r);
 		const statusIcon = isErr
 			? theme.fg("error", "\u2717")
 			: theme.fg("success", "\u2713");
@@ -2774,12 +2754,7 @@ function renderCollapsedGraph(
 ): string {
 	const totalTasks = details.waves.reduce((s, w) => s + w.tasks.length, 0);
 	const allSucceeded = details.waves.every((w) =>
-		w.tasks.every(
-			(r) =>
-				r.exitCode === 0 &&
-				r.stopReason !== "error" &&
-				r.stopReason !== "aborted",
-		),
+		w.tasks.every((r) => !isSubagentError(r)),
 	);
 	const icon = allSucceeded
 		? theme.fg("success", "\u2713")
@@ -2790,22 +2765,16 @@ function renderCollapsedGraph(
 	const wavesToRender = details.waves.slice(0, maxWavesToShow);
 
 	for (const wave of wavesToRender) {
-		const waveOk = wave.tasks.every(
-			(r) =>
-				r.exitCode === 0 &&
-				r.stopReason !== "error" &&
-				r.stopReason !== "aborted",
-		);
+		const waveOk = wave.tasks.every((r) => !isSubagentError(r));
 		const waveIcon = waveOk
 			? theme.fg("success", "\u2713")
 			: theme.fg("error", "\u2717");
 		const modeLabel = wave.parallel ? "parallel" : "serial";
 		const taskLabels = wave.tasks.map((r) => {
 			const label = r.label || r.task.slice(0, 30);
-			const taskIcon =
-				r.exitCode === 0 && r.stopReason !== "error" && r.stopReason !== "aborted"
-					? theme.fg("success", "\u2713")
-					: theme.fg("error", "\u2717");
+			const taskIcon = !isSubagentError(r)
+				? theme.fg("success", "\u2713")
+				: theme.fg("error", "\u2717");
 			return `${taskIcon} ${theme.fg("dim", label)}`;
 		});
 		text += `
@@ -2843,12 +2812,7 @@ function renderExpandedGraph(
 	container.addChild(new Spacer(1));
 
 	for (const wave of details.waves) {
-		const waveOk = wave.tasks.every(
-			(r) =>
-				r.exitCode === 0 &&
-				r.stopReason !== "error" &&
-				r.stopReason !== "aborted",
-		);
+		const waveOk = wave.tasks.every((r) => !isSubagentError(r));
 		const waveIcon = waveOk
 			? theme.fg("success", "\u2713")
 			: theme.fg("error", "\u2717");
@@ -2862,10 +2826,7 @@ function renderExpandedGraph(
 		);
 
 		for (const r of wave.tasks) {
-			const isErr =
-				r.exitCode !== 0 ||
-				r.stopReason === "error" ||
-				r.stopReason === "aborted";
+			const isErr = isSubagentError(r);
 			const statusIcon = isErr
 				? theme.fg("error", "\u2717")
 				: theme.fg("success", "\u2713");

package/src/types.ts

@@ -43,7 +43,14 @@ export type ErrorCategory =
 	| "aborted"
 	| "exit_error"
 	| "crash"
-	| "unknown";
+	| "unknown"
+	// Issue #179: additive terminal-reason categories. "truncated" = the model
+	// hit its output/context limit (stopReason "length"); "incomplete" = the
+	// agent stopped mid-turn without a terminal answer (stopReason
+	// "toolUse"/"deferred"/"pending"). Existing consumers treat categories as
+	// string keys (metrics/SLA breakdown), so both are additive.
+	| "truncated"
+	| "incomplete";
 
 // Issue #120 (Review round): single source of truth for the user-abort stamp.
 // Used by the abort handler (runner.ts), the stopped/aborted settlement paths
@@ -58,6 +65,17 @@ export const SUBAGENT_ABORTED_MESSAGE = "Subagent aborted by user";
  */
 export function classifyError(result: SubagentResult): ErrorCategory {
 	if (result.stopReason === "aborted") return "aborted";
+	// Issue #179: a terminal stopReason with no terminal answer is a failure in
+	// its own right — classify it before the message/exitCode fallbacks so the
+	// honest category wins (length → "truncated"; mid-turn → "incomplete").
+	if (result.stopReason === "length") return "truncated";
+	if (
+		result.stopReason === "toolUse" ||
+		result.stopReason === "deferred" ||
+		result.stopReason === "pending"
+	) {
+		return "incomplete";
+	}
 
 	const msg = (result.errorMessage ?? "").toLowerCase();
 	const err = (result.stderr ?? "").toLowerCase();
@@ -226,6 +244,27 @@ export interface SubagentRun {
 	id: string;
 	task: string;
 	label?: string;
+	/**
+	 * Issue #179 (D1/D2): terminal stopReason of the final assistant turn
+	 * ("stop" | "error" | "aborted" | "length" | "toolUse" | "deferred" |
+	 * "pending"). Recorded on the finalized entry so consumers can tell a real
+	 * success from a resolved-but-failed run.
+	 */
+	stopReason?: string;
+	/**
+	 * Issue #179 (D1/D2): classified error category at the TOP level. The legacy
+	 * `originalParams.errorCategory` is kept populated for back-compat (metrics,
+	 * retry snapshot), but new consumers should prefer this field.
+	 */
+	errorCategory?: ErrorCategory;
+	/**
+	 * Issue #179 (D3): assistant turns folded from the session usage. 0 means the
+	 * run burned nothing ("did nothing"); > 0 with `finalTurnError` means it did
+	 * work and then died.
+	 */
+	turns?: number;
+	/** Issue #179 (D3): whether the final assistant turn was a provider error. */
+	finalTurnError?: boolean;
 	// Issue #98: background run entries carry the agent description (the label
 	// the caller passed at spawn) — kept separate from `label` for symmetry
 	// with the background agent record.
@@ -665,9 +704,129 @@ export function getFinalOutput(messages: Array<Record<string, unknown>>): string
 }
 
 export function isSubagentError(result: SubagentResult): boolean {
-	return result.exitCode !== 0
-		|| result.stopReason === "error"
-		|| result.stopReason === "aborted";
+	if (result.exitCode !== 0) return true;
+	// Issue #179: a resolved-but-failed terminal reason is still an error. This
+	// is the foreground terminal-status derivation (finalizeRunRecord) — the
+	// background path classifies via classifyTerminalOutcome below.
+	return result.stopReason === "error"
+		|| result.stopReason === "aborted"
+		|| result.stopReason === "length"
+		|| result.stopReason === "toolUse"
+		|| result.stopReason === "deferred"
+		|| result.stopReason === "pending";
+}
+
+/**
+ * Issue #179 (review ratchet): the NARROWER question — was the terminal turn a
+ * provider/model error specifically?
+ *
+ * This is distinct from `isSubagentError` (did the run fail at all): a `length`,
+ * `toolUse`, `deferred` or `pending` ending is a FAILED RUN but NOT a provider
+ * error, and callers asking this narrower question want only `"error"`.
+ *
+ * Named so the literal has exactly one home — a consistency ratchet test fails if
+ * any other module compares `stopReason` against a failure reason directly, which
+ * is how the private copies of the wider predicate silently desynced.
+ */
+export function isProviderError(stopReason: string | undefined): boolean {
+	return stopReason === "error";
+}
+
+/**
+ * Issue #179 (C1 fix): tally subtask outcomes by the SHARED failure predicate.
+ * Deriving success from `exitCode === 0` alone mislabels a truncated or
+ * mid-turn run (a resolved prompt with stopReason length/toolUse/deferred/
+ * pending, exitCode 0) as a success — the exact "failure displayed as a
+ * success" defect. Every aggregate (parallel succeeded/failed, chain/graph
+ * success, the TUI verdicts) must route through isSubagentError so a future
+ * widening of the predicate cannot silently desync a private copy.
+ */
+export function countSubagentOutcomes(
+	results: ReadonlyArray<SubagentResult | undefined>,
+): { succeeded: number; failed: number } {
+	let succeeded = 0;
+	let failed = 0;
+	for (const r of results) {
+		if (!r) continue;
+		if (isSubagentError(r)) failed++;
+		else succeeded++;
+	}
+	return { succeeded, failed };
+}
+
+// ---------------------------------------------------------------------------
+// Issue #179: terminal outcome classification
+// ---------------------------------------------------------------------------
+
+/** Terminal status a settled run can take. */
+export type TerminalStatus = "completed" | "failed" | "stopped";
+
+export interface TerminalOutcome {
+	status: TerminalStatus;
+	errorCategory?: ErrorCategory;
+}
+
+/**
+ * Issue #179 (D1): classify a run's terminal outcome from its final assistant
+ * stopReason. This is the settle-time counterpart to classifyError/isSubagentError
+ * and REUSES classifyError for every failure reason (single taxonomy).
+ *
+ * | stopReason               | status    | errorCategory              |
+ * |--------------------------|-----------|----------------------------|
+ * | stop / undefined         | completed | —                          |
+ * | aborted                  | stopped   | aborted                    |
+ * | error                    | failed    | from classifyError         |
+ * | length                   | failed    | truncated                  |
+ * | toolUse/deferred/pending | failed    | incomplete                 |
+ */
+export function classifyTerminalOutcome(
+	stopReason: string | undefined,
+	errorMessage?: string,
+	extra?: { stderr?: string; exitCode?: number },
+): TerminalOutcome {
+	switch (stopReason) {
+		case "aborted":
+			return { status: "stopped", errorCategory: "aborted" };
+		case "error":
+		case "length":
+		case "toolUse":
+		case "deferred":
+		case "pending":
+			return {
+				status: "failed",
+				errorCategory: classifyError({
+					messages: [],
+					usage: { ...EMPTY_USAGE },
+					exitCode: extra?.exitCode ?? 0,
+					stderr: extra?.stderr ?? "",
+					errorMessage,
+					stopReason,
+				}),
+			};
+		default:
+			return { status: "completed" };
+	}
+}
+
+/**
+ * Issue #179 (C1 fix): a failed run entry/result must carry a terminal reason
+ * that AGREES with its status — never undefined, never "stop". Any reason the
+ * classifier already treats as a failure (error / length / toolUse / deferred
+ * / pending / aborted) is coherent and kept; a missing or success reason is
+ * coerced to the honest failure reason derived from the classified category.
+ *
+ * Issue #187: lives here (not session-manager) so BOTH the background
+ * finalize (session-manager.ts) and the foreground finalize (history.ts) apply
+ * the SAME rule through one implementation instead of two copies.
+ */
+export function coherentFailureReason(
+	stopReason: string | undefined,
+	errorCategory: ErrorCategory | undefined,
+): string {
+	if (stopReason && classifyTerminalOutcome(stopReason).status !== "completed") {
+		return stopReason;
+	}
+	return errorCategory === "aborted" ? "aborted" : "error";
 }
 
 export function formatModel(m: { provider: string; id: string } | undefined): string {