@kodrunhq/opencode-autopilot 1.3.0 → 1.4.0

package/src/observability/event-store.ts

@@ -0,0 +1,226 @@
+/**
+ * In-memory session event store for observability data.
+ *
+ * Accumulates events, tokens, and tool metrics per session.
+ * Data is flushed to disk by the event handler layer on session end.
+ *
+ * @module
+ */
+
+import type { TokenAggregate } from "./token-tracker";
+import { accumulateTokens, createEmptyTokenAggregate } from "./token-tracker";
+
+/**
+ * Unified event type for the in-memory store.
+ * Extends the Plan 01 SessionEvent types with additional observability events.
+ */
+export type ObservabilityEvent =
+	| {
+			readonly type: "fallback";
+			readonly timestamp: string;
+			readonly sessionId: string;
+			readonly failedModel: string;
+			readonly nextModel: string;
+			readonly reason: string;
+			readonly success: boolean;
+	  }
+	| {
+			readonly type: "error";
+			readonly timestamp: string;
+			readonly sessionId: string;
+			readonly errorType:
+				| "rate_limit"
+				| "quota_exceeded"
+				| "service_unavailable"
+				| "missing_api_key"
+				| "model_not_found"
+				| "content_filter"
+				| "context_length"
+				| "unknown";
+			readonly message: string;
+			readonly model: string;
+			readonly statusCode?: number;
+	  }
+	| {
+			readonly type: "decision";
+			readonly timestamp: string;
+			readonly sessionId: string;
+			readonly phase: string;
+			readonly agent: string;
+			readonly decision: string;
+			readonly rationale: string;
+	  }
+	| {
+			readonly type: "model_switch";
+			readonly timestamp: string;
+			readonly sessionId: string;
+			readonly fromModel: string;
+			readonly toModel: string;
+			readonly trigger: "fallback" | "config" | "user";
+	  }
+	| {
+			readonly type: "context_warning";
+			readonly timestamp: string;
+			readonly sessionId: string;
+			readonly utilization: number;
+			readonly contextLimit: number;
+			readonly inputTokens: number;
+	  }
+	| {
+			readonly type: "tool_complete";
+			readonly timestamp: string;
+			readonly sessionId: string;
+			readonly tool: string;
+			readonly durationMs: number;
+			readonly success: boolean;
+	  }
+	| {
+			readonly type: "phase_transition";
+			readonly timestamp: string;
+			readonly sessionId: string;
+			readonly fromPhase: string;
+			readonly toPhase: string;
+	  }
+	| { readonly type: "session_start"; readonly timestamp: string; readonly sessionId: string }
+	| {
+			readonly type: "session_end";
+			readonly timestamp: string;
+			readonly sessionId: string;
+			readonly durationMs: number;
+			readonly totalCost: number;
+	  };
+
+/**
+ * Per-tool execution metrics accumulated during a session.
+ */
+export interface ToolMetrics {
+	readonly invocations: number;
+	readonly totalDurationMs: number;
+	readonly successes: number;
+	readonly failures: number;
+}
+
+/**
+ * All collected data for a single session.
+ */
+export interface SessionEvents {
+	readonly sessionId: string;
+	readonly events: readonly ObservabilityEvent[];
+	readonly tokens: TokenAggregate;
+	readonly toolMetrics: ReadonlyMap<string, ToolMetrics>;
+	readonly currentPhase: string | null;
+	readonly startedAt: string;
+}
+
+/**
+ * Mutable internal state for a session (used within the store only).
+ */
+interface MutableSessionData {
+	sessionId: string;
+	events: ObservabilityEvent[];
+	tokens: TokenAggregate;
+	toolMetrics: Map<string, ToolMetrics>;
+	currentPhase: string | null;
+	startedAt: string;
+}
+
+/**
+ * In-memory store for session observability events.
+ * Accumulates events, tokens, and tool metrics per session.
+ */
+export class SessionEventStore {
+	private readonly sessions: Map<string, MutableSessionData> = new Map();
+
+	/**
+	 * Initializes a new session in the store.
+	 */
+	initSession(sessionId: string): void {
+		this.sessions.set(sessionId, {
+			sessionId,
+			events: [],
+			tokens: createEmptyTokenAggregate(),
+			toolMetrics: new Map(),
+			currentPhase: null,
+			startedAt: new Date().toISOString(),
+		});
+	}
+
+	/**
+	 * Appends an event to a session. Silently returns if session is not initialized.
+	 */
+	appendEvent(sessionId: string, event: ObservabilityEvent): void {
+		const session = this.sessions.get(sessionId);
+		if (!session) return;
+		session.events.push(event);
+	}
+
+	/**
+	 * Accumulates token data for a session.
+	 */
+	accumulateTokens(sessionId: string, tokens: Partial<TokenAggregate>): void {
+		const session = this.sessions.get(sessionId);
+		if (!session) return;
+		session.tokens = accumulateTokens(session.tokens, tokens);
+	}
+
+	/**
+	 * Records a tool execution metric.
+	 */
+	recordToolExecution(sessionId: string, tool: string, durationMs: number, success: boolean): void {
+		const session = this.sessions.get(sessionId);
+		if (!session) return;
+
+		const existing = session.toolMetrics.get(tool);
+		const updated: ToolMetrics = {
+			invocations: (existing?.invocations ?? 0) + 1,
+			totalDurationMs: (existing?.totalDurationMs ?? 0) + durationMs,
+			successes: (existing?.successes ?? 0) + (success ? 1 : 0),
+			failures: (existing?.failures ?? 0) + (success ? 0 : 1),
+		};
+		session.toolMetrics.set(tool, updated);
+	}
+
+	/**
+	 * Sets the current pipeline phase for a session.
+	 */
+	setCurrentPhase(sessionId: string, phase: string): void {
+		const session = this.sessions.get(sessionId);
+		if (!session) return;
+		session.currentPhase = phase;
+	}
+
+	/**
+	 * Gets the current pipeline phase for a session.
+	 */
+	getCurrentPhase(sessionId: string): string | null {
+		return this.sessions.get(sessionId)?.currentPhase ?? null;
+	}
+
+	/**
+	 * Returns a snapshot of session data without removing it.
+	 */
+	getSession(sessionId: string): SessionEvents | undefined {
+		const session = this.sessions.get(sessionId);
+		if (!session) return undefined;
+
+		return {
+			sessionId: session.sessionId,
+			events: [...session.events],
+			tokens: session.tokens,
+			toolMetrics: new Map(session.toolMetrics),
+			currentPhase: session.currentPhase,
+			startedAt: session.startedAt,
+		};
+	}
+
+	/**
+	 * Returns session data and removes it from the store (for disk flush).
+	 */
+	flush(sessionId: string): SessionEvents | undefined {
+		const session = this.getSession(sessionId);
+		if (session) {
+			this.sessions.delete(sessionId);
+		}
+		return session;
+	}
+}

