@kodrunhq/opencode-autopilot 1.17.0 → 1.19.0

package/src/types/background.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+export const TaskStatusSchema = z.enum(["pending", "running", "completed", "failed", "cancelled"]);
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
+
+export const TaskResultSchema = z.object({
+	taskId: z.string().min(1),
+	status: TaskStatusSchema,
+	output: z.string().optional(),
+	error: z.string().optional(),
+	startedAt: z.number().optional(),
+	completedAt: z.number().optional(),
+	durationMs: z.number().optional(),
+});
+export type TaskResult = z.infer<typeof TaskResultSchema>;
+
+export const BackgroundTaskSchema = z.object({
+	id: z.string().min(1),
+	name: z.string().min(1),
+	status: TaskStatusSchema,
+	agentId: z.string().optional(),
+	priority: z.number().int().min(0).max(100).default(50),
+	createdAt: z.number(),
+	result: TaskResultSchema.optional(),
+	metadata: z.record(z.string(), z.unknown()).default({}),
+});
+export type BackgroundTask = z.infer<typeof BackgroundTaskSchema>;
+
+export const AgentSlotSchema = z.object({
+	slotId: z.string().min(1),
+	agentId: z.string().min(1),
+	capacity: z.number().int().min(1).max(100).default(1),
+	activeTaskCount: z.number().int().min(0).default(0),
+	reserved: z.boolean().default(false),
+});
+export type AgentSlot = z.infer<typeof AgentSlotSchema>;
+
+export const ConcurrencyLimitsSchema = z.object({
+	global: z.number().int().min(1).max(50).default(5),
+	perAgent: z.number().int().min(1).max(10).default(2),
+	perCategory: z.record(z.string(), z.number().int().min(1).max(20)).default({}),
+});
+export type ConcurrencyLimits = z.infer<typeof ConcurrencyLimitsSchema>;
+
+export const backgroundConfigSchema = z.object({
+	enabled: z.boolean().default(false),
+	maxConcurrent: z.number().int().min(1).max(50).default(5),
+	persistence: z.boolean().default(true),
+});
+export type BackgroundConfig = z.infer<typeof backgroundConfigSchema>;
+export const backgroundDefaults = backgroundConfigSchema.parse({});

package/src/types/mcp.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+export const McpSkillSchema = z.object({
+	name: z.string().min(1),
+	description: z.string().optional(),
+	enabled: z.boolean().default(true),
+	version: z.string().optional(),
+	config: z.record(z.string(), z.unknown()).default({}),
+});
+export type McpSkill = z.infer<typeof McpSkillSchema>;
+
+export const McpServerSchema = z.object({
+	id: z.string().min(1),
+	url: z.string().url().optional(),
+	transport: z.enum(["stdio", "http", "sse"]).default("stdio"),
+	enabled: z.boolean().default(true),
+	skills: z.array(z.string()).default([]),
+	metadata: z.record(z.string(), z.unknown()).default({}),
+});
+export type McpServer = z.infer<typeof McpServerSchema>;
+
+export const mcpConfigSchema = z.object({
+	enabled: z.boolean().default(false),
+	skills: z.record(z.string(), z.unknown()).default({}),
+});
+export type McpConfig = z.infer<typeof mcpConfigSchema>;
+export const mcpDefaults = mcpConfigSchema.parse({});

package/src/types/recovery.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+
+export const ErrorCategorySchema = z.enum([
+	"rate_limit",
+	"auth_failure",
+	"quota_exceeded",
+	"service_unavailable",
+	"timeout",
+	"network",
+	"validation",
+	"empty_content",
+	"thinking_block_error",
+	"tool_result_overflow",
+	"context_window_exceeded",
+	"session_corruption",
+	"agent_loop_stuck",
+	"unknown",
+]);
+export type ErrorCategory = z.infer<typeof ErrorCategorySchema>;
+
+export const RecoveryStrategySchema = z.enum([
+	"retry",
+	"fallback_model",
+	"skip",
+	"abort",
+	"user_prompt",
+	"compact_and_retry",
+	"restart_session",
+	"reduce_context",
+	"skip_and_continue",
+]);
+export type RecoveryStrategy = z.infer<typeof RecoveryStrategySchema>;
+
+export const RecoveryActionSchema = z.object({
+	strategy: RecoveryStrategySchema,
+	errorCategory: ErrorCategorySchema,
+	maxAttempts: z.number().int().min(1).max(10).default(3),
+	backoffMs: z.number().int().min(0).default(1000),
+	fallbackAgentId: z.string().optional(),
+	metadata: z.record(z.string(), z.unknown()).default({}),
+});
+export type RecoveryAction = z.infer<typeof RecoveryActionSchema>;
+
+export const recoveryConfigSchema = z.object({
+	enabled: z.boolean().default(true),
+	maxRetries: z.number().int().min(0).max(10).default(3),
+});
+export type RecoveryConfig = z.infer<typeof recoveryConfigSchema>;
+export const recoveryDefaults = recoveryConfigSchema.parse({});

