@kontextmind/kxm 0.6.0 → 0.7.0

package/plugins/kxm/src/workflow-tui.ts

@@ -0,0 +1,255 @@
+/**
+ * KXM Workflow TUI module for Pi Extension.
+ * Renders active workflow run, stage progress stepper, assigned roles, and model/spend metrics.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { repoConfigDirectory } from "./config.ts";
+import { readRoutingRecords, telemetryPath } from "./telemetry.ts";
+
+export interface WorkflowProgressMetrics {
+  totalSpendUsd?: number | undefined;
+  inputTokens?: number | undefined;
+  outputTokens?: number | undefined;
+  cacheReadTokens?: number | undefined;
+  latencyMs?: number | undefined;
+  harness?: string | undefined;
+  model?: string | undefined;
+  effort?: string | undefined;
+  memoryRevision?: string | undefined;
+  transitions?: number | undefined;
+  maxTransitions?: number | undefined;
+}
+
+export interface WorkflowProgressState {
+  runId?: string | undefined;
+  workflowId: string;
+  status: "idle" | "running" | "waiting" | "passed" | "failed" | "completed" | "cancelled";
+  currentStage?: string | undefined;
+  currentRole?: string | undefined;
+  attempt?: number | undefined;
+  maxAttempts?: number | undefined;
+  stages: Array<{
+    id: string;
+    label?: string | undefined;
+    kind?: "agent" | "gate" | "wait" | "approval" | undefined;
+    status: "pending" | "running" | "passed" | "failed" | "waiting" | "cancelled";
+    role?: string | undefined;
+    attempts?: number | undefined;
+  }>;
+  metrics?: WorkflowProgressMetrics | undefined;
+  updatedAt?: string | undefined;
+}
+
+/**
+ * Load current active or latest workflow progress from SQLite state and telemetry.
+ */
+export function loadActiveWorkflowProgress(
+  repoRoot = process.cwd(),
+  targetRunId?: string,
+): WorkflowProgressState | undefined {
+  const dbPath = join(repoConfigDirectory(repoRoot), "state", "kxm.db");
+  if (!existsSync(dbPath)) return undefined;
+
+  let db: DatabaseSync | undefined;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    let row: { record: string } | undefined;
+    if (targetRunId) {
+      row = db.prepare("SELECT record FROM workflow_runs WHERE id = ?").get(targetRunId) as { record: string } | undefined;
+    } else {
+      row = db.prepare(
+        "SELECT record FROM workflow_runs ORDER BY CASE json_extract(record, '$.status') WHEN 'running' THEN 1 WHEN 'waiting' THEN 2 ELSE 3 END, json_extract(record, '$.updatedAt') DESC LIMIT 1",
+      ).get() as { record: string } | undefined;
+    }
+
+    if (!row) return undefined;
+
+    const raw = JSON.parse(row.record) as Record<string, unknown>;
+    const runId = (raw.id as string) || targetRunId;
+    const workflowId = (raw.definitionId as string) || (raw.workflowId as string) || "workflow";
+    const status = (raw.status as WorkflowProgressState["status"]) || "running";
+    const currentStage = (raw.currentStage as string) || undefined;
+    const updatedAt = (raw.updatedAt as string) || undefined;
+
+    const stages: WorkflowProgressState["stages"] = [];
+    const rawStages = Array.isArray(raw.stages) ? raw.stages : [];
+    for (const s of rawStages) {
+      if (s && typeof s === "object") {
+        stages.push({
+          id: String((s as Record<string, unknown>).id || ""),
+          label: (s as Record<string, unknown>).label as string | undefined,
+          kind: (s as Record<string, unknown>).kind as any,
+          status: ((s as Record<string, unknown>).status as any) || "pending",
+          role: (s as Record<string, unknown>).role as string | undefined,
+          attempts: typeof (s as Record<string, unknown>).attempts === "number" ? ((s as Record<string, unknown>).attempts as number) : undefined,
+        });
+      }
+    }
+
+    let metrics: WorkflowProgressMetrics | undefined;
+    try {
+      const logsDir = join(repoConfigDirectory(repoRoot), "logs");
+      const telemFile = telemetryPath(logsDir);
+      if (existsSync(telemFile)) {
+        const records = readRoutingRecords(telemFile);
+        const routingRunId = (routing: (typeof records)[number]["routing"]): string | undefined =>
+          "runId" in routing ? routing.runId : routing.workflowRunId;
+        let matching = records.filter((r) => routingRunId(r.routing) === runId);
+        if (matching.length === 0) {
+          const rawLines = readFileSync(telemFile, "utf8").split(/\r?\n/);
+          for (const line of rawLines) {
+            if (!line.trim()) continue;
+            try {
+              const p = JSON.parse(line) as Record<string, unknown>;
+              const rt = (p.routing || p) as any;
+              if (rt && (routingRunId(rt) === runId || p.runId === runId)) {
+                matching.push({ recordedAt: (p.timestamp as string) || new Date().toISOString(), routing: rt });
+              }
+            } catch {
+              // ignore
+            }
+          }
+        }
+        if (matching.length > 0) {
+          const latest = matching[matching.length - 1]!.routing;
+          let totalSpend = 0;
+          let totalIn = 0;
+          let totalOut = 0;
+          let totalCache = 0;
+          let totalLatency = 0;
+          for (const m of matching) {
+            const rt = m.routing;
+            if (typeof rt.costUsd === "number") totalSpend += rt.costUsd;
+            if ("tokensIn" in rt && typeof rt.tokensIn === "number") totalIn += rt.tokensIn;
+            else if ("tokens" in rt && rt.tokens && typeof (rt.tokens as { input?: unknown }).input === "number") totalIn += (rt.tokens as { input: number }).input;
+            if ("tokensOut" in rt && typeof rt.tokensOut === "number") totalOut += rt.tokensOut;
+            else if ("tokens" in rt && rt.tokens && typeof (rt.tokens as { output?: unknown }).output === "number") totalOut += (rt.tokens as { output: number }).output;
+            if ("cacheReadTokens" in rt && typeof rt.cacheReadTokens === "number") totalCache += rt.cacheReadTokens;
+            else if ("tokens" in rt && rt.tokens && typeof (rt.tokens as { cacheRead?: unknown }).cacheRead === "number") totalCache += (rt.tokens as { cacheRead: number }).cacheRead;
+            if ("latencyMs" in rt && typeof rt.latencyMs === "number") totalLatency += rt.latencyMs;
+          }
+          const latestRecord = latest as unknown as Record<string, unknown>;
+          const latestMetadata = latestRecord.providerMetadata && typeof latestRecord.providerMetadata === "object"
+            ? latestRecord.providerMetadata as Record<string, unknown>
+            : undefined;
+          metrics = {
+            totalSpendUsd: totalSpend,
+            inputTokens: totalIn,
+            outputTokens: totalOut,
+            cacheReadTokens: totalCache,
+            latencyMs: totalLatency,
+            harness: typeof latestRecord.harness === "string" ? latestRecord.harness : (typeof latestMetadata?.harness === "string" ? latestMetadata.harness : undefined),
+            model: typeof latestRecord.effectiveModel === "string" ? latestRecord.effectiveModel : (typeof latestRecord.model === "string" ? latestRecord.model : (typeof latestRecord.requestedModel === "string" ? latestRecord.requestedModel : undefined)),
+            effort: typeof latestRecord.thinking === "string" ? latestRecord.thinking : (typeof latestRecord.reasoningEffort === "string" ? latestRecord.reasoningEffort : undefined),
+          };
+        }
+      }
+    } catch {
+      // Telemetry optional
+    }
+
+    const activeStageObj = stages.find((s) => s.id === currentStage);
+    const currentRole = activeStageObj?.role || (raw.targetAgentName as string) || undefined;
+    const attempt = activeStageObj?.attempts || 1;
+
+    return {
+      runId,
+      workflowId,
+      status,
+      currentStage,
+      currentRole,
+      attempt,
+      stages,
+      metrics,
+      updatedAt,
+    };
+  } catch {
+    return undefined;
+  } finally {
+    try {
+      db?.close();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+/**
+ * Format stage progress indicator into a compact horizontal visual stepper.
+ * e.g.: [✔ implement] ──> [▶ review-arch] ──> [⧗ review-cli] ──> [○ verify]
+ */
+export function formatStageStepper(stages: WorkflowProgressState["stages"], currentStage?: string): string {
+  if (stages.length === 0) {
+    return currentStage ? `[▶ ${currentStage}]` : "[idle]";
+  }
+
+  const parts = stages.map((s) => {
+    let icon = "○"; // pending
+    if (s.status === "passed") icon = "✔";
+    else if (s.id === currentStage || s.status === "running") icon = "▶";
+    else if (s.status === "waiting") icon = "⧗";
+    else if (s.status === "failed") icon = "✖";
+    else if (s.status === "cancelled") icon = "⊘";
+    return `[${icon} ${s.id}]`;
+  });
+
+  return parts.join(" ──> ");
+}
+
+function formatTokenK(tokens?: number): string {
+  if (tokens === undefined || tokens === null) return "0";
+  if (tokens >= 1000) {
+    return `${(tokens / 1000).toFixed(1)}k`;
+  }
+  return String(tokens);
+}
+
+/**
+ * Render Pi Extension live widget lines (for `ctx.ui.setWidget("kxm-workflow", lines)`).
+ */
+export function renderWorkflowWidgetLines(state?: WorkflowProgressState): string[] {
+  if (!state || !state.runId) {
+    return [
+      "┌─ KXM Workflow ──────────────────────────────────────────────────────────────┐",
+      "│ No active workflow running. Use 'kxm workflow start <id>'                   │",
+      "└─────────────────────────────────────────────────────────────────────────────┘",
+    ];
+  }
+
+  const shortRun = state.runId ? state.runId.slice(0, 16) : "-";
+  const header = `┌─ KXM Workflow: ${state.workflowId} (${shortRun}) ─`;
+  const topBorder = header + "─".repeat(Math.max(2, 79 - header.length)) + "┐";
+
+  const stepper = formatStageStepper(state.stages, state.currentStage);
+  const statusStr = state.status.toUpperCase();
+  const attemptStr = state.attempt ? ` (Attempt ${state.attempt})` : "";
+  const roleStr = state.currentRole ? ` · Role: ${state.currentRole}` : "";
+
+  const lines: string[] = [topBorder];
+  lines.push(`│ Stage: ${stepper}`);
+  lines.push(`│ Status: ${statusStr}${attemptStr}${roleStr}`);
+
+  if (state.metrics) {
+    const costStr = state.metrics.totalSpendUsd !== undefined ? `$${state.metrics.totalSpendUsd.toFixed(2)}` : "unmetered";
+    const routeStr = state.metrics.model ? `${state.metrics.harness ?? "pi"}:${state.metrics.model}` : "harness";
+    const effortStr = state.metrics.effort ? ` (${state.metrics.effort})` : "";
+    const inTokens = formatTokenK(state.metrics.inputTokens);
+    const outTokens = formatTokenK(state.metrics.outputTokens);
+    const cacheTokens = formatTokenK(state.metrics.cacheReadTokens);
+    lines.push(`│ Model: ${routeStr}${effortStr} · Spend: ${costStr}`);
+    lines.push(`│ Tokens: In: ${inTokens} | Out: ${outTokens} | Cache: ${cacheTokens}`);
+  }
+
+  lines.push("└" + "─".repeat(78) + "┘");
+  return lines;
+}
+
+/**
+ * Render detailed full-width TUI banner / notification string.
+ */
+export function renderWorkflowTuiText(state?: WorkflowProgressState): string {
+  return renderWorkflowWidgetLines(state).join("\n");
+}

package/schemas/policy-draft/README.md

@@ -0,0 +1,17 @@
+# Policy-draft schemas (non-authoritative)
+
+`kxm.model.v2` and `kxm.role.v2` here are **passive scaffolding**. They are not
+operator settings, live registry identities, or admission.
+
+- Live project models remain `kxm.model.v1` under `schemas/vnext/`.
+- Live CLI roles remain `kxm.role.v1`.
+- Runner admission remains `.kxm/roster.json` via the trusted control Git loader.
+- This directory is not discovered as a vNext project resource.
+
+Pure validation lives in `plugins/kxm/src/policy-draft.mjs`
+(`validatePolicyDraft`). Callers must supply draft documents, evidence bytes,
+and code-owned ceilings explicitly. The function does not read files, Git,
+credentials, or cwd, and it does not dispatch or admit a route.
+
+Roster `route` lists are configured preference order, not a measured ranking.
+`status: candidate` is stored as candidate data and is never treated as admitted.

package/schemas/policy-draft/model.v2.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/policy-draft/model.v2.schema.json",
+  "title": "KXM policy-draft model route",
+  "description": "Passive kxm.model.v2 scaffolding. Not live registry selection, admission, or operator settings.",
+  "type": "object",
+  "required": ["schema", "harness", "model", "vendor", "status", "permissions"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "kxm.model.v2" },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "harness": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "model": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "vendor": { "type": "string", "minLength": 1, "maxLength": 64 },
+    "status": { "enum": ["admitted", "candidate", "retired"] },
+    "permissions": {
+      "type": "array",
+      "items": { "enum": ["edit", "read-only"] },
+      "minItems": 1,
+      "maxItems": 2,
+      "uniqueItems": true
+    },
+    "origin": {
+      "type": "object",
+      "required": ["source", "sha256"],
+      "additionalProperties": false,
+      "properties": {
+        "source": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "thinking": { "type": "string", "minLength": 1, "maxLength": 64 },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
+        "minLength": 1,
+        "maxLength": 64
+      },
+      "uniqueItems": true,
+      "maxItems": 32
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
+        "minLength": 1,
+        "maxLength": 64
+      },
+      "uniqueItems": true,
+      "maxItems": 32
+    },
+    "priority": { "type": "integer", "minimum": -10000, "maximum": 10000 },
+    "fallbacks": {
+      "type": "array",
+      "maxItems": 8,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["profile"],
+            "additionalProperties": false,
+            "properties": {
+              "profile": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
+                "minLength": 1,
+                "maxLength": 64
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["tag"],
+            "additionalProperties": false,
+            "properties": {
+              "tag": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
+                "minLength": 1,
+                "maxLength": 64
+              },
+              "capabilities": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
+                  "minLength": 1,
+                  "maxLength": 64
+                },
+                "uniqueItems": true,
+                "maxItems": 32
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["provider", "model"],
+            "additionalProperties": false,
+            "properties": {
+              "provider": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
+                "minLength": 1,
+                "maxLength": 64
+              },
+              "model": { "type": "string", "minLength": 1, "maxLength": 200 }
+            }
+          }
+        ]
+      }
+    },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "contextTokens": { "type": "integer", "minimum": 1 },
+        "outputTokens": { "type": "integer", "minimum": 1 },
+        "timeoutMs": { "type": "integer", "minimum": 0, "maximum": 31536000000 }
+      }
+    }
+  },
+  "if": {
+    "properties": { "harness": { "const": "pi" } },
+    "required": ["harness"]
+  },
+  "then": { "required": ["origin"] }
+}

