@kontextmind/kxm 0.7.163 → 0.7.165

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

@@ -3,20 +3,26 @@ 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 { hasClientHubCredential, resolveClientHubAuthToken } from "../hub-env.ts";
+import { agentSessionEnv, hasClientHubCredential, HubEnvError, resolveClientHubAuthToken } from "../hub-env.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";
 import {
   HUB_BINDING_SCHEMA,
+  CloudTokenError,
   HubBindingError,
   hubBindingFile,
   probeHubHealth,
   hubBindingScope,
+  effectiveHubBindingScope,
+  isCloudTokenEnvName,
   readHubBinding,
   removeHubBinding,
+  splitTokenCommand,
   validateHubUrl,
   writeHubBinding,
+  resolveCloudHubToken,
+  type HubBindingRecord,
   type HubHealth,
 } from "../hub-binding.ts";
 import {
@@ -57,9 +63,13 @@ import {
   type Runtime,
 } from "./types.ts";
 
-export async function hubGet(url: string, fetchImpl: typeof fetch): Promise<{ ok: boolean; status: number; body: unknown }> {
+export async function hubGet(
+  url: string,
+  fetchImpl: typeof fetch,
+  headers?: Record<string, string>,
+): Promise<{ ok: boolean; status: number; body: unknown }> {
   try {
-    const response = await fetchImpl(url);
+    const response = await fetchImpl(url, headers ? { headers } : undefined);
     const text = redactSecrets((await response.text()).slice(0, 8_000));
     let body: unknown = text;
     try {
@@ -147,14 +157,29 @@ export async function refreshKxmUpdateNotice(
 }
 
 export async function cmdStatus(runtime: Runtime): Promise<number> {
-  const health = await hubGet(`${runtime.serverUrl}/health`, runtime.fetchImpl);
-  const ready = await hubGet(`${runtime.serverUrl}/ready`, runtime.fetchImpl);
+  let headers: Record<string, string> | undefined;
+  try {
+    const binding = readHubBinding(runtime.env);
+    if (binding?.cloud) {
+      headers = { authorization: `Bearer ${resolveCloudHubToken(binding, runtime.env)}` };
+    }
+  } catch (error) {
+    if (error instanceof CloudTokenError) {
+      print(runtime.io, runtime.json, { ok: false, command: "hub view", error: error.code, detail: error.message }, error.message);
+      return 2;
+    }
+    if (!(error instanceof HubBindingError)) throw error;
+  }
+  const health = await hubGet(`${runtime.serverUrl}/health`, runtime.fetchImpl, headers);
+  const ready = await hubGet(`${runtime.serverUrl}/ready`, runtime.fetchImpl, headers);
   // Scope on the status line deliberately: "attached across a network" and "attached on
   // this box" are otherwise indistinguishable, and only one of them ships a token.
   // 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.
-  const effectiveScope = hubBindingScope(runtime.serverUrl);
+  // A cloud binding is remote when the contacted URL is that binding, including a
+  // loopback SSH forward.
+  const effectiveScope = effectiveHubBindingScope(runtime.serverUrl, runtime.env);
   const overridden = Boolean(runtime.boundHubUrl && runtime.boundHubUrl !== runtime.serverUrl);
   const payload = {
     ok: health.ok && ready.ok,
@@ -192,7 +217,16 @@ export async function cmdDash(runtime: Runtime, options: { screen?: string | und
     return 2;
   }
   const project = defaultProjectName(runtime.dirs.workdir, runtime.env) || "project";
-  const authToken = resolveClientHubAuthToken(runtime.env, project);
+  let authToken: string | undefined;
+  try {
+    authToken = resolveClientHubAuthToken(runtime.env, project);
+  } catch (error) {
+    if (error instanceof CloudTokenError) {
+      print(runtime.io, runtime.json, { ok: false, command: "dash", error: error.code, detail: error.message }, error.message);
+      return 2;
+    }
+    throw error;
+  }
   return await runMeshTui({
     serverUrl: runtime.serverUrl,
     dataPath,
@@ -254,7 +288,13 @@ export function formatHubBindHealth(health: HubHealth): string {
 const HUB_BIND_UNAUTHENTICATED_HINT =
   "export KXM_AUTH_TOKEN (or point KXM_STATE_HOME at the hub-env record that already holds one), then re-run; the hub itself requires a token beyond loopback";
 
-export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<number> {
+export interface HubBindOptions {
+  cloud?: boolean | undefined;
+  tokenEnv?: string | undefined;
+  tokenCommand?: string | undefined;
+}
+
+export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubBindOptions = {}): Promise<number> {
   let url: string;
   try {
     url = validateHubUrl(rawUrl);
@@ -270,7 +310,51 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<numb
     }
     throw error;
   }
-  const scope = hubBindingScope(url);
+  const cloud = options.cloud === true;
+  const tokenEnv = options.tokenEnv?.trim() || undefined;
+  const tokenCommand = options.tokenCommand?.trim() || undefined;
+  if ((tokenEnv || 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",
+    );
+    return 2;
+  }
+  if (cloud && !tokenEnv && !tokenCommand) {
+    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",
+    );
+    return 2;
+  }
+  if (cloud && tokenEnv && !isCloudTokenEnvName(tokenEnv)) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command: "hub bind", error: "cloud_token_env_invalid", url },
+      "--token-env must be an environment variable name; no binding was written",
+    );
+    return 2;
+  }
+  if (cloud && tokenCommand) {
+    try {
+      splitTokenCommand(tokenCommand);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "hub bind", error: "cloud_token_command_invalid", url, detail },
+        `${detail}; no binding was written`,
+      );
+      return 2;
+    }
+  }
+  const scope = cloud ? "remote" : hubBindingScope(url);
   // Scope-scoped on purpose, and only for **this command**. A remote binding puts a
   // bearer on a network path, so it is refused when nothing can authenticate it; a
   // stored-but-unusable URL otherwise reads later like a network fault and gets debugged
@@ -280,7 +364,7 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<numb
   // fail `kxm peer list` on loopback. Narrowing the claim is the point; the first version
   // of this guard checked the record *before* the scope and refused loopback binds that had
   // always worked, which is a regression against behaviour predating this slice.
-  if (scope === "remote") {
+  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";
@@ -329,14 +413,29 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<numb
     }
   }
   const file = hubBindingFile(runtime.env);
+  const cloudFields = cloud
+    ? { cloud: true as const, ...(tokenEnv ? { tokenEnv } : {}), ...(tokenCommand ? { tokenCommand } : {}) }
+    : {};
+  const record: HubBindingRecord = {
+    schema: HUB_BINDING_SCHEMA,
+    url,
+    boundAt: new Date().toISOString(),
+    ...cloudFields,
+  };
+  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 }, `would bind hub ${url} (${scope})`);
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "hub bind", dryRun: true, url, scope, file, ...cloudFields },
+      `would bind hub ${url} (${scope})${cloudNote}`,
+    );
     return 0;
   }