package/src/types/routing.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+export const CategorySchema = z.enum([
+	"quick",
+	"visual-engineering",
+	"ultrabrain",
+	"artistry",
+	"writing",
+	"unspecified-high",
+	"unspecified-low",
+]);
+export type Category = z.infer<typeof CategorySchema>;
+
+export const CategoryConfigSchema = z.object({
+	enabled: z.boolean().default(true),
+	agentId: z.string().optional(),
+	modelGroup: z.string().optional(),
+	maxTokenBudget: z.number().int().min(1000).optional(),
+	timeoutSeconds: z.number().int().min(1).max(3600).optional(),
+	skills: z.array(z.string()).default([]),
+	metadata: z.record(z.string(), z.unknown()).default({}),
+});
+export type CategoryConfig = z.infer<typeof CategoryConfigSchema>;
+
+export const RoutingDecisionSchema = z.object({
+	category: CategorySchema,
+	confidence: z.number().min(0).max(1),
+	agentId: z.string().optional(),
+	reasoning: z.string().optional(),
+	appliedConfig: CategoryConfigSchema.optional(),
+});
+export type RoutingDecision = z.infer<typeof RoutingDecisionSchema>;
+
+export const routingConfigSchema = z.object({
+	enabled: z.boolean().default(false),
+	categories: z.record(z.string(), CategoryConfigSchema).default({}),
+});
+export type RoutingConfig = z.infer<typeof routingConfigSchema>;
+export const routingDefaults = routingConfigSchema.parse({});

package/src/ux/context-warnings.ts

@@ -0,0 +1,81 @@
+import type { NotificationManager } from "./notifications";
+
+export type ContextWarningLevel = "none" | "moderate" | "high" | "critical";
+
+export interface ContextWarningMonitorOptions {
+	readonly notificationManager?: NotificationManager;
+}
+
+const warnedLevelsBySeverity = Object.freeze({
+	moderate: Object.freeze({
+		title: "Context warning",
+		message: "Context at 70%, consider wrapping up",
+		notify: (manager: NotificationManager) =>
+			manager.info("Context warning", "Context at 70%, consider wrapping up"),
+	}),
+	high: Object.freeze({
+		title: "Context warning",
+		message: "Context at 85%, compaction recommended",
+		notify: (manager: NotificationManager) =>
+			manager.warn("Context warning", "Context at 85%, compaction recommended"),
+	}),
+	critical: Object.freeze({
+		title: "Context warning",
+		message: "Context at 95%, force compaction",
+		notify: (manager: NotificationManager) =>
+			manager.error("Context warning", "Context at 95%, force compaction"),
+	}),
+});
+
+export class ContextWarningMonitor {
+	private readonly notificationManager?: NotificationManager;
+	private readonly warnedLevels = new Set<Exclude<ContextWarningLevel, "none">>();
+	private warningLevel: ContextWarningLevel = "none";
+
+	constructor(options: ContextWarningMonitorOptions = {}) {
+		this.notificationManager = options.notificationManager;
+	}
+
+	checkUtilization(inputTokens: number, contextLimit: number): void {
+		if (contextLimit <= 0) {
+			this.warningLevel = "none";
+			return;
+		}
+
+		const utilization = inputTokens / contextLimit;
+		const nextLevel = getWarningLevelForUtilization(utilization);
+		this.warningLevel = nextLevel;
+
+		if (nextLevel === "none" || this.warnedLevels.has(nextLevel)) {
+			return;
+		}
+
+		this.warnedLevels.add(nextLevel);
+		const notifier = warnedLevelsBySeverity[nextLevel];
+		if (!notifier || !this.notificationManager) {
+			return;
+		}
+
+		void notifier.notify(this.notificationManager);
+	}
+
+	getWarningLevel(): ContextWarningLevel {
+		return this.warningLevel;
+	}
+}
+
+function getWarningLevelForUtilization(utilization: number): ContextWarningLevel {
+	if (utilization >= 0.95) {
+		return "critical";
+	}
+
+	if (utilization >= 0.85) {
+		return "high";
+	}
+
+	if (utilization >= 0.7) {
+		return "moderate";
+	}
+
+	return "none";
+}

