agentic-comments 0.5.1 → 0.6.1

package/README.md

@@ -53,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.
@@ -173,8 +206,8 @@ 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 `npx 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`, 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
@@ -182,11 +215,13 @@ npx agentic-comments accept <id>
   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
+  the MCP server on stdio. If `AGENTIC_COMMENTS_AS` is missing, the server prints one error line that names it and exits with code 1. 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
+  `edit_message`, `delete_message`, `delete_thread`, and `erase_person` tools 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"`.
@@ -197,17 +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 to `kind:name`, or to
-`{ "as": "kind:name", "scopes": [...] }`. A token is 32 to 512 bytes, from A-Z a-z 0-9 `_` `-`, so a base64 token with `+` or `/` is refused.
-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 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
@@ -216,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 |
 | --- | --- |
@@ -229,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. |
 
@@ -261,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
@@ -280,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
 ```
 
@@ -361,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
@@ -372,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-QJXI3P5D.js → chunk-6N53KQVU.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";
@@ -248,7 +248,10 @@ import { PrincipalParseError, parsePrincipal } from "agentic-identity";
 function operatorActor(as, scopes) {
   const value = as?.trim();
   const cut = value === void 0 ? -1 : value.indexOf(":");
-  if (value === void 0 || cut < 1 || cut === value.length - 1) {
+  if (value === void 0 || value === "") {
+    throw new CommentsError("INVALID_AUTHOR", `no principal: set AGENTIC_COMMENTS_AS=kind:name (or pass --as), for example agent_of_human:scribe. Kinds: ${PRINCIPAL_KINDS.join(", ")}`);
+  }
+  if (cut < 1 || cut === value.length - 1) {
     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());

package/dist/{chunk-REFQNIEP.js → chunk-H6JK62SP.js}

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

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));

package/dist/{chunk-TFRLOBJW.js → chunk-UNJL3N2L.js}

@@ -1,12 +1,12 @@
 import {
   VERSION
-} from "./chunk-REFQNIEP.js";
+} from "./chunk-H6JK62SP.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",