agents-can-communicate 0.1.0

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

@@ -0,0 +1,201 @@
+// The model-facing surface stays at six high-level operations. Granular
+// internal transitions remain available to adapters through the CLI and are
+// deliberately not advertised here.
+//
+// Every description says that delivery is polled, because a tool description is
+// the only contract the model ever sees. MCP guarantees no lifecycle, no push,
+// and no write guard, so promising any of them here would be a lie the model
+// cannot check.
+const POLLED = "Delivery is polled: call this again to observe changes. "
+  + "MCP provides no push notification and no wake.";
+
+const object = (properties, required = []) => ({
+  type: "object",
+  properties,
+  required,
+  additionalProperties: false,
+});
+
+const string = description => ({ type: "string", description });
+const stringList = description => ({ type: "array", items: { type: "string" }, description });
+
+export const PUBLIC_TOOLS = Object.freeze([
+  {
+    name: "acc_sync",
+    description: `Read coordination state for this workspace: roster, attention items, and `
+      + `events since a cursor. Use scope "full" to answer questions about the whole `
+      + `workspace, including other participants' collapsed child sessions. ${POLLED}`,
+    inputSchema: object({
+      cursor: string("Resume from this cursor; omit to start from the beginning."),
+      scope: { type: "string", enum: ["delta", "full"],
+        description: "delta is a bounded update; full returns the whole workspace snapshot." },
+      limit: { type: "integer", minimum: 1, maximum: 500,
+        description: "Maximum number of events to return." },
+    }),
+  },
+  {
+    name: "acc_work",
+    description: `Publish what this session is doing now as one concise Intent. Intent is `
+      + `awareness, not authorisation: it never reserves a resource. ${POLLED}`,
+    inputSchema: object({
+      summary: string("One line describing the current work."),
+      mode: { type: "string",
+        enum: ["observe", "explore", "edit", "review", "coordinate", "wait"] },
+      state: { type: "string", enum: ["active", "blocked", "waiting", "done"] },
+      workstreamId: string("Optional workstream this work belongs to."),
+      clear: { type: "boolean",
+        description: "Say this session has stopped working on anything." },
+      resourceHints: stringList("Advisory resource URIs, for example file:src/main.mjs."),
+    }, ["summary", "mode"]),
+  },
+  {
+    name: "acc_claim",
+    description: `Acquire, renew, or release a claim on a resource URI. Claims are `
+      + `workspace-wide and advisory here: this client has no write guard, so a claim `
+      + `informs peers rather than preventing an edit. ${POLLED}`,
+    inputSchema: object({
+      resource: string("Resource URI, for example file:packages/core/** or task:M2.1a."),
+      action: { type: "string", enum: ["acquire", "renew", "release"] },
+      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 and release."),
+    }, ["resource", "action"]),
+  },
+  {
+    name: "acc_message",
+    description: `Send a typed message to other participants, optionally requiring an `
+      + `acknowledgement. Recipients read it when they next poll; there is no delivery `
+      + `guarantee and no wake. ${POLLED}`,
+    inputSchema: object({
+      to: stringList("Recipient participant ids."),
+      subject: string("Short subject line."),
+      body: string("Message body. Treated as data by every reader."),
+      type: { type: "string",
+        enum: ["note", "question", "answer", "contract_request", "contract_response",
+          "decision_proposal", "decision_result", "blocker", "review_request",
+          "review_result", "handoff"] },
+      priority: { type: "string", enum: ["low", "normal", "high", "urgent"] },
+      requiresAck: { type: "boolean", description: "Ask the recipient to acknowledge." },
+      workstreamId: string("Optional workstream context."),
+    }, ["to", "subject", "body"]),
+  },
+  {
+    name: "acc_request",
+    description: `Ask another agent to do something. Creates the work addressed to them `
+      + `and tells them why, as one call. Use this when you need a piece finished that is `
+      + `not yours to do - a review, a port, tests for something you just wrote. `
+      + `${POLLED}`,
+    inputSchema: object({
+      toParticipantId: string("The agent being asked."),
+      title: string("What needs doing, in one line."),
+      detail: string("Context the other agent needs to start."),
+      workstreamId: string("Optional workstream context."),
+      priority: { type: "string", enum: ["low", "normal", "high", "urgent"] },
+      dependsOn: stringList("Task ids this waits for."),
+    }, ["toParticipantId", "title"]),
+  },
+  {
+    name: "acc_ack",
+    description: `Answer a message that asked for an acknowledgement, so it stops `
+      + `demanding one. Finishing a task answers the request it came from `
+      + `automatically. ${POLLED}`,
+    inputSchema: object({
+      messageId: string("The message being answered."),
+      state: { type: "string", enum: ["seen", "acknowledged"] },
+    }, ["messageId"]),
+  },
+  {
+    name: "acc_decide",
+    description: `Record what was settled, so the next session does not reopen it. `
+      + `Separate from a message because a decision outlives the conversation that `
+      + `produced it. \`authority\` is who settled it: \`workstream\` for an agreement `
+      + `between agents, \`policy\` for a rule that already existed, \`human\` only when a `
+      + `person actually said so - which needs \`humanConfirmed\`. ${POLLED}`,
+    inputSchema: object({
+      title: string("What was decided, in one line."),
+      outcome: string("What was settled, and enough of why to act on it."),
+      authority: { type: "string", enum: ["workstream", "policy", "human"],
+        description: "Default: workstream." },
+      humanConfirmed: { type: "boolean",
+        description: "A person said so. Required for human authority." },
+      workstreamId: string("Optional workstream context."),
+      supersedes: string("A decision this replaces."),
+      decidedBy: stringList("Participants who settled it. Defaults to you."),
+    }, ["title", "outcome"]),
+  },
+  {
+    name: "acc_workstream",
+    description: `Group related work so several agents can see it as one thing, or take `
+      + `on steering one that exists. Optional: a single request needs no workstream. `
+      + `An open workstream with no coordinator is reported to everyone until somebody `
+      + `takes it. ${POLLED}`,
+    inputSchema: object({
+      action: { type: "string", enum: ["create", "coordinate", "release"],
+        description: "Default: create." },
+      title: string("Short name. Creating one."),
+      objective: string("What finishing it would mean. Creating one."),
+      workstreamId: string("The workstream to coordinate or hand back."),
+    }, []),
+  },
+  {
+    name: "acc_task",
+    description: `Create or transition an optional task within a workstream. Tasks are for `
+      + `work that needs assignment, dependencies, or acceptance tracking; ordinary work `
+      + `needs only Intent. ${POLLED}`,
+    inputSchema: object({
+      action: { type: "string", enum: ["create", "claim", "transition", "decline"] },
+      workstreamId: string("Workstream the task belongs to."),
+      title: string("Task title, required when creating."),
+      detail: string("Context for whoever picks it up."),
+      assigneeParticipantId: string("Agent this is for. Only they can take it."),
+      taskId: string("Required for claim and transition."),
+      state: { type: "string", enum: ["pending", "in_progress", "review", "done", "blocked"] },
+      dependsOn: stringList("Task ids this task waits for."),
+      reason: string("Why, when declining."),
+      force: { type: "boolean",
+        description: "Take work held by a session that has gone quiet." },
+    }, ["action"]),
+  },
+  {
+    name: "acc_finish",
+    description: `Record a handoff describing what was completed and what remains, and `
+      + `release the claims this session owns. Call it while still working, not after: `
+      + `nothing else writes the summary for you. ${POLLED}`,
+    inputSchema: object({
+      goal: string("What this stretch of work was for."),
+      status: { type: "string", enum: ["complete", "partial", "blocked"] },
+      completed: stringList("What was finished."),
+      remaining: stringList("What is left."),
+      blockers: stringList("What is in the way."),
+      toParticipantId: string("Participant taking over, if any."),
+    }, ["goal"]),
+  },
+]);
+
+export const RESOURCES = Object.freeze([
+  { uri: "acc://snapshot", name: "Workspace snapshot", mimeType: "application/json",
+    description: "The whole coordination state: participants, intents, claims, tasks." },
+  { uri: "acc://roster", name: "Participant roster", mimeType: "application/json",
+    description: "Sessions with their harness and presence, including collapsed children." },
+  { uri: "acc://workstreams", name: "Workstreams", mimeType: "application/json",
+    description: "Open workstreams and their coordinator lease, if any." },
+  { uri: "acc://tasks", name: "Tasks", mimeType: "application/json",
+    description: "Tasks with state, assignee, and dependencies." },
+  { uri: "acc://inbox", name: "Inbox", mimeType: "application/json",
+    description: "Messages addressed to this participant, rendered as attributed data." },
+]);
+
+// Declared, not assumed. MCP is a polling transport with no lifecycle contract,
+// so everything except polling stays false.
+export const MCP_CAPABILITIES = Object.freeze({
+  lifecycle: Object.freeze({ sessionStart: false, sessionResume: false, sessionEnd: false,
+    childSessions: false }),
+  context: Object.freeze({ startupInjection: false, beforeTurnInjection: false,
+    safePointInjection: false }),
+  guards: Object.freeze({ beforeRead: false, beforeWrite: false, beforeShell: false }),
+  delivery: Object.freeze({ polling: true, activeNotification: false,
+    wakeDormantSession: false }),
+  execution: Object.freeze({ launch: false, resume: false, terminate: false }),
+});

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

