@kontextmind/kxm 0.7.71 → 0.7.73

package/plugins/kxm/package.json

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

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

@@ -87,6 +87,24 @@ 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.
 
+## Fenced leases
+
+- `POST /v1/leases/:resource/acquire` takes or extends the lease over a
+  resource. Body `{ttlMs}` is bounded to 5 s–10 min. A live lease held by
+  another agent returns `409 lease_held` with the current holder and token.
+- `POST /v1/leases/:resource/renew` extends a lease under the token it was
+  issued. Body `{fencingToken, ttlMs?}`.
+- `POST /v1/leases/:resource/release` gives the resource back. Body
+  `{fencingToken}`.
+
+All three are agent-authenticated and project-scoped: the hub prefixes the
+caller's project onto `:resource`, so the same name in two projects is two
+leases. Every decision is a compare-and-set on the hub clock inside one store
+transaction. The fencing token starts at 1, is unchanged by renewal, and
+increments only when a new holder takes over an expired lease; a stale token
+returns `409 lease_superseded` with the token the hub now holds. Present the
+token before committing anything shared — a refusal means stop, not retry.
+
 ## Request states
 
 - `queued`: stored by the hub but not acknowledged by the recipient.

package/plugins/kxm/src/client.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { hostname } from "node:os";
 import { MAX_AGENT_HOST_CHARS } from "./protocol.ts";
