@kontextmind/kxm 0.7.69 → 0.7.71

package/plugins/kxm/src/protocol.ts

@@ -12,21 +12,62 @@ export const DEFAULT_RATE_LIMIT_MAX = 600;
 export const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
 export const MAX_BODY_BYTES = 256 * 1024;
 export const MAX_CONTENT_CHARS = 32_000;
+export const MAX_AGENT_HOST_CHARS = 64;
 
 export type DeliveryMode = "steer" | "followUp" | "nextTurn";
 export type MessageStatus = "queued" | "delivered" | "replied" | "cancelled" | "expired" | "error";
+export type AgentPresence = "online" | "stale" | "offline";
 
-export interface AgentRecord {
+/** The durable half of an agent: exactly the fields the hub persists in the
+ * agents record JSON. Presence is never stored, so a restored database can
+ * never claim an agent was alive. */
+export interface AgentIdentity {
   id: string;
   name: string;
   purpose: string;
   project: string;
   model?: string;
+  /** Client-declared label for the box this agent runs on. It exists so a
+   * reader can tell two boxes apart; the hub never reads it for
+   * authorization, project scope, or target resolution. */
+  host?: string;
   connectedAt: string;
   lastSeenAt: string;
   online: boolean;
 }
 
+/** The public projection of an agent: durable identity plus presence derived
+ * from the hub clock at read time. */
+export interface AgentRecord extends AgentIdentity {
+  /** `lastSeenAt + staleAfterMs`: the heartbeat lease the stale sweep enforces.
+   * Absent when projected from the local store without the hub's clock or lease. */
+  leaseExpiresAt?: string;
+  /** Hub-clocked presence. Absent when the reader has no hub projection. */
+  presence?: AgentPresence;
+}
+
+/** Presence is hub-clocked and never client-reported. An agent holds its lease
+ * until `lastSeenAt + staleAfterMs`; between lease expiry and the sweep that
+ * retires it, it reads `stale`; once retired it reads `offline`. An
+ * unparseable `lastSeenAt` leaves the lease at the epoch, which reads as an
+ * expired lease rather than as a live agent. */
+export function agentPresenceView(
+  agent: AgentIdentity,
+  staleAfterMs: number = DEFAULT_STALE_AFTER_MS,
+  now: number = Date.now(),
+): { leaseExpiresAt: string; presence: AgentPresence } {
+  const lastSeenMs = Date.parse(agent.lastSeenAt);
+  const leaseExpiresAtMs = (Number.isFinite(lastSeenMs) ? lastSeenMs : 0) + staleAfterMs;
+  const leaseExpiresAt = new Date(leaseExpiresAtMs).toISOString();
+  if (!agent.online) return { leaseExpiresAt, presence: "offline" };
+  return { leaseExpiresAt, presence: now < leaseExpiresAtMs ? "online" : "stale" };
+}
+
+/** Project a durable identity onto the wire shape readers consume. */
+export function toAgentRecord(agent: AgentIdentity, staleAfterMs?: number, now?: number): AgentRecord {
+  return { ...agent, ...agentPresenceView(agent, staleAfterMs, now) };
+}
+
 export interface MessageReply {
   content: string;
   createdAt: string;

package/plugins/kxm/src/store.ts

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import type { DatabaseSync } from "./sqlite.ts";
-import type { AgentRecord, MessageRecord } from "./protocol.ts";
+import type { AgentIdentity, MessageRecord } from "./protocol.ts";
 import type { ContextItem } from "./context.ts";
 import type { WorkflowJournalEntry, WorkflowRun } from "./workflow.ts";
 import {
@@ -78,7 +78,10 @@ export const HUB_STORE_SCHEMA_SPEC: DatabaseSchemaSpec = Object.freeze({
   tables: HUB_STORE_TABLES,
 });
 
-export interface StoredAgent extends AgentRecord {
+/** The stored shape stays the durable identity plus the agent key: presence
+ * and the lease are derived on read, so the agents record JSON grows only by
+ * the additive `host` label. */
+export interface StoredAgent extends AgentIdentity {
   key: string;
 }
 

package/plugins/kxm/src/tui.ts

@@ -310,6 +310,19 @@ function visibleAgents(snapshot: MeshTuiSnapshot): AgentRecord[] {
   return snapshot.agents.filter((agent) => agent.model !== "tui");
 }
 
+/** Presence comes from the hub clock, so the dash colours it rather than
+ * recomputing it: green holds a lease, amber has lost it but has not been
+ * swept, dim is a registered peer that is gone. */
+function presenceCell(agent: AgentRecord, theme: MeshTuiTheme, width = 7): string {
+  // Local-store projections carry no hub-clocked presence; the dash shows "n/a"
+  // rather than inventing a lease from the reader's clock.
+  const presence = agent.presence ?? "n/a";
+  const cell = pad(presence, width);
+  if (presence === "online") return theme.success(cell);
+  if (presence === "stale") return theme.warning(cell);
+  return theme.dim(cell);
+}
+
 function panelMetric(snapshot: MeshTuiSnapshot, panel: MeshTuiPanel): string {
   if (panel === "agents") {
     const agents = visibleAgents(snapshot);
@@ -441,7 +454,7 @@ function listLines(snapshot: MeshTuiSnapshot, view: MeshTuiView, theme: MeshTuiT
   const mark = (index: number) => cursor(theme, index === view.selected, "list", view.pane);
   if (view.tab === "agents") {
     return visibleAgents(snapshot).map((agent, index) => (
-      `${mark(index)}${pad(agent.name, 14)} ${agent.online ? theme.success(pad("yes", 3)) : theme.dim(pad("no", 3))} ${pad(agent.model ?? "-", 18)} ${pad(age(agent.lastSeenAt, now), 4)}`
+      `${mark(index)}${pad(agent.name, 14)} ${presenceCell(agent, theme)} ${pad(agent.host ?? "-", 12)} ${pad(agent.model ?? "-", 14)} ${pad(age(agent.lastSeenAt, now), 4)}`
     ));
   }
   if (view.tab === "tasks" || view.tab === "workflows") {
@@ -489,9 +502,10 @@ function detailLines(snapshot: MeshTuiSnapshot, view: MeshTuiView, theme: MeshTu
     const related = snapshot.openMessages.filter((message) => message.fromName === agent.name || message.toName === agent.name);
     return [
       theme.accent(agent.name),
-      `${agent.online ? theme.success("online") : theme.dim("offline")}  ${agent.model ?? "-"}`,
+      `${presenceCell(agent, theme, (agent.presence ?? "n/a").length)}  ${agent.model ?? "-"}`,
+      `host ${agent.host ?? "-"}`,
       agent.purpose,
-      `seen ${age(agent.lastSeenAt, now)} ago`,
+      `seen ${age(agent.lastSeenAt, now)} ago · lease ${agent.leaseExpiresAt?.slice(11, 19) ?? "n/a"} UTC`,
       "",
       theme.dim("Open work"),
       ...(related.length === 0 ? [theme.dim("none")] : related.map((message) => `${message.status}  ${message.fromName} → ${message.toName}  ${age(message.createdAt, now)}`)),
@@ -875,7 +889,9 @@ export async function runMeshTui(input: {
     }
     if (!useOpsStream && identity) {
       try {
-        const listed = await input.fetchImpl(`${base}/v1/agents`, { headers: headers(identity) });
+        // Offline members too: the ops snapshot lists the whole project, and
+        // the legacy path is a fallback for the same screen, not a narrower one.
+        const listed = await input.fetchImpl(`${base}/v1/agents?includeOffline=true`, { headers: headers(identity) });
         if (listed.ok) {
           const body = await readJson<{ agents: AgentRecord[] }>(listed);
           const byId = new Map(local.agents.map((agent) => [agent.id, agent]));

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\` |