pi-subagents 0.34.0 → 0.35.0

package/src/watchdog/turn-delta.ts

@@ -0,0 +1,161 @@
+import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "./types.ts";
+
+type MessageLike = {
+	role?: string;
+	content?: unknown;
+	customType?: string;
+	toolName?: string;
+	name?: string;
+	input?: unknown;
+	args?: unknown;
+	arguments?: unknown;
+	error?: unknown;
+	isError?: boolean;
+	details?: unknown;
+	stopReason?: string;
+};
+
+export interface WatchdogTurnDeltaInput {
+	userPrompt?: string;
+	includeUserPrompt?: boolean;
+	messages?: unknown[];
+	events?: unknown[];
+	finalAssistantStop?: boolean;
+}
+
+function textFromContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		return content.map((block) => {
+			if (typeof block === "string") return block;
+			if (block && typeof block === "object") {
+				const item = block as { type?: string; text?: unknown; thinking?: unknown; content?: unknown; name?: unknown; input?: unknown; args?: unknown; arguments?: unknown };
+				if (item.type === "text" && typeof item.text === "string") return item.text;
+				if (item.type === "thinking" && typeof item.thinking === "string") return ["Thinking:", item.thinking].join("\n");
+				if (item.type === "toolCall") return formatToolCall(item.name, item.input ?? item.args ?? item.arguments);
+				if (typeof item.content === "string") return item.content;
+			}
+			return "";
+		}).filter(Boolean).join("\n");
+	}
+	if (content === undefined || content === null) return "";
+	return formatValue(content);
+}
+
+function formatValue(value: unknown, indent = ""): string {
+	if (typeof value === "string") return value;
+	if (value === undefined) return "undefined";
+	if (value === null || typeof value === "number" || typeof value === "boolean") return JSON.stringify(value);
+	if (Array.isArray(value)) {
+		return value.map((item, index) => `${indent}- ${formatValue(item, `${indent}  `)}`).join("\n");
+	}
+	if (typeof value === "object") {
+		const lines: string[] = [];
+		for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+			if (typeof item === "string" && item.includes("\n")) lines.push(`${indent}${key}:\n${item}`);
+			else lines.push(`${indent}${key}: ${formatValue(item, `${indent}  `)}`);
+		}
+		return lines.join("\n");
+	}
+	return String(value);
+}
+
+function redactEditWriteInput(input: unknown): unknown {
+	if (Array.isArray(input)) return input.map(redactEditWriteInput);
+	if (!input || typeof input !== "object") return input;
+	const sanitized: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
+		sanitized[key] = ["oldText", "newText", "content"].includes(key) && typeof value === "string"
+			? `[omitted ${value.length} chars; use tool result diff]`
+			: redactEditWriteInput(value);
+	}
+	return sanitized;
+}
+
+function formatToolArguments(name: string, input: unknown): string {
+	if (name === "edit" || name === "write") return formatValue(redactEditWriteInput(input));
+	return formatValue(input);
+}
+
+function formatToolCall(name: unknown, input: unknown): string {
+	const toolName = typeof name === "string" && name ? name : "tool";
+	return [`Tool call: ${toolName}`, "Arguments:", formatToolArguments(toolName, input ?? {})].join("\n");
+}
+
+function formatToolResult(name: string, content: unknown, details: unknown, error: unknown, isError: boolean | undefined): string {
+	const failed = isError === true || Boolean(error);
+	const lines = [`Tool result: ${name}`];
+	if (failed) lines.push(`Error: ${error ? (typeof error === "string" ? error : formatValue(error)) : "tool reported an error"}`);
+	if (!failed && details && typeof details === "object" && "diff" in details && typeof (details as { diff?: unknown }).diff === "string") {
+		lines.push("Diff:", (details as { diff: string }).diff);
+	} else {
+		const body = textFromContent(content);
+		if (body) lines.push(failed ? "Output:" : "Result:", body);
+	}
+	return lines.join("\n");
+}
+
+function messagesFromEvent(event: unknown): unknown[] {
+	if (!event || typeof event !== "object") return [];
+	const input = event as Record<string, unknown>;
+	if (input.type === "turn_end" || input.event === "turn_end") {
+		return [input.message, ...(Array.isArray(input.toolResults) ? input.toolResults : [])].filter(Boolean);
+	}
+	if (input.message) return [input.message];
+	if (input.type === "tool_execution_start" || input.event === "tool_execution_start") {
+		return [{ role: "toolCall", name: input.toolName ?? input.name, input: input.args ?? input.input }];
+	}
+	if (input.type === "tool_execution_end" || input.event === "tool_execution_end") {
+		const result = input.result && typeof input.result === "object" && !Array.isArray(input.result) ? input.result as Record<string, unknown> : undefined;
+		return [{
+			role: "toolResult",
+			toolName: input.toolName ?? input.name,
+			content: result?.content ?? input.content ?? input.result,
+			details: result?.details ?? input.details,
+			error: input.error,
+			isError: input.isError,
+		}];
+	}
+	if (input.type === "tool_result" || input.event === "tool_result") {
+		return [{ role: "toolResult", toolName: input.toolName ?? input.name, content: input.content, details: input.details, error: input.error, isError: input.isError }];
+	}
+	return [];
+}
+
+export function formatWatchdogReviewMessage(message: unknown): string | undefined {
+	if (!message || typeof message !== "object") return undefined;
+	const input = message as MessageLike;
+	if (input.role === "custom" && input.customType === SUBAGENT_WATCHDOG_WARNING_TYPE) return undefined;
+	if (input.role === "assistant") {
+		const text = textFromContent(input.content);
+		const lines = text ? ["Assistant:", text] : ["Assistant: (no text)"];
+		if (input.stopReason === "stop") lines.push("Assistant stop: stop");
+		return lines.join("\n");
+	}
+	if (input.role === "toolCall") return formatToolCall(input.name ?? input.toolName, input.input ?? input.args ?? input.arguments);
+	if (input.role === "toolResult" || input.role === "tool") {
+		return formatToolResult(input.toolName ?? input.name ?? "tool", input.content, input.details, input.error, input.isError);
+	}
+	if (input.role === "user") {
+		const text = textFromContent(input.content);
+		return text ? ["User:", text].join("\n") : undefined;
+	}
+	return undefined;
+}
+
+export function formatWatchdogTurnDelta(input: WatchdogTurnDeltaInput): string {
+	const sections: string[] = [];
+	if (input.includeUserPrompt && input.userPrompt?.trim()) sections.push(["User prompt:", input.userPrompt].join("\n"));
+	for (const message of input.messages ?? []) {
+		const section = formatWatchdogReviewMessage(message);
+		if (section) sections.push(section);
+	}
+	for (const event of input.events ?? []) {
+		for (const message of messagesFromEvent(event)) {
+			const section = formatWatchdogReviewMessage(message);
+			if (section) sections.push(section);
+		}
+	}
+	if (input.finalAssistantStop) sections.push("Final assistant stop: stop without tool call");
+	return sections.join("\n\n---\n\n");
+}

