@kontextmind/kxm 0.6.0

package/scripts/build-runtime.mjs

@@ -0,0 +1,56 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { build } from "esbuild";
+
+await build({
+  entryPoints: ["plugins/kxm/src/cli.ts", "plugins/kxm/src/server.ts", "plugins/kxm/src/vnext-runtime-supervisor.ts"],
+  bundle: true,
+  platform: "node",
+  format: "esm",
+  target: "node22",
+  outdir: "plugins/kxm/dist",
+  entryNames: "[name]",
+  banner: { js: "#!/usr/bin/env node" },
+});
+
+await build({
+  entryPoints: [
+    "plugins/kxm/src/core.ts",
+    "plugins/kxm/src/runtime.ts",
+    "plugins/kxm/src/client.ts",
+    "plugins/kxm/src/extension.ts",
+  ],
+  bundle: true,
+  platform: "node",
+  format: "esm",
+  target: "node22",
+  outdir: "plugins/kxm/dist",
+  entryNames: "[name]",
+  external: ["@earendil-works/pi-coding-agent", "typebox"],
+});
+
+const shebang = "#!/usr/bin/env node\n";
+const createRequire = "import { createRequire as __kxmCreateRequire } from 'node:module'; const require = __kxmCreateRequire(import.meta.url);\n";
+// The bundled YAML CommonJS internals use dynamic require, which is
+// unsupported in ESM output; provide createRequire for every runtime bundle.
+for (const bundlePath of [
+  "plugins/kxm/dist/cli.js",
+  "plugins/kxm/dist/server.js",
+  "plugins/kxm/dist/vnext-runtime-supervisor.js",
+]) {
+  const bundled = readFileSync(bundlePath, "utf8");
+  if (!bundled.startsWith(shebang)) throw new Error(`runtime bundle is missing its executable shebang: ${bundlePath}`);
+  writeFileSync(bundlePath, `${shebang}${createRequire}${bundled.slice(shebang.length)}`);
+}
+
+const runtimeLibrary = "plugins/kxm/dist/runtime.js";
+const runtimeLibraryText = readFileSync(runtimeLibrary, "utf8");
+if (runtimeLibraryText.startsWith(shebang)) {
+  throw new Error(`library bundle must not have an executable shebang: ${runtimeLibrary}`);
+}
+writeFileSync(runtimeLibrary, `${createRequire}${runtimeLibraryText}`);
+
+const { emitCodexArtifacts } = await import("./emit-codex-artifacts.mjs");
+emitCodexArtifacts();
+
+const { syncHarnessMemory } = await import("../plugins/kxm/src/memory.ts");
+syncHarnessMemory(process.cwd());

