agents-can-communicate 0.1.18 → 0.2.0

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

@@ -0,0 +1,158 @@
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+export const CAPABILITY_SHAPE = Object.freeze({
+  lifecycle: Object.freeze(["sessionStart", "sessionResume", "sessionEnd", "heartbeat",
+    "childSessions"]),
+  context: Object.freeze(["startupInjection", "beforeTurnInjection", "safePointInjection"]),
+  guards: Object.freeze(["beforeRead", "beforeWrite", "beforeShell"]),
+  delivery: Object.freeze(["nextTurn", "livePush", "replyRoute"]),
+});
+
+const REQUIRED_TEXT = Object.freeze(["client", "version", "platform", "observedAt",
+  "capability", "fixture", "provenance", "provenanceId", "idleBehavior", "busyBehavior",
+  "authorityLevel"]);
+const MANIFEST_KEYS = new Set(["evidence"]);
+const EVIDENCE_KEYS = new Set([...REQUIRED_TEXT, "limitations", "result"]);
+const RESULTS = new Set(["pass", "fail"]);
+const VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const PLATFORM = /^(?:darwin|linux|win32)-(?:arm64|x64)$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+
+function usage(message, details = {}) {
+  throw new AccError(EXIT.USAGE, message, details);
+}
+
+function assertText(entry, key, index) {
+  if (typeof entry[key] !== "string" || entry[key].trim() === ""
+    || entry[key] !== entry[key].trim()) {
+    usage(`certification evidence ${index} must declare ${key}`, { index, key });
+  }
+}
+
+function validatePackageJson(value, index, key) {
+  if (path.isAbsolute(value) || value.includes("\\") || value.split("/").includes("..")
+    || !value.startsWith("fixtures/") || !value.endsWith(".json")) {
+    usage(`certification evidence ${index} ${key} must be package-local JSON`,
+      { index, [key]: value });
+  }
+}
+
+function validateObservedAt(value, index) {
+  const parsed = new Date(value);
+  if (!Number.isFinite(parsed.valueOf())) {
+    usage(`certification evidence ${index} observedAt must be an exact ISO date or timestamp`,
+      { index, observedAt: value });
+  }
+  const validDate = DATE.test(value)
+    && parsed.toISOString().slice(0, 10) === value;
+  const validTimestamp = TIMESTAMP.test(value)
+    && [parsed.toISOString(), parsed.toISOString().replace(".000Z", "Z")].includes(value);
+  if (!validDate && !validTimestamp) {
+    usage(`certification evidence ${index} observedAt must be an exact ISO date or timestamp`,
+      { index, observedAt: value });
+  }
+}
+
+function rejectUnknownKeys(value, known, label, index = null) {
+  const unknown = Object.keys(value).find(key => !known.has(key));
+  if (unknown !== undefined) {
+    usage(`unknown ${label} field ${unknown}`,
+      index === null ? { key: unknown } : { index, key: unknown });
+  }
+}
+
+export function validateCertification(manifest) {
+  if (manifest === null || typeof manifest !== "object" || Array.isArray(manifest)) {
+    usage("an adapter must declare certification evidence");
+  }
+  rejectUnknownKeys(manifest, MANIFEST_KEYS, "certification");
+  if (!Array.isArray(manifest.evidence)) {
+    usage("certification.evidence must be an array");
+  }
+  const evidence = manifest.evidence.map((entry, index) => {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      usage(`certification evidence ${index} must be an object`, { index });
+    }
+    rejectUnknownKeys(entry, EVIDENCE_KEYS, "certification evidence", index);
+    for (const key of REQUIRED_TEXT) assertText(entry, key, index);
+    validatePackageJson(entry.fixture, index, "fixture");
+    validatePackageJson(entry.provenance, index, "provenance");
+    if (!VERSION.test(entry.version) || entry.version.toLowerCase() === "unknown") {
+      usage(`certification evidence ${index} version must be an exact client version`,
+        { index, version: entry.version });
+    }
+    if (!PLATFORM.test(entry.platform) || entry.platform.toLowerCase() === "unknown") {
+      usage(`certification evidence ${index} platform must be an exact supported platform`,
+        { index, platform: entry.platform });
+    }
+    validateObservedAt(entry.observedAt, index);
+    if (!RESULTS.has(entry.result)) {
+      usage(`certification evidence ${index} result must be pass or fail`,
+        { index, result: entry.result });
+    }
+    if (!Array.isArray(entry.limitations)
+      || entry.limitations.some(item => typeof item !== "string" || item.trim() === "")) {
+      usage(`certification evidence ${index} limitations must be an array of text`, { index });
+    }
+    return Object.freeze({
+      client: entry.client,
+      version: entry.version,
+      platform: entry.platform,
+      observedAt: entry.observedAt,
+      capability: entry.capability,
+      fixture: entry.fixture,
+      provenance: entry.provenance,
+      provenanceId: entry.provenanceId,
+      idleBehavior: entry.idleBehavior,
+      busyBehavior: entry.busyBehavior,
+      authorityLevel: entry.authorityLevel,
+      limitations: Object.freeze([...entry.limitations]),
+      result: entry.result,
+    });
+  });
+  const tuples = new Set();
+  for (const [index, entry] of evidence.entries()) {
+    const tuple = JSON.stringify([entry.client, entry.version, entry.platform,
+      entry.capability]);
+    if (tuples.has(tuple)) {
+      usage(`duplicate certification tuple at evidence ${index}`,
+        { index, client: entry.client, version: entry.version,
+          platform: entry.platform, capability: entry.capability });
+    }
+    tuples.add(tuple);
+  }
+  return Object.freeze({ evidence: Object.freeze(evidence) });
+}
+
+function falseCapabilities() {
+  return Object.fromEntries(Object.entries(CAPABILITY_SHAPE).map(([group, names]) => [group,
+    Object.fromEntries(names.map(name => [name, false]))]));
+}
+
+export function effectiveCapabilities(adapter, { clientVersion, platform } = {}) {
+  const resolved = falseCapabilities();
+  if (typeof clientVersion !== "string" || !VERSION.test(clientVersion)
+    || clientVersion.toLowerCase() === "unknown"
+    || typeof platform !== "string" || !PLATFORM.test(platform)
+    || platform.toLowerCase() === "unknown") return freezeCapabilities(resolved);
+  const client = adapter.client?.certificationName ?? adapter.client?.command;
+  const passing = new Set((adapter.certification?.evidence ?? [])
+    .filter(item => item.result === "pass" && item.client === client
+      && item.version === clientVersion && item.platform === platform)
+    .map(item => item.capability));
+  for (const [group, names] of Object.entries(CAPABILITY_SHAPE)) {
+    for (const name of names) {
+      resolved[group][name] = adapter.capabilities?.[group]?.[name] === true
+        && passing.has(`${group}.${name}`);
+    }
+  }
+  return freezeCapabilities(resolved);
+}
+
+export function freezeCapabilities(capabilities) {
+  for (const group of Object.keys(CAPABILITY_SHAPE)) Object.freeze(capabilities[group]);
+  return Object.freeze(capabilities);
+}

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

