agents-can-communicate 0.2.0 → 0.3.0

package/node_modules/@agents-can-communicate/cli/src/install-command.mjs

@@ -6,7 +6,8 @@ import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
 import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
 import { createGrokAdapter } from "@agents-can-communicate/adapter-grok";
 import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
-import { applyPlan, detectInstallation, loadOwnership, planInstallation }
+import { LIVE_POLICIES, applyPlan, describeActivation, detectInstallation, livePolicyOf,
+  loadOwnership, planInstallation, rcFileFor, shellOf, shimDirFor }
   from "@agents-can-communicate/installer";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
@@ -18,13 +19,18 @@ import { platformPaths } from "./platform-paths.mjs";
 // Each client keeps its own directory under the user's home, and an adapter
 // pointed at the home itself writes beside them rather than inside them. That
 // install reports success and the client never reads a byte of it.
-export const clientContext = (home, stateRoot) => ({
+export const clientContext = (home, stateRoot, { shell = null, env = {} } = {}) => ({
   home,
   configDir: path.join(home, ".claude"),
   agentsHome: home,
   codexHome: path.join(home, ".codex"),
   kimiHome: path.join(home, ".kimi-code"),
   grokHome: path.join(home, ".grok"),
+  // The user's login shell and PATH, for the optional native shell bootstrap:
+  // which rc file could carry an ACC PATH block and which real executable a
+  // shim would exec. Detection reads them; nothing here writes.
+  shell,
+  env,
   // Where ACC keeps its own state, for the client that has to be told. Codex
   // sandboxes the commands a model runs to the workspace, and ACC's state is
   // outside every workspace on purpose - so an agent there could read the
@@ -108,11 +114,20 @@ export function describeChanges(operation, home) {
     return [...artifacts.filter(artifact => artifact.kind !== "merge")
       .map(artifact => `  created ${shorten(artifact.path, home)}`), ...edited];
   }
+  // An uninstall's merge edits come from the plan - every file ACC has ever
+  // written into - while everything else on this list is decided by the run.
+  // Printed unconditionally, a second uninstall told the operator it had edited
+  // six of their configuration files whose bytes it had not touched. `changes`
+  // is what the adapter actually took out, and is already what the packed
+  // verifier calls a no-op, so the report now follows the same definition. It
+  // is still the plan's list rather than a per-file one: this says whether
+  // anything was edited, not which of several files it was.
+  const editedIfAnything = (operation.changes ?? []).length === 0 ? [] : edited;
   return [
     ...(operation.removed ?? []).map(file => `  removed ${shorten(file, home)}`),
     ...(operation.removedDirectories ?? [])
       .map(file => `  removed ${shorten(file, home)}`),
-    ...edited,
+    ...editedIfAnything,
     ...(operation.kept ?? [])
       .map(file => `  kept    ${shorten(file, home)} - changed since ACC wrote it`),
   ];
@@ -174,12 +189,81 @@ export function actedOn(result) {
         + (operation.changes?.length ?? 0) > 0)).length;
 }
 
+const isInteractive = runtime => typeof runtime.isInteractive === "function"
+  && runtime.isInteractive() === true;
+
+// One default-No question per eligible client, asked only after detection has
+// finished and only when a person is at both ends of the terminal. It names
+// the client, the mechanism, and the files or service it would touch, and says
+// when the choice takes effect.
+function questionFor(entry, context) {
+  const activation = { livePolicy: "actionable", shell: context.shell,
+    rcFile: rcFileFor(context.home, context.shell), shimDir: shimDirFor(context.stateRoot),
+    mechanisms: entry.nativeDelivery.activationPlan.mechanisms };
+  return [`Enable native live delivery for ${entry.displayName} ${entry.version}?`,
+    ...describeActivation(activation).map(line => `  ${line}`),
+    "  applies to newly started sessions; a new PATH block needs a new or reloaded shell"]
+    .join("\n");
+}
+
+/**
+ * Which live policy each selected client gets.
+ *
+ * An explicit --delivery applies uniformly and never prompts. Otherwise a
+ * recorded opt-in is kept as it was consented to, a fresh or never-activated
+ * client is off unless a person answers yes here, and a dry run or a
+ * non-interactive stdin/stdout makes no interactive choice at all.
+ */
+export async function decideDelivery({ options, detected, recorded, runtime, dryRun, context }) {
+  const explicit = options.delivery;
+  if (explicit !== undefined && !LIVE_POLICIES.includes(explicit)) {
+    throw new AccError(EXIT.USAGE, `unknown delivery policy: ${explicit}`, { delivery: explicit });
+  }
+  const recordedById = new Map(recorded.map(install => [install.adapterId, install]));
+  const deliveryByAdapter = {};
+  const asked = [];
+  let withheld = 0;
+  for (const entry of detected) {
+    const eligible = entry.nativeDelivery?.state === "eligible";
+    const previous = livePolicyOf(recordedById.get(entry.adapterId));
+    if (explicit !== undefined) {
+      deliveryByAdapter[entry.adapterId] = explicit;
+    } else if (previous !== "off") {
+      deliveryByAdapter[entry.adapterId] = previous;
+    } else if (!eligible || dryRun || !isInteractive(runtime)) {
+      deliveryByAdapter[entry.adapterId] = "off";
+      if (eligible) withheld += 1;
+    } else {
+      const yes = await runtime.confirm(questionFor(entry, context),
+        { input: runtime.input, output: runtime.output }) === true;
+      deliveryByAdapter[entry.adapterId] = yes ? "actionable" : "off";
+      asked.push(entry.adapterId);
+    }
+  }
+  const notes = explicit === undefined && dryRun && withheld > 0
+    ? ["interactive choices were not made: this preview keeps native delivery off for "
+      + `${withheld} eligible client(s) without a recorded opt-in`]
+    : [];
+  return { deliveryByAdapter, asked, notes };
+}
+
+// Said once, after the first PATH block is written: a running shell and a
+// running client know nothing about it.
+function reloadAdvice(operations) {
+  const appended = operations.filter(operation => operation.appendedRcBlock === true);
+  if (appended.length === 0) return [];
+  const rc = appended[0].nativeActivation?.rcFile ?? "your shell rc file";
+  return ["", `native delivery is wired for new sessions: open a new terminal (or reload ${rc}), `
+    + "then start the client normally; a session already running keeps durable delivery"];
+}
+
 export async function runInstallCommand({ options, runtime, action = "install" }) {
   const adapters = selectAdapters(options.adapter);
   const home = options.home ?? runtime.env?.HOME ?? homedir();
   const { data: dataHome } = platformPaths({ platform: runtime.platform,
     env: runtime.env ?? {} });
-  const context = clientContext(home, path.join(dataHome, "acc"));
+  const context = clientContext(home, path.join(dataHome, "acc"),
+    { shell: shellOf(runtime.env), env: runtime.env ?? {} });
 
   const detected = await detectInstallation({ adapters, context,
     probeTimeoutMs: probeTimeout(runtime.env) });
@@ -205,20 +289,28 @@ export async function runInstallCommand({ options, runtime, action = "install" }
   const requested = options.adapter === undefined
     ? []
     : (Array.isArray(options.adapter) ? options.adapter : [options.adapter]);
+  // Decided only after detection, from the operator's explicit answer, the
+  // recorded consent, or a default of off; never from inference.
+  const decided = action === "install"
+    ? await decideDelivery({ options, detected, recorded, runtime, dryRun, context })
+    : { deliveryByAdapter: {}, asked: [], notes: [] };
   const plan = planInstallation({ adapters, detected, context, action, recorded,
     accVersion, allowDowngrade: options.downgrade === true, requested,
-    delivery: options.delivery ?? "off" });
+    deliveryByAdapter: decided.deliveryByAdapter });
   const result = await applyPlan({ plan, adapters, context, dataHome, dryRun, accVersion });
 
   const acted = actedOn(result);
   if (dryRun) {
-    return { data: { ...result, plan, dataHome },
+    return { data: { ...result, plan, dataHome, deliveryByAdapter: decided.deliveryByAdapter },
       text: [`would ${action}:`, ...plan.operations.flatMap(operation => operation.summary),
-        ...plan.skipped.map(entry => `skip ${entry.adapterId}: ${entry.reason}`)].join("\n") };
+        ...plan.skipped.map(entry => `skip ${entry.adapterId}: ${entry.reason}`),
+        ...decided.notes].join("\n") };
   }
 
-  return { data: { ...result, plan, dataHome },
-    text: describeOutcome({ action, acted, failed: result.failed,
-      skipped: plan.skipped, operations: result.operations, home }),
-    error: failureOf({ action, acted, failed: result.failed }) };
+  return { data: { ...result, plan, dataHome, deliveryByAdapter: decided.deliveryByAdapter,
+    asked: decided.asked },
+  text: [describeOutcome({ action, acted, failed: result.failed,
+    skipped: plan.skipped, operations: result.operations, home }),
+  ...reloadAdvice(result.operations)].join("\n"),
+  error: failureOf({ action, acted, failed: result.failed }) };
 }

