@kodrunhq/opencode-autopilot 1.2.1 → 1.4.0

package/src/observability/event-handlers.ts

@@ -0,0 +1,322 @@
+/**
+ * Hook handler factories for OpenCode event system integration.
+ *
+ * Creates handlers for:
+ * - event hook: session.created/error/idle/deleted/compacted, message.updated
+ * - tool.execute.before: records start timestamp
+ * - tool.execute.after: computes duration, records metrics
+ *
+ * All handlers are pure observers: they read event data, append to store,
+ * and never modify session state or output objects (Pitfall 5).
+ *
+ * @module
+ */
+
+import { classifyErrorType, getErrorMessage } from "../orchestrator/fallback/error-classifier";
+import type { ContextMonitor } from "./context-monitor";
+import { emitErrorEvent, emitToolCompleteEvent } from "./event-emitter";
+import type { ObservabilityEvent, SessionEventStore, SessionEvents } from "./event-store";
+import { accumulateTokensFromMessage, createEmptyTokenAggregate } from "./token-tracker";
+
+/**
+ * Dependencies for the observability event handler.
+ */
+export interface ObservabilityHandlerDeps {
+	readonly eventStore: SessionEventStore;
+	readonly contextMonitor: ContextMonitor;
+	readonly showToast: (
+		title: string,
+		message: string,
+		variant: "info" | "warning" | "error",
+	) => Promise<void>;
+	readonly writeSessionLog: (sessionData: SessionEvents | undefined) => Promise<void>;
+}
+
+/**
+ * Extracts a session ID from event properties.
+ * Supports properties.sessionID, properties.info.sessionID, and properties.info.id.
+ */
+function extractSessionId(properties: Record<string, unknown>): string | undefined {
+	if (typeof properties.sessionID === "string") return properties.sessionID;
+	if (properties.info !== null && typeof properties.info === "object") {
+		const info = properties.info as Record<string, unknown>;
+		if (typeof info.sessionID === "string") return info.sessionID;
+		if (typeof info.id === "string") return info.id;
+	}
+	return undefined;
+}
+
+/**
+ * Checks if an object has AssistantMessage token shape.
+ */
+function hasTokenShape(obj: unknown): obj is {
+	tokens: {
+		input: number;
+		output: number;
+		reasoning: number;
+		cache: { read: number; write: number };
+	};
+	cost: number;
+} {
+	if (obj === null || typeof obj !== "object") return false;
+	const o = obj as Record<string, unknown>;
+	if (typeof o.cost !== "number") return false;
+	if (o.tokens === null || typeof o.tokens !== "object") return false;
+	const tokens = o.tokens as Record<string, unknown>;
+	if (typeof tokens.input !== "number") return false;
+	if (typeof tokens.output !== "number") return false;
+	if (typeof tokens.reasoning !== "number") return false;
+	if (tokens.cache === null || typeof tokens.cache !== "object") return false;
+	const cache = tokens.cache as Record<string, unknown>;
+	return typeof cache.read === "number" && typeof cache.write === "number";
+}
+
+/**
+ * Creates the main observability event handler.
+ *
+ * Routes OpenCode events to the session event store:
+ * - session.created: init session, append session_start
+ * - session.error: classify error, append error event (D-37, D-38)
+ * - message.updated: accumulate tokens, check context utilization
+ * - session.idle: flush to disk (fire-and-forget, Pitfall 2)
+ * - session.deleted: final flush + cleanup
+ * - session.compacted: append event, intermediate flush
+ */
+export function createObservabilityEventHandler(deps: ObservabilityHandlerDeps) {
+	const { eventStore, contextMonitor, showToast, writeSessionLog } = deps;
+
+	return async (input: {
+		readonly event: { readonly type: string; readonly [key: string]: unknown };
+	}): Promise<void> => {
+		const { event } = input;
+		const properties = (event.properties ?? {}) as Record<string, unknown>;
+
+		switch (event.type) {
+			case "session.created": {
+				const info = properties.info as { id?: string; model?: string } | undefined;
+				if (!info?.id) return;
+
+				eventStore.initSession(info.id);
+
+				// Init context monitor with a default context limit.
+				// The actual limit would come from provider metadata if available.
+				contextMonitor.initSession(info.id, 200000);
+
+				// Append session_start event
+				const startEvent: ObservabilityEvent = Object.freeze({
+					type: "session_start" as const,
+					timestamp: new Date().toISOString(),
+					sessionId: info.id,
+				});
+				eventStore.appendEvent(info.id, startEvent);
+				return;
+			}
+
+			case "session.error": {
+				const sessionId = extractSessionId(properties);
+				if (!sessionId) return;
+
+				const error = properties.error;
+				const rawErrorType = classifyErrorType(error);
+				const errorType = (
+					[
+						"rate_limit",
+						"quota_exceeded",
+						"service_unavailable",
+						"missing_api_key",
+						"model_not_found",
+						"content_filter",
+						"context_length",
+					] as const
+				).includes(rawErrorType as never)
+					? (rawErrorType as
+							| "rate_limit"
+							| "quota_exceeded"
+							| "service_unavailable"
+							| "missing_api_key"
+							| "model_not_found"
+							| "content_filter"
+							| "context_length")
+					: ("unknown" as const);
+				const message = getErrorMessage(error);
+
+				const errorEvent = emitErrorEvent(sessionId, errorType, message);
+				eventStore.appendEvent(sessionId, errorEvent);
+				return;
+			}
+
+			case "message.updated": {
+				const info = properties.info as Record<string, unknown> | undefined;
+				if (!info) return;
+
+				const sessionId = typeof info.sessionID === "string" ? info.sessionID : undefined;
+				if (!sessionId) return;
+
+				// Accumulate tokens if message has AssistantMessage shape
+				if (hasTokenShape(info)) {
+					const empty = createEmptyTokenAggregate();
+					const accumulated = accumulateTokensFromMessage(empty, info);
+					eventStore.accumulateTokens(sessionId, accumulated);
+
+					// Check context utilization
+					const utilResult = contextMonitor.processMessage(sessionId, info.tokens.input);
+					if (utilResult.shouldWarn) {
+						const pct = Math.round(utilResult.utilization * 100);
+						// Append context_warning event
+						const warningEvent: ObservabilityEvent = Object.freeze({
+							type: "context_warning" as const,
+							timestamp: new Date().toISOString(),
+							sessionId,
+							utilization: utilResult.utilization,
+							contextLimit: 200000,
+							inputTokens: info.tokens.input,
+						});
+						eventStore.appendEvent(sessionId, warningEvent);
+
+						// Fire toast (per D-35)
+						showToast(
+							"Context Warning",
+							`Context at ${pct}% -- consider compacting`,
+							"warning",
+						).catch((err) => {
+							console.error("[opencode-autopilot]", err);
+						});
+					}
+				}
+				return;
+			}
+
+			case "session.idle": {
+				const sessionId = extractSessionId(properties);
+				if (!sessionId) return;
+
+				// Snapshot to disk (fire-and-forget per Pitfall 2) — session continues
+				const sessionData = eventStore.getSession(sessionId);
+				writeSessionLog(sessionData).catch((err) => {
+					console.error("[opencode-autopilot]", err);
+				});
+				return;
+			}
+
+			case "session.deleted": {
+				const sessionId = extractSessionId(properties);
+				if (!sessionId) return;
+
+				// Final flush — session is done, remove from store
+				const sessionData = eventStore.flush(sessionId);
+				writeSessionLog(sessionData).catch((err) => {
+					console.error("[opencode-autopilot]", err);
+				});
+
+				// Clean up context monitor
+				contextMonitor.cleanup(sessionId);
+				return;
+			}
+
+			case "session.compacted": {
+				const sessionId = extractSessionId(properties);
+				if (!sessionId) return;
+
+				// Append compaction decision event (not session_start)
+				const compactEvent: ObservabilityEvent = Object.freeze({
+					type: "decision" as const,
+					timestamp: new Date().toISOString(),
+					sessionId,
+					phase: "COMPACT",
+					agent: "system",
+					decision: "Session compacted",
+					rationale: "Context window compaction triggered",
+				});
+				eventStore.appendEvent(sessionId, compactEvent);
+
+				// Snapshot to disk — session continues after compaction
+				const sessionData = eventStore.getSession(sessionId);
+				writeSessionLog(sessionData).catch((err) => {
+					console.error("[opencode-autopilot]", err);
+				});
+				return;
+			}
+
+			default:
+				return;
+		}
+	};
+}
+
+/**
+ * Creates a tool.execute.before handler that records start timestamps.
+ *
+ * @param startTimes - Map to store callID -> start timestamp
+ */
+export function createToolExecuteBeforeHandler(startTimes: Map<string, number>) {
+	return (hookInput: {
+		readonly tool: string;
+		readonly sessionID: string;
+		readonly callID: string;
+		readonly args: unknown;
+	}): void => {
+		startTimes.set(hookInput.callID, Date.now());
+	};
+}
+
+/**
+ * Determines if a tool execution succeeded based on the output.
+ */
+function isToolSuccess(output: {
+	readonly title: string;
+	readonly output: string;
+	readonly metadata: unknown;
+}): boolean {
+	// Check metadata for explicit error flag
+	if (output.metadata !== null && typeof output.metadata === "object") {
+		const meta = output.metadata as Record<string, unknown>;
+		if (meta.error === true) return false;
+	}
+	// Check title for error indicator
+	if (output.title.toLowerCase().startsWith("error")) return false;
+	// Check output for error prefix
+	if (output.output.startsWith("Error:")) return false;
+	return true;
+}
+
+/**
+ * Creates a tool.execute.after handler that computes duration and records metrics.
+ *
+ * Never modifies the output object (pure observer per Pitfall 5).
+ *
+ * @param eventStore - The session event store
+ * @param startTimes - Map of callID -> start timestamp (shared with before handler)
+ */
+export function createToolExecuteAfterHandler(
+	eventStore: SessionEventStore,
+	startTimes: Map<string, number>,
+) {
+	return (
+		hookInput: {
+			readonly tool: string;
+			readonly sessionID: string;
+			readonly callID: string;
+			readonly args: unknown;
+		},
+		output: { readonly title: string; readonly output: string; readonly metadata: unknown },
+	): void => {
+		const startTime = startTimes.get(hookInput.callID);
+		const durationMs = startTime !== undefined ? Date.now() - startTime : 0;
+		const success = isToolSuccess(output);
+
+		// Clean up start time entry
+		startTimes.delete(hookInput.callID);
+
+		// Record tool execution metric (per D-39, D-40)
+		eventStore.recordToolExecution(hookInput.sessionID, hookInput.tool, durationMs, success);
+
+		// Append tool_complete event
+		const toolEvent = emitToolCompleteEvent(
+			hookInput.sessionID,
+			hookInput.tool,
+			durationMs,
+			success,
+		);
+		eventStore.appendEvent(hookInput.sessionID, toolEvent);
+	};
+}

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";