@@ -0,0 +1,12 @@
+{
+  "name": "@agents-can-communicate/protocol",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src/"
+  ]
+}

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

@@ -0,0 +1,151 @@
+import { AccError, EXIT } from "./errors.mjs";
+import { assertPortableId } from "./ids.mjs";
+
+export const CONFIG_SCHEMA_VERSION = 1;
+
+// One name, so discovery is a lookup rather than a search. A tool that accepts
+// four spellings has four ways to load the wrong file.
+export const CONFIG_FILENAME = "acc.workspace.json";
+
+// Project config carries identity and shared policy. Presence, messages,
+// claims, receipts and tokens belong to the runtime directory; a repository is
+// the wrong place for them, and a config carrying them is either a mistake or
+// an attempt to hand a peer state it would otherwise have to earn.
+export const RUNTIME_KEYS = Object.freeze(["sessions", "participants", "messages",
+  "claims", "receipts", "intents", "events", "tokens", "credentials"]);
+
+const KNOWN_KEYS = Object.freeze(["schemaVersion", "workspaceId", "displayName",
+  "roots", "policy", "requiredAdapters", "extensions"]);
+
+const CLAIM_MODES = Object.freeze(["advisory", "guarded"]);
+
+// The same default the context projector uses. Zero silently disables
+// coordination context; a very large one spends the model's window on a roster.
+const DEFAULT_CONTEXT_BUDGET_BYTES = 6_000;
+const MAX_CONTEXT_BUDGET_BYTES = 64_000;
+
+const data = (message, details) => {
+  throw new AccError(EXIT.DATA, message, details);
+};
+
+/**
+ * What a workspace policy is when nobody wrote one.
+ *
+ * Config is optional, so every value it can carry needs an answer without it.
+ * `workspaceId` is the exception and is null: identity comes from Git or the
+ * directory in that case, and inventing one here would give two checkouts of
+ * the same project two identities that both look deliberate.
+ */
+export function defaultProjectConfig() {
+  return Object.freeze({
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    workspaceId: null,
+    displayName: null,
+    roots: Object.freeze(["."]),
+    policy: Object.freeze({ claimMode: "advisory",
+      contextBudgetBytes: DEFAULT_CONTEXT_BUDGET_BYTES }),
+    requiredAdapters: Object.freeze([]),
+    extensions: Object.freeze({}),
+  });
+}
+
+function assertRoot(root, source) {
+  if (typeof root !== "string" || root === "") {
+    data("each workspace root must be a non-empty string", { source, root });
+  }
+  // Absolute is one machine's layout committed to a shared repository.
+  if (root.startsWith("/") || /^[A-Za-z]:[\\/]/.test(root)) {
+    data("a workspace root must be relative to the config", { source, root });
+  }
+  // Checked on the segments rather than the string: `packages/../../escape`
+  // leaves the workspace while containing no leading `..`.
+  const segments = root.split(/[\\/]/);
+  let depth = 0;
+  for (const segment of segments) {
+    if (segment === "" || segment === ".") continue;
+    depth += segment === ".." ? -1 : 1;
+    if (depth < 0) data("a workspace root must not leave the workspace", { source, root });
+  }
+}
+
+function assertPolicy(policy, source) {
+  if (policy === undefined) return { claimMode: "advisory",
+    contextBudgetBytes: DEFAULT_CONTEXT_BUDGET_BYTES };
+  if (policy === null || typeof policy !== "object" || Array.isArray(policy)) {
+    data("policy must be an object", { source });
+  }
+  for (const key of Object.keys(policy)) {
+    if (!["claimMode", "contextBudgetBytes"].includes(key)) {
+      data(`unknown policy key: ${key}`, { source, key });
+    }
+  }
+  const claimMode = policy.claimMode ?? "advisory";
+  if (!CLAIM_MODES.includes(claimMode)) {
+    data(`policy.claimMode must be one of ${CLAIM_MODES.join(", ")}`, { source, claimMode });
+  }
+  const contextBudgetBytes = policy.contextBudgetBytes ?? DEFAULT_CONTEXT_BUDGET_BYTES;
+  if (!Number.isInteger(contextBudgetBytes) || contextBudgetBytes <= 0
+    || contextBudgetBytes > MAX_CONTEXT_BUDGET_BYTES) {
+    data(`policy.contextBudgetBytes must be an integer between 1 and ${
+      MAX_CONTEXT_BUDGET_BYTES}`, { source, contextBudgetBytes });
+  }
+  return { claimMode, contextBudgetBytes };
+}
+
+/**
+ * Validate a project config.
+ *
+ * Strict about unknown keys, with `extensions` as the one declared door for
+ * anything else. A silently ignored key is how a team's policy stops applying
+ * without anyone noticing - `clam_mode` reads like a typo to a human and like
+ * nothing at all to a parser that shrugs.
+ */
+export function validateProjectConfig(config, { source = CONFIG_FILENAME } = {}) {
+  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+    data("the workspace config must be an object", { source });
+  }
+  if (config.schemaVersion !== CONFIG_SCHEMA_VERSION) {
+    data("unknown workspace config schemaVersion",
+      { source, schemaVersion: config.schemaVersion ?? null });
+  }
+
+  const runtime = RUNTIME_KEYS.filter(key => Object.hasOwn(config, key));
+  if (runtime.length > 0) {
+    data(`the workspace config must not carry runtime state: ${runtime.join(", ")}`,
+      { source, keys: runtime });
+  }
+  const unknown = Object.keys(config).filter(key => !KNOWN_KEYS.includes(key));
+  if (unknown.length > 0) {
+    data(`unknown workspace config key: ${unknown.join(", ")}`, { source, keys: unknown });
+  }
+
+  assertPortableId(config.workspaceId, "workspace id");
+  if (config.displayName !== undefined && typeof config.displayName !== "string") {
+    data("displayName must be a string", { source });
+  }
+
+  const roots = config.roots ?? ["."];
+  if (!Array.isArray(roots) || roots.length === 0) {
+    data("roots must be a non-empty array", { source });
+  }
+  for (const root of roots) assertRoot(root, source);
+
+  const requiredAdapters = config.requiredAdapters ?? [];
+  if (!Array.isArray(requiredAdapters)) data("requiredAdapters must be an array", { source });
+  for (const adapter of requiredAdapters) assertPortableId(adapter, "adapter id");
+
+  if (config.extensions !== undefined && (config.extensions === null
+    || typeof config.extensions !== "object" || Array.isArray(config.extensions))) {
+    data("extensions must be an object", { source });
+  }
+
+  return Object.freeze({
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    workspaceId: config.workspaceId,
+    displayName: config.displayName ?? null,
+    roots: Object.freeze([...roots]),
+    policy: Object.freeze(assertPolicy(config.policy, source)),
+    requiredAdapters: Object.freeze([...requiredAdapters]),
+    extensions: Object.freeze({ ...(config.extensions ?? {}) }),
+  });
+}

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

