agentic-comments 0.5.0 → 0.6.0

package/README.md

@@ -18,8 +18,6 @@ copy of `yjs`, because the package checks the Yjs types of your document. Instal
 npm install agentic-comments yjs
 ```
 
-To build from source, see Develop.
-
 ## Quick start
 
 ```ts
@@ -55,6 +53,39 @@ 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.
 
+## Edit, delete, export, and erase
+
+- `comments.editMessage(threadId, messageId, { body, mentions? }, actor)` changes a body. The id, author,
+  time, and place stay. The message gets `editedAt` and `editedBy`. A resolved thread refuses an edit.
+- `comments.deleteMessage(threadId, messageId, actor)` removes one message. The last message of a thread
+  stays: delete the thread instead.
+- `comments.deleteThread(threadId, actor)` removes a thread. Its author can do it while every message is theirs.
+- `comments.exportPerson(name, actor)` returns the messages a person wrote, the status change of theirs that
+  stands, and their edits to other people's messages. It holds no one else's words. `unread` counts stored
+  entries with their name that the read cannot show (a bad message, an unreadable thread). When it is not 0,
+  the export is not complete. `suggestions.exportPerson` lists their suggestions and decisions, with its own `unread` count.
+- `comments.erasePerson(name, actor)` replaces each message of that person with a tombstone: the body is
+  `[erased]`, the author name is `erased`, and mentions go. The author kind stays, so machine-made work stays
+  marked. The thread keeps its shape, order, and times. It works on the stored entries, so it also reaches a bad
+  message, a message past the read limit, and a copy that a merge hid. A status change of theirs and their name
+  as an editor get the tombstone name. `suggestions.erasePerson` does the same for their suggestions
+  (it drops the summary, and the change of a pending or rejected one, which can then no longer be accepted)
+  and their decisions. No principal can have the name `erased`.
+
+A self-export or self-erase covers only the actor's own kind: a message that `human:ada` wrote and one that
+`user_token:ada` wrote are two principals, and `unread` does not count the other kind. Ask a moderator for
+both. Erase rewrites a status record, so an erase and a real status change made at once on two replicas keep
+only one of them. An accepted suggestion keeps its `change`, which is still the author's text.
+
+Only the author can edit or delete a message, and a person can export or erase their own data: the same kind
+and name. A principal with the `comments:moderate` scope (`MODERATE_SCOPE`) can do it for anyone, and an
+export or erase by a moderator covers every kind with that name. The host gives that scope to an owner or
+admin. An edit made by a moderator records the moderator in `editedBy`. Nobody but a moderator can delete an
+erased message or a thread that holds one.
+
+Replicas that edit one message at once leave a copy each. When the copies agree on the author kind and time,
+the read keeps the erased copy, or else the latest edit. An edit and a delete made at once keep the edit.
+
 ## Anchors for plain text
 
 `agentic-comments/anchor` pins a range of a plain string. It needs no Yjs and no framework.
@@ -165,10 +196,6 @@ machine. It cannot check a lock held in another container or on another machine.
 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.
@@ -179,11 +206,11 @@ AGENTIC_COMMENTS_AS=agent_of_human:scribe npx agentic-comments suggest --text-qu
 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.
+- Commands: `init`, `list`, `show`, `comment`, `reply`, `resolve`, `reopen`, `relocate`, `edit-message`,
+  `delete-message`, `delete-thread`, `export-person`, `erase-person`, `suggestions`, `suggest`, `accept`, `reject`, `mcp`. Run `npx 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
+- The principal comes from `--as` or `AGENTIC_COMMENTS_AS`, as `kind:name`. The name starts with A-Z a-z 0-9 `_` `-`, then uses A-Z a-z 0-9 `.` `_` `-`, and is at most 128 characters. 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.
@@ -191,8 +218,10 @@ npx agentic-comments accept <id>
   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`.
+  `reopen_thread`, `relocate_thread`, `edit_message`, `delete_message`, `delete_thread`, `export_person`,
+  `erase_person`, `list_suggestions`, `suggest_change`, `accept_suggestion`, `reject_suggestion`.
+  Another person's message, thread, or data needs `comments:moderate` in `AGENTIC_COMMENTS_SCOPES`. The delete
+  tools and `erase_person` carry the destructive hint.
 - 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"`.
