@kontextmind/kxm 0.7.128 → 0.7.131

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

@@ -6,13 +6,13 @@ import { dirname, isAbsolute, join } from "node:path";
 import { findKxmRepoRoot } from "./repo-root.ts";
 import { loadKxmProject, KxmConfigError, type KxmConfigOptions } from "./project-config.ts";
 import {
+  KxmRunEventStore,
   KxmRuntimeRegistry,
   projectRuntimeKey,
   readKxmSupervisorRecord,
   runtimeError,
   verifyKxmDriveReceipt,
   kxmRuntimePaths,
-  type KxmRunEventStore,
   type KxmRuntimePaths,
   type KxmSupervisorRecord,
 } from "./runtime-store.ts";
@@ -28,7 +28,6 @@ import {
   type KxmRuntimeContext,
 } from "./runtime-service.ts";
 import { createKxmOneShotProducer } from "./oneshot-producer.ts";
-import { isRouteAdmitted } from "./routes.ts";
 import { KxmRunScheduler, createKxmSimulatedProducer, recordDriveReceipt, recoverKxmRun, kxmDrivePollProjection } from "./engine.ts";
 import { kxmDriveSession, kxmOpenDriveSessions } from "./runtime-owner.ts";
 import { RuntimeHubClient, HubHttpError, type SyncPushResponse } from "./client.ts";
@@ -126,6 +125,28 @@ function readRecentSupervisorError(paths: KxmRuntimePaths): string | undefined {
   }
 }
 