@@ -0,0 +1,25 @@
+import { AccError, EXIT } from "./errors.mjs";
+
+// The CLI JSON envelope is versioned independently of the record schemas, so a
+// client can recognise an envelope it cannot yet interpret (spec section 11).
+export const ENVELOPE_VERSION = 1;
+
+export function ok(data, meta = {}) {
+  return Object.freeze({ envelope_version: ENVELOPE_VERSION, ok: true, data, meta });
+}
+
+export function failure(error) {
+  // Stacks carry absolute paths and internal structure. An envelope is a
+  // published artefact, so it gets the code, the human message, and the
+  // structured details the thrower chose to expose - nothing else.
+  const known = error instanceof AccError;
+  return Object.freeze({
+    envelope_version: ENVELOPE_VERSION,
+    ok: false,
+    error: {
+      code: known ? error.code : EXIT.DATA,
+      message: error?.message ?? String(error),
+      details: known ? error.details : {},
+    },
+  });
+}

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

@@ -0,0 +1,30 @@
+// Numeric slots are a compatibility contract, not an implementation detail:
+// scripts and adapters branch on them. Slot 3 stays TIMEOUT and slot 6 carries
+// the meaning the reconciled prototype called REQUIRED, so ported process tests
+// keep their exit-code semantics after the rename to ATTENTION.
+export const EXIT = Object.freeze({
+  OK: 0,
+  USAGE: 2,
+  TIMEOUT: 3,
+  DATA: 4,
+  CONFLICT: 5,
+  ATTENTION: 6,
+});
+
+const CODES = new Set(Object.values(EXIT));
+
+export class AccError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    if (!CODES.has(code)) {
+      throw new TypeError(`unknown exit code: ${String(code)}`);
+    }
+    this.name = "AccError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function isAccError(value) {
+  return value instanceof AccError;
+}

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