-  writeHubBinding({ schema: HUB_BINDING_SCHEMA, url, boundAt: new Date().toISOString() }, runtime.env);
+  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 },
-    `bound hub ${url} · ${scope} · ${formatHubBindHealth(health)}${scope === "remote" ? " · token leaves this machine" : ""}`);
+  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, scope, file, health, probeMs, ...cloudFields },
+    `bound hub ${url} · ${scope} · ${formatHubBindHealth(health)}${cloud ? cloudNote : scope === "remote" ? " · token leaves this machine" : ""}`);
   return 0;
 }
 
@@ -383,7 +482,7 @@ export async function cmdWorker(runtime: Runtime, options: {
   freshStart?: boolean | undefined;
 }): Promise<number> {
   const name = options.name?.trim() || runtime.env.KXM_AGENT_NAME?.trim();
-  const project = options.project?.trim() || runtime.env.KXM_PROJECT?.trim();
+  const project = defaultProjectName(runtime.dirs.workdir, runtime.env, options.project);
   const model = options.model?.trim() || runtime.env.KXM_WORKER_MODEL?.trim();
   const fallbackModels = options.fallbackModels?.trim() || runtime.env.KXM_WORKER_FALLBACK_MODELS?.trim();
   const tools = options.tools?.trim() || runtime.env.KXM_WORKER_TOOLS?.trim();
@@ -392,10 +491,22 @@ export async function cmdWorker(runtime: Runtime, options: {
     runtime.io.stderr("worker --session-isolation must be workflow or off\n");
     return 2;
   }
+  let sessionEnv: NodeJS.ProcessEnv = { KXM_PROJECT: project };
+  if (!runtime.dryRun) {
+    try {
+      sessionEnv = agentSessionEnv(runtime.dirs.workdir, runtime.env, options.project);
+    } catch (error) {
+      if (error instanceof CloudTokenError || error instanceof HubEnvError) {
+        runtime.io.stderr(`${error.message}\n`);
+        return 2;
+      }
+      throw error;
+    }
+  }
   const extraEnv = {
     ...workspaceEnv(runtime),
+    ...sessionEnv,
     ...(name ? { KXM_AGENT_NAME: name } : {}),
-    ...(project ? { KXM_PROJECT: project } : {}),
     ...(model ? { KXM_WORKER_MODEL: model } : {}),
     ...(fallbackModels ? { KXM_WORKER_FALLBACK_MODELS: fallbackModels } : {}),
     ...(tools ? { KXM_WORKER_TOOLS: tools } : {}),
@@ -675,7 +786,7 @@ export async function cmdSessionBrief(runtime: Runtime, options: { status?: bool
       evidence: health === "unknown" ? "timeout" : "probed",
       online: health === "on",
       url: targetUrl,
-      scope: hubBindingScope(targetUrl),
+      scope: effectiveHubBindingScope(targetUrl, runtime.env),
     };
   } else {
     hub = { state: "off", evidence: "unconfigured", online: false };

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

@@ -29,6 +29,8 @@ import {
 import { kxmRuntimePaths, runtimeError } from "../runtime-store.ts";
 import { assembleTenantStatus, formatTenantStatus } from "../tenant-status.ts";
 import { resolveClientAdminAuthToken } from "../hub-env.ts";
+import { defaultProjectName } from "../project-name.ts";
+import { effectiveHubBindingScope } from "../hub-binding.ts";
 import {
   formatHarnessInventory,
   probeHarnessesAsync,
@@ -779,7 +781,7 @@ export async function cmdKxmRunList(runtime: Runtime): Promise<number> {
   }
 }
 
-export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
+export async function cmdTenantStatus(runtime: Runtime, options: { project?: string | undefined } = {}): Promise<number> {
   let projectRoot: string | undefined;
   let projectId: string;
   try {
@@ -789,7 +791,8 @@ export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
       return 1;
     }
     const bundle = loadKxmProject(projectRoot, {});
-    projectId = String(bundle.project.value.id);
+    const yamlProjectId = String(bundle.project.value.id);
+    projectId = defaultProjectName(runtime.cwd, runtime.env, options.project);
     const root = projectRoot;
 
     const payload = await assembleTenantStatus({
@@ -799,6 +802,7 @@ export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
       // and resolve it inside the hub source so a malformed persisted record degrades that
       // one source instead of aborting the Runtime read with it.
       resolveAdminToken: () => resolveClientAdminAuthToken(runtime.env),
+      bindingScope: effectiveHubBindingScope(runtime.serverUrl, runtime.env),
       fetchImpl: runtime.fetchImpl,
       runtime: {
         listRuns: async () => {
@@ -808,7 +812,7 @@ export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
           if (!handle) {
             throw runtimeError("runtime_supervisor_not_running", "runtime", "no live runtime supervisor on this box");
           }
-          const result = await kxmRuntimeRequest(handle, "GET", `/v1/projects/${encodeURIComponent(projectId)}/runs?projectRoot=${encodeURIComponent(root)}`);
+          const result = await kxmRuntimeRequest(handle, "GET", `/v1/projects/${encodeURIComponent(yamlProjectId)}/runs?projectRoot=${encodeURIComponent(root)}`);
           const runs = (result.runs ?? []) as Array<Record<string, unknown>>;
           return runs.map((run) => ({
             runId: String(run.runId ?? ""),

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

@@ -8,6 +8,7 @@ import { gateWorker, workerResult, type Worker, type WorkerOutcome } from "../en
 import { canonicalWorkflowEvidenceKey, type WorkflowEvidenceInput } from "../workflow.ts";
 import {
   HubBindingError,
+  effectiveHubBindingScope,
   hubBindingFile,
   readHubBinding,
 } from "../hub-binding.ts";
@@ -165,6 +166,11 @@ export function printWorker(
 }
 
 export function hostMode(runtime: Runtime): "local" | "hub" {
+  try {
+    if (effectiveHubBindingScope(runtime.serverUrl, runtime.env) === "remote") return "hub";
+  } catch {
+    // A malformed binding is classified from the URL below.
+  }
   try {
     const hostname = new URL(runtime.serverUrl).hostname;
     if (hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1") return "local";

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

@@ -37,6 +37,8 @@ import {
   type Runtime,
 } from "./types.ts";
 import { resolvePickItem, type PickCandidate } from "./roles.ts";
+import { CloudTokenError } from "../hub-binding.ts";
+import { resolveControlPlaneAuthToken } from "../hub-env.ts";
 
 const CLI_NAME = "kxm";
 
@@ -480,7 +482,16 @@ export async function cmdWorkflowStart(runtime: Runtime, definitionIdArg: string
 export async function cmdWorkflowDegrade(runtime: Runtime, runId: string, stageId: string, options: { requirement?: string | undefined; reason?: string | undefined }): Promise<number> {
   const requirementKey = options.requirement?.trim() ?? "";
   const reason = options.reason?.trim() ?? "";
-  const adminToken = runtime.env.KXM_AUTH_TOKEN?.trim();
+  let adminToken: string | undefined;
+  try {
+    adminToken = resolveControlPlaneAuthToken(runtime.env);
+  } catch (error) {
+    if (error instanceof CloudTokenError) {
+      runtime.io.stderr(`${error.message}\n`);
+      return 2;
+    }
+    throw error;
+  }
   if (!runId || !stageId || !requirementKey || !reason || !adminToken) {
     runtime.io.stderr("workflow degrade requires <runId> <stageId>, --requirement, --reason, and KXM_AUTH_TOKEN\n");
     return 2;

package/plugins/kxm/src/cli.ts

@@ -19,6 +19,7 @@ import { readInstalledKxmVersion } from "./kxm-update.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
 import { HubClient } from "./client.ts";
 import { AgentProjectTokenMissingError, resolveAgentHubAuthToken } from "./hub-env.ts";
+import { CloudTokenError } from "./hub-binding.ts";
 import { defaultProjectName } from "./project-name.ts";
 import {
   AGENT_COMMANDS_MAP,
@@ -310,6 +311,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 +328,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") {
@@ -388,6 +392,15 @@ async function dispatchAgentCliCommand(
       );
       return 2;
     }
+    if (error instanceof CloudTokenError) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, error: error.code, detail: message },
+        message,
+      );
+      return 2;
+    }
     print(runtime.io, runtime.json, { ok: false, error: "command_failed", detail: message }, `command failed: ${message}`);
     return 1;
   } finally {
@@ -649,8 +662,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 +830,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 +1341,11 @@ 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")
+    .action(async function hubBindAction(this: Command, url: string, options: { cloud?: boolean; tokenEnv?: string; tokenCommand?: 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")

package/plugins/kxm/src/extension.ts

@@ -7,6 +7,7 @@ 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 { CloudTokenError, resolveHubServerUrl } from "./hub-binding.ts";
 import { defaultProjectName } from "./project-name.ts";
 import { nousFactoryWork, type NousRegistrationReport } from "./nous-pi.ts";
 import {
@@ -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 = resolveHubServerUrl(process.env);
     let health = "unreachable";
     try {
       const response = await fetch(`${url}/health`);
@@ -676,7 +677,7 @@ 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 serverUrl = resolveHubServerUrl(process.env);
     const project = defaultProjectName(ctx.cwd, process.env);
     const name = process.env.KXM_AGENT_NAME ?? pi.getSessionName() ?? `pi-${process.pid}`;
     agentName = name;
@@ -710,7 +711,10 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
     try {
       hubAuthToken = resolveAgentHubAuthToken(process.env, project);
     } 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;
     }

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

@@ -133,6 +133,9 @@ 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: "" };
   }
 
   // 2. A live local claim means a hub (started any way) already owns this