package/src/observability/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Observability module barrel export.
+ *
+ * Re-exports all public APIs from the session observability system:
+ * - Schemas and types for structured events
+ * - Session logger for event capture (JSONL append)
+ * - Log writer for complete session persistence (atomic JSON)
+ * - Log reader for querying persisted sessions
+ * - Summary generator for human-readable markdown reports
+ * - Retention for time-based log pruning
+ */
+
+export type { EventSearchFilters, SessionLogEntry } from "./log-reader";
+export {
+	listSessionLogs,
+	readLatestSessionLog,
+	readSessionLog,
+	searchEvents,
+} from "./log-reader";
+export { convertToSessionLog, getLogsDir, writeSessionLog } from "./log-writer";
+export { pruneOldLogs } from "./retention";
+export {
+	baseEventSchema,
+	decisionEventSchema,
+	errorEventSchema,
+	fallbackEventSchema,
+	loggingConfigSchema,
+	loggingDefaults,
+	modelSwitchEventSchema,
+	sessionDecisionSchema,
+	sessionEventSchema,
+	sessionLogSchema,
+} from "./schemas";
+export { getLogsDir as getEventLogsDir, getSessionLog, logEvent } from "./session-logger";
+
+export {
+	computeDuration,
+	formatCost,
+	formatDuration,
+	generateSessionSummary,
+} from "./summary-generator";
+export type {
+	BaseEvent,
+	DecisionEvent,
+	ErrorEvent,
+	FallbackEvent,
+	LoggingConfig,
+	ModelSwitchEvent,
+	SessionDecision,
+	SessionEvent,
+	SessionEventType,
+	SessionLog,
+} from "./types";

package/src/observability/log-reader.ts

