@kontextmind/kxm 0.7.40 → 0.7.44

package/scripts/docker-install-smoke.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+// Fresh-container install smoke: proves the packed kxm tarball installs into a
+// clean Docker container with a brand-new Pi installation, that every runtime
+// dependency lands, and that two configured plan providers complete a live
+// turn. Secrets come from pass-cli and are injected through a mode-600 env
+// file inside a temp directory that is removed afterwards; they never touch
+// argv, the image, or the repository.
+//
+// Usage: just docker-install-smoke
+// Requires: docker daemon, pass-cli session, ~/.pi/agent/models-store.json.
+
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const repoRoot = resolve(import.meta.dirname, "..");
+
+const vault = process.env.KXM_SMOKE_VAULT ?? "AI Provider Keys";
+const image = process.env.KXM_SMOKE_IMAGE ?? "node:24-slim";
+const modelsStorePath = process.env.KXM_SMOKE_MODELS_STORE ?? join(homedir(), ".pi/agent/models-store.json");
+
+// provider id -> { env, item, field, model }. The zai key is stored in the
+// SshKey public_key slot of its pass item (upstream quirk); the qwen key is an
+// extra Hidden field named "API Key".
+const providers = [
+  {
+    id: "zai-coding-cn",
+    env: "ZAI_CODING_CN_API_KEY",
+    item: process.env.KXM_SMOKE_ZAI_ITEM ?? "Z.ai",
+    field: process.env.KXM_SMOKE_ZAI_FIELD ?? "public_key",
+    model: process.env.KXM_SMOKE_ZAI_MODEL ?? "glm-5.3-flash",
+  },
+  {
+    id: "qwen-token-plan",
+    env: "QWEN_TOKEN_PLAN_API_KEY",
+    item: process.env.KXM_SMOKE_QWEN_ITEM ?? "Alibaba Cloud Personal Plan",
+    field: process.env.KXM_SMOKE_QWEN_FIELD ?? "API Key",
+    model: process.env.KXM_SMOKE_QWEN_MODEL ?? "qwen3.8-flash",
+  },
+];
+
+function die(message) {
+  process.stderr.write(`docker-install-smoke: ${message}\n`);
+  process.exit(1);
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: "utf8", ...options });
+  if (result.status !== 0) {
+    die(`\`${command} ${args.join(" ")}\` failed (${result.status})\n${result.stderr || result.stdout}`);
+  }
+  return result;
+}
+
+function passItem(title) {
+  const result = spawnSync(
+    "pass-cli",
+    ["item", "view", "--vault-name", vault, "--item-title", title, "--output", "json"],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) {
+    die(`pass-cli could not read item ${JSON.stringify(title)} in vault ${JSON.stringify(vault)}: ${result.stderr}`);
+  }
+  return JSON.parse(result.stdout)?.item?.content;
+}
+
+// Field values hide in either extra_fields (by name) or the SshKey section.
+function extractField(content, field) {
+  const extra = content.extra_fields?.find((candidate) => candidate.name === field);
+  if (extra) {
+    const values = extra.content ?? {};
+    return values.Hidden ?? values.Text;
+  }
+  return content.content?.SshKey?.[field];
+}
+
+function main() {
+  for (const tool of ["docker", "pass-cli", "npm"]) {
+    if (spawnSync(tool, ["--version"], { encoding: "utf8" }).status !== 0) {
+      die(`${tool} is required but not on PATH`);
+    }
+  }
+  const daemon = spawnSync("docker", ["info", "--format", "ok"], { encoding: "utf8" });
+  if (daemon.status !== 0) {
+    die("docker daemon is not reachable; start Docker and retry");
+  }
+
+  const scratch = mkdtempSync(join(tmpdir(), "kxm-install-smoke-"));
+  try {
+    // 1. Pack the working tree. The committed dist must be current; the
+    //    commit gate (`npm run verify` -> check:generated) enforces that.
+    process.stdout.write("==> npm pack\n");
+    const packed = run("npm", ["pack", "--pack-destination", scratch, "--json"], { cwd: repoRoot });
+    const filename = JSON.parse(packed.stdout)[0]?.filename;
+    if (!filename) die("npm pack produced no tarball");
+    const tarball = join(scratch, filename);
+
+    // 2. Provider models from the local pi catalog (no secrets in this file).
+    const store = JSON.parse(readFileSync(modelsStorePath, "utf8"));
+    const configured = {};
+    const envLines = [];
+    for (const provider of providers) {
+      const entry = store[provider.id];
+      if (!entry) {
+        die(`provider ${provider.id} is missing from ${modelsStorePath}`);
+      }
+      const models = entry.models.map((model) => {
+        const copy = { ...model };
+        delete copy.checkedAt;
+        delete copy.lastModified;
+        delete copy.etag;
+        return copy;
+      });
+      if (models.length === 0) die(`provider ${provider.id} has no models in ${modelsStorePath}`);
+      configured[provider.id] = {
+        baseUrl: models[0].baseUrl,
+        api: models[0].api ?? "openai-completions",
+        apiKey: `$${provider.env}`,
+        models,
+      };
+      const key = extractField(passItem(provider.item), provider.field);
+      if (!key) {
+        die(`no value found for ${provider.item} / ${provider.field} in vault ${vault}`);
+      }
+      process.stdout.write(`==> key for ${provider.id}: item=${JSON.stringify(provider.item)} field=${provider.field} len=${key.length}\n`);
+      envLines.push(`${provider.env}=${key}`);
+    }
+    const modelsJson = join(scratch, "models.json");
+    writeFileSync(modelsJson, `${JSON.stringify({ providers: configured }, null, 2)}\n`);
+
+    // 3. Keys go into a mode-600 env file only; docker --env-file injects them
+    //    into the container environment without ever appearing in argv.
+    const envFile = join(scratch, "providers.env");
+    writeFileSync(envFile, `${envLines.join("\n")}\n`, { mode: 0o600 });
+    chmodSync(envFile, 0o600);
+
+    // 4. The in-container flow: fresh pi, both providers live, kxm operator
+    //    install with the documented --omit=peer path, pi package install,
+    //    then the README first-run flow.
+    const smokeModels = providers.map((provider) => ({
+      id: provider.id,
+      env: provider.env,
+      model: provider.model,
+      token: `${provider.id.toUpperCase().replaceAll(/[^A-Z]/g, "")}_SMOKE_OK`,
+    }));
+    const container = join(scratch, "container.sh");
+    writeFileSync(container, containerScript(smokeModels, filename));
+
+    process.stdout.write(`==> docker run ${image}\n`);
+    const result = spawnSync("docker", [
+      "run", "--rm",
+      "-v", `${scratch}:/mnt:ro`,
+      "--env-file", envFile,
+      image, "bash", "/mnt/container.sh",
+    ], { stdio: "inherit" });
+    if (result.status !== 0) {
+      die(`container smoke failed with ${result.status}`);
+    }
+    process.stdout.write("==> install smoke passed\n");
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+function containerScript(smokeModels, filename) {
+  const [first, second] = smokeModels;
+  return `#!/bin/bash
+# Generated by scripts/docker-install-smoke.mjs. Runs inside a clean container.
+set -uo pipefail
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+echo "== toolchain versions =="
+node --version
+npm --version
+apt-get update -qq >/dev/null 2>&1 && apt-get install -y -qq git >/dev/null 2>&1
+git --version
+
+echo
+echo "== [1/7] fresh pi installation (npm global, --ignore-scripts) =="
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent --no-audit --no-fund >/tmp/pi-install.log 2>&1 \\
+  || { tail -20 /tmp/pi-install.log; fail "pi global install failed"; }
+pi --version || fail "pi not on PATH after global install"
+
+echo
+echo "== [2/7] custom providers load with env-var auth =="
+mkdir -p ~/.pi/agent
+cp /mnt/models.json ~/.pi/agent/models.json
+${smokeModels.map((provider) => `env | grep -q '^${provider.env}=.' || fail "${provider.env} env missing"`).join("\n")}
+LM=$(pi --list-models 2>&1) || fail "pi --list-models failed: $LM"
+${smokeModels.map((provider) => `echo "$LM" | grep -qi "${provider.id}" || fail "${provider.id} models not available: $LM"`).join("\n")}
+${smokeModels.map((provider) => `echo "  ${provider.id}: $(echo "$LM" | grep -ci '${provider.id}') models listed"`).join("\n")}
+
+echo
+echo "== [3/7] live completion: ${first.id} / ${first.model} =="
+Z=$(pi --provider ${first.id} --model ${first.model} -p "Reply with exactly this token and nothing else: ${first.token}") \\
+  || fail "${first.id} completion failed"
+echo "  reply: $Z"
+echo "$Z" | grep -q "${first.token}" || fail "${first.id} reply missing expected token"
+
+echo
+echo "== [4/7] live completion: ${second.id} / ${second.model} =="
+Q=$(pi --provider ${second.id} --model ${second.model} -p "Reply with exactly this token and nothing else: ${second.token}") \\
+  || fail "${second.id} completion failed"
+echo "  reply: $Q"
+echo "$Q" | grep -q "${second.token}" || fail "${second.id} reply missing expected token"
+
+echo
+echo "== [5/7] kxm operator CLI: documented global --omit=peer tarball install =="
+GROOT_BEFORE=$(ls "$(npm root -g)")
+npm install --global --omit=peer --no-audit --no-fund /mnt/${filename} >/tmp/kxm-install.log 2>&1 \\
+  || { tail -20 /tmp/kxm-install.log; fail "kxm global install failed"; }
+kxm hub help 2>&1 | grep -q "Usage: kxm hub" || fail "kxm hub help did not run (runtime deps missing?)"
+echo "  kxm bin runs: OK"
+GROOT=$(npm root -g)
+for d in @anthropic-ai/claude-agent-sdk @earendil-works/pi-tui @modelcontextprotocol/sdk yaml; do
+  if [ -d "$GROOT/@kontextmind/kxm/node_modules/$d" ] || [ -d "$GROOT/$d" ]; then
+    echo "  dependency installed: $d"
+  else
+    fail "dependency NOT installed: $d"
+  fi
+done
+if [ -d "$GROOT/typebox" ] && ! echo "$GROOT_BEFORE" | grep -q "^typebox$"; then
+  fail "peer typebox was installed despite --omit=peer"
+fi
+echo "  peers correctly omitted (--omit=peer); CLI still runs"
+
+echo
+echo "== [6/7] pi package surface (extension + skills) =="
+mkdir -p /opt/kxm-pkg
+tar -xzf /mnt/${filename} -C /opt/kxm-pkg --strip-components=1
+cd /opt/kxm-pkg
+npm install --omit=dev --no-audit --no-fund >/tmp/pkg-install.log 2>&1 \\
+  || { tail -20 /tmp/pkg-install.log; fail "package npm install failed (pi git-install step)"; }
+pi install /opt/kxm-pkg >/tmp/pi-install-pkg.log 2>&1 || { tail -20 /tmp/pi-install-pkg.log; fail "pi install of kxm package failed"; }
+pi list 2>&1 | grep -qi "kxm" || fail "pi list does not show kxm"
+echo "  pi list shows kxm package: OK"
+
+echo
+echo "== [7/7] first-run flow: kxm init + hub + bind + session brief =="
+mkdir -p /testproj && cd /testproj && git init -q .
+kxm init --json --name docker-smoke --project-id prj_01JDOCKERTESTSMOKE000000000 || fail "kxm init failed"
+export KXM_AUTH_TOKEN="docker-admin-token"
+export KXM_PROJECT_TOKENS='{"docker-smoke":"proj-token"}'
+nohup kxm hub start >/tmp/hub.log 2>&1 &
+for i in $(seq 1 30); do grep -q "listening at" /tmp/hub.log 2>/dev/null && break; sleep 1; done
+grep "listening at" /tmp/hub.log || { cat /tmp/hub.log; fail "hub did not start"; }
+kxm hub bind http://127.0.0.1:7331 || fail "hub bind failed"
+kxm session brief >/dev/null || fail "session brief failed"
+echo "  first-run flow: OK"
+
+echo
+echo "== final: pi print-mode run with kxm extension loaded =="
+OUT=$(pi --provider ${first.id} --model ${first.model} -p "Reply with exactly: FINAL_OK" 2>/tmp/pi-ext.err) \\
+  || { cat /tmp/pi-ext.err; fail "final pi run failed"; }
+if grep -iE "failed to load|extension error|cannot find" /tmp/pi-ext.err >/dev/null; then
+  cat /tmp/pi-ext.err; fail "kxm extension load errors in pi"
+fi
+echo "  no extension load errors"
+echo "  final reply: $OUT"
+echo "$OUT" | grep -q "FINAL_OK" || fail "final reply missing expected token"
+
+echo
+echo "ALL CHECKS PASSED"
+`;
+}
+
+main();

package/scripts/emit-codex-artifacts.mjs

@@ -45,7 +45,7 @@ The \`kxm\` CLI is the unified agent surface for peer collaboration and workflow
 | \`kxm workflow checkpoint [runId] [stageId] [status] [summary]\` | Record stage result with verified evidence | \`--run-id\`, \`--stage-id\`, \`--status <passed\\|warning\\|failed>\`, \`--summary\`, \`--evidence <json>\`, \`--evidence-refs <json>\` |
 | \`kxm workflow record [runId] [category] [area] [summary]\` | Record plans, decisions, contradictions, errors, lessons | \`--run-id\`, \`--category <plan\\|decision\\|contradiction\\|error\\|lesson>\`, \`--area\`, \`--severity <info\\|warning\\|error>\`, \`--details\`, \`--evidence <items...>\` |
 | \`kxm workflow wait [runId] [stageId] [signalKey] [summary]\` | Pause stage until an external signed signal arrives | \`--run-id\`, \`--stage-id\`, \`--signal-key\`, \`--summary\`, \`--evidence <json>\`, \`--evidence-refs <json>\`, \`--timeout-ms\` |
-| \`kxm workflow signal <runId> <signalKey> <status> <summary>\` | Resume or unblock a waiting stage or vNext run | \`[evidence...]\`, \`--delivery-id\` |
+| \`kxm workflow signal <runId> <signalKey> <status> <summary>\` | Resume or unblock a waiting stage or KXM run | \`[evidence...]\`, \`--delivery-id\` |
 | \`kxm workflow list\` | List local workflow runs | \`--json\` |
 | \`kxm workflow get <runId>\` | Get stages and journal for a run | \`--json\` |
 

package/scripts/kxm-bump-version.mjs

@@ -9,14 +9,22 @@
  *   node scripts/kxm-bump-version.mjs minor               # bump minor
  *   node scripts/kxm-bump-version.mjs major               # bump major
  *
- * Surfaces updated (must stay in sync with scripts/check-versions.mjs):
+ * Surfaces updated (must stay in sync with scripts/check-versions.mjs — both
+ * take their package list from scripts/package-surfaces.mjs):
  *   1. package.json                          .version
  *   2. package-lock.json                     .version + .packages[""].version
+ *      + .packages[<workspace path>].version
  *   3. plugins/kxm/package.json              .version
  *   4. plugins/kxm/.claude-plugin/plugin.json .version
  *   5. .claude-plugin/marketplace.json       .plugins[name=kxm].version
  *   6. plugins/kxm/src/mcp-server.ts         const VERSION = "..."
  *   7. plugins/kxm/dist/mcp-server.js        const VERSION = "..." (rebuilt)
+ *   8. each workspace manifest scanned under packages/ —
+ *      packages/<name>/package.json and packages/<tier>/<name>/package.json
+ *
+ * The lockfile is patched by key, never by searching for the old version string:
+ * a third-party dependency that happens to carry the same version as the
+ * product must not be rewritten into a phantom artifact.
  *
  * After running this script, run `npm run build` to rebuild dist bundles.
  */
@@ -24,6 +32,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { workspaceManifestPaths } from "./package-surfaces.mjs";
 
 const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/;
 
@@ -79,6 +88,43 @@ function patchSourceVersion(filePath, newVersion) {
   writeFileSync(filePath, patched, "utf8");
 }
 
+/**
+ * Patch the lockfile structurally: the root entry and each workspace package
+ * entry, by key. Everything else — including an unrelated dependency whose
+ * version string equals ours — is left byte-for-byte alone.
+ */
+function patchLockVersions(root, newVersion) {
+  const file = resolve(root, "package-lock.json");
+  const raw = readFileSync(file, "utf8");
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`package-lock.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const touched = [];
+  if (typeof data.version === "string") {
+    data.version = newVersion;
+    touched.push("version");
+  }
+  if (data.packages?.[""]) {
+    data.packages[""].version = newVersion;
+    touched.push('packages[""]');
+  }
+  for (const rel of workspaceManifestPaths(root)) {
+    const entry = data.packages?.[rel];
+    if (!entry) {
+      throw new Error(`package-lock.json has no entry for workspace package ${rel}; run npm install to resync the lock`);
+    }
+    entry.version = newVersion;
+    touched.push(`packages[${rel}]`);
+  }
+  if (touched.length === 0) throw new Error("no version fields found to patch in package-lock.json");
+  const trailingNewline = raw.endsWith("\n") ? "\n" : "";
+  writeFileSync(file, `${JSON.stringify(data, null, 2)}${trailingNewline}`, "utf8");
+  return touched;
+}
+
 export function applyVersionBump(root, newVersion) {
   if (!parseSemver(newVersion)) {
     throw new Error(`invalid semver: ${newVersion}`);
@@ -88,18 +134,22 @@ export function applyVersionBump(root, newVersion) {
   const pkgPath = resolve(root, "package.json");
   const oldVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version;
 
-  // JSON surfaces (targeted patch preserves formatting)
+  // JSON manifests (targeted patch preserves formatting). Workspace packages are
+  // scanned, not hard-coded: a new package must not be releasable-then-forgotten.
   const jsonFiles = [
     "package.json",
-    "package-lock.json",
     "plugins/kxm/package.json",
     "plugins/kxm/.claude-plugin/plugin.json",
     ".claude-plugin/marketplace.json",
+    ...workspaceManifestPaths(root).map((rel) => `${rel}/package.json`),
   ];
   for (const rel of jsonFiles) {
     patchJsonVersion(resolve(root, rel), oldVersion, newVersion);
   }
 
+  // Lockfile by key, after the manifests so a missing workspace entry fails loudly.
+  patchLockVersions(root, newVersion);
+
   // TypeScript source
   patchSourceVersion(resolve(root, "plugins/kxm/src/mcp-server.ts"), newVersion);
 

package/scripts/kxm-hub.mjs

@@ -39,6 +39,29 @@ function processExists(pid) {
   }
 }
 
+/**
+ * Live hub claim, if any. Read-only: returns the pid of a well-formed
+ * `hub.pid` claim whose wrapper is still alive, otherwise null.
+ *
+ * Claims that are missing, malformed, dead, or stale return null so the
+ * atomic `claimPidFile()` below keeps sole authority over those cases — it is
+ * the real single-instance guard and fails closed on them. This exists only so
+ * a start that is certainly going to be refused can refuse *before* it
+ * persists credentials.
+ */
+function liveHubClaimPid() {
+  let existing;
+  try {
+    existing = JSON.parse(readFileSync(pidPath, "utf8"));
+  } catch {
+    return null;
+  }
+  if (existing?.version === 1 && existing.role === "hub" && Number.isInteger(existing.pid) && processExists(existing.pid)) {
+    return existing.pid;
+  }
+  return null;
+}
+
 function parseHubEnvFile() {
   const file = join(resolveUserStateRoot(), "hub-env.json");
   let raw;
@@ -122,6 +145,19 @@ function resolveCredentials() {
   return { authToken, authTokenSource, projectTokens, projectTokensSource, file };
 }
 
+// Pre-flight: refuse a start that a live hub already owns before
+// resolveCredentials() can generate and persist an admin token that the
+// running hub never issued. `kxm hub start` used to mint the credential at
+// module load and only then report "already managed by PID <n>", leaving a
+// hub-env.json whose token no process trusts.
+try {
+  const livePid = liveHubClaimPid();
+  if (livePid) {
+    process.stderr.write(`kxm hub: KXM hub is already managed by PID ${livePid}. Run kxm hub stop before starting another hub.\n`);
+    process.exit(1);
+  }
+} catch { /* the atomic claim below still guards startup */ }
+
 let credentials;
 try {
   credentials = resolveCredentials();

package/scripts/kxm-runtime-supervisor.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// KXM vNext Runtime supervisor entry point. Detached child of `kxm runtime start`.
-import { startVnextRuntimeSupervisor } from "../plugins/kxm/dist/vnext-runtime-supervisor.js";
+// KXM Runtime supervisor entry point. Detached child of `kxm runtime start`.
+import { startKxmRuntimeSupervisor } from "../plugins/kxm/dist/runtime-supervisor.js";
 
-const supervisor = await startVnextRuntimeSupervisor({});
+const supervisor = await startKxmRuntimeSupervisor({});
 process.stdout.write(`kxm-runtime-supervisor ready runtimeId=${supervisor.runtimeId} port=${supervisor.port}\n`);
 

package/scripts/package-surfaces.mjs

@@ -0,0 +1,39 @@
+/**
+ * The single source of truth for "which directories are KXM packages".
+ *
+ * `scripts/check-versions.mjs` (the gate) and `scripts/kxm-bump-version.mjs`
+ * (the release writer) must agree exactly, or a release bumps some surfaces and
+ * not others: the 0.7.41 release job failed because a workspace manifest existed
+ * for the checker but not for the bumper. Both now import this scan.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/**
+ * Every package directory under `packages/`, one or two levels deep
+ * (`packages/<name>`, `packages/<tier>/<name>`), as POSIX-style paths relative
+ * to `root` — the same shape `package-lock.json` uses for its `packages` keys.
+ *
+ * A directory that itself carries a `package.json` is a package and is not
+ * descended into further.
+ */
+export function workspaceManifestPaths(root) {
+  const found = [];
+  const packagesDir = resolve(root, "packages");
+  const scan = (absoluteDir, relativeDir, depth) => {
+    if (depth > 2 || !existsSync(absoluteDir)) return;
+    for (const entry of readdirSync(absoluteDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === "node_modules") continue;
+      const abs = join(absoluteDir, entry.name);
+      const rel = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+      if (existsSync(join(abs, "package.json"))) {
+        found.push(rel);
+        continue;
+      }
+      scan(abs, rel, depth + 1);
+    }
+  };
+  scan(packagesDir, "packages", 1);
+  return found.sort();
+}

package/plugins/kxm/src/vnext-gate-hash.ts

@@ -1,10 +0,0 @@
-import { vnextCanonicalJson, type JsonValue } from "./vnext-config.ts";
-import { vnextSha256 } from "./vnext-engine-plan.ts";
-
-export function gateDefinitionHash(id: string, definition: JsonValue): string {
-  return vnextSha256(vnextCanonicalJson({ id, ...(definition as object) } as JsonValue));
-}
-
-export function gateRegistryHash(registryValue: JsonValue): string {
-  return vnextSha256(vnextCanonicalJson(registryValue));
-}