@kontextmind/kxm 0.7.70 → 0.7.72

package/plugins/kxm/src/hub.ts

@@ -4,15 +4,20 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { isIP } from "node:net";
 import { dirname, join, resolve } from "node:path";
 import {
+  DEFAULT_LEASE_TTL_MS,
   DEFAULT_MAX_HOPS,
   DEFAULT_MESSAGE_RETENTION_MS,
   DEFAULT_MESSAGE_TTL_MS,
   DEFAULT_RATE_LIMIT_MAX,
   DEFAULT_RATE_LIMIT_WINDOW_MS,
   DEFAULT_STALE_AFTER_MS,
+  MAX_AGENT_HOST_CHARS,
   MAX_BODY_BYTES,
   MAX_CONTENT_CHARS,
+  MAX_LEASE_RESOURCE_CHARS,
+  MAX_LEASE_TTL_MS,
   MAX_MESSAGE_TTL_MS,
+  MIN_LEASE_TTL_MS,
   MIN_MESSAGE_TTL_MS,
   MIN_MESSAGE_RETENTION_MS,
   ProtocolError,
@@ -22,9 +27,11 @@ import {
   parseBoundedInteger,
   parseDeliveryMode,
   requireString,
+  toAgentRecord,
   type AgentRecord,
   type DeliveryMode,
   type HubEvent,
+  type LeaseRecord,
   type MessageRecord,
   type WorkflowMessageContext,
 } from "./protocol.ts";
@@ -37,7 +44,7 @@ import { NativeStateProvider } from "./state.ts";
 import { SkillLifecycle } from "./skills.ts";
 import { compileKnowledgeWiki, lintKnowledgeWiki, type WikiSourcePool } from "./wiki.ts";
 import { buildRetrospective, writeRetrospective } from "./retrospective.ts";
-import { MeshStore, type StoredAgent } from "./store.ts";
+import { MeshStore, type LeaseRefusal, type StoredAgent } from "./store.ts";
 import {
   canonicalWorkflowEvidenceKey,
   approveWorkflowDegradation,
@@ -89,6 +96,10 @@ export interface MeshHubOptions {
   skillsDir?: string;
   skillLifecycle?: SkillLifecycle;
   repoRoot?: string;
+  /** The hub clock every lease decision reads. Injectable so a test can move a
+   * lease past its deadline instead of sleeping through a real TTL; production
+   * leaves it at `Date.now`. It is never a client-supplied time. */
+  now?: () => number;
 }
 
 export interface MeshHub {
@@ -118,15 +129,50 @@ function isLoopback(host: string): boolean {
   return isIP(host) === 4 && host.startsWith("127.");
 }
 
-function publicAgent(agent: StoredAgent): AgentRecord {
-  const { key: _key, ...record } = agent;
-  return record;
+/** Drop the agent key and attach hub-clocked presence. Every caller passes the
+ * hub's own `staleAfterMs` and clock, so no reader ever sees a lease derived
+ * from a client timestamp. */
+function publicAgent(agent: StoredAgent, staleAfterMs: number, now = Date.now()): AgentRecord {
+  const { key: _key, ...identity } = agent;
+  return toAgentRecord(identity, staleAfterMs, now);
 }
 
 function safeTokenEqual(actual: string | undefined, expected: string): boolean {
   return timingSafeStringCompare(actual, expected);
 }
 
+/** The wire answer for a lease the hub will not extend or release. Every one of
+ * these means the caller's token no longer authorizes a shared write: the
+ * holder must stop, not retry. The current lease rides along so the caller can
+ * record who holds the resource now. */
+function leaseRefusal(reason: LeaseRefusal, name: string, lease?: LeaseRecord): ProtocolError {
+  if (reason === "missing") {
+    return new ProtocolError(404, `no lease is held on ${name}`, "lease_not_found");
+  }
+  if (reason === "expired") {
+    return new ProtocolError(
+      409,
+      `lease on ${name} expired at ${lease?.expiresAt ?? "its deadline"}; re-acquire to take it over`,
+      "lease_expired",
+      { lease },
+    );
+  }
+  if (reason === "held") {
+    return new ProtocolError(
+      409,
+      `lease on ${name} is held by ${lease?.holderAgentName ?? "another agent"} until ${lease?.expiresAt ?? "its deadline"}`,
+      "lease_held",
+      { lease },
+    );
+  }
+  return new ProtocolError(
+    409,
+    `fencing token for ${name} was superseded; the hub is now at token ${lease?.fencingToken ?? "a newer value"}`,
+    "lease_superseded",
+    { lease },
+  );
+}
+
 function bearerToken(request: IncomingMessage): string | undefined {
   const header = request.headers.authorization;
   return header?.startsWith("Bearer ") ? header.slice(7) : undefined;
@@ -404,6 +450,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       };
   const webhookWorkflows = new Map((options.webhookWorkflows ?? []).map((workflow) => [workflow.id, workflow]));
   const logger = options.logger ?? (() => undefined);
+  const hubNow = options.now ?? (() => Date.now());
   const assetsDir = options.assetsDir;
   const hubRepoRoot = options.repoRoot ?? (options.dataPath && options.dataPath !== ":memory:" ? resolve(dirname(dirname(options.dataPath))) : process.cwd());
   const store = new MeshStore(options.dataPath);
@@ -456,6 +503,9 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
     contextRequests: 0,
     attemptLatencySecondsTotal: 0,
     meteredCostUsdTotal: 0,
+    leasesGranted: 0,
+    leasesRefused: 0,
+    leasesReleased: 0,
   };
   let cleanupTimer: NodeJS.Timeout | undefined;
   let closed = false;
@@ -623,9 +673,10 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
   }
 
   function opsSnapshot(project: string) {
+    const snapshotAt = Date.now();
     const projectAgents = [...agents.values()]
       .filter((agent) => agent.project === project)
-      .map(publicAgent)
+      .map((agent) => publicAgent(agent, staleAfterMs, snapshotAt))
       .sort((left, right) => Number(right.online) - Number(left.online) || left.name.localeCompare(right.name));
     const open = store.getOpenMessages(project);
     const projectRuns = [...workflowRuns.values()]
@@ -683,7 +734,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
   function broadcastPresence(agent: StoredAgent): void {
     for (const candidate of agents.values()) {
       if (candidate.project === agent.project && candidate.id !== agent.id && candidate.online) {
-        publish(candidate.id, { type: "presence", agent: publicAgent(agent) });
+        publish(candidate.id, { type: "presence", agent: publicAgent(agent, staleAfterMs) });
       }
     }
     publishOps(agent.project, "agents");
@@ -1059,6 +1110,16 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
     for (const runId of swept.purgedRuns) {
       logger({ event: "workflow_run_purged", runId });
     }
+    for (const lease of swept.purgedLeases) {
+      logger({
+        event: "lease_purged",
+        resource: lease.resource,
+        project: lease.project,
+        agentId: lease.holderAgentId,
+        fencingToken: lease.fencingToken,
+        expiresAt: lease.expiresAt,
+      });
+    }
   }
 
   function metricsBody(): string {
@@ -1106,6 +1167,12 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       `kxm_attempt_latency_seconds_total ${counters.attemptLatencySecondsTotal}`,
       "# TYPE kxm_metered_cost_usd_total counter",
       `kxm_metered_cost_usd_total ${counters.meteredCostUsdTotal}`,
+      "# TYPE kxm_leases_granted_total counter",
+      `kxm_leases_granted_total ${counters.leasesGranted}`,
+      "# TYPE kxm_leases_refused_total counter",
+      `kxm_leases_refused_total ${counters.leasesRefused}`,
+      "# TYPE kxm_leases_released_total counter",
+      `kxm_leases_released_total ${counters.leasesReleased}`,
       "",
     ].join("\n");
   }
@@ -2109,6 +2176,9 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         const project = requireString(body.project, "project", { max: 128 });
         requireProjectAuth(request, project);
         const model = optionalString(body.model, "model", 128);
+        // A client declares which box it runs on. The label is a reading aid
+        // only: the project token is still the whole of admission.
+        const hostLabel = optionalString(body.host, "host", MAX_AGENT_HOST_CHARS);
         const existing = [...agents.values()].find(
           (agent) => agent.project === project && agent.name.toLowerCase() === name.toLowerCase(),
         );
@@ -2135,20 +2205,34 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         agent.online = true;
         if (model) agent.model = model;
         else delete agent.model;
+        if (hostLabel) agent.host = hostLabel;
+        else delete agent.host;
         store.saveAgent(agent);
         counters.registrations += 1;
-        logger({ event: existing ? "agent_resumed" : "agent_registered", agentId: agent.id, name, project });
+        logger({
+          event: existing ? "agent_resumed" : "agent_registered",
+          agentId: agent.id,
+          name,
+          project,
+          ...(hostLabel ? { host: hostLabel } : {}),
+        });
         broadcastPresence(agent);
-        json(response, existing ? 200 : 201, { agent: publicAgent(agent), agentKey: agent.key, resumed: Boolean(existing) });
+        json(response, existing ? 200 : 201, { agent: publicAgent(agent, staleAfterMs), agentKey: agent.key, resumed: Boolean(existing) });
         return;
       }
 
       if (method === "GET" && url.pathname === "/v1/agents") {
         const current = requireAgent(request);
         requireProjectAuth(request, current.project);
+        // Offline members are registered peers of the caller's own project
+        // whose lease the sweep has already retired. They stay out of the
+        // list unless a caller asks for them, so discovery keeps meaning
+        // "who can answer right now".
+        const includeOffline = url.searchParams.get("includeOffline") === "true";
+        const listedAt = Date.now();
         const result = [...agents.values()]
-          .filter((agent) => agent.project === current.project && agent.online)
-          .map(publicAgent);
+          .filter((agent) => agent.project === current.project && (agent.online || includeOffline))
+          .map((agent) => publicAgent(agent, staleAfterMs, listedAt));
         json(response, 200, { agents: result });
         return;
       }
@@ -2158,7 +2242,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         const current = requireAgent(request, decodeURIComponent(heartbeatMatch[1]!));
         requireProjectAuth(request, current.project);
         await readJson(request);
-        json(response, 200, { agent: publicAgent(current) });
+        json(response, 200, { agent: publicAgent(current, staleAfterMs) });
         return;
       }
 