@@ -0,0 +1,152 @@
+/**
+ * Session log reading, listing, searching, and filtering.
+ *
+ * Provides query capabilities over persisted session logs:
+ * - Read a specific session by ID
+ * - List all sessions sorted by startedAt (newest first)
+ * - Read the most recent session
+ * - Search/filter events within a session by type and time range
+ *
+ * All functions handle missing directories gracefully (D-16).
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isEnoentError } from "../utils/fs-helpers";
+import { getLogsDir } from "./log-writer";
+import { sessionLogSchema } from "./schemas";
+import type { SessionEvent, SessionLog } from "./types";
+
+/**
+ * Summary entry for session listing (lightweight, no full event data).
+ */
+export interface SessionLogEntry {
+	readonly sessionId: string;
+	readonly startedAt: string;
+	readonly endedAt: string | null;
+	readonly eventCount: number;
+	readonly decisionCount: number;
+	readonly errorCount: number;
+}
+
+/**
+ * Filters for searching events within a session log.
+ */
+export interface EventSearchFilters {
+	readonly type?: string;
+	readonly after?: string;
+	readonly before?: string;
+}
+
+/**
+ * Reads and parses a specific session log by ID.
+ *
+ * Returns null on: non-existent file, malformed JSON, invalid schema.
+ * Never throws for expected failure modes.
+ */
+export async function readSessionLog(
+	sessionId: string,
+	logsDir?: string,
+): Promise<SessionLog | null> {
+	const dir = logsDir ?? getLogsDir();
+	const logPath = join(dir, `${sessionId}.json`);
+
+	try {
+		const content = await readFile(logPath, "utf-8");
+		const parsed = JSON.parse(content);
+		const result = sessionLogSchema.safeParse(parsed);
+		return result.success ? result.data : null;
+	} catch (error: unknown) {
+		if (isEnoentError(error)) return null;
+		// Recover from malformed JSON
+		if (error instanceof SyntaxError) return null;
+		throw error;
+	}
+}
+
+/**
+ * Lists all session logs sorted by startedAt descending (newest first).
+ *
+ * Returns a lightweight SessionLogEntry for each log (no full event data).
+ * Skips non-JSON files and malformed logs.
+ * Returns empty array for missing or empty directories.
+ */
+export async function listSessionLogs(logsDir?: string): Promise<readonly SessionLogEntry[]> {
+	const dir = logsDir ?? getLogsDir();
+
+	let files: string[];
+	try {
+		files = await readdir(dir);
+	} catch (error: unknown) {
+		if (isEnoentError(error)) return [];
+		throw error;
+	}
+
+	const jsonFiles = files.filter((f) => f.endsWith(".json"));
+	const entries: SessionLogEntry[] = [];
+
+	for (const file of jsonFiles) {
+		try {
+			const content = await readFile(join(dir, file), "utf-8");
+			const parsed = JSON.parse(content);
+			const result = sessionLogSchema.safeParse(parsed);
+
+			if (result.success) {
+				const log = result.data;
+				const errorCount = log.events.filter((e) => e.type === "error").length;
+
+				entries.push({
+					sessionId: log.sessionId,
+					startedAt: log.startedAt,
+					endedAt: log.endedAt,
+					eventCount: log.events.length,
+					decisionCount: log.decisions.length,
+					errorCount,
+				});
+			}
+		} catch (innerError: unknown) {
+			// SyntaxError = malformed JSON, expected and skipped.
+			// I/O errors (permissions, etc.) are unexpected — log them.
+			if (!(innerError instanceof SyntaxError) && !isEnoentError(innerError)) {
+				console.error("[opencode-autopilot] Unexpected error reading log file:", file, innerError);
+			}
+		}
+	}
+
+	// Sort by startedAt descending (newest first)
+	entries.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+
+	return entries;
+}
+
+/**
+ * Returns the most recent session log (by startedAt).
+ *
+ * Returns null when no valid logs exist.
+ */
+export async function readLatestSessionLog(logsDir?: string): Promise<SessionLog | null> {
+	const entries = await listSessionLogs(logsDir);
+
+	if (entries.length === 0) return null;
+
+	// Entries are already sorted newest-first
+	return readSessionLog(entries[0].sessionId, logsDir);
+}
+
+/**
+ * Filters events by type and/or time range.
+ *
+ * Pure function (no I/O, no side effects).
+ * Accepts a readonly array of events and returns a filtered copy.
+ */
+export function searchEvents(
+	events: readonly SessionEvent[],
+	filters: EventSearchFilters,
+): readonly SessionEvent[] {
+	return events.filter((event) => {
+		if (filters.type && event.type !== filters.type) return false;
+		if (filters.after && event.timestamp <= filters.after) return false;
+		if (filters.before && event.timestamp >= filters.before) return false;
+		return true;
+	});
+}