@@ -203,13 +232,26 @@ npx agentic-comments accept <id>
 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`.
+By default the Worker signs requests in with `agentic-identity`. Principals and their credentials live in the same
+`Store` as the documents (`createStoreAuth`). A request sends `Authorization: Bearer <key>`. The scopes of the
+principal decide what it may do (see the table below). A request with no valid credential gets `401`. A valid
+credential whose scopes fall short gets `403`. A store failure while the credential is read gets `503`, never `401`.
+Issue credentials with `issueCredential` from `agentic-identity`.
+A request whose `Authorization` header is not `Bearer` followed by 1 to 512 bytes of A-Z a-z 0-9 `_` `-` gets `401`, before any custom `Auth` runs.
+A write with no `Authorization` header (a session cookie, for example) gets `403` unless its `Origin` is in the `origins`
+option of `createApp`. The default lists none.
+
+**Static token list (dev fallback).** `AGENTIC_COMMENTS_TOKENS` is read only when `AGENTIC_COMMENTS_UNSAFE_STATIC_TOKENS=1`.
+Identity credentials are tried first, then the list. A Worker that sets the list without the switch answers every
+`/api/v1` request with `503 NOT_CONFIGURED`. The list is JSON from a bearer token to `kind:name`, or to
+`{ "as": "kind:name", "scopes": [...] }`. A token is 32 to 512 bytes, from A-Z a-z 0-9 `_` `-`.
+A name starts with A-Z a-z 0-9 `_` `-`, then uses A-Z a-z 0-9 `.` `_` `-`, and is at most 128 characters.
+One bad entry refuses the whole table. A token with no scopes holds `comments:comment`. Never use the list in production.
 
 ```sh
 wrangler secret put AGENTIC_COMMENTS_TOKENS
 # {"<openssl rand -hex 32>": {"as": "human:ada", "scopes": ["comments:write"]}, "<another>": "agent_of_human:scribe"}
+wrangler secret put AGENTIC_COMMENTS_UNSAFE_STATIC_TOKENS   # the value is 1
 ```
 
 Also set `AGENTIC_COMMENTS_REGION` to `eu` or `us`. Without it every document route fails with `500 MISCONFIGURED`. Use `unknown` with
@@ -218,9 +260,13 @@ Also set `AGENTIC_COMMENTS_REGION` to `eu` or `us`. Without it every document ro
 | 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:comment` | Also add threads, reply, resolve, reopen, and suggest. This is the default for a static-list 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). |
+| `comments:admin` | Also let an agent accept or reject (the `comments:accept` right), and edit, delete, export, or erase what another person wrote (the `comments:moderate` right). |
+
+With `comments:comment` a principal edits and deletes its own messages, deletes a thread when every message is
+its own, and erases its own data. With `comments:read` it can export its own data, and it cannot change anything.
+Export of another person's data and any change to another person's words need `comments:admin`.
 
 | Route | Action |
 | --- | --- |
@@ -231,6 +277,10 @@ Also set `AGENTIC_COMMENTS_REGION` to `eu` or `us`. Without it every document ro
 | `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. |
+| `PATCH`, `DELETE .../threads/:id/messages/:message` | Edit (`{body, mentions?}`) or delete a message. |
+| `DELETE .../threads/:id` | Delete a thread. |
+| `GET .../people/:name/export` | Export what a person wrote in this document (`comments:read` for yourself, `comments:admin` for anyone). |
+| `DELETE .../people/:name` | Erase what a person wrote in this document: replace it with a tombstone (`comments:comment` for yourself, `comments:admin` for anyone). |
 | `GET`, `POST /api/v1/docs/:doc/suggestions` | List or suggest. |
 | `POST .../suggestions/:id/accept`, `reject` | Decide. An agent never decides its own suggestion. |
 
@@ -263,7 +313,7 @@ try {
 ```
 
 - The methods match the routes: `me`, `createDocument`, `getDocument`, `listThreads`, `getThread`, `addThread`, `reply`,
-  `resolve`, `reopen`, `relocate`, `listSuggestions`, `suggest`, `accept`, `reject`. Each takes an optional `{ signal }`.
+  `resolve`, `reopen`, `relocate`, `editMessage`, `deleteMessage`, `deleteThread`, `exportPerson`, `erasePerson`, `listSuggestions`, `suggest`, `accept`, `reject`. Each takes an optional `{ signal }`.
 - `baseUrl` is the Worker URL, `http` or `https`, with no query, hash, or credentials.
 - The client never sends an author. The Worker stamps one from the token.
 - A failed call throws `CommentsApiError`. `code` is the API error code, or `UNKNOWN` when the reply is not an API
@@ -282,7 +332,7 @@ To deploy your own copy, log in with `wrangler login` or set `CLOUDFLARE_API_TOK
 
 ```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
