@kodrunhq/opencode-autopilot 1.2.1 → 1.4.0

package/assets/commands/quick.md

@@ -0,0 +1,7 @@
+---
+description: Run a quick task (skip research/architecture, go straight to plan+build+ship)
+---
+
+Invoke the `oc_quick` tool with the following arguments, skipping research and architecture and going straight to plan, build, and ship:
+
+$ARGUMENTS

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kodrunhq/opencode-autopilot",
-	"version": "1.2.1",
+	"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/health/checks.ts

@@ -0,0 +1,125 @@
+import { access } from "node:fs/promises";
+import type { Config } from "@opencode-ai/plugin";
+import { loadConfig } from "../config";
+import { AGENT_NAMES } from "../orchestrator/handlers/types";
+import { getAssetsDir, getGlobalConfigDir } from "../utils/paths";
+import type { HealthResult } from "./types";
+
+/**
+ * Check that the plugin config file exists and passes Zod validation.
+ * loadConfig returns null when the file is missing, and throws on invalid JSON/schema.
+ */
+export async function configHealthCheck(configPath?: string): Promise<HealthResult> {
+	try {
+		const config = await loadConfig(configPath);
+		if (config === null) {
+			return Object.freeze({
+				name: "config-validity",
+				status: "fail" as const,
+				message: "Plugin config file not found",
+			});
+		}
+		return Object.freeze({
+			name: "config-validity",
+			status: "pass" as const,
+			message: `Config v${config.version} loaded and valid`,
+		});
+	} catch (error: unknown) {
+		const msg = error instanceof Error ? error.message : String(error);
+		return Object.freeze({
+			name: "config-validity",
+			status: "fail" as const,
+			message: `Config validation failed: ${msg}`,
+		});
+	}
+}
+
+/** Standard agent names, derived from the agents barrel export. */
+const STANDARD_AGENT_NAMES: readonly string[] = Object.freeze([
+	"researcher",
+	"metaprompter",
+	"documenter",
+	"pr-reviewer",
+	"autopilot",
+]);
+
+/** Pipeline agent names, derived from AGENT_NAMES in the orchestrator. */
+const PIPELINE_AGENT_NAMES: readonly string[] = Object.freeze(Object.values(AGENT_NAMES));
+
+/** All expected agent names (standard + pipeline). */
+const EXPECTED_AGENTS: readonly string[] = Object.freeze([
+	...STANDARD_AGENT_NAMES,
+	...PIPELINE_AGENT_NAMES,
+]);
+
+/**
+ * Check that all expected agents are injected into the OpenCode config.
+ * Requires the OpenCode config object (from the config hook).
+ */
+export async function agentHealthCheck(config: Config | null): Promise<HealthResult> {
+	if (!config?.agent) {
+		return Object.freeze({
+			name: "agent-injection",
+			status: "fail" as const,
+			message: "No OpenCode config or agent map available",
+		});
+	}
+
+	const agentMap = config.agent;
+	const missing = EXPECTED_AGENTS.filter((name) => !(name in agentMap));
+
+	if (missing.length > 0) {
+		return Object.freeze({
+			name: "agent-injection",
+			status: "fail" as const,
+			message: `${missing.length} agent(s) missing: ${missing.join(", ")}`,
+			details: Object.freeze(missing),
+		});
+	}
+
+	return Object.freeze({
+		name: "agent-injection",
+		status: "pass" as const,
+		message: `All ${EXPECTED_AGENTS.length} agents injected`,
+	});
+}
+
+/**
+ * Check that the source and target asset directories exist and are accessible.
+ */
+export async function assetHealthCheck(
+	assetsDir?: string,
+	targetDir?: string,
+): Promise<HealthResult> {
+	const source = assetsDir ?? getAssetsDir();
+	const target = targetDir ?? getGlobalConfigDir();
+
+	try {
+		await access(source);
+	} catch (error: unknown) {
+		const code = (error as NodeJS.ErrnoException).code;
+		const detail = code === "ENOENT" ? "missing" : `inaccessible (${code})`;
+		return Object.freeze({
+			name: "asset-directories",
+			status: "fail" as const,
+			message: `Asset source directory ${detail}: ${source}`,
+		});
+	}
+
+	try {
+		await access(target);
+		return Object.freeze({
+			name: "asset-directories",
+			status: "pass" as const,
+			message: `Asset directories exist: source=${source}, target=${target}`,
+		});
+	} catch (error: unknown) {
+		const code = (error as NodeJS.ErrnoException).code;
+		const detail = code === "ENOENT" ? "missing" : `inaccessible (${code})`;
+		return Object.freeze({
+			name: "asset-directories",
+			status: "fail" as const,
+			message: `Asset target directory ${detail}: ${target}`,
+		});
+	}
+}