package/src/observability/log-writer.ts

@@ -0,0 +1,93 @@
+/**
+ * Session log persistence layer.
+ *
+ * Writes complete session logs as JSON files with atomic write pattern
+ * (temp file + rename) to prevent corruption. Logs are stored in
+ * ~/.config/opencode/logs/ (user-scoped, not project-scoped per D-08, D-09).
+ */
+
+import { randomBytes } from "node:crypto";
+import { rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ensureDir } from "../utils/fs-helpers";
+import { getGlobalConfigDir } from "../utils/paths";
+import { sessionLogSchema } from "./schemas";
+import type { SessionEvent, SessionLog } from "./types";
+
+/**
+ * Returns the global logs directory path.
+ * Logs are user-scoped, not project-scoped (D-08, D-09).
+ */
+export function getLogsDir(): string {
+	return join(getGlobalConfigDir(), "logs");
+}
+
+/**
+ * Input shape for writeSessionLog -- the in-memory data to persist.
+ */
+interface WriteSessionInput {
+	readonly sessionId: string;
+	readonly startedAt: string;
+	readonly events: readonly SessionEvent[];
+}
+
+/**
+ * Converts in-memory session events to the persisted SessionLog format.
+ *
+ * Extracts decisions from decision-type events.
+ * Builds errorSummary by counting error events by errorType.
+ */
+export function convertToSessionLog(input: WriteSessionInput): SessionLog {
+	const decisions = input.events
+		.filter((e): e is SessionEvent & { type: "decision" } => e.type === "decision")
+		.map((e) => ({
+			timestamp: e.timestamp,
+			phase: e.phase,
+			agent: e.agent,
+			decision: e.decision,
+			rationale: e.rationale,
+		}));
+
+	const errorSummary: Record<string, number> = {};
+	for (const e of input.events) {
+		if (e.type === "error") {
+			errorSummary[e.errorType] = (errorSummary[e.errorType] ?? 0) + 1;
+		}
+	}
+
+	return {
+		schemaVersion: 1 as const,
+		sessionId: input.sessionId,
+		startedAt: input.startedAt,
+		endedAt: new Date().toISOString(),
+		events: [...input.events],
+		decisions,
+		errorSummary,
+	};
+}
+
+/**
+ * Persists a session log to disk as a JSON file.
+ *
+ * Uses atomic write pattern: write to temp file, then rename.
+ * Validates through sessionLogSchema before writing (defensive).
+ * Creates the logs directory if it does not exist.
+ *
+ * @param input - Session data to persist
+ * @param logsDir - Optional override for logs directory (for testing)
+ */
+export async function writeSessionLog(input: WriteSessionInput, logsDir?: string): Promise<void> {
+	const raw = convertToSessionLog(input);
+
+	// Validate and sanitize — use parsed result (strips unknown keys, applies defaults)
+	const log = sessionLogSchema.parse(raw);
+
+	const dir = logsDir ?? getLogsDir();
+	await ensureDir(dir);
+
+	const finalPath = join(dir, `${log.sessionId}.json`);
+	const tmpPath = `${finalPath}.tmp.${randomBytes(8).toString("hex")}`;
+
+	await writeFile(tmpPath, JSON.stringify(log, null, 2), "utf-8");
+	await rename(tmpPath, finalPath);
+}

package/src/observability/mock/mock-provider.ts

