agents-can-communicate 0.1.17 → 0.2.0

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

@@ -0,0 +1,117 @@
+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"]);
+const NAMED_LIVE_TRANSPORTS = new Set(["claude-channel", "codex-app-server"]);
+
+const adaptersById = adapters => adapters instanceof Map
+  ? adapters
+  : new Map((Array.isArray(adapters) ? adapters : Object.values(adapters ?? {}))
+    .map(adapter => [adapter.id, adapter]));
+
+const permits = (policy, kind) => policy === "all"
+  || (policy === "actionable" && ["question", "request", "handoff"].includes(kind));
+
+const durable = (recipientParticipantId, errorCode) => ({ recipientParticipantId,
+  outcome: "queued", transport: "durable", errorCode });
+
+const settled = receipt => ({ recipientParticipantId: receipt.recipientParticipantId,
+  outcome: receipt.state, transport: "durable" });
+
+function safeTransport(value, opaqueEndpointRef) {
+  if (NAMED_LIVE_TRANSPORTS.has(value) && value !== opaqueEndpointRef) return value;
+  // Both markers are fixed router vocabulary. The alternate prevents even a
+  // coincidental endpoint value equal to the primary redaction from escaping.
+  return opaqueEndpointRef === "live-adapter" ? "native-live" : "live-adapter";
+}
+
+export function createDeliveryRouter({ service, adapters, clock }) {
+  const registry = adaptersById(adapters);
+
+  async function recordFailure(binding, message, participantId, transport, safeErrorCode) {
+    await service.recordOfferFailed({ messageId: message.messageId,
+      recipientParticipantId: participantId, targetSessionId: binding.sessionId,
+      targetGeneration: binding.generation,
+      transport: safeTransport(transport, binding.opaqueEndpointRef), adapterId: binding.adapterId,
+      clientVersion: binding.clientVersion, safeErrorCode }).catch(() => null);
+  }
+
+  async function offerTo(message, participantId, now) {
+    const receipt = await service.readReceipt({ messageId: message.messageId,
+      recipientParticipantId: participantId });
+    if (receipt.state !== "queued") return settled(receipt);
+    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 }))
+      .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));
+    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,
+      adapter: registry.get(binding.adapterId) }))
+      .filter(({ binding, adapter }) => adapter !== undefined
+        && effectiveCapabilities(adapter,
+          { clientVersion: binding.clientVersion, platform: PLATFORM }).delivery.livePush);
+    if (certified.length === 0) {
+      return durable(participantId, "unsupported_client_version");
+    }
+    if (certified.length > 1) {
+      return durable(participantId, "ambiguous_recipient_sessions");
+    }
+
+    const { binding, adapter } = certified[0];
+    let response;
+    try {
+      response = await adapter.offerMessage({ binding, message });
+    } catch {
+      await recordFailure(binding, message, participantId, "live-adapter", "transport_error");
+      return durable(participantId, "transport_error");
+    }
+    const transport = safeTransport(response?.transport, binding.opaqueEndpointRef);
+    if (response?.accepted !== true) {
+      const code = SAFE_ERRORS.has(response?.safeErrorCode)
+        ? response.safeErrorCode : "transport_rejected";
+      await recordFailure(binding, message, participantId, transport, code);
+      return durable(participantId, code);
+    }
+    if (response.clientVersion !== binding.clientVersion) {
+      await recordFailure(binding, message, participantId, transport,
+        "unsupported_client_version");
+      return durable(participantId, "unsupported_client_version");
+    }
+    try {
+      await service.recordOfferSucceeded({ messageId: message.messageId,
+        recipientParticipantId: participantId, targetSessionId: binding.sessionId,
+        targetGeneration: binding.generation, transport, adapterId: binding.adapterId,
+        clientVersion: binding.clientVersion });
+    } catch {
+      await recordFailure(binding, message, participantId, transport, "transport_error");
+      return durable(participantId, "transport_error");
+    }
+    return { recipientParticipantId: participantId, outcome: "offered", transport };
+  }
+
+  async function offer(message) {
+    if (!Array.isArray(message?.toParticipantIds) || message.toParticipantIds.length === 0) {
+      return [];
+    }
+    const now = clock.now();
+    const outcomes = [];
+    for (const participantId of message.toParticipantIds) {
+      outcomes.push(await offerTo(message, participantId, now));
+    }
+    return outcomes;
+  }
+
+  return Object.freeze({ offer });
+}

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

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

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