package/src/ux/error-hints.ts

@@ -0,0 +1,38 @@
+const REMEDIATION_HINTS = Object.freeze([
+	{
+		pattern: /429|rate limit/i,
+		hint: "Rate limited. Will retry in 30s.",
+	},
+	{
+		pattern: /context window|token limit/i,
+		hint: "Context window exceeded. Try compacting conversation.",
+	},
+	{
+		pattern: /auth|unauthorized/i,
+		hint: "Authentication failed. Check your API key.",
+	},
+	{
+		pattern: /timeout/i,
+		hint: "Request timed out. Will retry with longer timeout.",
+	},
+	{
+		pattern: /empty content/i,
+		hint: "Model returned empty response. Retrying with different model.",
+	},
+	{
+		pattern: /SQLITE_BUSY/i,
+		hint: "Database busy. Retrying with backoff.",
+	},
+]);
+
+export function getRemediationHint(error: Error | string): string | null {
+	const message = typeof error === "string" ? error : error.message;
+
+	for (const entry of REMEDIATION_HINTS) {
+		if (entry.pattern.test(message)) {
+			return entry.hint;
+		}
+	}
+
+	return null;
+}

package/src/ux/index.ts

@@ -0,0 +1,7 @@
+export * from "./context-warnings";
+export * from "./error-hints";
+export * from "./notifications";
+export * from "./progress";
+export * from "./session-summary";
+export * from "./task-status";
+export * from "./types";

package/src/ux/notifications.ts

@@ -0,0 +1,67 @@
+import { getLogger } from "../logging/domains";
+import type { NotificationSink, ToastOptions, ToastVariant } from "./types";
+
+const DEFAULT_RATE_LIMIT_MS = 5_000;
+
+const logger = getLogger("ux", "notifications");
+
+export interface NotificationManagerOptions {
+	readonly sink?: NotificationSink;
+	readonly rateLimitMs?: number;
+}
+
+export class NotificationManager {
+	private readonly sink?: NotificationSink;
+	private readonly rateLimitMs: number;
+	private readonly lastToastAtByVariant = new Map<ToastVariant, number>();
+
+	constructor(options: NotificationManagerOptions = {}) {
+		this.sink = options.sink;
+		this.rateLimitMs = options.rateLimitMs ?? DEFAULT_RATE_LIMIT_MS;
+	}
+
+	async notify(options: ToastOptions): Promise<void> {
+		try {
+			if (!this.sink) {
+				return;
+			}
+
+			const now = Date.now();
+			const lastToastAt = this.lastToastAtByVariant.get(options.variant) ?? 0;
+
+			if (now - lastToastAt < this.rateLimitMs) {
+				logger.debug("Skipped rate-limited toast", {
+					variant: options.variant,
+					title: options.title,
+					rateLimitMs: this.rateLimitMs,
+				});
+				return;
+			}
+
+			await this.sink.showToast(options.title, options.message, options.variant, options.duration);
+			this.lastToastAtByVariant.set(options.variant, now);
+		} catch (error: unknown) {
+			logger.debug("Toast delivery failed", {
+				variant: options.variant,
+				title: options.title,
+				error: String(error),
+			});
+		}
+	}
+
+	info(title: string, message: string, duration?: number): Promise<void> {
+		return this.notify({ title, message, variant: "info", duration });
+	}
+
+	success(title: string, message: string, duration?: number): Promise<void> {
+		return this.notify({ title, message, variant: "success", duration });
+	}
+
+	warn(title: string, message: string, duration?: number): Promise<void> {
+		return this.notify({ title, message, variant: "warning", duration });
+	}
+
+	error(title: string, message: string, duration?: number): Promise<void> {
+		return this.notify({ title, message, variant: "error", duration });
+	}
+}

package/src/ux/progress.ts

