brl-subagent 2.3.4

package/src/notify-completion.ts

@@ -0,0 +1,207 @@
+/**
+ * brl-subagent — Completion-push wake (issue #147)
+ *
+ * Builds and sends the `subagent-completion` custom message that wakes the
+ * conductor when a background run reaches a terminal state. This module is
+ * deliberately split into:
+ *   - a PURE `buildCompletionMessage(agent, run)` builder (unit-tested, no pi
+ *     SDK, no side effects — derives status/category/label/cost from the run
+ *     record);
+ *   - a PURE `resolveDelivery(status, knob)` that maps the D1+D2 matrix to a
+ *     `{ deliverAs, triggerTurn }` pair;
+ *   - a THIN `sendCompletionNotification(pi, ...)` sender — the ONLY call site
+ *     of `pi.sendMessage`, one call, no logic.
+ *
+ * Delivery is always-on (minimum `nextTurn`); the `completionNotify` knob only
+ * controls the WAKE (D2). D1: failed/stopped → "steer", completed → "followUp".
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+	BackgroundAgent,
+	SubagentRun,
+	CompletionNotifyMode,
+	AgentStatus,
+} from "./types";
+import { truncateTail } from "./transcript-tail";
+import { formatRunDuration } from "./history";
+
+/** Terminal statuses the completion message can carry. */
+export type CompletionStatus = "completed" | "failed" | "stopped";
+
+/** Structured `details` the conductor can act on without drill-in (D3). */
+export interface CompletionMessageDetails {
+	id: string;
+	status: CompletionStatus;
+	errorCategory: string;
+	errorMessage?: string;
+	costUsd?: number;
+	tokensIn?: number;
+	tokensOut?: number;
+	durationMs?: number;
+	label?: string;
+}
+
+export interface CompletionMessagePayload {
+	customType: "subagent-completion";
+	content: string;
+	display: true;
+	details: CompletionMessageDetails;
+}
+
+export interface DeliveryResolution {
+	deliverAs: "steer" | "followUp" | "nextTurn";
+	triggerTurn: boolean;
+}
+
+/** Default dedupe cap: the set is simply cleared when it exceeds this. */
+const DEDUPE_CAP = 200;
+
+/**
+ * Soft directive appended to the content (D3): the conductor should process
+ * the completion silently unless action is needed; on failure apply the retry
+ * taxonomy (re-dispatch ≠ retry; Rule 18 governs terminations — ask the user
+ * before terminating anything).
+ */
+const COMPLETION_DIRECTIVE =
+	"Process this completion silently unless action is needed. If the run failed, apply the retry taxonomy: a re-dispatch is not a retry, and Rule 18 governs terminations — ask the user before terminating anything.";
+
+/**
+ * Normalize a BackgroundAgent status to a terminal status word. The subscriber
+ * only fires on terminal events, so the status is always terminal in practice;
+ * this maps any residual non-terminal value to "completed" rather than throwing.
+ */
+export function normalizeCompletionStatus(status: AgentStatus): CompletionStatus {
+	if (status === "failed" || status === "stopped") return status;
+	return "completed";
+}
+
+/**
+ * Resolve the finalized entry for a run id among the raw getRunEntries list.
+ *
+ * Each background run writes TWO custom entries sharing the same id and
+ * startedAt: a spawn entry (status "running") and a final entry (status
+ * "done"/"failed", stamped by finalizeRunRecord). The raw list preserves
+ * append order — the spawn entry comes FIRST (verified empirically) — so a
+ * plain `.find(r => r.id === id)` matches the spawn entry and never sees the
+ * stamped errorCategory/cost/duration/tokens. Prefer the terminal entry
+ * (status !== "running"); when none is terminal yet, fall back to the
+ * matching spawn entry (the pre-finalize stopped-run shape).
+ */
+export function resolveRunEntry(
+	entries: SubagentRun[],
+	id: string,
+): SubagentRun | undefined {
+	const matching = entries.filter((r) => r.id === id);
+	if (matching.length === 0) return undefined;
+	return matching.find((r) => r.status !== "running") ?? matching[0];
+}
+
+/**
+ * Build the one-line summary: `Background agent "<label>" (<id>) — <status> in
+ * <duration> · $<cost> · category: <category>` (D3).
+ */
+function buildSummaryLine(
+	label: string,
+	id: string,
+	status: CompletionStatus,
+	durationMs: number | undefined,
+	costUsd: number | undefined,
+	errorCategory: string,
+): string {
+	let line = `Background agent "${label}" (${id}) — ${status}`;
+	if (durationMs !== undefined) line += ` in ${formatRunDuration(durationMs)}`;
+	if (costUsd !== undefined) line += ` · $${costUsd}`;
+	line += ` · category: ${errorCategory}`;
+	return line;
+}
+
+/**
+ * PURE builder — no pi SDK, no side effects, never throws. Returns the
+ * sendMessage payload shape per D3.
+ *
+ * Cost/tokens/duration are read from the run entry when present; if the run
+ * entry is absent (or the field is unset) the field is omitted from `details`
+ * and the summary tail.
+ */
+export function buildCompletionMessage(
+	agent: BackgroundAgent,
+	run: SubagentRun | undefined,
+): CompletionMessagePayload {
+	const status = normalizeCompletionStatus(agent.status);
+	// BackgroundAgent has no `label` field — the caller's label is `description`
+	// (set from params.description at spawn). Fall back to the id.
+	const label = agent.description || agent.id;
+	// completed → "success"; failed/stopped → classified category from the run
+	// record (finalizeRunEntry stamps it), falling back to "unknown".
+	const errorCategory =
+		status === "completed" ? "success" : (run?.originalParams?.errorCategory ?? "unknown");
+	const durationMs = run?.durationMs;
+	const costUsd = run?.cost;
+	const tokensIn = run?.tokensIn;
+	const tokensOut = run?.tokensOut;
+	const errorMessage = status === "completed" ? undefined : agent.error ?? run?.errorMessage;
+
+	const summary = buildSummaryLine(label, agent.id, status, durationMs, costUsd, errorCategory);
+	const tail = truncateTail(agent.finalOutput ?? run?.fullOutput ?? "", 15);
+	const parts = [summary];
+	if (tail) parts.push(tail);
+	parts.push(COMPLETION_DIRECTIVE);
+	const content = parts.join("\n\n");
+
+	const details: CompletionMessageDetails = {
+		id: agent.id,
+		status,
+		errorCategory,
+		...(errorMessage ? { errorMessage } : {}),
+		...(costUsd !== undefined ? { costUsd } : {}),
+		...(tokensIn !== undefined ? { tokensIn } : {}),
+		...(tokensOut !== undefined ? { tokensOut } : {}),
+		...(durationMs !== undefined ? { durationMs } : {}),
+		...(label ? { label } : {}),
+	};
+
+	return { customType: "subagent-completion", content, display: true, details };
+}
+
+/**
+ * D1 + D2 matrix — the only knob-dependent logic. Delivery is always-on
+ * (minimum `nextTurn`); the knob controls the WAKE (triggerTurn).
+ */
+export function resolveDelivery(
+	status: CompletionStatus,
+	knob: CompletionNotifyMode,
+): DeliveryResolution {
+	if (status === "completed") {
+		if (knob === "all") return { deliverAs: "followUp", triggerTurn: true };
+		return { deliverAs: "nextTurn", triggerTurn: false }; // knob "failed" | "off"
+	}
+	// status === "failed" | "stopped"
+	if (knob === "off") return { deliverAs: "nextTurn", triggerTurn: false };
+	return { deliverAs: "steer", triggerTurn: true }; // knob "all" | "failed"
+}
+
+/**
+ * Dedupe guard — first terminal event per id wins. Returns true when the event
+ * should be delivered, false when it is a duplicate. Capped simply (W1): the
+ * set is cleared when it exceeds the cap.
+ */
+export function markTerminalSeen(seen: Set<string>, id: string, cap = DEDUPE_CAP): boolean {
+	if (seen.has(id)) return false;
+	seen.add(id);
+	if (seen.size > cap) seen.clear();
+	return true;
+}
+
+/**
+ * THIN sender — the only `pi.sendMessage` call site. One call, no logic.
+ * The `delivery` is the resolved output of `resolveDelivery` (D1+D2); it
+ * carries both `deliverAs` and `triggerTurn` so the matrix is honored.
+ */
+export function sendCompletionNotification(
+	pi: ExtensionAPI,
+	message: CompletionMessagePayload,
+	delivery: DeliveryResolution,
+): void {
+	pi.sendMessage(message, { deliverAs: delivery.deliverAs, triggerTurn: delivery.triggerTurn });
+}

