@kontextmind/kxm 0.7.163 → 0.7.165

package/plugins/kxm/src/hub-binding.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -20,8 +21,31 @@ export interface HubBindingRecord {
   schema: typeof HUB_BINDING_SCHEMA;
   url: string;
   boundAt: string;
+  /** A forwarded or otherwise remote hub. Loopback in the URL does not make this local. */
+  cloud?: true;
+  /** Environment variable that holds the hub token. The token itself is never stored. */
+  tokenEnv?: string;
+  /** Program plus arguments that print the hub token. Not a shell pipeline, and not the token. */
+  tokenCommand?: string;
 }
 
+export type CloudTokenErrorCode = "cloud_token_missing" | "cloud_token_command_failed" | "cloud_token_command_invalid";
+
+/** The cloud binding named a token source and that source did not produce a token. */
+export class CloudTokenError extends Error {
+  readonly code: CloudTokenErrorCode;
+
+  constructor(code: CloudTokenErrorCode, message: string) {
+    super(message);
+    this.name = "CloudTokenError";
+    this.code = code;
+  }
+}
+
+const TOKEN_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const TOKEN_COMMAND_TIMEOUT_MS = 15_000;
+const TOKEN_COMMAND_MAX_BUFFER = 4096;
+
 export class HubBindingError extends Error {
   constructor(message: string) {
     super(message);
@@ -71,6 +95,132 @@ export function validateHubUrl(raw: string): string {
   return parsed.href.replace(/\/$/, "");
 }
 
+/** A cloud binding's token command is a program and arguments, never a shell. */
+export function splitTokenCommand(raw: string): string[] {
+  if (/[|&;<>$`\n\r]/.test(raw)) {
+    throw new CloudTokenError(
+      "cloud_token_command_invalid",
+      "token command must be a program and arguments, not a shell pipeline",
+    );
+  }
+  const args: string[] = [];
+  let current = "";
+  let quote: "'" | "\"" | undefined;
+  for (const ch of raw) {
+    if (quote) {
+      if (ch === quote) quote = undefined;
+      else current += ch;
+      continue;
+    }
+    if (ch === "'" || ch === "\"") {
+      quote = ch;
+      continue;
+    }
+    if (ch === " " || ch === "\t") {
+      if (current.length > 0) {
+        args.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += ch;
+  }
+  if (quote) {
+    throw new CloudTokenError("cloud_token_command_invalid", "token command has an unclosed quote");
+  }
+  if (current.length > 0) args.push(current);
+  if (args.length === 0) {
+    throw new CloudTokenError("cloud_token_command_invalid", "token command is empty");
+  }
+  return args;
+}
+
+export function isCloudTokenEnvName(value: string): boolean {
+  return TOKEN_ENV_NAME.test(value);
+}
+
+/**
+ * Where this command should say the hub sits. A cloud binding is remote even when its
+ * URL is a loopback forward, but only for the URL the binding names. `KXM_SERVER_URL`
+ * pointing somewhere else keeps that URL's own scope.
+ */
+export function effectiveHubBindingScope(url: string, env: NodeJS.ProcessEnv = process.env): HubBindingScope {
+  try {
+    const binding = readHubBinding(env);
+    if (binding?.cloud) {
+      try {
+        if (validateHubUrl(url) === binding.url) return "remote";
+      } catch {
+        // An unparsable override is not the cloud binding.
+      }
+    }
+  } catch (error) {
+    if (!(error instanceof HubBindingError)) throw error;
+  }
+  return hubBindingScope(url);
+}
+
+/** Hub URL for a session: explicit env, else the binding, else the local default. */
+export function resolveHubServerUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = env.KXM_SERVER_URL?.trim();
+  if (fromEnv) return fromEnv.replace(/\/$/, "");
+  try {
+    const binding = readHubBinding(env);
+    if (binding?.url) return binding.url;
+  } catch (error) {
+    if (!(error instanceof HubBindingError)) throw error;
+  }
+  return "http://127.0.0.1:7331";
+}
+
+/**
+ * Resolve the token a cloud binding names. Never reads hub-env and never uses
+ * `KXM_AUTH_TOKEN` unless `tokenEnv` is that name. `tokenEnv` wins when it is non-empty;
+ * otherwise the command runs. The command is not cached.
+ */
+export function resolveCloudHubToken(binding: HubBindingRecord, env: NodeJS.ProcessEnv = process.env): string {
+  if (!binding.cloud) {
+    throw new CloudTokenError("cloud_token_missing", "cloud hub token is missing; the local hub-env token was not used");
+  }
+  if (binding.tokenEnv) {
+    const value = env[binding.tokenEnv]?.trim();
+    if (value) return value;
+  }
+  if (binding.tokenCommand) return runTokenCommand(binding.tokenCommand, env);
+  const source = binding.tokenEnv ? `${binding.tokenEnv} is unset or empty` : "no token source is configured";
+  throw new CloudTokenError(
+    "cloud_token_missing",
+    `cloud hub token is missing: ${source}; the local hub-env token was not used`,
+  );
+}
+
+function runTokenCommand(command: string, env: NodeJS.ProcessEnv): string {
+  const argv = splitTokenCommand(command);
+  const [program, ...args] = argv;
+  const result = spawnSync(program!, args, {
+    encoding: "utf8",
+    shell: false,
+    timeout: TOKEN_COMMAND_TIMEOUT_MS,
+    maxBuffer: TOKEN_COMMAND_MAX_BUFFER,
+    env,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    throw new CloudTokenError(
+      "cloud_token_command_failed",
+      "token command failed; the local hub-env token was not used",
+    );
+  }
+  const stdout = result.stdout ?? "";
+  if (stdout.trim().length === 0 || stdout.trim() !== stdout.trim().split(/\r?\n/)[0]) {
+    throw new CloudTokenError(
+      "cloud_token_command_failed",
+      "token command did not print a single token; the local hub-env token was not used",
+    );
+  }
+  return stdout.trim();
+}
+
 /** Loopback literals only; `0.0.0.0`, a LAN address or a hostname are all remote. */
 export function hubBindingScope(url: string): HubBindingScope {
   let host: string;
@@ -111,8 +261,11 @@ export function readHubBinding(env: NodeJS.ProcessEnv = process.env): HubBinding
   }
   const row = parsed as Record<string, unknown>;
   const keys = Object.keys(row);
+  const allowed = new Set(["schema", "url", "boundAt", "cloud", "tokenEnv", "tokenCommand"]);
+  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
   if (
-    keys.length !== 3
+    keys.some((key) => !allowed.has(key))
+    || (!cloudish && keys.length !== 3)
     || row.schema !== HUB_BINDING_SCHEMA
     || typeof row.url !== "string"
     || typeof row.boundAt !== "string"
@@ -126,7 +279,34 @@ export function readHubBinding(env: NodeJS.ProcessEnv = process.env): HubBinding
   } catch {
     throw new HubBindingError(`malformed hub binding at ${file}`);
   }
-  return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
+  if (!cloudish) return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
+  if (row.cloud !== true) throw new HubBindingError(`malformed hub binding at ${file}`);
+  let tokenEnv: string | undefined;
+  let tokenCommand: string | undefined;
+  if (row.tokenEnv !== undefined) {
+    if (typeof row.tokenEnv !== "string" || !isCloudTokenEnvName(row.tokenEnv)) {
+      throw new HubBindingError(`malformed hub binding at ${file}`);
+    }
+    tokenEnv = row.tokenEnv;
+  }
+  if (row.tokenCommand !== undefined) {
+    if (typeof row.tokenCommand !== "string") throw new HubBindingError(`malformed hub binding at ${file}`);
+    try {
+      splitTokenCommand(row.tokenCommand);
+    } catch {
+      throw new HubBindingError(`malformed hub binding at ${file}`);
+    }
+    tokenCommand = row.tokenCommand;
+  }
+  if (!tokenEnv && !tokenCommand) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return {
+    schema: HUB_BINDING_SCHEMA,
+    url,
+    boundAt: row.boundAt,
+    cloud: true,
+    ...(tokenEnv ? { tokenEnv } : {}),
+    ...(tokenCommand ? { tokenCommand } : {}),
+  };
 }
 
 export function writeHubBinding(record: HubBindingRecord, env: NodeJS.ProcessEnv = process.env): string {

package/plugins/kxm/src/hub-env.ts

@@ -2,6 +2,15 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { homedir } from "node:os";
 import { randomBytes } from "node:crypto";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import {
+  CloudTokenError,
+  HubBindingError,
+  hubBindingFile,
+  readHubBinding,
+  resolveCloudHubToken,
+  type HubBindingRecord,
+} from "./hub-binding.ts";
+import { defaultProjectName } from "./project-name.ts";
 
 export const HUB_ENV_SCHEMA = "kxm.hub-env.v1" as const;
 
@@ -210,6 +219,58 @@ export function resolveHubCredentials(options: ResolveHubCredentialsOptions = {}
  * only another project's token cannot authorise this one, and a guard that counts it as a
  * credential stores a binding that will fail exactly like the one it prevented.
  */
+/** A cloud binding, when this machine has one. A malformed binding fails closed. */
+function activeCloudBinding(env: NodeJS.ProcessEnv): HubBindingRecord | undefined {
+  try {
+    const binding = readHubBinding(env);
+    return binding?.cloud ? binding : undefined;
+  } catch (error) {
+    if (error instanceof HubBindingError) {
+      throw new HubEnvError(
+        `${error.message}; refusing to guess a credential — repair or remove ${hubBindingFile(env)}`,
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Credential for control-plane posts that are not agent sessions (context, degrade).
+ * Non-cloud keeps the historical rule: only the explicit `KXM_AUTH_TOKEN`, never hub-env.
+ * A cloud binding uses its named source and nothing else.
+ */
+export function resolveControlPlaneAuthToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const cloud = activeCloudBinding(env);
+  if (cloud) return resolveCloudHubToken(cloud, env);
+  return env.KXM_AUTH_TOKEN?.trim() || undefined;
+}
+
+/**
+ * Environment a pi or Claude session started through kxm should inherit.
+ * The project id comes from the shared resolver. A cloud binding adds
+ * `KXM_AUTH_TOKEN` in this object only — it is never written to the binding.
+ */
+export function agentSessionEnv(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  explicitProject?: string,
+): NodeJS.ProcessEnv {
+  const project = defaultProjectName(cwd, env, explicitProject);
+  const cloud = activeCloudBinding(env);
+  let serverUrl = env.KXM_SERVER_URL?.trim();
+  if (!serverUrl) {
+    try {
+      serverUrl = readHubBinding(env)?.url;
+    } catch (error) {
+      if (!(error instanceof HubBindingError)) throw error;
+    }
+  }
+  const session: NodeJS.ProcessEnv = { KXM_PROJECT: project };
+  if (serverUrl) session.KXM_SERVER_URL = serverUrl.replace(/\/$/, "");
+  if (cloud) session.KXM_AUTH_TOKEN = resolveCloudHubToken(cloud, env);
+  return session;
+}
+
 export function hasClientHubCredential(env: NodeJS.ProcessEnv = process.env, project?: string): boolean {
   if (env.KXM_AUTH_TOKEN?.trim()) return true;
   let record: HubEnvRecord | undefined;
@@ -229,6 +290,8 @@ export function hasClientHubCredential(env: NodeJS.ProcessEnv = process.env, pro
 }
 
 export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: string): string | undefined {
+  const cloud = activeCloudBinding(env);
+  if (cloud) return resolveCloudHubToken(cloud, env);
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
   const record = readHubEnvRecord(env);
@@ -245,6 +308,10 @@ export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: strin
  * malformed persisted record, same as `resolveClientHubAuthToken`.
  */
 export function resolveAgentHubAuthToken(env: NodeJS.ProcessEnv, project: string): string | undefined {
+  const cloud = activeCloudBinding(env);
+  // A cloud binding's token is the remote hub's credential. It is not this
+  // machine's hub-env admin token, which an agent must still never use.
+  if (cloud) return resolveCloudHubToken(cloud, env);
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
   const tokens = readHubEnvRecord(env)?.projectTokens;
@@ -277,7 +344,11 @@ export class AgentProjectTokenMissingError extends Error {
  * Throws on a malformed persisted record, same as `resolveClientHubAuthToken`.
  */
 export function resolveClientAdminAuthToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const cloud = activeCloudBinding(env);
+  if (cloud) return resolveCloudHubToken(cloud, env);
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
   return readHubEnvRecord(env)?.authToken?.trim() || undefined;
 }
+
+export { CloudTokenError };

package/plugins/kxm/src/mcp-server.ts

@@ -5,13 +5,14 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { HubClient, HubHttpError } from "./client.ts";
 import { resolveAgentHubAuthToken } from "./hub-env.ts";
+import { resolveHubServerUrl } from "./hub-binding.ts";
 import { defaultProjectName } from "./project-name.ts";
 import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } from "./commands.ts";
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.163";
+const VERSION = "0.7.165";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
@@ -51,7 +52,7 @@ function sessionIdentity(): { projectDir: string; project: string; serverUrl: st
   return {
     projectDir,
     project: defaultProjectName(projectDir, process.env),
-    serverUrl: process.env.KXM_SERVER_URL?.trim() || "http://127.0.0.1:7331",
+    serverUrl: resolveHubServerUrl(process.env),
   };
 }
 

package/plugins/kxm/src/project-name.ts

@@ -1,15 +1,21 @@
-import { readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
 
 /** Default project identity for a workspace.
  *
- * Precedence: `KXM_PROJECT` environment, then the workspace `package.json`
- * `name`, then the workspace directory name. The package.json read is
- * best-effort and never walks upward: a missing, malformed, or name-less
- * file falls through to the directory name. */
-export function defaultProjectName(cwd: string, env: NodeJS.ProcessEnv = process.env): string {
+ * Precedence: an explicit flag, then `KXM_PROJECT`, then the `id` in the
+ * nearest `.kxm/project.yaml` walking upward from `cwd`, then the workspace
+ * `package.json` `name` (that read never walks upward), then the directory
+ * name. A missing, malformed, or id-less project file falls through. A missing,
+ * malformed, or name-less package.json falls through to the directory name. */
+export function defaultProjectName(cwd: string, env: NodeJS.ProcessEnv = process.env, explicit?: string): string {
+  const fromExplicit = explicit?.trim();
+  if (fromExplicit) return fromExplicit;
   const fromEnv = env.KXM_PROJECT?.trim();
   if (fromEnv) return fromEnv;
+  const fromProject = readProjectYamlId(cwd);
+  if (fromProject) return fromProject;
   try {
     const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")) as { name?: unknown };
     if (typeof pkg.name === "string" && pkg.name.trim().length > 0) return pkg.name.trim();
@@ -18,3 +24,24 @@ export function defaultProjectName(cwd: string, env: NodeJS.ProcessEnv = process
   }
   return basename(cwd);
 }
+
+function readProjectYamlId(start: string): string | undefined {
+  let dir = resolve(start);
+  for (;;) {
+    const file = join(dir, ".kxm", "project.yaml");
+    if (existsSync(file)) {
+      try {
+        const doc = parseYaml(readFileSync(file, "utf8")) as { id?: unknown } | null;
+        if (doc && typeof doc === "object" && !Array.isArray(doc) && typeof doc.id === "string" && doc.id.trim()) {
+          return doc.id.trim();
+        }
+      } catch {
+        // Malformed YAML falls through to package.json of the original directory.
+      }
+      return undefined;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}

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

@@ -31,7 +31,7 @@ import { createKxmOneShotProducer } from "./oneshot-producer.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";
-import { readHubBinding } from "./hub-binding.ts";
+import { CloudTokenError, readHubBinding } from "./hub-binding.ts";
 import { resolveClientHubAuthToken } from "./hub-env.ts";
 import { createLogger } from "./logger.ts";
 import type { KxmOutboxRow, KxmOutboxStatus } from "./runtime-store.ts";
@@ -709,8 +709,14 @@ async function startKxmRuntimeSupervisorInner(
     // BEFORE any event can be appended — so the very first outbox row is
     // already scrubbed. Registering on the sync tick leaves a window where
     // appended events retain credentials.
-    const hubToken = resolveClientHubAuthToken(env, context.projectId);
-    if (hubToken) context.eventStore.syncRedactor.register(hubToken);
+    try {
+      const hubToken = resolveClientHubAuthToken(env, context.projectId);
+      if (hubToken) context.eventStore.syncRedactor.register(hubToken);
+    } catch (error) {
+      // A missing cloud token must not stop the local Runtime from opening.
+      // The sync tick records the same failure as blocked.
+      if (!(error instanceof CloudTokenError)) throw error;
+    }
     for (const key of Object.keys(env)) {
       if ((key.startsWith("KXM_") && (key.endsWith("_TOKEN") || key.endsWith("_KEY"))) || key.endsWith("_API_KEY") || key.endsWith("_SECRET")) {
         const value = env[key]?.trim();

package/plugins/kxm/src/tenant-status.ts

@@ -1,4 +1,4 @@
-import { hubBindingScope } from "./hub-binding.ts";
+import { CloudTokenError, hubBindingScope, type HubBindingScope } from "./hub-binding.ts";
 
 export const TENANT_STATUS_SCHEMA = "kxm.tenant-status.v1" as const;
 
@@ -163,6 +163,8 @@ export async function assembleTenantStatus(input: {
   /** Resolves the admin credential. May throw on a malformed persisted record; that
    * failure belongs to the hub source alone and never aborts the Runtime read. */
   resolveAdminToken: () => string | undefined;
+  /** When set, this is the scope already classified for `hubUrl` (cloud forwards included). */
+  bindingScope?: HubBindingScope | undefined;
   fetchImpl: typeof fetch;
   runtime: TenantStatusRuntimeReader;
   hubTimeoutMs?: number | undefined;
@@ -180,6 +182,11 @@ export async function assembleTenantStatus(input: {
     } catch (error) {
       // A malformed hub-env record is a configuration failure with a specific repair.
       // It belongs to this source; the Runtime read proceeds regardless.
+      // A cloud binding that cannot produce a token is not that failure: the local
+      // hub-env token was not consulted.
+      if (error instanceof CloudTokenError) {
+        return { state: "unavailable", observedAt: attemptedAt, reason: error.code };
+      }
       void error;
       return { state: "unavailable", observedAt: attemptedAt, reason: "hub_credential_unreadable" };
     }
@@ -331,7 +338,7 @@ export async function assembleTenantStatus(input: {
     project: input.project,
     generatedAt: at(),
     hubUrl: input.hubUrl,
-    bindingScope: hubBindingScope(input.hubUrl),
+    bindingScope: input.bindingScope ?? hubBindingScope(input.hubUrl),
     hub,
     runtime,
     runComparison,

package/scripts/build-runtime.mjs

@@ -47,9 +47,14 @@ for (const bundlePath of [
   "plugins/kxm/dist/server.js",
   "plugins/kxm/dist/runtime-supervisor.js",
   "plugins/kxm/dist/claude-hook.js",
+  // The MCP bundle is produced by build:mcp, then this script runs. It now
+  // imports the project-id resolver, which pulls in the YAML package. That
+  // package's dynamic require needs the same createRequire shim.
+  "plugins/kxm/dist/mcp-server.js",
 ]) {
   const bundled = readFileSync(bundlePath, "utf8");
   if (!bundled.startsWith(shebang)) throw new Error(`runtime bundle is missing its executable shebang: ${bundlePath}`);
+  if (bundled.includes("__kxmCreateRequire")) continue;
   writeFileSync(bundlePath, `${shebang}${createRequire}${bundled.slice(shebang.length)}`);
 }