@kontextmind/kxm 0.7.112 → 0.7.118

package/packages/core/tui/src/adapters/claude.ts

@@ -0,0 +1,131 @@
+/**
+ * Claude Code TUI & Channel Adapter.
+ *
+ * Formats KXM goals, tasks, upcoming lookaheads, retries, and workflow
+ * histories for Claude Code's terminal output, hook contexts, and channel events.
+ *
+ * Supports:
+ * - Single-line and boxed HUD banners for terminal output
+ * - Lookahead upcoming queue with dependency annotations
+ * - Formatted history timeline for channel delivery and SessionStart hooks
+ * - Plan optimizer proposals formatting
+ */
+
+import { type HistoryEventItem, renderWorkflowHistoryMarkdown } from "../tui/history.ts";
+import { type QueuedTaskItem } from "../tui/queue.ts";
+import { type OptimizerResult } from "../tui/optimizer.ts";
+import { type RoleBudgetState, type RoleBudgetConfig } from "../tui/roleBudget.ts";
+
+export interface ClaudeTaskHudOptions {
+  readonly goal: string;
+  readonly stageName: string;
+  readonly stageIndex: number;
+  readonly totalStages: number;
+  readonly completedTasks: number;
+  readonly totalTasks: number;
+  readonly activeTaskTitle?: string | undefined;
+  readonly activeRole?: string | undefined;
+  readonly activeModel?: string | undefined;
+  readonly attempt?: number | undefined;
+  readonly maxAttempts?: number | undefined;
+  readonly elapsedSeconds?: number | undefined;
+  readonly tokensIn?: number | undefined;
+  readonly tokensOut?: number | undefined;
+  readonly autoDispatch?: boolean | undefined;
+}
+
+/**
+ * Format a high-visibility, single-line or framed HUD for Claude Code terminal output.
+ */
+export function formatClaudeTaskHud(options: ClaudeTaskHudOptions, compact = false): string {
+  const percent = options.totalTasks > 0
+    ? Math.round((options.completedTasks / options.totalTasks) * 100)
+    : 0;
+  const filled = Math.round((percent / 100) * 10);
+  const bar = `[${"█".repeat(filled)}${"░".repeat(10 - filled)}] ${percent}%`;
+  const modeTag = options.autoDispatch ? "[AUTO]" : "[STEP]";
+  const attemptTag = options.attempt && options.attempt > 1 ? ` (Attempt ${options.attempt}/${options.maxAttempts ?? 3})` : "";
+  const timeTag = options.elapsedSeconds !== undefined ? ` ⏱ ${options.elapsedSeconds}s` : "";
+
+  if (compact) {
+    return `[KXM ${modeTag}] ${options.goal} ── Stage ${options.stageIndex}/${options.totalStages} ${bar}${attemptTag}${timeTag}`;
+  }
+
+  const activeTask = options.activeTaskTitle
+    ? `\n│  Active Task: ${options.activeTaskTitle}${attemptTag} [${options.activeRole ?? "agent"} (${options.activeModel ?? "default"})]`
+    : "";
+
+  return [
+    `┌── KXM TASK HUD ─────────────────────────────────────────────────────────────┐`,
+    `│  Goal: ${options.goal}`,
+    `│  Stage ${options.stageIndex}/${options.totalStages}: ${options.stageName}  │ Progress: ${bar}${timeTag} │ Mode: ${modeTag}${activeTask}`,
+    `└─────────────────────────────────────────────────────────────────────────────┘`,
+  ].join("\n");
+}
+
+/**
+ * Format the upcoming lookahead queue for Claude Code context and channel streams.
+ */
+export function formatClaudeUpcomingQueue(tasks: readonly QueuedTaskItem[]): string {
+  if (tasks.length === 0) return "No upcoming tasks in queue.";
+
+  const lines = ["### KXM Upcoming Task Queue:"];
+  for (let i = 0; i < tasks.length; i++) {
+    const t = tasks[i]!;
+    const deps = t.dependencies.length > 0 ? ` (Requires: ${t.dependencies.join(", ")})` : " (Ready)";
+    lines.push(`${i + 1}. [${t.status.toUpperCase()}] **${t.title}** (\`${t.id}\`)`);
+    lines.push(`   Role: \`${t.role}\` [${t.harness}/${t.model}]${deps}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Format plan optimizer proposals for Claude Code review prompts.
+ */
+export function formatClaudeOptimizerReport(result: OptimizerResult): string {
+  if (result.proposals.length === 0) {
+    return "Plan Optimizer: No pending optimization proposals.";
+  }
+
+  const lines = [
+    `### KXM Plan Optimizer Proposals:`,
+    `Total Projected Savings: -${result.totalProjectedTimeSavingsSeconds}s execution time, -${result.totalProjectedCostSavingsPercent}% token cost`,
+    "",
+  ];
+
+  for (const p of result.proposals) {
+    const icon = p.category === "concurrency" ? "⚡" : "💰";
+    lines.push(`${icon} **${p.title}** (\`${p.id}\`)`);
+    lines.push(`   ${p.description}`);
+    if (p.suggestedModel) {
+      lines.push(`   Suggested Routing: \`${p.suggestedHarness ?? "pi"}/${p.suggestedModel}\``);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").trim();
+}
+
+/**
+ * Format role budget and subscription status for Claude Code channel info.
+ */
+export function formatClaudeRoleBudget(config: RoleBudgetConfig, state: RoleBudgetState): string {
+  const runCap = config.runSpendCapUsd !== undefined ? `$${config.runSpendCapUsd.toFixed(2)}` : "Unmetered";
+  const monthlyCap = config.monthlySpendCapUsd !== undefined ? `$${config.monthlySpendCapUsd.toFixed(2)}` : "Unmetered";
+  const currentRun = `$${state.currentRunSpendUsd.toFixed(4)}`;
+  const currentMonthly = `$${state.currentMonthlySpendUsd.toFixed(2)}`;
+
+  return [
+    `Role: ${config.roleId} (${config.type})`,
+    `Run Spend: ${currentRun} / ${runCap}`,
+    `Monthly Spend: ${currentMonthly} / ${monthlyCap}`,
+    `On Exhausted: ${config.onExhausted}${config.fallbackModel ? ` (Fallback: ${config.fallbackModel})` : ""}`,
+  ].join(" │ ");
+}
+
+/**
+ * Format history for Claude Code channel updates.
+ */
+export function formatClaudeWorkflowHistory(runId: string, events: readonly HistoryEventItem[]): string {
+  return renderWorkflowHistoryMarkdown(runId, events);
+}

package/packages/core/tui/src/adapters/historyExport.ts

@@ -0,0 +1,35 @@
+/**
+ * History export adapter for local disk persistence.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  renderWorkflowHistoryMarkdown,
+  formatWorkflowHistoryJsonl,
+  type HistoryEventItem,
+} from "../tui/history.ts";
+
+export interface ExportedHistoryFiles {
+  readonly mdPath: string;
+  readonly jsonlPath: string;
+}
+
+/**
+ * Export workflow history into both Markdown retrospective and JSONL audit logs on disk.
+ */
+export function exportWorkflowHistory(
+  runId: string,
+  events: readonly HistoryEventItem[],
+  destinationDir: string,
+): ExportedHistoryFiles {
+  mkdirSync(destinationDir, { recursive: true });
+  const sanitizedRunId = runId.replaceAll(/[^a-zA-Z0-9_-]/g, "_");
+  const mdPath = join(destinationDir, `retrospective-${sanitizedRunId}.md`);
+  const jsonlPath = join(destinationDir, `history-${sanitizedRunId}.jsonl`);
+
+  writeFileSync(mdPath, renderWorkflowHistoryMarkdown(runId, events), "utf8");
+  writeFileSync(jsonlPath, formatWorkflowHistoryJsonl(runId, events), "utf8");
+
+  return { mdPath, jsonlPath };
+}

package/packages/core/tui/src/adapters/omp.ts

@@ -0,0 +1,174 @@
+/**
+ * OMP (Oh My Pi) overlay adapter.
+ *
+ * Provides a collapsible, differential-rendered task & plan overlay
+ * designed for OMP's overlay stack and custom TUI components.
+ *
+ * Supports:
+ * - Collapsed status HUD (single-line strip) vs Expanded 3-pane dashboard
+ * - Interactive task reordering (Shift+Up / Shift+Down)
+ * - Auto-dispatch flag toggling ('a' key)
+ * - On-demand plan optimizer ('o' key)
+ * - Full workflow history view ('h' key) with dual markdown + JSONL export ('x' key)
+ */
+
+import { KxmTuiPanelComponent } from "../tui/panelComponent.ts";
+import type { KxmTuiRegistry } from "../services/registry.ts";
+import { createKxmTuiThemeFromPi, type PiThemeLike, type KxmTuiTheme } from "../tui/theme.ts";
+import type { KxmTuiCustomComponent, KxmTuiCustomTui } from "./pi.ts";
+
+export type OverlayMode = "collapsed" | "expanded" | "history" | "optimizer";
+
+export interface KxmTuiOmpOverlayOptions {
+  readonly registry: KxmTuiRegistry;
+  readonly tui: KxmTuiCustomTui;
+  readonly theme: PiThemeLike | KxmTuiTheme;
+  readonly title: string;
+  readonly goal?: string | undefined;
+  readonly initialMode?: OverlayMode | undefined;
+  readonly autoDispatch?: boolean | undefined;
+  readonly onToggleAutoDispatch?: ((auto: boolean) => void) | undefined;
+  readonly onReorderTasks?: ((fromIndex: number, toIndex: number) => void) | undefined;
+  readonly onRunOptimizer?: (() => Promise<{ savingsTokens: number; savingsSeconds: number } | void>) | undefined;
+  readonly onExportHistory?: ((format: "both" | "md" | "jsonl") => Promise<{ mdPath?: string; jsonlPath?: string }>) | undefined;
+  readonly width?: (() => number) | undefined;
+  readonly done?: ((closed: true) => void) | undefined;
+}
+
+export interface KxmTuiOmpOverlayComponent extends KxmTuiCustomComponent {
+  getMode(): OverlayMode;
+  setMode(mode: OverlayMode): void;
+  isAutoDispatch(): boolean;
+  toggleAutoDispatch(): void;
+  dispose(): void;
+}
+
+function resolveKxmTheme(theme: PiThemeLike | KxmTuiTheme): KxmTuiTheme {
+  if ("headerBg" in theme && typeof (theme as KxmTuiTheme).headerBg === "function") {
+    return theme as KxmTuiTheme;
+  }
+  return createKxmTuiThemeFromPi(theme as PiThemeLike);
+}
+
+export function createKxmTuiOmpOverlay(options: KxmTuiOmpOverlayOptions): KxmTuiOmpOverlayComponent {
+  let closed = false;
+  let mode: OverlayMode = options.initialMode ?? "expanded";
+  let autoDispatch = Boolean(options.autoDispatch);
+  const theme: KxmTuiTheme = resolveKxmTheme(options.theme);
+
+  const panel = new KxmTuiPanelComponent({
+    registry: options.registry,
+    theme,
+    title: options.title,
+    ...(options.goal ? { breadcrumb: `Goal: ${options.goal}` } : {}),
+    helpLines: [
+      "[Ctrl+O/F2] Toggle Fold  [h] History  [a] Toggle Auto  [o] Optimize  [Shift+↑/↓] Reorder",
+    ],
+    requestRender: () => options.tui.requestRender(),
+    onQuit: () => {
+      if (closed) return;
+      closed = true;
+      panel.dispose();
+      options.done?.(true);
+    },
+    ...(options.width === undefined ? {} : { getWidth: options.width }),
+  });
+
+  function renderCollapsed(width: number): string[] {
+    const goalText = options.goal ? `Goal: ${options.goal}` : options.title;
+    const modeBadge = autoDispatch ? theme.accent("[AUTO: ON]") : theme.dim("[STEP MODE]");
+    const hint = theme.dim("[Ctrl+O to Expand]");
+    const content = ` [KXM] ${goalText} ── ${modeBadge} ── ${hint}`;
+    const pad = Math.max(0, width - content.length);
+    return [content + " ".repeat(pad)];
+  }
+
+  function handleInput(data: string): void {
+    if (closed) return;
+
+    // Toggle collapse: Ctrl+O (\x0f) or F2 (\x1bOQ or \x1b[12~)
+    if (data === "\x0f" || data === "\x1bOQ" || data === "\x1b[12~") {
+      mode = mode === "collapsed" ? "expanded" : "collapsed";
+      options.tui.requestRender();
+      return;
+    }
+
+    // When collapsed, only toggle/expand is handled
+    if (mode === "collapsed") {
+      if (data === "\r" || data === " " || data === "o" || data === "O") {
+        mode = "expanded";
+        options.tui.requestRender();
+      }
+      return;
+    }
+
+    // Toggle Auto-dispatch flag
+    if (data === "a" || data === "A") {
+      autoDispatch = !autoDispatch;
+      options.onToggleAutoDispatch?.(autoDispatch);
+      options.tui.requestRender();
+      return;
+    }
+
+    // History mode toggle
+    if (data === "h" || data === "H") {
+      mode = mode === "history" ? "expanded" : "history";
+      options.tui.requestRender();
+      return;
+    }
+
+    // Optimizer invocation
+    if (data === "o" || data === "O") {
+      mode = "optimizer";
+      options.onRunOptimizer?.();
+      options.tui.requestRender();
+      return;
+    }
+
+    // Export history in both formats
+    if ((data === "x" || data === "X") && mode === "history") {
+      options.onExportHistory?.("both");
+      options.tui.requestRender();
+      return;
+    }
+
+    // Escape in sub-modes returns to expanded
+    if (data === "\x1b" && mode !== "expanded") {
+      mode = "expanded";
+      options.tui.requestRender();
+      return;
+    }
+
+    // Forward to underlying KXM panel component
+    panel.handleInput(data);
+    options.tui.requestRender();
+  }
+
+  return {
+    getMode: () => mode,
+    setMode: (nextMode: OverlayMode) => {
+      mode = nextMode;
+      options.tui.requestRender();
+    },
+    isAutoDispatch: () => autoDispatch,
+    toggleAutoDispatch: () => {
+      autoDispatch = !autoDispatch;
+      options.onToggleAutoDispatch?.(autoDispatch);
+      options.tui.requestRender();
+    },
+    render: (width: number) => {
+      if (mode === "collapsed") {
+        return renderCollapsed(width);
+      }
+      return panel.render(width);
+    },
+    handleInput,
+    invalidate: () => panel.invalidate(),
+    dispose: () => {
+      if (closed) return;
+      closed = true;
+      panel.dispose();
+      options.done?.(true);
+    },
+  };
+}

package/packages/core/tui/src/adapters/pi.ts

@@ -13,6 +13,11 @@
 import { KxmTuiPanelComponent } from "../tui/panelComponent.ts";
 import type { KxmTuiRegistry } from "../services/registry.ts";
 import { createKxmTuiThemeFromPi, type PiThemeLike } from "../tui/theme.ts";
+import {
+  createKxmTuiOmpOverlay,
+  type KxmTuiOmpOverlayComponent,
+  type KxmTuiOmpOverlayOptions,
+} from "./omp.ts";
 
 /** The renderer handle Pi passes to a custom component. */
 export interface KxmTuiCustomTui {
@@ -38,6 +43,35 @@ export interface KxmTuiPiPanelOptions {
   readonly done?: (closed: true) => void;
 }
 
+export interface KxmTuiPiOverlayOptions extends KxmTuiOmpOverlayOptions {}
+export type KxmTuiPiOverlayComponent = KxmTuiOmpOverlayComponent;
+
+/**
+ * Create a collapsible Task & Plan overlay for Pi.
+ *
+ * Reuses the differential rendering engine and OMP overlay model,
+ * compatible with Pi's `ctx.ui.custom` hook and keybinding stack.
+ */
+export const createKxmTuiPiOverlay = createKxmTuiOmpOverlay;
+
+/**
+ * Format widget lines for Pi's `ctx.ui.setWidget`.
+ */
+export function renderPiWorkflowWidget(options: {
+  readonly goal: string;
+  readonly stage: string;
+  readonly progressPercent: number;
+  readonly activeTask?: string | undefined;
+  readonly autoDispatch?: boolean | undefined;
+}): string[] {
+  const filled = Math.min(10, Math.max(0, Math.round((options.progressPercent / 100) * 10)));
+  const bar = `[${"█".repeat(filled)}${"░".repeat(10 - filled)}] ${options.progressPercent}%`;
+  const mode = options.autoDispatch ? "AUTO" : "STEP";
+  const line1 = `[KXM] Goal: ${options.goal} ── Stage: ${options.stage} (${bar}) [${mode}]`;
+  const line2 = options.activeTask ? `  Active: ${options.activeTask}` : `  Waiting for next dispatch (use /kxm progress)`;
+  return [line1, line2];
+}
+
 /**
  * Build the object to return from `ctx.ui.custom`.
  *

package/packages/core/tui/src/exports/index.ts

@@ -25,6 +25,14 @@ export * from "../tui/theme.ts";
 export * from "../tui/panel.ts";
 export * from "../tui/render.ts";
 export * from "../tui/panelComponent.ts";
+export * from "../tui/optimizer.ts";
+export * from "../tui/history.ts";
+export * from "../tui/queue.ts";
+export * from "../tui/roleBudget.ts";
+export * from "../tui/modelSelector.ts";
 export * from "../services/registry.ts";
 export * from "../adapters/terminal.ts";
 export * from "../adapters/pi.ts";
+export * from "../adapters/omp.ts";
+export * from "../adapters/claude.ts";
+export * from "../adapters/historyExport.ts";

package/packages/core/tui/src/tui/history.ts

@@ -0,0 +1,106 @@
+/**
+ * Workflow History & Journal View Engine.
+ *
+ * Tracks the complete chronological lifecycle of the active run:
+ * - Event classification (Tasks, Gates, Retries, Peers, State)
+ * - Filtering by category and search query
+ * - Dual format generators: clean Markdown retrospective + JSONL audit ledger
+ */
+
+export type HistoryCategory = "all" | "task" | "gate" | "retry" | "peer" | "state";
+
+export interface HistoryEventItem {
+  readonly id: string;
+  readonly timestamp: string;
+  readonly category: Exclude<HistoryCategory, "all">;
+  readonly title: string;
+  readonly stageId?: string | undefined;
+  readonly taskId?: string | undefined;
+  readonly role?: string | undefined;
+  readonly harness?: string | undefined;
+  readonly model?: string | undefined;
+  readonly attempt?: number | undefined;
+  readonly status: "passed" | "failed" | "warning" | "in_flight" | "degraded";
+  readonly durationMs?: number | undefined;
+  readonly tokensIn?: number | undefined;
+  readonly tokensOut?: number | undefined;
+  readonly costUsd?: number | undefined;
+  readonly artifacts?: readonly string[] | undefined;
+  readonly evidenceHashes?: readonly string[] | undefined;
+  readonly journalSummary?: string | undefined;
+}
+
+export interface HistoryFilterOptions {
+  readonly category?: HistoryCategory | undefined;
+  readonly query?: string | undefined;
+}
+
+/**
+ * Filter history items by category and substring query.
+ */
+export function filterHistoryEvents(
+  events: readonly HistoryEventItem[],
+  options: HistoryFilterOptions = {},
+): HistoryEventItem[] {
+  const category = options.category ?? "all";
+  const query = options.query?.trim().toLowerCase();
+
+  return events.filter((ev) => {
+    if (category !== "all" && ev.category !== category) return false;
+    if (!query) return true;
+    const matchTarget = `${ev.id} ${ev.title} ${ev.stageId ?? ""} ${ev.taskId ?? ""} ${ev.role ?? ""} ${ev.model ?? ""} ${ev.journalSummary ?? ""}`.toLowerCase();
+    return matchTarget.includes(query);
+  });
+}
+
+/**
+ * Render retrospective markdown text from workflow events.
+ */
+export function renderWorkflowHistoryMarkdown(
+  runId: string,
+  events: readonly HistoryEventItem[],
+): string {
+  const totalSpend = events.reduce((acc, ev) => acc + (ev.costUsd ?? 0), 0);
+  const passedCount = events.filter((ev) => ev.status === "passed").length;
+  const failedCount = events.filter((ev) => ev.status === "failed").length;
+
+  let mdContent = `# KXM Workflow Retrospective: ${runId}\n\n`;
+  mdContent += `**Total Events:** ${events.length} (Passed: ${passedCount}, Failed: ${failedCount})\n`;
+  mdContent += `**Total Spend:** $${totalSpend.toFixed(4)} USD\n\n`;
+  mdContent += `## Chronological Event Journal\n\n`;
+  mdContent += `| Timestamp | Category | Title | Status | Role / Model | Duration | Spend |\n`;
+  mdContent += `|---|---|---|---|---|---|---|\n`;
+
+  for (const ev of events) {
+    const elapsed = ev.durationMs !== undefined ? `${(ev.durationMs / 1000).toFixed(1)}s` : "-";
+    const spend = ev.costUsd !== undefined ? `$${ev.costUsd.toFixed(4)}` : "-";
+    const roleModel = ev.role ? `${ev.role} (${ev.harness ?? "-"}/${ev.model ?? "-"})` : "-";
+    mdContent += `| ${ev.timestamp} | ${ev.category} | ${ev.title} | ${ev.status} | ${roleModel} | ${elapsed} | ${spend} |\n`;
+  }
+
+  mdContent += `\n## Produced Artifacts & Proofs\n\n`;
+  for (const ev of events) {
+    if (ev.artifacts && ev.artifacts.length > 0) {
+      mdContent += `### ${ev.title} (${ev.id})\n`;
+      for (const art of ev.artifacts) {
+        mdContent += `- \`${art}\`\n`;
+      }
+    }
+  }
+
+  return mdContent;
+}
+
+/**
+ * Format JSONL audit ledger lines from workflow events.
+ */
+export function formatWorkflowHistoryJsonl(
+  runId: string,
+  events: readonly HistoryEventItem[],
+): string {
+  return events.map((ev) => JSON.stringify({
+    schema: "kxm.workflow-history-event.v1",
+    runId,
+    ...ev,
+  })).join("\n") + "\n";
+}

package/packages/core/tui/src/tui/modelSelector.ts

@@ -0,0 +1,43 @@
+/**
+ * Model Selector & Provider Authentication Model.
+ *
+ * Provides fast fuzzy filtering, capability inspection, and
+ * provider readiness status across all supported harnesses.
+ */
+
+export interface ModelOptionItem {
+  readonly id: string;
+  readonly selector: string;
+  readonly name: string;
+  readonly provider: string;
+  readonly harness: string;
+  readonly contextWindow: number;
+  readonly maxTokens?: number | undefined;
+  readonly reasoning: boolean;
+  readonly thinkingLevels?: readonly string[] | undefined;
+  readonly cost: {
+    readonly inputPerMillion: number;
+    readonly outputPerMillion: number;
+    readonly cacheReadPerMillion?: number | undefined;
+  };
+  readonly authStatus: "ready" | "missing_auth" | "unprobed";
+  readonly authHint?: string | undefined;
+}
+
+export function filterModelOptions(
+  models: readonly ModelOptionItem[],
+  query?: string | undefined,
+  providerFilter?: string | undefined,
+): ModelOptionItem[] {
+  const q = query?.trim().toLowerCase();
+  const prov = providerFilter?.trim().toLowerCase();
+
+  return models.filter((m) => {
+    if (prov && m.provider.toLowerCase() !== prov && m.harness.toLowerCase() !== prov) {
+      return false;
+    }
+    if (!q) return true;
+    const matchTarget = `${m.id} ${m.selector} ${m.name} ${m.provider} ${m.harness}`.toLowerCase();
+    return matchTarget.includes(q);
+  });
+}