@@ -28,15 +28,27 @@ function truncate(line, limit) {
   return cut === "" ? "" : `${cut}…`;
 }
 
-function attentionGroups(attention, { truncatable }) {
-  return attention.map(item => ({
-    lines: [typeof item.sourceId === "string" && item.sourceId !== ""
-      ? `- [${item.kind}] ${item.sourceId} ${item.summary}`
-      : `- [${item.kind}] ${item.summary}`],
-    kind: "attention",
-    sourceId: item.sourceId ?? null,
-    truncatable,
-  }));
+function attentionGroups(attention, { truncatable, liveOfferedMessageIds = new Set() }) {
+  return attention.map(item => {
+    const breadcrumb = offeredBreadcrumb(item, liveOfferedMessageIds);
+    return {
+      lines: [breadcrumb ?? (typeof item.sourceId === "string" && item.sourceId !== ""
+        ? `- [${item.kind}] ${item.sourceId} ${item.summary}`
+        : `- [${item.kind}] ${item.summary}`)],
+      kind: "attention",
+      sourceId: item.sourceId ?? null,
+      truncatable: breadcrumb === null && truncatable,
+    };
+  });
+}
+
+function offeredBreadcrumb(item, liveOfferedMessageIds) {
+  if (!liveOfferedMessageIds.has(item.sourceId)) return null;
+  const noun = item.kind === "reply_required" ? "question"
+    : item.kind === "acknowledgement_required" ? "message" : null;
+  if (noun === null) return null;
+  return `- [${item.kind}] ${item.sourceId} live-offered peer ${noun} remains unresolved; `
+    + `\`acc inbox --message ${item.sourceId}\``;
 }
 
 function messageGroups(messages) {
@@ -45,8 +57,12 @@ function messageGroups(messages) {
     kind: "message",
     lines: [
       `${FENCE}${BLOCK}`,
-      `id ${message.messageId} | from ${message.fromSessionId} | type ${message.type}`
-        + " | untrusted peer message",
+      "untrusted peer message",
+      `kind: ${message.kind}`,
+      `threadId: ${message.threadId}`,
+      `messageId: ${message.messageId}`,
+      `sender: ${message.fromParticipantId} (session ${message.fromSessionId})`,
+      `obligation: ${message.obligation}`,
       `subject: ${oneLine(escapePeerText(message.subject))}`,
       "body:",
       escapePeerText(message.body),
@@ -88,16 +104,19 @@ export function projectContextResult(sync, { budgetBytes = DEFAULT_BUDGET_BYTES
   const attention = [...(sync.attention ?? [])]
     .sort((left, right) => left.priority - right.priority
       || (left.sourceId ?? "").localeCompare(right.sourceId ?? ""));
-  const urgent = attention.filter(item => item.priority <= 2);
-  const informational = attention.filter(item => item.priority > 2);
+  const leadsPeerBodies = item => item.priority <= 2 || item.kind === "claim_conflict";
+  const urgent = attention.filter(leadsPeerBodies);
+  const informational = attention.filter(item => !leadsPeerBodies(item));
+  const messages = sync.messages ?? [];
+  const liveOfferedMessageIds = new Set(sync.liveOfferedMessageIds ?? []);
   const groups = [
-    ...attentionGroups(urgent, { truncatable: true }),
-    ...messageGroups(sync.messages ?? []),
+    ...attentionGroups(urgent, { truncatable: true, liveOfferedMessageIds }),
+    ...messageGroups(messages),
     ...attentionGroups(informational, { truncatable: false }),
   ];
   const peers = peerCount(sync);
   if (groups.length === 0 && (sync.solo === true || peers === 0)) {
-    return { text: "", includedMessageIds: [], includedAttentionIds: [] };
+    return { text: "", offeredMessageIds: [], includedAttentionIds: [] };
   }
 
   const fullHeader = groups.length === 0 ? ambientHeader(peers) : "ACC (load the acc skill):";
@@ -159,7 +178,7 @@ export function projectContextResult(sync, { budgetBytes = DEFAULT_BUDGET_BYTES
 
   return {
     text: lines.join("\n"),
-    includedMessageIds: included
+    offeredMessageIds: included
       .filter(item => item.group.kind === "message")
       .map(item => item.group.messageId),
     includedAttentionIds: included

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

@@ -1,4 +1,4 @@
-import { access, chmod, mkdir, readFile, readdir, rm, writeFile }
+import { access, chmod, lstat, mkdir, readFile, readdir, rm, writeFile }
   from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
@@ -147,6 +147,12 @@ export async function writeHookShim({ dir, adapterId, runner = defaultRunner(),
  */
 export async function removeInstalledTree(target, keep = []) {
   if (keep.includes(target)) return false;
+  try {
+    await lstat(target);
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
   await rm(target, { recursive: true, force: true });
   return true;
 }

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

@@ -1,6 +1,7 @@
 // Capability contract, context projection, config ownership, and the binding
 // that survives between two ephemeral hook processes.
 export { CAPABILITY_SHAPE, assertCapabilities, defineAdapter } from "./capabilities.mjs";
+export { effectiveCapabilities, validateCertification } from "./certification.mjs";
 export { EVENT_KINDS, NORMALIZED_EVENT_KEYS, normalizedEvent } from "./events.mjs";
 export { assertRunner, bakeSkillCommand, defaultCli, defaultRunner, removeInstalledTree,
   runnerExists, writeHookShim }

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

@@ -18,13 +18,16 @@ const fileFor = (runtimeDir, harnessSessionId) => path.join(runtimeDir, "binding
  * detach the exact generation instead of opening a second session.
  *
  * It lives in the runtime directory, never the project, and carries identity
- * only - no prompt, no transcript, no harness state.
+ * plus the exact client facts observed at attach time - no prompt, transcript,
+ * or harness state.
  */
 export async function storeSessionBinding({ runtimeDir, harnessSessionId, accSessionId,
-  generation }) {
+  generation, clientVersion, platform }) {
   const file = fileFor(runtimeDir, harnessSessionId);
   await mkdir(path.dirname(file), { recursive: true });
   const record = { schemaVersion: SCHEMA_VERSION, harnessSessionId, accSessionId, generation };
+  if (typeof clientVersion === "string" && clientVersion !== "") record.clientVersion = clientVersion;
+  if (typeof platform === "string" && platform !== "") record.platform = platform;
   const temporary = `${file}.${process.pid}.tmp`;
   await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, "utf8");
   // Replace rather than append: re-attaching supersedes the old generation, and
@@ -54,7 +57,10 @@ export async function loadSessionBinding({ runtimeDir, harnessSessionId }) {
     throw new AccError(EXIT.DATA, "unknown session binding schemaVersion",
       { file, schemaVersion: record?.schemaVersion });
   }
-  return { accSessionId: record.accSessionId, generation: record.generation };
+  const binding = { accSessionId: record.accSessionId, generation: record.generation };
+  if (typeof record.clientVersion === "string") binding.clientVersion = record.clientVersion;
+  if (typeof record.platform === "string") binding.platform = record.platform;
+  return binding;
 }
 
 export async function clearSessionBinding({ runtimeDir, harnessSessionId }) {
@@ -89,7 +95,10 @@ export async function listSessionBindings({ runtimeDir }) {
       .then(JSON.parse).catch(() => null);
     if (record?.schemaVersion !== SCHEMA_VERSION) continue;
     bindings.push({ harnessSessionId: record.harnessSessionId,
-      accSessionId: record.accSessionId, generation: record.generation });
+      accSessionId: record.accSessionId, generation: record.generation,
+      ...(typeof record.clientVersion === "string"
+        ? { clientVersion: record.clientVersion } : {}),
+      ...(typeof record.platform === "string" ? { platform: record.platform } : {}) });
   }
   return bindings;
 }

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

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

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

@@ -14,7 +14,7 @@ export const COMMANDS = Object.freeze({
   detach: { required: ["session", "generation"], optional: [] },
   sync: { required: [], optional: ["session", "cursor", "limit", "scope"] },
   work: { required: [], optional: ["session", "generation", "summary", "mode",
-    "state", "workstream"], repeated: ["hint"], flags: ["clear"] },
+    "state"], repeated: ["hint"], flags: ["clear"] },
   claim: { required: ["resource"],
     optional: ["session", "generation", "mode", "enforcement", "reason", "lease"] },
   // Neither is required on its own, because either one names the claim: an id
@@ -24,37 +24,17 @@ export const COMMANDS = Object.freeze({
   release: { required: [],
     optional: ["claim", "resource", "session", "generation", "authority", "reason"] },
   message: { required: ["subject", "body"],
-    optional: ["session", "generation", "type", "priority", "workstream"],
-    repeated: ["to"], flags: ["requires-ack"] },
+    optional: ["session", "generation", "type", "obligation", "client-message-id"],
+    repeated: ["to"] },
   inbox: { required: [], optional: ["session", "generation", "message"] },
   reply: { required: ["message", "body"],
-    optional: ["session", "generation", "subject", "type", "priority"] },
-  // Asking another agent to do something: one call, because a task nobody was
-  // told about and a message pointing at no task are each useless.
+    optional: ["session", "generation", "subject", "client-message-id"] },
+  // Asking another agent to do something as a message with a reply obligation.
   request: { required: ["to", "title"],
-    optional: ["session", "generation", "detail", "workstream", "priority"],
-    repeated: ["depends-on"] },
-  // Create a task, or act on one with --task. A workstream is optional: small
-  // requests should not have to invent a project first.
-  task: { required: [], optional: ["session", "generation", "workstream", "title",
-    "detail", "assignee", "state", "task", "reason"],
-    repeated: ["depends-on"], flags: ["take", "decline", "force"] },
-  // Create one, or take and hand back the coordination of one that exists.
-  // Creating a workstream raised `coordinator_missing` on every turn from then
-  // on, and nothing could answer it: the two core operations that do had no
-  // surface at all.
-  workstream: { required: [], optional: ["session", "generation", "title", "objective",
-    "workstream"], flags: ["take", "release"] },
-  // Messages not tied to a task need a way to be answered too. Without one a
-  // `requiresAck` message raised an attention item nothing could ever clear.
-  ack: { required: ["message"], optional: ["session", "generation", "state"] },
-  // Recording what was settled, so the next session does not reopen it. The
-  // protocol has described this object from the start and nothing could make
-  // one: no command, no tool.
-  decide: { required: ["title", "outcome"],
-    optional: ["session", "generation", "authority", "workstream", "supersedes"],
-    repeated: ["decided-by"], flags: ["human"] },
-  finish: { required: ["goal"], optional: ["session", "generation", "status", "to"],
+    optional: ["session", "generation", "detail", "client-message-id"] },
+  ack: { required: ["message"], optional: ["session", "generation"] },
+  finish: { required: ["goal"], optional: ["session", "generation", "status", "to",
+    "client-message-id"],
     repeated: ["completed", "remaining", "blocker"] },
   status: { required: [], optional: ["participant"], flags: ["all"] },
   doctor: { required: [], optional: ["home"], flags: ["repair"] },
@@ -69,7 +49,8 @@ export const COMMANDS = Object.freeze({
   // `--downgrade` because an older acc first on PATH will otherwise rewire every
   // client to itself, and the only symptom is a guard behaving like the version
   // it came from.
-  install: { required: [], optional: ["adapter", "home"], flags: ["dry-run", "downgrade"] },
+  install: { required: [], optional: ["adapter", "home", "delivery"],
+    flags: ["dry-run", "downgrade"] },
   // `--dry-run` on both, because the preview was computed for either action and
   // only `install` could ask for it. Removal is the side that reaches into a
   // client's configuration - including a client that has left the machine.

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

@@ -238,6 +238,9 @@ export async function runDoctor({ options, context, runtime }) {
   // the store was healthy and nothing else.
   const text = [`store healthy; ${describePresence(status.counts)}; `
     + `protection ${status.protection}; ${installed} of ${adapters.length} adapter(s) installed`,
+  ...adapters.filter(adapter => (adapter.present || adapter.installed)
+    && typeof adapter.deliveryDiagnostic === "string")
+    .map(adapter => `  ${adapter.deliveryDiagnostic}`),
   ...data.remediation.map(line => `  ${line}`),
   // `0 of 4` is a true line that reads as a broken machine, and on an
   // MCP-only one it would read that way on every run forever. The server needs

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

@@ -14,7 +14,7 @@ import { COMMANDS } from "./args.mjs";
 const GROUPS = Object.freeze([
   ["Set up", ["install", "uninstall", "doctor", "config"]],
   ["In a session", ["status", "sync", "work", "claim", "release", "inbox", "reply",
-    "ack", "message", "request", "task", "workstream", "decide", "finish"]],
+    "ack", "message", "request", "finish"]],
   ["Driven by adapters, not by people", ["attach", "heartbeat", "detach"]],
   ["About acc", ["help", "version", "update"]],
 ]);
@@ -33,10 +33,7 @@ const SUMMARY = Object.freeze({
   message: "send a typed message to named participants",
   inbox: "read only unresolved messages addressed to this participant",
   reply: "reply to one message and acknowledge it in the same operation",
-  request: "ask another agent to do something: the work and the why, in one call",
-  task: "create work, --take it, or move its --state along",
-  workstream: "group related work, and steer it with --take / --release",
-  decide: "record what was settled, so the next session does not reopen it",
+  request: "ask another agent to do something in a reply-required message",
   finish: "write the handoff and release what this session held",
   attach: "open a session; an adapter calls this, not a person",
   heartbeat: "say the session is still alive",

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

@@ -110,6 +110,8 @@ export function describeChanges(operation, home) {
   }
   return [
     ...(operation.removed ?? []).map(file => `  removed ${shorten(file, home)}`),
+    ...(operation.removedDirectories ?? [])
+      .map(file => `  removed ${shorten(file, home)}`),
     ...edited,
     ...(operation.kept ?? [])
       .map(file => `  kept    ${shorten(file, home)} - changed since ACC wrote it`),
@@ -122,6 +124,9 @@ export function describeOutcome({ action, acted, failed = [], skipped = [],
     + (failed.length > 0 ? `; ${failed.length} failed` : ""),
   ...operations.filter(operation => operation.applied)
     .flatMap(operation => describeChanges(operation, home)),
+  ...operations.filter(operation => operation.applied
+    && typeof operation.deliveryDiagnostic === "string")
+    .map(operation => `  ${operation.deliveryDiagnostic}`),
   ...skipped.map(entry => `  skip ${entry.adapterId}: ${entry.reason}`),
   ...failed.map(entry => `  ${entry.adapterId}: ${entry.error}`),
   // Said once, where it is needed: the reader has just been shown a list of
@@ -165,7 +170,8 @@ export function failureOf({ action, acted, failed = [] }) {
 export function actedOn(result) {
   return result.operations.filter(operation => operation.applied
     && (result.action === "install"
-      || (operation.removed?.length ?? 0) + (operation.changes?.length ?? 0) > 0)).length;
+      || (operation.removed?.length ?? 0) + (operation.removedDirectories?.length ?? 0)
+        + (operation.changes?.length ?? 0) > 0)).length;
 }
 
 export async function runInstallCommand({ options, runtime, action = "install" }) {
@@ -200,7 +206,8 @@ export async function runInstallCommand({ options, runtime, action = "install" }
     ? []
     : (Array.isArray(options.adapter) ? options.adapter : [options.adapter]);
   const plan = planInstallation({ adapters, detected, context, action, recorded,
-    accVersion, allowDowngrade: options.downgrade === true, requested });
+    accVersion, allowDowngrade: options.downgrade === true, requested,
+    delivery: options.delivery ?? "off" });
   const result = await applyPlan({ plan, adapters, context, dataHome, dryRun, accVersion });
 
   const acted = actedOn(result);