+const SETTLED_RUN_STATUS = new Set(["completed", "failed", "cancelled"]);
+
+/** Same liveness rule as `kxmSupervisorStatus`: running, a fresh heartbeat, and a live pid. */
+export function kxmSupervisorRecordIsLive(record: KxmSupervisorRecord | undefined): boolean {
+  return supervisorStatusOf(record).running;
+}
+
+function unsettledRunIds(context: KxmRuntimeContext): string[] {
+  const ids: string[] = [];
+  for (const stored of context.eventStore.runsForProject(context.projectId, 10_000)) {
+    let status: string = stored.status;
+    try {
+      status = projectKxmRunReadOnly(context, stored.runId).status;
+    } catch {
+      ids.push(stored.runId);
+      continue;
+    }
+    if (!SETTLED_RUN_STATUS.has(status)) ids.push(stored.runId);
+  }
+  return ids;
+}
+
 function supervisorStatusOf(record: KxmSupervisorRecord | undefined): KxmSupervisorStatus {
   if (!record) return { running: false };
   // Pid-only liveness is not enough: after a crash the pid may be reused by
@@ -781,6 +802,65 @@ async function startKxmRuntimeSupervisorInner(
           return;
         }
 
+        if (request.method === "POST" && url.pathname === "/v1/projects/unregister") {
+          const body = await readJsonBody(request);
+          const projectRoot = typeof body.projectRoot === "string" ? body.projectRoot : "";
+          const force = body.force === true;
+          if (!projectRoot || !isAbsolute(projectRoot)) {
+            sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: "projectRoot must be an absolute path" });
+            return;
+          }
+          if (!force) {
+            const key = projectRuntimeKey(projectRoot);
+            const existing = contexts.get(key);
+            let openRunIds: string[] = [];
+            if (existing) {
+              openRunIds = unsettledRunIds(existing);
+            } else {
+              const registration = registry.projectByRoot(projectRoot);
+              const eventsPath = join(paths.projectsDir, registration?.projectKey ?? projectRuntimeKey(projectRoot), "run-events.db");
+              if (registration && existsSync(eventsPath)) {
+                const store = new KxmRunEventStore(eventsPath);
+                try {
+                  openRunIds = store.runsForProject(registration.projectId, 10_000)
+                    .filter((run) => !SETTLED_RUN_STATUS.has(run.status))
+                    .map((run) => run.runId);
+                } finally {
+                  store.close();
+                }
+              }
+            }
+            if (openRunIds.length > 0) {
+              sendJson(response, 409, {
+                ok: false,
+                error: "runtime_project_busy",
+                message: `unsettled run ${openRunIds.join(", ")}`,
+                runIds: openRunIds,
+              });
+              return;
+            }
+            const laneCount = registry.homeLaneCount(projectRoot);
+            if (laneCount > 0) {
+              sendJson(response, 409, {
+                ok: false,
+                error: "runtime_project_has_lanes",
+                message: `home root still has ${laneCount} lane(s)`,
+              });
+              return;
+            }
+          }
+          const key = projectRuntimeKey(projectRoot);
+          const existing = contexts.get(key);
+          const unregistered = registry.unregisterProject(projectRoot);
+          if (existing) {
+            contexts.delete(key);
+            syncStatuses.delete(key);
+            closeKxmRuntimeContext(existing);
+          }
+          sendJson(response, 200, { ok: true, unregistered });
+          return;
+        }
+
         if (request.method === "POST" && url.pathname === "/v1/runs") {
           const body = await readJsonBody(request);
           const projectRoot = typeof body.projectRoot === "string" ? body.projectRoot : "";
@@ -838,23 +918,6 @@ async function startKxmRuntimeSupervisorInner(
               ? createKxmOneShotProducer({
                   projectRoot,
                   timeoutMs: kxmProjectAdmissionLimits(bundle).agentStepTimeoutMs,
-                  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 || !isRouteAdmitted(projectRoot, `${provider}/${modelName}`)) {
-                      throw new Error("producer_route_not_admitted");
-                    }
-                    return { provider, model: modelName };
-                  },
                 })
               : createKxmSimulatedProducer(async () => {
                   if (delayMs > 0) {
@@ -1026,9 +1089,12 @@ async function startKxmRuntimeSupervisorInner(
           // that returned raw rows would let every consumer — including the portal's
           // tenant read — present cached status as authoritative. Folding replays each
           // run's events; workflows are transition-bounded, so this stays cheap at the
-          // 50-run cap. A run that refuses to fold is returned with its cached row plus
+          // default 50-run cap (`limit` may ask for up to 10000). A run that refuses to fold is returned with its cached row plus
           // `projectionError`, so one corrupt run cannot make the listing lie by omission.
-          const runs = context.eventStore.runsForProject(requestedProjectId, 50).map((stored) => {
+          const limitText = url.searchParams.get("limit");
+          const parsedLimit = limitText === null ? 50 : Number(limitText);
+          const limit = Number.isInteger(parsedLimit) && parsedLimit > 0 ? Math.min(parsedLimit, 10_000) : 50;
+          const runs = context.eventStore.runsForProject(requestedProjectId, limit).map((stored) => {
             try {
               return projectKxmRunReadOnly(context, stored.runId);
             } catch (error) {

package/plugins/kxm/src/suggest.ts

@@ -191,10 +191,10 @@ export function suggestWorkflowAndRoles(
       supported: true,
       prerequisites: [
         "Run kxm init in the target repository if needed, then install the exact template with the suggested command. If that workflow ID already exists, stop and review it; the commands below apply only to a newly installed template, not an existing definition with potentially different agents or permissions.",
-        ...roles.map((role) => `Set harness: ${role.harness} and model: <your authenticated compatible model selector> in .kxm/agents/${role.agent}.yaml. Admit that exact selector in .kxm/routes.yaml and ensure it is not disabled; this recommendation does not choose a model or change routing.`),
+        ...roles.map((role) => `Set role on .kxm/agents/${role.agent}.yaml to a role whose roster names an admitted route for harness ${role.harness}. Admit that route's selector in .kxm/routes.yaml and ensure it is not disabled; this recommendation does not choose a model or change routing.`),
         ...(writeStep ? [
           `Keep each writer step at assignments.maximum: 1 and set limits.maxConcurrentRuns: 1 in .kxm/project.yaml; the live ${selected.id} writer profile requires a lone writer in the checkout.`,
-          `If .kxm/roster.yaml exists, it must be readable kxm.developer-roster.v1 with a lineup.writer route matching harness: ${selected.id} and the selected writer model (model or vendor/model), status: admitted, and permissions containing edit.`,
+          `The writer role roster must name a route whose harness is ${selected.id}, whose status is admitted, and whose permissions contain edit.`,
           "Configure the test gate in .kxm/gates.yaml with kind: command and argv for this repository's actual verification command. A scaffold/example command or simulation is not evidence that the implementation works.",
         ] : []),
         `Validate the installed workflow with kxm gate validate --file .kxm/workflows/${bestPattern.id}.yaml and the project configuration with kxm init --dry-run before creating a run.`,

package/plugins/kxm/src/template.ts

@@ -175,21 +175,9 @@ function coreTemplate(projectId: string, projectName: string, variant: KxmTempla
   ]);
   if (variant === "v4-registry") {
     const coordinator = files.get(".kxm/agents/coordinator.yaml");
-    if (coordinator) {
-      files.set(".kxm/agents/coordinator.yaml", {
-        ...coordinator,
-        harness: "claude",
-        model: { provider: "anthropic", model: "fable" },
-      });
-    }
+    if (coordinator) files.set(".kxm/agents/coordinator.yaml", { ...coordinator, role: "planner" });
     const implementer = files.get(".kxm/agents/implementer.yaml");
-    if (implementer) {
-      files.set(".kxm/agents/implementer.yaml", {
-        ...implementer,
-        harness: "grok",
-        model: { provider: "xai", model: "grok-4.6" },
-      });
-    }
+    if (implementer) files.set(".kxm/agents/implementer.yaml", { ...implementer, role: "writer" });
     const workflow = files.get(".kxm/workflows/default.yaml");
     if (workflow) {
       const limits = { ...(workflow.limits as JsonObject) };

package/schemas/agent.schema.json

@@ -12,6 +12,14 @@
     "model": { "$ref": "common.schema.json#/$defs/modelSelector" },
     "executor": { "$ref": "common.schema.json#/$defs/identifier" },
     "harness": { "$ref": "common.schema.json#/$defs/identifier" },
+    "role": { "$ref": "common.schema.json#/$defs/identifier" },
+    "effort": { "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"] },
+    "skills": {
+      "type": "array",
+      "items": { "$ref": "common.schema.json#/$defs/identifier" },
+      "maxItems": 64,
+      "uniqueItems": true
+    },
     "tools": { "$ref": "common.schema.json#/$defs/toolPolicy" },
     "defaultRepositoryAccess": { "$ref": "common.schema.json#/$defs/repositoryAccess" },
     "repositories": {

package/scripts/roster-policy.d.mts

@@ -7,7 +7,6 @@ export interface RosterRoute {
   readonly status: 'admitted' | 'retired';
 }
 export interface RosterPolicy {
-  readonly schema: 'kxm.developer-roster.v1';
   readonly routes: Readonly<Record<string, RosterRoute>>;
   readonly lineup: Readonly<Record<string, readonly string[]>>;
   readonly required_critics: Readonly<Record<'review-arch' | 'review-cli', string>>;
@@ -15,9 +14,11 @@ export interface RosterPolicy {
 }
 export interface PolicyIdentity { readonly commit: string; readonly blob: string; readonly sha256: string }
 export interface LoadedPolicy { readonly identity: PolicyIdentity; readonly policy: RosterPolicy }
+export function refuseRetiredRosterFile(root: string): void;
 export function loadTrustedRosterPolicy(): LoadedPolicy;
 export function resolveBoundPolicy(identity: PolicyIdentity): LoadedPolicy;
 export function canonicalVendor(value: string): string;
+export function assembleRosterPolicy(models: readonly Record<string, unknown>[], roles: readonly Record<string, unknown>[]): RosterPolicy;
 export function validateRosterDocument(
   policy: RosterPolicy,
   readBlob: (source: string) => string | Uint8Array | null | undefined,

package/scripts/roster-policy.mjs

@@ -8,9 +8,11 @@ import YAML from 'yaml';
 import { NATIVE_PI_BRAKE_PROVIDERS, PI_ALLOWED_PROVIDERS, PI_ANTIGRAVITY_MODEL_ID, PI_NATIVE_VENDOR_PROVIDERS, ROUTES } from './harness-run.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const POLICY = '.kxm/roster.yaml';
-const RETIRED_POLICY = '.kxm/roster.json';
+const MODEL_DIR = '.kxm/models';
+const ROLE_DIR = '.kxm/roles';
+const RETIRED_ROSTER_FILES = ['.kxm/roster.json', '.kxm/roster.yaml'];
 const TRUSTED = 'refs/remotes/origin/main';
+const SKIP_MODELS = new Set(['inventory.yaml']);
 const ROLES = ['writer', 'planner', 'reviewer-arch', 'reviewer-cli', 'experiment'];
 const ALIASES = Object.freeze({ 'x-ai': 'xai', moonshotai: 'moonshot', 'google-ai': 'google', qwen: 'alibaba' });
 const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
@@ -55,14 +57,19 @@ function frozen(value) {
   if (value && typeof value === 'object') { for (const child of Object.values(value)) frozen(child); Object.freeze(value); }
   return value;
 }
+export function refuseRetiredRosterFile(root) {
+  for (const retired of RETIRED_ROSTER_FILES) {
+    if (existsSync(path.join(root, retired))) refuse(`retired_roster_file: retired ${retired} present; use ${MODEL_DIR} and ${ROLE_DIR}`);
+  }
+}
 function control() {
-  if (existsSync(path.join(ROOT, RETIRED_POLICY))) refuse(`retired ${RETIRED_POLICY} present; use ${POLICY}`);
+  refuseRetiredRosterFile(ROOT);
   if (realpathSync(gitText('rev-parse', '--show-toplevel')) !== realpathSync(ROOT)) refuse('module is outside its control repository');
   const head = gitText('rev-parse', '--verify', 'HEAD^{commit}');
   const trusted = gitText('rev-parse', '--verify', `${TRUSTED}^{commit}`);
   git('merge-base', '--is-ancestor', head, trusted);
   const flags = git('ls-files', '-v', '-z').toString('utf8').split('\0').filter(Boolean);
-  if (flags.some(entry => entry.slice(2) !== POLICY && (entry[0] === 'S' || entry[0] === entry[0].toLowerCase()))) refuse('hidden index flags on control source');
+  if (flags.some(entry => entry[0] === 'S' || entry[0] === entry[0].toLowerCase())) refuse('hidden index flags on control source');
   if (git('status', '--porcelain=v1', '--untracked-files=all').length) refuse('dirty or untracked control source');
   return { head, trusted };
 }
@@ -88,8 +95,7 @@ function workingBytes(source) {
   return readFileSync(current);
 }
 export function validateRosterDocument(policy, readBlob) {
-  keys(policy, ['schema', 'routes', 'lineup', 'required_critics', 'model_origins'], 'policy');
-  if (policy.schema !== 'kxm.developer-roster.v1') refuse('unsupported schema');
+  keys(policy, ['routes', 'lineup', 'required_critics', 'model_origins'], 'policy');
   record(policy.routes, 'routes'); record(policy.lineup, 'lineup'); record(policy.model_origins, 'model origins');
   if (!Object.keys(policy.routes).length) refuse('empty routes');
   if (typeof readBlob !== 'function') refuse('origin evidence reader required');
@@ -162,35 +168,126 @@ export function validateRosterDocument(policy, readBlob) {
   }
   return policy;
 }
-function validate(bytes, commit, trusted) {
-  let policy;
-  try { policy = YAML.parse(bytes.toString('utf8')); } catch { refuse('invalid policy YAML'); }
-  if (policy === undefined || policy === null || typeof policy !== 'object' || Array.isArray(policy)) refuse('invalid policy YAML');
+function parsePolicyYaml(bytes, label) {
+  let value;
+  try { value = YAML.parse(bytes.toString('utf8')); } catch { refuse(`invalid policy YAML (${label})`); }
+  if (value === undefined || value === null || typeof value !== 'object' || Array.isArray(value)) refuse(`invalid policy YAML (${label})`);
+  return value;
+}
+function listedPolicyFiles(commit) {
+  const raw = git('ls-tree', '-r', '-z', commit, '--', MODEL_DIR, ROLE_DIR).toString('utf8');
+  const files = [];
+  for (const entry of raw.split('\0').filter(Boolean)) {
+    const match = /^(100644|100755) blob ([a-f0-9]{40}(?:[a-f0-9]{24})?)\t(.+)$/u.exec(entry);
+    if (!match) refuse('source is missing or not a regular committed file');
+    const source = match[3];
+    if (!source.endsWith('.yaml')) continue;
+    const name = source.slice(source.lastIndexOf('/') + 1);
+    if (source.startsWith(`${MODEL_DIR}/`) && SKIP_MODELS.has(name)) continue;
+    if (source.startsWith(`${MODEL_DIR}/`) || source.startsWith(`${ROLE_DIR}/`)) files.push(source);
+  }
+  if (!files.some(source => source.startsWith(`${ROLE_DIR}/`)) || !files.some(source => source.startsWith(`${MODEL_DIR}/`))) {
+    refuse('source is missing or not a regular committed file');
+  }
+  return files.sort();
+}
+/** Build the runner policy object from parsed model and role documents. */
+export function assembleRosterPolicy(models, roles) {
+  if (!Array.isArray(models) || !Array.isArray(roles)) refuse('invalid policy YAML');
+  const lineup = {};
+  const rolesByRoute = {};
+  for (const role of [...roles].sort((left, right) => String(left?.id).localeCompare(String(right?.id)))) {
+    record(role, 'role');
+    text(role.id, 'role id');
+    if (!Array.isArray(role.roster)) refuse('lineup contains unsupported or duplicate values');
+    const ids = [];
+    for (const entry of role.roster) {
+      record(entry, 'roster entry');
+      text(entry.route, 'roster route');
+      ids.push(entry.route);
+      if (!rolesByRoute[entry.route]) rolesByRoute[entry.route] = [];
+      if (!rolesByRoute[entry.route].includes(role.id)) rolesByRoute[entry.route].push(role.id);
+    }
+    lineup[role.id] = ids;
+  }
+  const routes = {};
+  const model_origins = {};
+  for (const doc of models) {
+    record(doc, 'model');
+    text(doc.id, 'route id');
+    if (!rolesByRoute[doc.id]) continue;
+    routes[doc.id] = {
+      harness: doc.harness,
+      model: doc.model,
+      vendor: doc.vendor,
+      roles: rolesByRoute[doc.id],
+      permissions: doc.permissions,
+      status: doc.status,
+    };
+    if (doc.origin !== undefined) {
+      record(doc.origin, 'origin');
+      const evidence = { source: doc.origin.source, sha256: doc.origin.sha256 };
+      if (doc.origin.commit !== undefined) evidence.commit = doc.origin.commit;
+      model_origins[doc.model] = { vendor: doc.vendor, evidence };
+    }
+  }
+  return {
+    routes,
+    lineup,
+    required_critics: {
+      'review-arch': lineup['reviewer-arch']?.[0],
+      'review-cli': lineup['reviewer-cli']?.[0],
+    },
+    model_origins,
+  };
+}
+function readPolicySet(commit, checkWorking) {
+  const files = listedPolicyFiles(commit);
+  const models = [];
+  const roles = [];
+  const parts = [];
+  for (const source of files) {
+    const { bytes } = blobAt(commit, source);
+    if (checkWorking && !workingBytes(source).equals(bytes)) refuse('working policy differs from committed bytes');
+    const doc = parsePolicyYaml(bytes, source);
+    if (source.startsWith(`${MODEL_DIR}/`)) models.push(doc);
+    else roles.push(doc);
+    parts.push({ source, bytes });
+  }
+  return { models, roles, digest: compositeDigest(parts) };
+}
+function compositeDigest(parts) {
+  const hash = createHash('sha256');
+  for (const part of [...parts].sort((left, right) => left.source < right.source ? -1 : left.source > right.source ? 1 : 0)) {
+    hash.update(part.source);
+    hash.update('\0');
+    hash.update(part.bytes);
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+function policyAt(commit, trusted, checkWorking) {
+  const loaded = readPolicySet(commit, checkWorking);
   const readBlob = (source, pinnedCommit) => {
     if (pinnedCommit === undefined) return blobAt(commit, source).bytes;
-    // A pinned evidence commit decouples the digest from later edits to the
-    // evidence file; the pinned commit itself must be part of trusted history.
     git('merge-base', '--is-ancestor', pinnedCommit, trusted);
     return blobAt(pinnedCommit, source).bytes;
   };
-  return validateRosterDocument(policy, readBlob);
+  return { policy: validateRosterDocument(assembleRosterPolicy(loaded.models, loaded.roles), readBlob), digest: loaded.digest };
 }
 export function loadTrustedRosterPolicy() {
   const snapshot = control();
-  const { blob, bytes } = blobAt(snapshot.head, POLICY);
-  if (!workingBytes(POLICY).equals(bytes)) refuse('working policy differs from committed bytes');
-  const policy = validate(bytes, snapshot.head, snapshot.trusted);
+  const { policy, digest } = policyAt(snapshot.head, snapshot.trusted, true);
   unchanged(snapshot);
-  return frozen({ identity: { commit: snapshot.head, blob, sha256: sha256(bytes) }, policy });
+  return frozen({ identity: { commit: snapshot.head, blob: digest, sha256: digest }, policy });
 }
 export function resolveBoundPolicy(identity) {
   keys(identity, ['commit', 'blob', 'sha256'], 'identity');
-  objectId(identity.commit, 'commit'); objectId(identity.blob, 'blob'); digest(identity.sha256);
+  objectId(identity.commit, 'commit'); digest(identity.blob); digest(identity.sha256);
   const snapshot = control();
   git('merge-base', '--is-ancestor', identity.commit, snapshot.trusted);
-  const { blob, bytes } = blobAt(identity.commit, POLICY);
-  if (blob !== identity.blob || sha256(bytes) !== identity.sha256) refuse('bound identity mismatch');
-  const policy = validate(bytes, identity.commit, snapshot.trusted);
+  const loaded = policyAt(identity.commit, snapshot.trusted, false);
+  if (loaded.digest !== identity.blob || loaded.digest !== identity.sha256) refuse('bound identity mismatch');
   unchanged(snapshot);
-  return frozen({ identity: { ...identity }, policy });
+  return frozen({ identity: { ...identity }, policy: loaded.policy });
 }

package/scripts/run-bounded.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+// Wall-clock guard for a test suite. Node's --test-timeout also bounds each
+// file (each file is a test), so the suite scripts do not pass it. This
+// bounds the process that runs them.
+
+import { spawn } from "node:child_process";
+
+const timeoutMs = Number(process.argv[2]);
+const command = process.argv[3];
+const args = process.argv.slice(4);
+if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || command === undefined) {
+  console.error("usage: run-bounded.mjs <timeout-ms> <command> [args...]");
+  process.exit(2);
+}
+
+const child = spawn(command, args, { stdio: "inherit", detached: true });
+let timedOut = false;
+
+function signalGroup(signal) {
+  if (child.pid === undefined) return;
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    try { child.kill(signal); } catch { /* already gone */ }
+  }
+}
+
+const timer = setTimeout(() => {
+  timedOut = true;
+  console.error(`wall clock ${timeoutMs}ms exceeded`);
+  signalGroup("SIGTERM");
+  setTimeout(() => signalGroup("SIGKILL"), 2000).unref();
+}, timeoutMs);
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => {
+    signalGroup(signal);
+  });
+}
+
+child.on("error", (error) => {
+  clearTimeout(timer);
+  console.error(error.message);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  clearTimeout(timer);
+  if (timedOut) process.exit(124);
+  if (signal) process.exit(1);
+  process.exit(code ?? 1);
+});