@kontextmind/kxm 0.7.165 → 0.7.166

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.165",
+  "version": "0.7.166",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm-hub-ops/SKILL.md

@@ -46,7 +46,7 @@ the hub admin token or a project token.
 |---|---|---|
 | `kxm hub start` | Start the hub in the foreground | `--json` |
 | `kxm hub stop` | Request managed hub and worker shutdown | `--wait-ms <ms>` |
-| `kxm hub bind <url>` | Bind this machine to a running hub | http or https URL. `--cloud` with `--token-env` or `--token-command` for an SSH forward to loopback. The token is not stored |
+| `kxm hub bind <url>` | Bind this machine to a running hub and record the non-secret endpoint in `.kxm/config.yaml` | http or https URL. `--token-env` and `--key-op` for either mode. `--cloud` with `--token-env`, `--token-command`, or `--key-op` for an SSH forward to loopback. The token is not stored |
 | `kxm hub unbind` | Remove this machine's hub binding | `--json` |
 | `kxm restore <manifest>` | Replace this project's live stores from a verified backup manifest | `--all-projects`, `--json` |
 
@@ -60,19 +60,27 @@ kxm restore .kxm/backups/pre-upgrade/manifest.json
   `KXM_AUTH_TOKEN` is unset it generates a long random admin token once and
   persists it in `hub-env.json` (schema `kxm.hub-env.v1`, mode `0600`) under
   the user state root, then reuses it on every restart.
-- `KXM_PROJECT_TOKENS` must list every project's token. It replaces the saved
-  token map rather than merging with it, and the replacement is saved. When a
-  hub already serves other projects, build the full map with the merge
-  command in the KXM documentation's Claude Code quick start
+- `KXM_PROJECT_TOKENS` must list every project's token when it is set. It
+  replaces the saved token map rather than merging with it, and the
+  replacement is saved. The same map can instead live in `.kxm/config.yaml`
+  as `hub.projects`, with `op://` references or environment variable names.
+  That map is resolved in memory and is not saved. When a hub already serves
+  other projects, build the full map with the merge command in the KXM
+  documentation's Claude Code quick start
   (docs/start/quickstart-claude-code.md, section "Start the hub") before
   restarting the hub.
+- `kxm hub view` prints the mode, URL, project id, and key source. It does
+  not print the token. The project id is the flag, then `KXM_PROJECT`, then
+  `hub.local.project` or `hub.cloud.project`, then `.kxm/project.yaml`, then
+  the package name, then the directory name.
 - `kxm hub bind` to a remote (non-loopback) URL fails closed with
   `hub_bind_unauthenticated` unless a credential for the current project
   resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`.
 - `kxm hub bind --cloud` is the bind for a loopback SSH forward of a remote
   hub. It never falls back to this machine's hub-env token. Pass
-  `--token-env KXMD_HUB_TOKEN` or `--token-command "op read op://..."`.
-  See docs/operations.md, section "Cross-box peer attach".
+  `--token-env KXMD_HUB_TOKEN`, `--key-op op://Private/kxmd/project-token`,
+  or `--token-command "op read op://..."`. The non-secret fields are written
+  to `.kxm/config.yaml`. See docs/operations.md, section "Cross-box peer attach".
 - Hub PID claims record the wrapper and server child PID. A dead wrapper's
   claim is reclaimed automatically, an orphaned server is terminated first,
   and `kxm hub stop` recovers such orphans directly.

package/plugins/kxm/src/cli/hub.ts

@@ -3,7 +3,9 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 import { join, resolve } from "node:path";
 import { redactSecrets } from "../redact.ts";
 import { defaultProjectName } from "../project-name.ts";
-import { agentSessionEnv, hasClientHubCredential, HubEnvError, resolveClientHubAuthToken } from "../hub-env.ts";
+import { agentSessionEnv, hasClientHubCredential, HubEnvError, readHubEnvRecord, resolveClientHubAuthToken } from "../hub-env.ts";
+import { deleteKxmConfigValue, findConfigRoot, isHubOpReference, KxmHubConfigError, writeHubEndpoint } from "../config.ts";
+import { describeHubConnection, opReferenceFromTokenCommand, resolveProjectIdentity } from "../hub-identity.ts";
 import { agentWorker, type Worker } from "../envelope.ts";
 import { MESH_TUI_PANELS, runMeshTui, type MeshTuiPanel } from "../tui.ts";
 import { formatSessionBriefText, loadSessionBriefAsync, readCachedSessionBrief, type SessionHubStatus } from "../session-work.ts";