+npx wrangler secret put AGENTIC_COMMENTS_TOKENS --config wrangler.demo.jsonc   # the demo uses the static list. See HTTP API
 npm run deploy:demo
 ```
 
@@ -363,7 +413,8 @@ const stop = notifications.subscribe(async (event) => {
 - 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
+- Export and erase work on one document. A person who wrote in many documents needs one call for each.
+- A repeated message id hides every copy, unless every copy is an edit: then the read keeps one. A peer that appends a copy of a thread's only message makes
   the thread unreadable.
 - The quoted text of a text anchor is not checked when a thread is read. A peer can store any text there.
   `textAnchor` refuses a quote whose JSON form passes 4,096 characters. Quotes with many newlines or
@@ -374,6 +425,14 @@ const stop = notifications.subscribe(async (event) => {
 - A body mentions anyone named as `@handle`. Put `@` text in backticks to avoid that. Any two backticks in a body pair up, so a loose backtick
   can hide a real mention that sits between two of them. A scoped
   package name such as `@scope/pkg` is not a mention.
+- Erase does not touch a name that another person typed in their own message.
+- Replicas that delete two messages of one thread at once can leave a thread with no message. Only a moderator
+  can delete it. A reply made on another replica at the same time as `deleteThread` is lost with the thread.
+- After you merge replicas, run `exportPerson`. When `unread` is not 0, a copy that the merge hid or a bad entry
+  still holds the person's name: run `erasePerson` again. An entry whose author is not valid cannot be tied to
+  a person, so export and erase skip it. An edit or an erase makes no notification event, also when two replicas edit one message at once. A delete works on a resolved thread, and an edit does not.
+- Yjs drops the old text of a deleted or replaced message only when the document has garbage collection on
+  (the default). A copy that you saved before an erase or delete still holds it.
 - Mentions are stored in lowercase, with no leading `@`. A handle holds up to 64 letters, digits, marks,
   and `. _ -`. A longer handle in a body is refused.
 

package/SKILL.md

@@ -25,8 +25,12 @@ 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.
 
+Change your own words with `edit_message`, `delete_message`, and `delete_thread`. Another person's messages need the
+`comments:moderate` scope. `export_person` and `erase_person` read or tombstone what one person wrote (your own, or
+anyone's with that scope). Check `unread` in an export.
+
 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.
+`accept_suggestion`, `reject_suggestion`, and the tools above. You never pass an author or a scope.
 
 ## Rules
 

package/dist/{chunk-HXXJNFEO.js → chunk-2NBFTJ47.js}

@@ -2,7 +2,7 @@ import {
   CommentsError,
   PRINCIPAL_KINDS,
   stamp
-} from "./chunk-BSNBDKR2.js";
+} from "./chunk-VAVKBAHM.js";
 
 // src/file-store.ts
 import { createHash } from "crypto";
@@ -244,6 +244,7 @@ var FileStore = class {
 };
 
 // src/operator.ts
+import { PrincipalParseError, parsePrincipal } from "agentic-identity";
 function operatorActor(as, scopes) {
   const value = as?.trim();
   const cut = value === void 0 ? -1 : value.indexOf(":");
@@ -251,7 +252,13 @@ function operatorActor(as, scopes) {
     throw new CommentsError("INVALID_AUTHOR", `set the principal as kind:name, for example human:ada. Kinds: ${PRINCIPAL_KINDS.join(", ")}`);
   }
   const list = scopes === void 0 || scopes.trim() === "" ? [] : scopes.split(",").map((s) => s.trim());
-  return stamp({ kind: value.slice(0, cut), name: value.slice(cut + 1), scopes: list });
+  try {
+    const { kind, id } = parsePrincipal({ kind: value.slice(0, cut), id: value.slice(cut + 1) });
+    return stamp({ kind, name: id, scopes: list });
+  } catch (error) {
+    if (!(error instanceof PrincipalParseError)) throw error;
+    throw new CommentsError("INVALID_AUTHOR", `the principal needs a known kind (${PRINCIPAL_KINDS.join(", ")}) and a name of A-Z a-z 0-9 . _ -`);
+  }
 }
 
 export {

package/dist/{chunk-WQHJNHAR.js → chunk-ES3NZ7SX.js}

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

package/dist/{chunk-ABXAPWXD.js → chunk-SR2A5OZW.js}

@@ -1,12 +1,12 @@
 import {
   VERSION
-} from "./chunk-WQHJNHAR.js";
+} from "./chunk-ES3NZ7SX.js";
 import {
   CommentsService
-} from "./chunk-NQWRFKJ6.js";
+} from "./chunk-T77DPNIV.js";
 import {
   CommentsError
-} from "./chunk-BSNBDKR2.js";
+} from "./chunk-VAVKBAHM.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -21,6 +21,8 @@ var anchor = z.discriminatedUnion("type", [
 ]).describe("Where the thread or suggestion points.");
 var id = z.string().describe("The thread or suggestion id.");
 var body = z.string().describe("The message text. Write @handle to mention someone.");
+var messageId = z.string().describe("The message id, from get_thread.");
+var person = z.string().describe("The name of the person, as shown on their messages.");
 var mentions = z.array(z.string()).optional().describe("Extra handles to mention.");
 function ok(value) {
   return { content: [{ type: "text", text: JSON.stringify(value) }] };
@@ -33,10 +35,10 @@ function createMcpServer(store, actor) {
   const service = new CommentsService(store, actor);
   const server = new McpServer({ name: "agentic-comments", version: VERSION });
   const tools = /* @__PURE__ */ new Map();
-  const tool = (name, description, shape, readOnly, run) => {
+  const tool = (name, description, shape, readOnly, run, destructive = false) => {
     const strict = z.object(shape).strict();
     tools.set(name, { strict, run });
-    server.registerTool(name, { description, inputSchema: strict, annotations: { readOnlyHint: readOnly, destructiveHint: false, openWorldHint: false } }, (() => {
+    server.registerTool(name, { description, inputSchema: strict, annotations: { readOnlyHint: readOnly, destructiveHint: destructive, openWorldHint: false } }, (() => {
       throw new Error("calls are handled by the server");
     }));
   };
@@ -48,6 +50,11 @@ function createMcpServer(store, actor) {
   tool("resolve_thread", "Resolve a thread.", { id }, false, (i) => service.resolve(i.id));
   tool("reopen_thread", "Reopen a resolved thread.", { id }, false, (i) => service.reopen(i.id));
   tool("relocate_thread", "Move a text anchor to its quote when the quote occurs exactly once.", { id }, false, (i) => service.relocate(i.id));
+  tool("edit_message", "Change the body of a message you wrote. Needs the moderate scope for another person's message.", { id, messageId, body, mentions }, false, (i) => service.editMessage(i.id, i.messageId, { body: i.body, mentions: i.mentions }), true);
+  tool("delete_message", "Delete a message you wrote. The last message of a thread stays: delete the thread instead.", { id, messageId }, false, (i) => service.deleteMessage(i.id, i.messageId), true);
+  tool("delete_thread", "Delete a thread. Works while every message is yours. Otherwise it needs the moderate scope.", { id }, false, (i) => service.deleteThread(i.id), true);
+  tool("export_person", "Export the messages, status changes, and suggestions one person wrote. Your own, or any with the moderate scope.", { person }, true, (i) => service.exportPerson(i.person));
+  tool("erase_person", "Replace everything one person wrote with a tombstone. The thread shape stays. Your own, or any with the moderate scope.", { person }, false, (i) => service.erasePerson(i.person), true);
   tool("list_suggestions", "List suggested changes.", { status: z.enum(["pending", "accepted", "rejected"]).optional(), anchorState: state }, true, (i) => service.suggestions(i));
   tool(
     "suggest_change",

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

@@ -7,7 +7,7 @@ import {
   textAnchor,
   textOf,
   textRange
-} from "./chunk-BSNBDKR2.js";
+} from "./chunk-VAVKBAHM.js";
 
 // src/local-host.ts
 import * as Y from "yjs";
@@ -144,6 +144,26 @@ var CommentsService = class {
   relocate(threadId) {
     return this.write(({ comments }) => comments.relocate(threadId, this.actor));
   }
+  editMessage(threadId, messageId, input) {
+    return this.write(({ comments }) => comments.editMessage(threadId, messageId, exact(input, ["body", "mentions"], "an edit"), this.actor));
+  }
+  deleteMessage(threadId, messageId) {
+    return this.write(({ comments }) => comments.deleteMessage(threadId, messageId, this.actor));
+  }
+  deleteThread(threadId) {
+    return this.write(({ comments }) => comments.deleteThread(threadId, this.actor));
+  }
+  /** Everything the store holds that this person wrote: messages, status changes, and suggestions. */
+  exportPerson(person) {
+    return this.read(({ comments, suggestions }) => ({ ...comments.exportPerson(person, this.actor), suggestions: suggestions.exportPerson(person, this.actor) }));
+  }
+  /** Tombstone everything this person wrote. Both parts are checked before either is written. */
+  erasePerson(person) {
+    return this.write(({ comments, suggestions }) => {
+      comments.checkPerson(person, this.actor);
+      return { ...comments.erasePerson(person, this.actor), ...suggestions.erasePerson(person, this.actor) };
+    });
+  }
   suggestions(filter = {}) {
     const given = exact(filter, ["status", "anchorState"], "a filter");
     return this.read(({ suggestions }) => suggestions.list(given));