@kontextmind/kxm 0.7.54 → 0.7.57

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

@@ -16,11 +16,14 @@ import { diffKxmProjectAgainstRevision, formatKxmPermissionDiff } from "../permi
 import { readKxmLocalBindings, kxmUserStateRoot } from "../bindings.ts";
 import { loadKxmProject } from "../project-config.ts";
 import {
+  attachKxmSupervisor,
   ensureKxmSupervisor,
   kxmRuntimeRequest,
   kxmSupervisorStatus,
 } from "../runtime-supervisor.ts";
-import { kxmRuntimePaths } from "../runtime-store.ts";
+import { kxmRuntimePaths, runtimeError } from "../runtime-store.ts";
+import { assembleTenantStatus, formatTenantStatus } from "../tenant-status.ts";
+import { resolveClientAdminAuthToken } from "../hub-env.ts";
 import {
   formatHarnessInventory,
   probeHarnessesAsync,
@@ -568,12 +571,14 @@ export async function cmdKxmRunList(runtime: Runtime): Promise<number> {
     const projectId = String(bundle.project.value.id);
     const supervisor = await ensureKxmSupervisor({ env: runtime.env });
     const result = await kxmRuntimeRequest(supervisor, "GET", `/v1/projects/${encodeURIComponent(projectId)}/runs?projectRoot=${encodeURIComponent(projectRoot)}`);
-    const runs = (result.runs ?? []) as Array<{ runId: string; status: string; workflowId: string; createdAt: string }>;
+    const runs = (result.runs ?? []) as Array<{ runId: string; status: string; workflowId: string; createdAt: string; projectionError?: string }>;
     print(
       runtime.io,
       runtime.json,
       { ok: true, command: "runs list", runs },
-      runs.length === 0 ? "no runs" : runs.map((run) => `${run.runId}  ${run.status}  ${run.workflowId}  ${run.createdAt}`).join("\n"),
+      runs.length === 0
+        ? "no runs"
+        : runs.map((run) => `${run.runId}  ${run.status}  ${run.workflowId}  ${run.createdAt}${run.projectionError ? `  [state unverified: ${run.projectionError}]` : ""}`).join("\n"),
     );
     return 0;
   } catch (error) {
@@ -586,6 +591,72 @@ export async function cmdKxmRunList(runtime: Runtime): Promise<number> {
   }
 }
 
+export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
+  let projectRoot: string | undefined;
+  let projectId: string;
+  try {
+    projectRoot = discoverKxmProjectRoot(runtime.cwd) ?? undefined;
+    if (!projectRoot) {
+      print(runtime.io, runtime.json, { ok: false, command: "tenant status", error: "project_required" }, "kxm tenant status requires a KXM project (run kxm init first)");
+      return 1;
+    }
+    const bundle = loadKxmProject(projectRoot, {});
+    projectId = String(bundle.project.value.id);
+    const root = projectRoot;
+
+    const payload = await assembleTenantStatus({
+      project: projectId,
+      hubUrl: runtime.serverUrl,
+      // Admin-scoped route: resolve the admin credential only (a project token would 401),
+      // 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),
+      fetchImpl: runtime.fetchImpl,
+      runtime: {
+        listRuns: async () => {
+          // Attach only: a status read must never conjure a supervisor. "Nothing is
+          // running" is an answer the portal can render, not a condition to repair.
+          const handle = await attachKxmSupervisor({ env: runtime.env });
+          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 runs = (result.runs ?? []) as Array<Record<string, unknown>>;
+          return runs.map((run) => ({
+            runId: String(run.runId ?? ""),
+            status: String(run.status ?? "unknown"),
+            homeRuntimeId: String(run.homeRuntimeId ?? ""),
+            ...(typeof run.workflowId === "string" ? { workflowId: run.workflowId } : {}),
+            ...(typeof run.createdAt === "string" ? { createdAt: run.createdAt } : {}),
+            ...(typeof run.updatedAt === "string" ? { updatedAt: run.updatedAt } : {}),
+            ...(typeof run.projectionError === "string" ? { projectionError: run.projectionError } : {}),
+            source: (typeof run.projectionError === "string" ? "runtime-cached" : "runtime-authoritative") as "runtime-cached" | "runtime-authoritative",
+          }));
+        },
+      },
+    });
+
+    if (payload.hub.state !== "ok" && payload.runtime.state !== "ok") {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "tenant status", error: "tenant_status_no_source", payload },
+        `neither source could be read: hub ${payload.hub.reason ?? "unknown"}, runtime ${payload.runtime.reason ?? "unknown"}`,
+      );
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: true, command: "tenant status", ...payload }, formatTenantStatus(payload));
+    return 0;
+  } catch (error) {
+    if (error instanceof KxmConfigError) {
+      print(runtime.io, runtime.json, { ok: false, command: "tenant status", error: "tenant_status_failed", issues: error.issues }, `tenant status failed: ${error.message}`);
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "tenant status", error: "tenant_status_io_failed" }, "tenant status failed because a local operation did not complete");
+    return 1;
+  }
+}
+
 export async function cmdHarnessList(runtime: Runtime): Promise<number> {
   const inventory = await probeHarnessesAsync({ env: runtime.env });
   print(runtime.io, runtime.json, { ok: true, command: "harness list", ...inventory }, formatHarnessInventory(inventory));

package/plugins/kxm/src/cli.ts

@@ -107,6 +107,7 @@ cmdBackup,
   cmdKxmRunReceipt,
   cmdKxmRunCancel,
   cmdKxmRunList,
+  cmdTenantStatus,
   cmdHarnessList,
   cmdRouteChange,
   cmdModelsScreen,
@@ -395,6 +396,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdKxmRunList(runtimeFrom(ctx, this));
     });
 
