agentic-comments 0.2.0 → 0.3.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
@@ -170,6 +170,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 +288,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/{chunk-RWMBGIAS.js → chunk-GMA5I5L6.js}

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

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

@@ -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-ZCM2UDLN.js → chunk-IB6ANO32.js}

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

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

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

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

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

package/dist/cli.js

@@ -3,17 +3,17 @@ import {
   FileStore,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-C43HLFQE.js";
+} from "./chunk-YU5U4P22.js";
 import {
   VERSION
-} from "./chunk-RWMBGIAS.js";
+} from "./chunk-GMA5I5L6.js";
 import {
   CommentsService,
   TEXT_ROOT
-} from "./chunk-ZCM2UDLN.js";
+} from "./chunk-IB6ANO32.js";
 import {
   CommentsError
-} from "./chunk-C3P5TAC3.js";
+} from "./chunk-GSAJOCDV.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-YERA77HT.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,10 @@
-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-D4ZJFzzR.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, P as PRINCIPAL_KINDS, m as PrincipalKind, R as RelativePositionJson, n as RevertContext, o as SlideAnchor, p as StampInput, S as Suggestion, q as SuggestionFilter, r as SuggestionHost, s as TextAnchor, T as Thread, t as ThreadFilter, u as authorLabel, v as stamp, w as textAnchor, x as textOf } from './suggestions-D4ZJFzzR.js';
 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-GMA5I5L6.js";
 import {
   ACCEPT_SCOPE,
   Actor,
@@ -14,7 +14,7 @@ import {
   textAnchor,
   textOf,
   validDate
-} from "./chunk-C3P5TAC3.js";
+} from "./chunk-GSAJOCDV.js";
 
 // src/notifications.ts
 import * as Y from "yjs";

package/dist/local.d.ts

@@ -1,5 +1,6 @@
 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-BmMQMT_8.js';
+import { r as SuggestionHost, A as Actor } from './suggestions-D4ZJFzzR.js';
 
 /** 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 +36,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 +53,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-YU5U4P22.js";
 import {
   CommentsService,
   TEXT_ROOT,
   VALUES_ROOT,
   localHost
-} from "./chunk-ZCM2UDLN.js";
-import "./chunk-C3P5TAC3.js";
+} from "./chunk-IB6ANO32.js";
+import "./chunk-GSAJOCDV.js";
 export {
   CommentsService,
   FileStore,

package/dist/mcp-YERA77HT.js

@@ -0,0 +1,11 @@
+import {
+  createMcpServer,
+  startMcp
+} from "./chunk-TTTX3R6M.js";
+import "./chunk-GMA5I5L6.js";
+import "./chunk-IB6ANO32.js";
+import "./chunk-GSAJOCDV.js";
+export {
+  createMcpServer,
+  startMcp
+};

package/dist/mcp-bin.js

@@ -3,19 +3,38 @@ import {
   FileStore,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-C43HLFQE.js";
+} from "./chunk-YU5U4P22.js";
 import {
   startMcp
-} from "./chunk-UE5ULEXU.js";
-import "./chunk-RWMBGIAS.js";
-import "./chunk-ZCM2UDLN.js";
-import "./chunk-C3P5TAC3.js";
+} from "./chunk-TTTX3R6M.js";
+import {
+  VERSION
+} from "./chunk-GMA5I5L6.js";
+import "./chunk-IB6ANO32.js";
+import "./chunk-GSAJOCDV.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-BmMQMT_8.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-D4ZJFzzR.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-D4ZJFzzR.d.ts}

@@ -331,4 +331,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, PRINCIPAL_KINDS as P, 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 PrincipalKind as m, type RevertContext as n, type SlideAnchor as o, type StampInput as p, type SuggestionFilter as q, type SuggestionHost as r, type TextAnchor as s, type ThreadFilter as t, authorLabel as u, stamp as v, textAnchor as w, textOf as x };

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-D4ZJFzzR.js';
+import { C as CommentsService } from './service-BmMQMT_8.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-IB6ANO32.js";
+import {
+  ACCEPT_SCOPE,
+  CommentsError,
+  PRINCIPAL_KINDS,
+  exact,
+  invalid,
+  stamp
+} from "./chunk-GSAJOCDV.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-comments",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -47,6 +47,10 @@
     "./local": {
       "types": "./dist/local.d.ts",
       "import": "./dist/local.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
     }
   },
   "bin": {
@@ -57,12 +61,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 +80,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
-};