@@ -2175,6 +2259,81 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         return;
       }
 
+      // One writer, one clock. Every branch below decides inside a single store
+      // transaction, so two agents racing for the same resource cannot both read it
+      // free. The fencing token increments only on takeover, which is what lets a
+      // holder that slept past its deadline be refused at commit instead of writing
+      // behind whoever replaced it.
+      const leaseMatch = url.pathname.match(/^\/v1\/leases\/([^/]+)\/(acquire|renew|release)$/);
+      if (method === "POST" && leaseMatch) {
+        const holder = requireAgent(request);
+        requireProjectAuth(request, holder.project);
+        const name = requireString(decodeURIComponent(leaseMatch[1]!), "resource", { max: MAX_LEASE_RESOURCE_CHARS });
+        const action = leaseMatch[2]!;
+        const body = await readJson(request);
+        // The caller never names the prefix, so the same branch in two projects is
+        // two leases and neither project can reach the other's.
+        const resource = `${holder.project}/${name}`;
+        const nowMs = hubNow();
+        const leaseLog = { resource, project: holder.project, agentId: holder.id, agentName: holder.name };
+
+        if (action === "acquire") {
+          const ttlMs = parseBoundedInteger(body.ttlMs, "ttlMs", DEFAULT_LEASE_TTL_MS, MIN_LEASE_TTL_MS, MAX_LEASE_TTL_MS);
+          const outcome = store.acquireLease({
+            resource,
+            project: holder.project,
+            name,
+            holderAgentId: holder.id,
+            holderAgentName: holder.name,
+            ttlMs,
+            nowMs,
+          });
+          if (!outcome.ok) {
+            counters.leasesRefused += 1;
+            logger({ event: "lease_denied", ...leaseLog, reason: outcome.reason, heldBy: outcome.lease?.holderAgentId });
+            throw leaseRefusal(outcome.reason, name, outcome.lease);
+          }
+          counters.leasesGranted += 1;
+          logger({
+            event: outcome.renewed ? "lease_renewed" : "lease_acquired",
+            ...leaseLog,
+            fencingToken: outcome.lease.fencingToken,
+            expiresAt: outcome.lease.expiresAt,
+          });
+          json(response, 200, { lease: outcome.lease, renewed: outcome.renewed });
+          return;
+        }
+
+        if (body.fencingToken === undefined) {
+          throw new ProtocolError(400, "fencingToken is required", "lease_token_required");
+        }
+        const fencingToken = parseBoundedInteger(body.fencingToken, "fencingToken", 1, 1, Number.MAX_SAFE_INTEGER);
+        if (action === "renew") {
+          const ttlMs = parseBoundedInteger(body.ttlMs, "ttlMs", DEFAULT_LEASE_TTL_MS, MIN_LEASE_TTL_MS, MAX_LEASE_TTL_MS);
+          const outcome = store.renewLease({ resource, holderAgentId: holder.id, fencingToken, ttlMs, nowMs });
+          if (!outcome.ok) {
+            counters.leasesRefused += 1;
+            logger({ event: "lease_denied", ...leaseLog, reason: outcome.reason, fencingToken });
+            throw leaseRefusal(outcome.reason, name, outcome.lease);
+          }
+          counters.leasesGranted += 1;
+          logger({ event: "lease_renewed", ...leaseLog, fencingToken, expiresAt: outcome.lease.expiresAt });
+          json(response, 200, { lease: outcome.lease, renewed: true });
+          return;
+        }
+
+        const outcome = store.releaseLease({ resource, holderAgentId: holder.id, fencingToken });
+        if (!outcome.ok) {
+          counters.leasesRefused += 1;
+          logger({ event: "lease_denied", ...leaseLog, reason: outcome.reason, fencingToken });
+          throw leaseRefusal(outcome.reason, name, outcome.lease);
+        }
+        counters.leasesReleased += 1;
+        logger({ event: "lease_released", ...leaseLog, fencingToken });
+        json(response, 200, { released: true, lease: outcome.lease });
+        return;
+      }
+
       if (method === "GET" && url.pathname === "/v1/events") {
         const agentId = requireString(url.searchParams.get("agentId"), "agentId", { max: 80 });
         const current = requireAgent(request, agentId);
@@ -2191,7 +2350,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           "x-content-type-options": "nosniff",
           ...(presenceOnly ? { "x-kxm-events-mode": "presence" } : {}),
         });
