@kontextmind/kxm 0.7.177 → 0.7.179

package/plugins/kxm/src/config-editor.ts

@@ -0,0 +1,479 @@
+/**
+ * Owner for the `kxm.config.v1` terminal editor.
+ *
+ * The panel publishes this contribution and routes every write back here.
+ * `listSections` re-reads the merged files on each publish. `set` and `clear`
+ * validate the field and the value, then call the config owner. A refusal
+ * throws before either owner call, so the file bytes stay as they were.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { parse } from "yaml";
+import {
+  KXM_TUI_CLEAR_ACTION,
+  KXM_TUI_SET_ACTION,
+  createKxmTuiRegistry,
+  createKxmTuiPiPanel,
+  createPlainKxmTuiTheme,
+  runKxmTuiPanel,
+  type KxmTuiContribution,
+  type KxmTuiField,
+  type KxmTuiSectionView,
+} from "@kontextmind/tui";
+import {
+  deleteKxmConfigValue,
+  getKxmConfigValue,
+  kxmConfigFileForScope,
+  loadKxmConfig,
+  setKxmConfigValue,
+  userConfigDirForEnv,
+  type KxmResolvedConfig,
+} from "./config.ts";
+
+export const KXM_CONFIG_EDITOR_SOURCE = "kxm/config";
+
+export type KxmConfigEditorScope = "project" | "user";
+
+const INTEGER_TEXT = /^(0|[1-9][0-9]*)$/;
+const DECIMAL_TEXT = /^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$/;
+/** Workflow and harness ids already in use, including `@`, with no whitespace. */
+const TEXT_VALUE = /^[A-Za-z0-9@][A-Za-z0-9@._:/-]{0,127}$/;
+
+interface EnumSpec {
+  readonly kind: "enum";
+  readonly choices: readonly string[];
+}
+
+interface NumberSpec {
+  readonly kind: "number";
+  readonly integer: boolean;
+  readonly min: number;
+  readonly max: number;
+}
+
+interface TextSpec {
+  readonly kind: "text";
+}
+
+type ValueSpec = EnumSpec | NumberSpec | TextSpec;
+
+interface ConfigEditorFieldSpec {
+  readonly id: string;
+  readonly label: string;
+  readonly keyPath: string;
+  readonly spec: ValueSpec;
+  readonly note?: string;
+}
+
+interface ConfigEditorSectionSpec {
+  readonly id: string;
+  readonly title: string;
+  readonly order: number;
+  readonly fields: readonly ConfigEditorFieldSpec[];
+}
+
+const SCREEN_CHOICES = ["agents", "tasks", "workflows", "plans", "inbox", "procs", "spend"] as const;
+
+const SECTIONS: readonly ConfigEditorSectionSpec[] = [
+  {
+    id: "user",
+    title: "User",
+    order: 10,
+    fields: [
+      { id: "user-theme", label: "Theme", keyPath: "user.theme", spec: { kind: "enum", choices: ["dark", "light", "minimal"] } },
+      { id: "user-token-budget", label: "Token budget", keyPath: "user.tokenBudget", spec: { kind: "number", integer: true, min: 1, max: 2_000_000 } },
+    ],
+  },
+  {
+    id: "defaults",
+    title: "Defaults",
+    order: 20,
+    fields: [
+      { id: "defaults-workflow", label: "Workflow", keyPath: "defaults.workflow", spec: { kind: "text" } },
+      { id: "defaults-harness", label: "Harness", keyPath: "defaults.harness", spec: { kind: "text" } },
+    ],
+  },
+  {
+    id: "dash",
+    title: "Dashboard",
+    order: 30,
+    fields: [
+      { id: "dash-screen", label: "Default screen", keyPath: "dash.defaultScreen", spec: { kind: "enum", choices: SCREEN_CHOICES } },
+      { id: "dash-refresh", label: "Refresh interval", keyPath: "dash.refreshIntervalMs", spec: { kind: "number", integer: true, min: 250, max: 3_600_000 } },
+      { id: "dash-auto-open", label: "Auto-open", keyPath: "dash.autoOpen", spec: { kind: "enum", choices: ["true", "false"] } },
+    ],
+  },
+  {
+    id: "sync",
+    title: "Sync",
+    order: 40,
+    fields: [
+      { id: "sync-tracker", label: "Default tracker", keyPath: "sync.defaultTracker", spec: { kind: "enum", choices: ["github", "jira", "none"] } },
+    ],
+  },
+  {
+    id: "hub",
+    title: "Hub",
+    order: 50,
+    fields: [
+      {
+        id: "hub-auto-start",
+        label: "Auto-start",
+        keyPath: "hub.autoStart",
+        spec: { kind: "enum", choices: ["background", "off"] },
+        note: "Hub URLs and key references stay out of this panel.",
+      },
+    ],
+  },
+  {
+    id: "improvement",
+    title: "Improvement",
+    order: 60,
+    fields: [
+      { id: "improvement-policy", label: "Promotion policy", keyPath: "improvement.promotionPolicy", spec: { kind: "enum", choices: ["manual_pr", "critic_quorum", "auto_threshold"] } },
+      { id: "improvement-half-life", label: "Telemetry half-life", keyPath: "improvement.telemetryHalfLifeDays", spec: { kind: "number", integer: false, min: 0.000001, max: 3650 } },
+      { id: "improvement-min-runs", label: "Minimum runs", keyPath: "improvement.autoThreshold.minRuns", spec: { kind: "number", integer: true, min: 1, max: 1_000_000 } },
+      { id: "improvement-min-pass-rate", label: "Minimum pass rate", keyPath: "improvement.autoThreshold.minPassRate", spec: { kind: "number", integer: false, min: 0, max: 1 } },
+      { id: "improvement-min-cost-savings", label: "Minimum cost savings", keyPath: "improvement.autoThreshold.minCostSavings", spec: { kind: "number", integer: false, min: 0, max: 1_000_000 } },
+    ],
+  },
+  {
+    id: "routing",
+    title: "Routing",
+    order: 70,
+    fields: [
+      {
+        id: "routing-shadow",
+        label: "Shadow execution",
+        keyPath: "routing.shadowExecution.enabled",
+        spec: { kind: "enum", choices: ["true", "false"] },
+        note: "Strategy, fallback, and context limits stay in role and route files.",
+      },
+      { id: "routing-sample-rate", label: "Sample rate", keyPath: "routing.shadowExecution.sampleRate", spec: { kind: "number", integer: false, min: 0, max: 1 } },
+      { id: "routing-breaker-mode", label: "Breaker mode", keyPath: "routing.circuitBreaker.mode", spec: { kind: "enum", choices: ["soft_demotion", "quarantine"] } },
+      { id: "routing-failure-threshold", label: "Failure threshold", keyPath: "routing.circuitBreaker.failureThreshold", spec: { kind: "number", integer: true, min: 1, max: 10_000 } },
+      { id: "routing-window-seconds", label: "Window seconds", keyPath: "routing.circuitBreaker.windowSeconds", spec: { kind: "number", integer: true, min: 1, max: 31_536_000 } },
+      { id: "routing-cooldown-seconds", label: "Cooldown seconds", keyPath: "routing.circuitBreaker.cooldownSeconds", spec: { kind: "number", integer: true, min: 0, max: 31_536_000 } },
+      { id: "routing-penalty", label: "Penalty multiplier", keyPath: "routing.circuitBreaker.penaltyMultiplier", spec: { kind: "number", integer: false, min: 0.000001, max: 1000 } },
+    ],
+  },
+  {
+    id: "telemetry",
+    title: "Telemetry",
+    order: 80,
+    fields: [
+      { id: "telemetry-federated", label: "Federated", keyPath: "telemetry.federated", spec: { kind: "enum", choices: ["true", "false"] } },
+      { id: "telemetry-anonymize", label: "Anonymize", keyPath: "telemetry.anonymize", spec: { kind: "enum", choices: ["true", "false"] } },
+    ],
+  },
+];
+
+
+export class KxmConfigEditorError extends Error {
+  readonly code = "config_edit_refused";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "KxmConfigEditorError";
+  }
+}
+
+export interface KxmConfigEditorTarget {
+  readonly cwd: string;
+  readonly scope: KxmConfigEditorScope;
+  readonly userConfigDir?: string | undefined;
+}
+
+export function kxmConfigEditorKeyPaths(): readonly string[] {
+  return SECTIONS.flatMap((section) => section.fields.map((field) => field.keyPath));
+}
+
+export function createKxmConfigEditorContribution(target: KxmConfigEditorTarget): KxmTuiContribution {
+  return {
+    source: KXM_CONFIG_EDITOR_SOURCE,
+    republishAfterWrite: true,
+    listSections: () => listConfigEditorSections(target),
+    handlers: {
+      [KXM_TUI_SET_ACTION]: (input) => {
+        writeConfigEditorValue(target, input.sectionId, input.fieldId, input.value);
+      },
+      [KXM_TUI_CLEAR_ACTION]: (input) => {
+        clearConfigEditorValue(target, input.sectionId, input.fieldId);
+      },
+    },
+    describeError: (error) => (error instanceof Error && error.message ? error.message : "config edit failed"),
+  };
+}
+
+function scopeFile(target: KxmConfigEditorTarget): string {
+  return kxmConfigFileForScope(target.cwd, target.scope, target.userConfigDir);
+}
+
+function scopePhrase(scope: KxmConfigEditorScope): string {
+  return scope === "project" ? "the project file .kxm/config.yaml" : "the user file config.yaml";
+}
+
+function listConfigEditorSections(target: KxmConfigEditorTarget): KxmTuiSectionView[] {
+  const config = loadKxmConfig(target.cwd, {
+    ...(target.userConfigDir === undefined ? {} : { userConfigDir: target.userConfigDir }),
+    layers: target.scope === "user" ? "user" : "all",
+  });
+  const owned = readScopeDocument(scopeFile(target));
+  const where = scopePhrase(target.scope);
+  return SECTIONS.map((section) => {
+    const fields = section.fields.map((field) => publishField(field, config, owned, where));
+    const diagnosis = fields.find((field) => field.statusText)?.statusText;
+    return {
+      source: KXM_CONFIG_EDITOR_SOURCE,
+      id: section.id,
+      title: section.title,
+      order: section.order,
+      detail: `kxm.config.v1 · ${target.scope} scope. Re-read from disk after each write.`,
+      ...(diagnosis === undefined ? {} : { notice: diagnosis, noticeLevel: "error" as const }),
+      fields,
+    };
+  });
+}
+
+function publishField(
+  field: ConfigEditorFieldSpec,
+  config: KxmResolvedConfig,
+  owned: Record<string, unknown> | undefined,
+  where: string,
+): KxmTuiField {
+  const effective = getKxmConfigValue(config, field.keyPath);
+  const stored = ownValue(owned, field.keyPath);
+  const shown = displayScalar(effective);
+  const inherited = !stored.present;
+  const diagnosis = storedDiagnosis(field, stored, effective);
+  const detail = [
+    `Writes ${where}.`,
+    inherited ? "Inherited." : "Set in this scope.",
+    "Clear removes only this override.",
+    field.note ?? "",
+    diagnosis ?? "",
+  ].filter((part) => part.length > 0).join(" ");
+  const choices = field.spec.kind === "enum"
+    ? field.spec.choices.map((choice) => ({ id: choice, label: choice }))
+    : undefined;
+  return {
+    id: field.id,
+    label: field.label,
+    kind: field.spec.kind === "enum" ? "enum" : "text",
+    keyPath: field.keyPath,
+    detail,
+    status: "ready",
+    ...(shown === undefined ? {} : { value: shown }),
+    ...(choices === undefined ? {} : { choices }),
+    ...(diagnosis === undefined ? {} : { statusText: diagnosis }),
+  };
+}
+
+function displayScalar(value: unknown): string | undefined {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return undefined;
+}
+
+function isBooleanEnum(spec: ValueSpec): boolean {
+  return spec.kind === "enum"
+    && spec.choices.length === 2
+    && spec.choices.every((choice) => choice === "true" || choice === "false");
+}
+
+/** A display string such as `"true"` is not a boolean. The stored YAML type has to match the descriptor. */
+function storedTypeMatches(field: ConfigEditorFieldSpec, value: unknown): boolean {
+  if (field.spec.kind === "number") {
+    return typeof value === "number"
+      && Number.isFinite(value)
+      && (!field.spec.integer || Number.isInteger(value));
+  }
+  if (isBooleanEnum(field.spec)) return typeof value === "boolean";
+  return typeof value === "string";
+}
+
+function storedDiagnosis(
+  field: ConfigEditorFieldSpec,
+  stored: { present: boolean; value: unknown },
+  effective: unknown,
+): string | undefined {
+  if (!stored.present) return undefined;
+  if (!storedTypeMatches(field, stored.value)) return "stored type does not match this field";
+  if (field.spec.kind === "enum" && !isBooleanEnum(field.spec) && !field.spec.choices.includes(stored.value as string)) {
+    return "stored value is not a supported scalar";
+  }
+  if (field.spec.kind === "number") {
+    const value = stored.value as number;
+    if (value < field.spec.min || value > field.spec.max) return "stored value is not a supported scalar";
+  }
+  if (stored.value !== effective) return "stored value is not a supported scalar";
+  return undefined;
+}
+
+function writeConfigEditorValue(target: KxmConfigEditorTarget, sectionId: string, fieldId: string, raw: string | undefined): void {
+  const field = requireField(sectionId, fieldId);
+  const value = parseEditorValue(field, raw);
+  setKxmConfigValue(target.cwd, field.keyPath, value, {
+    scope: target.scope,
+    ...(target.userConfigDir === undefined ? {} : { userConfigDir: target.userConfigDir }),
+  });
+}
+
+function clearConfigEditorValue(target: KxmConfigEditorTarget, sectionId: string, fieldId: string): void {
+  const field = requireField(sectionId, fieldId);
+  deleteKxmConfigValue(target.cwd, field.keyPath, {
+    scope: target.scope,
+    ...(target.userConfigDir === undefined ? {} : { userConfigDir: target.userConfigDir }),
+  });
+}
+
+function requireField(sectionId: string, fieldId: string): ConfigEditorFieldSpec {
+  const section = SECTIONS.find((item) => item.id === sectionId);
+  const field = section?.fields.find((item) => item.id === fieldId);
+  if (!field) throw new KxmConfigEditorError("unknown configuration field");
+  return field;
+}
+
+function parseEditorValue(field: ConfigEditorFieldSpec, raw: string | undefined): string | number | boolean {
+  if (raw === undefined) throw new KxmConfigEditorError("a value is required");
+  if (raw.length === 0 || raw.length > 128 || /[\u0000-\u001f\u007f]/u.test(raw)) {
+    throw new KxmConfigEditorError("value must be a single bounded line");
+  }
+  if (field.spec.kind === "enum") {
+    if (!field.spec.choices.includes(raw)) throw new KxmConfigEditorError("value is not a supported choice");
+    if (isBooleanEnum(field.spec)) return raw === "true";
+    return raw;
+  }
+  if (field.spec.kind === "text") {
+    if (!TEXT_VALUE.test(raw)) throw new KxmConfigEditorError("value must be a single bounded line");
+    return raw;
+  }
+  if (!(field.spec.integer ? INTEGER_TEXT : DECIMAL_TEXT).test(raw)) {
+    throw new KxmConfigEditorError("value must be a finite number in range");
+  }
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || (field.spec.integer && !Number.isInteger(parsed)) || parsed < field.spec.min || parsed > field.spec.max) {
+    throw new KxmConfigEditorError("value must be a finite number in range");
+  }
+  return parsed;
+}
+
+function readScopeDocument(file: string): Record<string, unknown> | undefined {
+  if (!existsSync(file)) return undefined;
+  const parsed = parse(readFileSync(file, "utf8")) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new KxmConfigEditorError(`config file ${file} must be a mapping`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function ownValue(root: Record<string, unknown> | undefined, keyPath: string): { present: boolean; value: unknown } {
+  if (!root) return { present: false, value: undefined };
+  let cursor: unknown = root;
+  for (const part of keyPath.split(".")) {
+    if (!cursor || typeof cursor !== "object" || Array.isArray(cursor)) return { present: false, value: undefined };
+    const record = cursor as Record<string, unknown>;
+    if (!Object.prototype.hasOwnProperty.call(record, part)) return { present: false, value: undefined };
+    cursor = record[part];
+  }
+  return { present: true, value: cursor };
+}
+
+const EDITOR_HELP = [
+  "↑↓ move · enter edits · x clears this scope's override · q quits",
+  "Writes are checked, saved, then re-read. A refused edit leaves the file unchanged.",
+] as const;
+
+const FRAME_NOW_MS = Date.UTC(2026, 9, 11);
+
+export async function runKxmConfigEditor(input: {
+  readonly target: KxmConfigEditorTarget;
+  readonly stdout: (text: string) => void;
+  readonly isTty: boolean;
+  readonly dryRun: boolean;
+}): Promise<number> {
+  const registry = createKxmTuiRegistry();
+  try {
+    registry.register(createKxmConfigEditorContribution(input.target));
+    registry.getSections();
+    const failed = registry.getIssues()[0];
+    if (failed) throw new KxmConfigEditorError(failed.message);
+    const interactive = input.isTty && !input.dryRun;
+    return await runKxmTuiPanel({
+      registry,
+      title: "KXM configuration",
+      breadcrumb: `kxm.config.v1 · ${input.target.scope} scope`,
+      helpLines: EDITOR_HELP,
+      stdout: input.stdout,
+      isTty: interactive,
+      ...(interactive ? {} : { theme: createPlainKxmTuiTheme() }),
+      now: () => FRAME_NOW_MS,
+    });
+  } finally {
+    registry.dispose();
+  }
+}
+
+interface ConfigPanelUi {
+  notify?: ((message: string, type?: "error" | "info" | "warning") => void) | undefined;
+  custom?: ((
+    factory: (
+      tui: { requestRender(): void },
+      theme: { fg(token: string, text: string): string; bg(token: string, text: string): string },
+      keybindings: unknown,
+      done: (result: undefined) => void,
+    ) => { render(width: number): string[]; handleInput(data: string): void; invalidate(): void },
+    options?: { overlay?: boolean },
+  ) => Promise<unknown>) | undefined;
+}
+
+/** Mount the project-scope editor on Pi's generic custom panel. Only a TUI session may open it. */
+export async function openKxmProjectConfigPanel(
+  ui: { notify?: (message: string, type?: "error" | "info" | "warning") => void; custom?: unknown },
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  mode?: string,
+): Promise<void> {
+  if (mode !== "tui") {
+    ui.notify?.(
+      "kxm: /kxm config opens only in the Pi TUI. Nothing was written. Run kxm config edit --scope project",
+      "warning",
+    );
+    return;
+  }
+  if (typeof ui.custom !== "function") {
+    ui.notify?.(
+      "kxm: /kxm config needs Pi's custom panel. Open the repository in the Pi TUI, or run kxm config edit --scope project",
+      "warning",
+    );
+    return;
+  }
+  const custom = ui.custom as NonNullable<ConfigPanelUi["custom"]>;
+  const registry = createKxmTuiRegistry();
+  const userConfigDir = userConfigDirForEnv(env);
+  try {
+    registry.register(createKxmConfigEditorContribution({
+      cwd,
+      scope: "project",
+      ...(userConfigDir === undefined ? {} : { userConfigDir }),
+    }));
+    await custom(
+      (tui, theme, _keybindings, done) => createKxmTuiPiPanel({
+        registry,
+        tui,
+        theme,
+        title: "KXM configuration",
+        breadcrumb: "kxm.config.v1 · project scope",
+        helpLines: EDITOR_HELP,
+        done: () => {
+          registry.dispose();
+          done(undefined);
+        },
+      }),
+      { overlay: true },
+    );
+  } finally {
+    registry.dispose();
+  }
+}

package/plugins/kxm/src/config.ts

@@ -440,13 +440,14 @@ function normalizeImprovementConfig(raw: unknown): KxmImprovementConfig {
 
 export function loadKxmConfig(
   repoRoot = process.cwd(),
-  options: { userConfigDir?: string } = {},
+  options: { userConfigDir?: string; layers?: "user" | "all" } = {},
 ): KxmResolvedConfig {
   const userDir = userConfigDirectory(options.userConfigDir);
   const userConfigFile = join(userDir, "config.yaml");
 
   const repoDir = repoConfigDirectory(repoRoot);
   const repoConfigFile = join(repoDir, "config.yaml");
+  const includeProject = options.layers !== "user";
 
   let userRaw: Record<string, unknown> = {};
   let userLoadedPath: string | undefined;
@@ -462,7 +463,7 @@ export function loadKxmConfig(
 
   let repoRaw: Record<string, unknown> = {};
   let repoLoadedPath: string | undefined;
-  if (existsSync(repoConfigFile)) {
+  if (includeProject && existsSync(repoConfigFile)) {
     try {
       const text = readFileSync(repoConfigFile, "utf8");
       repoRaw = (parse(text) as Record<string, unknown>) ?? {};

package/plugins/kxm/src/extension.ts

@@ -39,6 +39,7 @@ import {
   type SessionHubStatus,
   type SessionWorkItem,
 } from "./session-work.ts";
+import { openKxmProjectConfigPanel } from "./config-editor.ts";
 import {
   loadActiveWorkflowProgress,
   renderWorkflowTuiText,
@@ -915,7 +916,7 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
   }
 
   pi.registerCommand("kxm", {
-    description: "Hub session brief, status line, and hub view",
+    description: "KXM session, workflow, hub, and configuration surfaces",
     getArgumentCompletions: (prefix: string) => {
       const items = kxmSlashCompletions(prefix);
       return items.length > 0 ? items : null;
@@ -949,8 +950,14 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
         }
         return;
       }
+      if (command === "config") {
+        const cwd = typeof ctx.cwd === "string" && ctx.cwd.trim().length > 0 ? ctx.cwd : process.cwd();
+        const mode = typeof ctx.mode === "string" ? ctx.mode : undefined;
+        await openKxmProjectConfigPanel(ctx.ui, cwd, process.env, mode);
+        return;
+      }
       if (command === "help") {
-        ctx.ui.notify("kxm: /kxm | /kxm status | /kxm progress | /kxm workflow | /kxm hub | /kxm memory | /kxm help. CLI: kxm session brief, kxm hub view, kxm memory brief", "info");
+        ctx.ui.notify("kxm: /kxm | /kxm status | /kxm progress | /kxm workflow | /kxm hub | /kxm memory | /kxm config | /kxm help. CLI: kxm session brief, kxm hub view, kxm memory brief, kxm config edit --scope project|user", "info");
         return;
       }
       if (command === "memory") {

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.177";
+const VERSION = "0.7.179";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();