@@ -0,0 +1,20 @@
+import { execFile } from "node:child_process";
+
+const VERSION = /(?:^|[^0-9A-Za-z])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\b|$)/;
+
+export function parseClientVersion(output) {
+  return typeof output === "string" ? VERSION.exec(output)?.[1] ?? null : null;
+}
+
+/** Probe the client binary once when its real session starts. */
+export function probeClientVersion(adapter, { timeoutMs = 1_000 } = {}) {
+  return new Promise(resolve => {
+    execFile(adapter.client.command, adapter.client.versionArgs ?? ["--version"], {
+      timeout: timeoutMs,
+      windowsHide: true,
+    }, (error, stdout, stderr) => {
+      if (error !== null) return resolve(null);
+      resolve(parseClientVersion(`${stdout}${stderr}`));
+    });
+  });
+}

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

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
 
-import { clearSessionBinding, loadSessionBinding, storeSessionBinding }
+import { clearSessionBinding, effectiveCapabilities, loadSessionBinding, storeSessionBinding }
   from "@agents-can-communicate/adapter-sdk";
 import { createCoordinationService } from "@agents-can-communicate/core";
 import { createId } from "@agents-can-communicate/protocol";
@@ -11,12 +11,40 @@ import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
   from "@agents-can-communicate/cli";
 
 import { resolveClientPid } from "./client-pid.mjs";
+import { probeClientVersion as defaultProbeClientVersion } from "./client-version.mjs";
 import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
 
+// Kept cohesive above 300 lines because every handler shares one fail-open
+// hook boundary, binding lifecycle, and client-specific outcome contract.
+// Splitting handlers would duplicate that safety boundary and make delivery or
+// guard failures behave differently by event kind.
+
 // A hook runs in front of the user's turn, so it gets a hard ceiling. Better to
 // let a call through than to make someone's session sit waiting on us.
 const DEFAULT_BUDGET_MS = 5_000;
 
+const byteLength = value => Buffer.byteLength(value, "utf8");
+
+function compactInboxRecovery(messages) {
+  const first = messages[0].messageId;
+  const rest = messages.length > 1 ? ` (+${messages.length - 1} more in \`acc inbox\`)` : "";
+  return `ACC: read pending peer message: \`acc inbox --message ${first}\`${rest}`;
+}
+
+function fitDegradation(projection, visibleDegradation, messages, budgetBytes) {
+  const full = [projection, visibleDegradation].filter(Boolean).join("\n");
+  if (byteLength(full) <= budgetBytes) return full;
+  const recovery = compactInboxRecovery(messages);
+  const exactRecovery = compactInboxRecovery(messages.slice(0, 1));
+  const withRecovery = [projection, recovery].filter(Boolean).join("\n");
+  if (byteLength(withRecovery) <= budgetBytes) return withRecovery;
+  const withExactRecovery = [projection, exactRecovery].filter(Boolean).join("\n");
+  if (byteLength(withExactRecovery) <= budgetBytes) return withExactRecovery;
+  if (byteLength(recovery) <= budgetBytes) return recovery;
+  if (byteLength(exactRecovery) <= budgetBytes) return exactRecovery;
+  return projection;
+}
+
 // Declared by this process on the session it opens, so peers can tell an idle
 // session from a dead one. Only one of the four clients fires a heartbeat event,
 // so the rest refresh here: on every turn, and during a long one whenever the
