@kodrunhq/opencode-autopilot 1.15.2 → 1.17.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.17.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/config/index.ts

@@ -0,0 +1,29 @@
+export {
+	CONFIG_PATH,
+	confidenceConfigSchema,
+	confidenceDefaults,
+	createDefaultConfig,
+	isFirstLoad,
+	loadConfig,
+	memoryConfigSchema,
+	memoryDefaults,
+	orchestratorConfigSchema,
+	orchestratorDefaults,
+	type PluginConfig,
+	pluginConfigSchema,
+	saveConfig,
+} from "../config";
+// Re-export migration schemas and functions for backward compatibility
+export {
+	migrateV1toV2,
+	migrateV2toV3,
+	migrateV3toV4,
+	migrateV4toV5,
+	migrateV5toV6,
+	pluginConfigSchemaV1,
+	pluginConfigSchemaV2,
+	pluginConfigSchemaV3,
+	pluginConfigSchemaV4,
+	pluginConfigSchemaV5,
+} from "./migrations";
+export { migrateV6toV7, type PluginConfigV7, v7ConfigDefaults } from "./v7";

package/src/config/migrations.ts

@@ -0,0 +1,196 @@
+import { z } from "zod";
+import {
+	confidenceConfigSchema,
+	confidenceDefaults,
+	memoryConfigSchema,
+	memoryDefaults,
+	orchestratorConfigSchema,
+	orchestratorDefaults,
+} from "../config";
+import {
+	fallbackConfigSchema,
+	fallbackDefaults,
+	testModeDefaults,
+} from "../orchestrator/fallback/fallback-config";
+import { AGENT_REGISTRY, ALL_GROUP_IDS } from "../registry/model-groups";
+
+export const pluginConfigSchemaV1 = z.object({
+	version: z.literal(1),
+	configured: z.boolean(),
+	models: z.record(z.string(), z.string()),
+});
+
+export type PluginConfigV1 = z.infer<typeof pluginConfigSchemaV1>;
+
+export const pluginConfigSchemaV2 = z.object({
+	version: z.literal(2),
+	configured: z.boolean(),
+	models: z.record(z.string(), z.string()),
+	orchestrator: orchestratorConfigSchema.default(orchestratorDefaults),
+	confidence: confidenceConfigSchema.default(confidenceDefaults),
+});
+
+export type PluginConfigV2 = z.infer<typeof pluginConfigSchemaV2>;
+
+export const pluginConfigSchemaV3 = z.object({
+	version: z.literal(3),
+	configured: z.boolean(),
+	models: z.record(z.string(), z.string()),
+	orchestrator: orchestratorConfigSchema.default(orchestratorDefaults),
+	confidence: confidenceConfigSchema.default(confidenceDefaults),
+	fallback: fallbackConfigSchema.default(fallbackDefaults),
+	fallback_models: z.union([z.string(), z.array(z.string())]).optional(),
+});
+
+export type PluginConfigV3 = z.infer<typeof pluginConfigSchemaV3>;
+
+const groupModelAssignmentSchema = z.object({
+	primary: z.string().min(1),
+	fallbacks: z.array(z.string().min(1)).default([]),
+});
+
+const agentOverrideSchema = z.object({
+	primary: z.string().min(1),
+	fallbacks: z.array(z.string().min(1)).optional(),
+});
+
+export const pluginConfigSchemaV4 = z
+	.object({
+		version: z.literal(4),
+		configured: z.boolean(),
+		groups: z.record(z.string(), groupModelAssignmentSchema).default({}),
+		overrides: z.record(z.string(), agentOverrideSchema).default({}),
+		orchestrator: orchestratorConfigSchema.default(orchestratorDefaults),
+		confidence: confidenceConfigSchema.default(confidenceDefaults),
+		fallback: fallbackConfigSchema.default(fallbackDefaults),
+	})
+	.superRefine((config, ctx) => {
+		for (const groupId of Object.keys(config.groups)) {
+			if (!ALL_GROUP_IDS.includes(groupId as (typeof ALL_GROUP_IDS)[number])) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ["groups", groupId],
+					message: `Unknown group id "${groupId}". Expected one of: ${ALL_GROUP_IDS.join(", ")}`,
+				});
+			}
+		}
+	});
+
+export type PluginConfigV4 = z.infer<typeof pluginConfigSchemaV4>;
+
+export const pluginConfigSchemaV5 = z
+	.object({
+		version: z.literal(5),
+		configured: z.boolean(),
+		groups: z.record(z.string(), groupModelAssignmentSchema).default({}),
+		overrides: z.record(z.string(), agentOverrideSchema).default({}),
+		orchestrator: orchestratorConfigSchema.default(orchestratorDefaults),
+		confidence: confidenceConfigSchema.default(confidenceDefaults),
+		fallback: fallbackConfigSchema.default(fallbackDefaults),
+		memory: memoryConfigSchema.default(memoryDefaults),
+	})
+	.superRefine((config, ctx) => {
+		for (const groupId of Object.keys(config.groups)) {
+			if (!ALL_GROUP_IDS.includes(groupId as (typeof ALL_GROUP_IDS)[number])) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ["groups", groupId],
+					message: `Unknown group id "${groupId}". Expected one of: ${ALL_GROUP_IDS.join(", ")}`,
+				});
+			}
+		}
+	});
+
+export type PluginConfigV5 = z.infer<typeof pluginConfigSchemaV5>;
+
+export function migrateV1toV2(v1Config: PluginConfigV1): PluginConfigV2 {
+	return {
+		version: 2 as const,
+		configured: v1Config.configured,
+		models: v1Config.models,
+		orchestrator: orchestratorDefaults,
+		confidence: confidenceDefaults,
+	};
+}
+
+export function migrateV2toV3(v2Config: PluginConfigV2): PluginConfigV3 {
+	return {
+		version: 3 as const,
+		configured: v2Config.configured,
+		models: v2Config.models,
+		orchestrator: v2Config.orchestrator,
+		confidence: v2Config.confidence,
+		fallback: fallbackDefaults,
+	};
+}
+
+export function migrateV3toV4(v3Config: PluginConfigV3): PluginConfigV4 {
+	const groups: Record<string, { primary: string; fallbacks: string[] }> = {};
+	const overrides: Record<string, { primary: string }> = {};
+
+	for (const [agentName, modelId] of Object.entries(v3Config.models)) {
+		const entry = AGENT_REGISTRY[agentName];
+		if (!entry) {
+			overrides[agentName] = { primary: modelId };
+			continue;
+		}
+
+		const groupId = entry.group;
+		if (!groups[groupId]) {
+			groups[groupId] = { primary: modelId, fallbacks: [] };
+		} else if (groups[groupId].primary !== modelId) {
+			overrides[agentName] = { primary: modelId };
+		}
+	}
+
+	const globalFallbacks = v3Config.fallback_models
+		? typeof v3Config.fallback_models === "string"
+			? [v3Config.fallback_models]
+			: [...v3Config.fallback_models]
+		: [];
+
+	for (const group of Object.values(groups)) {
+		if (group.fallbacks.length === 0 && globalFallbacks.length > 0) {
+			group.fallbacks = [...globalFallbacks];
+		}
+	}
+
+	return {
+		version: 4 as const,
+		configured: v3Config.configured,
+		groups,
+		overrides,
+		orchestrator: v3Config.orchestrator,
+		confidence: v3Config.confidence,
+		fallback: v3Config.fallback,
+	};
+}
+
+export function migrateV4toV5(v4Config: PluginConfigV4): PluginConfigV5 {
+	return {
+		version: 5 as const,
+		configured: v4Config.configured,
+		groups: v4Config.groups,
+		overrides: v4Config.overrides,
+		orchestrator: v4Config.orchestrator,
+		confidence: v4Config.confidence,
+		fallback: v4Config.fallback,
+		memory: memoryDefaults,
+	};
+}
+
+export function migrateV5toV6(
+	v5Config: PluginConfigV5,
+	_fallbackDefaultsV6: typeof fallbackDefaults,
+) {
+	return {
+		version: 6 as const,
+		configured: v5Config.configured,
+		groups: v5Config.groups,
+		overrides: v5Config.overrides,
+		orchestrator: v5Config.orchestrator,
+		confidence: v5Config.confidence,
+		fallback: { ...v5Config.fallback, testMode: testModeDefaults },
+		memory: v5Config.memory,
+	};
+}

