open-multi-agent-kit 0.79.1 → 0.80.0

package/dist/cli/runtime/task-controller.js

@@ -0,0 +1,29 @@
+/**
+ * Phase 1 — Task Controller
+ * Handles the 'task' command. Adapter shell around the core task runner.
+ * Collects events via EventBus and returns a normalized CliExecutionResult.
+ */
+import { createCliEventBus } from "./event-bus.js";
+export async function handleTaskCommand(envelope) {
+    const bus = createCliEventBus();
+    // TODO: wire to core task runner once available
+    bus.emit({
+        type: "task-started",
+        taskId: envelope.runtime.runId ?? "task-stub",
+        taskTitle: envelope.input.goal ?? "task",
+        timestamp: new Date().toISOString(),
+    });
+    bus.emit({
+        type: "task-completed",
+        taskId: envelope.runtime.runId ?? "task-stub",
+        taskTitle: envelope.input.goal ?? "task",
+        timestamp: new Date().toISOString(),
+    });
+    return {
+        command: "task",
+        success: true,
+        exitCode: 0,
+        result: { placeholder: true, goal: envelope.input.goal },
+        events: bus.snapshot(),
+    };
+}

package/dist/cli/runtime/types.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Phase 1 — CLI Runtime Types
+ * Normalized command envelope, output profile, execution result, and errors.
+ * Based on the CLI architecture redesign spec (2026-05-25).
+ */
+export type CommandKind = "run" | "task" | "plan" | "chat" | "provider" | "theme" | "doctor";
+export type InputSource = "argv" | "stdin" | "file" | "editor" | "interactive" | "nl-command";
+export type OutputFormat = "json" | "jsonl" | "markdown" | "nlp" | "silent" | "dashboard";
+export interface NormalizedInput {
+    readonly source: InputSource;
+    readonly goal?: string;
+    readonly goalFile?: string;
+    readonly teamFile?: string;
+    readonly taskFile?: string;
+    readonly orchestratorFile?: string;
+    readonly coordinatorFile?: string;
+    readonly rawArgs: readonly string[];
+    readonly metadata: {
+        readonly cwd: string;
+        readonly invokedAt: string;
+        readonly isTty: boolean;
+    };
+}
+export interface OutputProfile {
+    readonly format: OutputFormat;
+    readonly pretty: boolean;
+    readonly includeMessages: boolean;
+    readonly includeTrace: boolean;
+    readonly stream: boolean;
+    readonly destination: "stdout" | "file";
+    readonly outputFile?: string;
+}
+export interface ResolvedTheme {
+    readonly name: string;
+    readonly mode: "dark" | "light" | "auto" | "mono";
+}
+export interface RuntimeOptions {
+    readonly runId?: string;
+    readonly workers?: string;
+    readonly provider?: string;
+    readonly sudo?: boolean;
+}
+export interface CliResolvedConfig {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly projectConfig?: Record<string, unknown>;
+    readonly userConfig?: Record<string, unknown>;
+}
+export interface CommandEnvelope {
+    readonly kind: CommandKind;
+    readonly input: NormalizedInput;
+    readonly config: CliResolvedConfig;
+    readonly output: OutputProfile;
+    readonly theme: ResolvedTheme;
+    readonly runtime: RuntimeOptions;
+}
+export type CliErrorKind = "usage" | "validation" | "io" | "provider" | "runtime" | "theme" | "internal";
+export interface NormalizedCliError {
+    readonly kind: CliErrorKind;
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly hint?: string;
+    readonly docsUrl?: string;
+}
+export interface TokenUsageSummary {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly model?: string;
+}
+export type NormalizedRunEvent = AgentStartedEvent | AgentCompletedEvent | ProviderRequestStartedEvent | ProviderRequestCompletedEvent | ProviderRequestFailedEvent | ProviderFallbackEvent | ProviderAssistEvent | ProviderSkipEvent | TaskStartedEvent | TaskCompletedEvent | TaskFailedEvent | ToolCalledEvent | TokenUsageEvent | TraceSpanEvent | ApprovalRequestedEvent;
+export interface AgentStartedEvent {
+    readonly type: "agent-started";
+    readonly agentName: string;
+    readonly timestamp: string;
+}
+export interface AgentCompletedEvent {
+    readonly type: "agent-completed";
+    readonly agentName: string;
+    readonly success: boolean;
+    readonly timestamp: string;
+}
+export interface ProviderRequestStartedEvent {
+    readonly type: "provider-request-started";
+    readonly provider: string;
+    readonly taskId: string;
+    readonly taskTitle?: string;
+    readonly role?: string;
+    readonly requestedProvider?: string;
+    readonly authority?: string;
+    readonly reason?: string;
+    readonly timestamp: string;
+}
+export interface ProviderRequestCompletedEvent {
+    readonly type: "provider-request-completed";
+    readonly provider: string;
+    readonly taskId: string;
+    readonly taskTitle?: string;
+    readonly role?: string;
+    readonly requestedProvider?: string;
+    readonly authority?: string;
+    readonly durationMs?: number;
+    readonly attempts?: number;
+    readonly timestamp: string;
+}
+export interface ProviderRequestFailedEvent {
+    readonly type: "provider-request-failed";
+    readonly provider: string;
+    readonly taskId: string;
+    readonly taskTitle?: string;
+    readonly role?: string;
+    readonly requestedProvider?: string;
+    readonly authority?: string;
+    readonly durationMs?: number;
+    readonly attempts?: number;
+    readonly error: string;
+    readonly timestamp: string;
+}
+export interface ProviderFallbackEvent {
+    readonly type: "provider-fallback";
+    readonly taskId: string;
+    readonly from: string;
+    readonly to: string;
+    readonly reason: string;
+    readonly attempts?: number;
+    readonly failureKind?: string;
+    readonly timestamp: string;
+}
+export interface ProviderAssistEvent {
+    readonly type: "provider-assist";
+    readonly taskId: string;
+    readonly provider: string;
+    readonly participation: "advisory";
+    readonly success: boolean;
+    readonly model?: string;
+    readonly modelTier?: string;
+    readonly summary?: string;
+    readonly failureReason?: string;
+    readonly timestamp: string;
+}
+export interface ProviderSkipEvent {
+    readonly type: "provider-skip";
+    readonly taskId: string;
+    readonly provider: string;
+    readonly reason: string;
+    readonly attempts?: number;
+    readonly failureKind?: string;
+    readonly timestamp: string;
+}
+export interface TaskStartedEvent {
+    readonly type: "task-started";
+    readonly taskId: string;
+    readonly taskTitle: string;
+    readonly timestamp: string;
+}
+export interface TaskCompletedEvent {
+    readonly type: "task-completed";
+    readonly taskId: string;
+    readonly taskTitle: string;
+    readonly timestamp: string;
+}
+export interface TaskFailedEvent {
+    readonly type: "task-failed";
+    readonly taskId: string;
+    readonly taskTitle: string;
+    readonly error: string;
+    readonly timestamp: string;
+}
+export interface ToolCalledEvent {
+    readonly type: "tool-called";
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly timestamp: string;
+}
+export interface TokenUsageEvent {
+    readonly type: "token-usage";
+    readonly usage: TokenUsageSummary;
+    readonly timestamp: string;
+}
+export interface TraceSpanEvent {
+    readonly type: "trace-span";
+    readonly spanName: string;
+    readonly durationMs: number;
+    readonly timestamp: string;
+}
+export interface ApprovalRequestedEvent {
+    readonly type: "approval-requested";
+    readonly action: string;
+    readonly timestamp: string;
+}
+export interface CliExecutionResult {
+    readonly command: CommandKind;
+    readonly success: boolean;
+    readonly exitCode: 0 | 1 | 2 | 3;
+    readonly result?: unknown;
+    readonly events: readonly NormalizedRunEvent[];
+    readonly error?: NormalizedCliError;
+    readonly tokenUsage?: TokenUsageSummary;
+}
+export type TaskStatus = "running" | "pending" | "completed" | "failed";
+export interface NlpRenderInput {
+    readonly command: "run" | "task" | "plan";
+    readonly success: boolean;
+    readonly goal?: string;
+    readonly result: unknown;
+    readonly events: readonly NormalizedRunEvent[];
+    readonly tokenUsage?: TokenUsageSummary;
+    readonly errors: readonly NormalizedCliError[];
+}
+export interface RenderedOutput {
+    readonly format: OutputFormat;
+    readonly content: string;
+    readonly sourceResultHash: string;
+    readonly generatedAt: string;
+}
+/**
+ * Intent classification result — rule-based, no LLM required.
+ * Maps user input to a normalized intent kind for capability selection.
+ */
+export type IntentKind = "coding" | "review" | "debugging" | "research" | "planning" | "documentation" | "test-generation" | "refactor" | "shell-operation" | "chat" | "unknown";
+/**
+ * Classified intent with confidence and metadata.
+ */
+export interface ClassifiedIntent {
+    readonly kind: IntentKind;
+    readonly confidence: number;
+    readonly matchedRules: readonly string[];
+    readonly rawInput: string;
+}
+/**
+ * CapabilityPlan — what the runtime sidecar injects for a single turn.
+ * This is the output of CapabilitySelector and the input to RuntimeSidecarBuilder.
+ * Follows the invariant: availableMcp ≠ required activation.
+ */
+export interface CapabilityPlan {
+    readonly skills: readonly string[];
+    readonly mcpServers: readonly string[];
+    readonly hooks: readonly string[];
+    readonly tools: readonly string[];
+    readonly promptMode: "full" | "nlp" | "compact" | "minimal";
+    readonly providerHints: {
+        readonly preferProvider?: string;
+        readonly fallbackProvider?: string;
+        readonly requireToolCalling?: boolean;
+        readonly requireMcp?: boolean;
+    };
+    readonly rationale: string;
+}
+/**
+ * RuntimeSidecar — the filtered, per-turn runtime context.
+ * Built from CapabilityPlan + CommandEnvelope.
+ * This replaces the old monolithic config injection.
+ */
+export interface RuntimeSidecar {
+    readonly capabilityPlan: CapabilityPlan;
+    readonly filteredMcpConfig: Record<string, unknown>;
+    readonly promptInjection: string;
+    readonly envOverrides: Record<string, string>;
+    readonly outputProfile: OutputProfile;
+}
+/**
+ * ProviderAdapter — abstract interface for any LLM provider.
+ * Replaces Kimi-specific wiring. Each provider implements this.
+ */
+export interface ProviderAdapter {
+    readonly name: string;
+    readonly supportsStreaming: boolean;
+    readonly supportsToolCalling: boolean;
+    readonly supportsMcp: boolean;
+    send(request: ProviderRequest): AsyncIterable<ProviderChunk>;
+    abort?(): void;
+}
+export interface ProviderRequest {
+    readonly prompt: string;
+    readonly systemPrompt?: string;
+    readonly tools?: readonly unknown[];
+    readonly mcpConfig?: Record<string, unknown>;
+    readonly sidecar: RuntimeSidecar;
+    readonly signal?: AbortSignal;
+}
+export interface ProviderChunk {
+    readonly type: "text" | "tool_call" | "error" | "done" | "mcp_event";
+    readonly content?: string;
+    readonly toolName?: string;
+    readonly toolArgs?: unknown;
+    readonly error?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * SubAgentTask — a task dispatched to a parallel sub-agent.
+ * Each sub-agent gets its own CapabilityPlan (skills, hooks, MCP).
+ */
+export interface SubAgentTask {
+    readonly id: string;
+    readonly name: string;
+    readonly role: string;
+    readonly goal: string;
+    readonly capabilityPlan: CapabilityPlan;
+    readonly dependsOn: readonly string[];
+    readonly priority: number;
+    readonly timeout?: number;
+}
+/**
+ * OrchestratorGoal — top-level goal managed by the orchestrator.
+ */
+export interface OrchestratorGoal {
+    readonly id: string;
+    readonly objective: string;
+    readonly tasks: readonly SubAgentTask[];
+    readonly maxWorkers: number;
+    readonly status: "pending" | "running" | "completed" | "failed";
+}

package/dist/cli/runtime/types.js

@@ -0,0 +1,6 @@
+/**
+ * Phase 1 — CLI Runtime Types
+ * Normalized command envelope, output profile, execution result, and errors.
+ * Based on the CLI architecture redesign spec (2026-05-25).
+ */
+export {};

package/dist/cli/theme/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI Theme — Barrel export for terminal capability, theme registry, and theme resolver.
+ */
+export { getTerminalCapability, defaultThemeForCapability, detectColorTier, colorTierForDepth, } from "./terminal-capability.js";
+export type { TerminalCapability, ColorDepth, ColorTier, } from "./terminal-capability.js";
+export { hexToOklab, hexToRgb255, normalizeHex, nearestXterm256, buildXterm256Lookup, } from "./oklab-quantize.js";
+export type { OklabColor } from "./oklab-quantize.js";
+export { compileTheme } from "./render-table.js";
+export type { Ansi16Name, CompiledTheme, OmkThemeV1, RenderEntry, ThemeSemanticSpec, ThemeTokenKind, ThemeUsage, } from "./render-table.js";
+export { getBuiltinTheme, listBuiltinThemes, registerBuiltinTheme, __registry, } from "./theme-registry.js";
+export type { SemanticToken, ThemePalette, } from "./theme-registry.js";
+export { resolveTheme } from "./theme-resolver.js";
+export type { ResolveThemeOptions } from "./theme-resolver.js";
+export { renderStatusFrame } from "./status-frame.js";
+export { listThemeDocuments, loadThemeDocument, validateThemeDocument, } from "./theme-doc.js";
+export type { ThemeDocumentRef } from "./theme-doc.js";
+export { explainColorTier } from "./tier-explain.js";
+export type { ColorTierExplanation } from "./tier-explain.js";

package/dist/cli/theme/index.js

@@ -0,0 +1,11 @@
+/**
+ * CLI Theme — Barrel export for terminal capability, theme registry, and theme resolver.
+ */
+export { getTerminalCapability, defaultThemeForCapability, detectColorTier, colorTierForDepth, } from "./terminal-capability.js";
+export { hexToOklab, hexToRgb255, normalizeHex, nearestXterm256, buildXterm256Lookup, } from "./oklab-quantize.js";
+export { compileTheme } from "./render-table.js";
+export { getBuiltinTheme, listBuiltinThemes, registerBuiltinTheme, __registry, } from "./theme-registry.js";
+export { resolveTheme } from "./theme-resolver.js";
+export { renderStatusFrame } from "./status-frame.js";
+export { listThemeDocuments, loadThemeDocument, validateThemeDocument, } from "./theme-doc.js";
+export { explainColorTier } from "./tier-explain.js";

package/dist/cli/theme/oklab-quantize.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CLI Theme — OKLab xterm-256 Quantizer
+ * Precomputes an OKLab nearest-neighbor lookup mapping 24-bit theme colors to
+ * xterm-256 indexes 16-255 ONLY. System colors 0-15 are never emitted because
+ * users commonly remap them, which would break theme contrast guarantees.
+ *
+ * Pure functions, no I/O. OKLab math is self-contained, ported from
+ * scripts/theme-check.mjs (Björn Ottosson sRGB → OKLab).
+ */
+export interface OklabColor {
+    readonly L: number;
+    readonly a: number;
+    readonly b: number;
+}
+/** Normalize "#aabbcc" / "AABBCC" to canonical "#AABBCC". Throws on bad input. */
+export declare function normalizeHex(hex: string): string;
+/** Parse a normalized 6-digit hex color into 0-255 RGB channels. */
+export declare function hexToRgb255(hex: string): readonly [number, number, number];
+export declare function hexToOklab(hex: string): OklabColor;
+/**
+ * Nearest xterm-256 index (16-255 only) for a 24-bit hex color, measured by
+ * Euclidean distance in OKLab.
+ */
+export declare function nearestXterm256(hex: string): number;
+/**
+ * Precompute a lookup table mapping each distinct theme color to its nearest
+ * xterm-256 index. Keys are normalized hex ("#AABBCC").
+ */
+export declare function buildXterm256Lookup(hexes: readonly string[]): ReadonlyMap<string, number>;

package/dist/cli/theme/oklab-quantize.js

@@ -0,0 +1,105 @@
+/**
+ * CLI Theme — OKLab xterm-256 Quantizer
+ * Precomputes an OKLab nearest-neighbor lookup mapping 24-bit theme colors to
+ * xterm-256 indexes 16-255 ONLY. System colors 0-15 are never emitted because
+ * users commonly remap them, which would break theme contrast guarantees.
+ *
+ * Pure functions, no I/O. OKLab math is self-contained, ported from
+ * scripts/theme-check.mjs (Björn Ottosson sRGB → OKLab).
+ */
+function linearize(c) {
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function channelsToOklab(r255, g255, b255) {
+    const r = linearize(r255 / 255);
+    const g = linearize(g255 / 255);
+    const b = linearize(b255 / 255);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return {
+        L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    };
+}
+const HEX6_RE = /^#?[0-9A-Fa-f]{6}$/;
+/** Normalize "#aabbcc" / "AABBCC" to canonical "#AABBCC". Throws on bad input. */
+export function normalizeHex(hex) {
+    if (!HEX6_RE.test(hex)) {
+        throw new Error(`oklab-quantize: invalid 24-bit hex color "${hex}"`);
+    }
+    const v = hex.startsWith("#") ? hex.slice(1) : hex;
+    return `#${v.toUpperCase()}`;
+}
+/** Parse a normalized 6-digit hex color into 0-255 RGB channels. */
+export function hexToRgb255(hex) {
+    const v = normalizeHex(hex).slice(1);
+    return [
+        Number.parseInt(v.slice(0, 2), 16),
+        Number.parseInt(v.slice(2, 4), 16),
+        Number.parseInt(v.slice(4, 6), 16),
+    ];
+}
+export function hexToOklab(hex) {
+    const [r, g, b] = hexToRgb255(hex);
+    return channelsToOklab(r, g, b);
+}
+// xterm 6x6x6 color-cube channel levels (indexes 16-231).
+const CUBE_LEVELS = [0, 95, 135, 175, 215, 255];
+/** Build the OKLab palette for xterm indexes 16-255 (cube + grayscale ramp). */
+function buildXtermPalette() {
+    const entries = [];
+    for (let r = 0; r < 6; r++) {
+        for (let g = 0; g < 6; g++) {
+            for (let b = 0; b < 6; b++) {
+                entries.push({
+                    index: 16 + 36 * r + 6 * g + b,
+                    lab: channelsToOklab(CUBE_LEVELS[r], CUBE_LEVELS[g], CUBE_LEVELS[b]),
+                });
+            }
+        }
+    }
+    // Grayscale ramp: indexes 232-255 map to gray levels 8, 18, ..., 238.
+    for (let i = 0; i < 24; i++) {
+        const v = 8 + 10 * i;
+        entries.push({ index: 232 + i, lab: channelsToOklab(v, v, v) });
+    }
+    return entries;
+}
+// Precomputed once at module load — this is the "theme build/load time" cost.
+const XTERM_PALETTE = buildXtermPalette();
+/**
+ * Nearest xterm-256 index (16-255 only) for a 24-bit hex color, measured by
+ * Euclidean distance in OKLab.
+ */
+export function nearestXterm256(hex) {
+    const lab = hexToOklab(hex);
+    let bestIndex = 16;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const entry of XTERM_PALETTE) {
+        const dL = lab.L - entry.lab.L;
+        const da = lab.a - entry.lab.a;
+        const db = lab.b - entry.lab.b;
+        const dist = dL * dL + da * da + db * db;
+        if (dist < bestDist) {
+            bestDist = dist;
+            bestIndex = entry.index;
+        }
+    }
+    return bestIndex;
+}
+/**
+ * Precompute a lookup table mapping each distinct theme color to its nearest
+ * xterm-256 index. Keys are normalized hex ("#AABBCC").
+ */
+export function buildXterm256Lookup(hexes) {
+    const lookup = new Map();
+    for (const hex of hexes) {
+        const key = normalizeHex(hex);
+        if (!lookup.has(key)) {
+            lookup.set(key, nearestXterm256(key));
+        }
+    }
+    return lookup;
+}

package/dist/cli/theme/render-table.d.ts

@@ -0,0 +1,59 @@
+/**
+ * CLI Theme — Render Table Compiler
+ * Compiles an omk.theme.v1 document (themes/*.theme.json) into per-surface
+ * render tables at startup. For each semantic token it precomputes the SGR
+ * sequence for the requested degradation tier:
+ *   truecolor → SGR 38;2;R;G;B
+ *   256       → SGR 38;5;N via the OKLab nearest-neighbor lookup (16-255 only)
+ *   16        → the theme's hand-authored ansi16 (fallback16) mapping
+ *   no-color  → empty string
+ * Single entrypoint: compileTheme(theme, tier).
+ */
+import type { ColorTier } from "./terminal-capability.js";
+export type ThemeUsage = "text" | "indicator" | "background";
+export type ThemeTokenKind = "state" | "chrome" | "background";
+export type Ansi16Name = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "brightBlack" | "brightRed" | "brightGreen" | "brightYellow" | "brightBlue" | "brightMagenta" | "brightCyan" | "brightWhite";
+export interface ThemeSemanticSpec {
+    readonly color: string;
+    readonly glyph?: string;
+    readonly kind?: ThemeTokenKind;
+    readonly usage: ThemeUsage;
+}
+export interface OmkThemeV1 {
+    readonly schemaVersion: "omk.theme.v1";
+    readonly name: string;
+    readonly displayName?: string;
+    readonly mode: "dark" | "light";
+    readonly primitives: Readonly<Record<string, string>>;
+    readonly backgrounds: readonly string[];
+    readonly semantics: Readonly<Record<string, ThemeSemanticSpec>>;
+    readonly components: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    readonly fallback16: Readonly<Record<string, string>>;
+}
+export interface RenderEntry {
+    /** Semantic role this entry resolves (e.g. "dag.lane.running"). */
+    readonly role: string;
+    /** Canonical 24-bit hex of the underlying primitive. */
+    readonly hex: string;
+    /** Mandatory state glyph, or "" for chrome/background tokens. */
+    readonly glyph: string;
+    /** Precomputed SGR open sequence for the compiled tier ("" on no-color). */
+    readonly sgr: string;
+}
+export interface CompiledTheme {
+    readonly name: string;
+    readonly tier: ColorTier;
+    /** SGR reset for this tier ("" on no-color). */
+    readonly reset: string;
+    /** Semantic role → precomputed render entry. */
+    readonly tokens: Readonly<Record<string, RenderEntry>>;
+    /** Component surface → slot → precomputed render entry. */
+    readonly surfaces: Readonly<Record<string, Readonly<Record<string, RenderEntry>>>>;
+    /** Wrap text in the precomputed sequence for a semantic role. */
+    readonly paint: (role: string, text: string) => string;
+}
+/**
+ * Compile an omk.theme.v1 document into a per-surface render table for one
+ * degradation tier. Pure: computes everything up front, performs no I/O.
+ */
+export declare function compileTheme(theme: OmkThemeV1, tier: ColorTier): CompiledTheme;

package/dist/cli/theme/render-table.js

@@ -0,0 +1,112 @@
+/**
+ * CLI Theme — Render Table Compiler
+ * Compiles an omk.theme.v1 document (themes/*.theme.json) into per-surface
+ * render tables at startup. For each semantic token it precomputes the SGR
+ * sequence for the requested degradation tier:
+ *   truecolor → SGR 38;2;R;G;B
+ *   256       → SGR 38;5;N via the OKLab nearest-neighbor lookup (16-255 only)
+ *   16        → the theme's hand-authored ansi16 (fallback16) mapping
+ *   no-color  → empty string
+ * Single entrypoint: compileTheme(theme, tier).
+ */
+import { buildXterm256Lookup, normalizeHex, hexToRgb255 } from "./oklab-quantize.js";
+const ESC = "\u001b[";
+const SGR_RESET = `${ESC}0m`;
+// Foreground SGR codes for the 16-color tier (standard 30-37, bright 90-97).
+const ANSI16_FG = {
+    black: 30,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 34,
+    magenta: 35,
+    cyan: 36,
+    white: 37,
+    brightBlack: 90,
+    brightRed: 91,
+    brightGreen: 92,
+    brightYellow: 93,
+    brightBlue: 94,
+    brightMagenta: 95,
+    brightCyan: 96,
+    brightWhite: 97,
+};
+function isAnsi16Name(name) {
+    return Object.prototype.hasOwnProperty.call(ANSI16_FG, name);
+}
+function resolvePrimitiveHex(theme, role, color) {
+    const raw = theme.primitives[color];
+    if (raw === undefined) {
+        throw new Error(`compileTheme(${theme.name}): semantic "${role}" references unknown primitive "${color}"`);
+    }
+    return normalizeHex(raw);
+}
+function sgrForTier(theme, role, hex, tier, lookup256) {
+    switch (tier) {
+        case "truecolor": {
+            const [r, g, b] = hexToRgb255(hex);
+            return `${ESC}38;2;${r};${g};${b}m`;
+        }
+        case "256": {
+            const index = lookup256.get(hex);
+            if (index === undefined) {
+                throw new Error(`compileTheme(${theme.name}): missing 256-color lookup for "${role}" (${hex})`);
+            }
+            return `${ESC}38;5;${index}m`;
+        }
+        case "16": {
+            const name = theme.fallback16[role];
+            if (name === undefined || !isAnsi16Name(name)) {
+                throw new Error(`compileTheme(${theme.name}): semantic "${role}" has no valid ansi16 fallback (got "${name ?? "<missing>"}")`);
+            }
+            return `${ESC}${ANSI16_FG[name]}m`;
+        }
+        case "no-color":
+            return "";
+    }
+}
+/**
+ * Compile an omk.theme.v1 document into a per-surface render table for one
+ * degradation tier. Pure: computes everything up front, performs no I/O.
+ */
+export function compileTheme(theme, tier) {
+    // Precompute the OKLab → xterm-256 lookup once per compile (build/load time).
+    const distinctHexes = Object.entries(theme.semantics).map(([role, spec]) => resolvePrimitiveHex(theme, role, spec.color));
+    const lookup256 = tier === "256" ? buildXterm256Lookup(distinctHexes) : new Map();
+    const tokens = {};
+    for (const [role, spec] of Object.entries(theme.semantics)) {
+        const hex = resolvePrimitiveHex(theme, role, spec.color);
+        tokens[role] = {
+            role,
+            hex,
+            glyph: spec.glyph ?? "",
+            sgr: sgrForTier(theme, role, hex, tier, lookup256),
+        };
+    }
+    const surfaces = {};
+    for (const [surface, slots] of Object.entries(theme.components)) {
+        const compiled = {};
+        for (const [slot, role] of Object.entries(slots)) {
+            const entry = tokens[role];
+            if (entry === undefined) {
+                throw new Error(`compileTheme(${theme.name}): component ${surface}.${slot} references unknown semantic role "${role}"`);
+            }
+            compiled[slot] = entry;
+        }
+        surfaces[surface] = compiled;
+    }
+    const reset = tier === "no-color" ? "" : SGR_RESET;
+    return {
+        name: theme.name,
+        tier,
+        reset,
+        tokens,
+        surfaces,
+        paint(role, text) {
+            const entry = tokens[role];
+            if (entry === undefined || entry.sgr === "")
+                return text;
+            return entry.sgr + text + reset;
+        },
+    };
+}