agents-can-communicate 0.8.4 → 0.9.0

package/node_modules/@agents-can-communicate/adapter-sdk/src/capabilities.mjs

@@ -81,6 +81,41 @@ export function assertCapabilities(declared = {}, implementation = {}, certifica
   return freezeCapabilities(resolved);
 }
 
+/**
+ * The other products whose hooks one adapter serves. Antigravity 2.0 runs the
+ * same `~/.gemini/config/hooks.json` as Antigravity CLI, on its own version
+ * line, so its evidence is recorded under its own certification name. A
+ * variant names a product, not a launch mode: one adapter's hooks, one more
+ * version line.
+ */
+function validateClientVariants(variants, primary) {
+  if (variants === undefined) return [];
+  if (!Array.isArray(variants)) usage("client.variants must be an array", { variants });
+  const seen = new Set([primary]);
+  return variants.map((variant, index) => {
+    if (variant === null || typeof variant !== "object" || Array.isArray(variant)) {
+      usage(`client.variants entry ${index} must be an object`);
+    }
+    for (const key of Object.keys(variant)) {
+      if (!["certificationName", "displayName"].includes(key)) {
+        usage(`client.variants entry ${index} has unknown field ${key}`, { key });
+      }
+    }
+    const { certificationName, displayName } = variant;
+    if (typeof certificationName !== "string" || certificationName.trim() === "") {
+      usage(`client.variants entry ${index} certificationName must be a non-empty string`);
+    }
+    if (typeof displayName !== "string" || displayName.trim() === "") {
+      usage(`client.variants entry ${index} displayName must be a non-empty string`);
+    }
+    if (seen.has(certificationName)) {
+      usage(`client.variants entry ${index} repeats ${certificationName}`, { certificationName });
+    }
+    seen.add(certificationName);
+    return { certificationName, displayName };
+  });
+}
+
 export function defineAdapter(manifest) {
   if (typeof manifest?.id !== "string") usage("an adapter must declare an id");
   assertPortableId(manifest.id, "adapter id");
@@ -104,15 +139,25 @@ export function defineAdapter(manifest) {
   const certification = validateCertification(manifest.certification);
   const known = new Set(Object.entries(CAPABILITY_SHAPE)
     .flatMap(([group, names]) => names.map(name => `${group}.${name}`)));
+  const primary = manifest.client.certificationName ?? manifest.client.command;
+  const clients = new Set([primary, ...validateClientVariants(manifest.client.variants, primary)
+    .map(variant => variant.certificationName)]);
   for (const item of certification.evidence) {
     if (!known.has(item.capability)) {
       usage(`unknown certified capability: ${item.capability}`,
         { capability: item.capability });
     }
-    const client = manifest.client.certificationName ?? manifest.client.command;
-    if (item.client !== client) {
-      usage(`certification evidence client ${item.client} does not match ${client}`,
-        { evidenceClient: item.client, client });
+    if (!clients.has(item.client)) {
+      usage(`certification evidence client ${item.client} does not match ${primary}`,
+        { evidenceClient: item.client, client: primary });
+    }
+  }
+  // How the hook runner learns which product and which version a session runs
+  // in, from the process that runs it rather than the binary on PATH. Both are
+  // optional; an adapter without them is matched by client.command.
+  for (const method of ["identifyClientProcess", "clientVersionOf"]) {
+    if (manifest[method] !== undefined && typeof manifest[method] !== "function") {
+      usage(`optional client method ${method} must be a function`, { id: manifest.id, method });
     }
   }
   // A floor said "judge later versions by this capture". Evidence now does that
@@ -139,7 +184,7 @@ export function defineAdapter(manifest) {
   if (manifest.nativeDelivery !== undefined) {
     const client = manifest.client.certificationName ?? manifest.client.command;
     native.nativeDelivery = validateNativeDeliveryContract(manifest.nativeDelivery,
-      { certification, client });
+      { certification, client, clients: [...clients] });
     for (const method of NATIVE_METHODS) {
       if (typeof manifest[method] !== "function") {
         usage(`a native delivery contract requires ${method}()`, { id: manifest.id, method });

package/node_modules/@agents-can-communicate/adapter-sdk/src/certification.mjs

@@ -178,12 +178,21 @@ function falseCapabilities() {
  * first capture, whose version is returned) or `recorded-failure` (a capture at
  * the returned version recorded the loss).
  */
-export function capabilityEvidence(adapter, { clientVersion, platform } = {}, capability) {
+export function capabilityEvidence(adapter, { clientVersion, platform, clientName } = {},
+  capability) {
   const [group, name] = capability.split(".");
   if (adapter.capabilities?.[group]?.[name] !== true) {
     return { granted: false, reason: "undeclared", version: null };
   }
-  const client = adapter.client?.certificationName ?? adapter.client?.command;
+  // `clientName` names the product the session runs in when it is one of the
+  // adapter's variants. Another product's evidence never stands in for it: its
+  // versions count on a different line. A name the adapter does not declare
+  // has no evidence at all.
+  const primary = adapter.client?.certificationName ?? adapter.client?.command;
+  const declared = [primary, ...(adapter.client?.variants ?? [])
+    .map(variant => variant?.certificationName)];
+  const client = typeof clientName === "string" ? clientName : primary;
+  if (!declared.includes(client)) return { granted: false, reason: "unobserved", version: null };
   const named = (adapter.certification?.evidence ?? [])
     .filter(item => item.client === client && item.capability === capability);
   if (named.length === 0) return { granted: false, reason: "unobserved", version: null };

package/node_modules/@agents-can-communicate/adapter-sdk/src/executables.mjs

@@ -0,0 +1,149 @@
+// Finding and starting a client binary the way the platform does. POSIX joins
+// the bare name onto each PATH entry; Windows adds an extension from PATHEXT and
+// can start a .cmd or .bat only through cmd.exe.
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access, readFile as readText } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
+/** `override` laid over `base`. Windows variable names ignore case, so there an
+ * override replaces the base's variable however either spells it. */
+export function mergeEnv(base, override, platform = process.platform) {
+  if (platform !== "win32") return { ...base, ...override };
+  const replaced = new Set(Object.keys(override ?? {}).map(name => name.toUpperCase()));
+  const kept = Object.entries(base ?? {}).filter(([name]) => !replaced.has(name.toUpperCase()));
+  return { ...Object.fromEntries(kept), ...override };
+}
+
+/** An environment's search path. A copy of Windows' process.env keeps the
+ * variable's own spelling, usually `Path`, and a copy is case-sensitive. */
+export const pathOf = env => Object.entries(env ?? {})
+  .find(([name]) => name.toUpperCase() === "PATH")?.[1] ?? "";
+
+/**
+ * The file a bare command runs, found on PATH as the platform finds it.
+ * POSIX: the first executable `<dir>/<command>`. Windows: `<dir>/<command><ext>`
+ * for each PATHEXT extension in order, a real `.exe` before a `.cmd` shim in
+ * the same directory, because Node can run an `.exe` directly.
+ */
+export async function resolveExecutable(command, { pathEnv = pathOf(process.env),
+  pathExt = process.env.PATHEXT ?? DEFAULT_PATHEXT, platform = process.platform,
+  exclude = [], exists = defaultExists } = {}) {
+  const flavour = platform === "win32" ? path.win32 : path.posix;
+  const delimiter = platform === "win32" ? ";" : ":";
+  // Windows paths compare without case; POSIX ones do not.
+  const key = directory => (platform === "win32" ? flavour.resolve(directory).toLowerCase()
+    : flavour.resolve(directory));
+  const excluded = exclude.filter(Boolean).map(key);
+  const extensions = platform === "win32" && flavour.extname(command) === ""
+    ? orderedExtensions(pathExt) : [""];
+  // A path is used as it is, not looked up: the caller already knows the file.
+  if (flavour.isAbsolute(command)) {
+    for (const extension of extensions) {
+      if (await exists(`${command}${extension}`, platform)) return `${command}${extension}`;
+    }
+    return null;
+  }
+  for (const directory of String(pathEnv).split(delimiter).filter(Boolean)) {
+    if (excluded.includes(key(directory))) continue;
+    for (const extension of extensions) {
+      const candidate = flavour.join(directory, `${command}${extension}`);
+      if (await exists(candidate, platform)) return candidate;
+    }
+  }
+  return null;
+}
+
+function orderedExtensions(pathExt) {
+  const listed = String(pathExt).split(";").map(item => item.trim().toLowerCase()).filter(Boolean);
+  const runnable = listed.filter(item => [".exe", ".com", ".cmd", ".bat"].includes(item));
+  return [...new Set([".exe", ...runnable])];
+}
+
+async function defaultExists(file, platform) {
+  try {
+    await access(file, platform === "win32" ? constants.F_OK : constants.X_OK);
+    return true;
+  } catch { return false; }
+}
+
+// cmd.exe expands and splits these even inside quotes; a fixed argument that
+// carries one is refused rather than escaped.
+const CMD_UNSAFE = /["%^&|<>\r\n!]/;
+
+/**
+ * Run a resolved executable with fixed arguments. Windows cannot start a `.cmd`
+ * or `.bat` without cmd.exe (Node refuses with EINVAL since CVE-2024-27980), so
+ * those go through `cmd.exe /d /s /c` with a command line ACC builds itself.
+ */
+// Not async: the promise execFile returns carries `.child`, and a caller that
+// must close the child's stdin needs it.
+export function runExecutable(file, args, options = {},
+  { platform = process.platform, run = execFileAsync, env = process.env,
+    killTree = killProcessTree } = {}) {
+  if (platform !== "win32" || !/\.(cmd|bat)$/i.test(file)) {
+    return run(file, args, { windowsHide: true, ...options });
+  }
+  for (const word of [file, ...args]) {
+    if (CMD_UNSAFE.test(word)) {
+      return Promise.reject(Object.assign(new Error("argument unsafe for cmd.exe"), { code: "EINVAL" }));
+    }
+  }
+  const line = [file, ...args].map(word => `"${word}"`).join(" ");
+  const comspec = env.ComSpec ?? env.COMSPEC ?? "cmd.exe";
+  const { timeout, ...rest } = options;
+  const outcome = run(comspec, ["/d", "/s", "/c", `"${line}"`],
+    { windowsHide: true, windowsVerbatimArguments: true, ...rest });
+  if (!(timeout > 0)) return outcome;
+  // cmd.exe starts the batch file's program as a child of its own, and killing
+  // cmd.exe leaves that program running with this process's pipes open - which
+  // is what execFile waits on after its own timeout. So the timeout is kept
+  // here: the whole tree goes, and this side of the pipes is closed.
+  const { child } = outcome;
+  let timer;
+  const expired = new Promise((resolve, reject) => {
+    timer = setTimeout(() => {
+      // Only a batch still running: once cmd.exe has exited its pid may belong
+      // to another process, and /T would end that one and its tree.
+      if (child?.exitCode === null && child?.signalCode === null) killTree(child.pid);
+      child?.stdout?.destroy();
+      child?.stderr?.destroy();
+      reject(Object.assign(new Error(`${file} timed out after ${timeout}ms`),
+        { code: "ETIMEDOUT", killed: true }));
+    }, timeout);
+  });
+  // Once the timeout has answered, the batch's own failure is expected.
+  outcome.catch(() => {});
+  const settled = Promise.race([outcome, expired]).finally(() => clearTimeout(timer));
+  return Object.assign(settled, { child });
+}
+
+// taskkill /T ends a process and everything it started, which is the only way
+// Windows has to reach a grandchild. Best effort: the tree may already be gone.
+function killProcessTree(pid, env = process.env) {
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  const root = env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows";
+  execFile(path.win32.join(root, "System32", "taskkill.exe"), ["/pid", String(pid), "/T", "/F"],
+    { windowsHide: true }, () => {});
+}
+
+// The file an npm .cmd shim runs: `"%dp0%\<path inside the prefix>"`.
+const SHIM_TARGET = /"%dp0%\\([^"%]+)"/gi;
+
+/**
+ * The file an npm .cmd shim runs - a native binary or a package script - or
+ * null when the file is no such shim. A probe reads that file; the .cmd says
+ * nothing about the client behind it.
+ */
+export async function npmShimTarget(file, { readFile = readText } = {}) {
+  try {
+    const targets = [...String(await readFile(file, "utf8")).matchAll(SHIM_TARGET)];
+    return targets.length === 1 ? path.win32.join(path.win32.dirname(file), targets[0][1]) : null;
+  } catch {
+    return null;
+  }
+}

package/node_modules/@agents-can-communicate/adapter-sdk/src/hook-shim.mjs

@@ -81,8 +81,9 @@ export async function assertRunner(runner) {
 const PLACEHOLDER = "{{ACC}}";
 
 // Shell metacharacters in a path are the caller's problem to survive, not the
-// shell's to interpret.
-const quote = value => `"${String(value).replace(/(["\\$`])/g, "\\$1")}"`;
+// shell's to interpret. A hook command in the POSIX form quotes its shim the
+// same way, since each client runs it through /bin/sh.
+export const shellQuote = value => `"${String(value).replace(/(["\\$`])/g, "\\$1")}"`;
 
 /**
  * Whether a path is one shell word exactly as written: absolute, and made only
@@ -93,6 +94,43 @@ const quote = value => `"${String(value).replace(/(["\\$`])/g, "\\$1")}"`;
 export const isShellWord = value => typeof value === "string"
   && /^\/[A-Za-z0-9._/-]*$/.test(value);
 
+// Windows runs this where POSIX runs a shell script: no Windows client can be
+// relied on to have `sh`. Same order: the pinned target, loaded into this
+// process when the node running the shim is new enough (a second node start
+// costs more on Windows than the rest of a hook), else started with the pinned
+// node; then a message, and the exit code the caller chose.
+const json = value => JSON.stringify(String(value));
+function nodeShim({ node, target, lead, dataHome, gone, goneExit }) {
+  return [
+    "#!/usr/bin/env node",
+    "// Generated by ACC at install time. The paths are pinned for the reason the",
+    "// POSIX shell shim pins them: a hook's environment may carry no PATH, and a",
+    "// node version manager moves both the interpreter and the global packages.",
+    "import { spawnSync } from \"node:child_process\";",
+    "import { existsSync } from \"node:fs\";",
+    "import { pathToFileURL } from \"node:url\";",
+    "",
+    `const ACC_NODE = ${json(node)};`,
+    `const ACC_TARGET = ${json(target)};`,
+    ...(dataHome === undefined ? [] : [`process.env.ACC_DATA_HOME = ${json(dataHome)};`]),
+    `const args = [...${JSON.stringify(lead)}, ...process.argv.slice(2)];`,
+    "if (existsSync(ACC_TARGET) && Number(process.versions.node.split(\".\")[0]) >= 24) {",
+    "  process.argv = [process.execPath, ACC_TARGET, ...args];",
+    "  await import(pathToFileURL(ACC_TARGET).href);",
+    "} else if (existsSync(ACC_NODE) && existsSync(ACC_TARGET)) {",
+    "  const child = spawnSync(ACC_NODE, [ACC_TARGET, ...args], { stdio: \"inherit\", windowsHide: true });",
+    "  process.exitCode = child.status ?? 1;",
+    "} else {",
+    `  process.stderr.write(\`${gone} (node: \${ACC_NODE}).\\n\`);`,
+    "  process.stderr.write(\"acc: run 'acc install' to wire this client to the acc you have now.\\n\");",
+    `  process.exitCode = ${goneExit};`,
+    "}",
+    "",
+  ].join("\n");
+}
+
+const nodeShimName = name => name.replace(/\.sh$/, ".mjs");
+
 /**
  * Write the small shim a client's hook command points at.
  *
@@ -103,8 +141,15 @@ export const isShellWord = value => typeof value === "string"
  * install time.
  */
 export async function writeHookShim({ dir, adapterId, runner = defaultRunner(),
-  node = process.execPath, name = "acc-hook.sh", dataHome }) {
+  node = process.execPath, name = "acc-hook.sh", dataHome, platform = process.platform }) {
   await assertRunner(runner);
+  if (platform === "win32") {
+    const target = path.join(dir, nodeShimName(name));
+    await mkdir(dir, { recursive: true });
+    await writeFile(target, nodeShim({ node, target: runner, lead: [adapterId], dataHome,
+      gone: "acc: the hook runner installed here is gone", goneExit: 0 }));
+    return target;
+  }
   const target = path.join(dir, name);
   await mkdir(dir, { recursive: true });
   await writeFile(target, [
@@ -118,9 +163,9 @@ export async function writeHookShim({ dir, adapterId, runner = defaultRunner(),
     "# packages live in, and a shim naming the old ones failed on every event",
     "# with nothing to read but exit 126 - no presence, no claims, no messages,",
     "# and nothing anywhere saying why.",
-    `ACC_NODE=${quote(node)}`,
-    `ACC_RUNNER=${quote(runner)}`,
-    ...(dataHome === undefined ? [] : [`export ACC_DATA_HOME=${quote(dataHome)}`]),
+    `ACC_NODE=${shellQuote(node)}`,
+    `ACC_RUNNER=${shellQuote(runner)}`,
+    ...(dataHome === undefined ? [] : [`export ACC_DATA_HOME=${shellQuote(dataHome)}`]),
     'if [ -x "$ACC_NODE" ] && [ -f "$ACC_RUNNER" ]; then',
     `  exec "$ACC_NODE" "$ACC_RUNNER" ${adapterId} "$@"`,
     "fi",
@@ -166,7 +211,14 @@ export async function writeHookShim({ dir, adapterId, runner = defaultRunner(),
  * an agent told nothing went wrong improvises records by hand.
  */
 export async function writeCliShim({ dir, cli = defaultCli(), node = process.execPath,
-  name = "acc-cli.sh", dataHome }) {
+  name = "acc-cli.sh", dataHome, platform = process.platform }) {
+  if (platform === "win32") {
+    const target = path.join(dir, nodeShimName(name));
+    await mkdir(dir, { recursive: true });
+    await writeFile(target, nodeShim({ node, target: cli, lead: [], dataHome,
+      gone: "acc: the CLI installed here is gone", goneExit: 1 }));
+    return target;
+  }
   const target = path.join(dir, name);
   await mkdir(dir, { recursive: true });
   await writeFile(target, [
@@ -175,9 +227,9 @@ export async function writeCliShim({ dir, cli = defaultCli(), node = process.exe
     "# hook shim pins them: a node version manager moves both the interpreter and",
     "# the directory global packages live in, so the pinned pair is tried first",
     "# and then asked for.",
-    `ACC_NODE=${quote(node)}`,
-    `ACC_CLI=${quote(cli)}`,
-    ...(dataHome === undefined ? [] : [`export ACC_DATA_HOME=${quote(dataHome)}`]),
+    `ACC_NODE=${shellQuote(node)}`,
+    `ACC_CLI=${shellQuote(cli)}`,
+    ...(dataHome === undefined ? [] : [`export ACC_DATA_HOME=${shellQuote(dataHome)}`]),
     'if [ -x "$ACC_NODE" ] && [ -f "$ACC_CLI" ]; then',
     '  exec "$ACC_NODE" "$ACC_CLI" "$@"',
     "fi",
@@ -196,6 +248,17 @@ export async function writeCliShim({ dir, cli = defaultCli(), node = process.exe
   return target;
 }
 
+/**
+ * A Node shim at `file` that runs `target` with the pinned node, for an entry
+ * point a Windows shell starts as `node "<file>"`. `gone` is what it prints when
+ * neither is there any more, and `goneExit` the exit code it leaves.
+ */
+export async function writeNodeShim({ file, target, node = process.execPath, gone, goneExit = 0 }) {
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, nodeShim({ node, target, lead: [], gone, goneExit }));
+  return file;
+}
+
 /**
  * Remove a directory this adapter installed, unless it has been kept back.
  *
@@ -246,12 +309,16 @@ export const defaultCli = () => ownBinary("acc.mjs");
  * Antigravity CLI 1.2.12 never matched a command whose program word was quoted,
  * whatever rule was loaded (issue #214). A path that needs quotes keeps them.
  */
-export async function bakeSkillCommand({ root, cliShim, bareWhenSafe = false }) {
+export async function bakeSkillCommand({ root, cliShim, bareWhenSafe = false,
+  platform = process.platform }) {
   if (typeof cliShim !== "string" || cliShim === "") {
     throw new AccError(EXIT.DATA, "refusing to bake an empty skill command", { cliShim });
   }
   // A managed data home is "Application Support"; an unquoted path splits.
-  const command = bareWhenSafe && isShellWord(cliShim) ? cliShim : quote(cliShim);
+  // Windows names node and the Node shim: `node "C:/…/acc-cli.mjs"` runs the same
+  // in PowerShell, Git Bash and cmd, whichever the client gives its model.
+  const command = platform === "win32" ? `node "${cliShim.replaceAll("\\", "/")}"`
+    : bareWhenSafe && isShellWord(cliShim) ? cliShim : shellQuote(cliShim);
   const baked = [];
   const walk = async directory => {
     for (const entry of await readdir(directory, { withFileTypes: true })) {

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

@@ -5,12 +5,13 @@ export { capabilityEvidence, compareVersionOrder, effectiveCapabilities, validat
   versionOrder }
   from "./certification.mjs";
 export { NATIVE_ACTIVATION_KINDS, NATIVE_BINDING_MODES, NATIVE_REASON_CODES,
-  compareStableVersions, evaluateNativeEligibility, evaluateVersionContract, parseStableVersion,
+  compareStableVersions, evaluateNativeEligibility, evaluateVersionContract, isLaunchOption,
+  parseStableVersion,
   validateNativeActivationPlan, validateNativeDeliveryContract, validateNativeHandshake }
   from "./native-delivery.mjs";
 export { EVENT_KINDS, NORMALIZED_EVENT_KEYS, normalizedEvent } from "./events.mjs";
 export { assertRunner, bakeSkillCommand, defaultAntigravityRelay, defaultCli, isShellWord,
-  defaultRunner, removeInstalledTree, runnerExists, writeCliShim, writeHookShim }
+  defaultRunner, removeInstalledTree, runnerExists, shellQuote, writeCliShim, writeHookShim, writeNodeShim }
   from "./hook-shim.mjs";
 export { BEGIN, END, removeTomlBlock, renderBlock, stripBlock, tomlString, writeTomlBlock }
   from "./toml-block.mjs";
@@ -28,3 +29,11 @@ export { clearSessionBinding, listSessionBindings, loadSessionBinding,
 
 export { clearNativeAttempt, loadNativeAttempt, storeNativeAttempt } from "./native-attempt.mjs";
 export { channelSocketDirectory } from "./channel-directory.mjs";
+export { readProcessArgs, readProcessTable, readWindowsProcess, splitWindowsCommandLine }
+  from "./process-table.mjs";
+export { npmShimTarget, resolveExecutable, runExecutable } from "./executables.mjs";
+export { pathOf } from "./executables.mjs";
+export { windowsHookCommand } from "./windows-command.mjs";
+export { shortPath } from "./windows-command.mjs";
+export { mergeEnv } from "./executables.mjs";
+export { closedTo, isWindowsPlatform, openRegularNoFollow } from "./private-files.mjs";

package/node_modules/@agents-can-communicate/adapter-sdk/src/native-attempt.mjs

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { Worker } from "node:worker_threads";
 
-import { NATIVE_REASON_CODES, TIMESTAMP } from "./native-vocabulary.mjs";
+import { NATIVE_REASON_CODES, TIMESTAMP, isLaunchOption } from "./native-vocabulary.mjs";
 
 // Optional diagnostic metadata beside the hook-owner file, never an event
 // history or injected context. Copy only closed values: vendor errors, prompts,
@@ -18,9 +18,13 @@ export function nativeAttemptFrom(value) {
     || !["bootstrap-environment", "installation-record"].includes(value.policySource)
     || !["enabled", "off", "missing", "invalid", "unavailable"].includes(value.policyStatus)
     || !["identified", "unknown"].includes(value.clientProcess)) return null;
+  // The option a refusal named is optional and closed to a bare option token;
+  // anything else is dropped and the attempt itself kept.
   return { at: value.at, event: value.event, state: value.state, reasonCode: value.reasonCode,
     policy: value.policy, policySource: value.policySource, policyStatus: value.policyStatus,
-    clientProcess: value.clientProcess };
+    clientProcess: value.clientProcess,
+    ...(value.state !== "active" && isLaunchOption(value.launchOption)
+      ? { launchOption: value.launchOption } : {}) };
 }
 
 const keyFor = harnessSessionId => createHash("sha256").update(String(harnessSessionId))

package/node_modules/@agents-can-communicate/adapter-sdk/src/native-delivery.mjs

@@ -1,7 +1,7 @@
-import { CONTRACT_ID, FINGERPRINT, HANDSHAKE_KEYS, KNOWN_BAD_REASON, NATIVE_BINDING_MODES,
-  PLANNABLE_ACTIVATION_KINDS, PROBE_KEYS, TIMESTAMP, assertModes, assertReasonCode, closed,
-  compareStableVersions, deepFreeze, isPlainObject, isText, parseStableVersion, usage }
-  from "./native-vocabulary.mjs";
+import { CONTRACT_ID, FINGERPRINT, HANDSHAKE_KEYS, HANDSHAKE_OPTIONAL_KEYS, KNOWN_BAD_REASON,
+  NATIVE_BINDING_MODES, PLANNABLE_ACTIVATION_KINDS, PROBE_KEYS, TIMESTAMP, assertModes,
+  assertReasonCode, closed, compareStableVersions, deepFreeze, isLaunchOption, isPlainObject, isText,
+  parseStableVersion, usage } from "./native-vocabulary.mjs";
 import { compareVersionOrder, versionOrder } from "./certification.mjs";
 
 // The native-delivery compatibility contract: a minimum that is a real passing
@@ -17,12 +17,13 @@ import { compareVersionOrder, versionOrder } from "./certification.mjs";
 // live delivery alone.
 
 export { NATIVE_ACTIVATION_KINDS, NATIVE_BINDING_MODES, NATIVE_REASON_CODES,
-  PLANNABLE_ACTIVATION_KINDS, compareStableVersions, parseStableVersion } from "./native-vocabulary.mjs";
+  PLANNABLE_ACTIVATION_KINDS, compareStableVersions, isLaunchOption, parseStableVersion }
+  from "./native-vocabulary.mjs";
 export { validateNativeActivationPlan } from "./native-activation.mjs";
 
 const orderedModes = modes => NATIVE_BINDING_MODES.filter(mode => modes.includes(mode));
 
-export function validateNativeDeliveryContract(value, { certification, client }) {
+export function validateNativeDeliveryContract(value, { certification, client, clients = [client] }) {
   // Consent to live delivery is what `acc install` recorded. Up to 0.7.x a
   // Claude shell shim could export it instead ("bootstrap-environment"); the
   // shim is gone, and the installation record is the one source left.
@@ -64,11 +65,19 @@ export function validateNativeDeliveryContract(value, { certification, client })
         + "is recorded by its evidence, and the anchor names the version alone "
         + "(docs/design/2026-09-26-native-delivery-across-platforms.md)");
     }
-    closed(anchor, ["version", "protocolContract"], "nativeDelivery anchor");
+    closed(anchor, ["version", "protocolContract"], "nativeDelivery anchor", ["client"]);
     if (parseStableVersion(anchor.version) === null) {
       usage(`nativeDelivery anchor ${index} version must be a stable version`);
     }
-    if (compareStableVersions(anchor.version, minimum) < 0) {
+    // An anchor may belong to another product the adapter serves (see
+    // client.variants). Its versions count on that product's own line, so the
+    // primary minimum says nothing about them.
+    const owner = Object.hasOwn(anchor, "client") ? anchor.client : client;
+    if (!clients.includes(owner)) {
+      usage(`nativeDelivery anchor ${anchor.version} names client ${owner}, which the adapter `
+        + "does not declare", { anchor });
+    }
+    if (owner === client && compareStableVersions(anchor.version, minimum) < 0) {
       usage(`nativeDelivery anchor ${index} version ${anchor.version} is below the minimum ${minimum}: `
         + "the minimum must be the first passing capture");
     }
@@ -78,7 +87,7 @@ export function validateNativeDeliveryContract(value, { certification, client })
     // Where the capture was taken is provenance the evidence row keeps; the
     // anchor is proven by a passing capture of this version on any platform.
     const proven = (certification?.evidence ?? []).some(item => item.result === "pass"
-      && item.capability === "delivery.livePush" && item.client === client
+      && item.capability === "delivery.livePush" && item.client === owner
       && item.version === anchor.version);
     if (!proven) {
       usage(`nativeDelivery anchor ${anchor.version} has no passing delivery.livePush certification`,
@@ -86,7 +95,18 @@ export function validateNativeDeliveryContract(value, { certification, client })
     }
     return { ...anchor };
   });
-  if (!anchors.some(anchor => compareStableVersions(anchor.version, minimum) === 0)) {
+  const owners = new Map();
+  for (const anchor of anchors) {
+    const owner = anchor.client ?? client;
+    const previous = owners.get(anchor.protocolContract);
+    if (previous !== undefined && previous !== owner) {
+      usage(`nativeDelivery protocol ${anchor.protocolContract} is anchored for both ${previous} `
+        + `and ${owner}`, { protocolContract: anchor.protocolContract });
+    }
+    owners.set(anchor.protocolContract, owner);
+  }
+  if (!anchors.some(anchor => (anchor.client ?? client) === client
+    && compareStableVersions(anchor.version, minimum) === 0)) {
     usage(`nativeDelivery minimum ${minimum} must be the first passing capture: no anchor matches it`);
   }
   if (!Array.isArray(value.knownBad)) usage("nativeDelivery.knownBad must be an array");
@@ -143,7 +163,7 @@ function knownBadHit(contract, order) {
 // validateNativeHandshake below, and the delivery router's own offer check,
 // which uses this function alone because a response already carries no probe
 // or handshake shape to check further).
-export function evaluateVersionContract(adapter, { clientVersion } = {}) {
+export function evaluateVersionContract(adapter, { clientVersion, protocolContract } = {}) {
   const contract = adapter?.nativeDelivery;
   const unsupported = { reasonCode: "native_delivery_unsupported", minimumVersion: null,
     protocolContract: null };
@@ -160,9 +180,18 @@ export function evaluateVersionContract(adapter, { clientVersion } = {}) {
   // already answers malformed input this way.
   const minimumVersion = isText(contract.minimum) ? contract.minimum : null;
   if (minimumVersion === null) return unsupported;
-  const anchor = (Array.isArray(contract.anchors) ? contract.anchors : [])
-    .find(item => item?.version === minimumVersion);
+  const anchors = Array.isArray(contract.anchors) ? contract.anchors : [];
+  const primary = adapter.client?.certificationName ?? adapter.client?.command;
+  const anchor = anchors.find(item => item?.version === minimumVersion
+    && (!isText(item?.client) || item.client === primary));
   if (anchor === undefined) return unsupported;
+  // Another product's protocol has its own floor - the first capture that
+  // anchored it - and the denylist, which names the primary product's
+  // versions, does not reach it. Asked about no protocol, or the primary one,
+  // the rule is the primary minimum as it always was.
+  if (isText(protocolContract) && protocolContract !== anchor.protocolContract) {
+    return protocolFloor(anchors, protocolContract, clientVersion);
+  }
   const facts = { minimumVersion, protocolContract: anchor.protocolContract };
   const order = versionOrder(clientVersion);
   if (order === null) return { ...facts, reasonCode: "version_unavailable" };
@@ -173,6 +202,31 @@ export function evaluateVersionContract(adapter, { clientVersion } = {}) {
   return { ...facts, reasonCode: null };
 }
 
+function protocolFloor(anchors, protocolContract, clientVersion) {
+  const own = anchors.filter(item => item?.protocolContract === protocolContract
+    && isText(item?.version));
+  if (own.length === 0) {
+    return { reasonCode: "protocol_mismatch", minimumVersion: null, protocolContract };
+  }
+  const minimumVersion = own.map(item => item.version)
+    .reduce((first, version) => (compareStableVersions(version, first) < 0 ? version : first));
+  const facts = { minimumVersion, protocolContract };
+  const order = versionOrder(clientVersion);
+  if (order === null) return { ...facts, reasonCode: "version_unavailable" };
+  if (compareVersionOrder(order, versionOrder(minimumVersion)) < 0) {
+    return { ...facts, reasonCode: "below_minimum_version" };
+  }
+  return { ...facts, reasonCode: null };
+}
+
+// The protocol a probe or handshake reports, when it is one an anchor names:
+// that protocol's own floor judges it. Any other value is left to the primary
+// rule, so it still ends as the protocol_mismatch it always was.
+function reportedProtocol(adapter, reported) {
+  return isText(reported) && (adapter?.nativeDelivery?.anchors ?? [])
+    .some(item => item?.protocolContract === reported) ? reported : undefined;
+}
+
 function validateNativeProbe(probe) {
   closed(probe, PROBE_KEYS, "native probe");
   if (typeof probe.supported !== "boolean") usage("native probe supported must be a boolean");
@@ -198,7 +252,8 @@ export function evaluateNativeEligibility(adapter, { clientVersion, probe }) {
   // Only the version is read here; the shape is validated where it always was,
   // so a malformed probe still returns a closed result rather than throwing.
   const serving = isText(probe?.clientVersion) ? probe.clientVersion : clientVersion;
-  const rule = evaluateVersionContract(adapter, { clientVersion: serving });
+  const rule = evaluateVersionContract(adapter, { clientVersion: serving,
+    protocolContract: reportedProtocol(adapter, probe?.protocolContract) });
   const base = { eligible: false, reasonCode: null, minimumVersion: rule.minimumVersion,
     protocolContract: rule.protocolContract, modes: [] };
   const closedResult = reasonCode => deepFreeze({ ...base, reasonCode });
@@ -214,7 +269,7 @@ export function evaluateNativeEligibility(adapter, { clientVersion, probe }) {
 }
 
 function validateNativeHandshakeShape(handshake) {
-  closed(handshake, HANDSHAKE_KEYS, "native handshake");
+  closed(handshake, HANDSHAKE_KEYS, "native handshake", HANDSHAKE_OPTIONAL_KEYS);
   if (typeof handshake.supported !== "boolean") usage("native handshake supported must be a boolean");
   if (handshake.clientVersion !== null && !isText(handshake.clientVersion)) {
     usage("native handshake clientVersion must be a string or null");
@@ -236,6 +291,12 @@ function validateNativeHandshakeShape(handshake) {
   } else if (handshake.opaqueEndpointRef !== null || handshake.leaseUntil !== null) {
     usage("an unsupported native handshake carries no endpoint or lease");
   }
+  if (Object.hasOwn(handshake, "launchOption")) {
+    if (handshake.supported) usage("only a refused native handshake names a launchOption");
+    if (!isLaunchOption(handshake.launchOption)) {
+      usage("native handshake launchOption must be a bare command-line option");
+    }
+  }
   return handshake;
 }
 
@@ -256,7 +317,8 @@ export function validateNativeHandshake(adapter, { clientVersion, handshake }) {
   // the version is read here; the shape is validated where it always was, so
   // a malformed handshake still returns a closed result rather than throwing.
   const serving = isText(handshake?.clientVersion) ? handshake.clientVersion : clientVersion;
-  const rule = evaluateVersionContract(adapter, { clientVersion: serving });
+  const rule = evaluateVersionContract(adapter, { clientVersion: serving,
+    protocolContract: reportedProtocol(adapter, handshake?.protocolContract) });
   const base = { ok: false, reasonCode: null, clientVersion: null,
     protocolContract: rule.protocolContract, modes: [],
     opaqueEndpointRef: null, leaseUntil: null };
@@ -264,7 +326,10 @@ export function validateNativeHandshake(adapter, { clientVersion, handshake }) {
   if (rule.reasonCode !== null) return closedResult(rule.reasonCode);
   if (handshake === null || handshake === undefined) return closedResult("handshake_failed");
   const facts = validateNativeHandshakeShape(handshake);
-  if (facts.supported !== true) return closedResult(facts.reasonCode ?? "handshake_failed");
+  if (facts.supported !== true) {
+    return deepFreeze({ ...base, reasonCode: facts.reasonCode ?? "handshake_failed",
+      ...(Object.hasOwn(facts, "launchOption") ? { launchOption: facts.launchOption } : {}) });
+  }
   if (facts.protocolContract !== rule.protocolContract) return closedResult("protocol_mismatch");
   const modes = orderedModes(facts.modes);
   if (!modes.includes("livePush")) return closedResult("handshake_failed");