@kodrunhq/opencode-autopilot 1.2.1 → 1.4.0

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 };
+}

package/src/observability/schemas.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+
+export const baseEventSchema = z.object({
+	timestamp: z.string().max(128),
+	sessionId: z
+		.string()
+		.max(256)
+		.regex(/^[a-zA-Z0-9_-]{1,256}$/, "Invalid session ID"),
+	type: z.enum(["fallback", "error", "decision", "model_switch"]),
+});
+
+export const fallbackEventSchema = baseEventSchema.extend({
+	type: z.literal("fallback"),
+	failedModel: z.string().max(256),
+	nextModel: z.string().max(256),
+	reason: z.string().max(1024),
+	success: z.boolean(),
+});
+
+export const errorEventSchema = baseEventSchema.extend({
+	type: z.literal("error"),
+	errorType: z.enum([
+		"rate_limit",
+		"quota_exceeded",
+		"service_unavailable",
+		"missing_api_key",
+		"model_not_found",
+		"content_filter",
+		"context_length",
+		"unknown",
+	]),
+	model: z.string().max(256),
+	message: z.string().max(4096),
+	statusCode: z.number().optional(),
+});
+
+export const decisionEventSchema = baseEventSchema.extend({
+	type: z.literal("decision"),
+	phase: z.string().max(128),
+	agent: z.string().max(128),
+	decision: z.string().max(2048),
+	rationale: z.string().max(2048),
+});
+
+export const modelSwitchEventSchema = baseEventSchema.extend({
+	type: z.literal("model_switch"),
+	fromModel: z.string().max(256),
+	toModel: z.string().max(256),
+	trigger: z.enum(["fallback", "config", "user"]),
+});
+
+export const sessionEventSchema = z.discriminatedUnion("type", [
+	fallbackEventSchema,
+	errorEventSchema,
+	decisionEventSchema,
+	modelSwitchEventSchema,
+]);
+
+export const loggingConfigSchema = z.object({
+	enabled: z.boolean().default(true),
+	retentionDays: z.number().min(1).max(365).default(30),
+});
+
+export const sessionDecisionSchema = z.object({
+	timestamp: z.string().optional(),
+	phase: z.string(),
+	agent: z.string(),
+	decision: z.string(),
+	rationale: z.string(),
+});
+
+export const sessionLogSchema = z.object({
+	schemaVersion: z.number().default(1),
+	sessionId: z.string().regex(/^[a-zA-Z0-9_-]{1,256}$/, "Invalid session ID"),
+	startedAt: z.string(),
+	endedAt: z.string().nullable().default(null),
+	events: z.array(sessionEventSchema),
+	decisions: z.array(sessionDecisionSchema).default([]),
+	errorSummary: z.record(z.string(), z.number()).default({}),
+});
+
+// Pre-compute defaults for Zod v4 nested default compatibility
+export const loggingDefaults = loggingConfigSchema.parse({});

package/src/observability/session-logger.ts

@@ -0,0 +1,63 @@
+import { appendFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ensureDir, isEnoentError } from "../utils/fs-helpers";
+import { getGlobalConfigDir } from "../utils/paths";
+import { sessionEventSchema } from "./schemas";
+import type { SessionEvent } 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");
+}
+
+/**
+ * Returns the JSONL log file path for a given session ID.
+ */
+function getSessionLogPath(sessionId: string, logsDir?: string): string {
+	return join(logsDir ?? getLogsDir(), `${sessionId}.jsonl`);
+}
+
+/**
+ * Logs a structured event to the session's JSONL log file.
+ * Validates the event against the Zod schema before writing.
+ * Creates the logs directory if it does not exist.
+ *
+ * @param event - The session event to log (D-02, D-04-D-07)
+ * @param logsDir - Optional override for the logs directory (for testing)
+ */
+export async function logEvent(event: SessionEvent, logsDir?: string): Promise<void> {
+	// Validate against schema -- throws on invalid events
+	const validated = sessionEventSchema.parse(event);
+
+	const dir = logsDir ?? getLogsDir();
+	await ensureDir(dir);
+
+	const logPath = getSessionLogPath(validated.sessionId, dir);
+	const line = `${JSON.stringify(validated)}\n`;
+
+	await appendFile(logPath, line, "utf-8");
+}
+
+/**
+ * Reads and parses all events from a session's JSONL log file.
+ * Returns an empty array if the session log does not exist.
+ *
+ * @param sessionId - The session ID to read logs for
+ * @param logsDir - Optional override for the logs directory (for testing)
+ */
+export async function getSessionLog(sessionId: string, logsDir?: string): Promise<SessionEvent[]> {
+	const logPath = getSessionLogPath(sessionId, logsDir);
+
+	try {
+		const content = await readFile(logPath, "utf-8");
+		const lines = content.trim().split("\n").filter(Boolean);
+
+		return lines.map((line) => sessionEventSchema.parse(JSON.parse(line)));
+	} catch (error: unknown) {
+		if (isEnoentError(error)) return [];
+		throw error;
+	}
+}