@kontextmind/kxm 0.6.0 → 0.7.10

package/plugins/kxm/src/vnext-runtime-supervisor.ts

@@ -5,7 +5,6 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadVnextProject, VnextConfigError, type VnextConfigOptions } from "./vnext-config.ts";
-
 const repoRoot = resolve(fileURLToPath(new URL("../../../", import.meta.url)));
 import {
   VnextRuntimeRegistry,
@@ -23,7 +22,9 @@ import {
   rebuildVnextRunProjection,
   type VnextRuntimeContext,
 } from "./vnext-runtime.ts";
-import { recoverVnextRun } from "./vnext-engine.ts";
+import { createVnextOneShotProducer } from "./vnext-oneshot-producer.ts";
+import { isProducerAdmitted } from "./producers.ts";
+import { VnextRunScheduler, createVnextSimulatedProducer, driveVnextRun, pinVnextCompiledPlan, recoverVnextRun, startVnextRun } from "./vnext-engine.ts";
 
 /* ------------------------------------------------------------------ *
  * Token management
@@ -321,6 +322,7 @@ async function startVnextRuntimeSupervisorInner(
   const runtimeId = `rtm_${createHash("sha256").update(`${paths.stateRoot}\0${process.pid}\0${now()}\0${randomBytes(16).toString("hex")}`, "utf8").digest("hex").slice(0, 24)}`;
   const requestedPort = requestedPortOption ?? 0;
   let activeRuntimeId = runtimeId;
+  const activeDrives = new Map<string, Promise<unknown>>();
 
   const contexts = new Map<string, VnextRuntimeContext>();
   const contextFor = (projectRoot: string): VnextRuntimeContext => {
@@ -394,7 +396,7 @@ async function startVnextRuntimeSupervisorInner(
           return;
         }
 
-        const runMatch = /^\/v1\/runs\/([A-Za-z0-9_-]+)(?:\/(events|cancel|signal|wait))?$/.exec(url.pathname);
+        const runMatch = /^\/v1\/runs\/([A-Za-z0-9_-]+)(?:\/(events|cancel|signal|wait|drive))?$/.exec(url.pathname);
         if (runMatch) {
           const runId = runMatch[1] as string;
           const sub = runMatch[2];
@@ -404,11 +406,122 @@ async function startVnextRuntimeSupervisorInner(
             return;
           }
           const context = contextFor(projectRoot);
+          const bundle = loadVnextProject(projectRoot, {});
           if (request.method === "GET" && !sub) {
             const projected = rebuildVnextRunProjection(context, runId);
             sendJson(response, 200, { ok: true, run: projected });
             return;
           }
+          if (request.method === "POST" && sub === "drive") {
+            const body = await readJsonBody(request);
+            if (body.mode !== "simulated" && body.mode !== "live") {
+              sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: "drive mode must be simulated or live" });
+              return;
+            }
+            const run = context.eventStore.run(runId);
+            if (!run) throw runtimeError("run_unknown", runId, "run not found");
+            if (activeDrives.has(runId)) {
+              sendJson(response, 409, { ok: false, error: "run_busy", message: `run ${runId} is already executing` });
+              return;
+            }
+            if (run.status === "completed" || run.status === "failed" || run.status === "cancelled" || run.status === "cancelling") {
+              sendJson(response, 409, { ok: false, error: "run_busy", message: `run ${runId} is already ${run.status}` });
+              return;
+            }
+            let releaseActive = () => {};
+            const activePromise = new Promise<void>((resolve) => { releaseActive = resolve; });
+            activeDrives.set(runId, activePromise);
+            const cleanupActive = () => {
+              activeDrives.delete(runId);
+              releaseActive();
+            };
+
+            if (run.status === "created") {
+              pinVnextCompiledPlan(context, bundle, runId);
+              const plan = startVnextRun(context, runId, { allowLimits: true });
+              if (plan.handoff) {
+                cleanupActive();
+                sendJson(response, 409, { ok: false, error: "run_handoff_required", handoff: plan.handoff });
+                return;
+              }
+            }
+            const producer = body.mode === "live"
+              ? createVnextOneShotProducer({
+                  projectRoot,
+                  defaultHarness: String(bundle.project.value.defaultHarness ?? "pi"),
+                  resolveHarness: (agentId) => {
+                    const agent = bundle.agents.get(agentId);
+                    return typeof agent?.value.harness === "string" ? agent.value.harness : undefined;
+                  },
+                  resolveModel: (agentId) => {
+                    const agent = bundle.agents.get(agentId);
+                    const model = agent?.value.model;
+                    if (!model || typeof model !== "object" || Array.isArray(model)) return undefined;
+                    const value = model as Record<string, unknown>;
+                    const provider = typeof value.provider === "string" ? value.provider : undefined;
+                    const modelName = typeof value.model === "string" ? value.model : undefined;
+                    if (!provider || !modelName || !isProducerAdmitted(projectRoot, `${provider}/${modelName}`)) {
+                      throw new Error("producer_route_not_admitted");
+                    }
+                    return { provider, model: modelName };
+                  },
+                })
+              : (() => {
+                  const delayMs = typeof body.delayMs === "number" && body.delayMs > 0 ? body.delayMs : 0;
+                  return createVnextSimulatedProducer(async () => {
+                    if (delayMs > 0) {
+                      await new Promise((r) => setTimeout(r, delayMs));
+                    }
+                    return { outcome: "passed" };
+                  });
+                })();
+
+            let drivePromise: Promise<unknown> | undefined;
+            let earlyError: unknown;
+            try {
+              const scheduler = VnextRunScheduler.for(context, bundle);
+              drivePromise = scheduler.enqueue(runId, producer, { allowLimits: true, liveMode: body.mode === "live" });
+              drivePromise.catch((err) => { earlyError = err; });
+            } catch (err) {
+              earlyError = err;
+            }
+
+            // Yield microtask to catch synchronous duplicate queue check (e.g. run_busy)
+            await Promise.resolve();
+
+            if (earlyError) {
+              cleanupActive();
+              const errStr = String(earlyError);
+              if (errStr.includes("run_busy") || errStr.includes("scheduler_policy_conflict")) {
+                if ("close" in producer && typeof producer.close === "function") {
+                  try { await producer.close(); } catch { /* ignore */ }
+                }
+                sendJson(response, 409, { ok: false, error: "run_busy", message: `run ${runId} is already admitted or queued` });
+                return;
+              }
+              throw earlyError;
+            }
+
+            void drivePromise!.finally(async () => {
+              cleanupActive();
+              if ("close" in producer && typeof producer.close === "function") {
+                try { await producer.close(); } catch { /* ignore */ }
+              }
+            }).catch(() => {
+              // Derived finally() re-rejects when the admitted drive or cleanup
+              // throws; void does not consume that. Keep the request 202.
+            });
+
+            sendJson(response, 202, {
+              ok: true,
+              status: "accepted",
+              runId,
+              poll: `/v1/runs/${runId}`,
+              mode: body.mode,
+            });
+            return;
+          }
+
           if (request.method === "GET" && sub === "events") {
             const after = Number.parseInt(url.searchParams.get("after") ?? "0", 10);
             const events = context.eventStore.events(runId, Number.isFinite(after) && after >= 0 ? after : 0, 500);
@@ -429,9 +542,10 @@ async function startVnextRuntimeSupervisorInner(
             if (!run) throw runtimeError("run_unknown", runId, "run not found");
             const state = foldStoredVnextRun(context, run);
             let unblocked = false;
-            if (state.status === "blocked_uncertain" || state.currentStep?.effectState === "blocked_uncertain") {
+            if (state.status === "blocked_uncertain" || state.status === "cancelling" || state.currentStep?.effectState === "blocked_uncertain") {
+              const action = body.action === "cancel" || body.action === "fail" || body.action === "retry" || body.action === "unblock" ? body.action : "unblock";
               const rec = recoverVnextRun(context, runId, {
-                action: "unblock",
+                action,
                 reason: typeof body.summary === "string" ? body.summary : `signal_${body.signalKey ?? "callback"}`,
               });
               unblocked = rec.unblocked;
@@ -543,6 +657,9 @@ async function startVnextRuntimeSupervisorInner(
     stopping = true;
     clearInterval(heartbeat);
     try { registry.markStopping(process.pid, now()); } catch { /* best effort */ }
+    if (activeDrives.size > 0) {
+      await Promise.allSettled([...activeDrives.values()]);
+    }
     for (const context of contexts.values()) closeVnextRuntimeContext(context);
     contexts.clear();
     const closed = new Promise<void>((resolveStop) => server.close(() => resolveStop()));

package/plugins/kxm/src/vnext-runtime.ts

@@ -159,6 +159,19 @@ export function computeVnextMemoryRevision(
   return `ctxrev_${hash.digest("hex")}`;
 }
 
+export function checkMemoryRevisionDrift(
+  pinnedRevision: string,
+  bundle: VnextProjectBundle,
+  options?: VnextMemoryRevisionOptions,
+): { drifted: boolean; currentRevision: string; pinnedRevision: string } {
+  const currentRevision = computeVnextMemoryRevision(bundle, options);
+  return {
+    drifted: currentRevision !== pinnedRevision,
+    currentRevision,
+    pinnedRevision,
+  };
+}
+
 export function vnextPolicyRevisions(
   bundle: VnextProjectBundle,
   options?: VnextMemoryRevisionOptions,
@@ -423,6 +436,7 @@ export function acceptVnextRun(
       result: { runId, homeRuntimeId: context.homeRuntimeId, status: "created" },
       recordedAt: now,
     });
+    context.eventStore.putRunPrompt(runId, request.prompt);
     return { accepted: true, idempotent: false, run, event };
   });
 }

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

@@ -0,0 +1,392 @@
+/**
+ * KXM Workflow Management Subsystem.
+ * Supports add, remove, modify, list, and inspection of workflow YAML definitions.
+ * Handles global (~/.config/kxm/workflows/) and local (.kxm/workflows/) scoping.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parse, stringify } from "yaml";
+import { repoConfigDirectory, userConfigDirectory } from "./config.ts";
+
+export interface WorkflowDefSummary {
+  id: string;
+  description: string;
+  scope: "global" | "local" | "overridden";
+  filePath: string;
+  stepCount: number;
+  roles: string[];
+}
+
+export const WORKFLOW_TEMPLATES: Record<string, Record<string, unknown>> = {
+  "implement-and-verify": {
+    schema: "kxm.workflow.v1",
+    description: "Standard implement and verify workflow",
+    coordinator: "coordinator",
+    limits: {
+      maxTransitions: 8,
+    },
+    steps: [
+      {
+        id: "implement",
+        kind: "agent",
+        role: "writer",
+        maxAttempts: 2,
+        on: {
+          passed: "verify",
+          failed: {
+            target: "$terminal",
+            terminalStatus: "failed",
+          },
+        },
+      },
+      {
+        id: "verify",
+        kind: "gate",
+        gate: "verify-gate",
+        expect: "pass",
+        maxAttempts: 1,
+        on: {
+          passed: {
+            target: "$terminal",
+            terminalStatus: "completed",
+          },
+          failed: {
+            target: "implement",
+            maxTransitions: 2,
+          },
+        },
+      },
+    ],
+  },
+  "dual-critic-review": {
+    schema: "kxm.workflow.v1",
+    description: "Dual-critic review workflow with independent Fable architecture and Sol CLI critics",
+    coordinator: "coordinator",
+    limits: {
+      maxTransitions: 12,
+    },
+    steps: [
+      {
+        id: "implement",
+        kind: "agent",
+        role: "writer",
+        maxAttempts: 2,
+        on: {
+          passed: "review-arch",
+          failed: {
+            target: "$terminal",
+            terminalStatus: "failed",
+          },
+        },
+      },
+      {
+        id: "review-arch",
+        kind: "agent",
+        role: "critic-arch",
+        maxAttempts: 2,
+        on: {
+          passed: "review-cli",
+          failed: {
+            target: "implement",
+            maxTransitions: 2,
+          },
+        },
+      },
+      {
+        id: "review-cli",
+        kind: "agent",
+        role: "critic-cli",
+        maxAttempts: 2,
+        on: {
+          passed: "verify",
+          failed: {
+            target: "implement",
+            maxTransitions: 2,
+          },
+        },
+      },
+      {
+        id: "verify",
+        kind: "gate",
+        gate: "verify-gate",
+        expect: "pass",
+        maxAttempts: 1,
+        on: {
+          passed: {
+            target: "$terminal",
+            terminalStatus: "completed",
+          },
+          failed: {
+            target: "implement",
+            maxTransitions: 2,
+          },
+        },
+      },
+    ],
+  },
+  "spec-and-plan": {
+    schema: "kxm.workflow.v1",
+    description: "Specification and architecture breakdown planning workflow",
+    coordinator: "coordinator",
+    limits: {
+      maxTransitions: 6,
+    },
+    steps: [
+      {
+        id: "plan",
+        kind: "agent",
+        role: "planner",
+        maxAttempts: 2,
+        on: {
+          passed: "review-arch",
+          failed: {
+            target: "$terminal",
+            terminalStatus: "failed",
+          },
+        },
+      },
+      {
+        id: "review-arch",
+        kind: "agent",
+        role: "critic-arch",
+        maxAttempts: 2,
+        on: {
+          passed: {
+            target: "$terminal",
+            terminalStatus: "completed",
+          },
+          failed: {
+            target: "plan",
+            maxTransitions: 2,
+          },
+        },
+      },
+    ],
+  },
+};
+
+export const DEFAULT_WORKFLOW_TEMPLATE = WORKFLOW_TEMPLATES["implement-and-verify"]!;
+
+export function workflowsDirectory(
+  scope: "global" | "local",
+  repoRoot = process.cwd(),
+  userConfigDir?: string,
+): string {
+  if (scope === "global") {
+    return join(userConfigDirectory(userConfigDir), "workflows");
+  }
+  return join(repoConfigDirectory(repoRoot), "workflows");
+}
+
+export function ensureWorkflowsDirectory(
+  scope: "global" | "local",
+  repoRoot = process.cwd(),
+  userConfigDir?: string,
+): string {
+  const dir = workflowsDirectory(scope, repoRoot, userConfigDir);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+export function parseWorkflowFile(filePath: string): Record<string, unknown> | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    const parsed = parse(raw) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== "object") return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+export function listWorkflowDefinitions(options: {
+  scope?: "all" | "global" | "local" | undefined;
+  repoRoot?: string | undefined;
+  userConfigDir?: string | undefined;
+} = {}): WorkflowDefSummary[] {
+  const scopeFilter = options.scope ?? "all";
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const globalDir = workflowsDirectory("global", repoRoot, options.userConfigDir);
+  const localDir = workflowsDirectory("local", repoRoot, options.userConfigDir);
+
+  const localDefs = new Map<string, { def: Record<string, unknown>; filePath: string }>();
+  if (scopeFilter !== "global" && existsSync(localDir)) {
+    for (const entry of readdirSync(localDir)) {
+      if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+        const filePath = join(localDir, entry);
+        const def = parseWorkflowFile(filePath);
+        if (def) {
+          const id = (def.id as string) || entry.replace(/\.ya?ml$/i, "");
+          localDefs.set(id, { def, filePath });
+        }
+      }
+    }
+  }
+
+  const globalDefs = new Map<string, { def: Record<string, unknown>; filePath: string }>();
+  if (scopeFilter !== "local" && existsSync(globalDir)) {
+    for (const entry of readdirSync(globalDir)) {
+      if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+        const filePath = join(globalDir, entry);
+        const def = parseWorkflowFile(filePath);
+        if (def) {
+          const id = (def.id as string) || entry.replace(/\.ya?ml$/i, "");
+          globalDefs.set(id, { def, filePath });
+        }
+      }
+    }
+  }
+
+  const extractRoles = (def: Record<string, unknown>): string[] => {
+    const roles: string[] = [];
+    const steps = Array.isArray(def.steps) ? def.steps : [];
+    for (const step of steps) {
+      if (step && typeof step === "object") {
+        const role = (step as Record<string, unknown>).role || (step as Record<string, unknown>).agent;
+        if (typeof role === "string" && !roles.includes(role)) {
+          roles.push(role);
+        }
+      }
+    }
+    return roles;
+  };
+
+  const result: WorkflowDefSummary[] = [];
+
+  for (const [id, { def, filePath }] of localDefs) {
+    const isOverridden = globalDefs.has(id);
+    const steps = Array.isArray(def.steps) ? def.steps : [];
+    result.push({
+      id,
+      description: typeof def.description === "string" ? def.description : "",
+      scope: isOverridden ? "overridden" : "local",
+      filePath,
+      stepCount: steps.length,
+      roles: extractRoles(def),
+    });
+  }
+
+  for (const [id, { def, filePath }] of globalDefs) {
+    if (scopeFilter === "global" || !localDefs.has(id)) {
+      const steps = Array.isArray(def.steps) ? def.steps : [];
+      result.push({
+        id,
+        description: typeof def.description === "string" ? def.description : "",
+        scope: "global",
+        filePath,
+        stepCount: steps.length,
+        roles: extractRoles(def),
+      });
+    }
+  }
+
+  result.sort((a, b) => a.id.localeCompare(b.id));
+  return result;
+}
+
+export function getWorkflowDefinition(
+  workflowId: string,
+  options: {
+    scope?: "all" | "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+  } = {},
+): { workflow: Record<string, unknown>; scope: "global" | "local"; filePath: string } | undefined {
+  const scope = options.scope ?? "all";
+  const repoRoot = options.repoRoot ?? process.cwd();
+
+  // 1. Check local first
+  if (scope !== "global") {
+    const localDir = workflowsDirectory("local", repoRoot, options.userConfigDir);
+    const localFile = join(localDir, `${workflowId}.yaml`);
+    const parsed = parseWorkflowFile(localFile);
+    if (parsed) return { workflow: parsed, scope: "local", filePath: localFile };
+  }
+
+  // 2. Check global
+  if (scope !== "local") {
+    const globalDir = workflowsDirectory("global", repoRoot, options.userConfigDir);
+    const globalFile = join(globalDir, `${workflowId}.yaml`);
+    const parsed = parseWorkflowFile(globalFile);
+    if (parsed) return { workflow: parsed, scope: "global", filePath: globalFile };
+  }
+
+  return undefined;
+}
+
+export function addWorkflowDefinition(
+  workflowId: string,
+  content: Record<string, unknown> | string = DEFAULT_WORKFLOW_TEMPLATE,
+  options: {
+    scope?: "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+    overwrite?: boolean | undefined;
+  } = {},
+): { id: string; filePath: string; scope: "global" | "local" } {
+  const scope = options.scope ?? "local";
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const dir = ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+  const filePath = join(dir, `${workflowId}.yaml`);
+
+  if (existsSync(filePath) && !options.overwrite) {
+    throw new Error(`workflow_already_exists: workflow '${workflowId}' already exists at ${filePath}`);
+  }
+
+  const payload = typeof content === "string" ? content : stringify(content);
+  writeFileSync(filePath, payload, "utf8");
+  return { id: workflowId, filePath, scope };
+}
+
+export function removeWorkflowDefinition(
+  workflowId: string,
+  options: {
+    scope?: "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+  } = {},
+): { id: string; removed: boolean; filePath: string; scope: "global" | "local" } {
+  const scope = options.scope ?? "local";
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const dir = workflowsDirectory(scope, repoRoot, options.userConfigDir);
+  const filePath = join(dir, `${workflowId}.yaml`);
+
+  if (!existsSync(filePath)) {
+    throw new Error(`workflow_not_found: workflow '${workflowId}' not found in ${scope} directory (${filePath})`);
+  }
+
+  rmSync(filePath);
+  return { id: workflowId, removed: true, filePath, scope };
+}
+
+export function modifyWorkflowDefinition(
+  workflowId: string,
+  updates: Record<string, unknown>,
+  options: {
+    scope?: "global" | "local" | undefined;
+    repoRoot?: string | undefined;
+    userConfigDir?: string | undefined;
+  } = {},
+): { id: string; workflow: Record<string, unknown>; filePath: string; scope: "global" | "local" } {
+  const target = getWorkflowDefinition(workflowId, { scope: options.scope, repoRoot: options.repoRoot, userConfigDir: options.userConfigDir });
+  if (!target) {
+    throw new Error(`workflow_not_found: workflow '${workflowId}' does not exist`);
+  }
+
+  const updated: Record<string, unknown> = {
+    ...target.workflow,
+    ...updates,
+  };
+
+  const scope = options.scope ?? target.scope;
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const dir = ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+  const filePath = join(dir, `${workflowId}.yaml`);
+
+  writeFileSync(filePath, stringify(updated), "utf8");
+  return { id: workflowId, workflow: updated, filePath, scope };
+}