agents-can-communicate 0.2.0 → 0.3.0

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

@@ -12,6 +12,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 { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
 
 // Kept cohesive above 300 lines because every handler shares one fail-open
@@ -184,6 +185,107 @@ async function openContext({ cwd, dataHome, runtime, env }) {
     service: createCoordinationService({ store, clock: runtime.clock, ids: runtime.ids }) };
 }
 
+// What this turn is shown and which complete groups it may commit as
+// offered. Runs after the heartbeat and the bounded native retry.
+async function projectTurn({ binding, context, adapter, adapterId }) {
+  const sync = await context.service.sync({ sessionId: binding.accSessionId,
+    cursor: null, scope: "delta" });
+
+  // Sync already carries the roster. Calling collectStatus here used to read
+  // the entire materialised store a second time on every prompt merely to
+  // rediscover this session's participant id.
+  const mine = sync.roster
+    .find(participant => participant.sessionId === binding.accSessionId);
+
+  // What peers have said to this participant and no model has been shown yet.
+  // Without this the projector's peer block never runs in production: an
+  // agent sees only the obligation attention line, not the durable body that
+  // may be offered after the stdout transport succeeds.
+  const delivery = await context.service.nextTurnDelivery({
+    workspaceId: context.descriptor.id,
+    participantId: mine?.participantId,
+    exceptSessionId: binding.accSessionId });
+  const messages = delivery.queuedMessages;
+
+  // Solo costs nothing: nothing to say means nothing printed, not a banner
+  // announcing that nobody else is here. But something already said to you is
+  // not nothing - the check used to run before the inbox was read, so the
+  // answer to your own request vanished the moment the agent working on it
+  // closed and left you as the only session.
+  if (sync.solo && messages.length === 0) return { stdout: "" };
+
+  // The ceiling a team agreed on in `acc.workspace.json`, or the default when
+  // there is no config. Validated by the protocol and, until now, never read:
+  // the projector was always called with its own default.
+  const effective = effectiveCapabilities(adapter, binding);
+  const hasStructuredRenderer = typeof adapter.renderContextResult === "function";
+  const canOfferNextTurn = effective.delivery.nextTurn === true && hasStructuredRenderer;
+  const projectionInput = { ...sync, messages: canOfferNextTurn ? messages : [],
+    liveOfferedMessageIds: delivery.liveOfferedMessageIds,
+    roomMessageIds: delivery.roomMessageIds,
+    currentParticipantId: mine?.participantId };
+  const projectionOptions = {
+    budgetBytes: context.descriptor.policy?.contextBudgetBytes };
+  // Delivery is state, not text parsing. Peer-controlled bodies can imitate
+  // another message's visible header, so only projector metadata proves
+  // which complete groups survived the byte budget. A custom adapter without
+  // metadata may still inject text, but cannot advance a receipt from it.
+  const projection = !hasStructuredRenderer
+    ? { text: await adapter.renderContext?.(projectionInput, projectionOptions) ?? "",
+      offeredMessageIds: [], includedAttentionIds: [] }
+    : await adapter.renderContextResult(projectionInput, projectionOptions);
+  const clientFactsKnown = typeof binding.clientVersion === "string"
+    && typeof binding.platform === "string";
+  const reason = !effective.delivery.nextTurn
+    ? clientFactsKnown
+      ? `client ${binding.clientVersion} on ${binding.platform} is not certified for nextTurn`
+      : "the client version or platform is unknown"
+    : !hasStructuredRenderer ? "this adapter lacks structured delivery metadata" : null;
+  const degradation = reason !== null && messages.length > 0
+    ? `acc: ${messages.length} pending message(s) withheld because ${reason}; read `
+      + `${messages[0].messageId} with acc inbox --message ${messages[0].messageId}` : null;
+  const visibleDegradation = degradation === null ? "" : `ACC: ${degradation.slice(5)}`;
+  const budgetBytes = projectionOptions.budgetBytes ?? 6_000;
+  const projected = degradation === null ? projection.text
+    : fitDegradation(projection.text, visibleDegradation, messages, budgetBytes);
+  if (projected === "") {
+    return degradation === null ? { stdout: "" } : { stdout: "", stderr: degradation };
+  }
+
+  // The renderer returns ids as metadata, never as text to parse. A peer body
+  // can imitate every visible label, so only a complete group selected by the
+  // projector is eligible for the post-write offer commit.
+  const offered = new Set(canOfferNextTurn ? projection.offeredMessageIds ?? [] : []);
+  const offerInputs = messages.filter(message => offered.has(message.messageId))
+    .map(message => ({ messageId: message.messageId,
+      recipientParticipantId: mine.participantId,
+      targetSessionId: binding.accSessionId, targetGeneration: binding.generation,
+      transport: "next-turn", adapterId,
+      clientVersion: binding.clientVersion }));
+  // Same again: Kimi Code shows the model a hook's raw stdout, while Gemini
+  // and Claude Code want an envelope and drop a bare string.
+  // The entry point owns the transport boundary. This handler only prepares
+  // offer inputs; recording them here would claim delivery before stdout's
+  // callback proves that the bytes crossed.
+  const outcome = { stdout: "", ...adapter.injectOutcome?.(projected) };
+  const writableOffers = outcome.stdout === "" ? [] : offerInputs;
+  if (degradation === null) return { ...outcome, offerInputs: writableOffers };
+  return { ...outcome,
+    stderr: [outcome.stderr, degradation].filter(Boolean).join("\n"),
+    offerInputs: writableOffers };
+}
+
+// One bounded, fail-open native handshake for this exact session generation.
+// The policy comes only from the environment an owned shell bootstrap
+// exported; an ordinary launch has none and stays durable.
+async function bindNative({ adapter, event, hookBinding, clientVersion, platform, context, paths,
+  deadline }) {
+  return establishNativeBinding({ adapter, event, hookBinding, clientVersion, platform,
+    livePolicy: livePolicyFrom(context.env), service: context.service, runtimeDir: paths.root,
+    clock: context.service.clock,
+    timeoutMs: Math.max(1, Math.min(750, deadline - Date.now())) });
+}
+
 const HANDLERS = {
   async sessionStart({ event, context, adapter, adapterId, binding, paths,
     readProcessTable, probeClientVersion, platform, deadline }) {
@@ -204,6 +306,9 @@ const HANDLERS = {
     const command = adapter.client?.command ?? null;
     const pid = command === null ? null
       : resolveClientPid({ table: await readProcessTable(), from: process.pid, command });
+    const clientPid = Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    const native = hookBinding => bindNative({ adapter, event, hookBinding, ...clientFacts,
+      context, paths, deadline });
     const metadata = {
       pid,
       enforcement: capabilities.guards?.beforeWrite === true ? "guarded" : "advisory",
@@ -219,10 +324,12 @@ const HANDLERS = {
         ...metadata,
       });
       if (resumed !== null) {
+        const hookBinding = { accSessionId: resumed.sessionId, generation: resumed.generation,
+          ...clientFacts, clientPid };
         await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
-          accSessionId: resumed.sessionId, generation: resumed.generation, ...clientFacts });
+          ...hookBinding });
         return { accSessionId: resumed.sessionId, generation: resumed.generation,
-          ...clientFacts, capabilities };
+          ...clientFacts, capabilities, nativeBinding: await native(hookBinding) };
       }
     }
     const session = await context.service.openSession({
@@ -239,10 +346,12 @@ const HANDLERS = {
       ...metadata,
       descriptor: context.descriptor,
     });
+    const hookBinding = { accSessionId: session.sessionId, generation: session.generation,
+      ...clientFacts, clientPid };
     await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
-      accSessionId: session.sessionId, generation: session.generation, ...clientFacts });
+      ...hookBinding });
     return { accSessionId: session.sessionId, generation: session.generation,
-      ...clientFacts, capabilities };
+      ...clientFacts, capabilities, nativeBinding: await native(hookBinding) };
   },
 
   async heartbeat({ binding, context }) {
@@ -260,97 +369,21 @@ const HANDLERS = {
     return {};
   },
 
-  async beforeTurn({ binding, context, adapter, adapterId }) {
+  async beforeTurn(input) {
+    const { binding, context, adapter, event, paths, deadline } = input;
     if (binding === null) return {};
     // A turn is the clearest sign a session is alive. Never a reason to fail:
     // this runs in front of somebody's prompt.
     await context.service.heartbeatSession({ sessionId: binding.accSessionId,
       generation: binding.generation }).catch(() => null);
-    const sync = await context.service.sync({ sessionId: binding.accSessionId,
-      cursor: null, scope: "delta" });
-
-    // Sync already carries the roster. Calling collectStatus here used to read
-    // the entire materialised store a second time on every prompt merely to
-    // rediscover this session's participant id.
-    const mine = sync.roster
-      .find(participant => participant.sessionId === binding.accSessionId);
-
-    // What peers have said to this participant and no model has been shown yet.
-    // Without this the projector's peer block never runs in production: an
-    // agent sees only the obligation attention line, not the durable body that
-    // may be offered after the stdout transport succeeds.
-    const delivery = await context.service.nextTurnDelivery({
-      workspaceId: context.descriptor.id,
-      participantId: mine?.participantId,
-      exceptSessionId: binding.accSessionId });
-    const messages = delivery.queuedMessages;
-
-    // Solo costs nothing: nothing to say means nothing printed, not a banner
-    // announcing that nobody else is here. But something already said to you is
-    // not nothing - the check used to run before the inbox was read, so the
-    // answer to your own request vanished the moment the agent working on it
-    // closed and left you as the only session.
-    if (sync.solo && messages.length === 0) return { stdout: "" };
-
-    // The ceiling a team agreed on in `acc.workspace.json`, or the default when
-    // there is no config. Validated by the protocol and, until now, never read:
-    // the projector was always called with its own default.
-    const effective = effectiveCapabilities(adapter, binding);
-    const hasStructuredRenderer = typeof adapter.renderContextResult === "function";
-    const canOfferNextTurn = effective.delivery.nextTurn === true && hasStructuredRenderer;
-    const projectionInput = { ...sync, messages: canOfferNextTurn ? messages : [],
-      liveOfferedMessageIds: delivery.liveOfferedMessageIds,
-      roomMessageIds: delivery.roomMessageIds,
-      currentParticipantId: mine?.participantId };
-    const projectionOptions = {
-      budgetBytes: context.descriptor.policy?.contextBudgetBytes };
-    // Delivery is state, not text parsing. Peer-controlled bodies can imitate
-    // another message's visible header, so only projector metadata proves
-    // which complete groups survived the byte budget. A custom adapter without
-    // metadata may still inject text, but cannot advance a receipt from it.
-    const projection = !hasStructuredRenderer
-      ? { text: await adapter.renderContext?.(projectionInput, projectionOptions) ?? "",
-        offeredMessageIds: [], includedAttentionIds: [] }
-      : await adapter.renderContextResult(projectionInput, projectionOptions);
-    const clientFactsKnown = typeof binding.clientVersion === "string"
-      && typeof binding.platform === "string";
-    const reason = !effective.delivery.nextTurn
-      ? clientFactsKnown
-        ? `client ${binding.clientVersion} on ${binding.platform} is not certified for nextTurn`
-        : "the client version or platform is unknown"
-      : !hasStructuredRenderer ? "this adapter lacks structured delivery metadata" : null;
-    const degradation = reason !== null && messages.length > 0
-      ? `acc: ${messages.length} pending message(s) withheld because ${reason}; read `
-        + `${messages[0].messageId} with acc inbox --message ${messages[0].messageId}` : null;
-    const visibleDegradation = degradation === null ? "" : `ACC: ${degradation.slice(5)}`;
-    const budgetBytes = projectionOptions.budgetBytes ?? 6_000;
-    const projected = degradation === null ? projection.text
-      : fitDegradation(projection.text, visibleDegradation, messages, budgetBytes);
-    if (projected === "") {
-      return degradation === null ? { stdout: "" } : { stdout: "", stderr: degradation };
-    }
-
-    // The renderer returns ids as metadata, never as text to parse. A peer body
-    // can imitate every visible label, so only a complete group selected by the
-    // projector is eligible for the post-write offer commit.
-    const offered = new Set(canOfferNextTurn ? projection.offeredMessageIds ?? [] : []);
-    const offerInputs = messages.filter(message => offered.has(message.messageId))
-      .map(message => ({ messageId: message.messageId,
-        recipientParticipantId: mine.participantId,
-        targetSessionId: binding.accSessionId, targetGeneration: binding.generation,
-        transport: "next-turn", adapterId,
-        clientVersion: binding.clientVersion }));
-    // Same again: Kimi Code shows the model a hook's raw stdout, while Gemini
-    // and Claude Code want an envelope and drop a bare string.
-    // The entry point owns the transport boundary. This handler only prepares
-    // offer inputs; recording them here would claim delivery before stdout's
-    // callback proves that the bytes crossed.
-    const outcome = { stdout: "", ...adapter.injectOutcome?.(projected) };
-    const writableOffers = outcome.stdout === "" ? [] : offerInputs;
-    if (degradation === null) return { ...outcome, offerInputs: writableOffers };
-    return { ...outcome,
-      stderr: [outcome.stderr, degradation].filter(Boolean).join("\n"),
-      offerInputs: writableOffers };
+    // A native transport that became ready only after SessionStart is picked
+    // up here and a live lease is renewed: bounded, fail-open, never on a guard.
+    const nativeBinding = livePolicyFrom(context.env) === "off" ? undefined
+      : await bindNative({ adapter, event, hookBinding: binding,
+        clientVersion: binding.clientVersion, platform: binding.platform, context, paths,
+        deadline });
+    const turn = await projectTurn(input);
+    return nativeBinding === undefined ? turn : { ...turn, nativeBinding };
   },
 
   async beforeTool({ binding, context, event, adapter }) {

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "exports": { ".": "./src/index.mjs" },

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

@@ -1,3 +1,4 @@
+import { applyNativeActivation, deactivateNative } from "./native-activation.mjs";
 import { finalizeRemoval, missingArtifactParents, recordInstall,
   removeEmptyOwnedDirectories, removeOwnedArtifacts } from "./ownership.mjs";
 
@@ -14,7 +15,7 @@ import { finalizeRemoval, missingArtifactParents, recordInstall,
  * three that work, plus the name of the one that did not.
  */
 export async function applyPlan({ plan, adapters, context, dataHome, dryRun = false,
-  accVersion = null }) {
+  accVersion = null, activation = {} }) {
   const byId = new Map(adapters.map(adapter => [adapter.id, adapter]));
   const results = { action: plan.action, dryRun, operations: [], skipped: plan.skipped,
     failed: [] };
@@ -37,22 +38,46 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
           requestedLivePolicy: operation.livePolicy ?? "off",
           livePolicy: operation.effectiveLivePolicy ?? "off" };
         const outcome = await adapter.install(installContext);
+        // A consented activation is applied after the adapter's own wiring, in
+        // a fixed order; an explicit off takes a recorded one back first so the
+        // record written below describes the machine as it now is.
+        const notes = [];
+        if (operation.deactivation !== undefined) {
+          const report = await deactivateNative({ nativeActivation: operation.deactivation,
+            ...activation });
+          notes.push(...describeTeardown(report));
+        }
+        let native = null;
+        let appendedRcBlock = false;
+        if (operation.nativeActivation !== undefined) {
+          const applied = await applyNativeActivation({ adapter,
+            activation: operation.nativeActivation, dataHome, ...activation });
+          native = applied.nativeActivation;
+          appendedRcBlock = applied.appendedRcBlock;
+        }
         // Recorded after the write, so a record never claims an install that
         // did not happen. The reverse order would leave uninstall trying to
         // remove files nothing created.
         await recordInstall({ dataHome, adapterId: adapter.id,
           version: operation.clientVersion ?? null, accVersion,
-          artifacts: operation.artifacts, createdDirectories });
-        results.operations.push({ ...operation, applied: true,
+          artifacts: operation.artifacts, createdDirectories, nativeActivation: native });
+        results.operations.push({ ...operation, applied: true, appendedRcBlock,
           changes: outcome.changes ?? [], diagnostics: [
             ...(operation.deliveryDiagnostic === undefined
               ? [] : [operation.deliveryDiagnostic]),
             ...(outcome.diagnostics ?? []),
+            ...notes,
           ] });
       } else {
         // Keep the record until every cleanup step succeeds. It is both the
         // authority for deletion and the only durable recipe a retry has when
         // the client or one of ACC's own artifacts is already gone.
+        const notes = [];
+        if (operation.deactivation !== undefined) {
+          const report = await deactivateNative({ nativeActivation: operation.deactivation,
+            ...activation });
+          notes.push(...describeTeardown(report));
+        }
         const owned = await removeOwnedArtifacts({ dataHome, adapterId: adapter.id });
         // What ownership held back is passed on, because the adapter would
         // otherwise remove its own layout unconditionally and undo the decision.
@@ -66,7 +91,7 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
           changes: outcome.changes ?? [], removed: owned.removed, kept: owned.kept,
           removedDirectories: directories.removed, keptDirectories: directories.kept,
           missingDirectories: directories.missing,
-          diagnostics: outcome.diagnostics ?? [] });
+          diagnostics: [...(outcome.diagnostics ?? []), ...notes] });
       }
     } catch (error) {
       results.failed.push({ adapterId: operation.adapterId, error: error.message });
@@ -74,3 +99,22 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
   }
   return results;
 }