package/node_modules/@agents-can-communicate/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -8,7 +8,7 @@ function conflict(sessionId) {
 }
 
 export function createDeliveryBindingService(ports, sessions) {
-  const { store } = ports;
+  const { store, clock } = ports;
 
   async function currentBindings(now) {
     const bindings = await store.ephemeral.list("deliveryBinding");
@@ -17,6 +17,10 @@ export function createDeliveryBindingService(ports, sessions) {
       const located = await sessions.locateSession(binding.sessionId);
       if (located?.record.state !== "open"
         || located.record.generation !== binding.generation) continue;
+      // A retirement is final. It is kept as a record rather than deleted so a
+      // stale generation cannot race a successor's publication, and it must
+      // never be read back as a live endpoint.
+      if (binding.retiredAt !== null && binding.retiredAt !== undefined) continue;
       current.push({ binding, participantId: located.record.participantId,
         reachable: Date.parse(binding.leaseUntil) > Date.parse(now) });
     }
@@ -42,6 +46,7 @@ export function createDeliveryBindingService(ports, sessions) {
         livePolicy: input.livePolicy,
         opaqueEndpointRef: input.opaqueEndpointRef,
         leaseUntil: input.leaseUntil,
+        retiredAt: null,
       });
     } catch (error) {
       if (error?.details?.field === "opaqueEndpointRef") {
@@ -71,11 +76,56 @@ export function createDeliveryBindingService(ports, sessions) {
     return binding;
   }
 
+  // Clearing is an in-place retirement under the same writer lock as
+  // publication. The store's update contract has no deletion sentinel and its
+  // delete() takes the same mutex, so this is the one atomic form: a stale
+  // generation cannot retire a successor's endpoint, and an absent or
+  // already-retired binding stays as it is.
+  //
+  // The retirement is recorded as its own fact rather than as an expired lease.
+  // Expiry and retirement used to be the same edit, so a channel still renewing
+  // its endpoint could extend a binding the session had already given up.
+  async function clearDeliveryBinding({ sessionId, generation }) {
+    await store.ephemeral.update("deliveryBinding", sessionId, async current => {
+      if (current === null || current === undefined) return null;
+      if (current.generation !== generation) throw conflict(sessionId);
+      if (current.retiredAt !== null && current.retiredAt !== undefined) return null;
+      const now = clock.now();
+      return { ...current, leaseUntil: now, retiredAt: now };
+    });
+  }
+
+  /**
+   * Extend the lease on a binding whose endpoint is still being served.
+   *
+   * Only the process holding the endpoint knows it is alive, and for a client
+   * with no heartbeat nothing else refreshes this record: measured on a real
+   * Claude 2.1.259 session, the channel kept its registration renewed while
+   * this lease went stale about a minute after the last turn, and the router
+   * stopped offering to a session that was still serving.
+   *
+   * Narrow on purpose. It moves the lease and nothing else, refuses anything
+   * but the current open generation, and will not revive a retired binding.
+   */
+  async function refreshDeliveryBinding({ sessionId, generation, leaseUntil }) {
+    const located = await sessions.locateSession(sessionId);
+    if (located?.record.state !== "open" || located.record.generation !== generation) {
+      throw conflict(sessionId);
+    }
+    await store.ephemeral.update("deliveryBinding", sessionId, async current => {
+      if (current === null || current === undefined) return null;
+      if (current.generation !== generation) throw conflict(sessionId);
+      if (current.retiredAt !== null && current.retiredAt !== undefined) return null;
+      return validateRecord("deliveryBinding", { ...current, leaseUntil });
+    });
+  }
+
   async function listDeliveryBindings({ participantId, now }) {
     return (await currentBindings(now))
       .filter(item => item.participantId === participantId && item.reachable)
       .map(item => item.binding);
   }
 
-  return { publishDeliveryBinding, listDeliveryBindings, currentBindings };
+  return { publishDeliveryBinding, clearDeliveryBinding, refreshDeliveryBinding,
+    listDeliveryBindings, currentBindings };
 }

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

@@ -43,11 +43,21 @@ export function createCoordinationService({ store, clock, ids,
     ids,
     policies: Object.freeze({ ...policies }),
     ...sessions,
+    // Closing a session also retires its live endpoint under the same
+    // generation, so nothing can be offered into a session that has left.
+    closeSession: async input => {
+      const closed = await sessions.closeSession(input);
+      await deliveryBindings.clearDeliveryBinding({ sessionId: input.sessionId,
+        generation: input.generation });
+      return closed;
+    },
     ...intents,
     ...claims,
     ...conversations,
     publishDeliveryBinding: deliveryBindings.publishDeliveryBinding,
+    clearDeliveryBinding: deliveryBindings.clearDeliveryBinding,
     listDeliveryBindings: deliveryBindings.listDeliveryBindings,
+    refreshDeliveryBinding: deliveryBindings.refreshDeliveryBinding,
     ...inbox,
     ...receipts,
     ...sync,

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

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

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

@@ -1,6 +1,3 @@
-import { effectiveCapabilities } from "@agents-can-communicate/adapter-sdk";
-
-const PLATFORM = `${process.platform}-${process.arch}`;
 const SAFE_ERRORS = new Set(["ambiguous_recipient_sessions", "delivery_disabled",
   "recipient_busy", "recipient_unavailable", "transport_error", "transport_rejected",
   "unsupported_client_version"]);
@@ -11,8 +8,23 @@ const adaptersById = adapters => adapters instanceof Map
   : new Map((Array.isArray(adapters) ? adapters : Object.values(adapters ?? {}))
     .map(adapter => [adapter.id, adapter]));
 
+// Everything that closes or advances a conversation is actionable: a question
+// or request asks for work, an answer or decision resolves it, a handoff
+// 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 permits = (policy, kind) => policy === "all"
-  || (policy === "actionable" && ["question", "request", "handoff"].includes(kind));
+  || (policy === "actionable" && ACTIONABLE.has(kind));
+
+// Compatibility was decided twice already - at bootstrap by the probe and at
+// SessionStart by the generation-bound handshake that published this binding.
+// The router validates binding identity and the adapter's answer; it does not
+// impose a third, exact-version rule that would reject a client the handshake
+// admitted.
+const liveCapable = (adapter, binding) => adapter !== undefined
+  && adapter.capabilities?.delivery?.livePush === true
+  && adapter.nativeDelivery !== undefined
+  && binding.availableModes.includes("livePush");
 
 const durable = (recipientParticipantId, errorCode) => ({ recipientParticipantId,
   outcome: "queued", transport: "durable", errorCode });
@@ -57,22 +69,24 @@ export function createDeliveryRouter({ service, adapters, clock }) {
     if (permitted.length === 0) return durable(participantId, "delivery_disabled");
     const reachable = permitted.filter(binding => binding.availableModes.includes("livePush"));
     if (reachable.length === 0) return durable(participantId, "recipient_unavailable");
-    const certified = reachable.map(binding => ({ binding,
+    const capable = reachable.map(binding => ({ binding,
       adapter: registry.get(binding.adapterId) }))
-      .filter(({ binding, adapter }) => adapter !== undefined
-        && effectiveCapabilities(adapter,
-          { clientVersion: binding.clientVersion, platform: PLATFORM }).delivery.livePush);
-    if (certified.length === 0) {
+      .filter(({ binding, adapter }) => liveCapable(adapter, binding));
+    if (capable.length === 0) {
       return durable(participantId, "unsupported_client_version");
     }
-    if (certified.length > 1) {
+    if (capable.length > 1) {
       return durable(participantId, "ambiguous_recipient_sessions");
     }
 
-    const { binding, adapter } = certified[0];
+    const { binding, adapter } = capable[0];
     let response;
     try {
-      response = await adapter.offerMessage({ binding, message });
+      // 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,
+        runtimeDir: service.store?.root });
     } catch {
       await recordFailure(binding, message, participantId, "live-adapter", "transport_error");
       return durable(participantId, "transport_error");

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

@@ -1,10 +1,12 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "exports": {
-    ".": "./src/runner.mjs"
+    ".": "./src/runner.mjs",
+    "./client-pid": "./src/client-pid.mjs",
+    "./process-table": "./src/process-table.mjs"
   },
   "files": [
     "src/"

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

@@ -0,0 +1,90 @@
+import { validateNativeHandshake } from "@agents-can-communicate/adapter-sdk";
+import { EXIT } from "@agents-can-communicate/protocol";
+
+// 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
+// reach, then a sanitized binding published for the router. The helper, not
+// the adapter, supplies adapter id, client facts, session id, and generation;
+// the adapter supplies only closed handshake facts. Nothing here throws into
+// the hook path, and no endpoint reference ever leaves through the result.
+
+export const LIVE_POLICIES = Object.freeze(["off", "actionable", "all"]);
+export const NATIVE_BINDING_STATES = Object.freeze(["active", "off", "degraded", "unsupported"]);
+const DEFAULT_TIMEOUT_MS = 750;
+const DEFAULT_CADENCE_MS = 60_000;
+
+// Reasons the static rule refused: the client will not change within the
+// session, so the state is "unsupported" rather than a retryable "degraded".
+const STATIC_REASONS = new Set(["native_delivery_unsupported", "platform_not_captured",
+  "version_unavailable", "prerelease_not_captured", "below_minimum_version",
+  "known_bad_version"]);
+
+// Only the value a successful owned shell bootstrap exported counts; anything
+// else - missing, blank, differently cased, a number - is off.
+export function livePolicyFrom(env) {
+  const value = env?.ACC_NATIVE_DELIVERY_POLICY;
+  return LIVE_POLICIES.includes(value) ? value : "off";
+}
+
+const isPid = value => Number.isInteger(value) && value > 0;
+
+export async function establishNativeBinding({ adapter, event, hookBinding, clientVersion,
+  platform, livePolicy, service, runtimeDir, clock,
+  timeoutMs = DEFAULT_TIMEOUT_MS, heartbeatCadenceMs = DEFAULT_CADENCE_MS }) {
+  const outcome = (state, reasonCode, modes = []) =>
+    Object.freeze({ state, reasonCode, modes: Object.freeze([...modes]) });
+  const sessionId = hookBinding?.accSessionId;
+  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);
+  if (policy === "off") {
+    await clear();
+    return outcome("off", null);
+  }
+  if (adapter?.nativeDelivery === undefined || typeof adapter.bindNativeSession !== "function") {
+    return outcome("unsupported", "native_delivery_unsupported");
+  }
+  const clientPid = hookBinding.clientPid;
+  if (!isPid(clientPid)) {
+    await clear();
+    return outcome("degraded", "client_process_unknown");
+  }
+  // Whatever this generation published before is retired first, so a failed
+  // re-handshake can never leave yesterday's endpoint reachable.
+  await clear();
+  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 }),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(Object.assign(new Error("native handshake timed out"),
+          { code: "ETIMEDOUT" })), budget);
+      }),
+    ]);
+    const verdict = validateNativeHandshake(adapter, { clientVersion, platform, handshake });
+    if (!verdict.ok) {
+      return outcome(STATIC_REASONS.has(verdict.reasonCode) ? "unsupported" : "degraded",
+        verdict.reasonCode);
+    }
+    const now = Date.parse(clock.now());
+    const lease = Date.parse(verdict.leaseUntil);
+    if (!(lease > now)) return outcome("degraded", "handshake_failed");
+    const ceiling = now + 2 * heartbeatCadenceMs;
+    const leaseUntil = lease > ceiling ? new Date(ceiling).toISOString() : verdict.leaseUntil;
+    await service.publishDeliveryBinding({
+      sessionId, generation, adapterId: adapter.id, clientVersion,
+      availableModes: [...verdict.modes], livePolicy: policy,
+      opaqueEndpointRef: verdict.opaqueEndpointRef, leaseUntil,
+    });
+    return outcome("active", null, verdict.modes);
+  } catch (error) {
+    await clear();
+    const reasonCode = error?.code === "ETIMEDOUT" ? "handshake_timeout"
+      : error?.code === EXIT.CONFLICT ? "session_generation_stale" : "handshake_failed";
+    return outcome("degraded", reasonCode);
+  } finally {
+    if (timer !== null) clearTimeout(timer);
+  }
+}