@kontextmind/kxm 0.7.98 → 0.7.99

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.98",
+      "version": "0.7.99",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -365,6 +365,13 @@ All notable user-facing changes are documented here. The project follows [Semant
 - **Workflow prompts no longer point agents at `.kxm/config`**, a path KXM refuses.
 - **`kxm gate signal` and `kxm workflow wait` inside a KXM project reach the hub for hub
   runs.** They go to the local Runtime only for a run its store holds.
+- **`kxm peer inbox` lists the requests waiting for a named CLI agent.** It returned
+  `{"messages":[]}` every time. The hub now serves `GET /v1/agents/:id/inbox`
+  (agent-authenticated, project-scoped): the caller's queued and delivered requests,
+  oldest first, acknowledging nothing. Run with a stable `KXM_AGENT_NAME` (for example
+  `codex`) to list requests peers queued for it while it was offline, then answer them
+  with `kxm peer reply`. The Pi extension's `kxm_inbox` tool now refuses instead of
+  returning an empty list, because Pi activates each inbound request as a turn itself.
 
 - **The Claude plugin's SessionStart hook is one bundled, read-only, project-scoped
   script.** The two shell hooks it replaces (`kxm session brief --status` and

package/docs/guides/peer-messaging.md

@@ -210,7 +210,7 @@ CLI (run with the recipient's `KXM_AGENT_NAME`):
 kxm peer reply msg_779f5e0f22e04ac1af6078589a874971 "The plan is sound. Add a test for a zero discount."
 ```
 
-Only the recipient can reply, and only once. From the CLI, `kxm peer inbox` always returns an empty list, because a one-shot command has no long-running inbox. Use `kxm dash --screen inbox` to see pending requests.
+Only the recipient can reply, and only once. From the CLI, `kxm peer inbox` lists the requests still waiting for the agent named by `KXM_AGENT_NAME`, including ones queued while it was offline, without acknowledging them. The default `cli-<pid>` name is a new agent on every call, so its list is empty.
 
 ## Choose a delivery mode
 
@@ -291,7 +291,7 @@ Errors about `workflowContext` are covered in [Peer provenance and quorum gates]
 | A request stays `delivered` | The recipient's turn, tool, or provider call is still running, or a Claude Code session restarted after acknowledging it. | Wait, or cancel and send it again with a new idempotency key. |
 | `kxm_fanout` returns `pending` | The local wait ended before a reply. | Use the returned message IDs with `kxm_get`, or repeat the exact call. |
 | Claude Code never sees requests | Channel mode is off or blocked by policy. | Use `kxm_inbox` and `kxm_reply`. |
-| `kxm peer inbox` is always empty | The CLI has no long-running inbox. | Use `kxm dash --screen inbox`. |
+| `kxm peer inbox` is always empty | `KXM_AGENT_NAME` is unset, so each call registers a new `cli-<pid>` agent that nobody has addressed. | Set `KXM_AGENT_NAME` to the name peers send to. |
 
 For hub-level problems, see [Troubleshoot KXM](../operations/troubleshooting.md).
 

package/docs/reference/cli-reference.md

@@ -2397,18 +2397,21 @@ kxm peer fanout --targets reviewer critic --content "Independent review of PR 42
 kxm peer inbox
 ```
 
-List inbound peer requests. From the CLI this always returns `{"messages":[]}`: the inbox lives in a long-running harness session, which a one-shot CLI call does not have. Use `kxm dash --screen inbox` to see pending requests.
+List the inbound peer requests addressed to this agent that still need a reply, oldest first, read from the hub (`GET /v1/agents/<agentId>/inbox`). Only a stable `KXM_AGENT_NAME` has an inbox: a registered name that is offline keeps its agent ID, so a later call as the same name lists what peers queued for it with `peer send --allow-offline`. The default `cli-<pid>` is a new agent on every call, and its list is always empty. Answer each request with `peer reply` under the same name.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
 | `--payload` | `<json>` | none | JSON payload |
 
+- Reads only. Listing acknowledges nothing, so a request stays `queued` for push delivery. Output key: `messages`, each a full message record (`id`, `fromName`, `content`, `status` `queued` or `delivered`, `expiresAt`).
+- The call registers the name while it runs, so it exits 1 (`command_failed`, `agent name already active in project`) when another session holds that name online.
+
 ```bash
-kxm peer inbox --json
+KXM_AGENT_NAME=codex kxm peer inbox --json
 ```
 
 ```text
-{"schema":"kxm.cli-result.v1","messages":[]}
+{"schema":"kxm.cli-result.v1","messages":[{"id":"msg_1f0c…","project":"kxm","from":"agt_9d2e…","fromName":"reviewer","to":"agt_4b7a…","toName":"codex","content":"Review the retry loop in src/sync.ts","delivery":"followUp","hops":0,"maxHops":5,"seq":1,"createdAt":"2026-09-23T21:40:00.000Z","expiresAt":"2026-09-24T21:40:00.000Z","status":"queued"}]}
 ```
 
 ### `kxm peer reply`
@@ -3590,7 +3593,6 @@ These are behaviors of the current build that differ from what the help text or
 
 - `kxm routing benchmark` prints constant placeholder figures.
 - `kxm task sync` does not contact GitHub or Jira.
-- `kxm peer inbox` always returns an empty list from the CLI.
 - `kxm context` subcommands crash with a stack trace when the hub is unreachable, and they ignore the persisted hub credential.
 - `kxm completion <shell>` generates a command list that includes a nonexistent `plan` command, omits `models`, `routes`, `explain`, and `ssh`, lists a nonexistent `goal get`, and omits `runs drive`, `runs receipt`, `runtime sync-retry`, and `improve report`.
 - `kxm backup` JSON shows `manifestSha256` redacted.

package/docs/reference/http-api.md

@@ -49,6 +49,7 @@ Operations routes carry no message bodies. `kxm dash` and `kxm tenant status` us
 | `POST` | `/v1/agents/register` | Project | Register or resume `name` in `project` with `purpose`, optional `model` and `host`. Returns the agent and a new `agentKey` (201 new, 200 resumed) |
 | `GET` | `/v1/agents` | Agent | Agents in your project; `?includeOffline=true` adds registered offline agents |
 | `POST` | `/v1/agents/<agentId>/heartbeat` | Agent | Renew your presence lease (clients send one every 10 seconds) |
+| `GET` | `/v1/agents/<agentId>/inbox` | Agent | Your open inbound requests (`queued` or `delivered`), oldest first, as `{ "messages": [...] }`. Expires overdue requests first; acknowledges nothing and moves no delivery cursor |
 | `DELETE` | `/v1/agents/<agentId>` | Agent | Mark yourself offline (204) |
 
 Key errors: `duplicate_agent_name` (409, the name is online in the project), `invalid_agent_identity` (401). Presence (`online`, `stale`, `offline`) is computed from the hub's clock with a 30-second lease; agents never report their own presence.

package/docs/reference/tools.md

@@ -24,7 +24,7 @@ flowchart LR
 | `kxm_fanout` | Peers | Yes | `kxm peer fanout` |
 | `kxm_await` | Peers | No | `kxm peer await` |
 | `kxm_cancel` | Peers | Yes | `kxm peer cancel` |
-| `kxm_inbox` | Peers | No | `kxm peer inbox` (always empty from the CLI) |
+| `kxm_inbox` | Peers | No | `kxm peer inbox` (lists a named CLI agent's open requests; refused in Pi) |
 | `kxm_reply` | Peers | Yes | `kxm peer reply` |
 | `kxm_workflow_list` | Workflows | No | None; `kxm workflow list` reads the local database instead |
 | `kxm_workflow_get` | Workflows | No | None; `kxm workflow get` reads the local database instead |
@@ -162,8 +162,8 @@ Returns the message record with `status: "cancelled"`. Cancelling an already can
 Lists inbound requests that still need a reply. It takes no parameters.
 
 - **Claude Code:** returns `{ "messages": [...] }` from the session's inbox, which fills from the hub's event stream while the session is registered. Before returning, it re-reads each request and drops those already answered, cancelled or expired. This is pull mode; see [Pushed channel mode and pull mode](../../plugins/kxm/README.md#pushed-channel-mode-and-pull-mode).
-- **Pi:** always returns an empty list. The extension turns each inbound request into a model turn instead.
-- **CLI:** always returns an empty list, because a one-shot command holds no inbox.
+- **Pi:** refuses. The extension turns each inbound request into a model turn itself, and that turn's final response is the reply, so listing would offer requests its own queue is about to activate.
+- **CLI:** `kxm peer inbox` reads the agent's open requests from the hub (`GET /v1/agents/<agentId>/inbox`), acknowledging nothing. Run it with a stable `KXM_AGENT_NAME` to see requests queued for that name while it was offline; the default `cli-<pid>` is a new agent on every call, so its list is empty.
 
 ### `kxm_reply`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.98",
+  "version": "0.7.99",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.98",
+  "version": "0.7.99",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/claude-hook.js

@@ -9508,7 +9508,10 @@ var init_commands = __esm({
             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"
+          );
         }
       },
       {

package/plugins/kxm/dist/cli.js

@@ -19626,6 +19626,15 @@ var HubClient = class {
       }
     }));
   }
+  /** This agent's open inbound requests (queued or delivered), oldest first. A read: nothing
+   * is acknowledged. */
+  async listInbox() {
+    if (!this.agent) throw new Error("hub client is not registered");
+    const result = await this.request(
+      `/v1/agents/${encodeURIComponent(this.agent.id)}/inbox`
+    );
+    return result.messages;
+  }
   async getMessage(messageId) {
     const result = await this.request(`/v1/messages/${encodeURIComponent(messageId)}`);
     return result.message;
@@ -20322,7 +20331,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"
+      );
     }
   },
   {
@@ -49161,7 +49173,7 @@ async function dispatchAgentCliCommand(runtime, toolName, rawArgs) {
   let client;
   try {
     client = await ensureCliClient(runtime);
-    const output = await cmd.execute(client, args);
+    const output = await cmd.execute(client, args, { hubInbox: true });
     const payload = output && typeof output === "object" ? output : { result: output };
     print(runtime.io, runtime.json, payload, JSON.stringify(output, null, 2));
     return 0;

package/plugins/kxm/dist/client.js

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

package/plugins/kxm/dist/core.js

@@ -1284,7 +1284,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"
+      );
     }
   },
   {

package/plugins/kxm/dist/extension.js

@@ -14842,6 +14842,15 @@ var HubClient = class {
       }
     }));
   }
