agentic-comments 0.1.0 → 0.2.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 20 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,92 @@ 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"`.
+
+## 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 +225,7 @@ suggestions.accept(s.id, ada);
 
 ## Limits
 
-- No file store, CLI, MCP server, or HTTP API yet.
+- No HTTP API yet. The file store is for one machine. It is not a sync server.
 - `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 +236,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