agents-can-communicate 0.10.4 → 0.11.1

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

@@ -121,7 +121,7 @@ async function saveOwnership({ dataHome, record }) {
  */
 export async function recordInstall({ dataHome, adapterId, version, accVersion = null,
   artifacts, createdDirectories = [], deliveryPolicy, deliveryDecision,
-  nativeActivation = null }) {
+  nativeActivation = null, indicator }) {
   const stamped = await Promise.all(artifacts.map(async artifact => ({
     path: artifact.path,
     kind: artifact.kind ?? "file",
@@ -141,6 +141,7 @@ export async function recordInstall({ dataHome, adapterId, version, accVersion =
       { adapterId, version, accVersion, artifacts: stamped,
         ...(directories.length === 0 ? {} : { createdDirectories: directories }),
         ...(deliveryPolicy === undefined ? {} : { deliveryPolicy }),
+        ...(indicator === undefined ? {} : { indicator }),
         ...(retainedDeliveryDecision === undefined ? {} : {
           deliveryDecision: retainedDeliveryDecision,
         }),

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

@@ -14,7 +14,7 @@ import { LIVE_POLICIES, describeActivation, describeDeactivation, planActivation
  */
 export function planInstallation({ adapters, detected, context, action = "install",
   recorded = [], accVersion = null, allowDowngrade = false, requested = [],
-  deliveryByAdapter = {}, deliveryDecisionByAdapter = {}, allowServiceSetup = false }) {
+  deliveryByAdapter = {}, deliveryDecisionByAdapter = {}, allowServiceSetup = false, indicator }) {
   if (!["install", "uninstall"].includes(action)) {
     throw new AccError(EXIT.USAGE, `unknown installation action: ${action}`, { action });
   }
@@ -157,7 +157,13 @@ export function planInstallation({ adapters, detected, context, action = "instal
       : null;
     const deliverySummary = action === "install"
       ? describeInstallDelivery(entry, delivery, effectiveLivePolicy) : null;
-    const installContext = { ...context, requestedLivePolicy: delivery,
+    const indicatorPreference = indicator ?? recordedById.get(entry.adapterId)?.indicator ?? "off";
+    const indicatorDiagnostic = indicatorPreference !== "on" ? null : !adapter.statusIndicator
+      ? `${adapter.displayName} indicator: not supported in this client's native status line`
+      : entry.version == null || isOlder(entry.version, adapter.statusIndicator.minimumVersion)
+        ? `${adapter.displayName} indicator requires client ${adapter.statusIndicator.minimumVersion} or later`
+        : `${adapter.displayName} indicator: enabled; ${adapter.statusIndicator.reload}`;
+    const installContext = { ...context, indicator: indicatorPreference, requestedLivePolicy: delivery,
       livePolicy: configuredLivePolicy, clientVersion: entry.version, platform: entry.platform };
     const nativeServiceSetup = action === "install" && allowServiceSetup && delivery !== "off"
       && deliveryDecision.completeSetup === true ? entry.nativeServiceSetup : undefined;
@@ -192,6 +198,8 @@ export function planInstallation({ adapters, detected, context, action = "instal
       clientPresent: entry.present === true,
       alreadyInstalled: entry.installed === true,
       livePolicy: delivery,
+      indicator: indicatorPreference,
+      ...(indicatorDiagnostic === null ? {} : { indicatorDiagnostic }),
       effectiveLivePolicy,
       ...(action === "install" ? { deliveryDecision } : {}),
       ...(retainedActivation ? { configuredLivePolicy, retainedNativeActivation: retainedActivation } : {}),
@@ -205,6 +213,7 @@ export function planInstallation({ adapters, detected, context, action = "instal
       // Said in the operator's terms, not in paths: which files ACC creates
       // outright and which belong to the user and are only edited.
       summary: [
+        ...(indicatorDiagnostic === null ? [] : [indicatorDiagnostic]),
         ...(entry.present ? [] : [`${adapter.displayName ?? adapter.id} is no longer on `
           + "this machine; removing what ACC recorded writing"]),
         ...(deliverySummary === null ? [] : [deliverySummary]),

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

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

package/node_modules/@agents-can-communicate/mcp-server/src/claim-tools.mjs

@@ -0,0 +1,56 @@
+import { AccError, EXIT, assertMatchableResource, assertPortableId,
+  assertResourceUri, normaliseResource } from "@agents-can-communicate/protocol";
+
+const invalid = message => { throw new AccError(EXIT.USAGE, message); };
+
+function resourceSelector(resource) {
+  assertMatchableResource(resource, invalid);
+  return assertResourceUri(normaliseResource(resource), "resource");
+}
+
+function claimIdSelector(claimId, field) {
+  try { return assertPortableId(claimId, field); }
+  catch (error) {
+    if (!(error instanceof AccError)) throw error;
+    invalid(`${field} must be a portable identifier`);
+  }
+}
+
+// URI normalization and identifier validation must precede resolving a session:
+// an invalid selector must not create presence or a persistent session binding.
+export function validateClaimSelectors(name, args) {
+  if (name !== "acc_claim" && name !== "acc_release") return args;
+  const result = { ...args };
+  if (args.resource !== undefined) result.resource = resourceSelector(args.resource);
+  if (args.resources !== undefined) {
+    result.resources = args.resources.map(resourceSelector);
+    if (new Set(result.resources).size !== result.resources.length) {
+      invalid("arguments.resources contains duplicate selectors after normalization");
+    }
+  }
+  if (args.claimId !== undefined) claimIdSelector(args.claimId, "arguments.claimId");
+  args.claimIds?.forEach((id, index) => claimIdSelector(id, `arguments.claimIds[${index}]`));
+  return result;
+}
+
+export async function claimTool(service, owner, args) {
+  if (args.action === "renew") return service.renewClaim({ ...owner,
+    claimId: args.claimId, leaseSeconds: args.leaseSeconds });
+  const input = { ...owner, mode: args.mode ?? "exclusive", enforcement: "advisory",
+    reason: args.reason ?? "unspecified", leaseSeconds: args.leaseSeconds };
+  if (args.resources !== undefined) {
+    return { claims: await service.acquireClaims({ ...input, resources: args.resources }) };
+  }
+  return service.acquireClaim({ ...input, resource: args.resource });
+}
+
+export async function releaseTool(service, owner, args) {
+  if (args.claimId !== undefined) {
+    await service.releaseClaim({ ...owner, claimId: args.claimId });
+    return { released: args.claimId };
+  }
+  const selected = args.resource !== undefined ? { resources: [args.resource] } : args;
+  const claims = await service.releaseClaims({ ...owner, ...selected });
+  const released = claims.map(claim => claim.claimId);
+  return { released: args.resource !== undefined ? released[0] : released };
+}

package/node_modules/@agents-can-communicate/mcp-server/src/input-validator.mjs

@@ -43,6 +43,12 @@ function validateSchema(schema, value, path) {
     }
   } else if (schema.type === "array") {
     if (!Array.isArray(value)) fail(path, "must be an array");
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      fail(path, `must contain at least ${schema.minItems} item(s)`);
+    }
+    if (schema.uniqueItems === true && new Set(value).size !== value.length) {
+      fail(path, "must contain unique items");
+    }
     if (schema.items !== undefined) {
       value.forEach((item, index) => validateSchema(schema.items, item, `${path}[${index}]`));
     }
@@ -53,6 +59,9 @@ function validateSchema(schema, value, path) {
   } else if (schema.type === "integer" && !Number.isInteger(value)) {
     fail(path, "must be an integer");
   }
+  if (schema.minLength !== undefined && value.length < schema.minLength) {
+    fail(path, `must contain at least ${schema.minLength} character(s)`);
+  }
 
   if (schema.minimum !== undefined && value < schema.minimum) {
     fail(path, `must be at least ${schema.minimum}`);

package/node_modules/@agents-can-communicate/mcp-server/src/server.mjs

@@ -5,6 +5,7 @@ import { clearSessionBinding, loadSessionBinding, storeSessionBinding }
 
 import { readResource } from "./resources.mjs";
 import { validateToolInput } from "./input-validator.mjs";
+import { claimTool, releaseTool, validateClaimSelectors } from "./claim-tools.mjs";
 import { PUBLIC_TOOLS, RESOURCES } from "./tools.mjs";
 import { createProtocol } from "./protocol.mjs";
 
@@ -133,14 +134,9 @@ async function callTool(name, args, context) {
       return service.setIntent({ ...owner, summary: args.summary, mode: args.mode,
         state: args.state, resourceHints: args.resourceHints ?? [] });
     case "acc_claim":
-      if (args.action === "renew") return service.renewClaim({ ...owner,
-        claimId: args.claimId, leaseSeconds: args.leaseSeconds });
-      return service.acquireClaim({ ...owner, resource: args.resource,
-        mode: args.mode ?? "exclusive", enforcement: "advisory",
-        reason: args.reason ?? "unspecified", leaseSeconds: args.leaseSeconds });
+      return claimTool(service, owner, args);
     case "acc_release":
-      await service.releaseClaim({ ...owner, claimId: args.claimId });
-      return { released: args.claimId };
+      return releaseTool(service, owner, args);
     case "acc_message": {
       const kind = args.kind ?? "note";
       const toParticipantIds = args.to ?? [];
@@ -219,13 +215,16 @@ async function handle(message, context) {
           throw new AccError(EXIT.USAGE, `unknown tool: ${params.name}`, { name: params.name });
         }
         validateToolInput(tool.inputSchema, args);
-        const value = await callTool(params.name, args, context);
+        const value = await callTool(params.name, validateClaimSelectors(params.name, args), context);
         return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
           structuredContent: value };
       } catch (error) {
         // A failing operation is a tool result, not a transport failure: the
         // model must see it and be able to react.
+        const batchConflict = params.name === "acc_claim"
+          && params.arguments?.resources !== undefined && error.details?.conflicts !== undefined;
         return { isError: true,
+          ...(batchConflict ? { structuredContent: { code: error.code, details: error.details } } : {}),
           content: [{ type: "text", text: `${params.name}: ${error.message}` }] };
       }
     }

package/node_modules/@agents-can-communicate/mcp-server/src/tools.mjs

@@ -19,6 +19,10 @@ const object = (properties, required = []) => ({
 
 const string = description => ({ type: "string", description });
 const stringList = description => ({ type: "array", items: { type: "string" }, description });
+const selector = description => ({ ...string(description), minLength: 1 });
+const selectors = description => ({ type: "array", items: { type: "string", minLength: 1 },
+  minItems: 1, uniqueItems: true, description });
+const releaseFields = ["claimId", "claimIds", "resource", "resources", "all"];
 
 export const PUBLIC_TOOLS = Object.freeze([
   {
@@ -68,31 +72,45 @@ export const PUBLIC_TOOLS = Object.freeze([
   },
   {
     name: "acc_claim",
-    description: `Acquire or renew a claim on a resource URI. Claims are `
+    description: `Acquire one resource or atomically acquire a nonempty resources array; renew by claimId. `
+      + `resource returns a Claim; resources returns {claims: [...]}, including one-item arrays. `
+      + `A conflicting batch acquires nothing and lists every conflicting holder in structuredContent.details.conflicts. Claims are `
       + `workspace-wide and advisory here: this client has no write guard, so a claim `
       + `informs peers rather than preventing an edit. ${MUTATION_POLL}`,
     inputSchema: { ...object({
-      resource: string("Resource URI, for example file:packages/core/**."),
+      resource: selector("One resource URI, exclusive with resources; for example file:packages/core/**."),
+      resources: selectors("Resource URIs for one atomic acquisition; unique after normalization and exclusive with resource."),
       action: { type: "string", enum: ["acquire", "renew"] },
       mode: { type: "string", enum: ["shared", "exclusive"] },
       reason: string("Why the resource is being claimed."),
       leaseSeconds: { type: "integer", minimum: 1,
         description: "Lease length; the claim expires without renewal." },
-      claimId: string("Required for renew."),
+      claimId: selector("Required for renew; renew accepts one claimId only."),
     }, ["action"]), oneOf: [
       { properties: { action: { const: "acquire" } }, required: ["resource"],
-        not: { required: ["claimId"] } },
+        not: { anyOf: ["resources", "claimId"].map(field => ({ required: [field] })) } },
+      { properties: { action: { const: "acquire" } }, required: ["resources"],
+        not: { anyOf: ["resource", "claimId"].map(field => ({ required: [field] })) } },
       { properties: { action: { const: "renew" } }, required: ["claimId"],
-        not: { anyOf: ["resource", "mode", "reason"]
+        not: { anyOf: ["resource", "resources", "mode", "reason"]
           .map(field => ({ required: [field] })) } },
     ] },
   },
   {
     name: "acc_release",
-    description: `Release a claim this session owns. ${MUTATION_POLL}`,
-    inputSchema: object({
-      claimId: string("The claim to release."),
-    }, ["claimId"]),
+    description: `Release only claims this session owns, with exactly one of claimId, claimIds, resource, `
+      + `resources, or all: true. Arrays release atomically. Scalar selectors return {released: id}; `
+      + `arrays and all return {released: [ids]}, including an empty all result. `
+      + `all keeps this session's presence and intent open. ${MUTATION_POLL}`,
+    inputSchema: { ...object({
+      claimId: selector("One claim to release."),
+      claimIds: selectors("Claim IDs to release atomically."),
+      resource: selector("One exact resource URI this session holds."),
+      resources: selectors("Exact resource URIs to release atomically; unique after normalization."),
+      all: { type: "boolean", const: true, description: "Release every claim owned by this session." },
+    }), oneOf: releaseFields.map(field => ({ required: [field],
+      not: { anyOf: releaseFields.filter(other => other !== field)
+        .map(other => ({ required: [other] })) } })) },
   },
   {
     name: "acc_message",

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

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

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

@@ -11,5 +11,6 @@ export { CONFIG_FILENAME, CONFIG_SCHEMA_VERSION, RUNTIME_KEYS, defaultProjectCon
   validateProjectConfig } from "./config.mjs";
 export { RECEIPT_STATES, advanceReceipt } from "./states.mjs";
 export { assertMatchableResource, normaliseResource } from "./resources.mjs";
+export { resourceUri as assertResourceUri } from "./fields.mjs";
 export { assertDecisionChange } from "./decision-changes.mjs";
 export { TRANSACTION_INDEXES, assertIndexTuple, indexKeysFor } from "./transaction-indexes.mjs";

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

@@ -1,10 +1,11 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.10.4",
+  "version": "0.11.1",
   "private": true,
   "type": "module",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": "./src/index.mjs",
+    "./writer-mutex": "./src/writer-mutex.mjs"
   },
   "files": [
     "src/"

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

@@ -3,6 +3,6 @@ export { openFilesystemStore, storePaths, ZERO_CURSOR } from "./store.mjs";
 export { diagnoseFilesystemStore, repairFilesystemStore } from "./recovery.mjs";
 export { readStoreIdentity, requireStoreIdentity, STORE_VERSION } from "./identity.mjs";
 export { withWriterMutex } from "./writer-mutex.mjs";
-export { readSessionRecord } from "./session-read.mjs";
+export { readSessionRecord, readDeliveryBindingRecord } from "./session-read.mjs";
 export { openNoFollow } from "./portable-fs.mjs";
 export { migrateFilesystemStore } from "./store-migration.mjs";

package/node_modules/@agents-can-communicate/storage-filesystem/src/session-read.mjs

@@ -25,3 +25,16 @@ export async function readSessionRecord({ root, workspaceId, sessionId, allowLeg
   if (ephemeral === null || await ephemeralIsDeleted(paths, root, "session", sessionId)) return null;
   return validateRecord("session", ephemeral.value);
 }
+
+/** Read the one session's transport metadata without recovery, locks or renewal. */
+export async function readDeliveryBindingRecord({ root, workspaceId, sessionId }) {
+  assertPortableId(sessionId, "session id");
+  const paths = storePaths(root);
+  await requireStoreIdentity(paths, { workspaceId, create: false });
+  const value = await readJsonIfPresent(
+    path.join(paths.ephemeral, "deliveryBinding", `${sessionId}.json`), root);
+  if (value === null || await ephemeralIsDeleted(paths, root, "deliveryBinding", sessionId)) return null;
+  const binding = validateRecord("deliveryBinding", value.value);
+  if (binding.sessionId !== sessionId) throw new Error("delivery binding does not match its path");
+  return binding;
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/state-reads.mjs

@@ -19,14 +19,31 @@ export async function readStateEnvelope(paths, { root, workspaceId }, kind, id)
   return envelope;
 }
 
+// How many records of one kind are read at once. One at a time, a turn spent
+// 0.4 s reading a workspace of a few thousand records; sixteen read it in 0.15 s
+// on the same Mac (#298). The order of the listing is kept.
+const LIST_READS = 16;
+
 export async function listState(paths, root, kind, deadlineAt) {
-  const envelopes = [];
-  for (const filePath of await listJsonFiles(path.join(paths.state, kind), { root })) {
-    assertPublicationDeadline(deadlineAt);
-    const envelope = await readStateEnvelope(paths, { root }, kind, path.basename(filePath, ".json"));
-    if (envelope !== null) envelopes.push(envelope);
-  }
-  return envelopes;
+  const files = await listJsonFiles(path.join(paths.state, kind), { root });
+  const envelopes = new Array(files.length).fill(null);
+  let next = 0;
+  let failed = false;
+  const reader = async () => {
+    while (!failed && next < files.length) {
+      const index = next++;
+      try {
+        assertPublicationDeadline(deadlineAt);
+        envelopes[index] = await readStateEnvelope(paths, { root }, kind,
+          path.basename(files[index], ".json"));
+      } catch (error) {
+        failed = true;
+        throw error;
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(LIST_READS, files.length) }, reader));
+  return envelopes.filter(envelope => envelope !== null);
 }
 
 export async function loadStateEnvelopes(paths, { root, deadlineAt }, wanted = null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.10.4",
+  "version": "0.11.1",
   "accManagedUpdateProtocol": 2,
   "accStoreVersion": 7,
   "type": "module",
@@ -43,6 +43,7 @@
   },
   "bin": {
     "acc": "bin/acc.mjs",
+    "acc-indicator": "bin/acc-indicator.mjs",
     "acc-mcp": "bin/acc-mcp.mjs",
     "acc-hook": "bin/acc-hook.mjs"
   },
@@ -52,6 +53,7 @@
     "docs/ARCHITECTURE.md",
     "docs/CAPABILITIES.md",
     "docs/CLI.md",
+    "docs/STATUS_INDICATOR.md",
     "docs/CONCEPTS.md",
     "docs/CONFIGURATION.md",
     "docs/DESIGN_DECISIONS.md",