agentic-comments 0.1.0 → 0.3.0

package/README.md

@@ -6,12 +6,13 @@
 
 Comment threads and suggestions anchored to any content, from people and agents.
 
-> Status: first release, 0.1.0. Threads, suggestions, and anchor survival work. The CLI, the MCP
-> server, and notifications come next.
+> Status: see [npm](https://www.npmjs.com/package/agentic-comments) for the latest released version. The
+> `main` branch can have changes that npm does not have yet.
 
 ## Install
 
-Requires Node.js 20 or later. The quick start imports `yjs`, so install it with this package:
+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
 npm install agentic-comments yjs
@@ -126,6 +127,155 @@ suggestions.accept(s.id, ada);
   record is, and it can win settle, so every replica undoes the real edit. The sync layer must decide who
   may write.
 
+## CLI and MCP server
+
+Both run on a local store: one file that holds a Yjs document. The text is in the `text` root, and
+non-text values are in the `values` map. A file starts with a magic mark and a hash, so a damaged or zero-filled file is refused and not read as empty. A write
+takes a lock file, saves with a rename, and runs again if the file changed meanwhile, so parallel processes
+on one machine lose nothing. A full disk or a file size limit fails the write and leaves the old file. A lock left by a dead process, or by this process under another mark, is cleared. So is an empty lock older
+than two seconds and any lock older than a minute. The store is for one
+machine. It cannot check a lock held in another container or on another machine. Two containers that
+share a volume can have the same process id, and each then clears the other's lock, so they can lose writes. A save that
+would pass 50 MB is refused.
+
+If the version you install has no `agentic-comments` command, build from source (see [Develop](#develop)).
+In the cloned repo, run `npm run build` and use `node dist/cli.js` where these examples say
+`npx agentic-comments`.
+
+```sh
+export AGENTIC_COMMENTS_FILE=./comments.ydoc
+export AGENTIC_COMMENTS_AS=human:ada          # kind:name. The operator sets this.
+npx agentic-comments init --text "Hello brave world"
+npx agentic-comments comment --text-quote brave --body "Word choice? @scribe"
+npx agentic-comments list --status open
+AGENTIC_COMMENTS_AS=agent_of_human:scribe npx agentic-comments suggest --text-quote brave --replace bold
+npx agentic-comments accept <id>
+```
+
+- Commands: `init`, `list`, `show`, `comment`, `reply`, `resolve`, `reopen`, `relocate`, `suggestions`,
+  `suggest`, `accept`, `reject`, `mcp`. Run `agentic-comments --help` for flags.
+- Every result is JSON. An error is JSON on stderr with a `code`, and the exit code is 1. A usage error
+  exits 2.
+- The principal comes from `--as` or `AGENTIC_COMMENTS_AS`. Scopes come only from
+  `AGENTIC_COMMENTS_SCOPES`, a comma list such as `comments:accept`. No flag takes a scope or an author,
+  and a flag that does not apply to a command is refused. `AGENTIC_COMMENTS_LOCK_TIMEOUT_MS` sets the wait
+  for a lock, in whole milliseconds.
+- `npx agentic-comments mcp` (or the `agentic-comments-mcp` binary, which reads the same environment) starts
+  the MCP server on stdio. The operator fixes the principal and the
+  scopes when the server starts. No tool takes an author or a scope. A call with any key a tool does not list is refused, so an agent
+  cannot pick its own kind or rights. Tools: `list_threads`, `get_thread`, `add_comment`, `reply_to_thread`, `resolve_thread`,
+  `reopen_thread`, `relocate_thread`, `list_suggestions`, `suggest_change`, `accept_suggestion`,
+  `reject_suggestion`.
+- A text change is `{"replace": "new text"}`. A change for a cell, slide, or canvas anchor is
+  `{"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
+sees changes from other replicas too. It replays nothing from before you created it. A first load into an
+empty document looks like new changes, so create the stream with `muted: true` and call `unmute()` after
+that load.
+
+```ts
+import { Notifications } from "agentic-comments";
+
+const notifications = new Notifications(comments, suggestions, { muted: true, onError: (error, source) => report(error, source) });
+// ...load the document or connect the provider, then:
+notifications.unmute();
+const stop = notifications.subscribe(async (event) => {
+  if (event.type === "mention") await notify(event.mention, event.threadId); // fetch the text with the ids
+});
+```
+
+- Events: `thread.created`, `message.added`, `mention` (one per handle), `thread.resolved`,
+  `thread.reopened`, `suggestion.created`, `suggestion.accepted`, `suggestion.rejected`.
+- An event holds ids, the actor, `machineMade`, the anchor type, `source` (`local` or `remote`), and a time.
+  It never holds the text of a comment, a suggestion, or a change. Fetch that with the ids.
+- The same change has the same `id` on every replica. So a notifier that must
+  send once keeps the ids it has sent. Within one replica, an id is delivered at most once, and a listener
+  that throws is not retried. A replica remembers its last 10,000 ids (`seenLimit`) and drops a
+  repeat within that window. Two accepts at once give one id, and the actor can differ between replicas. A `suggestion.rejected` event
+  can be overturned: if another replica accepted at the same time, the merge ends as accepted, and a
+  `suggestion.accepted` event follows.
+  An id for a status change includes the clock time, so a clock coarser than the changes can merge two.
+- Use `source` to decide where to send. If every replica runs a notifier, filter on `local`, or each
+  replica sends its own copy of every remote change.
+- Events are delivered after the Yjs transaction that caused them has finished, so a listener can write to
+  the document. A listener that throws, or returns a rejected promise, cannot break a write or another
+  listener. The
+  error goes to `onError`, or to `errors()`.
+- Write a thread in one Yjs transaction, as `add` does. A thread whose map arrives empty and gets its fields
+  and messages in one later transaction is treated as created then. A thread built in more steps than that
+  can make no event.
+- A peer that deletes a thread or a suggestion and adds it back under the same id makes a `created` event
+  again once the id has left the `seenLimit` window.
+- A change that arrives as a whole thread, with its replies and status inside, makes an event for each
+  message and for a resolved status. A reopen inside such a thread makes none. A message past the thread's read limit makes no event.
+
 ## Author kinds
 
 | Kind | Meaning | Label |
@@ -138,7 +288,7 @@ suggestions.accept(s.id, ada);
 
 ## Limits
 
-- No file store, CLI, MCP server, or HTTP API yet.
+- 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
@@ -149,6 +299,14 @@ suggestions.accept(s.id, ada);
   on every read, so keep it fast.
 - A local reply stops at 1,000 messages. Replicas that reply at once can pass that. A read shows the first
   2,000 valid messages. `skipped` and `problems()` report the rest.
+- If several processes clear one stale lock at the same moment, two writes can very rarely overlap. The
+  save check catches almost every such case. A symlink as the store path is followed. A filesystem with no
+  hard links makes `init` use a check and a rename, which can race.
+- The CLI trusts its caller: a process that can set `AGENTIC_COMMENTS_AS` and `AGENTIC_COMMENTS_SCOPES` can
+  act as anyone. Give an agent the MCP server, where the operator fixes both. Do not give it a shell with
+  the store file and the CLI.
+- Events come from the data and not from the calls, so a status change that two replicas make at once gives
+  each replica its own event, and a thread that arrives whole gives events for its current state only.
 - Every replica of a document must register the same custom anchor kinds.
 - A repeated message id hides every copy. A peer that appends a copy of a thread's only message makes
   the thread unreadable.

package/SKILL.md

@@ -25,7 +25,8 @@ Check `thread.anchorState`. An `orphaned` thread has lost its content. Read it,
 Suggest a change with `suggestions.add({ anchor, change, summary }, actor)`. Accept needs a person or
 the `comments:accept` scope. You never accept or reject your own suggestion.
 
-The CLI and the MCP server are not built yet.
+Over MCP, call `list_threads`, `add_comment`, `reply_to_thread`, `resolve_thread`, `suggest_change`,
+`accept_suggestion`, and `reject_suggestion`. You never pass an author or a scope.
 
 ## Rules
 

package/dist/chunk-GMA5I5L6.js

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