+  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));
+    });
+
   const modelsCmd = addGlobalOptions(program.command("models").description("Manage model catalogs, roles, and route state"));
   modelsCmd.action(async function modelsScreenAction(this: Command) { result.code = await cmdModelsScreen(runtimeFrom(ctx, this)); });
   modelsCmd.helpCommand("help", "Show models help");

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

@@ -234,3 +234,16 @@ export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: strin
   const record = readHubEnvRecord(env);
   return record?.projectTokens?.[project]?.trim() || record?.authToken?.trim() || undefined;
 }
+
+/**
+ * Admin-scoped hub reads (`/v1/ops/snapshot`, …) are rejected with 401 by a project token,
+ * so this variant resolves the admin credential only: explicit `KXM_AUTH_TOKEN`, else the
+ * persisted record's admin token. It never falls back to a project token the route would
+ * refuse — handing the portal a 401 dressed as "configured" is worse than handing it none.
+ * Throws on a malformed persisted record, same as `resolveClientHubAuthToken`.
+ */
+export function resolveClientAdminAuthToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const envToken = env.KXM_AUTH_TOKEN?.trim();
+  if (envToken) return envToken;
+  return readHubEnvRecord(env)?.authToken?.trim() || undefined;
+}

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

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.54";
+const VERSION = "0.7.57";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/pi-producer.ts

@@ -82,20 +82,62 @@ function extractText(content: unknown): string {
   return "";
 }
 
