@kontextmind/kxm 0.7.97 → 0.7.99

package/plugins/kxm/dist/server.js

@@ -15271,6 +15271,10 @@ var READ_ONLY_ONESHOT_ARGS = Object.freeze({
 function oneShotReadOnlyArgs(harness) {
   return Object.hasOwn(READ_ONLY_ONESHOT_ARGS, harness) ? READ_ONLY_ONESHOT_ARGS[harness] : void 0;
 }
+var WRITER_ONESHOT_ARGS = Object.freeze({
+  pi: Object.freeze(["-a", "--no-extensions", "--no-skills", "--no-prompt-templates", "--no-session"]),
+  grok: Object.freeze(["--always-approve", "--no-subagents", "--disable-web-search"])
+});
 var BUILTIN_HARNESSES = Object.freeze([
   {
     id: "pi",
@@ -17219,7 +17223,10 @@ var AGENT_COMMANDS = [
         await reconcileInbox(client, context.inbox, context.notifiedInbox);
         return { messages: [...context.inbox.values()] };
       }
-      return { messages: [] };
+      if (context?.hubInbox) return { messages: await client.listInbox() };
+      throw new Error(
+        "kxm_inbox is not available in this session: it activates each inbound request as a turn, and that turn's final response is the reply"
+      );
     }
   },
   {
@@ -19418,6 +19425,9 @@ var DatabaseSync = class {
   }
 };
 
+// plugins/kxm/src/bindings.ts
+var MAX_BINDING_RECORD_BYTES = 256 * 1024;
+
 // plugins/kxm/src/database.ts
 function databaseError(code, file, message) {
   const issue2 = { phase: "semantic", code, file, message };
@@ -22519,6 +22529,14 @@ data: ${JSON.stringify({ type: "ops", project, topic: "agents", at: nowIso() })}
         json(response, 200, { agent: publicAgent(current, staleAfterMs) });
         return;
       }
+      const inboxMatch = url.pathname.match(/^\/v1\/agents\/([^/]+)\/inbox$/);
+      if (method === "GET" && inboxMatch) {
+        const current = requireAgent(request, decodeURIComponent(inboxMatch[1]));
+        requireProjectAuth(request, current.project);
+        expireMessages();
+        json(response, 200, { messages: store.getPendingMessages(current.id) });
+        return;
+      }
       const agentMatch = url.pathname.match(/^\/v1\/agents\/([^/]+)$/);
       if (method === "DELETE" && agentMatch) {
         const current = requireAgent(request, decodeURIComponent(agentMatch[1]));

package/plugins/kxm/package.json

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

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

@@ -15,7 +15,7 @@ invent restart or status subcommands.
 |---|---|---|
 | `kxm hub view` | Check `/health` and `/ready`; exits 1 when the hub is down | `--json` |
 | `kxm tenant status` | Hub metadata and Runtime run state as one labeled view; reads only and never starts the supervisor | `--json` |
-| `kxm backup` | Verified SQLite backup of the hub stores with a hashed manifest | `--out <dir>`, `--json` |
+| `kxm backup` | Verified SQLite backup of the hub store and the Runtime stores with a hashed manifest; exits 1 when the backup is incomplete | `--out <dir>`, `--json` |
 
 ```bash
 kxm hub view --json
@@ -30,8 +30,9 @@ runs have separate ID spaces, so a comparison with no shared ID is
 `unverified`, never agreement.
 
 The durable hub store defaults to `.kxm/state/kxm.db` (`KXM_DATA_PATH`). Do not
-hand-edit it. `kxm backup` does not include the Runtime supervisor's stores
-under the user state root.
+hand-edit it. `kxm backup` also copies the Runtime registry and every
+project's run event store and prompt sidecar under the user state root, so a
+`kxm restore` rolls back every project on the machine, not only this one.
 
 ## Operator steps
 

package/plugins/kxm/skills/kxm-peer/SKILL.md

@@ -42,9 +42,11 @@ reading of its heartbeat lease: `online` holds the lease, `stale` has passed
 peer the hub has retired. Offline peers are listed only with
 `--include-offline`. The host label is a reading aid, never a permission.
 
-`kxm peer inbox` from a one-shot CLI call always returns an empty list,
-because the inbox lives in a long-running harness session. Use `kxm_inbox` in
-that session or `kxm dash --screen inbox`.
+`kxm peer inbox` lists the requests addressed to the CLI agent's own name, so
+run it with a stable `KXM_AGENT_NAME` and answer each with `kxm peer reply`
+under that name. The default `cli-<pid>` is a new agent on every call, and its
+inbox is always empty. In Claude Code, `kxm_inbox` lists the session's inbox; a
+Pi session receives each request as a turn instead, and its `kxm_inbox` refuses.
 
 ## Examples
 

package/plugins/kxm/skills/kxm-project-setup/SKILL.md

@@ -122,8 +122,9 @@ or store the admin or project token in the conversation. The user enters
   in a workflow step, then run `kxm init` again. Only when
   `.kxm/project.yaml` does not exist yet, ask the user to follow the README's
   move-aside workaround; never do that in a committed project.
-- The template `default` workflow declares `limits.maxAgentTimeMs`, so
-  `kxm runs drive` on it fails with `run_handoff_required`. Use `first`.
+- The template `default` workflow can be driven, but even a simulated drive
+  runs its `npm test` gate, and a live drive spends Claude and Grok and lets
+  Grok edit the checkout. Use `first` for the first run.
 - `kxm run` starts the Runtime supervisor. Stop it with `kxm runtime stop`.
 - Only run workflow IDs that `kxm workflow definitions` lists; any other ID
   fails with `run_workflow_unknown`.

package/plugins/kxm/skills/kxm-routing-improve/SKILL.md

@@ -73,11 +73,14 @@ Never apply a candidate diff yourself or treat `readyForReview` as approval.
 |---|---|---|
 | `kxm routing report` | Compare verified completion, cost, and rework per behavioral configuration | `-f/--file`, `-l/--equivalent-list-cost`, `--list-prices`, `--prices <path>` |
 | `kxm routing benchmark` | Placeholder side-by-side comparison | `--task`, `--arms`, `--runs` |
+| `kxm prices acknowledge` | Stamp the existing `.kxm/prices.yaml` list as today's estimate without fetching vendor rates | `--json` |
 
 `kxm routing report` reads the same sources as `kxm improve`, and
 `routing report --json` includes the `sources`. `kxm routing benchmark` prints
 fixed placeholder figures in this build; never cite them as measured cost or
 quality. Use `kxm routing report` for recorded spend.
+Estimates stay unknown until the catalog carries today's stamp, and a routing
+total is null when any attempt has no cost.
 
 `--equivalent-list-cost` loads the price catalog (`.kxm/prices.yaml`, or
 `--prices <path>`) without a freshness check, so an old catalog quotes old

package/plugins/kxm/skills/kxm-runs/SKILL.md

@@ -7,8 +7,9 @@ description: Create, drive, and inspect local KXM runs. kxm runs drive with --si
 
 `kxm run` creates a run of a project workflow in the local Runtime and starts
 the Runtime supervisor. A created run stays `created` until
-`kxm runs drive` executes it. Do not invent get, create, or logs verbs under
-`runs`.
+`kxm runs drive` executes the pinned plan. Live drive is the default and spends
+an admitted model; `--simulated` is the model-free producer. Do not invent get,
+create, or logs verbs under `runs`.
 
 ## Commands
 
@@ -58,11 +59,11 @@ the receipt's settlement is terminal `completed`.
 - `run_workflow_unknown`: the workflow ID is not a project workflow. Run only
   IDs that `kxm workflow definitions` lists.
 - `run_handoff_required`: the Runtime does not execute a field the workflow
-  uses, so drive fails with `runtime request failed with HTTP 409` and the run
-  stays `preparing`. The template `default` workflow declares
-  `limits.maxAgentTimeMs`, which is one such field. Cancel the run with
-  `kxm runs cancel <runId>` and drive a workflow without the field, such as
-  `first`.
+  uses (such as `limits.maxAgentTimeMs`, which a fresh `kxm init` no longer
+  writes), so drive fails with `runtime request failed with HTTP 409` and the
+  run stays `preparing`. Cancel the run with `kxm runs cancel <runId>` and drive
+  a workflow without the field, such as `first`.
 
 Listing or status alone is not proof that steps ran; a verified receipt is.
+A read-only step that settles `passed` did not author a checkout change.
 `kxm workflow list` shows hub webhook runs, not these runs.

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

@@ -185,36 +185,41 @@ export async function cmdBackup(runtime: Runtime, options: { out?: string | unde
   try {
     const backupOptions = {
       projectRoot: runtime.cwd,
+      env: runtime.env,
       ...(options.out ? { outDir: resolve(runtime.cwd, options.out) } : {}),
     };
     if (runtime.dryRun) {
       const plan = planBackup(backupOptions);
       printPlan(
         runtime,
-        { command: "backup", outDir: plan.outDir, stores: plan.stores },
+        { command: "backup", outDir: plan.outDir, stores: plan.stores, files: plan.files },
         [
-          ...plan.stores.map((store) => ({ action: "write" as const, target: join(plan.outDir, store.backupFile) })),
+          ...[...plan.stores, ...plan.files].map((entry) => ({ action: "write" as const, target: join(plan.outDir, entry.backupFile) })),
           { action: "write", target: join(plan.outDir, "manifest.json") },
         ],
-        `back up ${plan.stores.length} store(s) to ${plan.outDir} (sources are not opened, so their WAL is not checkpointed)`,
+        `back up ${plan.stores.length} store(s) and ${plan.files.length} file(s) to ${plan.outDir} (sources are not opened, so their WAL is not checkpointed)`,
       );
       return 0;
     }
     const { manifest, outDir } = createBackup(backupOptions);
+    const complete = manifest.complete === true;
     const payload = {
-      ok: true,
+      ok: complete,
       command: "backup",
       backupId: manifest.backupId,
       outDir,
       manifest,
     };
     const summary = [
-      `Created SQLite backup with ${manifest.stores.length} store(s):`,
+      complete
+        ? `Created SQLite backup with ${manifest.stores.length} store(s):`
+        : `Backup is incomplete (${manifest.omitted?.length ?? 0} omitted); not ok:`,
       ...manifest.stores.map((s) => `  - ${s.storeId}: ${s.sourcePath} -> ${s.backupFile} (schema v${s.schemaVersion}, ${s.bytes} bytes, sha256 ${s.sha256.slice(0, 12)}...)`),
+      ...(manifest.omitted ?? []).map((id) => `  - omitted ${id}`),
       `Manifest: ${join(outDir, "manifest.json")}`,
     ].join("\n");
     print(runtime.io, runtime.json, payload, summary);
-    return 0;
+    return complete ? 0 : 1;
   } catch (error) {
     if (error instanceof KxmConfigError) {
       print(runtime.io, runtime.json, { ok: false, command: "backup", error: "backup_failed", issues: error.issues }, `backup failed: ${error.message}`);
@@ -236,14 +241,18 @@ export async function cmdRestore(runtime: Runtime, manifestArg: string): Promise
           backupId: plan.backupId,
           manifestPath: plan.manifestPath,
           stores: plan.stores.map(({ storeId, targetPath, schemaVersion }) => ({ storeId, targetPath, schemaVersion })),
+          files: plan.files.map(({ id, targetPath }) => ({ id, targetPath })),
         },
-        plan.stores.flatMap((store) => [
-          { action: "write" as const, target: store.targetPath },
-          ...[`${store.targetPath}-wal`, `${store.targetPath}-shm`]
-            .filter((file) => existsSync(file))
-            .map((file) => ({ action: "delete" as const, target: file })),
-        ]),
-        `restore ${plan.stores.length} store(s) from ${plan.manifestPath}; digests verified against the manifest`,
+        [
+          ...plan.stores.flatMap((store) => [
+            { action: "write" as const, target: store.targetPath },
+            ...[`${store.targetPath}-wal`, `${store.targetPath}-shm`]
+              .filter((file) => existsSync(file))
+              .map((file) => ({ action: "delete" as const, target: file })),
+          ]),
+          ...plan.files.map((file) => ({ action: "write" as const, target: file.targetPath })),
+        ],
+        `restore ${plan.stores.length} store(s) and ${plan.files.length} file(s) from ${plan.manifestPath}; digests verified against the manifest`,
       );
       return 0;
     }

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

@@ -20,7 +20,7 @@ import {
   type RoutingRecord,
   type RoutingRecordV2,
 } from "../routing.ts";
-import { loadPriceCatalog, type PriceCatalog } from "../prices.ts";
+import { acknowledgePriceCatalog, loadPriceCatalog, type PriceCatalog } from "../prices.ts";
 import {
   buildImprovementReport,
   formatImprovementReport,
@@ -59,6 +59,7 @@ import {
 import {
   GUIDE_WORKFLOWS,
   parseGuideSelection,
+  mergeGuideRouteAdmission,
   planGuideSetup,
   renderGuideSetupFiles,
   writeGuideSetupFiles,
@@ -867,8 +868,10 @@ export async function maybeOfferGuideSetup(runtime: Runtime): Promise<void> {
   const plan = planGuideSetup({ inventory, selected });
   const files = renderGuideSetupFiles(runtime.cwd, plan);
   const report = writeGuideSetupFiles(files);
+  const admitted = mergeGuideRouteAdmission(runtime.cwd, plan);
   for (const file of report.written) runtime.io.stdout(`wrote ${file}\n`);
   for (const file of report.existed) runtime.io.stdout(`kept existing ${file} (not overwritten)\n`);
+  for (const selector of admitted) runtime.io.stdout(`admitted route ${selector}\n`);
   for (const skip of plan.skipped) {
     runtime.io.stdout(`skipped ${skip.workflow}/${skip.role}: ${skip.reason}\n`);
   }
@@ -877,6 +880,24 @@ export async function maybeOfferGuideSetup(runtime: Runtime): Promise<void> {
   }
 }
 
+export async function cmdPricesAcknowledge(runtime: Runtime): Promise<number> {
+  try {
+    const catalog = acknowledgePriceCatalog(runtime.cwd);
+    print(runtime.io, runtime.json, {
+      ok: true,
+      command: "prices acknowledge",
+      date: catalog.date,
+      sha256: catalog.sha256,
+      note: "stamped the existing list as today's estimate; vendor rates were not fetched",
+    }, `price catalog stamped ${catalog.date} (list estimate only; vendor rates were not fetched)`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    print(runtime.io, runtime.json, { ok: false, command: "prices acknowledge", error: "prices_acknowledge_failed", message }, `prices acknowledge failed: ${message}`);
+    return 1;
+  }
+}
+
 export async function cmdRoutingReport(
   runtime: Runtime,
   options: { file?: string | undefined; equivalentListCost?: boolean | undefined; listPrices?: boolean | undefined; prices?: string | undefined },

package/plugins/kxm/src/cli.ts

@@ -149,6 +149,7 @@ import {
   cmdConfigList,
   cmdCompletion,
   cmdCompletionInstall,
+  cmdPricesAcknowledge,
   cmdRoutingReport,
   cmdRoutingBenchmark,
   maybeOfferCompletionInstall,
@@ -348,7 +349,9 @@ async function dispatchAgentCliCommand(
   let client: HubClient | undefined;
   try {
     client = await ensureCliClient(runtime);
-    const output = await cmd.execute(client, args);
+    // A one-shot call keeps no inbox, so `peer inbox` reads this agent's open requests from
+    // the hub; with a stable KXM_AGENT_NAME those include ones queued while it was offline.
+    const output = await cmd.execute(client, args, { hubInbox: true });
     const payload = (output && typeof output === "object" ? output : { result: output }) as object;
     print(runtime.io, runtime.json, payload, JSON.stringify(output, null, 2));
     return 0;
@@ -416,7 +419,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       });
     });
 
-  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of the project hub store with a hashed manifest (Runtime stores under the user state root are not included)"))
+  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of the project hub store and the Runtime stores under the user state root, with a hashed manifest"))
     .option("--out <dir>", "Directory to write backup and manifest")
     .action(async function backupAction(this: Command, options: { out?: string }) {
       result.code = await cmdBackup(runtimeFrom(ctx, this), options);
@@ -442,7 +445,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     });
   addGlobalOptions(runCmd.command("drive").description("Drive a run with live harness calls, or with the model-free simulation when --simulated is passed"))
     .argument("<runId>", "Run id")
-    .option("--simulated", "Use the model-free simulation producer")
+    .option("--simulated", "Use the model-free simulation producer instead of a live model")
     .option("--wait", "Wait until a drive receipt is recorded; exits 0 only for a VERIFIED COMPLETED settlement")
     .option("--timeout-ms <n>", "Wait timeout in milliseconds (default 60000, max 600000)")
     .action(async function runDriveAction(this: Command, runId: string, options: { simulated?: boolean; wait?: boolean; timeoutMs?: string }) {
@@ -474,6 +477,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdTenantStatus(runtimeFrom(ctx, this));
     });
 
+  const pricesCmd = addGlobalOptions(program.command("prices").description("Stamp the local list-price catalog. Estimates stay unknown until today's stamp"));
+  pricesCmd.helpCommand("help", "Show prices help");
+  addGlobalOptions(pricesCmd.command("acknowledge").description("Stamp the existing .kxm/prices.yaml list as today's estimate without fetching vendor rates"))
+    .action(async function pricesAcknowledgeAction(this: Command) {
+      result.code = await cmdPricesAcknowledge(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");
@@ -928,7 +938,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdGithubWatch(runtimeFrom(ctx, this), options);
     });
 
-  const improve = addGlobalOptions(program.command("improve").description("Propose coded-repeat candidates from this project's Runtime routing records and telemetry"));
+  const improve = addGlobalOptions(program.command("improve").description("Propose coded-repeat candidates from this project's Runtime routing records and telemetry. Proposals are not applied to the next run"));
   improve.helpCommand("help", "Show improve help");
   addGlobalOptions(improve.command("report", { isDefault: true }).description("Generate improvement report and candidates from routing records"))
     .option("--file <path>", "Read only this routing-record JSONL instead of the project's Runtime store and telemetry")

package/plugins/kxm/src/client.ts

@@ -325,6 +325,16 @@ export class HubClient {
     }));
   }
 
+  /** This agent's open inbound requests (queued or delivered), oldest first. A read: nothing
+   * is acknowledged. */
+  async listInbox(): Promise<MessageRecord[]> {
+    if (!this.agent) throw new Error("hub client is not registered");
+    const result = await this.request<{ messages: MessageRecord[] }>(
+      `/v1/agents/${encodeURIComponent(this.agent.id)}/inbox`,
+    );
+    return result.messages;
+  }
+
   async getMessage(messageId: string): Promise<MessageRecord> {
     const result = await this.request<{ message: MessageRecord }>(`/v1/messages/${encodeURIComponent(messageId)}`);
     return result.message;

package/plugins/kxm/src/commands.ts

@@ -72,8 +72,12 @@ export interface SessionTokenPayload {
 
 export interface CommandExecutionContext {
   signal?: AbortSignal | undefined;
+  /** An event-fed inbox the caller keeps (the MCP server); `kxm_inbox` reconciles it. */
   inbox?: Map<string, MessageRecord> | undefined;
   notifiedInbox?: Set<string> | undefined;
+  /** The caller keeps no inbox and reads its open requests from the hub (a one-shot CLI
+   * call). A caller with neither this nor `inbox` activates inbound requests itself (Pi). */
+  hubInbox?: boolean | undefined;
   /** Inbound requests this session is handling: the Pi extension's active request, the MCP
    * server's open inbox. A request sent meanwhile is one more hop along their chain. */
   handling?: readonly Pick<MessageRecord, "hops" | "maxHops">[] | undefined;
@@ -452,7 +456,12 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
         await reconcileInbox(client, context.inbox, context.notifiedInbox);
         return { messages: [...context.inbox.values()] };
       }
-      return { messages: [] };
+      if (context?.hubInbox) return { messages: await client.listInbox() };
+      // Listing would offer requests this session's own activation queue is about to hand
+      // it as turns, and an empty list would hide them, so it refuses.
+      throw new Error(
+        "kxm_inbox is not available in this session: it activates each inbound request as a turn, and that turn's final response is the reply",
+      );
     },
   },
   {