agentic-comments 0.2.0 → 0.4.0

package/README.md

@@ -11,7 +11,7 @@ Comment threads and suggestions anchored to any content, from people and agents.
 
 ## Install
 
-Requires Node.js 20 or later. `yjs` is a peer dependency. Your app and this package must use the same
+Requires Node.js 22 or later. `yjs` is a peer dependency. Your app and this package must use the same
 copy of `yjs`, because the package checks the Yjs types of your document. Install both:
 
 ```sh
@@ -55,6 +55,33 @@ normal sync, and every replica sees the same threads.
 - A malformed thread from a bad replica is skipped. A bad message is left out, and `skipped` on the
   thread counts those. `problems()` names them.
 
+## Anchors for plain text
+
+`agentic-comments/anchor` pins a range of a plain string. It needs no Yjs and no framework.
+Offsets are UTF-16 code units, like `slice`.
+
+```ts
+import { createAnchor, resolveAnchor } from "agentic-comments/anchor";
+
+const anchor = createAnchor("Hello brave world", 6, 11);
+const edits = [{ from: 0, to: 0, insert: "Oh, " }];
+resolveAnchor(anchor, "Oh, Hello brave world", edits, 17);
+// { state: "attached", from: 10, to: 15, method: "mapped" }
+```
+
+- An edit is `{ from, to, insert }`. Edits apply one after another, each in the text left by the one before.
+- `resolveAnchor(anchor, newText, edits?, originalLength?)` maps the range through the edits. Pass
+  `originalLength`, the length of the old text, so it can check that the edits fit both texts.
+- With edits, the edits are the truth, and the quote is not searched. A range that holds other text is `edited`.
+- With no edits, it searches for the quote. One match wins. With many, the best fit of the text around the
+  quote wins. On a tie, the match at the old offsets wins, or else the anchor is `orphaned`, because a wrong
+  place is worse than none. More than 500 matches orphan too.
+- `edited` means the range exists but holds other text. `orphaned` means the content is gone, the quote is ambiguous, the edits do not fit the text, or the anchor is bad data.
+- An insert at an edge of the range stays outside it. Deleting the whole range orphans it.
+- `createAnchor` throws a `RangeError` for an empty range, a range outside the text, or a range that cuts a
+  surrogate pair in two. It does not check grapheme boundaries, so a flag or a joined emoji can still be cut.
+- `mapPosition` and `mapRange` move offsets through edits on their own.
+
 ## When the content changes
 
 Every thread and suggestion has an `anchorState`:
@@ -170,6 +197,69 @@ npx agentic-comments accept <id>
   `{"value": <JSON>}`.
 - From code: `import { FileStore, CommentsService, operatorActor } from "agentic-comments/local"`.
 
+## HTTP API
+
+`agentic-comments/worker` is a Cloudflare Worker (Hono) with REST routes under `/api/v1`. It keeps each
+document in a D1 database through the `Store` port of `agentic-identity`. It checks every request with the
+`Auth` port, so the host picks who the caller is and no request carries an author.
+
+Set the principals as a secret. It is JSON from a bearer token (32 bytes or more) to `kind:name`, or to
+`{ "as": "kind:name", "scopes": [...] }`. One bad entry refuses the whole table. A request with no valid
+token gets `401`.
+
+```sh
+wrangler secret put AGENTIC_COMMENTS_TOKENS
+# {"<openssl rand -hex 32>": {"as": "human:ada", "scopes": ["comments:write"]}, "<another>": "agent_of_human:scribe"}
+```
+
+Also set `AGENTIC_COMMENTS_REGION` to `eu` or `us`. Without it every document route fails with `500 MISCONFIGURED`. Use `unknown` with
+`AGENTIC_COMMENTS_UNSAFE_REGION=1` only under `wrangler dev`. The `wrangler.jsonc` in the repo shows the D1 binding.
+
+| Scope | Allows |
+| --- | --- |
+| `comments:read` | Read documents, threads, and suggestions. |
+| `comments:comment` | Also add threads, reply, resolve, reopen, and suggest. This is the default for a token with no scopes. |
+| `comments:write` | Also create documents, relocate, and accept or reject. |
+| `comments:admin` | Also let an agent accept or reject (the `comments:accept` right). |
+
+| Route | Action |
+| --- | --- |
+| `GET /api/v1/me` | Who the token stands for. |
+| `POST /api/v1/docs` `{id, text?}` | Create a document. |
+| `GET /api/v1/docs/:doc` | Read the content text. |
+| `GET`, `POST /api/v1/docs/:doc/threads` | List (`?status=`, `?anchorState=`, `?mentioning=`) or add. |
+| `GET /api/v1/docs/:doc/threads/:id` | Read one thread. |
+| `POST /api/v1/docs/:doc/threads/:id/replies` | Reply. |
+| `POST .../threads/:id/resolve`, `reopen`, `relocate` | Change a thread. |
+| `GET`, `POST /api/v1/docs/:doc/suggestions` | List or suggest. |
+| `POST .../suggestions/:id/accept`, `reject` | Decide. An agent never decides its own suggestion. |
+
+Bodies are the same as the MCP tool inputs. An error is `{"error": {"code", "message"}}`. A body with an
+`author` key is refused with `400`.
+
+```sh
+curl -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
+  -d '{"anchor":{"type":"text","quote":"brave"},"body":"Word choice?"}' \
+  http://127.0.0.1:8787/api/v1/docs/d1/threads
+```
+
+## Live demo
+
+A demo Worker runs at <https://agentic-comments-demo.hello-fd1.workers.dev>. It is a staging site. Check it with
+`GET /health`. Every `/api/v1` route needs a bearer token, and the demo does not publish one, so a call
+with no token gets `401`. The data lives in a D1 database in the EU (`weur`), and the Worker sets the
+region to `eu`.
+
+To deploy your own copy, log in with `wrangler login` or set `CLOUDFLARE_API_TOKEN`, then:
+
+```sh
+npx wrangler d1 create agentic-comments-demo --location weur   # once. Put the id in wrangler.demo.jsonc.
+npx wrangler secret put AGENTIC_COMMENTS_TOKENS --config wrangler.demo.jsonc   # see HTTP API
+npm run deploy:demo
+```
+
+`wrangler.demo.jsonc` sets no secret. Deploys run by hand, and no CI job holds a Cloudflare token.
+
 ## Notifications
 
 `Notifications` turns changes into events that your app can send to a notifier. It watches the data, so it
@@ -225,7 +315,7 @@ const stop = notifications.subscribe(async (event) => {
 
 ## Limits
 
-- No HTTP API yet. The file store is for one machine. It is not a sync server.
+- The file store is for one machine. It is not a sync server. The Worker keeps each document as one D1 row and refuses a document past 600,000 bytes of state.
 - `add` checks that a text anchor points into this document and matches its quote.
 - The library trusts the host to call `stamp()` only for a principal it authenticated.
 - A reply to a resolved thread is refused on the replica that sees the resolve. A reply and a

package/dist/anchoring.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Plain-text anchors that survive edits. No Yjs, no framework. Offsets are UTF-16 code units, like
+ * `String.prototype.slice`. An anchor keeps its quote and some text around it, so it can be found again
+ * when you have no edit list.
+ */
+/** One edit: replace `text.slice(from, to)` with `insert`. A pure insert has `from === to`. */
+interface Edit {
+    from: number;
+    to: number;
+    insert: string;
+}
+interface TextRangeAnchor {
+    /** The text under the range when the anchor was made. */
+    quote: string;
+    /** Text just before the range. */
+    prefix: string;
+    /** Text just after the range. */
+    suffix: string;
+    /** The range at creation, in the text it was made for. */
+    from: number;
+    to: number;
+}
+interface OffsetRange {
+    from: number;
+    to: number;
+}
+/**
+ * `attached`: the range holds the quote. `edited`: the range still exists but holds other text.
+ * `orphaned`: the content is gone, or the quote is too ambiguous to trust.
+ */
+type Resolution = {
+    state: "attached";
+    from: number;
+    to: number;
+    method: "mapped" | "quote";
+} | {
+    state: "edited";
+    from: number;
+    to: number;
+} | {
+    state: "orphaned";
+};
+declare const CONTEXT_LENGTH = 32;
+declare const MAX_QUOTE_LENGTH = 2000;
+/** The most copies of a quote that `resolveAnchor` ranks. With more, the anchor is orphaned. */
+declare const MAX_MATCHES = 500;
+/** Pin the range `from..to` of `text`. Throws a `RangeError` when the range is empty, outside the text, or splits a character. */
+declare function createAnchor(text: string, from: number, to: number): TextRangeAnchor;
+/**
+ * Move one position through edits made one after another. `assoc` 1 puts a position that sits at an
+ * insert after the insert. `assoc` -1 puts it before. A position inside a replaced range moves to the
+ * end of the insert with `assoc` 1, and to the start of the insert with `assoc` -1. `length` is the text length before the first edit.
+ */
+declare function mapPosition(pos: number, edits: readonly Edit[], assoc?: 1 | -1, length?: number): number;
+/**
+ * Move a range through edits. An insert at either edge stays outside the range. Returns null when the
+ * edits delete the whole range.
+ */
+declare function mapRange(range: OffsetRange, edits: readonly Edit[], length?: number): OffsetRange | null;
+/**
+ * Find an anchor in `newText`.
+ *
+ * With `edits` (the changes from the text the anchor was made for to `newText`), the edits are the truth:
+ * the mapped range is `attached` if it holds the quote, `edited` if it holds other text, and `orphaned`
+ * if the edits delete it or it falls outside the text. The quote is not searched. Pass `originalLength`
+ * (the length of the old text) to also check that the edits fit both texts.
+ *
+ * With no edits, search for the quote. One match wins. With several, the match whose surrounding text
+ * fits best wins. On a tie, the match at the old offsets wins, else the anchor is `orphaned`: a wrong
+ * place is worse than none. A bad anchor, a half character, and too many matches also orphan.
+ */
+declare function resolveAnchor(anchor: TextRangeAnchor, newText: string, edits?: readonly Edit[], originalLength?: number): Resolution;
+
+export { CONTEXT_LENGTH, type Edit, MAX_MATCHES, MAX_QUOTE_LENGTH, type OffsetRange, type Resolution, type TextRangeAnchor, createAnchor, mapPosition, mapRange, resolveAnchor };

package/dist/anchoring.js

@@ -0,0 +1,122 @@
+// src/anchoring.ts
+var CONTEXT_LENGTH = 32;
+var MAX_QUOTE_LENGTH = 2e3;
+var MAX_MATCHES = 500;
+var isHigh = (c) => c >= 55296 && c <= 56319;
+var isLow = (c) => c >= 56320 && c <= 57343;
+var isLoneHalf = (code, atStart) => atStart ? isLow(code) : isHigh(code);
+function splits(text, index) {
+  return index > 0 && index < text.length && isHigh(text.charCodeAt(index - 1)) && isLow(text.charCodeAt(index));
+}
+var whole = (n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+function createAnchor(text, from, to) {
+  if (typeof text !== "string") throw new TypeError("text must be a string");
+  if (!whole(from) || !whole(to) || to <= from || to > text.length) {
+    throw new RangeError(`the range ${String(from)}..${String(to)} is not inside the text, which has ${text.length} characters`);
+  }
+  if (splits(text, from) || splits(text, to)) throw new RangeError("the range cuts a character in two");
+  if (isLow(text.charCodeAt(from)) || isHigh(text.charCodeAt(to - 1))) throw new RangeError("the range starts or ends inside a character");
+  if (to - from > MAX_QUOTE_LENGTH) throw new RangeError(`a quote holds up to ${MAX_QUOTE_LENGTH} characters`);
+  let before = Math.max(0, from - CONTEXT_LENGTH);
+  if (splits(text, before)) before += 1;
+  let after = Math.min(text.length, to + CONTEXT_LENGTH);
+  if (splits(text, after)) after -= 1;
+  return { quote: text.slice(from, to), prefix: text.slice(before, from), suffix: text.slice(to, after), from, to };
+}
+function checkEdit(edit, length) {
+  if (typeof edit !== "object" || edit === null) throw new RangeError("an edit must be an object");
+  if (!whole(edit.from) || !whole(edit.to) || edit.to < edit.from || edit.to > length || typeof edit.insert !== "string") {
+    throw new RangeError(`the edit ${JSON.stringify([edit.from, edit.to])} is not inside a text of ${length} characters`);
+  }
+}
+function mapPosition(pos, edits, assoc = 1, length = Infinity) {
+  if (!whole(pos) || !Array.isArray(edits) || assoc !== 1 && assoc !== -1) throw new RangeError("the position must be a whole number, the edits a list, and assoc 1 or -1");
+  if (length !== Infinity && (!whole(length) || pos > length)) throw new RangeError("the position must be inside a text of a whole length");
+  let len = length;
+  let p = pos;
+  for (const edit of edits) {
+    checkEdit(edit, len);
+    const removed = edit.to - edit.from;
+    const added = edit.insert.length;
+    if (p > edit.to) p += added - removed;
+    else if (p >= edit.from) {
+      if (removed === 0) p = assoc === 1 ? p + added : p;
+      else if (p === edit.from) p = edit.from;
+      else if (p === edit.to) p = edit.from + added;
+      else p = assoc === 1 ? edit.from + added : edit.from;
+    }
+    len = len === Infinity ? len : len - removed + added;
+  }
+  return p;
+}
+function mapRange(range, edits, length = Infinity) {
+  if (!Array.isArray(edits)) throw new RangeError("the edits must be a list");
+  if (!whole(range?.from) || !whole(range?.to) || range.to <= range.from) throw new RangeError("the range must be two whole numbers, from before to");
+  let { from, to } = range;
+  let len = length;
+  for (const edit of edits) {
+    from = mapPosition(from, [edit], 1, len);
+    to = mapPosition(to, [edit], -1, len);
+    if (to <= from) return null;
+    len = len === Infinity ? len : len - (edit.to - edit.from) + edit.insert.length;
+  }
+  return { from, to };
+}
+function occurrences(text, quote, max) {
+  const out = [];
+  for (let i = text.indexOf(quote); i >= 0 && out.length < max; i = text.indexOf(quote, i + 1)) out.push(i);
+  return out;
+}
+var commonSuffix = (a, b) => {
+  let n = 0;
+  while (n < a.length && n < b.length && a[a.length - 1 - n] === b[b.length - 1 - n]) n++;
+  return n;
+};
+var commonPrefix = (a, b) => {
+  let n = 0;
+  while (n < a.length && n < b.length && a[n] === b[n]) n++;
+  return n;
+};
+function resolveAnchor(anchor, newText, edits, originalLength) {
+  if (typeof newText !== "string") throw new TypeError("text must be a string");
+  if (typeof anchor?.quote !== "string" || anchor.quote === "") return { state: "orphaned" };
+  const quote = anchor.quote;
+  if (quote.length > MAX_QUOTE_LENGTH || edits !== void 0 && !Array.isArray(edits)) return { state: "orphaned" };
+  if (!whole(anchor.from) || !whole(anchor.to) || anchor.to - anchor.from !== quote.length) return { state: "orphaned" };
+  if (isLoneHalf(quote.charCodeAt(0), true) || isLoneHalf(quote.charCodeAt(quote.length - 1), false)) return { state: "orphaned" };
+  if (originalLength !== void 0) {
+    const final = (edits ?? []).reduce((n, e) => n - (e?.to - e?.from) + (typeof e?.insert === "string" ? e.insert.length : NaN), originalLength);
+    if (!whole(originalLength) || anchor.to > originalLength || edits && final !== newText.length) return { state: "orphaned" };
+  }
+  let mapped;
+  try {
+    mapped = edits ? mapRange({ from: anchor.from, to: anchor.to }, edits, originalLength) : { from: anchor.from, to: anchor.to };
+  } catch (error) {
+    if (error instanceof RangeError) return { state: "orphaned" };
+    throw error;
+  }
+  if (edits && mapped === null) return { state: "orphaned" };
+  const valid = mapped && mapped.to <= newText.length && !splits(newText, mapped.from) && !splits(newText, mapped.to);
+  if (edits) {
+    if (!valid || !mapped) return { state: "orphaned" };
+    return newText.slice(mapped.from, mapped.to) === quote ? { state: "attached", from: mapped.from, to: mapped.to, method: "mapped" } : { state: "edited", from: mapped.from, to: mapped.to };
+  }
+  const found = occurrences(newText, quote, MAX_MATCHES + 1).filter((at) => !splits(newText, at) && !splits(newText, at + quote.length));
+  if (found.length === 0 || found.length > MAX_MATCHES) return { state: "orphaned" };
+  const result = (at) => ({ state: "attached", from: at, to: at + quote.length, method: at === anchor.from ? "mapped" : "quote" });
+  if (found.length === 1) return result(found[0]);
+  const score = (at) => commonSuffix(anchor.prefix ?? "", newText.slice(Math.max(0, at - CONTEXT_LENGTH), at)) + commonPrefix(anchor.suffix ?? "", newText.slice(at + quote.length, at + quote.length + CONTEXT_LENGTH));
+  const ranked = found.map((at) => ({ at, score: score(at) })).sort((a, b) => b.score - a.score);
+  const best = ranked.filter((r) => r.score === ranked[0].score);
+  if (best.length === 1) return result(best[0].at);
+  return best.some((r) => r.at === anchor.from) ? result(anchor.from) : { state: "orphaned" };
+}
+export {
+  CONTEXT_LENGTH,
+  MAX_MATCHES,
+  MAX_QUOTE_LENGTH,
+  createAnchor,
+  mapPosition,
+  mapRange,
+  resolveAnchor
+};

package/dist/{chunk-C3P5TAC3.js → chunk-BSNBDKR2.js}

@@ -114,7 +114,7 @@ function onlyOccurrence(type, quote) {
 }
 
 // src/principal.ts
-var PRINCIPAL_KINDS = ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
+import { PRINCIPAL_KINDS } from "agentic-identity";
 var MAX_NAME = 128;
 var issued = /* @__PURE__ */ new WeakSet();
 var Actor = class _Actor {
@@ -158,9 +158,6 @@ function authorLabel(author) {
   return author.kind === "human" ? "person" : author.kind === "user_token" ? "person via agent" : "agent";
 }
 
-// src/suggestions.ts
-import * as Y2 from "yjs";
-
 // src/validate.ts
 var invalid = (message) => {
   throw new CommentsError("INVALID_INPUT", message);
@@ -182,6 +179,7 @@ var strictCopy = (value) => JSON.parse(
 );
 
 // src/suggestions.ts
+import * as Y2 from "yjs";
 var ACCEPT_SCOPE = "comments:accept";
 var MAX_CHANGE = 64e3;
 var MAX_RECEIPT = 16e3;

package/dist/{chunk-RWMBGIAS.js → chunk-DRACF66Y.js}

@@ -1,6 +1,6 @@
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.2.0" : readPackageVersion();
+var VERSION = true ? "0.4.0" : readPackageVersion();
 
 export {
   VERSION

package/dist/{chunk-C43HLFQE.js → chunk-HXXJNFEO.js}

@@ -2,7 +2,7 @@ import {
   CommentsError,
   PRINCIPAL_KINDS,
   stamp
-} from "./chunk-C3P5TAC3.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/file-store.ts
 import { createHash } from "crypto";

package/dist/{chunk-ZCM2UDLN.js → chunk-NQWRFKJ6.js}

@@ -7,7 +7,7 @@ import {
   textAnchor,
   textOf,
   textRange
-} from "./chunk-C3P5TAC3.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/local-host.ts
 import * as Y from "yjs";

package/dist/{chunk-UE5ULEXU.js → chunk-R4LH36VG.js}

@@ -1,12 +1,12 @@
 import {
   VERSION
-} from "./chunk-RWMBGIAS.js";
+} from "./chunk-DRACF66Y.js";
 import {
   CommentsService
-} from "./chunk-ZCM2UDLN.js";
+} from "./chunk-NQWRFKJ6.js";
 import {
   CommentsError
-} from "./chunk-C3P5TAC3.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/cli.js

@@ -3,17 +3,17 @@ import {
   FileStore,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-C43HLFQE.js";
+} from "./chunk-HXXJNFEO.js";
 import {
   VERSION
-} from "./chunk-RWMBGIAS.js";
+} from "./chunk-DRACF66Y.js";
 import {
   CommentsService,
   TEXT_ROOT
-} from "./chunk-ZCM2UDLN.js";
+} from "./chunk-NQWRFKJ6.js";
 import {
   CommentsError
-} from "./chunk-C3P5TAC3.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/cli.ts
 import { readFileSync, realpathSync } from "fs";
@@ -155,7 +155,7 @@ async function runCli(argv, io) {
       return 0;
     }
     if (p.command === "mcp") {
-      const { startMcp } = await import("./mcp-BOJM5NE6.js");
+      const { startMcp } = await import("./mcp-ACC4QIEM.js");
       await startMcp(store, operatorActor(p.flags["--as"] ?? io.env.AGENTIC_COMMENTS_AS, io.env.AGENTIC_COMMENTS_SCOPES));
       return 0;
     }

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-import { A as Author, C as Comments, S as Suggestions } from './suggestions-U8tXRLZ5.js';
-export { a as ACCEPT_SCOPE, b as Actor, c as Anchor, d as AnchorKind, e as AnchorState, f as ApplyContext, g as CanvasAnchor, h as CellAnchor, i as CommentsOptions, M as Message, N as NewReply, j as NewSuggestion, k as NewThread, P as PRINCIPAL_KINDS, l as PrincipalKind, R as RelativePositionJson, m as RevertContext, n as SlideAnchor, o as StampInput, p as Suggestion, q as SuggestionFilter, r as SuggestionHost, T as TextAnchor, s as Thread, t as ThreadFilter, u as authorLabel, v as stamp, w as textAnchor, x as textOf } from './suggestions-U8tXRLZ5.js';
+import { a as Author, C as Comments, b as Suggestions } from './suggestions-oj8fd-nG.js';
+export { c as ACCEPT_SCOPE, A as Actor, d as Anchor, e as AnchorKind, f as AnchorState, g as ApplyContext, h as CanvasAnchor, i as CellAnchor, j as CommentsOptions, M as Message, N as NewReply, k as NewSuggestion, l as NewThread, R as RelativePositionJson, m as RevertContext, n as SlideAnchor, o as StampInput, S as Suggestion, p as SuggestionFilter, q as SuggestionHost, r as TextAnchor, T as Thread, s as ThreadFilter, t as authorLabel, u as stamp, v as textAnchor, w as textOf } from './suggestions-oj8fd-nG.js';
+export { PRINCIPAL_KINDS, PrincipalKind } from 'agentic-identity';
 import 'yjs';
 
 declare const VERSION: string;
 
-type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED" | "STORE_MISSING" | "STORE_EXISTS" | "STORE_CORRUPT" | "STORE_LOCKED" | "STORE_FULL" | "USAGE";
+type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED" | "STORE_MISSING" | "STORE_EXISTS" | "STORE_CORRUPT" | "STORE_LOCKED" | "STORE_FULL" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "CONFLICT" | "MISCONFIGURED" | "USAGE";
 declare class CommentsError extends Error {
     readonly code: CommentsErrorCode;
     constructor(code: CommentsErrorCode, message: string);

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-RWMBGIAS.js";
+} from "./chunk-DRACF66Y.js";
 import {
   ACCEPT_SCOPE,
   Actor,
@@ -14,7 +14,7 @@ import {
   textAnchor,
   textOf,
   validDate
-} from "./chunk-C3P5TAC3.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/notifications.ts
 import * as Y from "yjs";

package/dist/local.d.ts

@@ -1,5 +1,7 @@
 import * as Y from 'yjs';
-import { b as Actor, s as Thread, M as Message, p as Suggestion, r as SuggestionHost } from './suggestions-U8tXRLZ5.js';
+export { A as AnchorSpec, C as CommentsService, L as ListFilter } from './service-Dxw9TVxY.js';
+import { q as SuggestionHost, A as Actor } from './suggestions-oj8fd-nG.js';
+import 'agentic-identity';
 
 /** The most bytes a saved document holds. A save over this is refused, so a file never grows past what a load accepts. */
 declare const MAX_FILE: number;
@@ -35,63 +37,6 @@ declare class FileStore {
     write<T>(fn: (ydoc: Y.Doc) => T): T;
 }
 
-/** Where a comment or suggestion points, in terms a person or agent can write down. */
-type AnchorSpec = {
-    type: "text";
-    quote: string;
-    occurrence?: number;
-} | {
-    type: "cell";
-    key: string;
-} | {
-    type: "slide";
-    elementId: string;
-} | {
-    type: "canvas";
-    elementId: string;
-};
-interface ListFilter {
-    status?: string;
-    anchorState?: string;
-    mentioning?: string;
-}
-/**
- * Every action the CLI and MCP server offer, on a local file store. Each call takes the actor the operator
- * stamped, and no input carries an author, so both faces return the same shapes and obey the same rules.
- */
-declare class CommentsService {
-    private readonly store;
-    private readonly actor;
-    constructor(store: FileStore, actor: Actor);
-    private open;
-    private read;
-    private write;
-    threads(filter?: ListFilter): Thread[];
-    thread(id: string): Thread;
-    comment(input: {
-        anchor: AnchorSpec;
-        body: string;
-        mentions?: string[];
-    }): Thread;
-    reply(threadId: string, input: {
-        body: string;
-        mentions?: string[];
-    }): Message;
-    resolve(threadId: string): Thread;
-    reopen(threadId: string): Thread;
-    relocate(threadId: string): Thread;
-    suggestions(filter?: ListFilter): Suggestion[];
-    suggest(input: {
-        anchor: AnchorSpec;
-        change: unknown;
-        summary?: string;
-    }): Suggestion;
-    accept(suggestionId: string): Suggestion;
-    reject(suggestionId: string): Suggestion;
-    /** The content text of the store. */
-    text(): string;
-}
-
 /** The root Y.Text that a local store keeps its content in. */
 declare const TEXT_ROOT = "text";
 /** The root Y.Map that holds values for cell, slide, canvas, and custom anchors. */
@@ -109,4 +54,4 @@ declare const localHost: SuggestionHost;
  */
 declare function operatorActor(as: string | undefined, scopes: string | undefined): Actor;
 
-export { type AnchorSpec, CommentsService, FileStore, type FileStoreOptions, type ListFilter, MAX_FILE, TEXT_ROOT, VALUES_ROOT, localHost, lockTimeoutFrom, operatorActor };
+export { FileStore, type FileStoreOptions, MAX_FILE, TEXT_ROOT, VALUES_ROOT, localHost, lockTimeoutFrom, operatorActor };

package/dist/local.js

@@ -3,14 +3,14 @@ import {
   MAX_FILE,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-C43HLFQE.js";
+} from "./chunk-HXXJNFEO.js";
 import {
   CommentsService,
   TEXT_ROOT,
   VALUES_ROOT,
   localHost
-} from "./chunk-ZCM2UDLN.js";
-import "./chunk-C3P5TAC3.js";
+} from "./chunk-NQWRFKJ6.js";
+import "./chunk-BSNBDKR2.js";
 export {
   CommentsService,
   FileStore,

package/dist/mcp-ACC4QIEM.js

@@ -0,0 +1,11 @@
+import {
+  createMcpServer,
+  startMcp
+} from "./chunk-R4LH36VG.js";
+import "./chunk-DRACF66Y.js";
+import "./chunk-NQWRFKJ6.js";
+import "./chunk-BSNBDKR2.js";
+export {
+  createMcpServer,
+  startMcp
+};

package/dist/mcp-bin.js

@@ -3,19 +3,38 @@ import {
   FileStore,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-C43HLFQE.js";
+} from "./chunk-HXXJNFEO.js";
 import {
   startMcp
-} from "./chunk-UE5ULEXU.js";
-import "./chunk-RWMBGIAS.js";
-import "./chunk-ZCM2UDLN.js";
-import "./chunk-C3P5TAC3.js";
+} from "./chunk-R4LH36VG.js";
+import {
+  VERSION
+} from "./chunk-DRACF66Y.js";
+import "./chunk-NQWRFKJ6.js";
+import "./chunk-BSNBDKR2.js";
 
 // src/mcp-bin.ts
-try {
-  const env = process.env;
-  await startMcp(new FileStore(env.AGENTIC_COMMENTS_FILE ?? "./comments.ydoc", { lockTimeoutMs: lockTimeoutFrom(env) }), operatorActor(env.AGENTIC_COMMENTS_AS, env.AGENTIC_COMMENTS_SCOPES));
-} catch (error) {
-  console.error(JSON.stringify({ error: { code: error.code ?? "INTERNAL", message: error instanceof Error ? error.message : String(error) } }));
-  process.exit(1);
+var MCP_HELP = `agentic-comments-mcp ${VERSION}
+
+Start the MCP server on stdio. Set the principal and scopes in the environment:
+
+  AGENTIC_COMMENTS_AS=kind:name           Required. For example agent_of_human:scribe.
+  AGENTIC_COMMENTS_SCOPES=a,b             Optional. A comma list, such as comments:accept.
+  AGENTIC_COMMENTS_FILE=./comments.ydoc   The store file. The default is ./comments.ydoc.
+  AGENTIC_COMMENTS_LOCK_TIMEOUT_MS=5000   How long a write waits for another process.
+
+Usage: agentic-comments-mcp [--help | --version]`;
+var args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(MCP_HELP);
+} else if (args.includes("--version") || args.includes("-v")) {
+  console.log(VERSION);
+} else {
+  try {
+    const env = process.env;
+    await startMcp(new FileStore(env.AGENTIC_COMMENTS_FILE ?? "./comments.ydoc", { lockTimeoutMs: lockTimeoutFrom(env) }), operatorActor(env.AGENTIC_COMMENTS_AS, env.AGENTIC_COMMENTS_SCOPES));
+  } catch (error) {
+    console.error(JSON.stringify({ error: { code: error.code ?? "INTERNAL", message: error instanceof Error ? error.message : String(error) } }));
+    process.exit(1);
+  }
 }

package/dist/service-Dxw9TVxY.d.ts

@@ -0,0 +1,66 @@
+import * as Y from 'yjs';
+import { A as Actor, T as Thread, M as Message, S as Suggestion } from './suggestions-oj8fd-nG.js';
+
+/** Where a comment or suggestion points, in terms a person or agent can write down. */
+type AnchorSpec = {
+    type: "text";
+    quote: string;
+    occurrence?: number;
+} | {
+    type: "cell";
+    key: string;
+} | {
+    type: "slide";
+    elementId: string;
+} | {
+    type: "canvas";
+    elementId: string;
+};
+/** Where a service reads and writes its document: a file store, or a document the host loaded. */
+interface YStore {
+    read<T>(fn: (ydoc: Y.Doc) => T): T;
+    write<T>(fn: (ydoc: Y.Doc) => T): T;
+}
+interface ListFilter {
+    status?: string;
+    anchorState?: string;
+    mentioning?: string;
+}
+/**
+ * Every action the CLI and MCP server offer, on a local file store. Each call takes the actor the operator
+ * stamped, and no input carries an author, so both faces return the same shapes and obey the same rules.
+ */
+declare class CommentsService {
+    private readonly store;
+    private readonly actor;
+    constructor(store: YStore, actor: Actor);
+    private open;
+    private read;
+    private write;
+    threads(filter?: ListFilter): Thread[];
+    thread(id: string): Thread;
+    comment(input: {
+        anchor: AnchorSpec;
+        body: string;
+        mentions?: string[];
+    }): Thread;
+    reply(threadId: string, input: {
+        body: string;
+        mentions?: string[];
+    }): Message;
+    resolve(threadId: string): Thread;
+    reopen(threadId: string): Thread;
+    relocate(threadId: string): Thread;
+    suggestions(filter?: ListFilter): Suggestion[];
+    suggest(input: {
+        anchor: AnchorSpec;
+        change: unknown;
+        summary?: string;
+    }): Suggestion;
+    accept(suggestionId: string): Suggestion;
+    reject(suggestionId: string): Suggestion;
+    /** The content text of the store. */
+    text(): string;
+}
+
+export { type AnchorSpec as A, CommentsService as C, type ListFilter as L };

package/dist/{suggestions-U8tXRLZ5.d.ts → suggestions-oj8fd-nG.d.ts}

@@ -1,4 +1,5 @@
 import * as Y from 'yjs';
+import { PrincipalKind } from 'agentic-identity';
 
 /** A Yjs relative position as JSON. It names an item, not an index, so it follows its text. */
 interface RelativePositionJson {
@@ -65,8 +66,6 @@ declare function textOf(type: Y.Text | Y.XmlText): string;
 /** Pin a range of a Yjs text. Later edits by any replica do not move the anchor off its text. */
 declare function textAnchor(type: Y.Text | Y.XmlText, from: number, to: number): TextAnchor;
 
-declare const PRINCIPAL_KINDS: readonly ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
-type PrincipalKind = (typeof PRINCIPAL_KINDS)[number];
 /** What a thread keeps about who wrote a message. Scopes never reach storage. */
 interface Author {
     kind: PrincipalKind;
@@ -331,4 +330,4 @@ declare class Suggestions {
     settle(): void;
 }
 
-export { type Author as A, Comments as C, type Message as M, type NewReply as N, PRINCIPAL_KINDS as P, type RelativePositionJson as R, Suggestions as S, type TextAnchor as T, ACCEPT_SCOPE as a, Actor as b, type Anchor as c, type AnchorKind as d, type AnchorState as e, type ApplyContext as f, type CanvasAnchor as g, type CellAnchor as h, type CommentsOptions as i, type NewSuggestion as j, type NewThread as k, type PrincipalKind as l, type RevertContext as m, type SlideAnchor as n, type StampInput as o, type Suggestion as p, type SuggestionFilter as q, type SuggestionHost as r, type Thread as s, type ThreadFilter as t, authorLabel as u, stamp as v, textAnchor as w, textOf as x };
+export { Actor as A, Comments as C, type Message as M, type NewReply as N, type RelativePositionJson as R, type Suggestion as S, type Thread as T, type Author as a, Suggestions as b, ACCEPT_SCOPE as c, type Anchor as d, type AnchorKind as e, type AnchorState as f, type ApplyContext as g, type CanvasAnchor as h, type CellAnchor as i, type CommentsOptions as j, type NewSuggestion as k, type NewThread as l, type RevertContext as m, type SlideAnchor as n, type StampInput as o, type SuggestionFilter as p, type SuggestionHost as q, type TextAnchor as r, type ThreadFilter as s, authorLabel as t, stamp as u, textAnchor as v, textOf as w };

package/dist/worker.d.ts

@@ -0,0 +1,58 @@
+import { Hono } from 'hono';
+import { Auth, Store, PrincipalContext, Region } from 'agentic-identity';
+import { D1Like } from 'agentic-identity/cloudflare';
+import { A as Actor } from './suggestions-oj8fd-nG.js';
+import { C as CommentsService } from './service-Dxw9TVxY.js';
+import 'yjs';
+
+interface WorkerEnv {
+    /** Where the data lives: "eu" or "us". It is a claim you make at deploy time, with no default. "unknown" needs `AGENTIC_COMMENTS_UNSAFE_REGION=1` too. */
+    AGENTIC_COMMENTS_REGION?: string;
+    /** Set to "1" to accept the region "unknown" under `wrangler dev`. Never set it in production. */
+    AGENTIC_COMMENTS_UNSAFE_REGION?: string;
+    /** D1 database: each document, with its threads, as a Yjs update. */
+    DB?: D1Like;
+    /**
+     * JSON object: bearer token (32 bytes or more) to `kind:name`, or to `{ "as": "kind:name", "scopes": ["comments:write"] }`.
+     * Set it as a secret. A short token or a bad entry refuses the whole config.
+     */
+    AGENTIC_COMMENTS_TOKENS?: string;
+}
+/**
+ * An `Auth` over a table of bearer tokens. One bad entry (a token under 32 bytes, a value that is not a valid principal)
+ * refuses the whole table, so a typo never leaves a weak token live. The compare visits every entry.
+ */
+declare function createTokenAuth(raw: string | undefined): Auth;
+/** The documents, on the `Store` port. Each write loads the document, runs the change, and saves in one transaction. */
+declare class CommentsDocs {
+    private readonly store;
+    constructor(store: Store);
+    private id;
+    private load;
+    private open;
+    create(id: string, text: string, actor: Actor): Promise<void>;
+    read<T>(id: string, actor: Actor, run: (service: CommentsService) => T): Promise<T>;
+    write<T>(id: string, actor: Actor, run: (service: CommentsService) => T): Promise<T>;
+}
+/** The docs, or a function that makes them from the Worker bindings. */
+type DocsSource = CommentsDocs | ((env: WorkerEnv) => Promise<CommentsDocs>);
+interface AppOptions {
+    /** The credential check. The default reads `AGENTIC_COMMENTS_TOKENS`. Pass any `Auth` from agentic-identity to replace it. */
+    auth?: Auth | ((env: WorkerEnv) => Auth);
+}
+type AppEnv = {
+    Bindings: WorkerEnv;
+    Variables: {
+        context: PrincipalContext;
+    };
+};
+declare function createApp(source: DocsSource, options?: AppOptions): Hono<AppEnv>;
+/** The region claim, or a MISCONFIGURED error. */
+declare function regionOf(env: WorkerEnv): Region;
+/** The documents over D1. */
+declare function docsFor(env: WorkerEnv): Promise<CommentsDocs>;
+declare const _default: {
+    fetch: (request: Request, env: WorkerEnv, ctx: unknown) => Response | Promise<Response>;
+};
+
+export { type AppOptions, CommentsDocs, type DocsSource, type WorkerEnv, createApp, createTokenAuth, _default as default, docsFor, regionOf };

package/dist/worker.js

@@ -0,0 +1,287 @@
+import {
+  CommentsService,
+  TEXT_ROOT
+} from "./chunk-NQWRFKJ6.js";
+import {
+  ACCEPT_SCOPE,
+  CommentsError,
+  PRINCIPAL_KINDS,
+  exact,
+  invalid,
+  stamp
+} from "./chunk-BSNBDKR2.js";
+
+// src/worker.ts
+import { Hono } from "hono";
+import { StoreConflictError, assertRegion, isScope, parseRegion, hasScope } from "agentic-identity";
+import { D1_SCHEMA, createD1Store } from "agentic-identity/cloudflare";
+import * as Y from "yjs";
+var READ = "comments:read";
+var COMMENT = "comments:comment";
+var WRITE = "comments:write";
+var ADMIN = "comments:admin";
+var DEFAULT_SCOPES = [COMMENT];
+var MIN_TOKEN_BYTES = 32;
+var warned = /* @__PURE__ */ new Set();
+function refuse(reason) {
+  if (!warned.has(reason)) {
+    warned.add(reason);
+    console.error(`AGENTIC_COMMENTS_TOKENS is refused: ${reason}`);
+  }
+  return void 0;
+}
+function same(a, b) {
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  return diff === 0;
+}
+function contextOf(entry) {
+  const object = typeof entry === "object" && entry !== null && !Array.isArray(entry) ? entry : void 0;
+  const who = typeof entry === "string" ? entry : object?.as;
+  const cut = typeof who === "string" ? who.indexOf(":") : -1;
+  if (typeof who !== "string" || cut < 1 || cut === who.length - 1) return void 0;
+  const kind = who.slice(0, cut);
+  const name = who.slice(cut + 1);
+  if (!PRINCIPAL_KINDS.includes(kind)) return void 0;
+  const given = object?.scopes;
+  if (given !== void 0 && !(Array.isArray(given) && given.every(isScope))) return void 0;
+  try {
+    stamp({ kind, name });
+  } catch {
+    return void 0;
+  }
+  return { principalId: name, kind, chain: [{ id: name, kind }], scopes: given ?? [...DEFAULT_SCOPES] };
+}
+function createTokenAuth(raw) {
+  let table;
+  try {
+    const parsed = JSON.parse(raw ?? "{}");
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { authenticate: async () => (refuse("not a JSON object"), null) };
+    table = /* @__PURE__ */ new Map();
+    for (const [token, entry] of Object.entries(parsed)) {
+      const context = contextOf(entry);
+      if (new TextEncoder().encode(token).length < MIN_TOKEN_BYTES) throw new Error(`a token is shorter than ${MIN_TOKEN_BYTES} bytes`);
+      if (!context) throw new Error("an entry is not a valid kind:name or { as, scopes }");
+      table.set(token, context);
+    }
+  } catch (error) {
+    table = void 0;
+    refuse(error instanceof SyntaxError ? "not valid JSON" : error.message);
+  }
+  const known = table;
+  return {
+    async authenticate(request) {
+      const bearer = /^Bearer (.+)$/.exec(request.headers.get("authorization") ?? "")?.[1];
+      if (bearer === void 0 || !known) return null;
+      let found = null;
+      for (const [token, context] of known) if (same(token, bearer)) found = context;
+      return found;
+    }
+  };
+}
+function actorOf(context) {
+  const scopes = hasScope(context.scopes, ADMIN) ? [ACCEPT_SCOPE] : [];
+  return stamp({ kind: context.kind, name: context.principalId, scopes });
+}
+var DOCS = "comments_docs";
+var DOC_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+var MAX_STATE = 6e5;
+var MAX_BODY = 256 * 1024;
+var toBase64 = (bytes) => {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 32768) out += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(out);
+};
+var fromBase64 = (text) => Uint8Array.from(atob(text), (ch) => ch.charCodeAt(0));
+var CommentsDocs = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  id(id) {
+    if (!DOC_ID.test(id)) invalid(`invalid document id "${id}": use 1 to 64 of a-z, 0-9, "-" and "_"`);
+    return id;
+  }
+  load(row, id) {
+    if (row === null) throw new CommentsError("NO_DOCUMENT", `no document with id "${id}"`);
+    const ydoc = new Y.Doc();
+    try {
+      if (typeof row.state !== "string") throw new Error("no state");
+      Y.applyUpdate(ydoc, fromBase64(row.state));
+    } catch {
+      throw new CommentsError("CORRUPT", `document "${id}" is damaged`);
+    }
+    return ydoc;
+  }
+  open(ydoc, actor) {
+    const fixed = { read: (fn) => fn(ydoc), write: (fn) => fn(ydoc) };
+    return new CommentsService(fixed, actor);
+  }
+  async create(id, text, actor) {
+    this.id(id);
+    const ydoc = new Y.Doc();
+    ydoc.getText(TEXT_ROOT).insert(0, text);
+    const state = Y.encodeStateAsUpdate(ydoc);
+    if (state.length > MAX_STATE) throw new CommentsError("STORE_FULL", `the text is too large for one document (${MAX_STATE} bytes of state)`);
+    await this.store.transaction(async (tx) => {
+      if (await tx.get(DOCS, id) !== null) throw new CommentsError("DOCUMENT_EXISTS", `document "${id}" already exists`);
+      await tx.put(DOCS, id, { state: toBase64(state), createdBy: { kind: actor.kind, name: actor.name }, createdAt: Date.now() });
+    });
+  }
+  async read(id, actor, run) {
+    return run(this.open(this.load(await this.store.get(DOCS, this.id(id)), id), actor));
+  }
+  async write(id, actor, run) {
+    this.id(id);
+    return this.store.transaction(async (tx) => {
+      const row = await tx.get(DOCS, id);
+      const ydoc = this.load(row, id);
+      const result = run(this.open(ydoc, actor));
+      const state = Y.encodeStateAsUpdate(ydoc);
+      if (state.length > MAX_STATE) throw new CommentsError("STORE_FULL", `document "${id}" would pass ${MAX_STATE} bytes of state`);
+      await tx.put(DOCS, id, { state: toBase64(state), createdBy: row?.createdBy ?? null, createdAt: row?.createdAt ?? null });
+      return result;
+    });
+  }
+};
+var STATUS = {
+  INVALID_AUTHOR: 400,
+  INVALID_INPUT: 400,
+  INVALID_ANCHOR: 400,
+  NO_THREAD: 404,
+  NO_SUGGESTION: 404,
+  NO_DOCUMENT: 404,
+  THREAD_RESOLVED: 409,
+  ALREADY_DECIDED: 409,
+  DOCUMENT_EXISTS: 409,
+  CONFLICT: 409,
+  APPLY_FAILED: 409,
+  RELOCATE_FAILED: 409,
+  FORBIDDEN: 403,
+  STORE_FULL: 413,
+  CORRUPT: 500,
+  MISCONFIGURED: 500
+};
+var fail = (code, message, status) => Response.json({ error: { code, message } }, { status });
+async function body(c) {
+  if (Number(c.req.header("content-length") ?? 0) > MAX_BODY) invalid(`the body is over ${MAX_BODY} bytes`);
+  const text = await c.req.text();
+  if (text.length > MAX_BODY) invalid(`the body is over ${MAX_BODY} bytes`);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    parsed = void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) invalid("the body must be a JSON object");
+  return parsed;
+}
+function createApp(source, options = {}) {
+  const app2 = new Hono();
+  const docsOf = (c) => typeof source === "function" ? source(c.env ?? {}) : Promise.resolve(source);
+  app2.use("*", async (c, next) => {
+    await next();
+    c.header("x-content-type-options", "nosniff");
+  });
+  app2.get("/health", (c) => c.json({ ok: true, pack: "agentic-comments" }));
+  app2.use("/api/v1/*", async (c, next) => {
+    const auth = typeof options.auth === "function" ? options.auth(c.env ?? {}) : options.auth ?? createTokenAuth(c.env?.AGENTIC_COMMENTS_TOKENS);
+    const context = await auth.authenticate(c.req.raw);
+    if (!context) return fail("UNAUTHENTICATED", "send a valid bearer token", 401);
+    c.set("context", context);
+    await next();
+  });
+  app2.get("/api/v1/me", (c) => {
+    const { principalId, kind, scopes } = c.get("context");
+    return c.json({ kind, name: principalId, scopes });
+  });
+  const act = (c, need, write, run) => (async () => {
+    const context = c.get("context");
+    if (!hasScope(context.scopes, need)) throw new CommentsError("FORBIDDEN", `this token needs the ${need} scope`);
+    const docs = await docsOf(c);
+    const actor = actorOf(context);
+    const id = c.req.param("doc") ?? "";
+    return c.json(await (write ? docs.write(id, actor, run) : docs.read(id, actor, run)));
+  })();
+  const doc = "/api/v1/docs/:doc";
+  app2.post("/api/v1/docs", async (c) => {
+    const given = exact(await body(c), ["id", "text"], "a document");
+    if (typeof given.id !== "string") invalid("a document needs an id");
+    if (given.text !== void 0 && typeof given.text !== "string") invalid("text must be a string");
+    const context = c.get("context");
+    if (!hasScope(context.scopes, WRITE)) throw new CommentsError("FORBIDDEN", `this token needs the ${WRITE} scope`);
+    await (await docsOf(c)).create(given.id, given.text ?? "", actorOf(context));
+    return c.json({ id: given.id }, 201);
+  });
+  app2.get(doc, (c) => act(c, READ, false, (s) => ({ id: c.req.param("doc"), text: s.text() })));
+  app2.get(`${doc}/threads`, (c) => act(c, READ, false, (s) => s.threads(c.req.query())));
+  app2.get(`${doc}/threads/:id`, (c) => act(c, READ, false, (s) => s.thread(c.req.param("id"))));
+  app2.post(`${doc}/threads`, async (c) => {
+    const input = await body(c);
+    return act(c, COMMENT, true, (s) => s.comment(input));
+  });
+  app2.post(`${doc}/threads/:id/replies`, async (c) => {
+    const input = await body(c);
+    return act(c, COMMENT, true, (s) => s.reply(c.req.param("id"), input));
+  });
+  for (const action of ["resolve", "reopen"]) {
+    app2.post(`${doc}/threads/:id/${action}`, (c) => act(c, COMMENT, true, (s) => s[action](c.req.param("id"))));
+  }
+  app2.post(`${doc}/threads/:id/relocate`, (c) => act(c, WRITE, true, (s) => s.relocate(c.req.param("id"))));
+  app2.get(`${doc}/suggestions`, (c) => act(c, READ, false, (s) => s.suggestions(c.req.query())));
+  app2.post(`${doc}/suggestions`, async (c) => {
+    const input = await body(c);
+    return act(c, COMMENT, true, (s) => s.suggest(input));
+  });
+  for (const action of ["accept", "reject"]) {
+    app2.post(`${doc}/suggestions/:id/${action}`, (c) => act(c, WRITE, true, (s) => s[action](c.req.param("id"))));
+  }
+  app2.notFound(() => fail("NOT_FOUND", "no such route", 404));
+  app2.onError((error) => {
+    if (error instanceof CommentsError) return fail(error.code, error.message, STATUS[error.code] ?? 400);
+    if (error instanceof StoreConflictError) return fail("CONFLICT", "the document kept changing; try again", 409);
+    console.error(error instanceof Error ? error.name : "error");
+    return fail("INTERNAL", "the server could not finish the request", 500);
+  });
+  return app2;
+}
+var schemas = /* @__PURE__ */ new WeakMap();
+function regionOf(env) {
+  let region;
+  try {
+    region = parseRegion(env.AGENTIC_COMMENTS_REGION);
+  } catch {
+    throw new CommentsError("MISCONFIGURED", 'set AGENTIC_COMMENTS_REGION to "eu" or "us" ("unknown" only for local development)');
+  }
+  if (region === "unknown" && env.AGENTIC_COMMENTS_UNSAFE_REGION !== "1") {
+    throw new CommentsError("MISCONFIGURED", 'the region "unknown" turns the residency check off; set AGENTIC_COMMENTS_UNSAFE_REGION=1 to accept that for local development');
+  }
+  return region;
+}
+async function docsFor(env) {
+  if (!env.DB) throw new CommentsError("MISCONFIGURED", "bind a D1 database as DB");
+  const region = regionOf(env);
+  const db = env.DB;
+  let ready = schemas.get(db);
+  if (!ready) {
+    ready = db.prepare(D1_SCHEMA).run().catch((error) => {
+      schemas.delete(db);
+      throw error;
+    });
+    schemas.set(db, ready);
+  }
+  await ready;
+  const store = createD1Store(db, { region });
+  assertRegion(region, store);
+  return new CommentsDocs(store);
+}
+var app = createApp(docsFor);
+var worker_default = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+export {
+  CommentsDocs,
+  createApp,
+  createTokenAuth,
+  worker_default as default,
+  docsFor,
+  regionOf
+};

package/llms.txt

@@ -5,6 +5,7 @@ Comment threads and suggestions anchored to any content, from people and agents.
 Keywords: comments,threads,mentions,suggestions,annotations,collaboration,agents,yjs.
 
 - SDK: import { Comments, Suggestions, textAnchor } from "agentic-comments". The host calls stamp(); an agent never does.
+- Plain text anchors: import { createAnchor, resolveAnchor, mapRange } from "agentic-comments/anchor". No Yjs. resolveAnchor maps through edits, then falls back to quote + context, else orphaned.
 - Threads live on a Yjs document and merge across replicas.
 - Events: new Notifications(comments, suggestions).subscribe(listener). Ids only, never text.
 - CLI: agentic-comments <command>. MCP: agentic-comments mcp. Both use a local store file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-comments",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Comment threads and suggestions anchored to any content, from people and agents.",
   "keywords": [
     "comments",
@@ -26,7 +26,7 @@
   "type": "module",
   "private": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "files": [
     "dist",
@@ -44,9 +44,17 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./anchor": {
+      "types": "./dist/anchoring.d.ts",
+      "import": "./dist/anchoring.js"
+    },
     "./local": {
       "types": "./dist/local.d.ts",
       "import": "./dist/local.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
     }
   },
   "bin": {
@@ -57,12 +65,15 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "deploy:demo": "npm run build && WRANGLER_SEND_METRICS=false wrangler deploy --config wrangler.demo.jsonc",
     "clean": "rm -rf dist",
     "prepack": "npm run build",
     "ci:local": "npm run build && npm run typecheck && npm test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
+    "agentic-identity": "^0.4.0",
+    "hono": "^4.13.14",
     "zod": "^3.25.76"
   },
   "peerDependencies": {
@@ -73,6 +84,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0",
+    "wrangler": "^4.155.0",
     "yjs": "^13.6.0"
   }
 }

package/dist/mcp-BOJM5NE6.js

@@ -1,11 +0,0 @@
-import {
-  createMcpServer,
-  startMcp
-} from "./chunk-UE5ULEXU.js";
-import "./chunk-RWMBGIAS.js";
-import "./chunk-ZCM2UDLN.js";
-import "./chunk-C3P5TAC3.js";
-export {
-  createMcpServer,
-  startMcp
-};