@kodrunhq/opencode-autopilot 1.15.1 → 1.16.0

package/src/observability/forensic-log.ts

@@ -0,0 +1,159 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { appendForensicEventsToKernel, loadForensicEventsFromKernel } from "../kernel/repository";
+import { isEnoentError } from "../utils/fs-helpers";
+import { getProjectArtifactDir } from "../utils/paths";
+import { forensicEventSchema } from "./forensic-schemas";
+import type { ForensicEvent, ForensicEventDomain, ForensicEventType } from "./forensic-types";
+
+const FORENSIC_LOG_FILE = "orchestration.jsonl";
+let forensicWriteWarned = false;
+let forensicMirrorWarned = false;
+
+interface ForensicEventInput {
+	readonly timestamp?: string;
+	readonly projectRoot: string;
+	readonly domain: ForensicEventDomain;
+	readonly runId?: string | null;
+	readonly sessionId?: string | null;
+	readonly parentSessionId?: string | null;
+	readonly phase?: string | null;
+	readonly dispatchId?: string | null;
+	readonly taskId?: number | null;
+	readonly agent?: string | null;
+	readonly type: ForensicEventType;
+	readonly code?: string | null;
+	readonly message?: string | null;
+	readonly payload?: Record<string, string | number | boolean | null | readonly unknown[] | object>;
+}
+
+function redactMessage(message: string | null | undefined): string | null {
+	if (message == null) {
+		return null;
+	}
+	return message.replace(/[/\\][^\s"']+/g, "[PATH]");
+}
+
+function toProjectRootFromArtifactDir(artifactDir: string): string {
+	return basename(artifactDir) === ".opencode-autopilot" ? dirname(artifactDir) : artifactDir;
+}
+
+function appendValidatedForensicEvent(artifactDir: string, event: ForensicEvent): void {
+	appendForensicEventsToKernel(artifactDir, [event]);
+
+	try {
+		mkdirSync(artifactDir, { recursive: true });
+		const logPath = join(artifactDir, FORENSIC_LOG_FILE);
+		appendFileSync(logPath, `${JSON.stringify(event)}\n`, "utf-8");
+	} catch (mirrorError) {
+		if (!forensicMirrorWarned) {
+			forensicMirrorWarned = true;
+			console.warn("[opencode-autopilot] forensic JSONL mirror write failed:", mirrorError);
+		}
+	}
+}
+
+export function getForensicLogPath(projectRoot: string): string {
+	return join(getProjectArtifactDir(projectRoot), FORENSIC_LOG_FILE);
+}
+
+export function createForensicEvent(input: ForensicEventInput): ForensicEvent {
+	return forensicEventSchema.parse({
+		schemaVersion: 1,
+		timestamp: input.timestamp ?? new Date().toISOString(),
+		projectRoot: input.projectRoot,
+		domain: input.domain,
+		runId: input.runId ?? null,
+		sessionId: input.sessionId ?? null,
+		parentSessionId: input.parentSessionId ?? null,
+		phase: input.phase ?? null,
+		dispatchId: input.dispatchId ?? null,
+		taskId: input.taskId ?? null,
+		agent: input.agent ?? null,
+		type: input.type,
+		code: input.code ?? null,
+		message: redactMessage(input.message),
+		payload: input.payload ?? {},
+	});
+}
+
+export function appendForensicEvent(projectRoot: string, event: ForensicEventInput): void {
+	try {
+		const validated = createForensicEvent(event);
+		const artifactDir = getProjectArtifactDir(projectRoot);
+		appendValidatedForensicEvent(artifactDir, validated);
+	} catch (error) {
+		if (!forensicWriteWarned) {
+			forensicWriteWarned = true;
+			console.warn("[opencode-autopilot] forensic log write failed:", error);
+		}
+	}
+}
+
+export function appendForensicEventForArtifactDir(
+	artifactDir: string,
+	event: Omit<ForensicEventInput, "projectRoot">,
+): void {
+	try {
+		const validated = createForensicEvent({
+			...event,
+			projectRoot: toProjectRootFromArtifactDir(artifactDir),
+		});
+		appendValidatedForensicEvent(artifactDir, validated);
+	} catch (error) {
+		if (!forensicWriteWarned) {
+			forensicWriteWarned = true;
+			console.warn("[opencode-autopilot] forensic log write failed:", error);
+		}
+	}
+}
+
+export async function readForensicEvents(projectRoot: string): Promise<readonly ForensicEvent[]> {
+	const kernelEvents = loadForensicEventsFromKernel(getProjectArtifactDir(projectRoot));
+	if (kernelEvents.length > 0) {
+		return kernelEvents;
+	}
+
+	try {
+		const raw = await readFile(getForensicLogPath(projectRoot), "utf-8");
+		const events: ForensicEvent[] = [];
+		for (const line of raw.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) {
+				continue;
+			}
+			try {
+				events.push(forensicEventSchema.parse(JSON.parse(trimmed)));
+			} catch {
+				// Ignore malformed forensic lines so one bad append does not hide the rest.
+			}
+		}
+		return Object.freeze(events);
+	} catch (error: unknown) {
+		if (isEnoentError(error)) {
+			return Object.freeze([]);
+		}
+		throw error;
+	}
+}
+
+export async function listProjectsWithForensicLogs(logsRoot?: string): Promise<readonly string[]> {
+	const root = logsRoot;
+	if (!root) {
+		return Object.freeze([]);
+	}
+
+	try {
+		const entries = await readdir(root, { withFileTypes: true });
+		const projects = entries
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => join(root, entry.name));
+		return Object.freeze(projects);
+	} catch (error: unknown) {
+		if (isEnoentError(error)) {
+			return Object.freeze([]);
+		}
+		throw error;
+	}
+}