package/src/config/v7.ts

@@ -0,0 +1,45 @@
+import type { PluginConfig } from "../config";
+
+export type PluginConfigV7 = Omit<PluginConfig, "version"> & {
+	readonly version: 7;
+	readonly background?: {
+		readonly enabled: boolean;
+		readonly maxConcurrent: number;
+		readonly defaultTimeout: number;
+	};
+	readonly autonomy?: {
+		readonly enabled: boolean;
+		readonly verification: "strict" | "normal" | "lenient";
+		readonly maxIterations: number;
+	};
+};
+
+export function migrateV6toV7(v6Config: PluginConfig): PluginConfigV7 {
+	return {
+		...v6Config,
+		version: 7,
+		background: {
+			enabled: true,
+			maxConcurrent: 5,
+			defaultTimeout: 300000,
+		},
+		autonomy: {
+			enabled: false,
+			verification: "normal",
+			maxIterations: 10,
+		},
+	};
+}
+
+export const v7ConfigDefaults = {
+	background: {
+		enabled: true,
+		maxConcurrent: 5,
+		defaultTimeout: 300000,
+	},
+	autonomy: {
+		enabled: false,
+		verification: "normal",
+		maxIterations: 10,
+	},
+} as const;

package/src/config.ts

@@ -53,8 +53,8 @@ export const confidenceConfigSchema = z.object({
 });
 
 // Pre-compute full defaults for nested schema defaults
-const orchestratorDefaults = orchestratorConfigSchema.parse({});
-const confidenceDefaults = confidenceConfigSchema.parse({});
+export const orchestratorDefaults = orchestratorConfigSchema.parse({});
+export const confidenceDefaults = confidenceConfigSchema.parse({});
 
 // --- V2 schema (internal, for migration) ---
 
@@ -90,7 +90,7 @@ export const memoryConfigSchema = z.object({
 	decayHalfLifeDays: z.number().min(7).max(365).default(90),
 });
 
-const memoryDefaults = memoryConfigSchema.parse({});
+export const memoryDefaults = memoryConfigSchema.parse({});
 
 // --- V4 sub-schemas ---