@kodrunhq/opencode-autopilot 1.3.0 → 1.4.0

package/src/tools/mock-fallback.ts

@@ -0,0 +1,100 @@
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+import { createMockError } from "../observability/mock/mock-provider";
+import type { MockFailureMode } from "../observability/mock/types";
+import { FAILURE_MODES } from "../observability/mock/types";
+import { classifyErrorType, isRetryableError } from "../orchestrator/fallback/error-classifier";
+
+/**
+ * Default retryable status codes matching the standard fallback config.
+ */
+const DEFAULT_RETRY_CODES: readonly number[] = Object.freeze([429, 503, 529]);
+
+/**
+ * Human-readable descriptions for each failure mode.
+ */
+const MODE_DESCRIPTIONS: Readonly<Record<MockFailureMode, string>> = Object.freeze({
+	rate_limit: "Simulates HTTP 429 rate limit response",
+	quota_exceeded: "Simulates HTTP 402 quota/billing error",
+	timeout: "Simulates HTTP 504 gateway timeout (classifies as service_unavailable)",
+	malformed: "Simulates unparseable/corrupt response (not retryable)",
+	service_unavailable: "Simulates HTTP 503 service outage",
+});
+
+/**
+ * Core function for mock fallback testing tool.
+ * Follows the *Core + tool() wrapper pattern per CLAUDE.md.
+ *
+ * - "list" mode returns all available failure modes with descriptions
+ * - Any valid failure mode generates and classifies the mock error
+ * - Invalid modes return an error JSON
+ *
+ * This tool does NOT trigger fallback in a live session. It generates and
+ * classifies errors, showing what the fallback system would see.
+ */
+export async function mockFallbackCore(mode: string): Promise<string> {
+	if (mode === "list") {
+		const modeLines = FAILURE_MODES.map((m) => `  ${m}: ${MODE_DESCRIPTIONS[m]}`).join("\n");
+
+		return JSON.stringify({
+			action: "mock_fallback_list",
+			modes: [...FAILURE_MODES],
+			displayText: `Available failure modes:\n${modeLines}`,
+		});
+	}
+
+	// Validate mode
+	if (!FAILURE_MODES.includes(mode as MockFailureMode)) {
+		return JSON.stringify({
+			action: "error",
+			message: "Invalid failure mode. Use 'list' to see available modes.",
+		});
+	}
+
+	const failureMode = mode as MockFailureMode;
+	const error = createMockError(failureMode);
+	const classification = classifyErrorType(error);
+	const retryable = isRetryableError(error, DEFAULT_RETRY_CODES);
+
+	// Extract error fields for the response
+	const errorObj = error as Record<string, unknown>;
+	const errorSummary: Record<string, unknown> = {
+		name: errorObj.name,
+		message: errorObj.message,
+	};
+	if (errorObj.status !== undefined) {
+		errorSummary.status = errorObj.status;
+	}
+
+	const displayText = [
+		`Mock ${failureMode} error generated.`,
+		`Classification: ${classification}`,
+		`Retryable: ${retryable}`,
+		"",
+		"To test fallback chain: inject this error into FallbackManager.handleError() in a test,",
+		"or use oc_mock_fallback in a session to verify error classification behavior.",
+	].join("\n");
+
+	return JSON.stringify({
+		action: "mock_fallback",
+		mode: failureMode,
+		error: errorSummary,
+		classification,
+		retryable,
+		displayText,
+	});
+}
+
+// --- Tool wrapper ---
+
+export const ocMockFallback = tool({
+	description:
+		"Generate mock errors for fallback chain testing. " +
+		"Use 'list' to see available failure modes.",
+	args: {
+		mode: z.string().describe("Failure mode to simulate or 'list' for available modes"),
+	},
+	async execute({ mode }) {
+		return mockFallbackCore(mode);
+	},
+});

package/src/tools/pipeline-report.ts