-import type { AgentRecord, DeliveryMode, HubEvent, MessageRecord, WorkflowMessageContext } from "./protocol.ts";
+import type { AgentRecord, DeliveryMode, HubEvent, LeaseRecord, MessageRecord, WorkflowMessageContext } from "./protocol.ts";
 import type { ContextAuthority, ContextConfidence, ContextItem, ContextItemAuditMetadata, ContextItemKind, ContextPacket } from "./context.ts";
 import {
   canonicalWorkflowEvidenceKey,
@@ -341,6 +341,41 @@ export class HubClient {
     return result.message;
   }
 
+  // ----- Fenced leases over shared resources (P3) -----
+
+  /**
+   * Take or extend the lease over `resource` inside this client's project.
+   *
+   * The returned `fencingToken` is the whole point: hold it, present it on every
+   * renewal, and present it again before committing anything shared. A hub that
+   * has moved past it refuses, and the caller must stop rather than retry —
+   * another holder owns the resource now. Rejects `HubHttpError` with code
+   * `lease_held` when a live holder has it.
+   */
+  async acquireLease(resource: string, ttlMs?: number): Promise<{ lease: LeaseRecord; renewed: boolean }> {
+    return await this.request(`/v1/leases/${encodeURIComponent(resource)}/acquire`, {
+      method: "POST",
+      body: JSON.stringify(ttlMs === undefined ? {} : { ttlMs }),
+    });
+  }
+
+  /** Extend a lease this client holds. The token never changes on renewal; a
+   * `lease_superseded` or `lease_expired` refusal means it is gone. */
+  async renewLease(resource: string, fencingToken: number, ttlMs?: number): Promise<{ lease: LeaseRecord }> {
+    return await this.request(`/v1/leases/${encodeURIComponent(resource)}/renew`, {
+      method: "POST",
+      body: JSON.stringify(ttlMs === undefined ? { fencingToken } : { fencingToken, ttlMs }),
+    });
+  }
+
+  /** Give the resource back. */
+  async releaseLease(resource: string, fencingToken: number): Promise<{ released: boolean; lease: LeaseRecord }> {
+    return await this.request(`/v1/leases/${encodeURIComponent(resource)}/release`, {
+      method: "POST",
+      body: JSON.stringify({ fencingToken }),
+    });
+  }
+
   async listWorkflows(): Promise<WorkflowRun[]> {
     const result = await this.request<{ runs: WorkflowRun[] }>("/v1/workflows");
     return result.runs;
@@ -597,15 +632,27 @@ export class HubClient {
   }
 
   private async request<T = unknown>(path: string, init: RequestInit = {}, includeIdentity = true): Promise<T> {
-    const requestTimeoutMs = this.options.requestTimeoutMs ?? 15_000;
+    return await hubJsonRequest<T>(this.options, path, init, this.headers(includeIdentity));
+  }
+}
+
+/** One JSON request to the hub with a bounded timeout. A non-2xx answer
+ * becomes a `HubHttpError` carrying the hub's code and next-action hints. */
+async function hubJsonRequest<T>(
+  options: { serverUrl: string; requestTimeoutMs?: number; fetchImpl?: typeof fetch },
+  path: string,
+  init: RequestInit,
+  headers: Record<string, string>,
+): Promise<T> {
+    const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
     const timeoutSignal = AbortSignal.timeout(requestTimeoutMs);
     const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
     let response: Response;
     try {
-      response = await (this.options.fetchImpl ?? fetch)(`${this.options.serverUrl.replace(/\/$/, "")}${path}`, {
+      response = await (options.fetchImpl ?? fetch)(`${options.serverUrl.replace(/\/$/, "")}${path}`, {
         ...init,
         signal,
-        headers: { ...this.headers(includeIdentity), ...(init.headers ?? {}) },
+        headers: { ...headers, ...(init.headers ?? {}) },
       });
     } catch (error) {
       if (timeoutSignal.aborted) throw new Error(`request timed out after ${requestTimeoutMs}ms`);
@@ -625,6 +672,9 @@ export class HubClient {
       for (const key of ["operation", "nextAction", "assignedCoordinatorName"]) {
         if (typeof body[key] === "string") extras[key] = body[key];
       }
+      // A lease refusal carries the lease that won, so the loser can record who
+      // holds the resource and at which token instead of guessing.
+      if (body.lease && typeof body.lease === "object") extras.lease = body.lease;
       throw new HubHttpError(
         response.status,
         String(body.error ?? `HTTP ${response.status}`),
@@ -634,5 +684,75 @@ export class HubClient {
       );
     }
     return body as T;
+}
+
+export interface RuntimeHubClientOptions {
+  serverUrl: string;
+  /** The hub project this Runtime reports into; its token is the admission. */
+  project: string;
+  authToken?: string;
+  runtimeId: string;
+  /** Box label; defaults to the hostname. Never used for authorization. */
+  host?: string;
+  requestTimeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+export interface RuntimePresenceView {
+  runtimeId: string;
+  host?: string;
+  registeredAt: string;
+  heartbeatAt: string;
+  leaseExpiresAt: string;
+  presence: "online" | "expired";
+}
+
+export interface SyncPushResult {
+  projectId?: string;
+  runId?: string;
+  sequence?: number;
+  outcome: "accepted" | "duplicate" | "conflict" | "rejected";
+  code?: string;
+}
+
+export interface SyncPushResponse {
+  results: SyncPushResult[];
+  cursors: Array<{ projectId: string; runId: string; cursor: number }>;
+}
+
+/**
+ * The Runtime's machine client for one hub project (P5). It registers
+ * presence and pushes derived sync events outbound; the hub never calls the
+ * Runtime back. No agent identity, no message verbs.
+ */
+export class RuntimeHubClient {
+  readonly options: RuntimeHubClientOptions;
+
+  constructor(options: RuntimeHubClientOptions) {
+    this.options = options;
+  }
+
+  async heartbeat(): Promise<RuntimePresenceView> {
+    const result = await this.request<{ presence: RuntimePresenceView }>("/v1/runtime/presence", {
+      project: this.options.project,
+      runtimeId: this.options.runtimeId,
+      host: this.options.host ?? defaultHostLabel(),
+    });
+    return result.presence;
+  }
+
+  /** Push already-derived `kxm.sync-event.v1` objects, in outbox order. */
+  async pushSyncEvents(events: readonly unknown[]): Promise<SyncPushResponse> {
+    return await this.request<SyncPushResponse>("/v1/sync/events", {
+      project: this.options.project,
+      runtimeId: this.options.runtimeId,
+      events,
+    });
+  }
+
+  private async request<T>(path: string, body: unknown): Promise<T> {
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    if (this.options.authToken) headers.authorization = `Bearer ${this.options.authToken}`;
+    return await hubJsonRequest<T>(this.options, path, { method: "POST", body: JSON.stringify(body) }, headers);
   }
 }

package/plugins/kxm/src/database.ts

@@ -591,7 +591,9 @@ export function discoverProjectStores(projectRoot: string, options: { hubDataPat
 
   const hubPath = options.hubDataPath ? resolve(options.hubDataPath) : join(root, ".kxm", "state", "kxm.db");
   if (existsSync(hubPath)) {
-    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: 3 });
+    // Must track HUB_STORE_SCHEMA_VERSION in store.ts: the hub's own fresh backup is
+    // restored through this ceiling, so a bump left behind here refuses it.
+    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: 5 });
   }
 
   const registryPath = join(root, ".kxm", "runtime", "registry.db");
@@ -613,7 +615,7 @@ export function discoverProjectStores(projectRoot: string, options: { hubDataPat
         stores.push({
           storeId: `events:${key}`,
           sourcePath: join(eventsDir, entry.name),
-          maxSupportedVersion: 4,
+          maxSupportedVersion: 6,
         });
       }
     }
@@ -727,14 +729,16 @@ export function restoreBackup(
       );
     }
 
-    let maxSupported = 3;
+    // The hub-store ceiling. Must track HUB_STORE_SCHEMA_VERSION in store.ts for the
+    // same reason as the events ceiling below.
+    let maxSupported = 5;
     if (store.storeId === "registry" || store.storeId === "binding-store") {
       maxSupported = 1;
     } else if (store.storeId.startsWith("events:")) {
       // Must track KXM_EVENT_STORE_SCHEMA_VERSION in runtime-store.ts. The pin is
       // the e6 backup/restore round-trip test: bump one without the other and it
       // refuses its own fresh backup.
-      maxSupported = 5;
+      maxSupported = 6;
     }
 
     let targetPath = store.sourcePath;