@kodrunhq/opencode-autopilot 1.15.1 → 1.16.0

package/README.md

@@ -62,6 +62,20 @@ npm install -g @kodrunhq/opencode-autopilot
 
 Launch OpenCode. The plugin auto-installs agents, skills, and commands on first load and shows a welcome toast.
 
+### Agent visibility defaults
+
+Primary Tab-cycle agents provided by this plugin are:
+
+- `autopilot`
+- `coder`
+- `debugger`
+- `planner`
+- `researcher`
+- `reviewer`
+
+OpenCode native `plan` and `build` are suppressed by the plugin config hook to avoid
+duplicate planning/building entries in the primary Tab menu.
+
 ### Verify your setup
 
 ```bash

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.1",
+	"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/agents/index.ts

@@ -71,22 +71,60 @@ function registerAgents(
 	}
 }
 
-function suppressBuiltInVariants(
-	variants: readonly string[],
-	builtInKeys: ReadonlySet<string>,
-	config: Config,
-): void {
+const nativeSuppressionPatch = Object.freeze({
+	disable: true,
+	mode: "subagent" as const,
+	hidden: true,
+});
+
+const optionalNativePlanBuildKeys = Object.freeze(["Plan", "Build", "Planner", "Builder"] as const);
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function mergeSuppressionPatch(entry: unknown): Record<string, unknown> {
+	if (isObjectRecord(entry)) {
+		return {
+			...entry,
+			...nativeSuppressionPatch,
+		};
+	}
+
+	return { ...nativeSuppressionPatch };
+}
+
+function suppressNativePlanBuildAgents(config: Config): void {
 	if (!config.agent) return;
-	for (const variant of variants) {
-		if (builtInKeys.has(variant) && config.agent[variant] !== undefined) {
-			config.agent[variant] = {
-				...config.agent[variant],
-				disable: true,
-			};
+
+	const agentRef = config.agent as Record<string, unknown>;
+
+	// Deterministically suppress native lowercase keys even if OpenCode did not
+	// pre-populate them before configHook execution.
+	for (const key of ["plan", "build"] as const) {
+		agentRef[key] = mergeSuppressionPatch(agentRef[key]);
+	}
+
+	// Also suppress optional native variants when present.
+	for (const key of optionalNativePlanBuildKeys) {
+		if (agentRef[key] !== undefined) {
+			agentRef[key] = mergeSuppressionPatch(agentRef[key]);
 		}
 	}
 }
 
+function suppressLegacyModePlanBuild(config: Config): void {
+	if (!config.mode) return;
+
+	const modeRef = config.mode as Record<string, unknown>;
+	for (const key of ["plan", "build", ...optionalNativePlanBuildKeys] as const) {
+		const existing = modeRef[key];
+		if (existing === undefined) continue;
+		if (!isObjectRecord(existing)) continue;
+		modeRef[key] = mergeSuppressionPatch(existing);
+	}
+}
+
 export async function configHook(config: Config, configPath?: string): Promise<void> {
 	if (!config.agent) {
 		config.agent = {};
@@ -105,21 +143,16 @@ export async function configHook(config: Config, configPath?: string): Promise<v
 	const groups: Readonly<Record<string, GroupModelAssignment>> = pluginConfig?.groups ?? {};
 	const overrides: Readonly<Record<string, AgentOverride>> = pluginConfig?.overrides ?? {};
 
-	// Snapshot built-in agent keys BEFORE we register ours — we only suppress
-	// built-in Plan/Build variants, never our custom planner/coder agents.
-	const builtInKeys = new Set(Object.keys(config.agent));
-
 	// Register standard agents and pipeline agents (v2 orchestrator subagents)
 	registerAgents(agents, config, groups, overrides);
 	registerAgents(pipelineAgents, config, groups, overrides);
 
-	// Suppress built-in Plan/Build agents — planner/coder replace them.
-	// Only disable keys that existed before our registration (built-ins).
-	const planVariants = ["Plan", "plan", "Planner", "planner"] as const;
-	suppressBuiltInVariants(planVariants, builtInKeys, config);
+	// Suppress native built-in Plan/Build agents. This is deterministic and does
+	// not rely on whether OpenCode pre-populated keys before configHook runs.
+	suppressNativePlanBuildAgents(config);
 
-	const buildVariants = ["Build", "build", "Builder", "builder"] as const;
-	suppressBuiltInVariants(buildVariants, builtInKeys, config);
+	// Backward compatibility for legacy mode.plan/mode.build config shape.
+	suppressLegacyModePlanBuild(config);
 }
 
 export { autopilotAgent } from "./autopilot";

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";
 
 /**
@@ -90,6 +94,85 @@ export async function agentHealthCheck(config: Config | null): Promise<HealthRes
 	});
 }
 
+/**
+ * Check that OpenCode native plan/build agents are suppressed by the plugin.
+ * Contract: both entries must have disable=true, mode=subagent, hidden=true.
+ */
+export async function nativeAgentSuppressionHealthCheck(
+	config: Config | null,
+): Promise<HealthResult> {
+	if (!config?.agent) {
+		return Object.freeze({
+			name: "native-agent-suppression",
+			status: "fail" as const,
+			message: "No OpenCode config or agent map available",
+		});
+	}
+
+	const agentMap = config.agent as Record<string, unknown>;
+	const issues: string[] = [];
+	const requiredKeys = ["plan", "build"] as const;
+	const optionalKeys = ["Plan", "Build", "Planner", "Builder"] as const;
+
+	for (const key of requiredKeys) {
+		const raw = agentMap[key];
+		if (raw === undefined) {
+			issues.push(`${key}: missing config entry`);
+			continue;
+		}
+		if (typeof raw !== "object" || raw === null) {
+			issues.push(`${key}: invalid config entry type`);
+			continue;
+		}
+
+		const entry = raw as Record<string, unknown>;
+		if (entry.disable !== true) {
+			issues.push(`${key}: disable must be true`);
+		}
+		if (entry.mode !== "subagent") {
+			issues.push(`${key}: mode must be subagent`);
+		}
+		if (entry.hidden !== true) {
+			issues.push(`${key}: hidden must be true`);
+		}
+	}
+
+	for (const key of optionalKeys) {
+		const raw = agentMap[key];
+		if (raw === undefined) continue;
+		if (typeof raw !== "object" || raw === null) {
+			issues.push(`${key}: invalid config entry type`);
+			continue;
+		}
+
+		const entry = raw as Record<string, unknown>;
+		if (entry.disable !== true) {
+			issues.push(`${key}: disable must be true`);
+		}
+		if (entry.mode !== "subagent") {
+			issues.push(`${key}: mode must be subagent`);
+		}
+		if (entry.hidden !== true) {
+			issues.push(`${key}: hidden must be true`);
+		}
+	}
+
+	if (issues.length > 0) {
+		return Object.freeze({
+			name: "native-agent-suppression",
+			status: "fail" as const,
+			message: `${issues.length} native suppression issue(s) found`,
+			details: Object.freeze([...issues]),
+		});
+	}
+
+	return Object.freeze({
+		name: "native-agent-suppression",
+		status: "pass" as const,
+		message: "Native plan/build agents are suppressed",
+	});
+}
+
 /**
  * Check that the source and target asset directories exist and are accessible.
  */
@@ -170,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",