@@ -21,7 +23,6 @@ import {
   splitTokenCommand,
   validateHubUrl,
   writeHubBinding,
-  resolveCloudHubToken,
   type HubBindingRecord,
   type HubHealth,
 } from "../hub-binding.ts";
@@ -157,11 +158,21 @@ export async function refreshKxmUpdateNotice(
 }
 
 export async function cmdStatus(runtime: Runtime): Promise<number> {
+  const connection = describeHubConnection(runtime.dirs.workdir, runtime.env, {
+    hasSavedProjectToken: (project) => {
+      try {
+        const token = readHubEnvRecord(runtime.env)?.projectTokens?.[project];
+        return typeof token === "string" && token.trim().length > 0;
+      } catch {
+        return false;
+      }
+    },
+  });
   let headers: Record<string, string> | undefined;
   try {
-    const binding = readHubBinding(runtime.env);
-    if (binding?.cloud) {
-      headers = { authorization: `Bearer ${resolveCloudHubToken(binding, runtime.env)}` };
+    if (connection.mode === "cloud") {
+      const token = resolveClientHubAuthToken(runtime.env, connection.project, runtime.dirs.workdir);
+      if (token) headers = { authorization: `Bearer ${token}` };
     }
   } catch (error) {
     if (error instanceof CloudTokenError) {
@@ -177,19 +188,29 @@ export async function cmdStatus(runtime: Runtime): Promise<number> {
   // Scope is a property of the URL actually contacted, not of whichever file the
   // binding came from: KXM_SERVER_URL overrides the binding, and labelling the binding
   // while probing an override would report "loopback" about a remote request.
-  // A cloud binding is remote when the contacted URL is that binding, including a
+  // A cloud mode is remote when the contacted URL is that endpoint, including a
   // loopback SSH forward.
-  const effectiveScope = effectiveHubBindingScope(runtime.serverUrl, runtime.env);
-  const overridden = Boolean(runtime.boundHubUrl && runtime.boundHubUrl !== runtime.serverUrl);
+  const effectiveScope = connection.scope;
+  const overridden = connection.urlSource === "env";
+  const identity = {
+    mode: connection.mode,
+    modeSource: connection.modeSource,
+    url: connection.url,
+    urlSource: connection.urlSource,
+    project: connection.project,
+    projectSource: connection.source,
+    keySource: connection.keySource,
+  };
   const payload = {
     ok: health.ok && ready.ok,
     command: "hub view",
     target: { url: runtime.serverUrl, scope: effectiveScope, ...(overridden ? { source: "env" } : {}) },
+    identity,
     health: health.body,
     ready: ready.body,
   };
   print(runtime.io, runtime.json, payload,
-    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""}`);
+    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} · mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}`);
   return payload.ok ? 0 : 1;
 }
 
@@ -216,10 +237,10 @@ export async function cmdDash(runtime: Runtime, options: { screen?: string | und
     runtime.io.stderr("kxm dash does not support --json; use kxm hub view\n");
     return 2;
   }
-  const project = defaultProjectName(runtime.dirs.workdir, runtime.env) || "project";
+  const project = resolveProjectIdentity(runtime.dirs.workdir, runtime.env).project || "project";
   let authToken: string | undefined;
   try {
-    authToken = resolveClientHubAuthToken(runtime.env, project);
+    authToken = resolveClientHubAuthToken(runtime.env, project, runtime.dirs.workdir);
   } catch (error) {
     if (error instanceof CloudTokenError) {
       print(runtime.io, runtime.json, { ok: false, command: "dash", error: error.code, detail: error.message }, error.message);
@@ -292,6 +313,7 @@ export interface HubBindOptions {
   cloud?: boolean | undefined;
   tokenEnv?: string | undefined;
   tokenCommand?: string | undefined;
+  keyOp?: string | undefined;
 }
 
 export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubBindOptions = {}): Promise<number> {
@@ -313,25 +335,35 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubB
   const cloud = options.cloud === true;
   const tokenEnv = options.tokenEnv?.trim() || undefined;
   const tokenCommand = options.tokenCommand?.trim() || undefined;
-  if ((tokenEnv || tokenCommand) && !cloud) {
+  const keyOp = options.keyOp?.trim() || opReferenceFromTokenCommand(tokenCommand ?? "") || undefined;
+  if (options.keyOp?.trim() && !isHubOpReference(options.keyOp.trim())) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command: "hub bind", error: "hub_config_invalid", url },
+      "--key-op must be an op://vault/item/field reference, not a token; no binding was written",
+    );
+    return 2;
+  }
+  if (tokenCommand && !cloud) {
     print(
       runtime.io,
       runtime.json,
       { ok: false, command: "hub bind", error: "cloud_flag_required", url },
-      "--token-env and --token-command require --cloud; no binding was written",
+      "--token-command requires --cloud; no binding was written",
     );
     return 2;
   }
-  if (cloud && !tokenEnv && !tokenCommand) {
+  if (cloud && !tokenEnv && !tokenCommand && !keyOp) {
     print(
       runtime.io,
       runtime.json,
       { ok: false, command: "hub bind", error: "cloud_token_source_required", url },
-      "--cloud needs --token-env, --token-command, or both; the token is not stored in the binding",
+      "--cloud needs --token-env, --token-command, --key-op, or a combination; the token is not stored",
     );
     return 2;
   }
-  if (cloud && tokenEnv && !isCloudTokenEnvName(tokenEnv)) {
+  if (tokenEnv && !isCloudTokenEnvName(tokenEnv)) {
     print(
       runtime.io,
       runtime.json,
@@ -367,10 +399,10 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubB
   if (!cloud && scope === "remote") {
     // The project that will actually authenticate: a record holding only another
     // project's token cannot authorise this one.
-    const bindProject = defaultProjectName(runtime.dirs.workdir, runtime.env) || "project";
+    const bindProject = resolveProjectIdentity(runtime.dirs.workdir, runtime.env).project || "project";
     let credentialReady = false;
     try {
-      credentialReady = hasClientHubCredential(runtime.env, bindProject);
+      credentialReady = hasClientHubCredential(runtime.env, bindProject, runtime.dirs.workdir);
     } catch (error) {
       // A malformed record is a readable configuration failure, not an uncaught throw
       // past a user-facing entry point.
@@ -413,8 +445,9 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubB
     }
   }
   const file = hubBindingFile(runtime.env);
+  const bindingCommand = tokenCommand ?? (cloud && keyOp ? `op read ${keyOp}` : undefined);
   const cloudFields = cloud
-    ? { cloud: true as const, ...(tokenEnv ? { tokenEnv } : {}), ...(tokenCommand ? { tokenCommand } : {}) }
+    ? { cloud: true as const, ...(tokenEnv ? { tokenEnv } : {}), ...(bindingCommand ? { tokenCommand: bindingCommand } : {}) }
     : {};
   const record: HubBindingRecord = {
     schema: HUB_BINDING_SCHEMA,
@@ -422,19 +455,44 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubB
     boundAt: new Date().toISOString(),
     ...cloudFields,
   };
+  const identity = resolveProjectIdentity(runtime.dirs.workdir, runtime.env);
+  const configFile = join(findConfigRoot(runtime.dirs.workdir), ".kxm", "config.yaml");
+  const key = {
+    ...(keyOp ? { op: keyOp } : {}),
+    ...(tokenEnv ? { env: tokenEnv } : {}),
+  };
   const cloudNote = cloud ? " · token is not stored" : "";
   if (runtime.dryRun) {
     print(
       runtime.io,
       runtime.json,
-      { ok: true, command: "hub bind", dryRun: true, url, scope, file, ...cloudFields },
+      { ok: true, command: "hub bind", dryRun: true, url, scope, file, configFile, project: identity.project, ...cloudFields },
       `would bind hub ${url} (${scope})${cloudNote}`,
     );
     return 0;
   }
+  try {
+    writeHubEndpoint(runtime.dirs.workdir, {
+      mode: cloud ? "cloud" : "local",
+      url,
+      project: identity.project,
+      ...(key.op || key.env ? { key } : {}),
+    });
+  } catch (error) {
+    if (error instanceof KxmHubConfigError) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "hub bind", error: error.code, detail: error.message },
+        `${error.message}; no binding was written`,
+      );
+      return 2;
+    }
+    throw error;
+  }
   writeHubBinding({ ...record, boundAt: new Date().toISOString() }, runtime.env);
   const { health, probeMs } = await probeHubHealth(url, runtime.fetchImpl);
-  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, scope, file, health, probeMs, ...cloudFields },
+  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, scope, file, configFile, project: identity.project, health, probeMs, ...cloudFields },
     `bound hub ${url} · ${scope} · ${formatHubBindHealth(health)}${cloud ? cloudNote : scope === "remote" ? " · token leaves this machine" : ""}`);
   return 0;
 }
@@ -463,6 +521,7 @@ export async function cmdHubUnbind(runtime: Runtime): Promise<number> {
     return 1;
   }
   removeHubBinding(runtime.env);
+  deleteKxmConfigValue(findConfigRoot(runtime.dirs.workdir), "hub.mode");
   if (malformed) {
     print(runtime.io, runtime.json, { ok: true, command: "hub unbind", file }, "unbound hub (record was malformed)");
     return 0;

package/plugins/kxm/src/cli/types.ts

@@ -12,6 +12,7 @@ import {
   hubBindingFile,
   readHubBinding,
 } from "../hub-binding.ts";
+import { describeHubConnection } from "../hub-identity.ts";
 import type { InstallProbe } from "../kxm-install-kind.ts";
 
 export interface CliSpawnResult {
@@ -166,6 +167,11 @@ export function printWorker(
 }
 
 export function hostMode(runtime: Runtime): "local" | "hub" {
+  try {
+    if (describeHubConnection(runtime.cwd, runtime.env).scope === "remote") return "hub";
+  } catch {
+    // A malformed binding is classified from the URL below.
+  }
   try {
     if (effectiveHubBindingScope(runtime.serverUrl, runtime.env) === "remote") return "hub";
   } catch {
@@ -282,13 +288,14 @@ export function runtimeFrom(ctx: CliContext, command: Command): Runtime {
       throw error;
     }
   }
+  const connection = describeHubConnection(ctx.cwd, ctx.env);
   return {
     ...ctx,
     json: Boolean(opts.json),
     dryRun: Boolean(opts.dryRun),
     ...(opts.workspace === undefined ? {} : { workspaceFlag: opts.workspace }),
     dirs: workspaceDirs(ctx.cwd, opts.workspace, ctx.env),
-    serverUrl: envServerUrl || boundHubUrl || "http://127.0.0.1:7331",
+    serverUrl: connection.url || envServerUrl || boundHubUrl || "http://127.0.0.1:7331",
     ...(boundHubUrl ? { boundHubUrl } : {}),
     fetchImpl: ctx.io.fetchImpl ?? fetch,
   };

package/plugins/kxm/src/cli.ts

@@ -17,10 +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 { CloudTokenError } from "./hub-binding.ts";
-import { defaultProjectName } from "./project-name.ts";
+import { KxmHubConfigError } from "./config.ts";
+import { resolveProjectIdentity } from "./hub-identity.ts";
 import {
   AGENT_COMMANDS_MAP,
   enforceToolPolicy,
@@ -256,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,
@@ -387,11 +389,38 @@ 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,
@@ -1344,7 +1373,8 @@ function createProgram(ctx: CliContext, result: { code: number }, argv: readonly
     .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")
-    .action(async function hubBindAction(this: Command, url: string, options: { cloud?: boolean; tokenEnv?: string; tokenCommand?: string }) {
+    .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));
@@ -1562,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;
   }
 }