@kodrunhq/opencode-autopilot 1.3.0 → 1.5.0

package/src/skills/dependency-resolver.ts

@@ -0,0 +1,88 @@
+/**
+ * Topological sort with cycle detection for skill dependencies.
+ *
+ * Uses iterative DFS-based topological ordering. Skills not in the map are
+ * silently skipped (graceful degradation). All cycle participants are reported
+ * in the `cycles` array so callers can exclude them.
+ */
+
+export interface DependencyNode {
+	readonly requires: readonly string[];
+}
+
+export interface ResolutionResult {
+	readonly ordered: readonly string[];
+	readonly cycles: readonly string[];
+}
+
+/** Hard cap on skill count to prevent DoS via crafted dependency chains. */
+const MAX_SKILLS = 500;
+
+/**
+ * Iterative topological sort with cycle detection.
+ * Skills not in the map are silently skipped (graceful degradation).
+ * All nodes participating in a cycle are reported (not just the re-entry point).
+ */
+export function resolveDependencyOrder(
+	skills: ReadonlyMap<string, DependencyNode>,
+): ResolutionResult {
+	if (skills.size > MAX_SKILLS) {
+		return { ordered: [], cycles: [...skills.keys()] };
+	}
+
+	const visited = new Set<string>();
+	const inStack = new Set<string>();
+	const stackArr: string[] = [];
+	const ordered: string[] = [];
+	const cycleSet = new Set<string>();
+
+	for (const startName of skills.keys()) {
+		if (visited.has(startName)) continue;
+
+		// Iterative DFS using explicit stack
+		const dfsStack: Array<{ name: string; depIndex: number }> = [{ name: startName, depIndex: 0 }];
+		inStack.add(startName);
+		visited.add(startName);
+		stackArr.push(startName);
+
+		while (dfsStack.length > 0) {
+			const frame = dfsStack[dfsStack.length - 1];
+			const skill = skills.get(frame.name);
+			const deps = skill ? skill.requires : [];
+
+			if (frame.depIndex < deps.length) {
+				const dep = deps[frame.depIndex];
+				frame.depIndex++;
+
+				if (!skills.has(dep)) continue; // skip unknown deps
+
+				if (inStack.has(dep)) {
+					// Cycle detected — record all nodes in the cycle path
+					const cycleStart = stackArr.indexOf(dep);
+					for (let i = cycleStart; i < stackArr.length; i++) {
+						cycleSet.add(stackArr[i]);
+					}
+					continue;
+				}
+
+				if (!visited.has(dep)) {
+					visited.add(dep);
+					inStack.add(dep);
+					stackArr.push(dep);
+					dfsStack.push({ name: dep, depIndex: 0 });
+				}
+			} else {
+				// All deps processed — pop this node
+				dfsStack.pop();
+				inStack.delete(frame.name);
+				stackArr.pop();
+				ordered.push(frame.name);
+			}
+		}
+	}
+
+	return Object.freeze({
+		ordered: Object.freeze(ordered),
+		cycles: Object.freeze([...cycleSet]),
+	});
+}

package/src/skills/linter.ts

