@kodrunhq/opencode-autopilot 1.2.1 → 1.4.0

package/src/observability/summary-generator.ts

@@ -0,0 +1,209 @@
+/**
+ * Session summary generator.
+ *
+ * Transforms structured SessionLog data into human-readable markdown summaries
+ * for post-session analysis. All functions are pure (no I/O, no side effects).
+ *
+ * Summaries include: metadata, decisions, errors, fallbacks, model switches,
+ * and a strategic one-paragraph analysis (D-03, D-11, D-42, D-43).
+ */
+
+import type { SessionEvent, SessionLog } from "./types";
+
+/**
+ * Computes session duration in milliseconds from startedAt/endedAt.
+ * Returns 0 when endedAt is null (session still in progress).
+ */
+export function computeDuration(log: SessionLog): number {
+	if (!log.endedAt) return 0;
+	return new Date(log.endedAt).getTime() - new Date(log.startedAt).getTime();
+}
+
+/**
+ * Formats duration in milliseconds to human-readable string.
+ * Uses "Xh Ym" for durations >= 1 hour, "Xm Ys" for >= 1 minute, "Xs" otherwise.
+ */
+export function formatDuration(ms: number): string {
+	const totalSeconds = Math.floor(ms / 1000);
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor((totalSeconds % 3600) / 60);
+	const seconds = totalSeconds % 60;
+
+	if (hours > 0) return `${hours}h ${minutes}m`;
+	if (minutes > 0) return `${minutes}m ${seconds}s`;
+	return `${seconds}s`;
+}
+
+/**
+ * Formats cost as USD string with 4 decimal places.
+ */
+export function formatCost(cost: number): string {
+	return `$${cost.toFixed(4)}`;
+}
+
+/**
+ * Generates a complete markdown summary from a SessionLog.
+ *
+ * Includes sections for: metadata, decisions, errors, fallbacks,
+ * model switches, and strategic summary. Sections are omitted when
+ * no relevant data exists.
+ */
+export function generateSessionSummary(log: SessionLog): string {
+	const sections: string[] = [];
+
+	// Header
+	sections.push(renderHeader(log));
+
+	// Decisions section (conditional)
+	if (log.decisions.length > 0) {
+		sections.push(renderDecisions(log));
+	}
+
+	// Errors section (conditional)
+	const errorEvents = log.events.filter(
+		(e): e is SessionEvent & { type: "error" } => e.type === "error",
+	);
+	if (errorEvents.length > 0) {
+		sections.push(renderErrors(errorEvents, log.errorSummary));
+	}
+
+	// Fallbacks section (conditional)
+	const fallbackEvents = log.events.filter(
+		(e): e is SessionEvent & { type: "fallback" } => e.type === "fallback",
+	);
+	if (fallbackEvents.length > 0) {
+		sections.push(renderFallbacks(fallbackEvents));
+	}
+
+	// Model switches section (conditional)
+	const switchEvents = log.events.filter(
+		(e): e is SessionEvent & { type: "model_switch" } => e.type === "model_switch",
+	);
+	if (switchEvents.length > 0) {
+		sections.push(renderModelSwitches(switchEvents));
+	}
+
+	// Strategic summary (always present, varies by content)
+	sections.push(renderStrategicSummary(log));
+
+	return sections.join("\n\n");
+}
+
+// --- Internal renderers ---
+
+function renderHeader(log: SessionLog): string {
+	const durationMs = computeDuration(log);
+	const durationStr = log.endedAt ? formatDuration(durationMs) : "In progress";
+
+	return [
+		`# Session Summary: ${log.sessionId}`,
+		"",
+		"| Field | Value |",
+		"|-------|-------|",
+		`| Started | ${log.startedAt} |`,
+		`| Ended | ${log.endedAt ?? "In progress"} |`,
+		`| Duration | ${durationStr} |`,
+		`| Events | ${log.events.length} |`,
+		`| Decisions | ${log.decisions.length} |`,
+	].join("\n");
+}
+
+function renderDecisions(log: SessionLog): string {
+	const lines = ["## Decisions", ""];
+
+	for (let i = 0; i < log.decisions.length; i++) {
+		const d = log.decisions[i];
+		lines.push(`${i + 1}. **[${d.phase}] ${d.agent}**: ${d.decision}`);
+		lines.push(`   - _Rationale:_ ${d.rationale}`);
+	}
+
+	return lines.join("\n");
+}
+
+function renderErrors(
+	events: readonly (SessionEvent & { type: "error" })[],
+	errorSummary: Record<string, number>,
+): string {
+	const lines = [
+		"## Errors",
+		"",
+		"| Timestamp | Type | Model | Message |",
+		"|-----------|------|-------|---------|",
+	];
+
+	for (const e of events) {
+		const safeMsg = (e.message ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
+		const safeModel = (e.model ?? "").replace(/\|/g, "\\|");
+		lines.push(`| ${e.timestamp} | ${e.errorType} | ${safeModel} | ${safeMsg} |`);
+	}
+
+	// Error summary counts
+	const summaryEntries = Object.entries(errorSummary);
+	if (summaryEntries.length > 0) {
+		lines.push("");
+		lines.push("**Error Summary:**");
+		for (const [type, count] of summaryEntries) {
+			lines.push(`- ${type}: ${count}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+function renderFallbacks(events: readonly (SessionEvent & { type: "fallback" })[]): string {
+	const lines = [
+		"## Fallbacks",
+		"",
+		"| Timestamp | Failed Model | Next Model | Reason | Success |",
+		"|-----------|-------------|------------|--------|---------|",
+	];
+
+	for (const e of events) {
+		lines.push(
+			`| ${e.timestamp} | ${e.failedModel} | ${e.nextModel} | ${e.reason} | ${e.success ? "Yes" : "No"} |`,
+		);
+	}
+
+	return lines.join("\n");
+}
+
+function renderModelSwitches(events: readonly (SessionEvent & { type: "model_switch" })[]): string {
+	const lines = [
+		"## Model Switches",
+		"",
+		"| Timestamp | From | To | Trigger |",
+		"|-----------|------|----|---------|",
+	];
+
+	for (const e of events) {
+		lines.push(`| ${e.timestamp} | ${e.fromModel} | ${e.toModel} | ${e.trigger} |`);
+	}
+
+	return lines.join("\n");
+}
+
+function renderStrategicSummary(log: SessionLog): string {
+	const errorCount = log.events.filter((e) => e.type === "error").length;
+	const fallbackCount = log.events.filter((e) => e.type === "fallback").length;
+	const durationMs = computeDuration(log);
+	const durationStr = log.endedAt ? formatDuration(durationMs) : "unknown (in progress)";
+
+	const parts: string[] = [];
+	parts.push(
+		`Session ran for ${durationStr} with ${log.events.length} events and ${log.decisions.length} autonomous decisions.`,
+	);
+
+	if (errorCount > 0) {
+		const successfulFallbacks = log.events.filter((e) => e.type === "fallback" && e.success).length;
+		parts.push(
+			`Encountered ${errorCount} errors; ${fallbackCount} fallback attempts (${successfulFallbacks} successful).`,
+		);
+	}
+
+	if (log.decisions.length > 0) {
+		const phases = [...new Set(log.decisions.map((d) => d.phase))];
+		parts.push(`Decisions spanned ${phases.length} phase(s): ${phases.join(", ")}.`);
+	}
+
+	return ["## Summary", "", parts.join(" ")].join("\n");
+}

package/src/observability/token-tracker.ts

@@ -0,0 +1,97 @@
+/**
+ * Token accumulation utilities for session observability.
+ *
+ * Pure functions that accumulate token/cost data from AssistantMessage shapes.
+ * Returns new objects (immutable, per CLAUDE.md) -- never mutates inputs.
+ *
+ * @module
+ */
+
+/**
+ * Aggregated token and cost data for a session.
+ */
+export interface TokenAggregate {
+	readonly inputTokens: number;
+	readonly outputTokens: number;
+	readonly reasoningTokens: number;
+	readonly cacheReadTokens: number;
+	readonly cacheWriteTokens: number;
+	readonly totalCost: number;
+	readonly messageCount: number;
+}
+
+/**
+ * Returns a zero-initialized TokenAggregate.
+ */
+export function createEmptyTokenAggregate(): TokenAggregate {
+	return Object.freeze({
+		inputTokens: 0,
+		outputTokens: 0,
+		reasoningTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		totalCost: 0,
+		messageCount: 0,
+	});
+}
+
+/**
+ * Accumulates token/cost data into a new TokenAggregate.
+ * Missing fields in `incoming` default to 0.
+ * Returns a new frozen object (immutable).
+ *
+ * @param current - The current aggregate to add onto
+ * @param incoming - Partial aggregate with fields to add
+ */
+export function accumulateTokens(
+	current: TokenAggregate,
+	incoming: Partial<TokenAggregate>,
+): TokenAggregate {
+	return Object.freeze({
+		inputTokens: current.inputTokens + (incoming.inputTokens ?? 0),
+		outputTokens: current.outputTokens + (incoming.outputTokens ?? 0),
+		reasoningTokens: current.reasoningTokens + (incoming.reasoningTokens ?? 0),
+		cacheReadTokens: current.cacheReadTokens + (incoming.cacheReadTokens ?? 0),
+		cacheWriteTokens: current.cacheWriteTokens + (incoming.cacheWriteTokens ?? 0),
+		totalCost: current.totalCost + (incoming.totalCost ?? 0),
+		messageCount: current.messageCount + (incoming.messageCount ?? 0),
+	});
+}
+
+/**
+ * Shape of token data within an AssistantMessage from the OpenCode SDK.
+ */
+export interface AssistantMessageTokens {
+	readonly tokens: {
+		readonly input: number;
+		readonly output: number;
+		readonly reasoning: number;
+		readonly cache: {
+			readonly read: number;
+			readonly write: number;
+		};
+	};
+	readonly cost: number;
+}
+
+/**
+ * Extracts token/cost data from an AssistantMessage shape and accumulates
+ * it into a new TokenAggregate. Increments messageCount by 1.
+ *
+ * @param current - The current aggregate to add onto
+ * @param msg - The AssistantMessage-shaped object with tokens and cost
+ */
+export function accumulateTokensFromMessage(
+	current: TokenAggregate,
+	msg: AssistantMessageTokens,
+): TokenAggregate {
+	return accumulateTokens(current, {
+		inputTokens: msg.tokens.input ?? 0,
+		outputTokens: msg.tokens.output ?? 0,
+		reasoningTokens: msg.tokens.reasoning ?? 0,
+		cacheReadTokens: msg.tokens.cache.read ?? 0,
+		cacheWriteTokens: msg.tokens.cache.write ?? 0,
+		totalCost: msg.cost ?? 0,
+		messageCount: 1,
+	});
+}

package/src/observability/types.ts

@@ -0,0 +1,24 @@
+import type { z } from "zod";
+import type {
+	baseEventSchema,
+	decisionEventSchema,
+	errorEventSchema,
+	fallbackEventSchema,
+	loggingConfigSchema,
+	modelSwitchEventSchema,
+	sessionDecisionSchema,
+	sessionEventSchema,
+	sessionLogSchema,
+} from "./schemas";
+
+export type SessionEventType = "fallback" | "error" | "decision" | "model_switch";
+
+export type BaseEvent = z.infer<typeof baseEventSchema>;
+export type FallbackEvent = z.infer<typeof fallbackEventSchema>;
+export type ErrorEvent = z.infer<typeof errorEventSchema>;
+export type DecisionEvent = z.infer<typeof decisionEventSchema>;
+export type ModelSwitchEvent = z.infer<typeof modelSwitchEventSchema>;
+export type SessionEvent = z.infer<typeof sessionEventSchema>;
+export type LoggingConfig = z.infer<typeof loggingConfigSchema>;
+export type SessionDecision = z.infer<typeof sessionDecisionSchema>;
+export type SessionLog = z.infer<typeof sessionLogSchema>;

package/src/tools/configure.ts

@@ -85,15 +85,25 @@ interface ConfigureArgs {
 
 /**
  * Discover available models from the stored provider data.
- * Returns a map of provider ID -> list of "providerId/modelId" strings.
+ * Returns a map of provider ID -> list of fully-qualified model ID strings.
+ *
+ * Uses the model's own `id` field (which may contain sub-provider paths like
+ * "anthropic/claude-opus-4-6" for a Zen provider) to construct the full
+ * "provider/model" path. This ensures Zen-proxied models display as
+ * "zen/anthropic/claude-opus-4-6" matching OpenCode's native `/models` output.
  */
 function discoverAvailableModels(): Map<string, string[]> {
 	const modelsByProvider = new Map<string, string[]>();
 
 	for (const provider of availableProviders) {
 		const modelIds: string[] = [];
-		for (const modelKey of Object.keys(provider.models)) {
-			modelIds.push(`${provider.id}/${modelKey}`);
+		for (const [modelKey, modelData] of Object.entries(provider.models)) {
+			// Prefer the model's id field — it carries sub-provider paths
+			// (e.g. "anthropic/claude-opus-4-6" under a "zen" provider).
+			// Fall back to the record key when the id is absent or empty.
+			const modelId = modelData.id || modelKey;
+			const fullId = `${provider.id}/${modelId}`;
+			modelIds.push(fullId);
 		}
 		if (modelIds.length > 0) {
 			modelsByProvider.set(provider.id, modelIds);

package/src/tools/doctor.ts

@@ -0,0 +1,111 @@
+import type { Config } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { runHealthChecks } from "../health/runner";
+import type { HealthResult } from "../health/types";
+
+/**
+ * A single check in the doctor report, with an optional fix suggestion.
+ */
+interface DoctorCheck {
+	readonly name: string;
+	readonly status: "pass" | "fail";
+	readonly message: string;
+	readonly fixSuggestion: string | null;
+}
+
+/**
+ * Options for doctorCore — all optional for testability.
+ */
+interface DoctorOptions {
+	readonly configPath?: string;
+	readonly openCodeConfig?: Config | null;
+	readonly assetsDir?: string;
+	readonly targetDir?: string;
+}
+
+/**
+ * Map check names to actionable fix suggestions (per D-11).
+ */
+const FIX_SUGGESTIONS: Readonly<Record<string, string>> = Object.freeze({
+	"config-validity":
+		"Run /oc-configure to reconfigure, or delete ~/.config/opencode/opencode-autopilot.json to reset",
+	"agent-injection": "Restart OpenCode to trigger agent re-injection via config hook",
+	"asset-directories": "Restart OpenCode to trigger asset reinstallation",
+});
+
+function getFixSuggestion(checkName: string): string {
+	return FIX_SUGGESTIONS[checkName] ?? "Restart OpenCode to trigger auto-repair";
+}
+
+function formatCheck(result: HealthResult): DoctorCheck {
+	return Object.freeze({
+		name: result.name,
+		status: result.status,
+		message: result.message,
+		fixSuggestion: result.status === "fail" ? getFixSuggestion(result.name) : null,
+	});
+}
+
+/**
+ * Build human-readable pass/fail display text (like `brew doctor` output).
+ */
+function buildDisplayText(checks: readonly DoctorCheck[], duration: number): string {
+	const lines = checks.map((c) => {
+		const icon = c.status === "pass" ? "OK" : "FAIL";
+		const line = `[${icon}] ${c.name}: ${c.message}`;
+		return c.fixSuggestion ? `${line}\n     Fix: ${c.fixSuggestion}` : line;
+	});
+	lines.push("", `Completed in ${duration}ms`);
+	return lines.join("\n");
+}
+
+/**
+ * Core diagnostic function — runs all health checks and returns a structured
+ * JSON report. Follows the *Core + tool() wrapper pattern per CLAUDE.md.
+ *
+ * The hook-registration check is informational: if oc_doctor is callable,
+ * the plugin is registered. Always passes.
+ */
+export async function doctorCore(options?: DoctorOptions): Promise<string> {
+	const report = await runHealthChecks({
+		configPath: options?.configPath,
+		openCodeConfig: options?.openCodeConfig,
+		assetsDir: options?.assetsDir,
+		targetDir: options?.targetDir,
+	});
+
+	// Map health results to doctor checks with fix suggestions
+	const healthChecks = report.results.map(formatCheck);
+
+	// Hook-registration check: if oc_doctor is callable, hooks are registered
+	const hookCheck: DoctorCheck = Object.freeze({
+		name: "hook-registration",
+		status: "pass" as const,
+		message: "Plugin tools registered (oc_doctor callable)",
+		fixSuggestion: null,
+	});
+
+	const allChecks = [...healthChecks, hookCheck];
+	const allPassed = report.allPassed && hookCheck.status === "pass";
+	const displayText = buildDisplayText(allChecks, report.duration);
+
+	return JSON.stringify({
+		action: "doctor",
+		checks: allChecks,
+		allPassed,
+		displayText,
+		duration: report.duration,
+	});
+}
+
+// --- Tool wrapper ---
+
+export const ocDoctor = tool({
+	description:
+		"Run plugin health diagnostics. Reports pass/fail status for config, agents, " +
+		"assets, and hooks. Like `brew doctor` for opencode-autopilot.",
+	args: {},
+	async execute() {
+		return doctorCore();
+	},
+});

package/src/tools/logs.ts

@@ -0,0 +1,178 @@
+/**
+ * oc_logs tool - Session log dashboard.
+ *
+ * Provides three modes:
+ * - "list": List all session logs with summary info
+ * - "detail": View full session log with markdown summary
+ * - "search": Filter events by type and time range
+ *
+ * Follows the *Core + tool() wrapper pattern per CLAUDE.md.
+ * Returns JSON with displayText field following oc_doctor pattern.
+ *
+ * @module
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+import {
+	listSessionLogs,
+	readLatestSessionLog,
+	readSessionLog,
+	searchEvents,
+} from "../observability/log-reader";
+import { generateSessionSummary } from "../observability/summary-generator";
+
+/**
+ * Options for logsCore search/detail modes.
+ */
+interface LogsOptions {
+	readonly sessionID?: string;
+	readonly eventType?: string;
+	readonly after?: string;
+	readonly before?: string;
+}
+
+/**
+ * Formats a session list as a human-readable table.
+ */
+function formatSessionTable(
+	sessions: readonly {
+		readonly sessionId: string;
+		readonly startedAt: string;
+		readonly endedAt: string | null;
+		readonly eventCount: number;
+		readonly decisionCount: number;
+		readonly errorCount: number;
+	}[],
+): string {
+	if (sessions.length === 0) {
+		return "No session logs found.";
+	}
+
+	const lines = [
+		"Session Logs",
+		"",
+		"| Session ID | Started | Events | Decisions | Errors |",
+		"|------------|---------|--------|-----------|--------|",
+	];
+
+	for (const s of sessions) {
+		const started = s.startedAt.replace("T", " ").replace(/\.\d+Z$/, "Z");
+		lines.push(
+			`| ${s.sessionId} | ${started} | ${s.eventCount} | ${s.decisionCount} | ${s.errorCount} |`,
+		);
+	}
+
+	lines.push("", `${sessions.length} session(s) total`);
+	return lines.join("\n");
+}
+
+/**
+ * Core function for the oc_logs tool.
+ *
+ * @param mode - "list", "detail", or "search"
+ * @param options - Optional filters (sessionID, eventType, after, before)
+ * @param logsDir - Optional override for logs directory (for testing)
+ */
+export async function logsCore(
+	mode: "list" | "detail" | "search",
+	options?: LogsOptions,
+	logsDir?: string,
+): Promise<string> {
+	switch (mode) {
+		case "list": {
+			const sessions = await listSessionLogs(logsDir);
+
+			return JSON.stringify({
+				action: "logs_list",
+				sessions,
+				displayText: formatSessionTable(sessions),
+			});
+		}
+
+		case "detail": {
+			const log = options?.sessionID
+				? await readSessionLog(options.sessionID, logsDir)
+				: await readLatestSessionLog(logsDir);
+
+			if (!log) {
+				const target = options?.sessionID
+					? `Session "${options.sessionID}" not found.`
+					: "No session logs found.";
+				return JSON.stringify({
+					action: "error",
+					message: target,
+				});
+			}
+
+			const summary = generateSessionSummary(log);
+
+			return JSON.stringify({
+				action: "logs_detail",
+				sessionLog: log,
+				summary,
+				displayText: summary,
+			});
+		}
+
+		case "search": {
+			const log = options?.sessionID
+				? await readSessionLog(options.sessionID, logsDir)
+				: await readLatestSessionLog(logsDir);
+
+			if (!log) {
+				const target = options?.sessionID
+					? `Session "${options.sessionID}" not found.`
+					: "No session logs found.";
+				return JSON.stringify({
+					action: "error",
+					message: target,
+				});
+			}
+
+			const filtered = searchEvents(log.events, {
+				type: options?.eventType,
+				after: options?.after,
+				before: options?.before,
+			});
+
+			const displayLines = [
+				`Search Results (${filtered.length} event(s))`,
+				"",
+				...filtered.map((e) => `[${e.timestamp}] ${e.type}: ${JSON.stringify(e)}`),
+			];
+
+			return JSON.stringify({
+				action: "logs_search",
+				sessionId: log.sessionId,
+				events: filtered,
+				displayText: displayLines.join("\n"),
+			});
+		}
+	}
+}
+
+// --- Tool wrapper ---
+
+export const ocLogs = tool({
+	description:
+		"View session logs. Modes: 'list' shows all sessions, 'detail' shows full log with " +
+		"summary, 'search' filters events by type/time. Use to inspect session history and errors.",
+	args: {
+		mode: z.enum(["list", "detail", "search"]).describe("View mode: list, detail, or search"),
+		sessionID: z
+			.string()
+			.regex(/^[a-zA-Z0-9_-]{1,256}$/)
+			.optional()
+			.describe("Session ID to view (uses latest if omitted)"),
+		eventType: z.string().optional().describe("Filter events by type (for search mode)"),
+		after: z.string().optional().describe("Only events after this ISO timestamp (for search mode)"),
+		before: z
+			.string()
+			.optional()
+			.describe("Only events before this ISO timestamp (for search mode)"),
+	},
+	async execute({ mode, sessionID, eventType, after, before }) {
+		return logsCore(mode, { sessionID, eventType, after, before });
+	},
+});