@@ -0,0 +1,103 @@
+import { AccError, EXIT } from "./errors.mjs";
+import { assertPortableId } from "./ids.mjs";
+
+// Resource URIs are deliberately not identifiers: they carry a scheme and an
+// opaque part that may hold slashes, globs, and fragments (file:src/**,
+// doc:architecture#camera-contract). What they may not carry is whitespace or
+// control bytes, which break every line-oriented tool that displays them.
+const RESOURCE_URI = /^[a-z][a-z0-9+.-]*:[^\s]+$/;
+
+// Written as code rather than a character-class literal: escaped control
+// ranges in a regex are easy to corrupt silently in an editor or a patch, and
+// a corrupted range fails open.
+function hasControl(value, { allowNewline = false } = {}) {
+  for (const character of value) {
+    const code = character.codePointAt(0);
+    if (allowNewline && (code === 10 || code === 13)) continue;
+    if (code < 32 || code === 127) return true;
+  }
+  return false;
+}
+
+export function invalid(field, message, value) {
+  throw new AccError(EXIT.DATA, `${field} ${message}`, { field, value });
+}
+
+export const id = (value, field) => {
+  try {
+    return assertPortableId(value, field);
+  } catch {
+    return invalid(field, "must be a portable identifier", value);
+  }
+};
+
+export const text = ({ max = 500, multiline = false } = {}) => (value, field) => {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    invalid(field, "must be a non-empty string", value);
+  }
+  if (value.length > max) invalid(field, `must be at most ${max} characters`, value);
+  if (hasControl(value, { allowNewline: multiline })) {
+    invalid(field, "must not contain control characters", value);
+  }
+  return value;
+};
+
+export const timestamp = (value, field) => {
+  const milliseconds = typeof value === "string" ? Date.parse(value) : Number.NaN;
+  if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString() !== value) {
+    invalid(field, "must be a canonical UTC timestamp", value);
+  }
+  return value;
+};
+
+export const oneOf = (...allowed) => (value, field) => {
+  if (!allowed.includes(value)) {
+    invalid(field, `must be one of ${allowed.join(", ")}`, value);
+  }
+  return value;
+};
+
+export const resourceUri = (value, field) => {
+  if (typeof value !== "string" || !RESOURCE_URI.test(value) || hasControl(value)
+    || value.length > 1024) {
+    invalid(field, "must be a scheme-qualified resource URI", value);
+  }
+  return value;
+};
+
+export const listOf = inner => (value, field) => {
+  if (!Array.isArray(value)) invalid(field, "must be an array", value);
+  value.forEach((item, index) => inner(item, `${field}[${index}]`));
+  return value;
+};
+
+export const nullable = inner => (value, field) =>
+  (value === null ? null : inner(value, field));
+
+export const positiveInteger = (value, field) => {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    invalid(field, "must be a positive integer", value);
+  }
+  return value;
+};
+
+export const flag = (value, field) => {
+  if (typeof value !== "boolean") invalid(field, "must be a boolean", value);
+  return value;
+};
+
+export const plainObject = (value, field) => {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    invalid(field, "must be an object", value);
+  }
+  return value;
+};
+
+// Event sequence numbers are zero-padded decimal strings so lexicographic
+// order equals numeric order in a directory listing and in JSON.
+export const sequence = (value, field) => {
+  if (typeof value !== "string" || !/^[0-9]{16}$/.test(value)) {
+    invalid(field, "must be a 16-digit zero-padded sequence", value);
+  }
+  return value;
+};

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