+  /** This agent's open inbound requests (queued or delivered), oldest first. A read: nothing
+   * is acknowledged. */
+  async listInbox() {
+    if (!this.agent) throw new Error("hub client is not registered");
+    const result2 = await this.request(
+      `/v1/agents/${encodeURIComponent(this.agent.id)}/inbox`
+    );
+    return result2.messages;
+  }
   async getMessage(messageId) {
     const result2 = await this.request(`/v1/messages/${encodeURIComponent(messageId)}`);
     return result2.message;
@@ -15408,7 +15417,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"
+      );
     }
   },
   {

package/plugins/kxm/dist/mcp-server.js

@@ -16042,6 +16042,15 @@ var HubClient = class {
       }
     }));
   }
+  /** This agent's open inbound requests (queued or delivered), oldest first. A read: nothing
+   * is acknowledged. */
+  async listInbox() {
+    if (!this.agent) throw new Error("hub client is not registered");
+    const result = await this.request(
+      `/v1/agents/${encodeURIComponent(this.agent.id)}/inbox`
+    );
+    return result.messages;
+  }
   async getMessage(messageId) {
     const result = await this.request(`/v1/messages/${encodeURIComponent(messageId)}`);
     return result.message;
@@ -16700,7 +16709,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"
+      );
     }
   },
   {
@@ -17296,7 +17308,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.98";
+var VERSION = "0.7.99";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/dist/server.js

@@ -17223,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"
+      );
     }
   },
   {
@@ -22526,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.98",
+  "version": "0.7.99",
   "private": true,
   "type": "module",
   "engines": {

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/src/cli.ts

@@ -349,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;

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",
+      );
     },
   },
   {

package/plugins/kxm/src/extension.ts

@@ -898,6 +898,7 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
           throw new Error(`tool_policy_denied: ${policy.detail ?? policy.error}`);
         }
         // A request sent while handling the active inbound request continues its hop chain.
+        // No inbox and no hubInbox: `pending` owns activation, so kxm_inbox refuses here.
         const handling = activeInbound ? [activeInbound] : [];
         return result(
           await workflowCall(() =>

package/plugins/kxm/src/hub.ts

@@ -2520,6 +2520,18 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         return;
       }
 
+      // An agent's open inbound requests, queued or delivered, in delivery order. A read
+      // for a caller that holds no event-fed inbox of its own (a one-shot CLI call): it
+      // acknowledges nothing and moves no cursor, so push delivery is unchanged.
+      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/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.98";
+const VERSION = "0.7.99";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();