package/src/observability/forensic-schemas.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+
+export const forensicEventTypeSchema = z.enum([
+	"run_started",
+	"dispatch",
+	"dispatch_multi",
+	"result_applied",
+	"phase_transition",
+	"complete",
+	"decision",
+	"error",
+	"loop_detected",
+	"failure_recorded",
+	"warning",
+	"session_start",
+	"session_end",
+	"fallback",
+	"model_switch",
+	"context_warning",
+	"tool_complete",
+	"compacted",
+]);
+
+export const forensicEventDomainSchema = z.enum(["session", "orchestrator", "contract"]);
+
+export type JsonValue =
+	| null
+	| boolean
+	| number
+	| string
+	| readonly JsonValue[]
+	| { readonly [key: string]: JsonValue };
+
+export const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+	z.union([
+		z.null(),
+		z.boolean(),
+		z.number(),
+		z.string(),
+		z.array(jsonValueSchema),
+		z.record(z.string(), jsonValueSchema),
+	]),
+);
+
+export const forensicEventSchema = z.object({
+	schemaVersion: z.literal(1),
+	timestamp: z.string().max(128),
+	projectRoot: z.string().max(4096),
+	domain: forensicEventDomainSchema,
+	runId: z.string().max(128).nullable().default(null),
+	sessionId: z.string().max(256).nullable().default(null),
+	parentSessionId: z.string().max(256).nullable().default(null),
+	phase: z.string().max(128).nullable().default(null),
+	dispatchId: z.string().max(128).nullable().default(null),
+	taskId: z.number().int().positive().nullable().default(null),
+	agent: z.string().max(128).nullable().default(null),
+	type: forensicEventTypeSchema,
+	code: z.string().max(128).nullable().default(null),
+	message: z.string().max(4096).nullable().default(null),
+	payload: z.record(z.string(), jsonValueSchema).default({}),
+});
+
+export const forensicEventDefaults = forensicEventSchema.parse({
+	schemaVersion: 1,
+	timestamp: new Date(0).toISOString(),
+	projectRoot: "/unknown",
+	domain: "orchestrator",
+	type: "error",
+});

package/src/observability/forensic-types.ts

@@ -0,0 +1,10 @@
+import type { z } from "zod";
+import type {
+	forensicEventDomainSchema,
+	forensicEventSchema,
+	forensicEventTypeSchema,
+} from "./forensic-schemas";
+
+export type ForensicEventDomain = z.infer<typeof forensicEventDomainSchema>;
+export type ForensicEventType = z.infer<typeof forensicEventTypeSchema>;
+export type ForensicEvent = z.infer<typeof forensicEventSchema>;