+
+// What a deactivation actually did, said truthfully: a retained service is
+// named as retained, a modified PATH block as kept.
+function describeTeardown(report) {
+  const lines = [];
+  if (report.shell !== null) {
+    for (const file of report.shell.removedShims) lines.push(`removed shim ${file}`);
+    for (const file of report.shell.keptShims) lines.push(`kept shim ${file} - changed since ACC wrote it`);
+    if (report.shell.rcBlock === "removed") lines.push("removed the ACC PATH block");
+    if (report.shell.rcBlock === "modified") lines.push("kept the ACC PATH block - changed since ACC wrote it");
+    if (report.shell.rcBlock === "kept") lines.push("kept the ACC PATH block - another ACC shim still uses it");
+  }
+  for (const service of report.services) {
+    lines.push(service.outcome === "stopped" ? `stopped the ${service.serviceId} service`
+      : `retained the ${service.serviceId} service (${service.outcome === "retained_pre_existing"
+        ? "it existed before ACC" : "no vendor teardown exists"})`);
+  }
+  return lines;
+}

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

@@ -0,0 +1,144 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { evaluateNativeEligibility } from "@agents-can-communicate/adapter-sdk";
+
+// The launch-time check behind an owned shell shim. It answers one closed
+// question - may this exact executable receive native delivery? - from the
+// static minimum, a read-only adapter probe, and a keyed cache under ACC's own
+// data home. It never throws: a shim that cannot decide launches the vendor
+// command untouched, and this module is what makes "cannot decide" cheap.
+//
+// The cache key is the executable's identity - resolved path, symlink target,
+// inode, size, mtime, and full sha256 - so an upgrade or replacement is a miss
+// and an unchanged binary skips the version spawn and the probe. A cached
+// failure is short-lived; a repaired client is never disabled for long.
+
+export const BOOTSTRAP_CACHE_SCHEMA = 1;
+export const SUPPORTED_TTL_MS = 6 * 60 * 60 * 1_000;
+export const FAILED_TTL_MS = 5 * 60 * 1_000;
+const DEFAULT_TIMEOUT_MS = 750;
+const VERSION = /(?:^|[^0-9A-Za-z])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\b|$)/;
+
+export const cachePathFor = (dataHome, adapterId) =>
+  path.join(dataHome, "acc", "native-bootstrap", `${adapterId}.json`);
+
+function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    createReadStream(file).on("data", chunk => hash.update(chunk))
+      .on("error", reject).on("end", () => resolve(`sha256:${hash.digest("hex")}`));
+  });
+}
+
+async function executableIdentity(realExecutable) {
+  const target = await realpath(realExecutable);
+  const facts = await stat(target);
+  if (!facts.isFile()) throw new Error("not a file");
+  return { path: realExecutable, target, inode: facts.ino, size: facts.size,
+    mtimeMs: Math.floor(facts.mtimeMs), executableFingerprint: await sha256File(target) };
+}
+
+function withTimeout(work, ms, label) {
+  let timer = null;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(Object.assign(new Error(`${label} timed out`),
+      { code: "ETIMEDOUT" })), ms);
+  });
+  return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+}
+
+// Read-only: the client's own version command, nothing else.
+export function defaultReadVersion({ realExecutable, versionArgs, timeoutMs }) {
+  return new Promise(resolve => {
+    execFile(realExecutable, versionArgs, { timeout: timeoutMs, windowsHide: true },
+      (error, stdout, stderr) => {
+        if (error !== null) return resolve(null);
+        resolve(VERSION.exec(`${stdout}${stderr}`)?.[1] ?? null);
+      });
+  });
+}
+
+const sameIdentity = (left, right) => left !== undefined && right !== undefined
+  && ["path", "target", "inode", "size", "mtimeMs", "executableFingerprint"]
+    .every(key => left[key] === right[key]);
+
+async function loadCache(file) {
+  try {
+    const record = JSON.parse(await readFile(file, "utf8"));
+    return record?.schemaVersion === BOOTSTRAP_CACHE_SCHEMA ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+async function saveCache(file, record) {
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, file);
+}
+
+const closedOutcome = (supported, reasonCode) => Object.freeze({ supported, reasonCode });
+
+export async function checkNativeBootstrap({ adapter, realExecutable, platform, dataHome,
+  timeoutMs = DEFAULT_TIMEOUT_MS, clock = { now: () => new Date().toISOString() },
+  readVersion = defaultReadVersion }) {
+  try {
+    if (adapter?.nativeDelivery === undefined || typeof adapter.probeNativeDelivery !== "function") {
+      return closedOutcome(false, "native_delivery_unsupported");
+    }
+    const identity = await executableIdentity(realExecutable);
+    const file = cachePathFor(dataHome, adapter.id);
+    const now = Date.parse(clock.now());
+    const cached = await loadCache(file);
+    if (cached !== null && cached.adapterId === adapter.id && cached.platform === platform
+      && sameIdentity(cached.identity, identity) && Date.parse(cached.expiresAt) > now) {
+      return closedOutcome(cached.supported, cached.reasonCode);
+    }
+
+    const clientVersion = await withTimeout(readVersion({ realExecutable: identity.target,
+      versionArgs: adapter.client?.versionArgs ?? ["--version"], timeoutMs }), timeoutMs,
+    "version probe").catch(() => null);
+    let probe = null;
+    let reasonCode = null;
+    if (clientVersion !== null) {
+      try {
+        probe = await withTimeout(adapter.probeNativeDelivery({ realExecutable: identity.target,
+          timeoutMs }), timeoutMs, "native probe");
+      } catch (error) {
+        probe = null;
+        reasonCode = error?.code === "ETIMEDOUT" ? "probe_timeout" : "feature_probe_failed";
+      }
+    }
+    let eligibility;
+    try {
+      eligibility = evaluateNativeEligibility(adapter, { clientVersion, platform, probe });
+    } catch {
+      // A malformed probe is an adapter bug, and still not a reason to change
+      // the user's launch: it fails closed like any other probe failure.
+      eligibility = { eligible: false, reasonCode: "feature_probe_failed" };
+    }
+    const supported = eligibility.eligible === true;
+    // A probe that timed out or threw is reported as such rather than as the
+    // generic verdict the missing probe would otherwise produce.
+    const outcomeReason = supported ? null : (reasonCode ?? eligibility.reasonCode
+      ?? "feature_probe_failed");
+    // Only closed facts are stored: identity, versions, the eligibility verdict.
+    // Never command output, never a message body.
+    await saveCache(file, {
+      schemaVersion: BOOTSTRAP_CACHE_SCHEMA, adapterId: adapter.id, platform, identity,
+      clientVersion, supported, reasonCode: outcomeReason,
+      protocolContract: supported ? eligibility.protocolContract : null,
+      modes: supported ? [...eligibility.modes] : [],
+      checkedAt: new Date(now).toISOString(),
+      expiresAt: new Date(now + (supported ? SUPPORTED_TTL_MS : FAILED_TTL_MS)).toISOString(),
+    }).catch(() => null);
+    return closedOutcome(supported, outcomeReason);
+  } catch {
+    return closedOutcome(false, "feature_probe_failed");
+  }
+}

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

@@ -1,10 +1,19 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
-import { effectiveCapabilities } from "@agents-can-communicate/adapter-sdk";
+import { effectiveCapabilities, evaluateNativeEligibility, validateNativeActivationPlan }
+  from "@agents-can-communicate/adapter-sdk";
+
+import { resolveExecutable, shellOf, shimDirFor } from "./native-activation.mjs";
 
 const run = promisify(execFile);
 
+// Reasons the client itself will not change within an install: unsupported,
+// as opposed to degraded, which a repaired probe or shell may lift.
+const STATIC_REASONS = new Set(["native_delivery_unsupported", "platform_not_captured",
+  "version_unavailable", "prerelease_not_captured", "below_minimum_version",
+  "known_bad_version"]);
+
 const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
 
 // Clients print their version in their own shape: "codex-cli 0.147.0", a bare
@@ -37,9 +46,65 @@ const withTimeout = (work, ms, label) => new Promise((resolve, reject) => {
  * exactly the case someone is running this command to find out about, and
  * letting it throw would hide the other three behind it.
  */
+const unsupported = reasonCode => ({ state: "unsupported", reasonCode, realExecutable: null,
+  probe: null, eligibility: null, activationPlan: null });
+const degraded = (reasonCode, facts) => ({ state: "degraded", reasonCode, activationPlan: null,
+  ...facts });
+
+/**
+ * The read-only native-delivery report for one detected client: which
+ * executable a shim would exec, what the adapter's probe saw, the static
+ * verdict, and the activation the adapter would ask for. Version, help, and
+ * protocol probes only; never a service mutation.
+ */
+async function detectNative(adapter, entry, { context, platform, probeTimeoutMs, pathEnv }) {
+  if (adapter.nativeDelivery === undefined) return unsupported("native_delivery_unsupported");
+  try {
+    const realExecutable = await resolveExecutable(adapter.client.command, { pathEnv,
+      exclude: [typeof context?.stateRoot === "string" ? shimDirFor(context.stateRoot) : null] });
+    if (realExecutable === null) return unsupported("version_unavailable");
+    const facts = { realExecutable, probe: null, eligibility: null };
+    try {
+      facts.probe = await withTimeout(Promise.resolve(adapter.probeNativeDelivery({
+        realExecutable, timeoutMs: probeTimeoutMs })), probeTimeoutMs,
+      `${adapter.id} native probe`);
+    } catch {
+      facts.probe = null;
+    }
+    try {
+      facts.eligibility = evaluateNativeEligibility(adapter,
+        { clientVersion: entry.version, platform, probe: facts.probe });
+    } catch {
+      facts.eligibility = { eligible: false, reasonCode: "feature_probe_failed" };
+    }
+    if (facts.eligibility.eligible !== true) {
+      const reasonCode = facts.eligibility.reasonCode ?? "feature_probe_failed";
+      return STATIC_REASONS.has(reasonCode)
+        ? { ...unsupported(reasonCode), ...facts } : degraded(reasonCode, facts);
+    }
+    let activationPlan;
+    try {
+      activationPlan = validateNativeActivationPlan(await adapter.planNativeActivation({
+        detection: { realExecutable, version: entry.version, platform, probe: facts.probe },
+        context, livePolicy: null }));
+    } catch {
+      return degraded("feature_probe_failed", facts);
+    }
+    if (!activationPlan.eligible) return degraded(activationPlan.reasonCode, facts);
+    const shell = context?.shell ?? null;
+    if (activationPlan.mechanisms.some(item => item.kind === "shell-bootstrap") && shell !== "zsh") {
+      return { ...degraded("unsupported_shell", facts), activationPlan };
+    }
+    return { state: "eligible", reasonCode: null, ...facts, activationPlan };
+  } catch {
+    return degraded("feature_probe_failed", { realExecutable: null, probe: null, eligibility: null });
+  }
+}
+
 export async function detectInstallation({ adapters, context, probe = spawnProbe,
   probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS,
-  platform = `${process.platform}-${process.arch}` }) {
+  platform = `${process.platform}-${process.arch}`,
+  pathEnv = context?.env?.PATH ?? process.env.PATH ?? "" }) {
   const entries = await Promise.all([...adapters]
     // Ordered by id so two runs can be diffed, and so a plan built from this is
     // deterministic rather than dependent on registry order.
@@ -67,6 +132,10 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
       }
       entry.capabilities = effectiveCapabilities(adapter,
         { clientVersion: entry.version, platform });
+      entry.nativeDelivery = entry.present
+        ? await detectNative(adapter, entry, { context, platform, probeTimeoutMs, pathEnv })
+        : unsupported(adapter.nativeDelivery === undefined
+          ? "native_delivery_unsupported" : "version_unavailable");
 
       try {
         const detected = await adapter.detect(context);
@@ -82,7 +151,7 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
       } catch (error) {
         entry.error = entry.error ?? error.message;
       }
-      if (entry.capabilities?.delivery?.livePush !== true
+      if (entry.nativeDelivery.state !== "eligible"
         && typeof adapter.deliveryFallback?.diagnostic === "string") {
         const nextTurnDowngraded = adapter.capabilities?.delivery?.nextTurn === true
           && entry.capabilities?.delivery?.nextTurn !== true;

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

@@ -5,3 +5,10 @@ export { applyPlan } from "./apply.mjs";
 export { finalizeRemoval, fingerprint, loadOwnership, missingArtifactParents, recordInstall,
   removeEmptyOwnedDirectories, removeOwned, removeOwnedArtifacts, treeFingerprint, verifyOwned }
   from "./ownership.mjs";
+export { BOOTSTRAP_CACHE_SCHEMA, FAILED_TTL_MS, SUPPORTED_TTL_MS, cachePathFor,
+  checkNativeBootstrap } from "./bootstrap-runtime.mjs";
+export { BLOCK_BEGIN, BLOCK_END, SHIM_MARKER, SHIM_POLICIES, SUPPORTED_SHELLS,
+  installShellBootstrap, locateBlock, planShellBootstrap, renderCommandShim, renderPathBlock,
+  shellLiteral, uninstallShellBootstrap, validateShimEntry } from "./shell-bootstrap.mjs";
+export { LIVE_POLICIES, describeActivation, describeDeactivation, livePolicyOf, rcFileFor,
+  resolveExecutable, shellOf, shimDirFor } from "./native-activation.mjs";