agents-can-communicate 0.4.1 → 0.4.3

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

@@ -3,10 +3,9 @@ import { createHash, randomBytes } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
 
-import { clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
+import { clearNativeAttempt, clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
   from "@agents-can-communicate/adapter-sdk";
 import { createCoordinationService } from "@agents-can-communicate/core";
-import { readInstalledLivePolicy } from "@agents-can-communicate/installer";
 import { AccError, createId } from "@agents-can-communicate/protocol";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
 import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
@@ -14,7 +13,7 @@ import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
 
 import { resolveClientPid } from "./client-pid.mjs";
 import { probeClientVersion as defaultProbeClientVersion } from "./client-version.mjs";
-import { establishNativeBinding, livePolicyFrom } from "./native-binding.mjs";
+import { bindNative, nativeDiagnosticDeadline } from "./native-attempt.mjs";
 import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
 import { withSessionLifecycle } from "./session-lifecycle.mjs";
 import { appendToolOwner, ownerHeader, ownerOnlyOutcome } from "./owner-context.mjs";
@@ -305,22 +304,6 @@ async function projectTurn({ binding, context, adapter, adapterId }) {
     offerInputs: writableOffers };
 }
 
-// One bounded, fail-open native handshake for this exact session generation.
-// New adapters read durable consent from their installation record; legacy
-// adapters keep the environment exported by an owned shell bootstrap.
-async function bindNative({ adapter, event, hookBinding, clientVersion, platform, context, paths,
-  deadline }) {
-  assertHookBudget(deadline);
-  const livePolicy = adapter?.nativeDelivery?.policySource === "installation-record"
-    ? await readInstalledLivePolicy({ dataHome: context.dataHome, adapterId: adapter.id })
-    : livePolicyFrom(context.env);
-  assertHookBudget(deadline);
-  return establishNativeBinding({ adapter, event, hookBinding, clientVersion, platform,
-    livePolicy, service: context.service, runtimeDir: paths.root,
-    clock: context.service.clock, env: context.env,
-    timeoutMs: Math.max(1, Math.min(750, deadline - Date.now())) });
-}
-
 const HANDLERS = {
   async sessionStart({ event, context, adapter, adapterId, binding, paths,
     readProcessTable, probeClientVersion, platform, deadline }) {
@@ -356,12 +339,12 @@ const HANDLERS = {
       branch: context.descriptor.git?.branch ?? null,
     };
     if (event.kind === "beforeTurn" && binding !== null) {
-      // A real prompt may continue after finish closed this native owner's
-      // record. Recheck after the probes: a CLI replacement can run outside
-      // the native lifecycle lock. Never adopt that replacement's identity.
+      // A genuine prompt can resume after an ephemeral removal or a durable
+      // close. Recheck after probes: a CLI replacement can run outside the
+      // native lifecycle lock. Never adopt that replacement's identity.
       const previous = await context.service.locateSession(binding.accSessionId);
-      if (previous?.record.state !== "closed"
-        || previous.record.generation !== binding.generation) {
+      if (previous !== null && (previous.record.state !== "closed"
+        || previous.record.generation !== binding.generation)) {
         throw new Error("the completed hook owner changed during turn registration");
       }
     }
@@ -432,6 +415,11 @@ const HANDLERS = {
       await context.service.clearDeliveryBinding(owner);
     }
     await clearSessionBinding({ runtimeDir: paths.root, deadlineAt: deadline, harnessSessionId: event.sessionId });
+    const diagnosticDeadline = nativeDiagnosticDeadline(deadline);
+    if (diagnosticDeadline !== null) {
+      await clearNativeAttempt({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+        ...binding, deadlineAt: diagnosticDeadline });
+    }
     return {};
   },
 
@@ -450,9 +438,11 @@ const HANDLERS = {
       return { ...turn, nativeBinding: started.nativeBinding };
     }
     const current = await context.service.locateSession(binding.accSessionId);
-    if (current?.record.state === "closed" && current.record.generation === binding.generation) {
-      // finish ends an ACC incarnation, not the native conversation. Only a
-      // genuine new user turn can start another one; tool hooks cannot. Reuse
+    if (current === null
+      || current.record.state === "closed" && current.record.generation === binding.generation) {
+      // A solo detach removes its ephemeral record; a durable close retains it.
+      // Both end the ACC incarnation while the native conversation may continue.
+      // Only a genuine user turn can start another one; tool hooks cannot. Reuse
       // the crash-safe opening path, retaining its full published client facts
       // and its single native handshake rather than binding a second time.
       const started = await HANDLERS.sessionStart(input);

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/installer/src/apply.mjs

@@ -35,6 +35,7 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
         const createdDirectories = await missingArtifactParents({ home: context.home,
           artifacts: operation.artifacts });
         const installContext = { ...context,
+          clientVersion: operation.clientVersion, platform: operation.platform,
           requestedLivePolicy: operation.livePolicy ?? "off",
           livePolicy: operation.effectiveLivePolicy ?? "off" };
         const outcome = await adapter.install(installContext);
@@ -103,6 +104,7 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
           retainedNativeActivation: retainedMechanisms.length === 0 ? null
             : { ...operation.deactivation, mechanisms: retainedMechanisms } });
         results.operations.push({ ...operation, applied: true,
+          needsAction: outcome.needsAction ?? [],
           changes: outcome.changes ?? [], removed: owned.removed, kept: owned.kept,
           removedDirectories: directories.removed, keptDirectories: directories.kept,
           missingDirectories: directories.missing,

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

@@ -0,0 +1,36 @@
+// Shared presentation of observed delivery facts. Vendor probes provide closed
+// reasons; installation and doctor must not turn a version floor into readiness.
+const REASONS = Object.freeze({
+  native_delivery_unsupported: "this adapter has no native delivery channel",
+  platform_not_captured: "native delivery is not verified on this platform",
+  version_unavailable: "the client version could not be verified",
+  prerelease_not_captured: "this client version is not a verified stable release",
+  below_minimum_version: "the client is below the native delivery minimum version",
+  known_bad_version: "this client version has a known native delivery failure",
+  native_endpoint_unavailable: "the client's local delivery service is unavailable",
+  native_session_unavailable: "the local delivery service has no loaded client session",
+  feature_probe_failed: "the native protocol probe did not succeed",
+  probe_timeout: "the native protocol probe timed out",
+  probe_version_mismatch: "the local service and CLI versions differ",
+  protocol_mismatch: "the local service did not confirm the required protocol",
+  unsupported_shell: "automatic launch setup requires zsh",
+});
+
+export function describeNativeReason(reason, { clientVersion, minimumVersion } = {}) {
+  if (reason === "below_minimum_version" && clientVersion && minimumVersion) {
+    return `client ${clientVersion} needs version ${minimumVersion} or newer for native delivery`;
+  }
+  return REASONS[reason] ?? reason ?? "readiness is unverified";
+}
+export const describeDeliveryFallback = entry => entry.capabilities?.delivery?.nextTurn === true
+  ? "next-turn hooks (when enabled) or acc inbox" : "acc inbox";
+
+export function describeInstallDelivery(entry, policy, effectivePolicy) {
+  const state = policy === "off" ? "off" : effectivePolicy === "off"
+    ? `consent saved (${policy}); not active` : `enabled (${policy}); waiting for a verified session`;
+  const reason = entry.nativeDelivery?.reasonCode;
+  return `${entry.displayName ?? entry.adapterId} live delivery: ${state}`
+    + (reason ? `; ${describeNativeReason(reason, { clientVersion: entry.version,
+      minimumVersion: entry.nativeDelivery?.eligibility?.minimumVersion })}` : "")
+    + `; fallback: ${describeDeliveryFallback(entry)}`;
+}

package/node_modules/@agents-can-communicate/installer/src/detect.mjs

@@ -6,6 +6,8 @@ import { effectiveCapabilities, evaluateNativeEligibility, validateNativeActivat
 
 import { resolveExecutable, shellOf, shimDirFor } from "./native-activation.mjs";
 
+import { describeDeliveryFallback, describeNativeReason } from "./delivery-diagnostics.mjs";
+
 const run = promisify(execFile);
 
 // Reasons the client itself will not change within an install: unsupported,
@@ -79,8 +81,14 @@ async function detectNative(adapter, entry, { context, platform, probeTimeoutMs,
     }
     if (facts.eligibility.eligible !== true) {
       const reasonCode = facts.eligibility.reasonCode ?? "feature_probe_failed";
+      // A stored policy can be consented to before a service/session exists.
+      // No activation is planned until the full probe passes; bootstrap-based
+      // clients still need their verified plan to disclose launch changes.
+      const consentAvailable = adapter.nativeDelivery.policySource === "installation-record"
+        && ["native_endpoint_unavailable", "native_session_unavailable"].includes(reasonCode);
       return STATIC_REASONS.has(reasonCode)
-        ? { ...unsupported(reasonCode), ...facts } : degraded(reasonCode, facts);
+        ? { ...unsupported(reasonCode), ...facts }
+        : { ...degraded(reasonCode, facts), consentAvailable };
     }
     let activationPlan;
     try {
@@ -110,7 +118,7 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
     // deterministic rather than dependent on registry order.
     .sort((left, right) => left.id.localeCompare(right.id))
     .map(async adapter => {
-      const entry = { adapterId: adapter.id, displayName: adapter.displayName,
+      const entry = { adapterId: adapter.id, displayName: adapter.displayName, platform,
         present: false, version: null, versionOutput: null, installed: false,
         diagnostics: [], needsAction: [], capabilities: effectiveCapabilities(adapter),
         deliveryDiagnostic: null, error: null };
@@ -138,7 +146,10 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
           ? "native_delivery_unsupported" : "version_unavailable");
 
       try {
-        const detected = await adapter.detect(context);
+        const detected = await adapter.detect({ ...context, clientVersion: entry.version,
+          platform, nativeDelivery: entry.nativeDelivery });
+        if (detected.outgoingDelivery) entry.outgoingDelivery = detected.outgoingDelivery;
+        if (detected.nativeSetup) entry.nativeSetup = detected.nativeSetup;
         entry.diagnostics = [...(detected.diagnostics ?? [])];
         // What a person has to do, as opposed to what is true. Adapters that
         // have nothing to ask for say nothing.
@@ -151,15 +162,20 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
       } catch (error) {
         entry.error = entry.error ?? error.message;
       }
-      if (entry.nativeDelivery.state !== "eligible"
-        && typeof adapter.deliveryFallback?.diagnostic === "string") {
-        const nextTurnDowngraded = adapter.capabilities?.delivery?.nextTurn === true
-          && entry.capabilities?.delivery?.nextTurn !== true;
-        entry.deliveryDiagnostic = nextTurnDowngraded
-          ? `${adapter.displayName} ${entry.version ?? "unknown version"} has no certified `
-            + `next-turn delivery on ${platform}; ${adapter.deliveryFallback.diagnostic}`
-          : adapter.deliveryFallback.diagnostic;
-        entry.diagnostics.push(entry.deliveryDiagnostic);
+      if (entry.nativeDelivery.state !== "eligible") {
+        if (adapter.nativeDelivery !== undefined) {
+          entry.deliveryDiagnostic = `${adapter.displayName} native delivery: `
+            + `${describeNativeReason(entry.nativeDelivery.reasonCode, { clientVersion: entry.version,
+              minimumVersion: entry.nativeDelivery.eligibility?.minimumVersion })}; `
+            + `fallback: ${describeDeliveryFallback(entry)}`;
+        } else if (typeof adapter.deliveryFallback?.diagnostic === "string") {
+          const downgraded = adapter.capabilities?.delivery?.nextTurn === true
+            && entry.capabilities?.delivery?.nextTurn !== true;
+          entry.deliveryDiagnostic = (downgraded
+            ? `${adapter.displayName} ${entry.version ?? "unknown version"} has no certified `
+              + `next-turn delivery on ${platform}; ` : "") + adapter.deliveryFallback.diagnostic;
+        }
+        if (entry.deliveryDiagnostic !== null) entry.diagnostics.push(entry.deliveryDiagnostic);
       }
       return entry;
     }));

package/node_modules/@agents-can-communicate/installer/src/index.mjs

@@ -12,4 +12,6 @@ export { BLOCK_BEGIN, BLOCK_END, SHIM_MARKER, SHIM_POLICIES, SUPPORTED_SHELLS,
   shellLiteral, uninstallShellBootstrap, validateShimEntry } from "./shell-bootstrap.mjs";
 export { LIVE_POLICIES, describeActivation, describeDeactivation, livePolicyOf, rcFileFor,
   resolveExecutable, shellOf, shimDirFor } from "./native-activation.mjs";
-export { readInstalledLivePolicy } from "./live-policy.mjs";
+export { readInstalledLivePolicy, readInstalledLivePolicyState } from "./live-policy.mjs";
+export { describeDeliveryFallback, describeInstallDelivery, describeNativeReason }
+  from "./delivery-diagnostics.mjs";

package/node_modules/@agents-can-communicate/installer/src/live-policy.mjs

@@ -10,12 +10,19 @@ export const livePolicyOf = install => {
     ? install.nativeActivation.livePolicy : "off";
 };
 
-export async function readInstalledLivePolicy({ dataHome, adapterId }) {
+export async function readInstalledLivePolicy(input) {
+  return (await readInstalledLivePolicyState(input)).policy;
+}
+
+export async function readInstalledLivePolicyState({ dataHome, adapterId }) {
   try {
     const record = await loadOwnership({ dataHome });
     const install = record.installs.find(entry => entry.adapterId === adapterId);
-    return livePolicyOf(install);
+    const raw = Object.hasOwn(install ?? {}, "deliveryPolicy")
+      ? install.deliveryPolicy : install?.nativeActivation?.livePolicy;
+    return { policy: livePolicyOf(install), policyStatus: raw === undefined ? "missing"
+      : !LIVE_POLICIES.includes(raw) ? "invalid" : raw === "off" ? "off" : "enabled" };
   } catch {
-    return "off";
+    return { policy: "off", policyStatus: "unavailable" };
   }
 }

package/node_modules/@agents-can-communicate/installer/src/plan.mjs

@@ -1,3 +1,5 @@
+import { describeInstallDelivery } from "./delivery-diagnostics.mjs";
+
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 import { LIVE_POLICIES, describeActivation, describeDeactivation, planActivationRetirements, rcFileFor, shimDirFor }
@@ -112,8 +114,12 @@ export function planInstallation({ adapters, detected, context, action = "instal
         ?? `${adapter.displayName ?? adapter.id} cannot receive native delivery `
           + `(${native?.reasonCode ?? "native_delivery_unsupported"}); durable fallback remains active`
       : null;
+    const deliverySummary = action === "install"
+      ? describeInstallDelivery(entry, delivery, effectiveLivePolicy) : null;
     const installContext = { ...context, requestedLivePolicy: delivery,
-      livePolicy: effectiveLivePolicy };
+      livePolicy: effectiveLivePolicy, clientVersion: entry.version, platform: entry.platform };
+    const setupNotes = action === "install" && delivery !== "off"
+      ? [entry.outgoingDelivery?.setup, entry.nativeSetup].filter(note => typeof note === "string") : [];
     // A consented activation that this run keeps, activates, or takes back.
     // Only an explicit off or an uninstall removes one; an absent record never
     // creates one.
@@ -135,6 +141,7 @@ export function planInstallation({ adapters, detected, context, action = "instal
       displayName: adapter.displayName,
       action,
       clientVersion: entry.version ?? record?.version ?? null,
+      platform: entry.platform ?? context?.platform,
       // "Remove these files for a client that is not here" is a different thing
       // to approve than an ordinary uninstall, so it is said rather than left
       // to be inferred from a client version that is null.
@@ -143,6 +150,8 @@ export function planInstallation({ adapters, detected, context, action = "instal
       livePolicy: delivery,
       effectiveLivePolicy,
       ...(deliveryDiagnostic === null ? {} : { deliveryDiagnostic }),
+      ...(deliverySummary === null ? {} : { deliverySummary }),
+      ...(setupNotes.length ? { setupNotes } : {}),
       ...(nativeActivation === null ? {} : { nativeActivation }),
       ...(deactivation === null ? {} : { deactivation }),
       artifacts,
@@ -151,7 +160,8 @@ export function planInstallation({ adapters, detected, context, action = "instal
       summary: [
         ...(entry.present ? [] : [`${adapter.displayName ?? adapter.id} is no longer on `
           + "this machine; removing what ACC recorded writing"]),
-        ...(deliveryDiagnostic === null ? [] : [deliveryDiagnostic]),
+        ...(deliverySummary === null ? [] : [deliverySummary]),
+        ...setupNotes,
         ...artifacts.filter(a => a.kind === "tree")
           .map(a => `${action === "install" ? "create" : "remove"} ${a.path}`),
         ...artifacts.filter(a => a.kind === "merge")

package/node_modules/@agents-can-communicate/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "private": true,
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "description": "Local-first coordination for independently opened AI agent sessions.",
   "keywords": [