@kontextmind/kxm 0.7.164 → 0.7.166

package/plugins/kxm/src/cli.ts

@@ -17,9 +17,11 @@ import { fileURLToPath } from "node:url";
 import { Command, CommanderError } from "commander";
 import { readInstalledKxmVersion } from "./kxm-update.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
-import { HubClient } from "./client.ts";
+import { HubClient, HubHttpError } from "./client.ts";
 import { AgentProjectTokenMissingError, resolveAgentHubAuthToken } from "./hub-env.ts";
-import { defaultProjectName } from "./project-name.ts";
+import { CloudTokenError } from "./hub-binding.ts";
+import { KxmHubConfigError } from "./config.ts";
+import { resolveProjectIdentity } from "./hub-identity.ts";
 import {
   AGENT_COMMANDS_MAP,
   enforceToolPolicy,
@@ -255,13 +257,14 @@ function addGlobalOptions(command: Command): Command {
 
 async function ensureCliClient(runtime: Runtime): Promise<HubClient> {
   const serverUrl = runtime.serverUrl;
-  const project = defaultProjectName(runtime.cwd, runtime.env);
+  const identity = resolveProjectIdentity(runtime.cwd, runtime.env);
+  const project = identity.project;
   const name = runtime.env.KXM_AGENT_NAME?.trim() || `cli-${process.pid}`;
   const purpose = runtime.env.KXM_AGENT_PURPOSE?.trim() || "CLI agent client";
   // These commands act as a peer agent, so they take the agent credential: never the
   // persisted admin token, which the hub accepts for any project without its own token.
-  const authToken = resolveAgentHubAuthToken(runtime.env, project);
-  if (!authToken) throw new AgentProjectTokenMissingError(project);
+  const authToken = resolveAgentHubAuthToken(runtime.env, project, runtime.cwd);
+  if (!authToken) throw new AgentProjectTokenMissingError(identity);
   const client = new HubClient({
     serverUrl,
     name,
@@ -310,6 +313,9 @@ async function dispatchAgentCliCommand(
     return 2;
   }
 
+  const explicitProject = typeof rawArgs.project === "string" ? rawArgs.project.trim() : "";
+  if (explicitProject) runtime = { ...runtime, env: { ...runtime.env, KXM_PROJECT: explicitProject } };
+
   let args: Record<string, unknown> = {};
   if (typeof rawArgs.payload === "string" && rawArgs.payload.trim()) {
     try {
@@ -324,7 +330,7 @@ async function dispatchAgentCliCommand(
   }
 
   for (const [key, val] of Object.entries(rawArgs)) {
-    if (val !== undefined && key !== "payload") {
+    if (val !== undefined && key !== "payload" && key !== "project") {
       if (key === "timeoutMs" || key === "ttlMs" || key === "attempt") {
         args[key] = Number(val);
       } else if (key === "targets" && typeof val === "string") {
@@ -383,7 +389,43 @@ async function dispatchAgentCliCommand(
       print(
         runtime.io,
         runtime.json,
-        { ok: false, error: error.code, project: error.project, nextAction: "export_kxm_auth_token", detail: message },
+        {
+          ok: false,
+          error: error.code,
+          project: error.project,
+          projectSource: error.projectSource,
+          nextAction: "configure_hub_project",
+          hint: error.hint,
+          detail: message,
+        },
+        message,
+      );
+      return 2;
+    }
+    if (error instanceof HubHttpError && error.code === "project_token_missing") {
+      const identity = resolveProjectIdentity(runtime.cwd, runtime.env);
+      const missing = new AgentProjectTokenMissingError(identity);
+      print(
+        runtime.io,
+        runtime.json,
+        {
+          ok: false,
+          error: missing.code,
+          project: identity.project,
+          projectSource: identity.source,
+          nextAction: "configure_hub_project",
+          hint: missing.hint,
+          detail: missing.message,
+        },
+        missing.message,
+      );
+      return 2;
+    }
+    if (error instanceof CloudTokenError) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, error: error.code, detail: message },
         message,
       );
       return 2;
@@ -649,8 +691,9 @@ function createProgram(ctx: CliContext, result: { code: number }, argv: readonly
   const tenantCmd = addGlobalOptions(program.command("tenant").description("Composed tenant reads for machine clients (portal)"));
   tenantCmd.helpCommand("help", "Show tenant help");
   addGlobalOptions(tenantCmd.command("status").description("Read hub metadata and authoritative Runtime run state as one labeled view"))
-    .action(async function tenantStatusAction(this: Command) {
-      result.code = await cmdTenantStatus(runtimeFrom(ctx, this));
+    .option("--project <id>", "Hub project; overrides KXM_PROJECT for this command")
+    .action(async function tenantStatusAction(this: Command, options: { project?: string }) {
+      result.code = await cmdTenantStatus(runtimeFrom(ctx, this), options);
     });
 
   const pricesCmd = addGlobalOptions(program.command("prices").description("Stamp the local list-price catalog. Estimates stay unknown until today's stamp"));
@@ -816,6 +859,7 @@ function createProgram(ctx: CliContext, result: { code: number }, argv: readonly
   peer.helpCommand("help", "Show peer help");
 
   addGlobalOptions(peer.command("list").description("List peer agents in this project's hub pool with host and presence"))
+    .option("--project <id>", "Hub project; overrides KXM_PROJECT for this command")
     .option("--include-offline", "Also list registered peers whose hub lease has expired")
     .option("--payload <json>", "JSON payload")
     .action(async function peerListAction(this: Command, opts?: Record<string, unknown>) {
@@ -1326,8 +1370,12 @@ function createProgram(ctx: CliContext, result: { code: number }, argv: readonly
       result.code = await cmdStop(runtimeFrom(ctx, this), options.waitMs);
     });
   addGlobalOptions(hub.command("bind").description("Bind this machine to a running hub").argument("<url>", "Hub base URL (http or https)"))
-    .action(async function hubBindAction(this: Command, url: string) {
-      result.code = await cmdHubBind(runtimeFrom(ctx, this), url);
+    .option("--cloud", "Mark the hub remote even when the URL is a loopback forward")
+    .option("--token-env <name>", "Environment variable that holds the hub token; the token is not stored")
+    .option("--token-command <command>", "Program that prints the hub token; the token is not stored")
+    .option("--key-op <ref>", "op:// reference for the hub token; resolved with op read, never stored")
+    .action(async function hubBindAction(this: Command, url: string, options: { cloud?: boolean; tokenEnv?: string; tokenCommand?: string; keyOp?: string }) {
+      result.code = await cmdHubBind(runtimeFrom(ctx, this), url, options);
     });
   addGlobalOptions(hub.command("unbind").description("Remove this machine's hub binding")).action(bind(cmdHubUnbind));
   addGlobalOptions(program.command("dash").description("Live screens for headless agents, tasks, workflows, and plans")
@@ -1544,6 +1592,10 @@ export async function runCli(
   } catch (error) {
     if (error instanceof CommanderError) return mapCommanderError(error, argv, program, io);
     if (error instanceof DryRunRefused) return error.code;
+    if (error instanceof KxmHubConfigError) {
+      print(io, hasJsonFlag(argv), { ok: false, error: error.code, detail: error.message }, error.message);
+      return 2;
+    }
     throw error;
   }
 }

package/plugins/kxm/src/config.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { tmpdir, homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { parse, stringify } from "yaml";
 import { redactSecrets } from "./redact.ts";
@@ -47,10 +47,55 @@ export interface KxmSyncTrackerConfig {
 
 export type KxmHubAutoStart = "off" | "background";
 
+export type KxmHubMode = "local" | "cloud";
+
+/** A secret reference. `op` is an `op://` reference resolved with `op read` at
+ * use time. `env` is an environment variable name. Neither field holds a token. */
+export interface HubKeyRef {
+  op?: string;
+  env?: string;
+}
+
+/** One hub endpoint. `project` is the id presented to that hub. `key` is a
+ * reference, never a literal token. */
+export interface HubEndpointConfig {
+  url?: string;
+  project?: string;
+  key?: HubKeyRef;
+}
+
 export interface KxmHubConfig {
   /** Pi extension hub startup: `background` starts a detached hub when no
    * healthy bound hub or live local claim exists; `off` never starts one. */
   autoStart: KxmHubAutoStart;
+  /** Which endpoint is in effect. Unset means local unless a cloud binding says otherwise. */
+  mode?: KxmHubMode;
+  local?: HubEndpointConfig;
+  cloud?: HubEndpointConfig;
+  /** Hub-process project id to key reference. Resolved in memory; never persisted. */
+  projects?: Record<string, HubKeyRef>;
+}
+
+/** A hub config value is a token, or a key reference that is not an `op://` ref or an env var name. */
+export class KxmHubConfigError extends Error {
+  readonly code = "hub_config_invalid";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "KxmHubConfigError";
+  }
+}
+
+const HUB_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const HUB_OP_REF = /^op:\/\/\S+\/\S+\/\S+$/;
+const LITERAL_SECRET_KEY = /^(token|secret|password|authToken|auth_token|apiKey|api_key|api_token|bearer|credential|access_token)$/i;
+
+export function isHubKeyEnvName(value: string): boolean {
+  return HUB_ENV_NAME.test(value);
+}
+
+export function isHubOpReference(value: string): boolean {
+  return HUB_OP_REF.test(value);
 }
 
 export type ImprovementPromotionPolicy = "manual_pr" | "critic_quorum" | "auto_threshold";
@@ -191,11 +236,174 @@ function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<
   return result as T;
 }
 
+function literalSecretMessage(path: string): string {
+  return `refusing literal hub token at ${path}: store an op:// reference (key.op) or an environment variable name (key.env), never the token`;
+}
+
+function rejectLiteralHubSecrets(value: unknown, path: string): void {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => rejectLiteralHubSecrets(item, `${path}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    const childPath = `${path}.${key}`;
+    if (typeof child === "string" && (key === "key" || LITERAL_SECRET_KEY.test(key))) {
+      throw new KxmHubConfigError(literalSecretMessage(childPath));
+    }
+    if (child && typeof child === "object") rejectLiteralHubSecrets(child, childPath);
+  }
+}
+
+function parseKeyRef(raw: unknown, path: string): HubKeyRef | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw === "string") throw new KxmHubConfigError(literalSecretMessage(path));
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new KxmHubConfigError(`${path} must be a key reference with op and/or env, never a token`);
+  }
+  const row = raw as Record<string, unknown>;
+  for (const key of Object.keys(row)) {
+    if (key !== "op" && key !== "env") {
+      throw new KxmHubConfigError(literalSecretMessage(`${path}.${key}`));
+    }
+  }
+  const ref: HubKeyRef = {};
+  if (row.op !== undefined) {
+    if (typeof row.op !== "string" || !isHubOpReference(row.op)) {
+      throw new KxmHubConfigError(`${path}.op must be an op://vault/item/field reference, not a token`);
+    }
+    ref.op = row.op;
+  }
+  if (row.env !== undefined) {
+    if (typeof row.env !== "string" || !isHubKeyEnvName(row.env)) {
+      throw new KxmHubConfigError(`${path}.env must be an environment variable name, not a token`);
+    }
+    ref.env = row.env;
+  }
+  if (!ref.op && !ref.env) throw new KxmHubConfigError(`${path} needs key.op, key.env, or both`);
+  return ref;
+}
+
+function parseEndpoint(raw: unknown, path: string): HubEndpointConfig | undefined {
+  if (raw === undefined) return undefined;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new KxmHubConfigError(`${path} must be an object with url, project, and key`);
+  }
+  const row = raw as Record<string, unknown>;
+  const endpoint: HubEndpointConfig = {};
+  if (row.url !== undefined) {
+    if (typeof row.url !== "string" || !isHubUrl(row.url)) {
+      throw new KxmHubConfigError(`${path}.url must be an http or https URL without credentials, query, or fragment`);
+    }
+    endpoint.url = row.url.replace(/\/$/, "");
+  }
+  if (row.project !== undefined) {
+    if (typeof row.project !== "string" || !isHubProjectId(row.project)) {
+      throw new KxmHubConfigError(`${path}.project must be a single-line project id, not a token`);
+    }
+    endpoint.project = row.project.trim();
+  }
+  const key = parseKeyRef(row.key, `${path}.key`);
+  if (key) endpoint.key = key;
+  for (const name of Object.keys(row)) {
+    if (name !== "url" && name !== "project" && name !== "key") {
+      if (typeof row[name] === "string") throw new KxmHubConfigError(literalSecretMessage(`${path}.${name}`));
+      throw new KxmHubConfigError(`${path}.${name} is not a hub endpoint field`);
+    }
+  }
+  return endpoint;
+}
+
+function isHubUrl(raw: string): boolean {
+  try {
+    const parsed = new URL(raw);
+    return (parsed.protocol === "http:" || parsed.protocol === "https:")
+      && parsed.username === ""
+      && parsed.password === ""
+      && parsed.search === ""
+      && parsed.hash === ""
+      && !raw.includes("?")
+      && !raw.includes("#");
+  } catch {
+    return false;
+  }
+}
+
+function isHubProjectId(raw: string): boolean {
+  const value = raw.trim();
+  return value.length > 0 && value.length <= 200 && !/[\s\r\n]/.test(value);
+}
+
+function parseProjectMap(raw: unknown): Record<string, HubKeyRef> | undefined {
+  if (raw === undefined) return undefined;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new KxmHubConfigError("hub.projects must be a map of project id to key reference, never a token");
+  }
+  const projects: Record<string, HubKeyRef> = {};
+  for (const [project, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!isHubProjectId(project)) {
+      throw new KxmHubConfigError(`hub.projects key ${JSON.stringify(project)} must be a project id, not a token`);
+    }
+    const ref = parseKeyRef(value, `hub.projects.${project}`);
+    if (!ref) throw new KxmHubConfigError(`hub.projects.${project} needs an op:// reference or an environment variable name`);
+    projects[project.trim()] = ref;
+  }
+  return projects;
+}
+
 /** Unknown `hub.autoStart` values fail closed to the default so a config typo
- * never silently changes hub startup behavior. */
+ * never silently changes hub startup behavior. Literal tokens under `hub` are
+ * refused. Key references stay unresolved. */
 function normalizeHubConfig(raw: unknown): KxmHubConfig {
   const autoStart = (raw as { autoStart?: unknown } | undefined)?.autoStart;
-  return { autoStart: autoStart === "off" || autoStart === "background" ? autoStart : DEFAULT_KXM_CONFIG.hub.autoStart };
+  const hub: KxmHubConfig = {
+    autoStart: autoStart === "off" || autoStart === "background" ? autoStart : DEFAULT_KXM_CONFIG.hub.autoStart,
+  };
+  if (raw === undefined) return hub;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new KxmHubConfigError("hub must be an object");
+  }
+  rejectLiteralHubSecrets(raw, "hub");
+  const row = raw as Record<string, unknown>;
+  if (row.mode !== undefined) {
+    if (row.mode !== "local" && row.mode !== "cloud") {
+      throw new KxmHubConfigError("hub.mode must be local or cloud");
+    }
+    hub.mode = row.mode;
+  }
+  const local = parseEndpoint(row.local, "hub.local");
+  const cloud = parseEndpoint(row.cloud, "hub.cloud");
+  const projects = parseProjectMap(row.projects);
+  if (local) hub.local = local;
+  if (cloud) hub.cloud = cloud;
+  if (projects && Object.keys(projects).length > 0) hub.projects = projects;
+  return hub;
+}
+
+/** Directory that holds this checkout's `.kxm/` config: the nearest
+ * `project.yaml` or `config.yaml`, otherwise `start`. */
+export function findConfigRoot(start: string): string {
+  let dir = resolve(start);
+  for (;;) {
+    if (existsSync(join(dir, ".kxm", "project.yaml")) || existsSync(join(dir, ".kxm", "config.yaml"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return resolve(start);
+    dir = parent;
+  }
+}
+
+/** User config directory for this env. A partial env (tests, a command env
+ * that is not the process env) does not read `~/.config/kxm`. */
+export function userConfigDirForEnv(env: NodeJS.ProcessEnv): string | undefined {
+  const explicit = env.KXM_USER_CONFIG_DIR?.trim();
+  if (explicit) return explicit;
+  if (env === process.env) return undefined;
+  return join(tmpdir(), "kxm-no-user-config");
+}
+
+export function loadHubSettings(start: string, env: NodeJS.ProcessEnv = process.env): KxmHubConfig {
+  const userConfigDir = userConfigDirForEnv(env);
+  return loadKxmConfig(findConfigRoot(start), userConfigDir === undefined ? {} : { userConfigDir }).hub;
 }
 
 function recordOf(raw: unknown): Record<string, unknown> {
@@ -352,10 +560,45 @@ export function setKxmConfigValue(
     cursor = cursor[p] as Record<string, unknown>;
   }
   cursor[parts[parts.length - 1]!] = value;
+  if (parts[0] === "hub") normalizeHubConfig(existing.hub);
   if (!options.dryRun) writeConfigFile(targetFile, existing);
   return { file: targetFile };
 }
 
+/** Record the non-secret parts of a hub bind: mode, URL, project id, and key
+ * reference. The resolved token is never written. */
+export function writeHubEndpoint(
+  start: string,
+  endpoint: { mode: KxmHubMode; url: string; project: string; key?: HubKeyRef },
+): { file: string } {
+  if (!isHubUrl(endpoint.url)) {
+    throw new KxmHubConfigError("hub url must be an http or https URL without credentials, query, or fragment");
+  }
+  if (!isHubProjectId(endpoint.project)) {
+    throw new KxmHubConfigError("hub project id must be a single-line project id, not a token");
+  }
+  if (endpoint.key) parseKeyRef(endpoint.key, `hub.${endpoint.mode}.key`);
+  const root = findConfigRoot(start);
+  const file = join(root, ".kxm", "config.yaml");
+  const existing = readConfigFile(file);
+  const hub = recordOf(existing.hub);
+  const current = recordOf(hub[endpoint.mode]);
+  current.url = endpoint.url.replace(/\/$/, "");
+  current.project = endpoint.project.trim();
+  if (endpoint.key && (endpoint.key.op || endpoint.key.env)) {
+    const key = recordOf(current.key);
+    if (endpoint.key.op) key.op = endpoint.key.op;
+    if (endpoint.key.env) key.env = endpoint.key.env;
+    current.key = key;
+  }
+  hub[endpoint.mode] = current;
+  hub.mode = endpoint.mode;
+  existing.hub = hub;
+  normalizeHubConfig(hub);
+  writeConfigFile(file, existing);
+  return { file };
+}
+
 /**
  * Remove a key so the next scope, then the built-in default, applies.
  *

package/plugins/kxm/src/extension.ts

@@ -7,7 +7,8 @@ import { HubClient, HubHttpError } from "./client.ts";
 import { loadKxmConfig } from "./config.ts";
 import { ensureHubRunning, hubAutoStartMode } from "./hub-autostart.ts";
 import { AgentProjectTokenMissingError, resolveAgentHubAuthToken } from "./hub-env.ts";
-import { defaultProjectName } from "./project-name.ts";
+import { CloudTokenError } from "./hub-binding.ts";
+import { describeHubConnection, resolveProjectIdentity } from "./hub-identity.ts";
 import { nousFactoryWork, type NousRegistrationReport } from "./nous-pi.ts";
 import {
   antigravityRegistrationNotice,
@@ -346,7 +347,7 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
   }
 
   async function showKxmHub(ctx: { ui: { notify: (message: string, type: "info" | "warning" | "error") => void } }): Promise<void> {
-    const url = (process.env.KXM_SERVER_URL ?? "http://127.0.0.1:7331").replace(/\/$/, "");
+    const url = describeHubConnection(process.cwd(), process.env).url;
     let health = "unreachable";
     try {
       const response = await fetch(`${url}/health`);
@@ -676,8 +677,9 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
       return;
     }
     currentPiSessionId = ctx.sessionManager?.getSessionId();
-    const serverUrl = process.env.KXM_SERVER_URL ?? "http://127.0.0.1:7331";
-    const project = defaultProjectName(ctx.cwd, process.env);
+    const identity = resolveProjectIdentity(ctx.cwd, process.env);
+    const serverUrl = describeHubConnection(ctx.cwd, process.env).url;
+    const project = identity.project;
     const name = process.env.KXM_AGENT_NAME ?? pi.getSessionName() ?? `pi-${process.pid}`;
     agentName = name;
     projectName = project;
@@ -708,14 +710,17 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
     // stand in for a project token.
     let hubAuthToken: string | undefined;
     try {
-      hubAuthToken = resolveAgentHubAuthToken(process.env, project);
+      hubAuthToken = resolveAgentHubAuthToken(process.env, project, ctx.cwd);
     } catch (error) {
-      ctx.ui.notify(`kxm could not read persisted hub credentials: ${error instanceof Error ? error.message : String(error)}`, "error");
+      const detail = error instanceof CloudTokenError
+        ? error.message
+        : `kxm could not read persisted hub credentials: ${error instanceof Error ? error.message : String(error)}`;
+      ctx.ui.notify(detail, "error");
       await applySessionChrome(ctx, event, true);
       return;
     }
     if (!hubAuthToken) {
-      ctx.ui.notify(new AgentProjectTokenMissingError(project).message, "error");
+      ctx.ui.notify(new AgentProjectTokenMissingError(identity).message, "error");
       await applySessionChrome(ctx, event, true);
       return;
     }

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

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { probeHubHealth, readHubBinding } from "./hub-binding.ts";
+import { describeHubConnection } from "./hub-identity.ts";
 import { resolveHubCredentials } from "./hub-env.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
 import { redactSecrets } from "./redact.ts";
@@ -133,6 +134,28 @@ export async function ensureHubRunning(options: EnsureHubOptions): Promise<Ensur
   if (binding) {
     const { health } = await probeHubHealth(binding.url, fetchImpl);
     if (health === "on") return { status: "bound-healthy", url: binding.url };
+    // A cloud binding names a remote hub. A dead forward must not start a local hub
+    // that would then authenticate with this machine's hub-env token.
+    if (binding.cloud) return { status: "failed", reason: "cloud_hub_unreachable", logPath: "" };
+  }
+
+  // A cloud endpoint in config is the same rule when no cloud binding is on disk:
+  // a dead forward must not start a local hub.
+  if (!binding?.cloud) {
+    try {
+      const connection = describeHubConnection(options.cwd, env);
+      if (connection.mode === "cloud") {
+        const { health } = await probeHubHealth(connection.url, fetchImpl);
+        if (health === "on") return { status: "bound-healthy", url: connection.url };
+        return { status: "failed", reason: "cloud_hub_unreachable", logPath: "" };
+      }
+    } catch (error) {
+      return {
+        status: "failed",
+        reason: error instanceof Error ? error.message : "hub_config_invalid",
+        logPath: "",
+      };
+    }
   }
 
   // 2. A live local claim means a hub (started any way) already owns this