@@ -157,14 +185,46 @@ async function openContext({ cwd, dataHome, runtime, env }) {
 }
 
 const HANDLERS = {
-  async sessionStart({ event, context, adapter, adapterId, paths, readProcessTable }) {
-    const capabilities = adapter.capabilities ?? {};
+  async sessionStart({ event, context, adapter, adapterId, binding, paths,
+    readProcessTable, probeClientVersion, platform, deadline }) {
+    // A repeated start refreshes the client's version/platform. Remove the old
+    // certified facts before any probe, PID lookup, resume, or open can fail;
+    // keep only the generation identity needed for a successful resume.
+    if (binding !== null) {
+      await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+        accSessionId: binding.accSessionId, generation: binding.generation });
+    }
+    const clientVersion = await probeClientVersion(adapter,
+      { timeoutMs: Math.max(1, Math.min(1_000, deadline - Date.now())) });
+    const clientFacts = { clientVersion, platform };
+    const capabilities = effectiveCapabilities(adapter, clientFacts);
     // Once per session, never per turn. A client that cannot be found yields
     // null, and the session is then judged by age alone - which is exactly the
     // behaviour every session had before this existed.
     const command = adapter.client?.command ?? null;
     const pid = command === null ? null
       : resolveClientPid({ table: await readProcessTable(), from: process.pid, command });
+    const metadata = {
+      pid,
+      enforcement: capabilities.guards?.beforeWrite === true ? "guarded" : "advisory",
+      lifecycle: capabilities.lifecycle?.sessionEnd === true ? "managed" : "manual",
+      heartbeatCadenceMs: CADENCE_MS,
+      checkoutRoot: context.descriptor.git?.worktreeRoot ?? context.descriptor.roots[0],
+      branch: context.descriptor.git?.branch ?? null,
+    };
+    if (binding !== null) {
+      const resumed = await context.service.resumeSession({
+        sessionId: binding.accSessionId,
+        generation: binding.generation,
+        ...metadata,
+      });
+      if (resumed !== null) {
+        await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
+          accSessionId: resumed.sessionId, generation: resumed.generation, ...clientFacts });
+        return { accSessionId: resumed.sessionId, generation: resumed.generation,
+          ...clientFacts, capabilities };
+      }
+    }
     const session = await context.service.openSession({
       workspaceId: context.descriptor.id,
       participantId: participantFor(adapterId, event.sessionId, context.env),
@@ -174,19 +234,15 @@ const HANDLERS = {
       // Declared from what this adapter proved, not from the fact that it is an
       // adapter at all. A peer reading the roster can then tell a session whose
       // writes can be stopped from one whose cannot.
-      enforcement: capabilities.guards?.beforeWrite === true ? "guarded" : "advisory",
-      lifecycle: capabilities.lifecycle?.sessionEnd === true ? "managed" : "manual",
-      heartbeatCadenceMs: CADENCE_MS,
       // Which checkout this agent is in. One workspace spans every worktree of
       // a repository, so this is the only thing that distinguishes them.
-      checkoutRoot: context.descriptor.git?.worktreeRoot ?? context.descriptor.roots[0],
-      pid,
-      branch: context.descriptor.git?.branch ?? null,
+      ...metadata,
       descriptor: context.descriptor,
     });
     await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
-      accSessionId: session.sessionId, generation: session.generation });
-    return { accSessionId: session.sessionId, generation: session.generation };
+      accSessionId: session.sessionId, generation: session.generation, ...clientFacts });
+    return { accSessionId: session.sessionId, generation: session.generation,
+      ...clientFacts, capabilities };
   },
 
   async heartbeat({ binding, context }) {
@@ -204,7 +260,7 @@ const HANDLERS = {
     return {};
   },
 
-  async beforeTurn({ binding, context, adapter }) {
+  async beforeTurn({ binding, context, adapter, adapterId }) {
     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.
@@ -213,36 +269,21 @@ const HANDLERS = {
     const sync = await context.service.sync({ sessionId: binding.accSessionId,
       cursor: null, scope: "delta" });
 
-    // Claims held by others, and whether this session can actually be stopped
-    // from breaking them. For a harness that guards writes this is useful
-    // warning; for one that cannot - a Codex model editing through the shell,
-    // an MCP client - it is the only protection there is, so it has to say
-    // plainly that the responsibility has moved to the session itself.
-    const status = await context.service.collectStatus({
-      workspaceId: context.descriptor.id });
-    const mine = status.participants
+    // 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);
-    // Two independent facts, and both are needed. `enforceable` is whether ACC
-    // could stop *this* session at all; `enforcement` is what the claim's owner
-    // asked for. A guarded session facing an advisory claim is not blocked from
-    // anything, so reporting either one alone mislabels the other case.
-    const enforceable = mine?.enforcement === "guarded";
-    const claims = status.claims
-      .filter(claim => claim.ownerSessionId !== binding.accSessionId)
-      .map(claim => ({ resource: claim.resource, enforcement: claim.enforcement,
-        enforceable,
-        ownerParticipantId: status.participants
-          .find(p => p.sessionId === claim.ownerSessionId)?.participantId
-          ?? claim.ownerSessionId }));
 
     // What peers have said to this participant and no model has been shown yet.
-    // Without this the projector's peer block never ran in production: an agent
-    // saw only the subject of a message through its attention line, and the
-    // `injected` delivery state was unreachable.
-    const messages = await context.service.pendingMessages({
+    // 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
@@ -254,32 +295,62 @@ const HANDLERS = {
     // 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 projected = await adapter.renderContext?.({ ...sync, claims, messages },
-      { budgetBytes: context.descriptor.policy?.contextBudgetBytes }) ?? "";
-    if (projected === "") return { stdout: "" };
-
-    // Only what the model was actually shown is recorded as delivered. The
-    // budget can leave a message out, and a receipt reading `injected` for text
-    // nobody saw is worse than one still reading `queued` - the sender would be
-    // told it landed. A message left behind stays queued and goes out next turn.
-    const failures = [];
-    for (const message of messages) {
-      if (!projected.includes(message.messageId)) continue;
-      await context.service.markDelivery({ sessionId: binding.accSessionId,
-        generation: binding.generation, messageId: message.messageId,
-        recipientParticipantId: mine.participantId, state: "injected" })
-        .catch(error => failures.push(`${message.messageId}: ${error.message}`));
+    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.
-    // Reported rather than swallowed. The context still goes out - losing it
-    // over bookkeeping would be the worse trade - but a receipt that failed to
-    // advance has to be visible somewhere, and stdout belongs to the model.
+    // 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) };
-    if (failures.length === 0) return outcome;
+    const writableOffers = outcome.stdout === "" ? [] : offerInputs;
+    if (degradation === null) return { ...outcome, offerInputs: writableOffers };
     return { ...outcome,
-      stderr: [outcome.stderr, `acc: delivery not recorded for ${failures.join(", ")}`]
-        .filter(Boolean).join("\n") };
+      stderr: [outcome.stderr, degradation].filter(Boolean).join("\n"),
+      offerInputs: writableOffers };
   },
 
   async beforeTool({ binding, context, event, adapter }) {
@@ -350,8 +421,12 @@ const HANDLERS = {
  */
 export async function runHook({ adapterId, payload, adapters, dataHome, env,
   runtime = defaultRuntime(), budgetMs = DEFAULT_BUDGET_MS,
-  readProcessTable = defaultReadProcessTable }) {
-  const result = { stdout: "", exitCode: 0, decision: "allow", sessions: [] };
+  readProcessTable = defaultReadProcessTable,
+  probeClientVersion = defaultProbeClientVersion,
+  platform = `${process.platform}-${process.arch}` }) {
+  const deadline = Date.now() + budgetMs;
+  const result = { stdout: "", exitCode: 0, decision: "allow", sessions: [], deadlineAt: deadline,
+    commitOffers: async () => {} };
   let timer = null;
   try {
     const adapter = adapters?.[adapterId];
@@ -366,7 +441,7 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     const work = handler === undefined
       ? Promise.resolve({})
       : handler({ event, context, adapter, adapterId, binding, paths: context.paths,
-        readProcessTable });
+        readProcessTable, probeClientVersion, platform, deadline });
 
     // The loser of a race is not cancelled, so the timer is cleared explicitly:
     // an outstanding one keeps the process alive long past its answer.
@@ -375,6 +450,24 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     });
     Object.assign(result, await Promise.race([work, budget]));
 
+    const offerInputs = result.offerInputs ?? [];
+    let commitPromise = null;
+    result.commitOffers = () => {
+      if (commitPromise !== null) return commitPromise;
+      commitPromise = (async () => {
+        for (const input of offerInputs) {
+          const remaining = deadline - Date.now();
+          if (remaining <= 0) throw new Error("hook budget exhausted before offer commit");
+          // The durable transaction owns deadline cancellation. Racing it here
+          // would only reject the public promise while the losing writer kept
+          // waiting and could publish later.
+          await context.service.recordOfferSucceeded({ ...input, deadlineAt: deadline });
+        }
+      })();
+      return commitPromise;
+    };
+    delete result.offerInputs;
+
     const status = await context.service.collectStatus({
       workspaceId: context.descriptor.id });
     result.sessions = status.participants.filter(p => p.presence !== "offline");
@@ -384,6 +477,9 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     result.reason = error.message;
     result.decision = "allow";
     result.stdout = "";
+    // A later failure may happen after a turn prepared offer inputs. Once the
+    // fail-open path withdraws stdout, no transport boundary remains to commit.
+    result.commitOffers = async () => {};
   } finally {
     if (timer !== null) clearTimeout(timer);
   }

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

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

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

@@ -1,4 +1,5 @@
-import { recordInstall, removeOwned } from "./ownership.mjs";
+import { finalizeRemoval, missingArtifactParents, recordInstall,
+  removeEmptyOwnedDirectories, removeOwnedArtifacts } from "./ownership.mjs";
 
 /**
  * Carry out a plan, one adapter at a time.
@@ -30,26 +31,41 @@ export async function applyPlan({ plan, adapters, context, dataHome, dryRun = fa
 
     try {
       if (plan.action === "install") {
-        const outcome = await adapter.install(context);
+        const createdDirectories = await missingArtifactParents({ home: context.home,
+          artifacts: operation.artifacts });
+        const installContext = { ...context,
+          requestedLivePolicy: operation.livePolicy ?? "off",
+          livePolicy: operation.effectiveLivePolicy ?? "off" };
+        const outcome = await adapter.install(installContext);
         // 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 });
+          artifacts: operation.artifacts, createdDirectories });
         results.operations.push({ ...operation, applied: true,
-          changes: outcome.changes ?? [], diagnostics: outcome.diagnostics ?? [] });
+          changes: outcome.changes ?? [], diagnostics: [
+            ...(operation.deliveryDiagnostic === undefined
+              ? [] : [operation.deliveryDiagnostic]),
+            ...(outcome.diagnostics ?? []),
+          ] });
       } else {
-        // Ownership first: it decides what may be deleted, and the adapter's own
-        // uninstall then unpicks the entries it added to files the user owns.
-        const owned = await removeOwned({ dataHome, adapterId: adapter.id });
+        // 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 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.
         // The case that matters: someone put their own work inside a directory
         // ACC created, and a recognised path is not a reason to delete it.
         const outcome = await adapter.uninstall({ ...context, keep: owned.kept });
+        const directories = await removeEmptyOwnedDirectories({ home: context.home,
+          directories: owned.createdDirectories });
+        await finalizeRemoval({ dataHome, adapterId: adapter.id });
         results.operations.push({ ...operation, applied: true,
           changes: outcome.changes ?? [], removed: owned.removed, kept: owned.kept,
+          removedDirectories: directories.removed, keptDirectories: directories.kept,
+          missingDirectories: directories.missing,
           diagnostics: outcome.diagnostics ?? [] });
       }
     } catch (error) {

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

@@ -1,6 +1,8 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
+import { effectiveCapabilities } from "@agents-can-communicate/adapter-sdk";
+
 const run = promisify(execFile);
 
 const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
@@ -9,7 +11,7 @@ const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
 // "0.36.1", a banner with the number somewhere inside. The number is extracted
 // where it can be, and the raw line is kept either way - "present, version
 // unreadable" is a real state and hiding it would make the client look absent.
-const VERSION = /\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\b/;
+const VERSION = /(?:^|[^0-9A-Za-z])v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\b|$)/;
 
 /**
  * Ask the operating system what a client reports as its version.
@@ -36,7 +38,8 @@ const withTimeout = (work, ms, label) => new Promise((resolve, reject) => {
  * letting it throw would hide the other three behind it.
  */
 export async function detectInstallation({ adapters, context, probe = spawnProbe,
-  probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS }) {
+  probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS,
+  platform = `${process.platform}-${process.arch}` }) {
   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.
@@ -44,8 +47,8 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
     .map(async adapter => {
       const entry = { adapterId: adapter.id, displayName: adapter.displayName,
         present: false, version: null, versionOutput: null, installed: false,
-        diagnostics: [], needsAction: [], capabilities: adapter.capabilities ?? {},
-        error: null };
+        diagnostics: [], needsAction: [], capabilities: effectiveCapabilities(adapter),
+        deliveryDiagnostic: null, error: null };
 
       try {
         const output = await withTimeout(
@@ -62,10 +65,12 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
       } catch (error) {
         entry.error = error.message;
       }
+      entry.capabilities = effectiveCapabilities(adapter,
+        { clientVersion: entry.version, platform });
 
       try {
         const detected = await adapter.detect(context);
-        entry.diagnostics = detected.diagnostics ?? [];
+        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.
         entry.needsAction = detected.needsAction ?? [];
@@ -77,6 +82,16 @@ export async function detectInstallation({ adapters, context, probe = spawnProbe
       } catch (error) {
         entry.error = entry.error ?? error.message;
       }
+      if (entry.capabilities?.delivery?.livePush !== true
+        && 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);
+      }
       return entry;
     }));
   return entries;

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

@@ -2,5 +2,6 @@
 export { detectInstallation, spawnProbe } from "./detect.mjs";
 export { planInstallation } from "./plan.mjs";
 export { applyPlan } from "./apply.mjs";
-export { fingerprint, loadOwnership, recordInstall, removeOwned, treeFingerprint,
-  verifyOwned } from "./ownership.mjs";
+export { finalizeRemoval, fingerprint, loadOwnership, missingArtifactParents, recordInstall,
+  removeEmptyOwnedDirectories, removeOwned, removeOwnedArtifacts, treeFingerprint, verifyOwned }
+  from "./ownership.mjs";