@kodrunhq/opencode-autopilot 1.3.0 → 1.5.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/orchestrator/skill-injection.ts

@@ -10,6 +10,12 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { sanitizeTemplateContent } from "../review/sanitize";
+import {
+	buildMultiSkillContext,
+	detectProjectStackTags,
+	filterSkillsByStack,
+} from "../skills/adaptive-injector";
+import { loadAllSkills } from "../skills/loader";
 import { isEnoentError } from "../utils/fs-helpers";
 
 const MAX_SKILL_LENGTH = 2048;
@@ -50,3 +56,35 @@ export function buildSkillContext(skillContent: string): string {
 	const header = "Coding standards for this project (follow these conventions):";
 	return `\n\n${header}\n${sanitized}`;
 }
+
+// --- Adaptive multi-skill loading ---
+
+/**
+ * Load and inject all matching skills for the current project.
+ * Detects project stack from manifest files, filters skills by stack,
+ * resolves dependencies, and builds a token-budgeted context string.
+ *
+ * Returns empty string on any error (best-effort, same as lesson injection).
+ */
+export async function loadAdaptiveSkillContext(
+	baseDir: string,
+	projectRoot: string,
+	tokenBudget?: number,
+): Promise<string> {
+	try {
+		const skillsDir = join(baseDir, "skills");
+		const [allSkills, projectTags] = await Promise.all([
+			loadAllSkills(skillsDir),
+			detectProjectStackTags(projectRoot),
+		]);
+
+		if (allSkills.size === 0) return "";
+
+		const matchingSkills = filterSkillsByStack(allSkills, projectTags);
+		return buildMultiSkillContext(matchingSkills, tokenBudget);
+	} catch (error: unknown) {
+		// Best-effort for I/O errors; re-throw programmer errors
+		if (error instanceof TypeError || error instanceof RangeError) throw error;
+		return "";
+	}
+}

package/src/review/sanitize.ts

@@ -4,5 +4,5 @@
  * {{PRIOR_FINDINGS}} or similar tokens that get substituted in a subsequent .replace() call.
  */
 export function sanitizeTemplateContent(content: string): string {
-	return content.replace(/\{\{[A-Z_]+\}\}/g, "[REDACTED]");
+	return content.replace(/\{\{[\w]+\}\}/gi, "[REDACTED]");
 }

package/src/skills/adaptive-injector.ts

@@ -0,0 +1,122 @@
+/**
+ * Adaptive skill injection: project stack detection, skill filtering, and
+ * multi-skill context building with dependency ordering and token budget.
+ *
+ * Complements detectStackTags (which works on file paths from git diff)
+ * by checking the project root for manifest files. This enables skill
+ * filtering even before any git diff is available.
+ */
+
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { sanitizeTemplateContent } from "../review/sanitize";
+import { resolveDependencyOrder } from "./dependency-resolver";
+import type { LoadedSkill } from "./loader";
+
+const DEFAULT_TOKEN_BUDGET = 8000;
+/** Rough estimate: 1 token ~ 4 chars */
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Manifest files that indicate project stack.
+ * Checks project root for these files to detect the stack.
+ */
+const MANIFEST_TAGS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+	"package.json": Object.freeze(["javascript"]),
+	"tsconfig.json": Object.freeze(["typescript"]),
+	"bunfig.toml": Object.freeze(["bun", "typescript"]),
+	"bun.lockb": Object.freeze(["bun"]),
+	"go.mod": Object.freeze(["go"]),
+	"Cargo.toml": Object.freeze(["rust"]),
+	"pyproject.toml": Object.freeze(["python"]),
+	"requirements.txt": Object.freeze(["python"]),
+	Pipfile: Object.freeze(["python"]),
+	Gemfile: Object.freeze(["ruby"]),
+});
+
+/**
+ * Detect project stack tags from manifest files in the project root.
+ * Complements detectStackTags (which works on file paths from git diff).
+ */
+export async function detectProjectStackTags(projectRoot: string): Promise<readonly string[]> {
+	const results = await Promise.all(
+		Object.entries(MANIFEST_TAGS).map(async ([manifest, manifestTags]) => {
+			try {
+				await access(join(projectRoot, manifest));
+				return [...manifestTags];
+			} catch {
+				return [];
+			}
+		}),
+	);
+
+	return [...new Set(results.flat())];
+}
+
+/**
+ * Filter skills by detected stack tags.
+ * Skills with empty stacks are ALWAYS included (methodology skills).
+ * Skills with non-empty stacks are included only if at least one tag matches.
+ */
+export function filterSkillsByStack(
+	skills: ReadonlyMap<string, LoadedSkill>,
+	tags: readonly string[],
+): ReadonlyMap<string, LoadedSkill> {
+	const tagSet = new Set(tags);
+	const filtered = new Map<string, LoadedSkill>();
+
+	for (const [name, skill] of skills) {
+		if (skill.frontmatter.stacks.length === 0) {
+			filtered.set(name, skill);
+		} else if (skill.frontmatter.stacks.some((s) => tagSet.has(s))) {
+			filtered.set(name, skill);
+		}
+	}
+
+	return filtered;
+}
+
+/**
+ * Build multi-skill context string with dependency ordering and token budget.
+ * Skills are ordered by dependency (prerequisites first), then concatenated
+ * until the token budget is exhausted.
+ */
+export function buildMultiSkillContext(
+	skills: ReadonlyMap<string, LoadedSkill>,
+	tokenBudget: number = DEFAULT_TOKEN_BUDGET,
+): string {
+	if (skills.size === 0) return "";
+
+	// Resolve dependency order
+	const depMap = new Map(
+		[...skills.entries()].map(([name, skill]) => [name, { requires: skill.frontmatter.requires }]),
+	);
+	const { ordered, cycles } = resolveDependencyOrder(depMap);
+
+	// Skip cycle participants (graceful degradation)
+	const cycleSet = new Set(cycles);
+	const validOrder = ordered.filter((name) => !cycleSet.has(name));
+
+	// Build context with token budget enforcement
+	const charBudget = tokenBudget * CHARS_PER_TOKEN;
+	let totalChars = 0;
+	const sections: string[] = [];
+
+	for (const name of validOrder) {
+		const skill = skills.get(name);
+		if (!skill) continue;
+
+		const collapsed = skill.content.replace(/[\r\n]+/g, " ");
+		const header = `[Skill: ${name}]\n`;
+		const separator = sections.length > 0 ? 2 : 0; // "\n\n"
+		const sectionCost = collapsed.length + header.length + separator;
+		if (totalChars + sectionCost > charBudget) break;
+
+		const sanitized = sanitizeTemplateContent(collapsed);
+		sections.push(`${header}${sanitized}`);
+		totalChars += sectionCost;
+	}
+
+	if (sections.length === 0) return "";
+	return `\n\nSkills context (follow these conventions and methodologies):\n${sections.join("\n\n")}`;
+}