@@ -0,0 +1,72 @@
+import type { MockFailureMode } from "./types";
+
+/**
+ * Default error messages for each failure mode.
+ */
+const DEFAULT_MESSAGES: Readonly<Record<MockFailureMode, string>> = Object.freeze({
+	rate_limit: "Rate limit exceeded",
+	quota_exceeded: "Quota exceeded",
+	timeout: "Request timeout — service unavailable (504)",
+	malformed: "Malformed response from model",
+	service_unavailable: "Service unavailable",
+});
+
+/**
+ * Creates a deterministic error object for the given failure mode.
+ * Generated errors match the shapes consumed by classifyErrorType in
+ * src/orchestrator/fallback/error-classifier.ts.
+ *
+ * This is a test utility -- not a real provider registration.
+ * Each returned error object is frozen for immutability.
+ *
+ * @param mode - The failure mode to simulate
+ * @param customMessage - Optional override for the default error message
+ * @returns A frozen error-like object matching SDK error shapes
+ */
+export function createMockError(mode: MockFailureMode, customMessage?: string): unknown {
+	const message = customMessage ?? DEFAULT_MESSAGES[mode];
+
+	switch (mode) {
+		case "rate_limit":
+			return Object.freeze({
+				name: "APIError",
+				status: 429,
+				statusCode: 429,
+				message,
+				error: Object.freeze({ message }),
+			});
+
+		case "quota_exceeded":
+			return Object.freeze({
+				name: "APIError",
+				status: 402,
+				statusCode: 402,
+				message,
+				error: Object.freeze({ message }),
+			});
+
+		case "timeout":
+			return Object.freeze({
+				name: "APIError",
+				status: 504,
+				statusCode: 504,
+				message,
+				error: Object.freeze({ message }),
+			});
+
+		case "malformed":
+			return Object.freeze({
+				name: "UnknownError",
+				message,
+			});
+
+		case "service_unavailable":
+			return Object.freeze({
+				name: "APIError",
+				status: 503,
+				statusCode: 503,
+				message,
+				error: Object.freeze({ message }),
+			});
+	}
+}

package/src/observability/mock/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Mock failure modes for fallback chain testing.
+ * Each mode generates a deterministic error object that feeds into the existing
+ * error classifier (src/orchestrator/fallback/error-classifier.ts).
+ */
+export type MockFailureMode =
+	| "rate_limit"
+	| "quota_exceeded"
+	| "timeout"
+	| "malformed"
+	| "service_unavailable";
+
+/**
+ * All valid failure modes as a frozen readonly array.
+ */
+export const FAILURE_MODES: readonly MockFailureMode[] = Object.freeze([
+	"rate_limit",
+	"quota_exceeded",
+	"timeout",
+	"malformed",
+	"service_unavailable",
+] as const);
+
+/**
+ * Configuration for a mock error provider instance.
+ */
+export interface MockProviderConfig {
+	readonly mode: MockFailureMode;
+	readonly delayMs?: number;
+	readonly customMessage?: string;
+}

package/src/observability/retention.ts

@@ -0,0 +1,57 @@
+import { readdir, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { isEnoentError } from "../utils/fs-helpers";
+import { getLogsDir } from "./session-logger";
+
+const DEFAULT_RETENTION_DAYS = 30;
+
+interface PruneOptions {
+	readonly logsDir?: string;
+	readonly retentionDays?: number;
+}
+
+interface PruneResult {
+	readonly pruned: number;
+}
+
+/**
+ * Removes log files older than the configured retention period.
+ * Defaults to 30 days if no retention period is specified (D-12).
+ *
+ * Runs non-blocking on plugin load (D-14).
+ * Handles missing or empty directories gracefully.
+ *
+ * @param options - Optional logs directory and retention period
+ * @returns Count of pruned files
+ */
+export async function pruneOldLogs(options?: PruneOptions): Promise<PruneResult> {
+	const logsDir = options?.logsDir ?? getLogsDir();
+	const retentionDays = options?.retentionDays ?? DEFAULT_RETENTION_DAYS;
+	const threshold = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+
+	let entries: string[];
+	try {
+		entries = await readdir(logsDir);
+	} catch (error: unknown) {
+		if (isEnoentError(error)) return { pruned: 0 };
+		throw error;
+	}
+
+	let pruned = 0;
+
+	for (const entry of entries) {
+		const filePath = join(logsDir, entry);
+		try {
+			const fileStat = await stat(filePath);
+			if (fileStat.isFile() && fileStat.mtimeMs < threshold) {
+				await unlink(filePath);
+				pruned++;
+			}
+		} catch (error: unknown) {
+			// Skip files that disappear between readdir and stat (race condition safety)
+			if (!isEnoentError(error)) throw error;
+		}
+	}
+
+	return { pruned };
+}