agents-can-communicate 0.3.1 → 0.4.0

package/node_modules/@agents-can-communicate/core/src/sync.mjs

@@ -2,10 +2,12 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 import { computeAttention } from "./attention.mjs";
 import { classifySessionPresence } from "./sessions.mjs";
+import { assertMessageId, messagePage } from "./message-pages.mjs";
+import { decisionView, isCurrentDecision } from "./decision-state.mjs";
 
 const DEFAULT_LIMIT = 100;
 const CURSOR = /^[0-9]{16}$/;
-const SCOPES = Object.freeze(["delta", "full"]);
+const SCOPES = Object.freeze(["delta", "full", "history"]);
 
 function assertScope(scope) {
   if (scope != null && !SCOPES.includes(scope)) {
@@ -25,9 +27,36 @@ function assertCursor(cursor) {
 export function createSyncService(ports, sessions) {
   const { store, clock, pidIsAlive } = ports;
 
+  async function history(input) {
+    const exact = input.messageId !== undefined;
+    if (input.current !== undefined && (typeof input.current !== "boolean"
+      || input.kind !== "decision" || exact)) {
+      throw new AccError(EXIT.USAGE, "current requires a decision history list, without message id");
+    }
+    if (exact && (input.cursor != null || input.limit !== undefined || input.kind !== undefined)) {
+      throw new AccError(EXIT.USAGE, "an exact history read cannot use cursor, limit, or type");
+    }
+    if (exact) assertMessageId(input.messageId);
+    const snapshot = await store.snapshot(input.workspaceId ?? store.workspaceId,
+      { kinds: ["message"] });
+    const messages = snapshot.messages.map(decisionView(snapshot.messages));
+    if (!exact) return messagePage(messages, input,
+      { include: message => input.current !== true || isCurrentDecision(message),
+        metadata: { scope: "history", view: "summary" } });
+    const message = messages.find(item => item.messageId === input.messageId);
+    if (message === undefined) {
+      throw new AccError(EXIT.DATA, "message is not in this workspace's history");
+    }
+    return { scope: "history", view: "message", items: [message], nextCursor: null };
+  }
+
   async function sync(input = {}) {
-    if (input.cursor != null) assertCursor(input.cursor);
     assertScope(input.scope);
+    if (input.scope === "history") return history(input);
+    if (input.messageId !== undefined || input.kind !== undefined || input.current !== undefined) {
+      throw new AccError(EXIT.USAGE, "message, type and current require history scope");
+    }
+    if (input.cursor != null) assertCursor(input.cursor);
     const workspaceId = input.workspaceId ?? store.workspaceId;
     const now = clock.now();
     const located = input.sessionId === undefined

package/node_modules/@agents-can-communicate/delivery-router/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/delivery-router",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/delivery-router/src/refresh-binding.mjs

@@ -0,0 +1,38 @@
+import { validateNativeHandshake } from "@agents-can-communicate/adapter-sdk";
+
+const MAX_REFRESH_LEASE_MS = 120_000;
+
+function sameBinding(current, expected, leaseUntil) {
+  return current !== null && current !== undefined
+    && (current.retiredAt === null || current.retiredAt === undefined)
+    && current.sessionId === expected.sessionId
+    && current.generation === expected.generation
+    && current.adapterId === expected.adapterId
+    && current.clientVersion === expected.clientVersion
+    && current.opaqueEndpointRef === expected.opaqueEndpointRef
+    && current.leaseUntil === leaseUntil;
+}
+
+export async function refreshExpiredBinding({ service, adapter, binding, runtimeDir,
+  platform, clock, timeoutMs = 750 }) {
+  if (typeof adapter?.refreshNativeSession !== "function") return false;
+  const now = Date.parse(clock.now());
+  if (!Number.isFinite(now)) return false;
+  try {
+    const handshake = await adapter.refreshNativeSession({ binding, runtimeDir, timeoutMs });
+    const validated = validateNativeHandshake(adapter, {
+      clientVersion: binding.clientVersion, platform, handshake,
+    });
+    if (!validated.ok || validated.opaqueEndpointRef !== binding.opaqueEndpointRef) return false;
+    const requestedLease = Date.parse(validated.leaseUntil);
+    if (!Number.isFinite(requestedLease) || requestedLease <= now) return false;
+    const leaseUntil = new Date(Math.min(requestedLease,
+      now + MAX_REFRESH_LEASE_MS)).toISOString();
+    await service.refreshDeliveryBinding({ sessionId: binding.sessionId,
+      generation: binding.generation, leaseUntil });
+    const current = await service.store?.ephemeral?.get("deliveryBinding", binding.sessionId);
+    return sameBinding(current, binding, leaseUntil);
+  } catch {
+    return false;
+  }
+}

package/node_modules/@agents-can-communicate/delivery-router/src/router.mjs

@@ -1,3 +1,5 @@
+import { refreshExpiredBinding } from "./refresh-binding.mjs";
+
 const SAFE_ERRORS = new Set(["ambiguous_recipient_sessions", "delivery_disabled",
   "recipient_busy", "recipient_unavailable", "transport_error", "transport_rejected",
   "unsupported_client_version"]);
@@ -13,6 +15,7 @@ const adaptersById = adapters => adapters instanceof Map
 // transfers it. A note informs and waits for the next turn. Room messages
 // have no recipient and are never offered live.
 const ACTIONABLE = new Set(["question", "request", "answer", "decision", "handoff"]);
+const LIVE_POLICIES = new Set(["off", "actionable", "all"]);
 const permits = (policy, kind) => policy === "all"
   || (policy === "actionable" && ACTIONABLE.has(kind));
 
@@ -39,9 +42,22 @@ function safeTransport(value, opaqueEndpointRef) {
   return opaqueEndpointRef === "live-adapter" ? "native-live" : "live-adapter";
 }
 
-export function createDeliveryRouter({ service, adapters, clock }) {
+export function createDeliveryRouter({ service, adapters, clock, platform, readLivePolicy }) {
   const registry = adaptersById(adapters);
 
+  async function policyFor(adapter, binding) {
+    if (adapter?.nativeDelivery?.policySource !== "installation-record") {
+      return LIVE_POLICIES.has(binding.livePolicy) ? binding.livePolicy : "off";
+    }
+    if (typeof readLivePolicy !== "function") return "off";
+    try {
+      const policy = await readLivePolicy({ adapter, binding });
+      return LIVE_POLICIES.has(policy) ? policy : "off";
+    } catch {
+      return "off";
+    }
+  }
+
   async function recordFailure(binding, message, participantId, transport, safeErrorCode) {
     await service.recordOfferFailed({ messageId: message.messageId,
       recipientParticipantId: participantId, targetSessionId: binding.sessionId,
@@ -54,24 +70,29 @@ export function createDeliveryRouter({ service, adapters, clock }) {
     const receipt = await service.readReceipt({ messageId: message.messageId,
       recipientParticipantId: participantId });
     if (receipt.state !== "queued") return settled(receipt);
+    // Core keeps its existing 24-hour presence hard expiry. Refreshing an
+    // endpoint lease never sends a hook heartbeat: a daemon is reachability,
+    // not evidence that this particular session thread is still present.
     const liveSessions = await service.listLiveSessions({ participantId, now });
     if (liveSessions.length === 0) return durable(participantId, "recipient_unavailable");
     if (liveSessions.length > 1) {
       return durable(participantId, "ambiguous_recipient_sessions");
     }
     const [target] = liveSessions;
-    const bindings = (await service.listDeliveryBindings({ participantId, now }))
+    const bindings = (await service.listDeliveryBindings({
+      participantId, now, includeExpired: true }))
       .filter(binding => binding.sessionId === target.sessionId
         && binding.generation === target.generation);
     if (bindings.length === 0) return durable(participantId, "recipient_unavailable");
-    const permitted = bindings.filter(binding => binding.livePolicy !== "off"
-      && permits(binding.livePolicy, message.kind));
+    const evaluated = await Promise.all(bindings.map(async binding => {
+      const adapter = registry.get(binding.adapterId);
+      return { binding, adapter, policy: await policyFor(adapter, binding) };
+    }));
+    const permitted = evaluated.filter(({ policy }) => permits(policy, message.kind));
     if (permitted.length === 0) return durable(participantId, "delivery_disabled");
-    const reachable = permitted.filter(binding => binding.availableModes.includes("livePush"));
+    const reachable = permitted.filter(({ binding }) => binding.availableModes.includes("livePush"));
     if (reachable.length === 0) return durable(participantId, "recipient_unavailable");
-    const capable = reachable.map(binding => ({ binding,
-      adapter: registry.get(binding.adapterId) }))
-      .filter(({ binding, adapter }) => liveCapable(adapter, binding));
+    const capable = reachable.filter(({ binding, adapter }) => liveCapable(adapter, binding));
     if (capable.length === 0) {
       return durable(participantId, "unsupported_client_version");
     }
@@ -79,13 +100,61 @@ export function createDeliveryRouter({ service, adapters, clock }) {
       return durable(participantId, "ambiguous_recipient_sessions");
     }
 
-    const { binding, adapter } = capable[0];
+    let { binding } = capable[0];
+    const { adapter } = capable[0];
+    if (Date.parse(binding.leaseUntil) <= Date.parse(now)) {
+      const refreshed = await refreshExpiredBinding({ service, adapter, binding,
+        runtimeDir: service.store?.root, platform, clock });
+      if (!refreshed) return durable(participantId, "recipient_unavailable");
+      const current = (await service.listDeliveryBindings({
+        participantId, now: clock.now() })).filter(item => item.sessionId === binding.sessionId
+          && item.generation === binding.generation
+          && item.adapterId === binding.adapterId
+          && item.clientVersion === binding.clientVersion
+          && item.opaqueEndpointRef === binding.opaqueEndpointRef);
+      if (current.length !== 1) return durable(participantId, "recipient_unavailable");
+      [binding] = current;
+    }
+    const currentPolicy = await policyFor(adapter, binding);
+    if (!permits(currentPolicy, message.kind)) {
+      return durable(participantId, "delivery_disabled");
+    }
+    // A refresh RPC or policy read can overlap another session opening. The
+    // receiver must still be the sole live session when we hand off to transport.
+    const currentSessions = await service.listLiveSessions({ participantId, now: clock.now() });
+    if (currentSessions.length > 1) return durable(participantId, "ambiguous_recipient_sessions");
+    if (currentSessions.length !== 1 || currentSessions[0].sessionId !== binding.sessionId
+      || currentSessions[0].generation !== binding.generation) {
+      return durable(participantId, "recipient_unavailable");
+    }
+    // Every recipient gets a fresh decision snapshot after async lookup. A
+    // previous recipient may have replaced it while processing their offer.
+    // A send already in flight cannot be recalled by a later peer assertion.
+    if (message.kind === "decision") {
+      message = (await service.sync({ scope: "history", messageId: message.messageId })).items[0];
+      if (!message.decisionStatus.isHead) return settled(await service.readReceipt({
+        messageId: message.messageId, recipientParticipantId: participantId }));
+    }
+    // Consent and session reads can outlive retirement or a re-handshake in
+    // the same generation. Core filters retired, expired and stale-generation
+    // bindings; require the selected identity and live mode immediately before
+    // transport, with no further awaited policy/session work in between.
+    const currentBindings = (await service.listDeliveryBindings({
+      participantId, now: clock.now() })).filter(item => item.sessionId === binding.sessionId
+        && item.generation === binding.generation
+        && item.adapterId === binding.adapterId
+        && item.clientVersion === binding.clientVersion
+        && item.opaqueEndpointRef === binding.opaqueEndpointRef
+        && item.availableModes.includes("livePush")
+        && Date.parse(item.leaseUntil) > Date.parse(clock.now()));
+    if (currentBindings.length !== 1) return durable(participantId, "recipient_unavailable");
+    const currentBinding = { ...currentBindings[0], livePolicy: currentPolicy };
     let response;
     try {
       // The store root is this workspace's runtime dir; the adapter resolves its
       // opaque endpoint id under it. Passed as data, never as a leak into core:
       // the router does not read what the adapter does with it.
-      response = await adapter.offerMessage({ binding, message,
+      response = await adapter.offerMessage({ binding: currentBinding, message,
         runtimeDir: service.store?.root });
     } catch {
       await recordFailure(binding, message, participantId, "live-adapter", "transport_error");
@@ -119,6 +188,13 @@ export function createDeliveryRouter({ service, adapters, clock }) {
     if (!Array.isArray(message?.toParticipantIds) || message.toParticipantIds.length === 0) {
       return [];
     }
+    if (message.kind === "decision") {
+      message = (await service.sync({ scope: "history", messageId: message.messageId })).items[0];
+      if (!message.decisionStatus.isHead) {
+        return Promise.all(message.toParticipantIds.map(async recipientParticipantId => settled(
+          await service.readReceipt({ messageId: message.messageId, recipientParticipantId }))));
+      }
+    }
     const now = clock.now();
     const outcomes = [];
     for (const participantId of message.toParticipantIds) {

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/hook-runner/src/client-version.mjs

@@ -11,6 +11,7 @@ export function probeClientVersion(adapter, { timeoutMs = 1_000 } = {}) {
   return new Promise(resolve => {
     execFile(adapter.client.command, adapter.client.versionArgs ?? ["--version"], {
       timeout: timeoutMs,
+      killSignal: "SIGKILL",
       windowsHide: true,
     }, (error, stdout, stderr) => {
       if (error !== null) return resolve(null);

package/node_modules/@agents-can-communicate/hook-runner/src/native-binding.mjs

@@ -1,5 +1,6 @@
 import { validateNativeHandshake } from "@agents-can-communicate/adapter-sdk";
 import { EXIT } from "@agents-can-communicate/protocol";
+import { retireNativeBinding } from "./native-retirement.mjs";
 
 // The hook side of native delivery: one bounded, fail-open attempt to bind
 // this exact ACC session generation to the vendor session the adapter can
@@ -29,7 +30,7 @@ export function livePolicyFrom(env) {
 const isPid = value => Number.isInteger(value) && value > 0;
 
 export async function establishNativeBinding({ adapter, event, hookBinding, clientVersion,
-  platform, livePolicy, service, runtimeDir, clock,
+  platform, livePolicy, service, runtimeDir, clock, env,
   timeoutMs = DEFAULT_TIMEOUT_MS, heartbeatCadenceMs = DEFAULT_CADENCE_MS }) {
   const outcome = (state, reasonCode, modes = []) =>
     Object.freeze({ state, reasonCode, modes: Object.freeze([...modes]) });
@@ -37,7 +38,7 @@ export async function establishNativeBinding({ adapter, event, hookBinding, clie
   const generation = hookBinding?.generation;
   if (typeof sessionId !== "string" || typeof generation !== "string") return outcome("off", null);
   const policy = LIVE_POLICIES.includes(livePolicy) ? livePolicy : "off";
-  const clear = () => service.clearDeliveryBinding({ sessionId, generation }).catch(() => null);
+  const clear = () => retireNativeBinding({ adapter, service, sessionId, generation, runtimeDir, timeoutMs });
   if (policy === "off") {
     await clear();
     return outcome("off", null);
@@ -52,12 +53,13 @@ export async function establishNativeBinding({ adapter, event, hookBinding, clie
   }
   // Whatever this generation published before is retired first, so a failed
   // re-handshake can never leave yesterday's endpoint reachable.
-  await clear();
+  if (!await clear()) return outcome("degraded", "handshake_failed");
   let timer = null;
   try {
     const budget = Math.max(1, Math.floor(timeoutMs));
     const handshake = await Promise.race([
-      adapter.bindNativeSession({ event, clientPid, clientVersion, runtimeDir, timeoutMs: budget }),
+      adapter.bindNativeSession({ event, clientPid, clientVersion, runtimeDir,
+        timeoutMs: budget, env }),
       new Promise((_resolve, reject) => {
         timer = setTimeout(() => reject(Object.assign(new Error("native handshake timed out"),
           { code: "ETIMEDOUT" })), budget);

package/node_modules/@agents-can-communicate/hook-runner/src/native-retirement.mjs

@@ -0,0 +1,48 @@
+// Retire the core fact first. Adapter cleanup is bounded and acts only on the
+// endpoint whose retirement was observed; an expired registration is retained
+// for on-demand verification, and a successor's endpoint is never touched.
+async function attempt(run, deadlineAt) {
+  const timeoutMs = Math.max(0, deadlineAt - Date.now());
+  if (timeoutMs === 0) return null;
+  let timer;
+  try {
+    return await Promise.race([Promise.resolve().then(run), new Promise(resolve => {
+      timer = setTimeout(() => resolve(null), timeoutMs);
+    })]);
+  } catch { return null; }
+  finally { clearTimeout(timer); }
+}
+
+export async function retireNativeBinding({ adapter, service, sessionId, generation,
+  runtimeDir, timeoutMs = 200 }) {
+  const deadlineAt = Date.now() + Math.max(1, Math.floor(timeoutMs));
+  const cleanup = typeof adapter?.retireNativeSession === "function";
+  const read = () => service.store.ephemeral.get("deliveryBinding", sessionId);
+  const clear = opaqueEndpointRef => opaqueEndpointRef === undefined
+    ? service.clearDeliveryBinding({ sessionId, generation, deadlineAt })
+    : service.clearDeliveryBinding({ sessionId, generation, opaqueEndpointRef, deadlineAt });
+  if (!cleanup) {
+    return await attempt(async () => {
+      await clear(undefined);
+      return true;
+    }, deadlineAt) === true;
+  }
+  // Observation is metadata, not the state transition. A hung read leaves half
+  // the shared retirement window for the exact core clear; a cheap read spends
+  // only the time it actually takes.
+  const observationDeadline = Date.now() + Math.max(1,
+    Math.floor(Math.max(0, deadlineAt - Date.now()) / 2));
+  const observed = await attempt(async () => ({ binding: await read() }), observationDeadline);
+  const prior = observed?.binding;
+  const cleared = await attempt(async () => {
+    await clear(prior?.opaqueEndpointRef ?? null);
+    return true;
+  }, deadlineAt) === true;
+  if (!cleared || observed === null) return false;
+  if (prior?.generation !== generation) return true;
+  const after = await attempt(read, deadlineAt);
+  if (after?.generation !== generation || after.retiredAt == null
+    || after.opaqueEndpointRef !== prior.opaqueEndpointRef) return true;
+  await attempt(() => adapter.retireNativeSession({ binding: prior, runtimeDir }), deadlineAt);
+  return true;
+}

package/node_modules/@agents-can-communicate/hook-runner/src/process-table.mjs

@@ -20,7 +20,7 @@ export async function readProcessTable({ run: exec = run,
   timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   try {
     const { stdout } = await exec("ps", ["-o", "pid=,ppid=,comm=", "-A"],
-      { timeout: timeoutMs });
+      { timeout: timeoutMs, killSignal: "SIGKILL" });
     const table = new Map();
     for (const line of stdout.split("\n")) {
       const match = LINE.exec(line);