agents-can-communicate 0.1.0

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

@@ -0,0 +1,126 @@
+import { listSessionBindings } from "@agents-can-communicate/adapter-sdk";
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+/**
+ * Work out which session is running this command.
+ *
+ * Every mutating command needs a session id and the generation that proves the
+ * caller is that session. Until this existed, both had to be passed on the
+ * command line, and the shipped skills told agents to pass
+ * `--session "$ACC_SESSION" --generation "$ACC_GENERATION"` - two variables that
+ * nothing in the system has ever set. The generation is not printed by `acc
+ * status` either, deliberately: it is the proof of ownership, not public
+ * information. So the documented workflow could not be carried out by any agent
+ * on any client, and the only way through was to read ACC's own files by hand,
+ * which the same skill forbids in as many words.
+ *
+ * The hook runtime already knows both. It writes them into a binding at
+ * SessionStart, keyed by the harness's own session id. What was missing was a
+ * way for a shell inside that session to find its own binding. Each step below
+ * answers that from something the caller demonstrably has.
+ */
+const NEEDS_OWNER = Object.freeze(new Set(["work", "claim", "release", "message",
+  "request", "ack", "workstream", "task", "finish", "decide"]));
+
+/**
+ * Reads that are answers about *you*.
+ *
+ * Attention is computed per session: what is addressed to you, what has become
+ * unblocked for you. Run by hand with nothing identifying the caller, both of
+ * these answered for nobody and returned an empty list - so an agent told at the
+ * top of its turn that work was waiting could ask `acc status` and be told there
+ * was none. They resolve softly: a shell with no session attached still gets the
+ * roster and the events, which is what it came for.
+ */
+const WANTS_OWNER = Object.freeze(new Set(["sync", "status"]));
+
+export const needsOwner = command => NEEDS_OWNER.has(command);
+
+/**
+ * Bindings whose session is still open, carrying the session's own checkout.
+ *
+ * A binding outlives a crash, so one that names a closed or vanished session is
+ * a leftover. Acting as a closed session would fail deeper in the service with a
+ * conflict; dropping it here means the *next* candidate can be recognised
+ * instead.
+ */
+async function liveCandidates({ context }) {
+  const bindings = await listSessionBindings({ runtimeDir: context.paths.root });
+  if (bindings.length === 0) return [];
+  const status = await context.service.collectStatus({});
+  const live = new Map(status.participants
+    .filter(participant => participant.presence !== "offline")
+    .map(participant => [participant.sessionId, participant]));
+  return bindings
+    .filter(binding => live.has(binding.accSessionId))
+    .map(binding => ({ ...binding, session: live.get(binding.accSessionId) }));
+}
+
+const describe = candidates => candidates
+  .map(candidate => `${candidate.session.participantId} (${candidate.session.harness})`)
+  .join(", ");
+
+export async function resolveOwner({ command, options, context, env = {} }) {
+  const soft = WANTS_OWNER.has(command);
+  if (!soft && !needsOwner(command)) return options;
+  if (options.session !== undefined && options.generation !== undefined) return options;
+  if (soft && options.participant !== undefined) return options;
+
+  const candidates = await liveCandidates({ context });
+  const take = candidate => ({ ...options, session: candidate.accSessionId,
+    generation: candidate.generation,
+    // `status` filters by participant rather than by session, so it is told who
+    // the caller is in the terms it works in.
+    participant: options.participant ?? candidate.session.participantId });
+
+  // Named a session but not the generation: the id is in `acc status --json`,
+  // so this is what an agent reaches for first, and refusing it would teach the
+  // wrong lesson about which half is secret.
+  if (options.session !== undefined) {
+    // The reads never needed a generation, and a session opened by `acc attach`
+    // has no binding to find one in. Answering for the session it was given is
+    // both what it was asked and what it did before this resolver existed.
+    if (soft) return options;
+    const named = candidates.find(candidate => candidate.accSessionId === options.session);
+    if (named !== undefined) return take(named);
+    throw new AccError(EXIT.USAGE,
+      `no live session ${options.session} in this workspace`,
+      { command, session: options.session });
+  }
+
+  // The documented pair, honoured for anyone who has wired it up themselves.
+  if (typeof env.ACC_SESSION === "string" && typeof env.ACC_GENERATION === "string") {
+    return { ...options, session: env.ACC_SESSION, generation: env.ACC_GENERATION };
+  }
+
+  // The client's own session id, under whatever name it exports it. Claude Code
+  // sets CLAUDE_CODE_SESSION_ID, measured equal to the `session_id` its hooks
+  // receive; matching on the value rather than the variable name means a client
+  // that names it something else works without ACC knowing the name.
+  const exported = new Set(Object.values(env).filter(value => typeof value === "string"));
+  const byEnvironment = candidates
+    .filter(candidate => exported.has(candidate.harnessSessionId));
+  if (byEnvironment.length === 1) return take(byEnvironment[0]);
+
+  // Two agents in one workspace are the normal case, and each is usually in its
+  // own checkout - that is what the worktree story is. Same repository, so the
+  // same workspace, and the checkout tells them apart.
+  const here = context.descriptor.git?.worktreeRoot;
+  const byCheckout = here === undefined
+    ? []
+    : candidates.filter(candidate => candidate.session.checkoutRoot === here);
+  if (byCheckout.length === 1) return take(byCheckout[0]);
+
+  if (candidates.length === 1) return take(candidates[0]);
+
+  // Guessing between two live sessions would let one agent act as another, which
+  // is exactly what the generation exists to prevent. So this refuses, and says
+  // what it found.
+  if (soft) return options;
+  throw new AccError(EXIT.USAGE, candidates.length === 0
+    ? `${command} could not tell which session is running it: no live session is `
+      + "attached here. An adapter attaches one at SessionStart; `acc status` shows who is."
+    : `${command} could not tell which of ${candidates.length} live sessions is running `
+      + `it (${describe(candidates)}). Pass --session, which \`acc status --json\` lists.`,
+  { command, candidates: candidates.map(candidate => candidate.accSessionId) });
+}

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

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, CONFIG_FILENAME, EXIT, validateProjectConfig }
+  from "@agents-can-communicate/protocol";
+
+/**
+ * @typedef {{ id: string, roots: string[], source: "config" | "git" | "directory",
+ *   displayName: string, git?: object }} WorkspaceDescriptor
+ */
+
+const stableId = value =>
+  `workspace_${createHash("sha256").update(value).digest("hex").slice(0, 32)}`;
+
+async function readConfigNoFollow(configPath) {
+  let handle;
+  try {
+    handle = await open(configPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    // ELOOP is what O_NOFOLLOW reports for a symlink. A config reached through
+    // a link may point anywhere, so it is refused rather than followed.
+    throw new AccError(EXIT.DATA, "cannot safely read the workspace config",
+      { configPath, cause: error.message });
+  }
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+      throw new AccError(EXIT.DATA, "the workspace config is not a regular file", { configPath });
+    }
+    return JSON.parse(await handle.readFile("utf8"));
+  } catch (error) {
+    if (error instanceof AccError) throw error;
+    throw new AccError(EXIT.DATA, "the workspace config is not valid JSON",
+      { configPath, cause: error.message });
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Walk up looking for the one config filename.
+ *
+ * Sessions start wherever the human happens to be, so a config that only counted
+ * at the top of the tree would apply to some sessions in a project and not
+ * others. The walk stops at the filesystem root: climbing past it would let a
+ * stray file in a home directory claim every project underneath.
+ */
+async function findConfig(start) {
+  let directory = start;
+  for (;;) {
+    const candidate = path.join(directory, CONFIG_FILENAME);
+    const config = await readConfigNoFollow(candidate);
+    if (config !== null) return { config, configPath: candidate, base: directory };
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+async function canonical(directory, label) {
+  try {
+    return await realpath(directory);
+  } catch (error) {
+    throw new AccError(EXIT.USAGE, `cannot resolve the ${label}`,
+      { directory, cause: error.message });
+  }
+}
+
+async function probeGit(gitProbe, cwd) {
+  if (typeof gitProbe !== "function") return null;
+  try {
+    return await gitProbe({ cwd });
+  } catch {
+    // Git is enrichment, never a requirement. A missing binary, a bare
+    // directory, or a probe failure all degrade to a directory workspace.
+    return null;
+  }
+}
+
+/**
+ * Resolve the workspace for a working directory. Pure: no argument parsing, no
+ * stdout, no process exit, because the MCP server and every native adapter
+ * import this module directly.
+ */
+export async function discoverWorkspace({ cwd, env = {}, gitProbe, explicitConfig }) {
+  const override = env.ACC_WORKSPACE_ROOT;
+  if (typeof override === "string" && override.length > 0 && !path.isAbsolute(override)) {
+    throw new AccError(EXIT.USAGE, "ACC_WORKSPACE_ROOT must be an absolute path",
+      { value: override });
+  }
+  const start = await canonical(
+    typeof override === "string" && override.length > 0 ? override : cwd, "workspace root");
+
+  const found = explicitConfig === undefined
+    ? await findConfig(start)
+    : { config: await readConfigNoFollow(explicitConfig), configPath: explicitConfig,
+      base: path.dirname(explicitConfig) };
+  const config = found?.config == null
+    ? null
+    : validateProjectConfig(found.config, { source: found.configPath });
+
+  const git = await probeGit(gitProbe, start);
+  const enrichment = git === null ? {} : {
+    git: Object.freeze({
+      commonDir: git.commonDir,
+      worktreeRoot: git.worktreeRoot,
+      branch: git.branch ?? null,
+      head: git.head ?? null,
+      remote: git.remote ?? null,
+    }),
+  };
+
+  if (config !== null) {
+    // Declared roots are relative to the config, never to the working
+    // directory. Runtime containment is checked against these, so resolving
+    // them against the wrong base would let state land somewhere it must not.
+    const roots = await Promise.all(config.roots
+      .map(root => canonical(path.resolve(found.base, root), "declared workspace root")));
+    return Object.freeze({
+      id: config.workspaceId,
+      roots: Object.freeze([...new Set(roots)]),
+      source: "config",
+      displayName: config.displayName ?? path.basename(found.base),
+      policy: config.policy,
+      requiredAdapters: config.requiredAdapters,
+      ...enrichment,
+    });
+  }
+
+  if (git !== null) {
+    // Every worktree of one repository shares the common directory, so they
+    // share one workspace while keeping distinct checkout metadata.
+    return Object.freeze({
+      id: stableId(await canonical(git.commonDir, "Git common directory")),
+      roots: Object.freeze([start]),
+      source: "git",
+      displayName: path.basename(git.worktreeRoot),
+      ...enrichment,
+    });
+  }
+
+  return Object.freeze({
+    id: stableId(start),
+    roots: Object.freeze([start]),
+    source: "directory",
+    displayName: path.basename(start),
+  });
+}

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

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

package/node_modules/@agents-can-communicate/core/src/claims.mjs

@@ -0,0 +1,180 @@
+import { AccError, EXIT, SCHEMA_VERSION, assertMatchableResource, createId,
+  normaliseResource, validateRecord } from "@agents-can-communicate/protocol";
+
+import { ensureMaterialised } from "./materialisation.mjs";
+import { classifySessionPresence } from "./sessions.mjs";
+
+const GLOB = "/**";
+
+const split = resource => {
+  const index = resource.indexOf(":");
+  return { scheme: resource.slice(0, index), rest: resource.slice(index + 1) };
+};
+
+/**
+ * Two resources overlap when they name the same thing or when one is a glob
+ * prefix of the other. Comparison is per path segment, so `file:ab/c` is not
+ * inside `file:a/**` - raw string prefixes are how this check usually goes
+ * wrong. Adapters may add richer overlap keys; the core rule stays generic.
+ */
+export function overlaps(left, right) {
+  if (left === right) return true;
+  const a = split(left);
+  const b = split(right);
+  if (a.scheme !== b.scheme) return false;
+  const covers = (glob, plain) => glob.rest.endsWith(GLOB)
+    && (plain.rest === glob.rest.slice(0, -GLOB.length)
+      || plain.rest.startsWith(`${glob.rest.slice(0, -GLOB.length)}/`));
+  return covers(a, b) || covers(b, a);
+}
+
+const isLive = (claim, now) => Date.parse(claim.expiresAt) > Date.parse(now);
+
+export function createClaimService(ports, sessions) {
+  const { store, clock, ids } = ports;
+
+  async function requireOwner(input, action) {
+    const existing = await sessions.locateSession(input.sessionId, input.workspaceId);
+    if (existing === null || existing.record.state !== "open") {
+      throw new AccError(EXIT.CONFLICT, `cannot ${action} from a session that is not open`,
+        { sessionId: input.sessionId });
+    }
+    if (existing.record.generation !== input.generation) {
+      throw new AccError(EXIT.CONFLICT, `cannot ${action} with a replaced session generation`,
+        { sessionId: input.sessionId });
+    }
+    return existing.record;
+  }
+
+  function conflictWith(existing, owner, now, snapshotSessions) {
+    const ownerSession = snapshotSessions.find(item => item.sessionId === existing.ownerSessionId);
+    // Staleness is reported so the requester can decide what to do; it never
+    // releases the claim on its own.
+    const ownerPresence = ownerSession === undefined
+      ? "offline"
+      : classifySessionPresence(ownerSession, now);
+    return new AccError(EXIT.CONFLICT, "the resource is already claimed", {
+      claimId: existing.claimId,
+      resource: existing.resource,
+      ownerSessionId: existing.ownerSessionId,
+      ownerPresence,
+      expiresAt: existing.expiresAt,
+      requestedBy: owner.sessionId,
+    });
+  }
+
+  async function acquireClaim(input) {
+    const session = await requireOwner(input, "claim");
+    // One name for one file, decided here rather than at each surface, so a
+    // claim taken over MCP and one taken from the CLI mean the same thing - and
+    // a shape that could never match is refused rather than stored.
+    assertMatchableResource(input.resource, message => {
+      throw new AccError(EXIT.USAGE, message, { resource: input.resource });
+    });
+    const resource = normaliseResource(input.resource);
+    const workspaceId = session.workspaceId;
+    await ensureMaterialised(ports, { workspaceId, descriptor: input.descriptor,
+      reason: "durable_object" });
+    const now = clock.now();
+    const expiresAt = new Date(Date.parse(now) + (input.leaseSeconds ?? 1800) * 1000)
+      .toISOString();
+    // Only to name the owner of a conflicting claim in the error.
+    const snapshot = await store.snapshot(workspaceId, { kinds: ["session"] });
+
+    let record = null;
+    await store.transaction(async tx => {
+      const live = tx.list("claim", claim => isLive(claim, now));
+      // This session's own claim on this resource, live or lapsed. Looking only
+      // among the live ones left the expired record behind and made a fresh one
+      // beside it, so taking a resource back after a lease ran out reported
+      // success while the workspace still held a dead claim saying otherwise -
+      // and the owner went on being told its claim had run out.
+      const mine = tx.list("claim", claim => claim.ownerSessionId === session.sessionId
+        && claim.resource === resource).at(0);
+      const blocking = live.find(claim => overlaps(claim.resource, resource)
+        && claim.ownerSessionId !== session.sessionId
+        && (claim.mode === "exclusive" || input.mode === "exclusive"));
+      if (blocking !== undefined) throw conflictWith(blocking, session, now, snapshot.sessions);
+
+      const claimId = mine?.claimId ?? createId("claim");
+      record = validateRecord("claim", {
+        schemaVersion: SCHEMA_VERSION,
+        claimId,
+        workspaceId,
+        ownerSessionId: session.sessionId,
+        resource,
+        mode: input.mode ?? "exclusive",
+        enforcement: input.enforcement ?? "advisory",
+        reason: input.reason,
+        // A lapsed claim taken again is a new period of holding it, not a
+        // continuation of one that ended.
+        acquiredAt: mine !== undefined && isLive(mine, now) ? mine.acquiredAt : now,
+        expiresAt,
+        generation: ids.next("generation"),
+      });
+      tx.put("claim", claimId, record, tx.generationOf("claim", claimId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId: session.sessionId, type: mine === undefined ? "claim.acquired"
+          : "claim.renewed", occurredAt: now,
+        payload: { claimId, resource, mode: record.mode } });
+    }, { kinds: ["claim"] });
+    return record;
+  }
+
+  async function renewClaim(input) {
+    const session = await requireOwner(input, "renew");
+    const now = clock.now();
+    const expiresAt = new Date(Date.parse(now) + (input.leaseSeconds ?? 1800) * 1000)
+      .toISOString();
+    let record = null;
+    await store.transaction(async tx => {
+      const existing = tx.get("claim", input.claimId);
+      if (existing === null || existing.ownerSessionId !== session.sessionId) {
+        throw new AccError(EXIT.CONFLICT, "only the owning session generation may renew a claim",
+          { claimId: input.claimId });
+      }
+      record = { ...existing, expiresAt, generation: ids.next("generation") };
+      tx.put("claim", input.claimId, record, tx.generationOf("claim", input.claimId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: existing.workspaceId, actorSessionId: session.sessionId,
+        type: "claim.renewed", occurredAt: now, payload: { claimId: input.claimId } });
+    }, { kinds: ["claim"] });
+    return record;
+  }
+
+  async function removeClaim(input, { authority, reason }) {
+    const session = await requireOwner(input, "release");
+    const now = clock.now();
+    await store.transaction(async tx => {
+      const existing = tx.get("claim", input.claimId);
+      if (existing === null) {
+        throw new AccError(EXIT.CONFLICT, "the claim does not exist", { claimId: input.claimId });
+      }
+      const owned = existing.ownerSessionId === session.sessionId;
+      // Force release is an authority decision, not a peer decision. A
+      // coordinator lease does not extend outside its own workstream.
+      if (!owned && authority !== "human" && authority !== "policy") {
+        throw new AccError(EXIT.CONFLICT,
+          "force release requires human or policy authority",
+          { claimId: input.claimId, authority: authority ?? null });
+      }
+      // The claim record is removed rather than tombstoned: a released claim is
+      // not a claim, and every consumer of a snapshot would otherwise have to
+      // re-derive liveness. The event log keeps the history.
+      tx.remove("claim", input.claimId, tx.generationOf("claim", input.claimId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: existing.workspaceId, actorSessionId: session.sessionId,
+        type: owned ? "claim.released" : "claim.force_released", occurredAt: now,
+        payload: { claimId: input.claimId, authority: authority ?? null,
+          reason: reason ?? null, replacedGeneration: existing.generation } });
+    }, { kinds: ["claim"] });
+  }
+
+  return {
+    acquireClaim,
+    renewClaim,
+    releaseClaim: input => removeClaim(input, { authority: null, reason: null }),
+    forceReleaseClaim: input => removeClaim(input,
+      { authority: input.authority, reason: input.reason }),
+  };
+}