@@ -0,0 +1,25 @@
+import { randomBytes as nodeRandomBytes } from "node:crypto";
+
+import { AccError, EXIT } from "./errors.mjs";
+
+// Identifiers become path segments and record filenames on every backend, so
+// the alphabet is the intersection of what POSIX and Windows accept safely:
+// no separators, no control characters, no reserved device names, no trailing
+// dot, and a leading alphanumeric so nothing is hidden or looks like ".." .
+const PORTABLE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+const WINDOWS_DEVICE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+
+export function assertPortableId(value, label) {
+  if (typeof value !== "string" || !PORTABLE_ID.test(value)
+    || value.endsWith(".") || WINDOWS_DEVICE.test(value)) {
+    throw new AccError(EXIT.DATA, `invalid ${label}`, { value });
+  }
+  return value;
+}
+
+export function createId(kind, randomBytes = nodeRandomBytes) {
+  assertPortableId(kind, "kind");
+  // base64url keeps the payload inside the portable alphabet: unlike base64 it
+  // emits no "/", "+", or "=" padding.
+  return `${kind}_${Buffer.from(randomBytes(16)).toString("base64url")}`;
+}

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

@@ -0,0 +1,9 @@
+// Schemas, identifiers, error codes, and JSON envelopes.
+export { AccError, EXIT, isAccError } from "./errors.mjs";
+export { assertPortableId, createId } from "./ids.mjs";
+export { ENVELOPE_VERSION, failure, ok } from "./envelopes.mjs";
+export { RECORD_KINDS, SCHEMA_VERSION, validateRecord } from "./schema.mjs";
+export { CONFIG_FILENAME, CONFIG_SCHEMA_VERSION, RUNTIME_KEYS, defaultProjectConfig,
+  validateProjectConfig } from "./config.mjs";
+export { DELIVERY_STATES, TASK_STATES, advanceDelivery, transitionTask } from "./states.mjs";
+export { assertMatchableResource, normaliseResource } from "./resources.mjs";

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