package/scripts/check-generated.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const GENERATED_ARTIFACTS = [
+  "plugins/kxm/dist/cli.js",
+  "plugins/kxm/dist/server.js",
+  "plugins/kxm/dist/mcp-server.js",
+  "plugins/kxm/dist/vnext-runtime-supervisor.js",
+  "plugins/kxm/dist/core.js",
+  "plugins/kxm/dist/runtime.js",
+  "plugins/kxm/dist/client.js",
+  "plugins/kxm/dist/extension.js",
+  ".agents/skills/kxm/SKILL.md",
+  ".agents/skills/kxm/references/protocol.md",
+  ".agents/skills/kxm-session/SKILL.md",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+];
+
+function runGit(repository, args, allowFailure = false) {
+  const result = spawnSync("git", args, {
+    cwd: repository,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.error) throw new Error(`could not run git: ${result.error.message}`);
+  if (!allowFailure && result.status !== 0) {
+    throw new Error(`git ${args.join(" ")} failed: ${(result.stderr || result.stdout).trim()}`);
+  }
+  return result;
+}
+
+export function checkGeneratedArtifacts(repository = process.cwd()) {
+  const requestedRoot = resolve(repository);
+  const topLevel = runGit(requestedRoot, ["rev-parse", "--show-toplevel"]).stdout.trim();
+  const root = resolve(topLevel);
+  const missing = GENERATED_ARTIFACTS.filter((path) => !existsSync(resolve(root, path)));
+  if (missing.length > 0) {
+    throw new Error(`generated artifacts are missing: ${missing.join(", ")}`);
+  }
+
+  const untracked = GENERATED_ARTIFACTS.filter((path) => runGit(
+    root,
+    ["--literal-pathspecs", "ls-files", "--error-unmatch", "--", path],
+    true,
+  ).status !== 0);
+  if (untracked.length > 0) {
+    throw new Error(`generated artifacts are not tracked by git: ${untracked.join(", ")}`);
+  }
+
+  const status = runGit(root, [
+    "--literal-pathspecs",
+    "diff",
+    "--name-only",
+    "--",
+    ...GENERATED_ARTIFACTS,
+  ]).stdout.trim();
+  if (status) {
+    throw new Error(`generated artifacts changed after build:\n${status}`);
+  }
+  return { root, artifacts: [...GENERATED_ARTIFACTS] };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const result = checkGeneratedArtifacts();
+    process.stdout.write(`generated artifacts are tracked and current (${result.artifacts.length})\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : "generated artifact check failed"}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/check-versions.mjs

@@ -0,0 +1,34 @@
+import { readFile } from "node:fs/promises";
+
+async function json(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+const root = await json("package.json");
+const lock = await json("package-lock.json");
+const pluginPackage = await json("plugins/kxm/package.json");
+const pluginManifest = await json("plugins/kxm/.claude-plugin/plugin.json");
+const marketplace = await json(".claude-plugin/marketplace.json");
+const mcpSource = await readFile("plugins/kxm/src/mcp-server.ts", "utf8");
+const mcpVersion = mcpSource.match(/const VERSION = "([^"]+)"/)?.[1];
+const marketplaceEntry = marketplace.plugins?.find((plugin) => plugin.name === "kxm");
+
+const versions = new Map([
+  ["root package", root.version],
+  ["package lock", lock.version],
+  ["package lock root", lock.packages?.[""]?.version],
+  ["plugin package", pluginPackage.version],
+  ["Claude plugin manifest", pluginManifest.version],
+  ["Claude marketplace entry", marketplaceEntry?.version],
+  ["MCP server", mcpVersion],
+]);
+
+const failures = [...versions].filter(([, version]) => version !== root.version);
+if (failures.length > 0) {
+  for (const [name, version] of failures) {
+    process.stderr.write(`${name} version ${String(version)} does not match ${root.version}\n`);
+  }
+  process.exitCode = 1;
+} else {
+  process.stdout.write(`all package surfaces use version ${root.version}\n`);
+}

package/scripts/emit-codex-artifacts.d.mts

@@ -0,0 +1,9 @@
+export const CODEX_COMMANDS_BLOCK: string;
+
+export interface EmitCodexArtifactsResult {
+  readonly destSkillsDir: string;
+  readonly agentsPath: string;
+  readonly agentsUpdated: boolean;
+}
+
+export function emitCodexArtifacts(repoRoot?: string): EmitCodexArtifactsResult;

package/scripts/emit-codex-artifacts.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MARKER_START = "<!-- kxm:codex:commands:start -->";
+const MARKER_END = "<!-- kxm:codex:commands:end -->";
+
+export const CODEX_COMMANDS_BLOCK = `${MARKER_START}
+## KXM agent commands
+
+The \`kxm\` CLI is the unified agent surface for peer collaboration and workflow stages. Every command supports \`--json\`.
+
+### Peer messaging (\`kxm peer <verb> --json\`)
+
+| Command | Purpose | Key options |
+|---|---|---|
+| \`kxm peer list\` | List online peer agents and purposes | \`--json\` |
+| \`kxm peer send [target] [content]\` | Send a focused request to a peer | \`--target\`, \`--content\`, \`--delivery <steer\\|followUp\\|nextTurn>\`, \`--correlation-id\`, \`--idempotency-key\`, \`--workflow-context <json>\`, \`--ttl-ms\` |
+| \`kxm peer get [messageId]\` | Check request status without blocking | \`--message-id\` |
+| \`kxm peer await [messageId]\` | Wait for reply (capped at 60 seconds) | \`--message-id\`, \`--timeout-ms\` (max 60000) |
+| \`kxm peer cancel [messageId]\` | Cancel a queued or delivered request | \`--message-id\` |
+| \`kxm peer fanout\` | Send same request to 1–3 peers | \`--targets <t1,t2>\`, \`--content\`, \`--timeout-ms\`, \`--workflow-context <json>\` |
+| \`kxm peer inbox\` | List inbound requests awaiting a reply | \`--json\` |
+| \`kxm peer reply [messageId] [content]\` | Reply to an inbound request | \`--message-id\`, \`--content\` |
+
+### Workflow lifecycle (\`kxm workflow <verb> --json\`)
+
+| Command | Purpose | Key options |
+|---|---|---|
+| \`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 list\` | List local workflow runs | \`--json\` |
+| \`kxm workflow get <runId>\` | Get stages and journal for a run | \`--json\` |
+
+### Context operating system (\`kxm context <verb> --json\`)
+
+| Command | Purpose | Key options |
+|---|---|---|
+| \`kxm context get <project>\` | Assemble role-aware context packet | \`--role\`, \`--task\`, \`--run\`, \`--stage\`, \`--budget\` |
+| \`kxm context recall <project>\` | Search durable context metadata | \`--query\`, \`--kinds\`, \`--limit\` |
+| \`kxm context state <project> <key>\` | Query authoritative temporal state | \`--as-of <timestamp>\` |
+| \`kxm context episode <project>\` | Query workflow learning episodes | \`--run\` |
+| \`kxm context promote <project> <key>\` | Propose temporal state change | \`--summary\`, \`--authority\`, \`--confidence\`, \`--evidence\` |
+${MARKER_END}`;
+
+export function emitCodexArtifacts(repoRoot = process.cwd()) {
+  const root = resolve(repoRoot);
+  const srcSkillsDir = join(root, "plugins", "kxm", "skills");
+  const destSkillsDir = join(root, ".agents", "skills");
+
+  // 1. Emit .agents/skills from authored skill tree
+  if (existsSync(srcSkillsDir)) {
+    mkdirSync(destSkillsDir, { recursive: true });
+    cpSync(srcSkillsDir, destSkillsDir, { recursive: true });
+  }
+
+  // 2. Emit marker-delimited AGENTS.md block
+  const agentsPath = join(root, "AGENTS.md");
+  let agentsUpdated = false;
+  if (existsSync(agentsPath)) {
+    const original = readFileSync(agentsPath, "utf8");
+    let updated;
+    if (original.includes(MARKER_START) && original.includes(MARKER_END)) {
+      const startIdx = original.indexOf(MARKER_START);
+      const endIdx = original.indexOf(MARKER_END) + MARKER_END.length;
+      updated = original.slice(0, startIdx) + CODEX_COMMANDS_BLOCK + original.slice(endIdx);
+    } else {
+      const doNotIdx = original.indexOf("## Do not");
+      if (doNotIdx !== -1) {
+        updated = `${original.slice(0, doNotIdx)}${CODEX_COMMANDS_BLOCK}\n\n${original.slice(doNotIdx)}`;
+      } else {
+        updated = `${original.trimEnd()}\n\n${CODEX_COMMANDS_BLOCK}\n`;
+      }
+    }
+    if (updated !== original) {
+      writeFileSync(agentsPath, updated);
+      agentsUpdated = true;
+    }
+  }
+
+  return { destSkillsDir, agentsPath, agentsUpdated };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const result = emitCodexArtifacts();
+  process.stdout.write(`Codex artifacts emitted: skills -> ${result.destSkillsDir}, AGENTS.md updated -> ${result.agentsUpdated}\n`);
+}

package/scripts/harness-run.d.mts

@@ -0,0 +1,83 @@
+export const REQUEST_SCHEMA: "kxm.harness-request.v1";
+export const RESULT_SCHEMA: "kxm.harness-result.v2";
+export const OBSOLETE_RESULT_SCHEMA: "kxm.harness-result.v1";
+export const ROUTING_INT_CAP: number;
+export const TOKEN_BASIS: "cumulative";
+export const CONTEXT_OCCUPANCY_UNKNOWN: "unknown";
+export const COST_BASIS: readonly string[];
+export const MODEL_CLAIM_STATUSES: readonly string[];
+export const REVIEW_VERDICTS: readonly string[];
+export const CLAIM_SOURCES: readonly string[];
+export const CLAIM_COUNT_CAP: number;
+export const TRANSPORT_STATUSES: readonly string[];
+export const TRANSPORT_STAGES: readonly string[];
+export const STOP_REASONS: readonly string[];
+export const ERROR_CODES: readonly string[];
+export const EFFORT: readonly string[];
+export const NATIVE_PI_BRAKE_PROVIDERS: readonly string[];
+export const PI_ALLOWED_PROVIDERS: readonly string[];
+export const PI_NOUS_PORTAL_HY4: "nous-portal/tencent/hy4-preview";
+export const PI_ADMITTED_WRITER: "openrouter/qwen/qwen3-coder-plus";
+export const ROUTES: Record<string, {
+  provider: string;
+  roles: readonly string[];
+  permissions: readonly string[];
+  models: readonly string[];
+  efforts: readonly string[];
+  auth: { args: readonly string[]; loginHint: string };
+}>;
+
+export function clampEffort(harness: string, effort?: string): { effort?: string; clamped?: string };
+export function parseJson(text: string): unknown;
+export function piProviderOf(model?: string): string | undefined;
+export function piModelId(model?: string): string | undefined;
+export function piAuthCheckArgs(request: { model: string; role: string }): string[];
+export function resolveLauncher(cliId: string, options?: {
+  platform?: NodeJS.Platform | string;
+  pathEnv?: string;
+  existsSync?: (path: string) => boolean;
+  realpathSync?: (path: string) => string;
+}): string;
+export function unsupportedLauncherMessage(target: string, platform?: string): string;
+export function parseAuth(harness: string, stdio: {
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  status?: number | null;
+}, options?: { observedAt?: string; provider?: string }): {
+  loggedIn: true;
+  method: string;
+  observedAt: string;
+  subscriptionType?: unknown;
+};
+export function buildArgv(request: Record<string, unknown>, ctx?: {
+  mcpConfigPath?: string;
+  promptPath?: string;
+  promptText?: string;
+  schemaPath?: string;
+  schemaText?: string;
+}): string[];
+export function formatRunCost(result: {
+  costBasis?: string | null;
+  costUsd?: number;
+  providerReportedCostUsd?: number;
+}): string;
+export function diagnoseHarnessResult(payload: unknown, filePath?: string): {
+  result?: Record<string, any>;
+  diagnostic?: string;
+};
+export function formatRunListing(payload: unknown, filePath?: string): string;
+export function normalizePi(stdout: string): Record<string, any>;
+export function normalizeCodex(stdout: string): Record<string, any>;
+export function normalizeAgy(payload: unknown): Record<string, any>;
+export function resolveModelUsage(modelUsage: Record<string, unknown>, requestedModel?: string): {
+  effectiveModel?: string;
+  primary?: Record<string, unknown>;
+  auxiliary: unknown[];
+  candidates: string[];
+  matched?: string;
+};
+export function normalizeClaudeOrGrok(payload: unknown, requestedModel?: string): Record<string, any>;
+export function preflightRequest(request: unknown): unknown;
+export function runHarness(request: unknown, deps?: Record<string, unknown>): Promise<Record<string, any>>;
+export function main(argv?: string[], io?: { stdin: NodeJS.ReadableStream; stdout: NodeJS.WritableStream; stderr: NodeJS.WritableStream }): Promise<Record<string, unknown>>;