package/src/observability/index.ts

@@ -2,14 +2,25 @@
  * 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
+ * - Schemas and types for structured forensic events
+ * - Forensic log writer/reader for durable project-local evidence
+ * - Summary generator for human-readable reports
+ * - Retention for time-based pruning
  */
 
+export {
+	appendForensicEvent,
+	appendForensicEventForArtifactDir,
+	createForensicEvent,
+	getForensicLogPath,
+	readForensicEvents,
+} from "./forensic-log";
+export {
+	forensicEventDefaults,
+	forensicEventDomainSchema,
+	forensicEventSchema,
+	forensicEventTypeSchema,
+} from "./forensic-schemas";
 export type { EventSearchFilters, SessionLogEntry } from "./log-reader";
 export {
 	listSessionLogs,
@@ -17,20 +28,8 @@ export {
 	readSessionLog,
 	searchEvents,
 } from "./log-reader";
-export { convertToSessionLog, getLogsDir, writeSessionLog } from "./log-writer";
+export { 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 {
@@ -40,14 +39,9 @@ export {
 	generateSessionSummary,
 } from "./summary-generator";
 export type {
-	BaseEvent,
-	DecisionEvent,
-	ErrorEvent,
-	FallbackEvent,
-	LoggingConfig,
-	ModelSwitchEvent,
+	ForensicEvent,
+	ForensicEventDomain,
+	ForensicEventType,
 	SessionDecision,
-	SessionEvent,
-	SessionEventType,
 	SessionLog,
 } from "./types";

package/src/observability/log-reader.ts

@@ -1,27 +1,32 @@
-/**
- * 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 { readdir } 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";
+import { getProjectRootFromArtifactDir } from "../utils/paths";
+import { readForensicEvents } from "./forensic-log";
+import type { ForensicEvent } from "./forensic-types";
+
+export interface SessionDecision {
+	readonly timestamp: string | null;
+	readonly phase: string;
+	readonly agent: string;
+	readonly decision: string;
+	readonly rationale: string;
+}
+
+export interface SessionLog {
+	readonly schemaVersion: 1;
+	readonly sessionId: string;
+	readonly projectRoot: string;
+	readonly startedAt: string;
+	readonly endedAt: string | null;
+	readonly events: readonly ForensicEvent[];
+	readonly decisions: readonly SessionDecision[];
+	readonly errorSummary: Readonly<Record<string, number>>;
+}
 
-/**
- * Summary entry for session listing (lightweight, no full event data).
- */
 export interface SessionLogEntry {
 	readonly sessionId: string;
+	readonly projectRoot: string;
 	readonly startedAt: string;
 	readonly endedAt: string | null;
 	readonly eventCount: number;
@@ -29,124 +34,150 @@ export interface SessionLogEntry {
 	readonly errorCount: number;
 }
 
-/**
- * Filters for searching events within a session log.
- */
 export interface EventSearchFilters {
 	readonly type?: string;
 	readonly after?: string;
 	readonly before?: string;
+	readonly domain?: 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`);
+function isSessionForProject(event: Readonly<ForensicEvent>, sessionId: string): boolean {
+	return event.domain === "session" && event.sessionId === sessionId;
+}
 
-	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;
+function buildErrorSummary(events: readonly ForensicEvent[]): Readonly<Record<string, number>> {
+	const summary: Record<string, number> = {};
+	for (const event of events) {
+		if (event.type !== "error") {
+			continue;
+		}
+		const code =
+			event.code ?? (typeof event.payload.errorType === "string" ? event.payload.errorType : null);
+		const key = code ?? "unknown";
+		summary[key] = (summary[key] ?? 0) + 1;
 	}
+	return Object.freeze(summary);
 }
 
-/**
- * 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;
-	}
+function buildDecisions(events: readonly ForensicEvent[]): readonly SessionDecision[] {
+	return Object.freeze(
+		events
+			.filter((event) => event.type === "decision")
+			.map((event) => ({
+				timestamp: event.timestamp,
+				phase: event.phase ?? "UNKNOWN",
+				agent: event.agent ?? "unknown",
+				decision:
+					typeof event.payload.decision === "string"
+						? event.payload.decision
+						: (event.message ?? "decision recorded"),
+				rationale:
+					typeof event.payload.rationale === "string"
+						? event.payload.rationale
+						: (event.message ?? ""),
+			})),
+	);
+}
 
-	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);
-			}
-		}
+function buildSessionLog(
+	projectRoot: string,
+	sessionId: string,
+	events: readonly ForensicEvent[],
+): SessionLog | null {
+	if (events.length === 0) {
+		return null;
 	}
 
-	// Sort by startedAt descending (newest first)
-	entries.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+	const sessionEvents = events
+		.filter((event) => event.sessionId === sessionId)
+		.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+	if (sessionEvents.length === 0) {
+		return null;
+	}
 
-	return entries;
+	const started = sessionEvents.find((event) => event.type === "session_start");
+	const ended = [...sessionEvents].reverse().find((event) => event.type === "session_end");
+
+	return {
+		schemaVersion: 1,
+		sessionId,
+		projectRoot,
+		startedAt: started?.timestamp ?? sessionEvents[0].timestamp,
+		endedAt: ended?.timestamp ?? null,
+		events: Object.freeze(sessionEvents),
+		decisions: buildDecisions(sessionEvents),
+		errorSummary: buildErrorSummary(sessionEvents),
+	};
 }
 
-/**
- * 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);
+export async function readSessionLog(
+	sessionId: string,
+	artifactDirOrProjectRoot: string,
+): Promise<SessionLog | null> {
+	const projectRoot = getProjectRootFromArtifactDir(artifactDirOrProjectRoot);
+	const events = await readForensicEvents(projectRoot);
+	return buildSessionLog(projectRoot, sessionId, events);
+}
 
-	if (entries.length === 0) return null;
+export async function listSessionLogs(
+	artifactDirOrProjectRoot: string,
+): Promise<readonly SessionLogEntry[]> {
+	const projectRoot = getProjectRootFromArtifactDir(artifactDirOrProjectRoot);
+	const events = await readForensicEvents(projectRoot);
+	const sessionIds = [
+		...new Set(events.map((event) => event.sessionId).filter((value): value is string => !!value)),
+	];
+
+	const entries = sessionIds
+		.map((sessionId) => buildSessionLog(projectRoot, sessionId, events))
+		.filter((entry): entry is SessionLog => entry !== null)
+		.map((log) => ({
+			sessionId: log.sessionId,
+			projectRoot: log.projectRoot,
+			startedAt: log.startedAt,
+			endedAt: log.endedAt,
+			eventCount: log.events.length,
+			decisionCount: log.decisions.length,
+			errorCount: Object.values(log.errorSummary).reduce((sum, count) => sum + count, 0),
+		}))
+		.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+
+	return Object.freeze(entries);
+}
 
-	// Entries are already sorted newest-first
-	return readSessionLog(entries[0].sessionId, logsDir);
+export async function readLatestSessionLog(
+	artifactDirOrProjectRoot: string,
+): Promise<SessionLog | null> {
+	const entries = await listSessionLogs(artifactDirOrProjectRoot);
+	if (entries.length === 0) {
+		return null;
+	}
+	return readSessionLog(entries[0].sessionId, artifactDirOrProjectRoot);
 }
 
-/**
- * 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[],
+	events: readonly ForensicEvent[],
 	filters: EventSearchFilters,
-): readonly SessionEvent[] {
+): readonly ForensicEvent[] {
 	return events.filter((event) => {
 		if (filters.type && event.type !== filters.type) return false;
+		if (filters.domain && event.domain !== filters.domain) return false;
 		if (filters.after && event.timestamp <= filters.after) return false;
 		if (filters.before && event.timestamp >= filters.before) return false;
 		return true;
 	});
 }
+
+export async function listProjectRootsWithLogs(rootDir: string): Promise<readonly string[]> {
+	try {
+		const entries = await readdir(rootDir, { withFileTypes: true });
+		return Object.freeze(
+			entries.filter((entry) => entry.isDirectory()).map((entry) => join(rootDir, entry.name)),
+		);
+	} catch (error: unknown) {
+		if (isEnoentError(error)) {
+			return Object.freeze([]);
+		}
+		throw error;
+	}
+}