@@ -0,0 +1,77 @@
+import type { NotificationManager } from "./notifications";
+import type { ProgressUpdate } from "./types";
+
+export interface ProgressTrackerOptions {
+	readonly notificationManager?: NotificationManager;
+}
+
+export class ProgressTracker {
+	private readonly notificationManager?: NotificationManager;
+	private progress: ProgressUpdate | null = null;
+	private phaseName: string | null = null;
+
+	constructor(options: ProgressTrackerOptions = {}) {
+		this.notificationManager = options.notificationManager;
+	}
+
+	startPhase(phaseName: string, totalSteps: number): void {
+		const normalizedTotal = Math.max(0, totalSteps);
+		this.phaseName = phaseName;
+		this.progress = Object.freeze({
+			current: 0,
+			total: normalizedTotal,
+			label: phaseName,
+			detail: "Starting phase",
+		});
+
+		void this.notificationManager?.info("Phase started", `${phaseName} has started.`);
+	}
+
+	advanceStep(label: string): void {
+		if (!this.progress) {
+			return;
+		}
+
+		const nextCurrent =
+			this.progress.total > 0
+				? Math.min(this.progress.current + 1, this.progress.total)
+				: this.progress.current + 1;
+
+		this.progress = Object.freeze({
+			...this.progress,
+			current: nextCurrent,
+			label,
+		});
+	}
+
+	complete(): void {
+		if (!this.progress) {
+			return;
+		}
+
+		const completedLabel = this.phaseName ? `${this.phaseName} complete` : "Complete";
+		this.progress = Object.freeze({
+			...this.progress,
+			current: this.progress.total,
+			label: completedLabel,
+			detail: "Completed",
+		});
+
+		void this.notificationManager?.success(
+			"Phase complete",
+			`${this.phaseName ?? "Phase"} finished.`,
+		);
+	}
+
+	getProgress(): ProgressUpdate | null {
+		return this.progress;
+	}
+
+	formatProgress(): string {
+		if (!this.progress) {
+			return "No active phase";
+		}
+
+		return `[${this.progress.current}/${this.progress.total}] ${this.progress.label}...`;
+	}
+}

package/src/ux/session-summary.ts

@@ -1,7 +1,32 @@
 import type { SessionEvents } from "../observability/event-store";
 import type { PipelineState } from "../orchestrator/types";
 