-function determineOutcome(text: string, allowedOutcomes: readonly string[]): string {
-  const normalized = text.trim();
-  const jsonMatch = /"outcome"\s*:\s*"([^"]+)"/.exec(normalized);
-  if (jsonMatch && allowedOutcomes.includes(jsonMatch[1]!)) {
-    return jsonMatch[1]!;
+function asJsonObject(text: string): Record<string, unknown> | undefined {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : undefined;
+  } catch {
+    return undefined;
   }
-  for (const outcome of allowedOutcomes) {
-    const regex = new RegExp(`\\b${outcome}\\b`, "i");
-    if (regex.test(normalized)) {
-      return outcome;
-    }
+}
+
+function outcomeField(value: Record<string, unknown>): string | undefined {
+  const outcome = value.outcome;
+  return typeof outcome === "string" ? outcome : undefined;
+}
+
+/**
+ * The result a reply actually declares, or `undefined` when it declares none.
+ *
+ * Two shapes count: the whole reply is one JSON object, or a **standalone** result object on a
+ * line of its own — and when there is more than one of those, the **last** one wins, because
+ * that is where a reply puts its answer after showing an example. If anything in the tail after
+ * that declaration still looks like an outcome key, the reply is **ambiguous and settles
+ * `failed`**. What is deliberately not accepted: an outcome *word* anywhere in prose, and an
+ * object embedded mid-sentence, so
+ * `Example: {"outcome": "passed"}. Actual result: {"outcome": "failed"}` declares nothing at
+ * all and settles as `failed` rather than letting the illustration outrank the answer.
+ */
+function declaredOutcomeOf(text: string): string | undefined {
+  const trimmed = text.trim();
+  if (!trimmed) return undefined;
+  const whole = asJsonObject(trimmed);
+  if (whole) return outcomeField(whole);
+  const lines = trimmed.split(/\r?\n/);
+  let declaration: { index: number; outcome: string } | undefined;
+  for (let index = 0; index < lines.length; index += 1) {
+    const outcome = outcomeField(asJsonObject(lines[index]!.trim()) ?? {});
+    if (outcome !== undefined) declaration = { index, outcome };
   }
-  if (allowedOutcomes.includes("passed")) return "passed";
-  return allowedOutcomes[0] ?? "completed";
+  if (!declaration) return undefined;
+  // Ambiguity after the declaration fails closed. Anything in the tail that still looks like
+  // an outcome key — an inline `Actual result: {"outcome": "failed"}` on the next line, a
+  // pretty-printed object, or a second mention — means we cannot tell which one the reply is
+  // reporting, and guessing is exactly the behaviour this function exists to remove. Trailing
+  // prose that says nothing about outcomes is fine, which is what lets a real reply put its
+  // usage or sign-off after the result block.
+  const tail = lines.slice(declaration.index + 1).join("\n");
+  if (/"outcome"\s*:/.test(tail)) return undefined;
+  return declaration.outcome;
+}
+
+function determineOutcome(text: string, allowedOutcomes: readonly string[]): string {
+  // Structured result only. What does **not** count: an outcome *word* anywhere in the text —
+  // "the tests did not pass" used to settle a step as `passed` — and an empty or unstructured
+  // reply, which used to default to success. Undeclared here means `failed`; if the step does
+  // not declare `failed` the engine records `outcome_unknown` and terminates as `failed` anyway.
+  const declared = declaredOutcomeOf(text);
+  return declared !== undefined && allowedOutcomes.includes(declared) ? declared : "failed";
 }
 
 export class PiSession {
@@ -255,9 +297,11 @@ export class PiSession {
       const isAborted = active.aborted || active.signal?.aborted;
       let outcome: string;
       if (isAborted) {
-        outcome = active.allowedOutcomes.includes("cancelled")
-          ? "cancelled"
-          : (active.allowedOutcomes.includes("failed") ? "failed" : active.allowedOutcomes[0]!);
+        // A cancel is a cancel. The old chain fell through to `allowedOutcomes[0]` when the
+        // step declared neither `cancelled` nor `failed`, so aborting a step whose only
+        // declared outcome was `passed` reported `passed`. Returning `cancelled` instead lets
+        // the engine record `outcome_unknown` and terminate `failed` — never a borrowed success.
+        outcome = "cancelled";
       } else {
         outcome = determineOutcome(active.text, active.allowedOutcomes);
       }
@@ -316,8 +360,8 @@ export class PiSession {
       throw new Error("pi_session_busy");
     }
     if (signal?.aborted) {
-      const outcome = allowedOutcomes.includes("cancelled") ? "cancelled" : (allowedOutcomes.includes("failed") ? "failed" : allowedOutcomes[0]!);
-      return { outcome, text: "aborted", usage: {} };
+      // Same rule as the in-flight abort: never fall back to the first declared outcome.
+      return { outcome: "cancelled", text: "aborted", usage: {} };
     }
 
     this.status = "busy";

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

@@ -179,6 +179,28 @@ export interface KxmSupervisorHandle {
   started: boolean;
 }
 
+/**
+ * Attach to a live supervisor, or return `undefined`. Never starts one.
+ *
+ * `ensureKxmSupervisor` is for operators: an absent supervisor is a problem to fix, so it
+ * spawns. A poller — the portal tenant read, a status screen — has the opposite contract:
+ * polling must not conjure a daemon, and "nothing is running" is an answer to report, not
+ * a condition to repair. Returns `undefined` for every not-running shape: no claim, a
+ * supervisor registered but dead, a missing token file, or a probe that fails the
+ * token-proof challenge.
+ */
+export async function attachKxmSupervisor(
+  options: { stateRoot?: string; env?: NodeJS.ProcessEnv } = {},
+): Promise<KxmSupervisorHandle | undefined> {
+  const paths = kxmRuntimePaths(options.stateRoot !== undefined ? { stateRoot: options.stateRoot } : { ...(options.env ? { env: options.env } : {}) });
+  const status = kxmSupervisorStatus(paths);
+  if (!status.running || !status.port || !status.runtimeId) return undefined;
+  const token = readKxmSupervisorToken(paths);
+  if (!token) return undefined;
+  if (!(await probeSupervisor(status.port, status.runtimeId, token))) return undefined;
+  return { runtimeId: status.runtimeId, port: status.port, token, started: false };
+}
+
 /** Ensure a supervisor is running: reuse a live one, otherwise auto-start. */
 export async function ensureKxmSupervisor(
   options: { stateRoot?: string; env?: NodeJS.ProcessEnv; spawnImpl?: (scriptPath: string, env: NodeJS.ProcessEnv) => number } = {},
@@ -658,7 +680,25 @@ async function startKxmRuntimeSupervisorInner(
             sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: `project ${requestedProjectId} is not the bound project ${context.projectId}` });
             return;
           }
-          const runs = context.eventStore.runsForProject(requestedProjectId, 50);
+          // The stored `runs` row is a cache, not the state: per-run reads fold the event
+          // log (`projectKxmRunReadOnly`) precisely because the row can be stale. A listing
+          // that returned raw rows would let every consumer — including the portal's
+          // tenant read — present cached status as authoritative. Folding replays each
+          // run's events; workflows are transition-bounded, so this stays cheap at the
+          // 50-run cap. A run that refuses to fold is returned with its cached row plus
+          // `projectionError`, so one corrupt run cannot make the listing lie by omission.
+          const runs = context.eventStore.runsForProject(requestedProjectId, 50).map((stored) => {
+            try {
+              return projectKxmRunReadOnly(context, stored.runId);
+            } catch (error) {
+              return {
+                ...stored,
+                projectionError: error instanceof KxmConfigError
+                  ? (error.issues[0]?.code ?? "runtime_projection_failed")
+                  : "runtime_projection_failed",
+              };
+            }
+          });
           sendJson(response, 200, { ok: true, runs });
           return;
         }