@@ -0,0 +1,148 @@
+/**
+ * oc_pipeline_report tool - Decision trace with phase-by-phase breakdown.
+ *
+ * Reads a session log and produces a read-only report showing:
+ * - Phase-by-phase decision timeline
+ * - Per-phase decision count
+ * - Decisions with agent and rationale context
+ *
+ * Follows the *Core + tool() wrapper pattern per CLAUDE.md.
+ * Returns JSON with displayText field following oc_doctor pattern.
+ *
+ * @module
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+import { readLatestSessionLog, readSessionLog } from "../observability/log-reader";
+import { computeDuration, formatDuration } from "../observability/summary-generator";
+import type { SessionLog } from "../observability/types";
+
+/**
+ * A decision entry within a phase section of the report.
+ */
+interface ReportDecision {
+	readonly agent: string;
+	readonly decision: string;
+	readonly rationale: string;
+}
+
+/**
+ * A phase section in the pipeline report.
+ */
+interface ReportPhase {
+	readonly phase: string;
+	readonly decisions: readonly ReportDecision[];
+}
+
+/**
+ * Groups decisions by phase, preserving insertion order.
+ */
+function groupDecisionsByPhase(log: SessionLog): readonly ReportPhase[] {
+	const phaseOrder: string[] = [];
+	const phaseMap = new Map<string, ReportDecision[]>();
+
+	for (const d of log.decisions) {
+		if (!phaseMap.has(d.phase)) {
+			phaseOrder.push(d.phase);
+			phaseMap.set(d.phase, []);
+		}
+		const decisions = phaseMap.get(d.phase);
+		decisions?.push({
+			agent: d.agent,
+			decision: d.decision,
+			rationale: d.rationale,
+		});
+	}
+
+	return phaseOrder.map((phase) => ({
+		phase,
+		decisions: phaseMap.get(phase) ?? [],
+	}));
+}
+
+/**
+ * Builds the displayText report for the pipeline report.
+ */
+function buildDisplayText(
+	log: SessionLog,
+	phases: readonly ReportPhase[],
+	durationMs: number,
+): string {
+	const lines: string[] = [];
+
+	// Header
+	const durationStr = log.endedAt ? formatDuration(durationMs) : "In progress";
+	lines.push(`Pipeline Report: ${log.sessionId}`);
+	lines.push(`Duration: ${durationStr}`);
+	lines.push(`Total Decisions: ${log.decisions.length}`);
+	lines.push("");
+
+	if (phases.length === 0) {
+		lines.push("No decisions recorded in this session.");
+		return lines.join("\n");
+	}
+
+	// Phase-by-phase breakdown
+	for (const phase of phases) {
+		lines.push(`--- ${phase.phase} (${phase.decisions.length} decision(s)) ---`);
+		for (const d of phase.decisions) {
+			lines.push(`  [${d.agent}] ${d.decision}`);
+			lines.push(`    Rationale: ${d.rationale}`);
+		}
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Core function for the oc_pipeline_report tool.
+ *
+ * @param sessionID - Optional session ID (uses latest if omitted)
+ * @param logsDir - Optional override for logs directory (for testing)
+ */
+export async function pipelineReportCore(sessionID?: string, logsDir?: string): Promise<string> {
+	const log = sessionID
+		? await readSessionLog(sessionID, logsDir)
+		: await readLatestSessionLog(logsDir);
+
+	if (!log) {
+		const target = sessionID ? `Session "${sessionID}" not found.` : "No session logs found.";
+		return JSON.stringify({
+			action: "error",
+			message: target,
+		});
+	}
+
+	const durationMs = computeDuration(log);
+	const phases = groupDecisionsByPhase(log);
+	const totalDecisions = log.decisions.length;
+	const displayText = buildDisplayText(log, phases, durationMs);
+
+	return JSON.stringify({
+		action: "pipeline_report",
+		sessionId: log.sessionId,
+		phases,
+		totalDecisions,
+		displayText,
+	});
+}
+
+// --- Tool wrapper ---
+
+export const ocPipelineReport = tool({
+	description:
+		"View pipeline decision trace. Shows phase-by-phase breakdown of all autonomous decisions " +
+		"with agent and rationale. Read-only report for post-session analysis.",
+	args: {
+		sessionID: z
+			.string()
+			.regex(/^[a-zA-Z0-9_-]{1,256}$/)
+			.optional()
+			.describe("Session ID to view (uses latest if omitted)"),
+	},
+	async execute({ sessionID }) {
+		return pipelineReportCore(sessionID);
+	},
+});

package/src/tools/session-stats.ts

@@ -0,0 +1,185 @@
+/**
+ * oc_session_stats tool - Event counts, decisions, errors, and per-phase breakdown.
+ *
+ * Reads a session log and computes:
+ * - Event count totals
+ * - Decision count and per-phase grouping
+ * - Error summary by type with per-phase attribution
+ * - Session duration
+ * - Per-phase breakdown (when decisions span multiple phases)
+ *
+ * Follows the *Core + tool() wrapper pattern per CLAUDE.md.
+ * Returns JSON with displayText field following oc_doctor pattern.
+ *
+ * @module
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+import { readLatestSessionLog, readSessionLog } from "../observability/log-reader";
+import { computeDuration, formatDuration } from "../observability/summary-generator";
+import type { SessionLog } from "../observability/types";
+
+/**
+ * Per-phase breakdown entry.
+ */
+interface PhaseBreakdownEntry {
+	readonly phase: string;
+	readonly decisionCount: number;
+	readonly errorCount: number;
+}
+
+/**
+ * Computes per-phase breakdown from session log decisions and events.
+ * Groups decisions by phase and counts errors per phase time window.
+ *
+ * Error-to-phase mapping: for each error event, find the phase whose
+ * decision time window (first to last decision timestamp) contains the
+ * error timestamp. Unmatched errors are not attributed to any phase
+ * (they still appear in the overall errorSummary).
+ */
+function computePhaseBreakdown(log: SessionLog): readonly PhaseBreakdownEntry[] {
+	const phaseMap = new Map<string, { decisions: number; errors: number }>();
+
+	// Collect per-phase time windows from decisions
+	const phaseWindows = new Map<string, { start: string; end: string }>();
+
+	for (const d of log.decisions) {
+		const existing = phaseMap.get(d.phase) ?? { decisions: 0, errors: 0 };
+		phaseMap.set(d.phase, { ...existing, decisions: existing.decisions + 1 });
+
+		const ts = d.timestamp ?? "";
+		if (!ts) continue; // Skip decisions without timestamps — cannot build time windows
+		const window = phaseWindows.get(d.phase);
+		if (!window) {
+			phaseWindows.set(d.phase, { start: ts, end: ts });
+		} else {
+			if (ts < window.start) phaseWindows.set(d.phase, { ...window, start: ts });
+			if (ts > window.end) phaseWindows.set(d.phase, { ...window, end: ts });
+		}
+	}
+
+	// Map errors to phases by timestamp overlap with phase time windows
+	for (const e of log.events) {
+		if (e.type === "error") {
+			for (const [phase, window] of phaseWindows) {
+				if (e.timestamp >= window.start && e.timestamp <= window.end) {
+					const data = phaseMap.get(phase);
+					if (data) {
+						phaseMap.set(phase, { ...data, errors: data.errors + 1 });
+					}
+					break;
+				}
+			}
+		}
+	}
+
+	const result: PhaseBreakdownEntry[] = [];
+	for (const [phase, data] of phaseMap) {
+		result.push({
+			phase,
+			decisionCount: data.decisions,
+			errorCount: data.errors,
+		});
+	}
+
+	return result;
+}
+
+/**
+ * Builds the displayText report for session stats.
+ */
+function buildDisplayText(
+	log: SessionLog,
+	durationMs: number,
+	phaseBreakdown: readonly PhaseBreakdownEntry[],
+): string {
+	const lines: string[] = [];
+
+	// Header
+	lines.push(`Session Stats: ${log.sessionId}`);
+	lines.push("");
+
+	// Duration
+	const durationStr = log.endedAt ? formatDuration(durationMs) : "In progress";
+	lines.push(`Duration: ${durationStr}`);
+	lines.push(`Events: ${log.events.length}`);
+	lines.push(`Decisions: ${log.decisions.length}`);
+	lines.push("");
+
+	// Error summary
+	const errorEntries = Object.entries(log.errorSummary);
+	if (errorEntries.length > 0) {
+		lines.push("Error Summary:");
+		for (const [type, count] of errorEntries) {
+			lines.push(`  ${type}: ${count}`);
+		}
+		lines.push("");
+	}
+
+	// Per-phase breakdown (when phases exist)
+	if (phaseBreakdown.length > 0) {
+		lines.push("Phase Breakdown:");
+		lines.push("| Phase | Decisions | Errors |");
+		lines.push("|-------|-----------|--------|");
+		for (const p of phaseBreakdown) {
+			lines.push(`| ${p.phase} | ${p.decisionCount} | ${p.errorCount} |`);
+		}
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Core function for the oc_session_stats tool.
+ *
+ * @param sessionID - Optional session ID (uses latest if omitted)
+ * @param logsDir - Optional override for logs directory (for testing)
+ */
+export async function sessionStatsCore(sessionID?: string, logsDir?: string): Promise<string> {
+	const log = sessionID
+		? await readSessionLog(sessionID, logsDir)
+		: await readLatestSessionLog(logsDir);
+
+	if (!log) {
+		const target = sessionID ? `Session "${sessionID}" not found.` : "No session logs found.";
+		return JSON.stringify({
+			action: "error",
+			message: target,
+		});
+	}
+
+	const durationMs = computeDuration(log);
+	const phaseBreakdown = computePhaseBreakdown(log);
+	const displayText = buildDisplayText(log, durationMs, phaseBreakdown);
+
+	return JSON.stringify({
+		action: "session_stats",
+		sessionId: log.sessionId,
+		duration: durationMs,
+		eventCount: log.events.length,
+		decisionCount: log.decisions.length,
+		errorSummary: log.errorSummary,
+		phaseBreakdown,
+		displayText,
+	});
+}
+
+// --- Tool wrapper ---
+
+export const ocSessionStats = tool({
+	description:
+		"View session statistics including event counts, decisions, errors, and per-phase breakdown. " +
+		"Shows duration, error summary, and phase-by-phase activity.",
+	args: {
+		sessionID: z
+			.string()
+			.regex(/^[a-zA-Z0-9_-]{1,256}$/)
+			.optional()
+			.describe("Session ID to view (uses latest if omitted)"),
+	},
+	async execute({ sessionID }) {
+		return sessionStatsCore(sessionID);
+	},
+});