@kodrunhq/opencode-autopilot 1.3.0 → 1.4.0

package/src/observability/schemas.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+
+export const baseEventSchema = z.object({
+	timestamp: z.string().max(128),
+	sessionId: z
+		.string()
+		.max(256)
+		.regex(/^[a-zA-Z0-9_-]{1,256}$/, "Invalid session ID"),
+	type: z.enum(["fallback", "error", "decision", "model_switch"]),
+});
+
+export const fallbackEventSchema = baseEventSchema.extend({
+	type: z.literal("fallback"),
+	failedModel: z.string().max(256),
+	nextModel: z.string().max(256),
+	reason: z.string().max(1024),
+	success: z.boolean(),
+});
+
+export const errorEventSchema = baseEventSchema.extend({
+	type: z.literal("error"),
+	errorType: z.enum([
+		"rate_limit",
+		"quota_exceeded",
+		"service_unavailable",
+		"missing_api_key",
+		"model_not_found",
+		"content_filter",
+		"context_length",
+		"unknown",
+	]),
+	model: z.string().max(256),
+	message: z.string().max(4096),
+	statusCode: z.number().optional(),
+});
+
+export const decisionEventSchema = baseEventSchema.extend({
+	type: z.literal("decision"),
+	phase: z.string().max(128),
+	agent: z.string().max(128),
+	decision: z.string().max(2048),
+	rationale: z.string().max(2048),
+});
+
+export const modelSwitchEventSchema = baseEventSchema.extend({
+	type: z.literal("model_switch"),
+	fromModel: z.string().max(256),
+	toModel: z.string().max(256),
+	trigger: z.enum(["fallback", "config", "user"]),
+});
+
+export const sessionEventSchema = z.discriminatedUnion("type", [
+	fallbackEventSchema,
+	errorEventSchema,
+	decisionEventSchema,
+	modelSwitchEventSchema,
+]);
+
+export const loggingConfigSchema = z.object({
+	enabled: z.boolean().default(true),
+	retentionDays: z.number().min(1).max(365).default(30),
+});
+
+export const sessionDecisionSchema = z.object({
+	timestamp: z.string().optional(),
+	phase: z.string(),
+	agent: z.string(),
+	decision: z.string(),
+	rationale: z.string(),
+});
+
+export const sessionLogSchema = z.object({
+	schemaVersion: z.number().default(1),
+	sessionId: z.string().regex(/^[a-zA-Z0-9_-]{1,256}$/, "Invalid session ID"),
+	startedAt: z.string(),
+	endedAt: z.string().nullable().default(null),
+	events: z.array(sessionEventSchema),
+	decisions: z.array(sessionDecisionSchema).default([]),
+	errorSummary: z.record(z.string(), z.number()).default({}),
+});
+
+// Pre-compute defaults for Zod v4 nested default compatibility
+export const loggingDefaults = loggingConfigSchema.parse({});

package/src/observability/session-logger.ts

@@ -0,0 +1,63 @@
+import { appendFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ensureDir, isEnoentError } from "../utils/fs-helpers";
+import { getGlobalConfigDir } from "../utils/paths";
+import { sessionEventSchema } from "./schemas";
+import type { SessionEvent } from "./types";
+
+/**
+ * Returns the global logs directory path.
+ * Logs are user-scoped, not project-scoped (D-08, D-09).
+ */
+export function getLogsDir(): string {
+	return join(getGlobalConfigDir(), "logs");
+}
+
+/**
+ * Returns the JSONL log file path for a given session ID.
+ */
+function getSessionLogPath(sessionId: string, logsDir?: string): string {
+	return join(logsDir ?? getLogsDir(), `${sessionId}.jsonl`);
+}
+
+/**
+ * Logs a structured event to the session's JSONL log file.
+ * Validates the event against the Zod schema before writing.
+ * Creates the logs directory if it does not exist.
+ *
+ * @param event - The session event to log (D-02, D-04-D-07)
+ * @param logsDir - Optional override for the logs directory (for testing)
+ */
+export async function logEvent(event: SessionEvent, logsDir?: string): Promise<void> {
+	// Validate against schema -- throws on invalid events
+	const validated = sessionEventSchema.parse(event);
+
+	const dir = logsDir ?? getLogsDir();
+	await ensureDir(dir);
+
+	const logPath = getSessionLogPath(validated.sessionId, dir);
+	const line = `${JSON.stringify(validated)}\n`;
+
+	await appendFile(logPath, line, "utf-8");
+}
+
+/**
+ * Reads and parses all events from a session's JSONL log file.
+ * Returns an empty array if the session log does not exist.
+ *
+ * @param sessionId - The session ID to read logs for
+ * @param logsDir - Optional override for the logs directory (for testing)
+ */
+export async function getSessionLog(sessionId: string, logsDir?: string): Promise<SessionEvent[]> {
+	const logPath = getSessionLogPath(sessionId, logsDir);
+
+	try {
+		const content = await readFile(logPath, "utf-8");
+		const lines = content.trim().split("\n").filter(Boolean);
+
+		return lines.map((line) => sessionEventSchema.parse(JSON.parse(line)));
+	} catch (error: unknown) {
+		if (isEnoentError(error)) return [];
+		throw error;
+	}
+}

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