@@ -0,0 +1,113 @@
+import { parse } from "yaml";
+
+interface LintResult {
+	readonly valid: boolean;
+	readonly errors: readonly string[];
+	readonly warnings: readonly string[];
+}
+
+/** Parse YAML frontmatter from markdown content. Supports LF and CRLF. */
+function extractFrontmatter(content: string): Record<string, unknown> | null {
+	const match = content.match(/^---\r?\n([\s\S]*?\r?\n)?---/);
+	if (!match) return null;
+	try {
+		const parsed = parse(match[1] ?? "");
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+		return parsed as Record<string, unknown>;
+	} catch {
+		return null;
+	}
+}
+
+/** Freeze a LintResult including nested arrays. */
+function freezeResult(valid: boolean, errors: string[], warnings: string[]): LintResult {
+	return Object.freeze({
+		valid,
+		errors: Object.freeze(errors),
+		warnings: Object.freeze(warnings),
+	});
+}
+
+/** Lint a skill SKILL.md file for valid YAML frontmatter and required fields. */
+export function lintSkill(content: string): LintResult {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+
+	const fm = extractFrontmatter(content);
+	if (!fm) {
+		return freezeResult(false, ["Missing YAML frontmatter"], []);
+	}
+
+	// Required fields
+	if (typeof fm.name !== "string" || fm.name.length === 0) {
+		errors.push("Missing required field: name");
+	}
+	if (typeof fm.description !== "string" || fm.description.length === 0) {
+		errors.push("Missing required field: description");
+	}
+
+	// Optional but recommended fields
+	if (!Array.isArray(fm.stacks)) {
+		warnings.push(
+			"Missing recommended field: stacks (add stacks: [] for methodology skills or stacks: [lang] for language skills)",
+		);
+	}
+	if (!Array.isArray(fm.requires)) {
+		warnings.push("Missing recommended field: requires (add requires: [] if no dependencies)");
+	}
+
+	// Validate stacks entries are strings
+	if (Array.isArray(fm.stacks) && fm.stacks.some((s: unknown) => typeof s !== "string")) {
+		errors.push("stacks must contain only strings");
+	}
+	if (Array.isArray(fm.requires) && fm.requires.some((s: unknown) => typeof s !== "string")) {
+		errors.push("requires must contain only strings");
+	}
+
+	// Content validation (CRLF-safe)
+	const body = content.replace(/^---\r?\n(?:[\s\S]*?\r?\n)?---/, "").trim();
+	if (body.length === 0) {
+		warnings.push("Skill has no content after frontmatter");
+	}
+
+	return freezeResult(errors.length === 0, errors, warnings);
+}
+
+/** Lint a command markdown file for valid YAML frontmatter and required fields. */
+export function lintCommand(content: string): LintResult {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+
+	const fm = extractFrontmatter(content);
+	if (!fm) {
+		return freezeResult(false, ["Missing YAML frontmatter"], []);
+	}
+
+	if (typeof fm.description !== "string" || fm.description.length === 0) {
+		errors.push("Missing required field: description");
+	}
+
+	const body = content.replace(/^---\r?\n(?:[\s\S]*?\r?\n)?---/, "").trim();
+	if (body.length === 0) {
+		warnings.push("Command has no content after frontmatter");
+	}
+
+	return freezeResult(errors.length === 0, errors, warnings);
+}
+
+/** Lint an agent markdown file for valid YAML frontmatter and required fields. */
+export function lintAgent(content: string): LintResult {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+
+	const fm = extractFrontmatter(content);
+	if (!fm) {
+		return freezeResult(false, ["Missing YAML frontmatter"], []);
+	}
+
+	if (typeof fm.name !== "string" || fm.name.length === 0) {
+		errors.push("Missing required field: name");
+	}
+
+	return freezeResult(errors.length === 0, errors, warnings);
+}

package/src/skills/loader.ts

