@kodrunhq/opencode-autopilot 1.3.0 → 1.5.0

package/src/tools/pipeline-report.ts

@@ -0,0 +1,148 @@
+/**
+ * oc_pipeline_report tool - Decision trace with phase-by-phase breakdown.
+ *
+ * Reads a session log and produces a read-only report showing:
+ * - Phase-by-phase decision timeline
+ * - Per-phase decision count
+ * - Decisions with agent and rationale context
+ *
+ * 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 { readLatestSessionLog, readSessionLog } from "../observability/log-reader";
+import { computeDuration, formatDuration } from "../observability/summary-generator";
+import type { SessionLog } from "../observability/types";
+
+/**
+ * A decision entry within a phase section of the report.
+ */
+interface ReportDecision {
+	readonly agent: string;
+	readonly decision: string;
+	readonly rationale: string;
+}
+
+/**
+ * A phase section in the pipeline report.
+ */
+interface ReportPhase {
+	readonly phase: string;
+	readonly decisions: readonly ReportDecision[];
+}
+
+/**
+ * Groups decisions by phase, preserving insertion order.
+ */
+function groupDecisionsByPhase(log: SessionLog): readonly ReportPhase[] {
+	const phaseOrder: string[] = [];
+	const phaseMap = new Map<string, ReportDecision[]>();
+
+	for (const d of log.decisions) {
+		if (!phaseMap.has(d.phase)) {
+			phaseOrder.push(d.phase);
+			phaseMap.set(d.phase, []);
+		}
+		const decisions = phaseMap.get(d.phase);
+		decisions?.push({
+			agent: d.agent,
+			decision: d.decision,
+			rationale: d.rationale,
+		});
+	}
+
+	return phaseOrder.map((phase) => ({
+		phase,
+		decisions: phaseMap.get(phase) ?? [],
+	}));
+}
+
+/**
+ * Builds the displayText report for the pipeline report.
+ */
+function buildDisplayText(
+	log: SessionLog,
+	phases: readonly ReportPhase[],
+	durationMs: number,
+): string {
+	const lines: string[] = [];
+
+	// Header
+	const durationStr = log.endedAt ? formatDuration(durationMs) : "In progress";
+	lines.push(`Pipeline Report: ${log.sessionId}`);
+	lines.push(`Duration: ${durationStr}`);
+	lines.push(`Total Decisions: ${log.decisions.length}`);
+	lines.push("");
+
+	if (phases.length === 0) {
+		lines.push("No decisions recorded in this session.");
+		return lines.join("\n");
+	}
+
+	// Phase-by-phase breakdown
+	for (const phase of phases) {
+		lines.push(`--- ${phase.phase} (${phase.decisions.length} decision(s)) ---`);
+		for (const d of phase.decisions) {
+			lines.push(`  [${d.agent}] ${d.decision}`);
+			lines.push(`    Rationale: ${d.rationale}`);
+		}
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Core function for the oc_pipeline_report tool.
+ *
+ * @param sessionID - Optional session ID (uses latest if omitted)
+ * @param logsDir - Optional override for logs directory (for testing)
+ */
+export async function pipelineReportCore(sessionID?: string, logsDir?: string): Promise<string> {
+	const log = sessionID
+		? await readSessionLog(sessionID, logsDir)
+		: await readLatestSessionLog(logsDir);
+
+	if (!log) {
+		const target = sessionID ? `Session "${sessionID}" not found.` : "No session logs found.";
+		return JSON.stringify({
+			action: "error",
+			message: target,
+		});
+	}
+
+	const durationMs = computeDuration(log);
+	const phases = groupDecisionsByPhase(log);
+	const totalDecisions = log.decisions.length;
+	const displayText = buildDisplayText(log, phases, durationMs);
+
+	return JSON.stringify({
+		action: "pipeline_report",
+		sessionId: log.sessionId,
+		phases,
+		totalDecisions,
+		displayText,
+	});
+}
+
+// --- Tool wrapper ---
+
+export const ocPipelineReport = tool({
+	description:
+		"View pipeline decision trace. Shows phase-by-phase breakdown of all autonomous decisions " +
+		"with agent and rationale. Read-only report for post-session analysis.",
+	args: {
+		sessionID: z
+			.string()
+			.regex(/^[a-zA-Z0-9_-]{1,256}$/)
+			.optional()
+			.describe("Session ID to view (uses latest if omitted)"),
+	},
+	async execute({ sessionID }) {
+		return pipelineReportCore(sessionID);
+	},
+});

package/src/tools/session-stats.ts

@@ -0,0 +1,185 @@
+/**
+ * oc_session_stats tool - Event counts, decisions, errors, and per-phase breakdown.
+ *
+ * Reads a session log and computes:
+ * - Event count totals
+ * - Decision count and per-phase grouping
+ * - Error summary by type with per-phase attribution
+ * - Session duration
+ * - Per-phase breakdown (when decisions span multiple phases)
+ *
+ * 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 { readLatestSessionLog, readSessionLog } from "../observability/log-reader";
+import { computeDuration, formatDuration } from "../observability/summary-generator";
+import type { SessionLog } from "../observability/types";
+
+/**
+ * Per-phase breakdown entry.
+ */
+interface PhaseBreakdownEntry {
+	readonly phase: string;
+	readonly decisionCount: number;
+	readonly errorCount: number;
+}
+
+/**
+ * Computes per-phase breakdown from session log decisions and events.
+ * Groups decisions by phase and counts errors per phase time window.
+ *
+ * Error-to-phase mapping: for each error event, find the phase whose
+ * decision time window (first to last decision timestamp) contains the
+ * error timestamp. Unmatched errors are not attributed to any phase
+ * (they still appear in the overall errorSummary).
+ */
+function computePhaseBreakdown(log: SessionLog): readonly PhaseBreakdownEntry[] {
+	const phaseMap = new Map<string, { decisions: number; errors: number }>();
+
+	// Collect per-phase time windows from decisions
+	const phaseWindows = new Map<string, { start: string; end: string }>();
+
+	for (const d of log.decisions) {
+		const existing = phaseMap.get(d.phase) ?? { decisions: 0, errors: 0 };
+		phaseMap.set(d.phase, { ...existing, decisions: existing.decisions + 1 });
+
+		const ts = d.timestamp ?? "";
+		if (!ts) continue; // Skip decisions without timestamps — cannot build time windows
+		const window = phaseWindows.get(d.phase);
+		if (!window) {
+			phaseWindows.set(d.phase, { start: ts, end: ts });
+		} else {
+			if (ts < window.start) phaseWindows.set(d.phase, { ...window, start: ts });
+			if (ts > window.end) phaseWindows.set(d.phase, { ...window, end: ts });
+		}
+	}
+
+	// Map errors to phases by timestamp overlap with phase time windows
+	for (const e of log.events) {
+		if (e.type === "error") {
+			for (const [phase, window] of phaseWindows) {
+				if (e.timestamp >= window.start && e.timestamp <= window.end) {
+					const data = phaseMap.get(phase);
+					if (data) {
+						phaseMap.set(phase, { ...data, errors: data.errors + 1 });
+					}
+					break;
+				}
+			}
+		}
+	}
+
+	const result: PhaseBreakdownEntry[] = [];
+	for (const [phase, data] of phaseMap) {
+		result.push({
+			phase,
+			decisionCount: data.decisions,
+			errorCount: data.errors,
+		});
+	}
+
+	return result;
+}
+
+/**
+ * Builds the displayText report for session stats.
+ */
+function buildDisplayText(
+	log: SessionLog,
+	durationMs: number,
+	phaseBreakdown: readonly PhaseBreakdownEntry[],
+): string {
+	const lines: string[] = [];
+
+	// Header
+	lines.push(`Session Stats: ${log.sessionId}`);
+	lines.push("");
+
+	// Duration
+	const durationStr = log.endedAt ? formatDuration(durationMs) : "In progress";
+	lines.push(`Duration: ${durationStr}`);
+	lines.push(`Events: ${log.events.length}`);
+	lines.push(`Decisions: ${log.decisions.length}`);
+	lines.push("");
+
+	// Error summary
+	const errorEntries = Object.entries(log.errorSummary);
+	if (errorEntries.length > 0) {
+		lines.push("Error Summary:");
+		for (const [type, count] of errorEntries) {
+			lines.push(`  ${type}: ${count}`);
+		}
+		lines.push("");
+	}
+
+	// Per-phase breakdown (when phases exist)
+	if (phaseBreakdown.length > 0) {
+		lines.push("Phase Breakdown:");
+		lines.push("| Phase | Decisions | Errors |");
+		lines.push("|-------|-----------|--------|");
+		for (const p of phaseBreakdown) {
+			lines.push(`| ${p.phase} | ${p.decisionCount} | ${p.errorCount} |`);
+		}
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Core function for the oc_session_stats tool.
+ *
+ * @param sessionID - Optional session ID (uses latest if omitted)
+ * @param logsDir - Optional override for logs directory (for testing)
+ */
+export async function sessionStatsCore(sessionID?: string, logsDir?: string): Promise<string> {
+	const log = sessionID
+		? await readSessionLog(sessionID, logsDir)
+		: await readLatestSessionLog(logsDir);
+
+	if (!log) {
+		const target = sessionID ? `Session "${sessionID}" not found.` : "No session logs found.";
+		return JSON.stringify({
+			action: "error",
+			message: target,
+		});
+	}
+
+	const durationMs = computeDuration(log);
+	const phaseBreakdown = computePhaseBreakdown(log);
+	const displayText = buildDisplayText(log, durationMs, phaseBreakdown);
+
+	return JSON.stringify({
+		action: "session_stats",
+		sessionId: log.sessionId,
+		duration: durationMs,
+		eventCount: log.events.length,
+		decisionCount: log.decisions.length,
+		errorSummary: log.errorSummary,
+		phaseBreakdown,
+		displayText,
+	});
+}
+
+// --- Tool wrapper ---
+
+export const ocSessionStats = tool({
+	description:
+		"View session statistics including event counts, decisions, errors, and per-phase breakdown. " +
+		"Shows duration, error summary, and phase-by-phase activity.",
+	args: {
+		sessionID: z
+			.string()
+			.regex(/^[a-zA-Z0-9_-]{1,256}$/)
+			.optional()
+			.describe("Session ID to view (uses latest if omitted)"),
+	},
+	async execute({ sessionID }) {
+		return sessionStatsCore(sessionID);
+	},
+});

package/src/tools/stocktake.ts

@@ -0,0 +1,170 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tool } from "@opencode-ai/plugin";
+import { lintAgent, lintCommand, lintSkill } from "../skills/linter";
+import { getAssetsDir, getGlobalConfigDir } from "../utils/paths";
+
+interface StocktakeArgs {
+	readonly lint?: boolean;
+}
+
+interface AssetEntry {
+	readonly name: string;
+	readonly type: "skill" | "command" | "agent";
+	readonly origin: "built-in" | "user-created";
+	readonly lint?: {
+		readonly valid: boolean;
+		readonly errors: readonly string[];
+		readonly warnings: readonly string[];
+	};
+}
+
+/** Read directory entries safely, returning empty array on ENOENT only. */
+async function safeReaddir(dirPath: string): Promise<string[]> {
+	try {
+		return await readdir(dirPath);
+	} catch (error: unknown) {
+		const errObj = error as { code?: unknown };
+		if (errObj?.code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/** Cache for built-in asset lookups (keyed by assetType). */
+const builtInCache = new Map<string, ReadonlySet<string>>();
+
+/** Check if an asset name exists in the bundled assets directory. */
+async function isBuiltIn(assetType: string, name: string): Promise<boolean> {
+	let cached = builtInCache.get(assetType);
+	if (!cached) {
+		const assetsDir = getAssetsDir();
+		const entries = await safeReaddir(join(assetsDir, assetType));
+		cached = new Set(entries);
+		builtInCache.set(assetType, cached);
+	}
+	return cached.has(name);
+}
+
+export async function stocktakeCore(args: StocktakeArgs, baseDir: string): Promise<string> {
+	const shouldLint = args.lint !== false;
+	const skills: AssetEntry[] = [];
+	const commands: AssetEntry[] = [];
+	const agents: AssetEntry[] = [];
+
+	// Scan skills (each subdirectory is a skill) — filter to directories only
+	const skillEntries = await readdir(join(baseDir, "skills"), { withFileTypes: true }).catch(
+		() => [],
+	);
+	const skillDirs = skillEntries
+		.filter((e) => e.isDirectory() && e.name !== ".gitkeep")
+		.map((e) => e.name);
+	for (const name of skillDirs) {
+		const skillFile = join(baseDir, "skills", name, "SKILL.md");
+		const origin = (await isBuiltIn("skills", name)) ? "built-in" : "user-created";
+		const entry: AssetEntry = { name, type: "skill", origin };
+
+		if (shouldLint) {
+			try {
+				const content = await readFile(skillFile, "utf-8");
+				const lint = lintSkill(content);
+				skills.push({ ...entry, lint });
+			} catch {
+				skills.push({
+					...entry,
+					lint: { valid: false, errors: ["Could not read SKILL.md"], warnings: [] },
+				});
+			}
+		} else {
+			skills.push(entry);
+		}
+	}
+
+	// Scan commands (.md files)
+	const commandFiles = await safeReaddir(join(baseDir, "commands"));
+	for (const file of commandFiles.filter((f) => f.endsWith(".md"))) {
+		const name = file.replace(/\.md$/, "");
+		const origin = (await isBuiltIn("commands", file)) ? "built-in" : "user-created";
+		const entry: AssetEntry = { name, type: "command", origin };
+
+		if (shouldLint) {
+			try {
+				const content = await readFile(join(baseDir, "commands", file), "utf-8");
+				const lint = lintCommand(content);
+				commands.push({ ...entry, lint });
+			} catch {
+				commands.push({
+					...entry,
+					lint: { valid: false, errors: ["Could not read command file"], warnings: [] },
+				});
+			}
+		} else {
+			commands.push(entry);
+		}
+	}
+
+	// Scan agents (.md files)
+	const agentFiles = await safeReaddir(join(baseDir, "agents"));
+	for (const file of agentFiles.filter((f) => f.endsWith(".md"))) {
+		const name = file.replace(/\.md$/, "");
+		const origin = (await isBuiltIn("agents", file)) ? "built-in" : "user-created";
+		const entry: AssetEntry = { name, type: "agent", origin };
+
+		if (shouldLint) {
+			try {
+				const content = await readFile(join(baseDir, "agents", file), "utf-8");
+				const lint = lintAgent(content);
+				agents.push({ ...entry, lint });
+			} catch {
+				agents.push({
+					...entry,
+					lint: { valid: false, errors: ["Could not read agent file"], warnings: [] },
+				});
+			}
+		} else {
+			agents.push(entry);
+		}
+	}
+
+	// Compute summary
+	const allAssets = [...skills, ...commands, ...agents];
+	const builtIn = allAssets.filter((a) => a.origin === "built-in").length;
+	const userCreated = allAssets.filter((a) => a.origin === "user-created").length;
+	const lintErrors = shouldLint
+		? allAssets.reduce((sum, a) => sum + (a.lint?.errors.length ?? 0), 0)
+		: 0;
+	const lintWarnings = shouldLint
+		? allAssets.reduce((sum, a) => sum + (a.lint?.warnings.length ?? 0), 0)
+		: 0;
+
+	return JSON.stringify(
+		{
+			skills,
+			commands,
+			agents,
+			summary: {
+				total: allAssets.length,
+				builtIn,
+				userCreated,
+				lintErrors,
+				lintWarnings,
+			},
+		},
+		null,
+		2,
+	);
+}
+
+export const ocStocktake = tool({
+	description:
+		"Audit all installed skills, commands, and agents with optional YAML frontmatter lint validation.",
+	args: {
+		lint: tool.schema
+			.boolean()
+			.optional()
+			.default(true)
+			.describe("Run YAML frontmatter linter on all assets"),
+	},
+	async execute(args) {
+		return stocktakeCore(args, getGlobalConfigDir());
+	},
+});

package/src/tools/update-docs.ts

@@ -0,0 +1,116 @@
+import { execFile as execFileCb } from "node:child_process";
+import { basename } from "node:path";
+import { promisify } from "node:util";
+import { tool } from "@opencode-ai/plugin";
+
+const execFile = promisify(execFileCb);
+
+interface UpdateDocsArgs {
+	readonly scope?: string;
+}
+
+interface AffectedDoc {
+	readonly doc: string;
+	readonly reason: string;
+	readonly suggestion: string;
+}
+
+/** Run a git command and return stdout lines (empty array on error). */
+async function gitLines(args: readonly string[], cwd: string): Promise<readonly string[]> {
+	try {
+		const { stdout } = await execFile("git", [...args], { cwd });
+		return stdout
+			.trim()
+			.split("\n")
+			.filter((line) => line.length > 0);
+	} catch {
+		return [];
+	}
+}
+
+export async function updateDocsCore(args: UpdateDocsArgs, projectDir: string): Promise<string> {
+	const scope = args.scope ?? "changed";
+
+	// Get changed source files
+	const changedFiles: readonly string[] =
+		scope === "all"
+			? await gitLines(["ls-files"], projectDir)
+			: await gitLines(["diff", "--name-only", "HEAD"], projectDir);
+
+	// Get all markdown files in the project
+	const mdFiles = await gitLines(["ls-files", "*.md"], projectDir);
+
+	// For each changed source file, check if any markdown file references it
+	const affectedDocs: AffectedDoc[] = [];
+	const seenDocs = new Set<string>();
+
+	for (const changedFile of changedFiles) {
+		// Skip markdown files themselves
+		if (changedFile.endsWith(".md")) continue;
+
+		const fileBaseName = basename(changedFile);
+		// Strip extension for module-style references
+		const moduleName = fileBaseName.replace(/\.[^.]+$/, "");
+
+		for (const mdFile of mdFiles) {
+			if (seenDocs.has(`${mdFile}:${changedFile}`)) continue;
+
+			// Simple heuristic: check if the markdown file path suggests it documents this area
+			// or if the changed file's name/module appears in common documentation patterns
+			const mdBaseName = basename(mdFile).replace(/\.md$/, "").toLowerCase();
+			const changedDir = changedFile.split("/").slice(0, -1).join("/");
+
+			const isRelated =
+				mdBaseName === "readme" ||
+				mdBaseName === moduleName.toLowerCase() ||
+				(changedDir.length > 0 && mdFile.toLowerCase().includes(changedDir.toLowerCase()));
+
+			if (isRelated) {
+				seenDocs.add(`${mdFile}:${changedFile}`);
+				affectedDocs.push({
+					doc: mdFile,
+					reason: `may be related to ${changedFile} (heuristic: path/name match)`,
+					suggestion: `Review ${mdFile} — it may need updates to reflect changes to ${changedFile}`,
+				});
+			}
+		}
+	}
+
+	// Deduplicate by doc path
+	const uniqueDocs = Array.from(
+		affectedDocs
+			.reduce((map, item) => {
+				if (!map.has(item.doc)) {
+					map.set(item.doc, item);
+				}
+				return map;
+			}, new Map<string, AffectedDoc>())
+			.values(),
+	);
+
+	const nonMdChanged = changedFiles.filter((f) => !f.endsWith(".md"));
+
+	return JSON.stringify(
+		{
+			changedFiles: nonMdChanged,
+			affectedDocs: uniqueDocs,
+			summary: `${nonMdChanged.length} source files changed, ${uniqueDocs.length} docs may need updates`,
+		},
+		null,
+		2,
+	);
+}
+
+export const ocUpdateDocs = tool({
+	description: "Detect documentation affected by recent code changes and suggest updates.",
+	args: {
+		scope: tool.schema
+			.enum(["changed", "all"])
+			.optional()
+			.default("changed")
+			.describe("Scope: 'changed' for git diff, 'all' for full scan"),
+	},
+	async execute(args) {
+		return updateDocsCore(args, process.cwd());
+	},
+});