package/src/params.ts

@@ -0,0 +1,225 @@
+/**
+ * brl-subagent — Parameter Resolution (issue #59)
+ *
+ * resolveSubagentParams merges per-call params with the resolved preset,
+ * then applies thinking-level caps, timeout normalization, the edit→write
+ * tool fix, git mode / approval mode resolution, and E2 auto-routing.
+ *
+ * The function used to live as a closure inside src/index.ts's default
+ * export, which forced the integration tests to replicate it — a copy that
+ * silently drifted from the real behavior. Extracted here so the tests can
+ * drive the REAL function (no more silent test drift).
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type {
+	ThinkingLevel,
+	SubagentPreset,
+	GitMode,
+	ApprovalMode,
+	SubagentToolOptions,
+	ResolvedParams,
+} from "./types";
+import { resolveThinkingLevel } from "./types";
+import { getAllPresets, getPreset } from "./presets";
+import { autoRoutePreset } from "./router";
+import { normalizeTimeout } from "./validate";
+import type { SessionState } from "./state";
+import type { Logger } from "./logging";
+
+// ---------------------------------------------------------------------------
+// delegate_task known keys (issue #99)
+// ---------------------------------------------------------------------------
+
+/**
+ * Keys the delegate_task schema declares. TypeBox's Type.Object allows
+ * additional properties by default, so this set is the source of truth for
+ * the unknown-param warn: any received key outside it is silently ignored
+ * by execute and worth a warn.
+ *
+ * Single source of truth (review R1): index.ts imports this instead of
+ * carrying a duplicate, and per-step-model.test.ts ratchets it against the
+ * REAL registered schema (the #108-class drift that #99's fix targeted can
+ * never silently return). Keep in sync with the schema's Type.Object({ ... })
+ * block in index.ts.
+ */
+export const KNOWN_DELEGATE_KEYS = new Set([
+	"task", "systemPrompt", "inheritSystemPrompt", "thinkingLevel",
+	"outputFile", "label", "model", "timeout", "cwd", "tools",
+	"excludeTools", "noBuiltinTools", "preset", "template", "params",
+	"retryRunId", "gitMode", "retryOnTimeout", "approvalMode", "background",
+	"priority", "chain", "tasks", "graph",
+] as const);
+
+/**
+ * Issue #99: warn-worthy unknown keys in a delegate_task params object.
+ * TypeBox's Type.Object allows additional properties by default and pi's
+ * validateToolArguments returns validated args UNCHANGED — so unknown keys
+ * survive to execute and are silently ignored. Comparing received keys
+ * against the schema's known keys converts that silent class into a
+ * visible one (warn-not-reject: never break a delegation).
+ */
+export function findUnknownParams(
+	received: Record<string, unknown>,
+	knownKeys: ReadonlySet<string>,
+): string[] {
+	return Object.keys(received).filter((k) => !knownKeys.has(k));
+}
+
+/**
+ * Issue #108: snapshot the caller's raw delegate_task params onto a run
+ * record's originalParams — single source of truth for the retry merge
+ * (resolveRetryParams). The background and foreground run-record creation
+ * sites previously duplicated this 12-field literal (priority added, issue
+ * #114); a future param added to one and not the other would silently
+ * degrade retries of that path.
+ * NOTE: the schema's `params` (template slots) key is intentionally NOT
+ * snapshotted — it is a template-resolution input, not a retry override.
+ */
+export function snapshotOriginalParams(params: {
+	systemPrompt?: string;
+	inheritSystemPrompt?: boolean;
+	model?: string;
+	thinkingLevel?: string;
+	priority?: string;
+	outputFile?: string;
+	timeout?: number;
+	cwd?: string;
+	tools?: string[];
+	excludeTools?: string[];
+	noBuiltinTools?: boolean;
+	preset?: string;
+}): Record<string, unknown> {
+	return {
+		systemPrompt: params.systemPrompt,
+		inheritSystemPrompt: params.inheritSystemPrompt,
+		model: params.model,
+		thinkingLevel: params.thinkingLevel,
+		priority: params.priority,
+		outputFile: params.outputFile,
+		timeout: params.timeout,
+		cwd: params.cwd,
+		tools: params.tools,
+		excludeTools: params.excludeTools,
+		noBuiltinTools: params.noBuiltinTools,
+		preset: params.preset,
+	};
+}
+
+export function resolveSubagentParams(
+	params: {
+		task: string;
+		label?: string;
+		preset?: string;
+		systemPrompt?: string;
+		inheritSystemPrompt?: boolean;
+		thinkingLevel?: string;
+		outputFile?: string;
+		timeout?: number;
+		cwd?: string;
+		tools?: string[];
+		excludeTools?: string[];
+		noBuiltinTools?: boolean;
+		gitMode?: string;
+		approvalMode?: string;
+		template?: string;
+	},
+	state: SessionState,
+	ctx: ExtensionContext,
+	log: Logger,
+): ResolvedParams & {
+	resolvedGitMode: GitMode;
+	resolvedApprovalMode: ApprovalMode;
+	resolvedPreset?: SubagentPreset;
+	autoRoutedPreset?: SubagentPreset; // set only when autoRoutePreset chose it
+} {
+	// E2: Auto-route to best preset only when the conductor expressed NO
+	// explicit preference — an explicit preset, template, or tool
+	// parameters (tools/excludeTools/noBuiltinTools) all count as intent
+	// that must win over keyword-based routing (issue #57).
+	let resolvedPreset = params.preset;
+	let wasAutoRouted = false;
+	const hasExplicitToolPreference =
+		params.tools !== undefined ||
+		params.excludeTools !== undefined ||
+		params.noBuiltinTools !== undefined;
+	if (!resolvedPreset && !params.template && !hasExplicitToolPreference) {
+		const allPresets = getAllPresets(state.builtinPresets, state.customPresets);
+		const suggested = autoRoutePreset(params.task, allPresets);
+		if (suggested) {
+			resolvedPreset = suggested;
+			wasAutoRouted = true;
+			log.info("Auto-routed task to preset", { preset: suggested });
+		}
+	}
+
+	const preset = resolvedPreset
+		? getPreset(resolvedPreset, state.builtinPresets, state.customPresets)
+		: undefined;
+	const autoRoutedPreset = wasAutoRouted ? preset : undefined;
+
+	const mergedThinkingLevel =
+		(params.thinkingLevel as ThinkingLevel | undefined) ??
+		(preset?.thinkingLevel as ThinkingLevel | undefined);
+	const mergedSystemPrompt = params.systemPrompt ?? preset?.systemPrompt;
+	const mergedInheritSP = params.inheritSystemPrompt ?? preset?.inheritSystemPrompt;
+	const mergedOutputFile = params.outputFile ?? preset?.outputFile;
+	const mergedTimeout = normalizeTimeout(params.timeout ?? preset?.timeout);
+	const mergedTools = params.tools ?? preset?.tools;
+	// Fix: edit depends on write in pi's tool system.
+	// If edit is in the allowlist but write is not, all tools fail to resolve.
+	const resolvedTools = mergedTools && mergedTools.includes("edit") && !mergedTools.includes("write")
+		? [...mergedTools, "write"]
+		: mergedTools;
+	const mergedExcludeTools = params.excludeTools ?? preset?.excludeTools;
+	const mergedNoBuiltinTools = params.noBuiltinTools ?? preset?.noBuiltinTools;
+
+	// QUIRK (pre-existing, preserved from the original closure): gitMode merges
+	// from preset?.NAME, not a preset gitMode field (SubagentPreset has none).
+	// A preset literally named "branch"/"none" would silently set gitMode.
+	// Deliberately NOT changed here — altering it is a behavior change beyond
+	// issue #59's scope.
+	const mergedGitMode = (params.gitMode as GitMode | undefined) ?? preset?.name;
+	const resolvedGitMode: GitMode =
+		mergedGitMode === "branch" || mergedGitMode === "none"
+			? mergedGitMode
+			: state.config.gitMode;
+
+	// P4: Resolve approval mode: per-call param > state config > default "writes"
+	const mergedApprovalMode = params.approvalMode as ApprovalMode | undefined;
+	const resolvedApprovalMode: ApprovalMode =
+		mergedApprovalMode === "auto" || mergedApprovalMode === "writes" || mergedApprovalMode === "always"
+			? mergedApprovalMode
+			: state.config.approvalMode;
+
+	const thinkingLevel = resolveThinkingLevel(
+		mergedThinkingLevel,
+		state.config.maxThinkingLevel,
+	);
+
+	const toolOptions: SubagentToolOptions | undefined =
+		resolvedTools || mergedExcludeTools || mergedNoBuiltinTools
+			? {
+					tools: resolvedTools,
+					excludeTools: mergedExcludeTools,
+					noBuiltinTools: mergedNoBuiltinTools,
+				}
+			: undefined;
+
+	return {
+		task: params.task,
+		label: params.label?.trim() || undefined,
+		inheritSP: mergedInheritSP !== false,
+		customSP: mergedSystemPrompt,
+		outputFile: mergedOutputFile,
+		timeout: mergedTimeout,
+		effectiveCwd: params.cwd || ctx.cwd,
+		thinkingLevel,
+		toolOptions,
+		resolvedGitMode,
+		resolvedApprovalMode,
+		resolvedPreset: preset,
+		autoRoutedPreset,
+	};
+}