-        response.write(`event: ready\ndata: ${JSON.stringify({ agent: publicAgent(current) })}\n\n`);
+        response.write(`event: ready\ndata: ${JSON.stringify({ agent: publicAgent(current, staleAfterMs) })}\n\n`);
         const client: SseClient = {
           response,
           heartbeat: setInterval(() => response.write(": heartbeat\n\n"), 15_000),

package/plugins/kxm/src/local-snapshot.ts

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
-import type { AgentRecord, MessageRecord } from "./protocol.ts";
+import type { AgentIdentity, AgentRecord, MessageRecord } from "./protocol.ts";
 import type { WorkflowRun } from "./workflow.ts";
 import { readRoutingRecords } from "./telemetry.ts";
 import type { RoutingRecord, RoutingRecordV2 } from "./routing.ts";
@@ -253,7 +253,15 @@ export function loadLocalMeshSnapshot(
     const database = new DatabaseSync(dataPath, { readOnly: true });
     try {
       database.exec("PRAGMA busy_timeout = 5000");
-      agents = readJsonRows<AgentRecord>(database, "SELECT record FROM agents");
+      // Stored rows carry identity only. Presence is derived here against the
+      // default lease window, because the hub's configured `staleAfterMs` is
+      // not in the file; a reachable hub's own records replace these.
+      // Stored rows carry identity only. Presence is NOT computed here: the hub's
+      // configured staleAfterMs and its clock are not in the file, so a reader-side
+      // lease would mislabel agents against the hub's own projection. The stored
+      // `online` boolean is the only durable truth; the hub's /v1/agents or the
+      // ops snapshot is the authoritative presence source.
+      agents = readJsonRows<AgentIdentity>(database, "SELECT record FROM agents");
       openMessages = readOpenMessageMetadata(database);
       openMessageTotal = countRows(database, "messages", " WHERE json_extract(record, '$.status') IN ('queued', 'delivered')");
       legacyRuns = readJsonRows<WorkflowRun>(database, "SELECT record FROM workflow_runs ORDER BY rowid DESC LIMIT 8");

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

package/plugins/kxm/src/protocol.ts

@@ -12,21 +12,87 @@ 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 const MIN_LEASE_TTL_MS = 5_000;
+export const MAX_LEASE_TTL_MS = 10 * 60_000;
+export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
+export const MAX_LEASE_RESOURCE_CHARS = 200;
 
 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) };
+}
+
+/** One hub-held fenced lease over a project-scoped resource.
+ *
+ * `resource` is what the store keys on: the caller's project prefixed onto the
+ * name it asked for, so two projects naming the same branch never contend.
+ * Expiry is the hub's clock, never the holder's, and `fencingToken` increments
+ * only when a new holder takes over an expired lease — a renewal keeps its
+ * token, so a writer that comes back after a takeover can be told its token
+ * was superseded instead of being allowed to commit. */
+export interface LeaseRecord {
+  /** `${project}/${name}`. */
+  resource: string;
+  project: string;
+  /** The resource as the caller named it, without the project prefix. */
+  name: string;
+  holderAgentId: string;
+  holderAgentName: string;
+  fencingToken: number;
+  acquiredAt: string;
+  expiresAt: string;
+}
+
 export interface MessageReply {
   content: string;
   createdAt: string;