@kodrunhq/opencode-autopilot 1.3.0 → 1.5.0

package/src/observability/context-monitor.ts

@@ -0,0 +1,102 @@
+/**
+ * Context utilization tracking with one-time warning per session.
+ *
+ * Pure function `checkContextUtilization` computes utilization ratio and warning signal.
+ * `ContextMonitor` class tracks per-session warned state and context limits.
+ *
+ * The toast itself is NOT fired here -- that happens in the event handler
+ * (separation of concerns). This module only computes whether to warn.
+ *
+ * @module
+ */
+
+/** Threshold at which context utilization triggers a warning (80%). */
+const CONTEXT_WARNING_THRESHOLD = 0.8;
+
+/**
+ * Result of a context utilization check.
+ */
+export interface ContextUtilizationResult {
+	readonly utilization: number;
+	readonly shouldWarn: boolean;
+}
+
+/**
+ * Pure function that computes context utilization and whether to warn.
+ *
+ * - Returns utilization as a ratio (0.0 - 1.0)
+ * - Returns shouldWarn=true when utilization >= 0.80 and not already warned
+ * - Returns shouldWarn=false when already warned (fires once per D-36)
+ * - Handles zero contextLimit gracefully (returns 0 utilization)
+ *
+ * @param latestInputTokens - Current cumulative input tokens for the session
+ * @param contextLimit - The model's context window size in tokens
+ * @param alreadyWarned - Whether this session has already been warned
+ */
+export function checkContextUtilization(
+	latestInputTokens: number,
+	contextLimit: number,
+	alreadyWarned: boolean,
+): ContextUtilizationResult {
+	if (contextLimit <= 0) {
+		return { utilization: 0, shouldWarn: false };
+	}
+
+	const utilization = latestInputTokens / contextLimit;
+	const shouldWarn = !alreadyWarned && utilization >= CONTEXT_WARNING_THRESHOLD;
+
+	return { utilization, shouldWarn };
+}
+
+/**
+ * Per-session state for context monitoring.
+ */
+interface SessionContextState {
+	readonly contextLimit: number;
+	warned: boolean;
+}
+
+/**
+ * Tracks context utilization per session with one-time warning.
+ *
+ * - `initSession` sets the context limit for a session
+ * - `processMessage` checks utilization and updates warned state
+ * - `cleanup` removes session tracking data
+ */
+export class ContextMonitor {
+	private readonly sessions: Map<string, SessionContextState> = new Map();
+
+	/**
+	 * Initializes tracking for a session with its model's context limit.
+	 */
+	initSession(sessionID: string, contextLimit: number): void {
+		this.sessions.set(sessionID, { contextLimit, warned: false });
+	}
+
+	/**
+	 * Checks context utilization for a session and updates warned state.
+	 * Returns utilization 0 for unknown sessions.
+	 */
+	processMessage(sessionID: string, inputTokens: number): ContextUtilizationResult {
+		const state = this.sessions.get(sessionID);
+		if (!state) {
+			return { utilization: 0, shouldWarn: false };
+		}
+
+		const result = checkContextUtilization(inputTokens, state.contextLimit, state.warned);
+
+		// Update warned flag if warning triggered (one-time per session)
+		if (result.shouldWarn) {
+			this.sessions.set(sessionID, { ...state, warned: true });
+		}
+
+		return result;
+	}
+
+	/**
+	 * Removes session tracking data.
+	 */
+	cleanup(sessionID: string): void {
+		this.sessions.delete(sessionID);
+	}
+}

package/src/observability/event-emitter.ts

@@ -0,0 +1,136 @@
+/**
+ * Typed event emitter helper functions for observability events.
+ *
+ * Each function constructs a frozen ObservabilityEvent with a timestamp.
+ * Pure functions: take args, return frozen event object.
+ *
+ * @module
+ */
+
+import type { ObservabilityEvent } from "./event-store";
+
+/**
+ * Constructs a fallback event.
+ */
+export function emitFallbackEvent(
+	sessionId: string,
+	failedModel: string,
+	nextModel: string,
+	reason: string,
+	success: boolean,
+): ObservabilityEvent {
+	return Object.freeze({
+		type: "fallback" as const,
+		timestamp: new Date().toISOString(),
+		sessionId,
+		failedModel,
+		nextModel,
+		reason,
+		success,
+	});
+}
+
+/**
+ * Constructs an error event.
+ */
+export function emitErrorEvent(
+	sessionId: string,
+	errorType:
+		| "rate_limit"
+		| "quota_exceeded"
+		| "service_unavailable"
+		| "missing_api_key"
+		| "model_not_found"
+		| "content_filter"
+		| "context_length"
+		| "unknown",
+	message: string,
+	model = "unknown",
+	statusCode?: number,
+): ObservabilityEvent {
+	return Object.freeze({
+		type: "error" as const,
+		timestamp: new Date().toISOString(),
+		sessionId,
+		errorType,
+		message,
+		model,
+		...(statusCode !== undefined ? { statusCode } : {}),
+	});
+}
+
+/**
+ * Constructs a decision event (per D-27, D-28).
+ */
+export function emitDecisionEvent(
+	sessionId: string,
+	phase: string,
+	agent: string,
+	decision: string,
+	rationale: string,
+): ObservabilityEvent {
+	return Object.freeze({
+		type: "decision" as const,
+		timestamp: new Date().toISOString(),
+		sessionId,
+		phase,
+		agent,
+		decision,
+		rationale,
+	});
+}
+
+/**
+ * Constructs a model_switch event.
+ */
+export function emitModelSwitchEvent(
+	sessionId: string,
+	fromModel: string,
+	toModel: string,
+	trigger: "fallback" | "config" | "user",
+): ObservabilityEvent {
+	return Object.freeze({
+		type: "model_switch" as const,
+		timestamp: new Date().toISOString(),
+		sessionId,
+		fromModel,
+		toModel,
+		trigger,
+	});
+}
+
+/**
+ * Constructs a tool_complete event.
+ */
+export function emitToolCompleteEvent(
+	sessionId: string,
+	tool: string,
+	durationMs: number,
+	success: boolean,
+): ObservabilityEvent {
+	return Object.freeze({
+		type: "tool_complete" as const,
+		timestamp: new Date().toISOString(),
+		sessionId,
+		tool,
+		durationMs,
+		success,
+	});
+}
+
+/**
+ * Constructs a phase_transition event.
+ */
+export function emitPhaseTransition(
+	sessionId: string,
+	fromPhase: string,
+	toPhase: string,
+): ObservabilityEvent {
+	return Object.freeze({
+		type: "phase_transition" as const,
+		timestamp: new Date().toISOString(),
+		sessionId,
+		fromPhase,
+		toPhase,
+	});
+}

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