+export interface SessionSummaryData {
+	readonly sessionId: string;
+	readonly startedAt: string;
+	readonly endedAt: string;
+	readonly tokensUsed: number;
+	readonly phasesCompleted: readonly string[];
+	readonly errorsEncountered: number;
+	readonly tasksCompleted: number;
+	readonly lessonsLearned: readonly string[];
+}
+
 export function generateSessionSummary(
+	sessionData: SessionEvents | SessionSummaryData | undefined,
+	pipelineState?: PipelineState | null,
+): string {
+	if (isStructuredSessionSummaryData(sessionData) && pipelineState === undefined) {
+		return generateStructuredSessionSummary(sessionData);
+	}
+
+	return generatePipelineSessionSummary(
+		sessionData as SessionEvents | undefined,
+		pipelineState ?? null,
+	);
+}
+
+function generatePipelineSessionSummary(
 	sessionData: SessionEvents | undefined,
 	pipelineState: PipelineState | null,
 ): string {
@@ -54,3 +79,45 @@ export function generateSessionSummary(
 
 	return sections.join("\n").trim();
 }
+
+function generateStructuredSessionSummary(data: SessionSummaryData): string {
+	const sections = [
+		`# Session Summary: ${data.sessionId}`,
+		"",
+		"## Overview",
+		`- Started: ${data.startedAt}`,
+		`- Ended: ${data.endedAt}`,
+		`- Tokens Used: ${data.tokensUsed.toLocaleString()}`,
+		`- Tasks Completed: ${data.tasksCompleted}`,
+		`- Errors Encountered: ${data.errorsEncountered}`,
+		"",
+		"## Phases Completed",
+		...(data.phasesCompleted.length > 0
+			? data.phasesCompleted.map((phase) => `- ${phase}`)
+			: ["- None"]),
+		"",
+		"## Lessons Learned",
+		...(data.lessonsLearned.length > 0
+			? data.lessonsLearned.map((lesson) => `- ${lesson}`)
+			: ["- None recorded"]),
+	];
+
+	return sections.join("\n").trim();
+}
+
+function isStructuredSessionSummaryData(
+	value: SessionEvents | SessionSummaryData | undefined,
+): value is SessionSummaryData {
+	if (!value) {
+		return false;
+	}
+
+	return (
+		"endedAt" in value &&
+		"tokensUsed" in value &&
+		"phasesCompleted" in value &&
+		"errorsEncountered" in value &&
+		"tasksCompleted" in value &&
+		"lessonsLearned" in value
+	);
+}

package/src/ux/task-status.ts

@@ -0,0 +1,109 @@
+export interface TaskStatusItem {
+	readonly id: string;
+	readonly description: string;
+	readonly status: string;
+	readonly createdAt: string;
+}
+
+export interface TaskStatusDisplayOptions {
+	readonly maxDisplayCount?: number;
+}
+
+const DEFAULT_MAX_DISPLAY_COUNT = 5;
+const ACTIVE_STATUSES = new Set(["running"]);
+const QUEUED_STATUSES = new Set(["pending"]);
+const COMPLETED_STATUSES = new Set(["completed"]);
+
+export class TaskStatusDisplay {
+	private readonly maxDisplayCount: number;
+	private tasks: readonly TaskStatusItem[] = [];
+
+	constructor(options: TaskStatusDisplayOptions = {}) {
+		this.maxDisplayCount = options.maxDisplayCount ?? DEFAULT_MAX_DISPLAY_COUNT;
+	}
+
+	updateTasks(tasks: readonly TaskStatusItem[]): void {
+		this.tasks = [...tasks];
+	}
+
+	formatStatus(): string {
+		const activeCount = this.getActiveCount();
+		const queueDepth = this.getQueueDepth();
+		const visibleTasks = this.getDisplayTasks();
+
+		const lines = [`Background Tasks: ${activeCount} active, ${queueDepth} queued`];
+
+		for (const task of visibleTasks) {
+			const age = formatAge(task.createdAt);
+			const ageSuffix = age ? ` (${age})` : "";
+			lines.push(`- [${task.status}] ${task.description}${ageSuffix}`);
+		}
+
+		return lines.join("\n");
+	}
+
+	getActiveCount(): number {
+		return this.tasks.filter((task) => ACTIVE_STATUSES.has(task.status)).length;
+	}
+
+	getQueueDepth(): number {
+		return this.tasks.filter((task) => QUEUED_STATUSES.has(task.status)).length;
+	}
+
+	getRecentCompletions(limit = this.maxDisplayCount): readonly TaskStatusItem[] {
+		return this.tasks
+			.filter((task) => COMPLETED_STATUSES.has(task.status))
+			.toSorted((left, right) => toTimestamp(right.createdAt) - toTimestamp(left.createdAt))
+			.slice(0, limit);
+	}
+
+	private getDisplayTasks(): readonly TaskStatusItem[] {
+		return this.tasks
+			.toSorted((left, right) => {
+				const leftPriority = getStatusPriority(left.status);
+				const rightPriority = getStatusPriority(right.status);
+				if (leftPriority !== rightPriority) {
+					return leftPriority - rightPriority;
+				}
+				return toTimestamp(right.createdAt) - toTimestamp(left.createdAt);
+			})
+			.slice(0, this.maxDisplayCount);
+	}
+}
+
+function getStatusPriority(status: string): number {
+	if (ACTIVE_STATUSES.has(status)) {
+		return 0;
+	}
+
+	if (QUEUED_STATUSES.has(status)) {
+		return 1;
+	}
+
+	if (COMPLETED_STATUSES.has(status)) {
+		return 2;
+	}
+
+	return 3;
+}
+
+function toTimestamp(value: string): number {
+	const timestamp = Date.parse(value);
+	return Number.isNaN(timestamp) ? 0 : timestamp;
+}
+
+function formatAge(createdAt: string): string | null {
+	const createdAtMs = toTimestamp(createdAt);
+	if (createdAtMs === 0) {
+		return null;
+	}
+
+	const elapsedMs = Math.max(0, Date.now() - createdAtMs);
+	const elapsedMinutes = Math.floor(elapsedMs / 60_000);
+	if (elapsedMinutes > 0) {
+		return `${elapsedMinutes}m ago`;
+	}
+
+	const elapsedSeconds = Math.floor(elapsedMs / 1_000);
+	return `${elapsedSeconds}s ago`;
+}

package/src/ux/types.ts

@@ -0,0 +1,24 @@
+export type ToastVariant = "info" | "success" | "warning" | "error";
+
+export interface ToastOptions {
+	readonly title: string;
+	readonly message: string;
+	readonly variant: ToastVariant;
+	readonly duration?: number;
+}
+
+export interface NotificationSink {
+	showToast(
+		title: string,
+		message: string,
+		variant: ToastVariant,
+		duration?: number,
+	): Promise<void>;
+}
+
+export interface ProgressUpdate {
+	readonly current: number;
+	readonly total: number;
+	readonly label: string;
+	readonly detail?: string;
+}