package/src/health/index.ts

@@ -0,0 +1,3 @@
+export { agentHealthCheck, assetHealthCheck, configHealthCheck } from "./checks";
+export { runHealthChecks } from "./runner";
+export type { HealthReport, HealthResult } from "./types";

package/src/health/runner.ts

@@ -0,0 +1,56 @@
+import type { Config } from "@opencode-ai/plugin";
+import { agentHealthCheck, assetHealthCheck, configHealthCheck } from "./checks";
+import type { HealthReport, HealthResult } from "./types";
+
+/**
+ * Map a settled promise result to a HealthResult.
+ * Fulfilled results pass through; rejected results become fail entries.
+ */
+function settledToResult(
+	outcome: PromiseSettledResult<HealthResult>,
+	fallbackName: string,
+): HealthResult {
+	if (outcome.status === "fulfilled") {
+		return outcome.value;
+	}
+	const msg = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+	return Object.freeze({
+		name: fallbackName,
+		status: "fail" as const,
+		message: `Check threw unexpectedly: ${msg}`,
+	});
+}
+
+/**
+ * Run all health checks and aggregate into a HealthReport.
+ * Each check runs independently — a failure in one does not skip others.
+ * Uses Promise.allSettled so a throwing check cannot kill the entire report.
+ */
+export async function runHealthChecks(options?: {
+	configPath?: string;
+	openCodeConfig?: Config | null;
+	assetsDir?: string;
+	targetDir?: string;
+}): Promise<HealthReport> {
+	const start = Date.now();
+
+	const settled = await Promise.allSettled([
+		configHealthCheck(options?.configPath),
+		agentHealthCheck(options?.openCodeConfig ?? null),
+		assetHealthCheck(options?.assetsDir, options?.targetDir),
+	]);
+
+	const fallbackNames = ["config-validity", "agent-injection", "asset-directories"];
+	const results: readonly HealthResult[] = Object.freeze(
+		settled.map((outcome, i) => settledToResult(outcome, fallbackNames[i])),
+	);
+
+	const allPassed = results.every((r) => r.status === "pass");
+	const duration = Date.now() - start;
+
+	return Object.freeze({
+		results,
+		allPassed,
+		duration,
+	});
+}

package/src/health/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Health check result for a single diagnostic check.
+ * Immutable — frozen on creation by each check function.
+ */
+export interface HealthResult {
+	readonly name: string;
+	readonly status: "pass" | "fail";
+	readonly message: string;
+	readonly details?: readonly string[];
+}
+
+/**
+ * Aggregated health report from running all checks.
+ * Immutable — frozen on creation by runHealthChecks.
+ */
+export interface HealthReport {
+	readonly results: readonly HealthResult[];
+	readonly allPassed: boolean;
+	readonly duration: number;
+}

package/src/index.ts

@@ -1,7 +1,18 @@
 import type { Config, Plugin } from "@opencode-ai/plugin";
 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,
@@ -21,11 +32,17 @@ import {
 import { ocCreateAgent } from "./tools/create-agent";
 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;
@@ -62,6 +79,20 @@ const plugin: Plugin = async (input) => {
 	const config = await loadConfig();
 	const fallbackConfig = config?.fallback ?? fallbackDefaults;
 
+	// Self-healing health checks on every load (non-blocking, <100ms target)
+	runHealthChecks().catch(() => {
+		// 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) => {
@@ -115,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,
@@ -126,10 +183,20 @@ const plugin: Plugin = async (input) => {
 			oc_phase: ocPhase,
 			oc_plan: ocPlan,
 			oc_orchestrate: ocOrchestrate,
+			oc_doctor: ocDoctor,
+			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!",
@@ -138,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 });
 			}
@@ -163,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;
@@ -172,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,
+	});
+}