@kodrunhq/opencode-autopilot 1.15.2 → 1.16.0

package/bin/cli.ts

@@ -11,6 +11,7 @@ import { ALL_GROUP_IDS, DIVERSITY_RULES, GROUP_DEFINITIONS } from "../src/regist
 import type { GroupId } from "../src/registry/types";
 import { fileExists } from "../src/utils/fs-helpers";
 import { runConfigure } from "./configure-tui";
+import { runInspect } from "./inspect";
 
 const execFile = promisify(execFileCb);
 
@@ -314,6 +315,7 @@ function printUsage(): void {
 	console.log("  install     Register the plugin and create starter config");
 	console.log("  configure   Interactive model assignment for each agent group");
 	console.log("  doctor      Check installation health and model assignments");
+	console.log("  inspect     Read-only inspection of projects, runs, events, and memory");
 	console.log("");
 	console.log("Options:");
 	console.log("  --help, -h  Show this help message");
@@ -336,6 +338,9 @@ if (import.meta.main) {
 		case "doctor":
 			await runDoctor();
 			break;
+		case "inspect":
+			await runInspect(args.slice(1));
+			break;
 		case "--help":
 		case "-h":
 		case undefined:

package/bin/inspect.ts

@@ -0,0 +1,337 @@
+import {
+	formatEvents,
+	formatLessons,
+	formatMemoryOverview,
+	formatPaths,
+	formatPreferences,
+	formatProjectDetails,
+	formatProjects,
+	formatRuns,
+} from "../src/inspect/formatters";
+import {
+	getMemoryOverview,
+	getProjectDetails,
+	listEvents,
+	listLessons,
+	listPreferences,
+	listProjects,
+	listRuns,
+} from "../src/inspect/repository";
+
+type InspectView =
+	| "projects"
+	| "project"
+	| "paths"
+	| "runs"
+	| "events"
+	| "lessons"
+	| "preferences"
+	| "memory";
+
+export interface InspectCliOptions {
+	readonly dbPath?: string;
+}
+
+export interface InspectCliResult {
+	readonly isError: boolean;
+	readonly output: string;
+	readonly format: "text" | "json";
+}
+
+interface ParsedInspectArgs {
+	readonly view: InspectView | null;
+	readonly json: boolean;
+	readonly projectRef: string | null;
+	readonly limit: number;
+	readonly runId: string | null;
+	readonly sessionId: string | null;
+	readonly type: string | null;
+	readonly help: boolean;
+	readonly error: string | null;
+}
+
+const INSPECT_VIEWS: readonly InspectView[] = Object.freeze([
+	"projects",
+	"project",
+	"paths",
+	"runs",
+	"events",
+	"lessons",
+	"preferences",
+	"memory",
+]);
+
+function inspectUsage(): string {
+	return [
+		"Usage: opencode-autopilot inspect <view> [options]",
+		"",
+		"Views:",
+		"  projects                     List known projects",
+		"  project --project <ref>      Show one project's details",
+		"  paths --project <ref>        List one project's path history",
+		"  runs [--project <ref>]       List pipeline runs",
+		"  events [--project <ref>]     List forensic events",
+		"  lessons [--project <ref>]    List stored lessons",
+		"  preferences                  List stored preferences",
+		"  memory                       Show memory overview",
+		"",
+		"Options:",
+		"  --project <ref>              Project id, path, or unique name",
+		"  --run-id <id>                Filter events by run id",
+		"  --session-id <id>            Filter events by session id",
+		"  --type <type>                Filter events by type",
+		"  --limit <n>                  Limit rows (default: 20 for runs, 50 elsewhere)",
+		"  --json                       Emit JSON output",
+		"  --help, -h                   Show inspect help",
+	].join("\n");
+}
+
+function parsePositiveInt(raw: string): number | null {
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		return null;
+	}
+	return parsed;
+}
+
+function parseInspectArgs(args: readonly string[]): ParsedInspectArgs {
+	let view: InspectView | null = null;
+	let json = false;
+	let projectRef: string | null = null;
+	let limit = 50;
+	let runId: string | null = null;
+	let sessionId: string | null = null;
+	let type: string | null = null;
+	let help = false;
+	let error: string | null = null;
+
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--help" || arg === "-h") {
+			help = true;
+			continue;
+		}
+		if (arg === "--json") {
+			json = true;
+			continue;
+		}
+		if (arg === "--project") {
+			projectRef = args[index + 1] ?? null;
+			if (projectRef === null) {
+				error = "Missing value for --project.";
+				break;
+			}
+			index += 1;
+			continue;
+		}
+		if (arg === "--limit") {
+			const parsed = parsePositiveInt(args[index + 1] ?? "");
+			if (parsed === null) {
+				error = "--limit must be a positive integer.";
+				break;
+			}
+			limit = parsed;
+			index += 1;
+			continue;
+		}
+		if (arg === "--run-id") {
+			runId = args[index + 1] ?? null;
+			if (runId === null) {
+				error = "Missing value for --run-id.";
+				break;
+			}
+			index += 1;
+			continue;
+		}
+		if (arg === "--session-id") {
+			sessionId = args[index + 1] ?? null;
+			if (sessionId === null) {
+				error = "Missing value for --session-id.";
+				break;
+			}
+			index += 1;
+			continue;
+		}
+		if (arg === "--type") {
+			type = args[index + 1] ?? null;
+			if (type === null) {
+				error = "Missing value for --type.";
+				break;
+			}
+			index += 1;
+			continue;
+		}
+
+		if (view === null) {
+			if ((INSPECT_VIEWS as readonly string[]).includes(arg)) {
+				view = arg as InspectView;
+				if (view === "runs") {
+					limit = 20;
+				}
+				continue;
+			}
+			error = `Unknown inspect view: ${arg}`;
+			break;
+		}
+
+		if (projectRef === null && (view === "project" || view === "paths")) {
+			projectRef = arg;
+			continue;
+		}
+
+		error = `Unexpected argument: ${arg}`;
+		break;
+	}
+
+	if (!help && error === null && view === null) {
+		help = true;
+	}
+
+	if (
+		error === null &&
+		(view === "project" || view === "paths") &&
+		(projectRef === null || projectRef.trim().length === 0)
+	) {
+		error = `${view} view requires --project <ref> or a positional project reference.`;
+	}
+
+	return {
+		view,
+		json,
+		projectRef,
+		limit,
+		runId,
+		sessionId,
+		type,
+		help,
+		error,
+	};
+}
+
+function makeOutput(payload: unknown, json: boolean, text: string): InspectCliResult {
+	return Object.freeze({
+		isError: false,
+		format: json ? "json" : "text",
+		output: json ? JSON.stringify(payload, null, 2) : text,
+	});
+}
+
+function makeError(message: string, json: boolean): InspectCliResult {
+	return Object.freeze({
+		isError: true,
+		format: json ? "json" : "text",
+		output: json
+			? JSON.stringify({ action: "error", message }, null, 2)
+			: `${message}\n\n${inspectUsage()}`,
+	});
+}
+
+export async function inspectCliCore(
+	args: readonly string[],
+	options: InspectCliOptions = {},
+): Promise<InspectCliResult> {
+	const parsed = parseInspectArgs(args);
+	if (parsed.help) {
+		return makeOutput({ action: "help", usage: inspectUsage() }, parsed.json, inspectUsage());
+	}
+	if (parsed.error !== null) {
+		return makeError(parsed.error, parsed.json);
+	}
+
+	const dbInput = options.dbPath;
+	switch (parsed.view) {
+		case "projects": {
+			const projects = listProjects(dbInput);
+			return makeOutput(
+				{ action: "inspect_projects", projects },
+				parsed.json,
+				formatProjects(projects),
+			);
+		}
+		case "project": {
+			const details = getProjectDetails(parsed.projectRef!, dbInput);
+			if (details === null) {
+				return makeError(`Project not found: ${parsed.projectRef}`, parsed.json);
+			}
+			return makeOutput(
+				{ action: "inspect_project", project: details },
+				parsed.json,
+				formatProjectDetails(details),
+			);
+		}
+		case "paths": {
+			const details = getProjectDetails(parsed.projectRef!, dbInput);
+			if (details === null) {
+				return makeError(`Project not found: ${parsed.projectRef}`, parsed.json);
+			}
+			return makeOutput(
+				{ action: "inspect_paths", project: details.project, paths: details.paths },
+				parsed.json,
+				formatPaths(details),
+			);
+		}
+		case "runs": {
+			const runs = listRuns(
+				{ projectRef: parsed.projectRef ?? undefined, limit: parsed.limit },
+				dbInput,
+			);
+			return makeOutput({ action: "inspect_runs", runs }, parsed.json, formatRuns(runs));
+		}
+		case "events": {
+			const events = listEvents(
+				{
+					projectRef: parsed.projectRef ?? undefined,
+					runId: parsed.runId ?? undefined,
+					sessionId: parsed.sessionId ?? undefined,
+					type: parsed.type ?? undefined,
+					limit: parsed.limit,
+				},
+				dbInput,
+			);
+			return makeOutput({ action: "inspect_events", events }, parsed.json, formatEvents(events));
+		}
+		case "lessons": {
+			const lessons = listLessons(
+				{ projectRef: parsed.projectRef ?? undefined, limit: parsed.limit },
+				dbInput,
+			);
+			return makeOutput(
+				{ action: "inspect_lessons", lessons },
+				parsed.json,
+				formatLessons(lessons),
+			);
+		}
+		case "preferences": {
+			const preferences = listPreferences(dbInput);
+			return makeOutput(
+				{ action: "inspect_preferences", preferences },
+				parsed.json,
+				formatPreferences(preferences),
+			);
+		}
+		case "memory": {
+			const overview = getMemoryOverview(dbInput);
+			return makeOutput(
+				{ action: "inspect_memory", overview },
+				parsed.json,
+				formatMemoryOverview(overview),
+			);
+		}
+		case null:
+			return makeOutput({ action: "help", usage: inspectUsage() }, parsed.json, inspectUsage());
+	}
+}
+
+export async function runInspect(
+	args: readonly string[],
+	options: InspectCliOptions = {},
+): Promise<void> {
+	const result = await inspectCliCore(args, options);
+	if (result.isError) {
+		console.error(result.output);
+		process.exitCode = 1;
+		return;
+	}
+
+	console.log(result.output);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kodrunhq/opencode-autopilot",
-	"version": "1.15.2",
+	"version": "1.16.0",
 	"description": "Curated agents, skills, and commands for the OpenCode AI coding CLI — autonomous orchestrator, multi-agent code review, model fallback, and in-session asset creation tools.",
 	"main": "src/index.ts",
 	"keywords": [

package/src/agents/autopilot.ts

@@ -9,10 +9,10 @@ export const autopilotAgent: Readonly<AgentConfig> = Object.freeze({
 
 ## Loop
 
-1. Call oc_orchestrate with your initial idea (first turn) or with the result from the previous agent.
+1. Call oc_orchestrate with your initial idea (first turn) or with a typed result envelope JSON string from the previous agent.
 2. Parse the JSON response.
-3. If action is "dispatch": call the named agent with the provided prompt, then pass its output back to oc_orchestrate via the result parameter.
-4. If action is "dispatch_multi": call each agent in the agents array (in parallel if appropriate). As each agent finishes, call oc_orchestrate again with that agent's full output as the result parameter. Do NOT combine multiple agents' outputs into a single result.
+3. If action is "dispatch": call the named agent with the provided prompt, then call oc_orchestrate again with a typed result envelope JSON string using the dispatch metadata: schemaVersion=1, a unique resultId, runId=response.runId, phase=response.phase, dispatchId=response.dispatchId, agent=response.agent, kind=response.expectedResultKind ?? response.resultKind, taskId=response.taskId ?? null, payload.text=<full agent output>.
+4. If action is "dispatch_multi": do the same for each agent entry. Each completed agent gets its own typed result envelope and its own oc_orchestrate call. Do NOT combine multiple agents' outputs into one result.
 5. If action is "complete": report the summary to the user. You are done.
 6. If action is "error": report the error to the user. Stop.
 
@@ -24,20 +24,12 @@ When editing files, prefer oc_hashline_edit over the built-in edit tool. Hash-an
 
 - NEVER skip calling oc_orchestrate. It is the single source of truth for pipeline state.
 - NEVER make pipeline decisions yourself. Always defer to oc_orchestrate.
-- ALWAYS pass the full agent output back as the result parameter.
+- NEVER pass raw agent output as result. ALWAYS send a typed result envelope JSON string.
+- ALWAYS preserve the full agent output in payload.text.
+- ALWAYS use a unique resultId for every returned result.
 - Do not attempt to run phases out of order.
 - Do not retry a failed phase unless oc_orchestrate instructs you to.
-- If an agent dispatch fails, pass the error message back to oc_orchestrate as the result.
-
-## Example Turn Sequence
-
-Turn 1: oc_orchestrate(idea="Build a CLI tool")
-  -> {action:"dispatch", agent:"oc-researcher", prompt:"Research: Build a CLI tool", phase:"RECON"}
-Turn 2: @oc-researcher "Research: Build a CLI tool"
-  -> "Research findings: ..."
-Turn 3: oc_orchestrate(result="Research findings: ...")
-  -> {action:"dispatch", agent:"oc-challenger", prompt:"Challenge: ...", phase:"CHALLENGE"}
-... continues until action is "complete"`,
+- If an agent dispatch fails, wrap the error text in payload.text and still return a typed result envelope.`,
 	permission: {
 		edit: "allow",
 		bash: "allow",

package/src/health/checks.ts

@@ -4,11 +4,15 @@ import { join } from "node:path";
 import type { Config } from "@opencode-ai/plugin";
 import { parse } from "yaml";
 import { loadConfig } from "../config";
-import { DB_FILE, MEMORY_DIR } from "../memory/constants";
 import { AGENT_NAMES } from "../orchestrator/handlers/types";
 import { detectProjectStackTags, filterSkillsByStack } from "../skills/adaptive-injector";
 import { loadAllSkills } from "../skills/loader";
-import { getAssetsDir, getGlobalConfigDir } from "../utils/paths";
+import {
+	getAssetsDir,
+	getAutopilotDbPath,
+	getGlobalConfigDir,
+	getLegacyMemoryDbPath,
+} from "../utils/paths";
 import type { HealthResult } from "./types";
 
 /**
@@ -249,19 +253,40 @@ export async function skillHealthCheck(
  */
 export async function memoryHealthCheck(baseDir?: string): Promise<HealthResult> {
 	const resolvedBase = baseDir ?? getGlobalConfigDir();
-	const dbPath = join(resolvedBase, MEMORY_DIR, DB_FILE);
+	const dbPath = getAutopilotDbPath(resolvedBase);
+	const legacyDbPath = getLegacyMemoryDbPath(resolvedBase);
 
 	try {
 		await access(dbPath);
 	} catch (error: unknown) {
 		const code = (error as NodeJS.ErrnoException).code;
 		if (code === "ENOENT") {
+			try {
+				await access(legacyDbPath);
+			} catch (legacyError: unknown) {
+				const legacyCode = (legacyError as NodeJS.ErrnoException).code;
+				if (legacyCode === "ENOENT") {
+					return Object.freeze({
+						name: "memory-db",
+						status: "pass" as const,
+						message: `Memory DB not yet initialized -- will be created on first memory capture`,
+					});
+				}
+				const legacyMsg = legacyError instanceof Error ? legacyError.message : String(legacyError);
+				return Object.freeze({
+					name: "memory-db",
+					status: "fail" as const,
+					message: `Memory DB inaccessible: ${legacyMsg}`,
+				});
+			}
+
 			return Object.freeze({
 				name: "memory-db",
 				status: "pass" as const,
-				message: `Memory DB not yet initialized -- will be created on first memory capture`,
+				message: `Legacy memory DB found -- unified DB will be created on next write`,
 			});
 		}
+
 		const msg = error instanceof Error ? error.message : String(error);
 		return Object.freeze({
 			name: "memory-db",

package/src/index.ts

@@ -4,7 +4,12 @@ import { isFirstLoad, loadConfig } from "./config";
 import { runHealthChecks } from "./health/runner";
 import { createAntiSlopHandler } from "./hooks/anti-slop";
 import { installAssets } from "./installer";
-import { createMemoryCaptureHandler, createMemoryInjector, getMemoryDb } from "./memory";
+import {
+	createMemoryCaptureHandler,
+	createMemoryChatMessageHandler,
+	createMemoryInjector,
+	getMemoryDb,
+} from "./memory";
 import { ContextMonitor } from "./observability/context-monitor";
 import {
 	createObservabilityEventHandler,
@@ -12,9 +17,9 @@ import {
 	createToolExecuteBeforeHandler,
 } from "./observability/event-handlers";
 import { SessionEventStore } from "./observability/event-store";
+import { createForensicEvent } from "./observability/forensic-log";
 import { writeSessionLog } from "./observability/log-writer";
 import { pruneOldLogs } from "./observability/retention";
-import type { SessionEvent } from "./observability/types";
 import type { SdkOperations } from "./orchestrator/fallback";
 import {
 	createChatMessageHandler,
@@ -38,6 +43,7 @@ import { ocDoctor, setOpenCodeConfig as setDoctorOpenCodeConfig } from "./tools/
 import { ocForensics } from "./tools/forensics";
 import { ocHashlineEdit } from "./tools/hashline-edit";
 import { ocLogs } from "./tools/logs";
+import { ocMemoryPreferences } from "./tools/memory-preferences";
 import { ocMemoryStatus } from "./tools/memory-status";
 import { ocMockFallback } from "./tools/mock-fallback";
 import { ocOrchestrate } from "./tools/orchestrate";
@@ -148,6 +154,29 @@ const plugin: Plugin = async (input) => {
 		manager,
 		sdk: sdkOps,
 		config: fallbackConfig,
+		onFallbackEvent: (event) => {
+			if (event.type === "fallback") {
+				eventStore.appendEvent(event.sessionId, {
+					type: "fallback",
+					timestamp: new Date().toISOString(),
+					sessionId: event.sessionId,
+					failedModel: event.failedModel ?? "unknown",
+					nextModel: event.nextModel ?? "unknown",
+					reason: event.reason ?? "fallback",
+					success: event.success === true,
+				});
+				return;
+			}
+
+			eventStore.appendEvent(event.sessionId, {
+				type: "model_switch",
+				timestamp: new Date().toISOString(),
+				sessionId: event.sessionId,
+				fromModel: event.fromModel ?? "unknown",
+				toModel: event.toModel ?? "unknown",
+				trigger: event.trigger ?? "fallback",
+			});
+		},
 	});
 	const chatMessageHandler = createChatMessageHandler(manager);
 	const toolExecuteAfterHandler = createToolExecuteAfterHandler(manager);
@@ -165,6 +194,9 @@ const plugin: Plugin = async (input) => {
 	const memoryCaptureHandler = memoryConfig.enabled
 		? createMemoryCaptureHandler({ getDb: () => getMemoryDb(), projectRoot: process.cwd() })
 		: null;
+	const memoryChatMessageHandler = memoryConfig.enabled
+		? createMemoryChatMessageHandler({ getDb: () => getMemoryDb(), projectRoot: process.cwd() })
+		: null;
 
 	const memoryInjector = memoryConfig.enabled
 		? createMemoryInjector({
@@ -183,18 +215,73 @@ const plugin: Plugin = async (input) => {
 		showToast: sdkOps.showToast,
 		writeSessionLog: async (sessionData) => {
 			if (!sessionData) return;
-			// Filter to schema-valid event types that match SessionEvent discriminated union
-			const schemaEvents: SessionEvent[] = sessionData.events.filter(
-				(e): e is SessionEvent =>
-					e.type === "fallback" ||
-					e.type === "error" ||
-					e.type === "decision" ||
-					e.type === "model_switch",
-			);
 			await writeSessionLog({
+				projectRoot: process.cwd(),
 				sessionId: sessionData.sessionId,
 				startedAt: sessionData.startedAt,
-				events: schemaEvents,
+				events: sessionData.events.map((event) =>
+					createForensicEvent({
+						projectRoot: process.cwd(),
+						domain: "session",
+						timestamp: event.timestamp,
+						sessionId: event.sessionId,
+						type: event.type,
+						message: event.type === "error" ? event.message : null,
+						code:
+							event.type === "error"
+								? event.errorType
+								: event.type === "fallback"
+									? "FALLBACK"
+									: null,
+						payload:
+							event.type === "error"
+								? {
+										model: event.model,
+										errorType: event.errorType,
+										...(event.statusCode !== undefined ? { statusCode: event.statusCode } : {}),
+									}
+								: event.type === "fallback"
+									? {
+											failedModel: event.failedModel,
+											nextModel: event.nextModel,
+											reason: event.reason,
+											success: event.success,
+										}
+									: event.type === "decision"
+										? {
+												decision: event.decision,
+												rationale: event.rationale,
+											}
+										: event.type === "model_switch"
+											? {
+													fromModel: event.fromModel,
+													toModel: event.toModel,
+													trigger: event.trigger,
+												}
+											: event.type === "context_warning"
+												? {
+														utilization: event.utilization,
+														contextLimit: event.contextLimit,
+														inputTokens: event.inputTokens,
+													}
+												: event.type === "tool_complete"
+													? {
+															tool: event.tool,
+															durationMs: event.durationMs,
+															success: event.success,
+														}
+													: event.type === "phase_transition"
+														? {
+																fromPhase: event.fromPhase,
+																toPhase: event.toPhase,
+															}
+														: event.type === "compacted"
+															? {
+																	trigger: event.trigger,
+																}
+															: {},
+					}),
+				),
 			});
 		},
 	});
@@ -224,6 +311,7 @@ const plugin: Plugin = async (input) => {
 			oc_stocktake: ocStocktake,
 			oc_update_docs: ocUpdateDocs,
 			oc_memory_status: ocMemoryStatus,
+			oc_memory_preferences: ocMemoryPreferences,
 		},
 		event: async ({ event }) => {
 			// 1. Observability: collect (pure observer, no side effects on session)
@@ -269,6 +357,10 @@ const plugin: Plugin = async (input) => {
 				parts: unknown[];
 			},
 		) => {
+			if (memoryChatMessageHandler) {
+				await memoryChatMessageHandler(hookInput, output);
+			}
+
 			if (fallbackConfig.enabled) {
 				await chatMessageHandler(hookInput, output);
 			}