package/src/watchdog/types.ts

@@ -0,0 +1,188 @@
+export const SUBAGENT_WATCHDOG_WARNING_TYPE = "subagent_watchdog_warning";
+
+export const WATCHDOG_WARNING_SEVERITIES = ["concern", "blocker"] as const;
+export type WatchdogSeverity = typeof WATCHDOG_WARNING_SEVERITIES[number];
+
+export const WATCHDOG_WARNING_CATEGORIES = [
+	"correctness",
+	"missed-constraint",
+	"test-gap",
+	"unsafe-change",
+	"scope-drift",
+	"stale-fact",
+	"loop-risk",
+	"other",
+] as const;
+export type WatchdogCategory = typeof WATCHDOG_WARNING_CATEGORIES[number];
+
+export const WATCHDOG_WARNING_CONFIDENCES = ["medium", "high"] as const;
+export type WatchdogConfidence = typeof WATCHDOG_WARNING_CONFIDENCES[number];
+
+export const WATCHDOG_WARNING_SOURCES = ["main", "child", "async-completion", "lsp"] as const;
+export type WatchdogWarningSource = typeof WATCHDOG_WARNING_SOURCES[number];
+
+export const WATCHDOG_LSP_DIAGNOSTIC_SEVERITIES = ["error", "warning", "info", "hint"] as const;
+export type WatchdogLspDiagnosticSeverity = typeof WATCHDOG_LSP_DIAGNOSTIC_SEVERITIES[number];
+
+export const WATCHDOG_LSP_STATUSES = ["disabled", "ok", "skipped", "unavailable", "timeout", "failed"] as const;
+export type WatchdogLspStatus = typeof WATCHDOG_LSP_STATUSES[number];
+
+export const WATCHDOG_RUNTIME_STATUSES = ["idle", "queued", "reviewing", "waiting-at-agent-end", "stale", "failed"] as const;
+export type WatchdogRuntimeStatus = typeof WATCHDOG_RUNTIME_STATUSES[number];
+
+export const WATCHDOG_WARNING_STATES = [
+	"candidate",
+	"confirmed",
+	"displayed",
+	"stale",
+	"failed",
+	"resolved",
+	"stalemate",
+	"suppressed",
+] as const;
+export type WatchdogWarningState = typeof WATCHDOG_WARNING_STATES[number];
+
+export const WATCHDOG_LATE_WARNING_POLICIES = ["show-stale-no-autofollow"] as const;
+export type WatchdogLateWarningPolicy = typeof WATCHDOG_LATE_WARNING_POLICIES[number];
+
+export const WATCHDOG_DELIVERY_MODES = ["held"] as const;
+export type WatchdogDeliveryMode = typeof WATCHDOG_DELIVERY_MODES[number];
+
+export type WatchdogSyncBacklog = "off" | number;
+
+export interface WatchdogWarning {
+	severity: WatchdogSeverity;
+	summary: string;
+	evidence: string;
+	recommendedAction: string;
+	category?: WatchdogCategory;
+	confidence?: WatchdogConfidence;
+	source?: WatchdogWarningSource;
+	agent?: string;
+	runId?: string;
+	stale?: boolean;
+	autoFollowAttempt?: number;
+	state?: WatchdogWarningState;
+}
+
+export interface WatchdogWarningDetails extends WatchdogWarning {
+	category: WatchdogCategory;
+	source: WatchdogWarningSource;
+	identity?: string;
+	displayedAt?: string;
+	error?: string;
+	stalemateRepeats?: number;
+}
+
+export interface WatchdogWarningMessage {
+	customType: typeof SUBAGENT_WATCHDOG_WARNING_TYPE;
+	content: string;
+	display: boolean;
+	details: WatchdogWarningDetails;
+}
+
+export interface WatchdogAutoFollowConfig {
+	blockers: boolean;
+	maxAttempts: number | null;
+	stalemateRepeats: number;
+}
+
+export interface WatchdogGuidanceConfig {
+	watchdogMd: boolean;
+	systemPromptPath: string | null;
+}
+
+export interface WatchdogEndpointConfig {
+	enabled: boolean;
+	model?: string;
+	thinking?: string | false;
+}
+
+export interface WatchdogChildOverrideConfig {
+	enabled?: boolean;
+	model?: string;
+	thinking?: string | false;
+}
+
+export interface WatchdogChildrenConfig extends WatchdogEndpointConfig {
+	watchdogTailTimeoutMs: number;
+	autoFollow: WatchdogAutoFollowConfig;
+	overrides: Record<string, WatchdogChildOverrideConfig>;
+}
+
+export interface WatchdogAsyncCompletionConfig {
+	enabled: boolean;
+	autoFollowBlockers: boolean;
+}
+
+export interface WatchdogLspConfig {
+	enabled: boolean;
+	timeoutMs: number;
+	maxFiles: number;
+	maxDiagnostics: number;
+}
+
+export interface WatchdogLspDiagnostic {
+	path: string;
+	line: number;
+	column: number;
+	severity: WatchdogLspDiagnosticSeverity;
+	source: string;
+	code?: string;
+	message: string;
+}
+
+export interface WatchdogLspResult {
+	status: WatchdogLspStatus;
+	provider?: string;
+	checkedPaths: string[];
+	skippedPaths: string[];
+	diagnostics: WatchdogLspDiagnostic[];
+	message?: string;
+}
+
+export interface WatchdogLspRuntimeSnapshot extends WatchdogLspResult {
+	enabled: boolean;
+	diagnosticCount: number;
+	freshDiagnosticCount: number;
+	updatedAt?: string;
+}
+
+export interface ResolvedWatchdogConfig {
+	enabled: boolean;
+	delivery: WatchdogDeliveryMode;
+	showDuringRun: boolean;
+	syncBacklog: WatchdogSyncBacklog;
+	agentEndTimeoutMs: number;
+	lateWarningPolicy: WatchdogLateWarningPolicy;
+	severityThreshold: WatchdogSeverity;
+	maxWarnings: number | null;
+	guidance: WatchdogGuidanceConfig;
+	autoFollow: WatchdogAutoFollowConfig;
+	main: WatchdogEndpointConfig;
+	children: WatchdogChildrenConfig;
+	asyncCompletion: WatchdogAsyncCompletionConfig;
+	lsp: WatchdogLspConfig;
+	compactAtPercent: number;
+	reviewRetryDelayMs: number;
+	maxReviewFailures: number;
+}
+
+export interface WatchdogSettingsError {
+	scope: "user" | "project" | "session";
+	path?: string;
+	message: string;
+}
+
+export interface WatchdogSettingsSource {
+	scope: "user" | "project" | "session";
+	path?: string;
+	exists: boolean;
+}
+
+export interface WatchdogSettingsResult {
+	ok: boolean;
+	config: ResolvedWatchdogConfig;
+	errors: WatchdogSettingsError[];
+	sources: WatchdogSettingsSource[];
+}

