brl-subagent 2.3.5 → 2.3.7

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();
@@ -209,8 +227,6 @@ export interface SubagentState {
 	slaTrackingEnabled: boolean; // E4: SLA tracking toggle
 	slaWindowSize: number; // E4: number of recent runs to analyze (10-500)
 	lastSLAMetrics?: SLAMetrics; // E4: persisted baseline for degradation comparison
-	updateCheckEnabled: boolean; // Version update notifier toggle
-	lastUpdateCheck: number; // Epoch ms of last update check
 }
 
 /**
@@ -228,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.
@@ -556,8 +593,6 @@ export const TEMPLATE_PARAM_RE = /\$\{(\w+)\}/g;
 
 export const DEFAULT_SESSION_COST_LIMIT = 0;
 
-export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-
 export const CUSTOM_ENTRY_TYPES = {
 	run: "brl-subagent-run",
 	state: "brl-subagent-state",
@@ -589,7 +624,7 @@ export const RESERVED_NAME_PATTERN = /^__.*__$/;
 export const RESERVED_COMMAND_NAMES = new Set([
 	"model", "thinking", "concurrency", "depth", "history", "monitor",
 	"preset", "retry", "reset", "priority", "templates", "dashboard", "approval",
- "costlimit", "historyentries", "sla", "update-check", "completionnotify",
+ "costlimit", "historyentries", "sla", "completionnotify",
 	"graph", "sla-stats",
 ]);
 
@@ -669,9 +704,108 @@ 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" };
+	}
 }
 
 export function formatModel(m: { provider: string; id: string } | undefined): string {
@@ -750,14 +884,6 @@ export function isSubagentStateShape(value: unknown): value is SubagentState {
 		if (typeof v.slaWindowSize !== "number" || v.slaWindowSize < 10 || v.slaWindowSize > 500) return false;
 	}
 
-	// updateCheckEnabled must be a boolean if present
-	if (v.updateCheckEnabled !== undefined && typeof v.updateCheckEnabled !== "boolean") return false;
-
-	// lastUpdateCheck must be a non-negative number if present
-	if (v.lastUpdateCheck !== undefined) {
-		if (typeof v.lastUpdateCheck !== "number" || v.lastUpdateCheck < 0) return false;
-	}
-
 	return true;
 }
 

package/src/update.ts

@@ -1,109 +0,0 @@
-/**
- * brl-subagent — Version Update Notifier
- *
- * Checks GitHub releases for newer versions of brl-subagent.
- * Runs non-blocking with a 5-second timeout on session start.
- */
-
-import type { Logger } from "./logging";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface UpdateCheckResult {
-	available: boolean;
-	version?: string;
-	url?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Semver comparison
-// ---------------------------------------------------------------------------
-
-/**
- * Compare two semver strings (e.g., "2.1.0" vs "2.0.1").
- * Returns 1 if a > b, -1 if a < b, 0 if equal.
- */
-function compareSemver(a: string, b: string): number {
-	const aParts = a.split(".").map(Number);
-	const bParts = b.split(".").map(Number);
-	const len = Math.max(aParts.length, bParts.length);
-
-	for (let i = 0; i < len; i++) {
-		const aVal = aParts[i] ?? 0;
-		const bVal = bParts[i] ?? 0;
-		if (aVal > bVal) return 1;
-		if (aVal < bVal) return -1;
-	}
-	return 0;
-}
-
-// ---------------------------------------------------------------------------
-// Main export
-// ---------------------------------------------------------------------------
-
-/**
- * Check GitHub for a newer release of brl-subagent.
- *
- * @param currentVersion - The current version string (e.g., "2.0.1")
- * @param log - Optional logger for debug output
- * @returns Update check result, or null on any error (never throws)
- */
-export async function checkForUpdates(
-	currentVersion: string,
-	log?: Logger,
-): Promise<UpdateCheckResult | null> {
-	try {
-		const controller = new AbortController();
-		const timeoutId = setTimeout(() => controller.abort(), 5_000);
-
-		const response = await fetch(
-			"https://api.github.com/repos/azmeenafandi/brl-subagent/releases/latest",
-			{
-				headers: {
-					Accept: "application/vnd.github+json",
-					"User-Agent": "brl-subagent",
-				},
-				signal: controller.signal,
-			},
-		);
-
-		clearTimeout(timeoutId);
-
-		if (!response.ok) {
-			log?.debug("Update check: non-OK response", { status: response.status });
-			return null;
-		}
-
-		const data = (await response.json()) as {
-			tag_name?: string;
-			html_url?: string;
-		};
-
-		if (!data.tag_name || !data.html_url) {
-			log?.debug("Update check: missing tag_name or html_url in response");
-			return null;
-		}
-
-		// Strip "v" prefix from tag_name (e.g., "v2.1.0" → "2.1.0")
-		const latestVersion = data.tag_name.replace(/^v/, "");
-
-		const cmp = compareSemver(latestVersion, currentVersion);
-
-		if (cmp > 0) {
-			return {
-				available: true,
-				version: latestVersion,
-				url: data.html_url,
-			};
-		}
-
-		return { available: false };
-	} catch (err) {
-		log?.debug("Update check failed", {
-			error: err instanceof Error ? err.message : String(err),
-		});
-		return null;
-	}
-}