package/src/preflight.ts

@@ -0,0 +1,150 @@
+/**
+ * brl-subagent — Pre-flight Checks (R3)
+ *
+ * Validates the execution environment before spawning a subagent.
+ * Checks: pi binary availability, temp directory writability,
+ * and project cwd readability.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getPiInvocation } from "./runner";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type PreflightResult = { ok: true } | { ok: false; error: string };
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify the pi binary is accessible via the same resolution logic used
+ * at spawn time. When `getPiInvocation` falls back to "pi" on PATH, we
+ * walk PATH to confirm the binary exists. For absolute paths (e.g.
+ * process.execPath), we verify the file is executable.
+ */
+function checkPiBinary(): PreflightResult {
+	const { command } = getPiInvocation([]);
+
+	if (command !== "pi") {
+		// Absolute or relative path — verify it exists
+		try {
+			fs.accessSync(command, fs.constants.X_OK);
+			return { ok: true };
+		} catch {
+			return {
+				ok: false,
+				error: `Subagent command '${command}' is not accessible or not executable.`,
+			};
+		}
+	}
+
+	// "pi" fallback — search PATH
+	const pathDirs = (process.env.PATH || "").split(path.delimiter);
+	const isWindows = process.platform === "win32";
+	const piNames = isWindows ? ["pi.cmd", "pi.exe", "pi"] : ["pi"];
+
+	for (const dir of pathDirs) {
+		for (const name of piNames) {
+			const fullPath = path.join(dir, name);
+			try {
+				fs.accessSync(fullPath, fs.constants.X_OK);
+				return { ok: true };
+			} catch {
+				// Not found in this directory — continue searching
+			}
+		}
+	}
+
+	return {
+		ok: false,
+		error:
+			"pi binary not found in PATH. " +
+			"Ensure pi is installed and accessible from the command line.",
+	};
+}
+
+/**
+ * Verify the project working directory exists and is readable.
+ */
+function checkCwdReadable(cwd: string): PreflightResult {
+	try {
+		fs.accessSync(cwd, fs.constants.R_OK);
+	} catch {
+		return {
+			ok: false,
+			error: `Project working directory is not readable: ${cwd}. ` +
+				"Check that the directory exists and has read permissions.",
+		};
+	}
+
+	// Double-check it's actually a directory
+	try {
+		const stat = fs.statSync(cwd);
+		if (!stat.isDirectory()) {
+			return {
+				ok: false,
+				error: `Project working directory is not a directory: ${cwd}.`,
+			};
+		}
+	} catch {
+		return {
+			ok: false,
+			error: `Cannot stat project working directory: ${cwd}.`,
+		};
+	}
+
+	return { ok: true };
+}
+
+/**
+ * Verify the system temp directory is writable by creating and
+ * removing a small temporary file.
+ */
+function checkTempWritable(): PreflightResult {
+	const tmpDir = os.tmpdir();
+	const testFile = path.join(tmpDir, `.brl-subagent-pcheck-${process.pid}`);
+
+	try {
+		fs.writeFileSync(testFile, "ok", { encoding: "utf-8", mode: 0o600 });
+		fs.unlinkSync(testFile);
+		return { ok: true };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return {
+			ok: false,
+			error: `System temp directory (${tmpDir}) is not writable: ${message}. ` +
+				"Set TMPDIR or TEMP to a writable directory.",
+		};
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run all pre-flight checks for subagent execution.
+ * Returns `{ ok: true }` if all checks pass,
+ * or `{ ok: false, error: "..." }` with a human-readable description
+ * of the first failure.
+ *
+ * Call this BEFORE acquiring a concurrency slot to avoid wasting
+ * resources on a doomed spawn.
+ */
+export function preflightCheck(cwd: string): PreflightResult {
+	const piResult = checkPiBinary();
+	if (!piResult.ok) return piResult;
+
+	const cwdResult = checkCwdReadable(cwd);
+	if (!cwdResult.ok) return cwdResult;
+
+	const tempResult = checkTempWritable();
+	if (!tempResult.ok) return tempResult;
+
+	return { ok: true };
+}