@kontextmind/kxm 0.7.69 → 0.7.70

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.69",
+      "version": "0.7.70",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -6,6 +6,13 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **`kxm peer send --allow-offline` queues to a registered offline peer.**
+  `POST /v1/messages` accepts `allowOffline: true` (also `kxm_send.allowOffline`): a
+  registered agent in the same project is stored `queued` instead of `target_not_found`,
+  real-time `publish` is skipped, and the existing reconnect cursor delivers the message
+  once on resumption. Unknown names still fail closed. TTL expiry is unchanged; queued
+  messages are not evidence unless `workflowContext` was hub-authorized at send.
+
 - **Per-tenant hosting operations, and a backup that covers the whole state set.**
   `docs/operations.md` gained a *Per-tenant hosted deployment* section (one tenant = one box
   = one hub; loopback-only hub and supervisor; the tenant's proxy owns TLS and the browser

package/docs/test-matrix.md

@@ -22,6 +22,7 @@ npm run verify
 | All delivery modes, message fields, hop limits, and validation | `test/core/hub-api.test.ts`, `test/core/protocol.test.ts` |
 | Queue, acknowledgement, visibility, reply, and authorization | `test/core/hub-api.test.ts`, `test/core/hub.test.ts` |
 | Queued/delivered replay after recipient restart reuses one message record | `test/core/hub.test.ts`, `test/core/extension.test.ts`, `test/core/mcp.test.ts` |
+| Known-offline peer send with `allowOffline` queues, delivers once on resumption, and expires unread by TTL | `test/core/hub-api.test.ts` |
 | One-to-three-peer fanout, recoverable local timeouts/aborts, exact retries, and partial-error collection | `test/core/client.test.ts`, `test/core/hub-api.test.ts`, `test/core/extension.test.ts`, `test/core/mcp.test.ts` |
 | TTL expiry, sender cancellation, and terminal retention | `test/core/hub-api.test.ts` |
 | Terminal inbound cleanup and next-request activation | `test/core/extension.test.ts`, `test/core/mcp.test.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.69",
+  "version": "0.7.70",
   "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.69",
+  "version": "0.7.70",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -19817,7 +19817,12 @@ var AGENT_COMMANDS = [
           required: ["runId", "stageId", "requirementKey", "attempt"],
           additionalProperties: false
         },
-        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" }
+        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" },
+        allowOffline: {
+          type: "boolean",
+          default: false,
+          description: "Queue the request if the target is a registered offline agent in this project"
+        }
       },
       required: ["target", "content"],
       additionalProperties: false
@@ -19834,7 +19839,8 @@ var AGENT_COMMANDS = [
         ...correlationId ? { correlationId } : {},
         ...idempotencyKey ? { idempotencyKey } : {},
         ...workflowContext ? { workflowContext } : {},
-        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {}
+        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {},
+        ...args.allowOffline === true ? { allowOffline: true } : {}
       });
       return { messageId: message.id, status: message.status, target: message.toName };
     }
@@ -47741,7 +47747,7 @@ function createProgram(ctx, result) {
   addGlobalOptions(peer.command("list").description("List online peer agents in this project's hub pool")).option("--payload <json>", "JSON payload").action(async function peerListAction(opts) {
     result.code = await dispatchAgentCliCommand(runtimeFrom(ctx, this), "kxm_list", opts ?? {});
   });
-  addGlobalOptions(peer.command("send [target] [content]").description("Send a focused request to a peer agent")).option("--target <name>", "Peer name or agent ID").option("--content <text>", "Focused request content").option("--delivery <mode>", "steer, followUp, or nextTurn").option("--correlation-id <id>", "Task grouping ID").option("--idempotency-key <key>", "Deduplication key").option("--workflow-context <json>", "Workflow context JSON").option("--ttl-ms <ms>", "Message TTL in milliseconds").option("--payload <json>", "JSON payload").action(async function peerSendAction(target, content, opts) {
+  addGlobalOptions(peer.command("send [target] [content]").description("Send a focused request to a peer agent")).option("--target <name>", "Peer name or agent ID").option("--content <text>", "Focused request content").option("--delivery <mode>", "steer, followUp, or nextTurn").option("--correlation-id <id>", "Task grouping ID").option("--idempotency-key <key>", "Deduplication key").option("--workflow-context <json>", "Workflow context JSON").option("--ttl-ms <ms>", "Message TTL in milliseconds").option("--allow-offline", "Queue the request if the target is registered but offline").option("--payload <json>", "JSON payload").action(async function peerSendAction(target, content, opts) {
     const options = { ...opts, ...target ? { target } : {}, ...content ? { content } : {} };
     result.code = await dispatchAgentCliCommand(runtimeFrom(ctx, this), "kxm_send", options);
   });

package/plugins/kxm/dist/core.js

@@ -992,7 +992,12 @@ var AGENT_COMMANDS = [
           required: ["runId", "stageId", "requirementKey", "attempt"],
           additionalProperties: false
         },
-        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" }
+        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" },
+        allowOffline: {
+          type: "boolean",
+          default: false,
+          description: "Queue the request if the target is a registered offline agent in this project"
+        }
       },
       required: ["target", "content"],
       additionalProperties: false
@@ -1009,7 +1014,8 @@ var AGENT_COMMANDS = [
         ...correlationId ? { correlationId } : {},
         ...idempotencyKey ? { idempotencyKey } : {},
         ...workflowContext ? { workflowContext } : {},
-        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {}
+        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {},
+        ...args.allowOffline === true ? { allowOffline: true } : {}
       });
       return { messageId: message.id, status: message.status, target: message.toName };
     }

package/plugins/kxm/dist/extension.js

@@ -15061,7 +15061,12 @@ var AGENT_COMMANDS = [
           required: ["runId", "stageId", "requirementKey", "attempt"],
           additionalProperties: false
         },
-        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" }
+        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" },
+        allowOffline: {
+          type: "boolean",
+          default: false,
+          description: "Queue the request if the target is a registered offline agent in this project"
+        }
       },
       required: ["target", "content"],
       additionalProperties: false
@@ -15078,7 +15083,8 @@ var AGENT_COMMANDS = [
         ...correlationId ? { correlationId } : {},
         ...idempotencyKey ? { idempotencyKey } : {},
         ...workflowContext ? { workflowContext } : {},
-        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {}
+        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {},
+        ...args.allowOffline === true ? { allowOffline: true } : {}
       });
       return { messageId: message.id, status: message.status, target: message.toName };
     }

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

@@ -16372,7 +16372,12 @@ var AGENT_COMMANDS = [
           required: ["runId", "stageId", "requirementKey", "attempt"],
           additionalProperties: false
         },
-        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" }
+        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" },
+        allowOffline: {
+          type: "boolean",
+          default: false,
+          description: "Queue the request if the target is a registered offline agent in this project"
+        }
       },
       required: ["target", "content"],
       additionalProperties: false
@@ -16389,7 +16394,8 @@ var AGENT_COMMANDS = [
         ...correlationId ? { correlationId } : {},
         ...idempotencyKey ? { idempotencyKey } : {},
         ...workflowContext ? { workflowContext } : {},
-        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {}
+        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {},
+        ...args.allowOffline === true ? { allowOffline: true } : {}
       });
       return { messageId: message.id, status: message.status, target: message.toName };
     }
@@ -17121,7 +17127,7 @@ async function deliverInboxNotification(messageId, delivered, notify) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.69";
+var VERSION = "0.7.70";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
 var meshClient;

package/plugins/kxm/dist/server.js

@@ -8622,7 +8622,12 @@ var AGENT_COMMANDS = [
           required: ["runId", "stageId", "requirementKey", "attempt"],
           additionalProperties: false
         },
-        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" }
+        ttlMs: { type: "number", minimum: 1e3, maximum: 6048e5, description: "Message TTL in milliseconds" },
+        allowOffline: {
+          type: "boolean",
+          default: false,
+          description: "Queue the request if the target is a registered offline agent in this project"
+        }
       },
       required: ["target", "content"],
       additionalProperties: false
@@ -8639,7 +8644,8 @@ var AGENT_COMMANDS = [
         ...correlationId ? { correlationId } : {},
         ...idempotencyKey ? { idempotencyKey } : {},
         ...workflowContext ? { workflowContext } : {},
-        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {}
+        ...typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {},
+        ...args.allowOffline === true ? { allowOffline: true } : {}
       });
       return { messageId: message.id, status: message.status, target: message.toName };
     }
@@ -12198,6 +12204,11 @@ function sameWorkflowMessageContext(left, right) {
   if (!left || !right) return left === right;
   return left.schema === right.schema && left.runId === right.runId && left.stageId === right.stageId && left.requirementKey === right.requirementKey && left.attempt === right.attempt;
 }
+function parseOptionalBoolean(value, field) {
+  if (value === void 0 || value === null) return false;
+  if (typeof value === "boolean") return value;
+  throw new ProtocolError(400, `${field} must be a boolean`);
+}
 function sameIdempotentRequest(message, target, content, delivery, correlationId, replyTo, hops, maxHops, ttlMs, workflowContext) {
   return (message.to === target || message.toName.toLowerCase() === target.toLowerCase()) && message.content === content && message.delivery === delivery && message.correlationId === correlationId && message.replyTo === replyTo && message.hops === hops && message.maxHops === maxHops && sameWorkflowMessageContext(message.workflowContext, workflowContext) && Date.parse(message.expiresAt) - Date.parse(message.createdAt) === ttlMs;
 }
@@ -12500,7 +12511,10 @@ function createMeshHub(options = {}) {
     agent.lastSeenAt = nowIso();
     agent.online = true;
     store.saveAgent(agent);
-    if (wasOffline) broadcastPresence(agent);
+    if (wasOffline) {
+      broadcastPresence(agent);
+      if ((streams.get(agent.id)?.size ?? 0) > 0) flushPending(agent.id);
+    }
     return agent;
   }
   function checkRateLimit(request, response) {
@@ -12601,11 +12615,11 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
     }
     publishOps(agent.project, "agents");
   }
-  function findTarget(project, target) {
+  function findTarget(project, target, allowOffline = false) {
     const byId = agents.get(target);
-    if (byId?.project === project && byId.online) return byId;
+    if (byId?.project === project && (allowOffline || byId.online)) return byId;
     const byName = [...agents.values()].find(
-      (agent) => agent.project === project && agent.online && agent.name.toLowerCase() === target.toLowerCase()
+      (agent) => agent.project === project && (allowOffline || agent.online) && agent.name.toLowerCase() === target.toLowerCase()
     );
     if (!byName) throw new ProtocolError(404, `online target not found: ${target}`, "target_not_found");
     return byName;
@@ -14026,6 +14040,7 @@ data: ${JSON.stringify({ agent: publicAgent(current) })}
           MIN_MESSAGE_TTL_MS,
           MAX_MESSAGE_TTL_MS
         );
+        const allowOffline = parseOptionalBoolean(body.allowOffline, "allowOffline");
         const idempotencyKey = optionalString(body.idempotencyKey, "idempotencyKey", 128);
         if (idempotencyKey) {
           const existing = store.findMessageByIdempotency(sender.id, idempotencyKey);
@@ -14048,7 +14063,7 @@ data: ${JSON.stringify({ agent: publicAgent(current) })}
             return;
           }
         }
-        const target = findTarget(sender.project, targetInput);
+        const target = findTarget(sender.project, targetInput, allowOffline);
         if (target.id === sender.id) {
           throw new ProtocolError(400, "cannot send a request to yourself", "self_target");
         }
@@ -14076,7 +14091,7 @@ data: ${JSON.stringify({ agent: publicAgent(current) })}
         };
         store.saveMessage(message);
         publishOps(message.project, "messages");
-        publish(target.id, { type: "message", message });
+        if (target.online) publish(target.id, { type: "message", message });
         counters.messagesSent += 1;
         logger({ event: "message_sent", messageId: message.id, hops, ...messageLog(message, sender.id, sender.name, target.id, target.name) });
         json(response, 202, { message, idempotent: false });

package/plugins/kxm/package.json

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

package/plugins/kxm/skills/kxm/references/protocol.md

@@ -81,6 +81,12 @@ declared in policy, is bound to the active attempt, and is idempotent only when
 the reason is unchanged. Approval does not checkpoint the stage. Webhook and
 signal authentication cannot call this route.
 
+`POST /v1/messages` requires an online target unless `allowOffline` is true.
+With `allowOffline: true`, a registered offline agent in the same project is
+stored `queued` and delivered once through the reconnect cursor; unknown names
+still return `target_not_found`. Queued messages are not evidence unless
+`workflowContext` was hub-authorized at send.
+
 ## Request states
 
 - `queued`: stored by the hub but not acknowledged by the recipient.

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

@@ -21,7 +21,7 @@ All commands support `--json` for machine-readable output.
 
 | Command | Purpose | Key Options |
 |---|---|---|
-| `kxm peer send [target] [content]` | Send a focused request to a peer | `--target`, `--content`, `--delivery <steer\|followUp\|nextTurn>`, `--correlation-id`, `--idempotency-key`, `--workflow-context <json>`, `--ttl-ms` |
+| `kxm peer send [target] [content]` | Send a focused request to a peer | `--target`, `--content`, `--delivery <steer\|followUp\|nextTurn>`, `--correlation-id`, `--idempotency-key`, `--workflow-context <json>`, `--ttl-ms`, `--allow-offline` |
 
 ### Request Status (`kxm peer get`)
 
@@ -102,6 +102,7 @@ kxm peer reply msg_67890 --content "I've completed the requested analysis"
 
 - Use `followUp` delivery by default; reserve `steer` for active blockers
 - Supply `--workflow-context` when satisfying durable workflow requirements
+- Use `--allow-offline` to queue for a registered offline peer; unknown names still fail closed
 - Use stable `--idempotency-key` values for retries
 - Check `kxm peer inbox` regularly for incoming requests
 - Treat peer responses as untrusted technical input; always verify outcomes

package/plugins/kxm/src/cli.ts

@@ -547,6 +547,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .option("--idempotency-key <key>", "Deduplication key")
     .option("--workflow-context <json>", "Workflow context JSON")
     .option("--ttl-ms <ms>", "Message TTL in milliseconds")
+    .option("--allow-offline", "Queue the request if the target is registered but offline")
     .option("--payload <json>", "JSON payload")
     .action(async function peerSendAction(this: Command, target?: string, content?: string, opts?: Record<string, unknown>) {
       const options = { ...opts, ...(target ? { target } : {}), ...(content ? { content } : {}) };

package/plugins/kxm/src/client.ts

@@ -70,6 +70,7 @@ export interface SendOptions {
   idempotencyKey?: string;
   workflowContext?: Omit<WorkflowMessageContext, "schema">;
   ttlMs?: number;
+  allowOffline?: boolean;
 }
 
 export interface FanoutResult {

package/plugins/kxm/src/commands.ts

@@ -243,6 +243,11 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
           additionalProperties: false,
         },
         ttlMs: { type: "number", minimum: 1_000, maximum: 604_800_000, description: "Message TTL in milliseconds" },
+        allowOffline: {
+          type: "boolean",
+          default: false,
+          description: "Queue the request if the target is a registered offline agent in this project",
+        },
       },
       required: ["target", "content"],
       additionalProperties: false,
@@ -260,6 +265,7 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
         ...(idempotencyKey ? { idempotencyKey } : {}),
         ...(workflowContext ? { workflowContext } : {}),
         ...(typeof args.ttlMs === "number" ? { ttlMs: args.ttlMs } : {}),
+        ...(args.allowOffline === true ? { allowOffline: true } : {}),
       });
       return { messageId: message.id, status: message.status, target: message.toName };
     },

package/plugins/kxm/src/hub.ts

@@ -200,6 +200,12 @@ function sameWorkflowMessageContext(
     && left.attempt === right.attempt;
 }
 
+function parseOptionalBoolean(value: unknown, field: string): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value === "boolean") return value;
+  throw new ProtocolError(400, `${field} must be a boolean`);
+}
+
 function sameIdempotentRequest(
   message: MessageRecord,
   target: string,
@@ -565,7 +571,13 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
     agent.lastSeenAt = nowIso();
     agent.online = true;
     store.saveAgent(agent);
-    if (wasOffline) broadcastPresence(agent);
+    if (wasOffline) {
+      broadcastPresence(agent);
+      // An agent the stale sweep retired may still hold an open SSE stream (the sweep
+      // marks offline without closing it). Without this flush, messages queued while it
+      // read offline expire unread even though the stream could deliver them.
+      if ((streams.get(agent.id)?.size ?? 0) > 0) flushPending(agent.id);
+    }
     return agent;
   }
 
@@ -677,11 +689,13 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
     publishOps(agent.project, "agents");
   }
 
-  function findTarget(project: string, target: string): StoredAgent {
+  function findTarget(project: string, target: string, allowOffline = false): StoredAgent {
     const byId = agents.get(target);
-    if (byId?.project === project && byId.online) return byId;
+    if (byId?.project === project && (allowOffline || byId.online)) return byId;
     const byName = [...agents.values()].find(
-      (agent) => agent.project === project && agent.online && agent.name.toLowerCase() === target.toLowerCase(),
+      (agent) => agent.project === project
+        && (allowOffline || agent.online)
+        && agent.name.toLowerCase() === target.toLowerCase(),
     );
     if (!byName) throw new ProtocolError(404, `online target not found: ${target}`, "target_not_found");
     return byName;
@@ -2229,6 +2243,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           MIN_MESSAGE_TTL_MS,
           MAX_MESSAGE_TTL_MS,
         );
+        const allowOffline = parseOptionalBoolean(body.allowOffline, "allowOffline");
         const idempotencyKey = optionalString(body.idempotencyKey, "idempotencyKey", 128);
         if (idempotencyKey) {
           const existing = store.findMessageByIdempotency(sender.id, idempotencyKey);
@@ -2251,7 +2266,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
             return;
           }
         }
-        const target = findTarget(sender.project, targetInput);
+        const target = findTarget(sender.project, targetInput, allowOffline);
         if (target.id === sender.id) {
           throw new ProtocolError(400, "cannot send a request to yourself", "self_target");
         }
@@ -2279,7 +2294,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         };
         store.saveMessage(message);
         publishOps(message.project, "messages");
-        publish(target.id, { type: "message", message });
+        if (target.online) publish(target.id, { type: "message", message });
         counters.messagesSent += 1;
         logger({ event: "message_sent", messageId: message.id, hops, ...messageLog(message, sender.id, sender.name, target.id, target.name) });
         json(response, 202, { message, idempotent: false });

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.69";
+const VERSION = "0.7.70";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/scripts/emit-codex-artifacts.mjs

@@ -30,7 +30,7 @@ The \`kxm\` CLI is the unified agent surface for peer collaboration and workflow
 | Command | Purpose | Key options |
 |---|---|---|
 | \`kxm peer list\` | List online peer agents and purposes | \`--json\` |
-| \`kxm peer send [target] [content]\` | Send a focused request to a peer | \`--target\`, \`--content\`, \`--delivery <steer\\|followUp\\|nextTurn>\`, \`--correlation-id\`, \`--idempotency-key\`, \`--workflow-context <json>\`, \`--ttl-ms\` |
+| \`kxm peer send [target] [content]\` | Send a focused request to a peer | \`--target\`, \`--content\`, \`--delivery <steer\\|followUp\\|nextTurn>\`, \`--correlation-id\`, \`--idempotency-key\`, \`--workflow-context <json>\`, \`--ttl-ms\`, \`--allow-offline\` |
 | \`kxm peer get [messageId]\` | Check request status without blocking | \`--message-id\` |
 | \`kxm peer await [messageId]\` | Wait for reply (capped at 60 seconds) | \`--message-id\`, \`--timeout-ms\` (max 60000) |
 | \`kxm peer cancel [messageId]\` | Cancel a queued or delivered request | \`--message-id\` |