package/src/watchdog/warning-format.ts

@@ -0,0 +1,73 @@
+import {
+	SUBAGENT_WATCHDOG_WARNING_TYPE,
+	type WatchdogWarning,
+	type WatchdogWarningDetails,
+	type WatchdogWarningMessage,
+} from "./types.ts";
+
+function escapeXmlText(value: string): string {
+	return value
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+function escapeXmlAttribute(value: string): string {
+	return escapeXmlText(value).replace(/"/g, "&quot;");
+}
+
+function tag(name: string, value: string | number | boolean | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	return `<${name}>${escapeXmlText(String(value))}</${name}>`;
+}
+
+export function normalizeWatchdogWarningDetails(warning: WatchdogWarning, extras: Partial<WatchdogWarningDetails> = {}): WatchdogWarningDetails {
+	return {
+		...warning,
+		category: warning.category ?? extras.category ?? "other",
+		source: warning.source ?? extras.source ?? "main",
+		...extras,
+	};
+}
+
+export function formatWatchdogWarningContent(warning: WatchdogWarning): string {
+	const details = normalizeWatchdogWarningDetails(warning);
+	const attrs = [
+		`severity="${escapeXmlAttribute(details.severity)}"`,
+		`category="${escapeXmlAttribute(details.category)}"`,
+		`source="${escapeXmlAttribute(details.source)}"`,
+		`guidance="weigh, don't blindly obey"`,
+	];
+	const optionalTags = [
+		tag("confidence", details.confidence),
+		tag("agent", details.agent),
+		tag("run_id", details.runId),
+		tag("state", details.state),
+		tag("stale", details.stale),
+		tag("auto_follow_attempt", details.autoFollowAttempt),
+	];
+	return [
+		`<subagent_watchdog ${attrs.join(" ")}>`,
+		`<summary>${escapeXmlText(details.summary)}</summary>`,
+		`<evidence>${escapeXmlText(details.evidence)}</evidence>`,
+		`<recommended_action>${escapeXmlText(details.recommendedAction)}</recommended_action>`,
+		...optionalTags.filter((line): line is string => Boolean(line)),
+		details.severity === "blocker"
+			? "<blocker_guidance>If this warning changes the outcome, produce a new self-contained final answer after addressing it.</blocker_guidance>"
+			: undefined,
+		"</subagent_watchdog>",
+	].filter((line): line is string => Boolean(line)).join("\n");
+}
+
+export function createWatchdogWarningMessage(
+	warning: WatchdogWarning,
+	options: { display?: boolean; details?: Partial<WatchdogWarningDetails> } = {},
+): WatchdogWarningMessage {
+	const details = normalizeWatchdogWarningDetails(warning, options.details);
+	return {
+		customType: SUBAGENT_WATCHDOG_WARNING_TYPE,
+		content: formatWatchdogWarningContent(details),
+		display: options.display ?? true,
+		details,
+	};
+}