@@ -0,0 +1,74 @@
+/**
+ * One name for one file.
+ *
+ * A claim is a string, and a file has many spellings: `src/a.mjs`,
+ * `./src/a.mjs`, `src//a.mjs`, `src/x/../a.mjs`. All four name the same file and
+ * none of them matched the others, so a claim written one way protected nothing
+ * against a write spelled another - the claim was taken, `acc status` reported
+ * `protection guarded`, and the write went through.
+ *
+ * Only the path part of a `file:` resource is touched. Other schemes are opaque
+ * identifiers, and rewriting one would be inventing meaning ACC does not have.
+ * A trailing `/**` is a glob and is preserved: the segments before it are
+ * normalised, the marker is put back.
+ */
+const GLOB = "/**";
+
+function normalisePath(value) {
+  const segments = [];
+  for (const segment of value.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    // `..` climbing past the start is kept, not swallowed: the result would name
+    // something outside the workspace, and a resource that cannot be relativised
+    // must stay visibly wrong rather than quietly become a different file.
+    if (segment === ".." && segments.length > 0 && segments.at(-1) !== "..") {
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  return segments.join("/");
+}
+
+/**
+ * A claim that cannot match anything is worse than no claim.
+ *
+ * Only a trailing `/**` is understood. Every other shape an agent reaches for -
+ * `file:src` for a directory, `file:src/`, `file:src/*.mjs`, `file:src/*` - was
+ * accepted, stored, and reported by `acc status` as `protection guarded`, and
+ * covered nothing at all. Measured: four spellings, four claims taken, four
+ * writes allowed, and only `file:src/**` denied.
+ *
+ * Refusing is the honest answer. The claim was going to be useless either way;
+ * this way its author finds out, and is told the form that works.
+ */
+export function assertMatchableResource(resource, fail) {
+  if (typeof resource !== "string" || !resource.startsWith("file:")) return resource;
+  const rest = resource.slice("file:".length);
+  if (rest.endsWith("/") && rest !== "/") {
+    fail(`${resource} names a directory; claim ${resource}** to cover what is in it`);
+  }
+  const body = rest.endsWith(GLOB) ? rest.slice(0, -GLOB.length) : rest;
+  if (body.includes("*")) {
+    fail(`${resource} matches nothing: only a trailing /** is understood, `
+      + `so a directory is claimed as file:<path>/**`);
+  }
+  return resource;
+}
+
+export function normaliseResource(resource) {
+  if (typeof resource !== "string") return resource;
+  const colon = resource.indexOf(":");
+  if (colon === -1 || resource.slice(0, colon) !== "file") return resource;
+
+  const rest = resource.slice(colon + 1);
+  const glob = rest.endsWith(GLOB);
+  const body = glob ? rest.slice(0, -GLOB.length) : rest;
+  // An absolute path keeps its leading slash: it names a different thing from
+  // the relative path with the same spelling, and pretending otherwise would
+  // merge two resources that are not the same.
+  const absolute = body.startsWith("/");
+  const normalised = normalisePath(body);
+  if (normalised === "" && !glob) return resource;
+  return `file:${absolute ? "/" : ""}${normalised}${glob ? GLOB : ""}`;
+}