@kodrunhq/opencode-autopilot 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kodrunhq/opencode-autopilot",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"description": "Curated agents, skills, and commands for the OpenCode AI coding CLI — autonomous orchestrator, multi-agent code review, model fallback, and in-session asset creation tools.",
 	"main": "src/index.ts",
 	"keywords": [

package/src/index.ts

@@ -3,6 +3,16 @@ import { configHook } from "./agents";
 import { isFirstLoad, loadConfig } from "./config";
 import { runHealthChecks } from "./health/runner";
 import { installAssets } from "./installer";
+import { ContextMonitor } from "./observability/context-monitor";
+import {
+	createObservabilityEventHandler,
+	createToolExecuteAfterHandler as createObsToolAfterHandler,
+	createToolExecuteBeforeHandler,
+} from "./observability/event-handlers";
+import { SessionEventStore } from "./observability/event-store";
+import { writeSessionLog } from "./observability/log-writer";
+import { pruneOldLogs } from "./observability/retention";
+import type { SessionEvent } from "./observability/types";
 import type { SdkOperations } from "./orchestrator/fallback";
 import {
 	createChatMessageHandler,
@@ -24,11 +34,15 @@ import { ocCreateCommand } from "./tools/create-command";
 import { ocCreateSkill } from "./tools/create-skill";
 import { ocDoctor } from "./tools/doctor";
 import { ocForensics } from "./tools/forensics";
+import { ocLogs } from "./tools/logs";
+import { ocMockFallback } from "./tools/mock-fallback";
 import { ocOrchestrate } from "./tools/orchestrate";
 import { ocPhase } from "./tools/phase";
+import { ocPipelineReport } from "./tools/pipeline-report";
 import { ocPlan } from "./tools/plan";
 import { ocQuick } from "./tools/quick";
 import { ocReview } from "./tools/review";
+import { ocSessionStats } from "./tools/session-stats";
 import { ocState } from "./tools/state";
 
 let openCodeConfig: Config | null = null;
@@ -70,6 +84,15 @@ const plugin: Plugin = async (input) => {
 		// Health check failures are non-fatal — oc_doctor provides manual diagnostics
 	});
 
+	// --- Observability subsystem initialization ---
+	const eventStore = new SessionEventStore();
+	const contextMonitor = new ContextMonitor();
+
+	// Retention pruning on load (non-blocking per D-14)
+	pruneOldLogs().catch((err) => {
+		console.error("[opencode-autopilot]", err);
+	});
+
 	// --- Fallback subsystem initialization ---
 	const sdkOps: SdkOperations = {
 		abortSession: async (sessionID) => {
@@ -123,6 +146,32 @@ const plugin: Plugin = async (input) => {
 	const chatMessageHandler = createChatMessageHandler(manager);
 	const toolExecuteAfterHandler = createToolExecuteAfterHandler(manager);
 
+	// --- Observability handlers ---
+	const toolStartTimes = new Map<string, number>();
+	const observabilityEventHandler = createObservabilityEventHandler({
+		eventStore,
+		contextMonitor,
+		showToast: sdkOps.showToast,
+		writeSessionLog: async (sessionData) => {
+			if (!sessionData) return;
+			// Filter to schema-valid event types that match SessionEvent discriminated union
+			const schemaEvents: SessionEvent[] = sessionData.events.filter(
+				(e): e is SessionEvent =>
+					e.type === "fallback" ||
+					e.type === "error" ||
+					e.type === "decision" ||
+					e.type === "model_switch",
+			);
+			await writeSessionLog({
+				sessionId: sessionData.sessionId,
+				startedAt: sessionData.startedAt,
+				events: schemaEvents,
+			});
+		},
+	});
+	const obsToolBeforeHandler = createToolExecuteBeforeHandler(toolStartTimes);
+	const obsToolAfterHandler = createObsToolAfterHandler(eventStore, toolStartTimes);
+
 	return {
 		tool: {
 			oc_configure: ocConfigure,
@@ -138,8 +187,16 @@ const plugin: Plugin = async (input) => {
 			oc_quick: ocQuick,
 			oc_forensics: ocForensics,
 			oc_review: ocReview,
+			oc_logs: ocLogs,
+			oc_session_stats: ocSessionStats,
+			oc_pipeline_report: ocPipelineReport,
+			oc_mock_fallback: ocMockFallback,
 		},
 		event: async ({ event }) => {
+			// 1. Observability: collect (pure observer, no side effects on session)
+			await observabilityEventHandler({ event });
+
+			// 2. First-load toast
 			if (event.type === "session.created" && isFirstLoad(config)) {
 				await sdkOps.showToast(
 					"Welcome to OpenCode Autopilot!",
@@ -148,7 +205,7 @@ const plugin: Plugin = async (input) => {
 				);
 			}
 
-			// Fallback event handling (runs for all events)
+			// 3. Fallback event handling
 			if (fallbackConfig.enabled) {
 				await fallbackEventHandler({ event });
 			}
@@ -173,6 +230,12 @@ const plugin: Plugin = async (input) => {
 				await chatMessageHandler(hookInput, output);
 			}
 		},
+		"tool.execute.before": async (
+			input: { tool: string; sessionID: string; callID: string },
+			output: { args: unknown },
+		) => {
+			obsToolBeforeHandler({ ...input, args: output.args });
+		},
 		"tool.execute.after": async (
 			hookInput: {
 				readonly tool: string;
@@ -182,6 +245,10 @@ const plugin: Plugin = async (input) => {
 			},
 			output: { title: string; output: string; metadata: unknown },
 		) => {
+			// Observability: record tool execution (pure observer)
+			obsToolAfterHandler(hookInput, output);
+
+			// Fallback handling
 			if (fallbackConfig.enabled) {
 				await toolExecuteAfterHandler(hookInput, output);
 			}

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