@@ -0,0 +1,88 @@
+/**
+ * Skill frontmatter parser and file loader.
+ *
+ * Loads SKILL.md files from the global skills directory, parses their
+ * YAML frontmatter, and returns structured skill metadata + content.
+ * Uses the `yaml` package for parsing (not regex — per "Don't Hand-Roll" guideline).
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { isEnoentError } from "../utils/fs-helpers";
+
+export interface SkillFrontmatter {
+	readonly name: string;
+	readonly description: string;
+	readonly stacks: readonly string[];
+	readonly requires: readonly string[];
+}
+
+export interface LoadedSkill {
+	readonly frontmatter: SkillFrontmatter;
+	readonly content: string;
+	readonly path: string;
+}
+
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ * Returns null if no valid frontmatter block is found or parsing fails.
+ */
+export function parseSkillFrontmatter(content: string): SkillFrontmatter | null {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) return null;
+
+	try {
+		const parsed = parse(match[1]);
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+		const fm = parsed as Record<string, unknown>;
+		return {
+			name: typeof fm.name === "string" ? fm.name : "",
+			description: typeof fm.description === "string" ? fm.description : "",
+			stacks: Array.isArray(fm.stacks)
+				? fm.stacks.filter((s): s is string => typeof s === "string")
+				: [],
+			requires: Array.isArray(fm.requires)
+				? fm.requires.filter((s): s is string => typeof s === "string")
+				: [],
+		};
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Load all skills from a base directory (e.g., ~/.config/opencode/skills/).
+ * Returns a map of skill name -> LoadedSkill. Best-effort: skips invalid skills.
+ */
+export async function loadAllSkills(skillsDir: string): Promise<ReadonlyMap<string, LoadedSkill>> {
+	const skills = new Map<string, LoadedSkill>();
+
+	try {
+		const entries = await readdir(skillsDir, { withFileTypes: true });
+		await Promise.all(
+			entries
+				.filter((e) => e.isDirectory() && e.name !== ".gitkeep")
+				.map(async (dir) => {
+					try {
+						const skillPath = join(skillsDir, dir.name, "SKILL.md");
+						const content = await readFile(skillPath, "utf-8");
+						const fm = parseSkillFrontmatter(content);
+						if (fm?.name) {
+							skills.set(fm.name, { frontmatter: fm, content, path: skillPath });
+						}
+					} catch (error: unknown) {
+						// Skip ENOENT/IO errors (expected for invalid skills)
+						if (!isEnoentError(error) && !(error instanceof SyntaxError)) {
+							const errObj = error as { code?: unknown };
+							if (typeof errObj?.code !== "string") throw error;
+						}
+					}
+				}),
+		);
+	} catch (error: unknown) {
+		if (!isEnoentError(error)) throw error;
+	}
+
+	return skills;
+}

package/src/templates/skill-template.ts

@@ -5,12 +5,16 @@ export interface SkillTemplateInput {
 	readonly description: string;
 	readonly license?: string;
 	readonly compatibility?: string;
+	readonly stacks?: readonly string[];
+	readonly requires?: readonly string[];
 }
 
 export function generateSkillMarkdown(input: SkillTemplateInput): string {
 	const frontmatter: Record<string, unknown> = {
 		name: input.name,
 		description: input.description,
+		stacks: input.stacks ?? [],
+		requires: input.requires ?? [],
 		...(input.license !== undefined && { license: input.license }),
 		...(input.compatibility !== undefined && { compatibility: input.compatibility }),
 	};

package/src/tools/create-skill.ts

@@ -11,6 +11,8 @@ interface CreateSkillArgs {
 	readonly description: string;
 	readonly license?: string;
 	readonly compatibility?: string;
+	readonly stacks?: readonly string[];
+	readonly requires?: readonly string[];
 }
 
 export async function createSkillCore(args: CreateSkillArgs, baseDir: string): Promise<string> {
@@ -27,6 +29,8 @@ export async function createSkillCore(args: CreateSkillArgs, baseDir: string): P
 		description: args.description,
 		license: args.license,
 		compatibility: args.compatibility,
+		stacks: args.stacks,
+		requires: args.requires,
 	});
 
 	try {
@@ -67,6 +71,14 @@ export const ocCreateSkill = tool({
 			.max(64)
 			.optional()
 			.describe("Compatibility (e.g., 'opencode')"),
+		stacks: tool.schema
+			.array(tool.schema.string())
+			.optional()
+			.describe("Stack tags for adaptive loading (e.g., ['typescript', 'bun'])"),
+		requires: tool.schema
+			.array(tool.schema.string())
+			.optional()
+			.describe("Required skill dependencies (e.g., ['coding-standards'])"),
 	},
 	async execute(args) {
 		return createSkillCore(args, getGlobalConfigDir());

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

package/src/tools/mock-fallback.ts

@@ -0,0 +1,100 @@
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+import { createMockError } from "../observability/mock/mock-provider";
+import type { MockFailureMode } from "../observability/mock/types";
+import { FAILURE_MODES } from "../observability/mock/types";
+import { classifyErrorType, isRetryableError } from "../orchestrator/fallback/error-classifier";
+
+/**
+ * Default retryable status codes matching the standard fallback config.
+ */
+const DEFAULT_RETRY_CODES: readonly number[] = Object.freeze([429, 503, 529]);
+
+/**
+ * Human-readable descriptions for each failure mode.
+ */
+const MODE_DESCRIPTIONS: Readonly<Record<MockFailureMode, string>> = Object.freeze({
+	rate_limit: "Simulates HTTP 429 rate limit response",
+	quota_exceeded: "Simulates HTTP 402 quota/billing error",
+	timeout: "Simulates HTTP 504 gateway timeout (classifies as service_unavailable)",
+	malformed: "Simulates unparseable/corrupt response (not retryable)",
+	service_unavailable: "Simulates HTTP 503 service outage",
+});
+
+/**
+ * Core function for mock fallback testing tool.
+ * Follows the *Core + tool() wrapper pattern per CLAUDE.md.
+ *
+ * - "list" mode returns all available failure modes with descriptions
+ * - Any valid failure mode generates and classifies the mock error
+ * - Invalid modes return an error JSON
+ *
+ * This tool does NOT trigger fallback in a live session. It generates and
+ * classifies errors, showing what the fallback system would see.
+ */
+export async function mockFallbackCore(mode: string): Promise<string> {
+	if (mode === "list") {
+		const modeLines = FAILURE_MODES.map((m) => `  ${m}: ${MODE_DESCRIPTIONS[m]}`).join("\n");
+
+		return JSON.stringify({
+			action: "mock_fallback_list",
+			modes: [...FAILURE_MODES],
+			displayText: `Available failure modes:\n${modeLines}`,
+		});
+	}
+
+	// Validate mode
+	if (!FAILURE_MODES.includes(mode as MockFailureMode)) {
+		return JSON.stringify({
+			action: "error",
+			message: "Invalid failure mode. Use 'list' to see available modes.",
+		});
+	}
+
+	const failureMode = mode as MockFailureMode;
+	const error = createMockError(failureMode);
+	const classification = classifyErrorType(error);
+	const retryable = isRetryableError(error, DEFAULT_RETRY_CODES);
+
+	// Extract error fields for the response
+	const errorObj = error as Record<string, unknown>;
+	const errorSummary: Record<string, unknown> = {
+		name: errorObj.name,
+		message: errorObj.message,
+	};
+	if (errorObj.status !== undefined) {
+		errorSummary.status = errorObj.status;
+	}
+
+	const displayText = [
+		`Mock ${failureMode} error generated.`,
+		`Classification: ${classification}`,
+		`Retryable: ${retryable}`,
+		"",
+		"To test fallback chain: inject this error into FallbackManager.handleError() in a test,",
+		"or use oc_mock_fallback in a session to verify error classification behavior.",
+	].join("\n");
+
+	return JSON.stringify({
+		action: "mock_fallback",
+		mode: failureMode,
+		error: errorSummary,
+		classification,
+		retryable,
+		displayText,
+	});
+}
+
+// --- Tool wrapper ---
+
+export const ocMockFallback = tool({
+	description:
+		"Generate mock errors for fallback chain testing. " +
+		"Use 'list' to see available failure modes.",
+	args: {
+		mode: z.string().describe("Failure mode to simulate or 'list' for available modes"),
+	},
+	async execute({ mode }) {
+		return mockFallbackCore(mode);
+	},
+});