package/schemas/policy-draft/role.v2.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/policy-draft/role.v2.schema.json",
+  "title": "KXM policy-draft role",
+  "description": "Passive kxm.role.v2 scaffolding. Specialty identity is separate from purpose. Roster order is configured preference, not a measured ranking. Not live admission or operator settings.",
+  "type": "object",
+  "required": ["schema", "purpose", "permission", "description", "roster"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "kxm.role.v2" },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "purpose": {
+      "enum": ["writer", "planner", "reviewer-arch", "reviewer-cli", "experiment"]
+    },
+    "permission": { "enum": ["edit", "read-only"] },
+    "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "roster": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "required": ["route"],
+        "additionalProperties": false,
+        "properties": {
+          "route": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "effort": {
+            "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"]
+          },
+          "mode": { "enum": ["headless", "interactive", "either"] }
+        }
+      }
+    },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "maxLength": 128 },
+      "maxItems": 64
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "preset": { "type": "string" },
+        "allow": { "type": "array", "items": { "type": "string" } },
+        "deny": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "produces": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["template"],
+        "additionalProperties": false,
+        "properties": {
+          "template": { "type": "string" },
+          "schema": { "type": "string" }
+        }
+      }
+    },
+    "consumes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["template"],
+        "additionalProperties": false,
+        "properties": {
+          "template": { "type": "string" },
+          "schema": { "type": "string" }
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "vendorIndependenceRequired": { "type": "boolean" },
+        "maxTransitions": { "type": "integer", "minimum": 1 },
+        "requiresGateVerification": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/vnext/role.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/vnext/role.schema.json",
+  "title": "KXM role definition",
+  "description": "The filename determines the role identity unless explicitly declared.",
+  "type": "object",
+  "required": ["schema", "description"],
+  "properties": {
+    "schema": { "const": "kxm.role.v1" },
+    "id": { "$ref": "common.schema.json#/$defs/identifier" },
+    "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "maxLength": 128 },
+      "maxItems": 64
+    },
+    "tools": {
+      "type": "object",
+      "properties": {
+        "preset": { "type": "string" },
+        "allow": { "type": "array", "items": { "type": "string" } },
+        "deny": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "produces": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["template"],
+        "properties": {
+          "template": { "type": "string" },
+          "schema": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "consumes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["template"],
+        "properties": {
+          "template": { "type": "string" },
+          "schema": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "roster": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["harness", "model"],
+        "properties": {
+          "harness": { "$ref": "common.schema.json#/$defs/identifier" },
+          "model": { "$ref": "common.schema.json#/$defs/modelSelector" },
+          "provider": { "type": "string" },
+          "effort": { "enum": ["low", "medium", "high", "xhigh"] },
+          "mode": { "enum": ["headless", "interactive", "either"] }
+        },
+        "additionalProperties": false
+      }
+    },
+    "policy": {
+      "type": "object",
+      "properties": {
+        "vendorIndependenceRequired": { "type": "boolean" },
+        "maxTransitions": { "type": "integer", "minimum": 1 },
+        "requiresGateVerification": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/vnext/run-event.schema.json

@@ -323,6 +323,7 @@
       "properties": {
         "workflowId": { "$ref": "common.schema.json#/$defs/identifier" },
         "displayTitle": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "prompt": { "type": "string", "maxLength": 64000 },
         "promptHash": { "$ref": "common.schema.json#/$defs/sha256" },
         "runPlanHash": { "$ref": "common.schema.json#/$defs/sha256" },
         "capabilityHash": { "$ref": "common.schema.json#/$defs/sha256" },

package/scripts/assignment-run.d.mts

@@ -33,7 +33,7 @@ export function resolveRequiredCritics(policy: unknown): Readonly<Record<string,
   vendor: string;
   route_id?: string;
 }>>>;
-export function getRosterPolicy(deps?: Record<string, unknown>): unknown;
+export function getRosterPolicy(deps?: Record<string, unknown>): import("./roster-policy.mjs").RosterPolicy;
 export const ASSIGNMENT_KINDS: readonly string[];
 export const KIND_ROLES: Readonly<Record<string, string>>;
 export const REVIEW_KINDS: readonly string[];