agentic-documents 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 0.3.0
+
+### Breaking changes
+
+The API of this package does not change. The change is in the dependency.
+
+- **Dependencies.** `agentic-identity` moves from `^0.3.0` to `^0.4.0`. In 0.4 a grant is keyed on the
+  principal kind and the id, so a person and an agent with the same id hold separate roles. Grants
+  written by 0.3 are not honored until you run `migrateGrants`. A host that shares documents through
+  `createSharing` must pass `{ kind, id }` to `grant` and `revokeGrant`.
+
+### Added
+
+- Tests that a person and an agent with the same id get separate roles, and that `deleteResource`
+  removes the grants.
+- This package has no grant call and no command that deletes a whole document or erases a person. A
+  host that deletes a document must call `deleteResource` for it, and must delete the document and its
+  catalog entry itself. If `deleteResource` fails, run it again. If it throws `EraseRefusedError`,
+  remove the child resources or the extra owners first. Do not reuse the document id until it
+  succeeds. The `agentic-identity` person erase does not remove document content, and author names
+  stay in the edit log, the threads, and the suggestions.
+
+## 0.2.0
+
+### Breaking changes
+
+- **Worker deployments from the repo template.** `wrangler.jsonc` now sets `main` to
+  `src/live-worker.ts`. To host live rooms, add the `SYNC_ROOM` Durable Object binding and the `v1`
+  migration (`new_sqlite_classes`). Without the binding, the room routes fail with `MISCONFIGURED`.
+  The published package does not include `wrangler.jsonc`.
+- **Token table.** An `AGENTIC_DOCS_TOKENS` entry in object form may now carry a `role`. A `role` that
+  is not `editor` or `viewer` refuses the whole token table, so a typo never leaves a token live with
+  the wrong role. Entries with no `role` stay editors, as before.
+- **Dependencies.** `agentic-identity` moves from `^0.2.0` to `^0.3.0`.
+
+### Added
+
+- Live rooms. Several people and agents edit one document at the same time. Import `LiveDoc` from
+  `agentic-documents/live`. Deploy `agentic-documents/live-worker` to host the rooms.
+- The `agentic-realtime` dependency (`^0.1.0`, the version on npm) for the live rooms.
+- `--live <url>` on the CLI and the MCP server, or `AGENTIC_DOCS_LIVE_URL`. Set `AGENTIC_DOCS_TOKEN`
+  to join a room. The server sets the author kind and the role from the token.
+- With `--live`, the CLI refuses `--as`, `--scopes`, and `--dir`, and exits 2. The server sets these
+  from the token.
+- A `viewer` role. A viewer reads and cannot write, over HTTP or in a live room. The default role is
+  `editor`.
+- Worker routes for live rooms: `GET /api/v1/me`, `GET /api/v1/docs/:id/room`,
+  `GET /api/v1/docs/:id/ws`, `GET /api/v1/docs/:id/state`, and `POST /api/v1/docs/:id/checkpoint`.
+- Live rooms save through the shared `Store` and `Blobs` ports. A stored document too big for a room
+  fails the join with a clear error.
+- `npm pack` and `npm publish` build `dist/` first (`prepack`).
+
+## 0.1.0
+
+- First release. The document model, the Markdown and ODT export, the text operations, the CLI, the
+  MCP server, and the Worker HTTP API.

package/README.md

@@ -7,8 +7,8 @@
 
 Write documents with people and agents in real time.
 
-> Status: early, version 0.1.0. The document model, the text operations, the CLI, the MCP server,
-> and the Worker API work. The web UI is not built yet.
+> Status: early, version 0.3.0. The document model, the text operations, the CLI, the MCP server,
+> the Worker API, and live editing in a room work. The web UI is not built yet.
 
 ## Install
 
@@ -130,7 +130,60 @@ curl "$URL/api/v1/docs/plan/export?format=html" -H "authorization: Bearer $TOKEN
   its alt text, because a remote image tells its host who opened the file. `remoteImages` turns
   that back on.
 - Every edit, message, and suggestion needs an author. The edit log keeps the kind and the name, so
-  agent work stays labeled. The log holds no content.
+  agent work stays labeled. The log holds no content. Over the CLI, MCP, and HTTP the server or
+  the operator sets the author. In a live room a client writes its own log entries, suggestion decisions, and
+  threads. A save merges them into the stored document. So after a live client saves, treat all three
+  as advisory. The room's own record of who sent updates in the room is at `GET /api/v1/docs/:id/room`. It does not cover
+  text written over HTTP, the CLI, or MCP before the room opened: the client that seeds the room appears there.
+
+## Live editing
+
+A person and an agent can edit one document at the same time. Each sees the other's changes. The Worker
+hosts one room per document, on a Durable Object, through [agentic-realtime](https://www.npmjs.com/package/agentic-realtime).
+Deploy `agentic-documents/live-worker`. The sample `wrangler.jsonc` binds `SYNC_ROOM` and sets the migration.
+
+```ts
+import { LiveDoc } from "agentic-documents/live";
+
+const live = await LiveDoc.join({ server: "https://docs.example.com", id: "plan", token });
+await live.edit((doc, author) => doc.append("Ship on Friday.", author));
+console.log(live.peers); // the other people and agents. `machine` is true for an agent.
+await live.save(); // write the room state to the stored document
+await live.leave();
+```
+
+The CLI and the MCP server join rooms too. Every command then runs in the room and saves:
+
+```sh
+export AGENTIC_DOCS_TOKEN=...   # a bearer token. The server sets the author kind and the role.
+export AGENTIC_DOCS_LIVE_URL=https://docs.example.com   # or pass --live <url>
+npx agentic-documents append plan --content "Ship on Friday." --live https://docs.example.com
+npx agentic-documents mcp --live https://docs.example.com
+```
+
+- The server reads your author kind and role from the token (`GET /api/v1/me`). An agent token writes
+  agent edits. `--as`, `--scopes`, and `--dir` do not apply with `--live`: the CLI refuses them and exits 2. This
+  holds when `AGENTIC_DOCS_LIVE_URL` is set too, so unset it for a local call.
+- A room starts from the stored document. `save` merges the room back into the stored document, so
+  `read`, `export`, and the other commands see live edits. A save also creates a document that has none.
+  The CLI and MCP server save after each change. If a save fails, the room keeps the change and the error says so: do not repeat it. `new` makes the document in the store, and a room picks it up on the next join. A document over 1,000,000 bytes cannot open in a room or be saved from one. A save refuses an update with a wrong
+  kind of content or a malformed thread, suggestion, or log entry. HTTP edits reach an open room only when a client joins and seeds it.
+- A `viewer` token joins and reads. The room drops its updates, and `edit` and `save` fail with `FORBIDDEN`.
+  Set a role in `AGENTIC_DOCS_TOKENS` with `{ "as": "human:Vic", "role": "viewer" }`. A token with no role is an editor.
+- `GET /api/v1/docs/:id/room` lists who sent updates in the room, and whether each is machine-made.
+- Pass `reconnect: {}` to `join` to keep trying after a drop. Edits made offline merge on return.
+  A room that restarts recovers its state from the Durable Object.
+
+Limits of live editing:
+
+- The edit log, the suggestion decisions, and the threads live in the document, and a client writes them.
+  A modified client can write a log entry with another author, or accept its own suggestion. The room's
+  list at `/room` is the record to trust for who sent updates. It does not cover text written before the
+  room opened.
+- Until a client saves, a command over HTTP reads the stored copy, not the room.
+- After the room refuses an edit, the local copy of `LiveDoc` still holds it. Join again.
+- Durable Objects have no US jurisdiction. With the region `us` a room sits near the first client that opens it.
+  With `eu` it stays in the EU. The local `wrangler dev` cannot place rooms.
 
 ## Rules for text matching
 
@@ -142,12 +195,19 @@ curl "$URL/api/v1/docs/plan/export?format=html" -H "authorization: Bearer $TOKEN
 ## Limits
 
 - No web UI yet.
+- A document holds no roles of its own. The token table gives `editor` or `viewer`. To share a document
+  by person, use `createSharing` from `agentic-identity` 0.4. A grant names its subject by kind
+  (`human` or `agent`) and id, so a person and an agent with the same id hold separate roles. When you
+  delete a document, call `deleteResource` on its resource so its grants do not outlive it. If
+  `deleteResource` fails, treat the delete as failed and run it again. If it throws
+  `EraseRefusedError`, remove the child resources or the extra owners first. Do not reuse the id
+  until it succeeds. This package has no command that deletes a whole document.
 - The Worker keeps each document in R2 and a catalog (who made it, and when) in D1. Both come from the
   shared `agentic-identity` ports. A save is conditional on the version it read, so two writers cannot
   overwrite each other. The CLI and MCP server keep the same data in local files.
 - The CLI and MCP server keep files under `<dir>/blobs` and `<dir>/store`. Files from an older release that sit
   directly in `<dir>` are not read.
-- Token auth is a stopgap until the `Auth` port exists. There is no per-document sharing or role yet.
+- Token auth is a stopgap until the `Auth` port exists. A token has one role for the whole server: `editor` (the default) or `viewer`. A viewer cannot call a write command or write in a live room. There is no per-document sharing yet.
 - A save is a compare-and-set. The file store takes a lock file, checks the version, and renames a
   uniquely named temp file into place. A writer that loses loads the document again and runs
   its change again. A lock older than 10 seconds counts as dead and is taken over. A lock that

package/dist/chunk-FZA5LQV3.js

@@ -0,0 +1,150 @@
+import {
+  AgenticDoc,
+  DocError,
+  PRINCIPAL_KINDS,
+  Suggestions,
+  Threads
+} from "./chunk-YBBQNCMC.js";
+
+// src/service.ts
+import * as Y from "yjs";
+var ATTEMPTS = 64;
+var ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+var CATALOG = "documents";
+var MAX_LIVE_BYTES = 1e6;
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isString = (v) => typeof v === "string";
+var isWho = (v) => isObject(v) && PRINCIPAL_KINDS.includes(v.kind) && isString(v.name) && v.name !== "";
+var isAnchor = (v) => isObject(v) && isString(v.text) && isObject(v.start) && isObject(v.end);
+var ROOTS = /* @__PURE__ */ new Set(["default", "edits", "suggestions", "threads", "applied"]);
+var DocsService = class {
+  constructor(ports, options = {}) {
+    this.options = options;
+    this.blobs = ports.blobs;
+    this.store = ports.store;
+  }
+  options;
+  blobs;
+  store;
+  key(id) {
+    if (!ID.test(id)) throw new DocError("INVALID_INPUT", `invalid document id "${id}": use 1 to 64 of a-z, 0-9, "-" and "_"`);
+    return `${id}.ydoc`;
+  }
+  async create(id, markdown, author) {
+    const key = this.key(id);
+    const created = await this.blobs.put(key, AgenticDoc.fromMarkdown(markdown, author, this.options).encode(), { ifNoneMatch: "*" });
+    if (!created) throw new DocError("DOCUMENT_EXISTS", `document "${id}" already exists`);
+    await this.catalog(id, author);
+  }
+  /** The stored document as a Yjs update. A live client seeds its room from it. */
+  async state(id) {
+    const found = await this.blobs.get(this.key(id));
+    if (!found) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
+    return found.data;
+  }
+  /**
+   * Merge a Yjs update from a live room into the stored document, and create the document when it
+   * has none. A merge is safe to repeat and to run in any order. The save is conditional, so two
+   * checkpoints at once both land.
+   */
+  async checkpoint(id, update, author) {
+    const key = this.key(id);
+    const scratch = new Y.Doc();
+    try {
+      Y.applyUpdate(scratch, update);
+    } catch {
+      throw new DocError("INVALID_INPUT", "the update is not a Yjs update");
+    }
+    if (scratch.store.clients.size === 0 || scratch.store.pendingStructs || scratch.store.pendingDs) {
+      throw new DocError("INVALID_INPUT", "the update is empty or lacks the changes it depends on");
+    }
+    for (const root of scratch.share.keys()) if (!ROOTS.has(root)) throw new DocError("INVALID_INPUT", `the update holds a part this package does not use: "${root}"`);
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const found = await this.blobs.get(key);
+      if (!found) {
+        const created = AgenticDoc.fromUpdate(update, this.options);
+        const fresh = this.checked(id, created);
+        this.fits(id, fresh);
+        if (!await this.blobs.put(key, fresh, { ifNoneMatch: "*" })) continue;
+        await this.catalog(id, author);
+        return;
+      }
+      const doc = AgenticDoc.fromUpdate(found.data, this.options);
+      doc.applyUpdate(update);
+      const merged = this.checked(id, doc);
+      this.fits(id, merged);
+      if (await this.blobs.put(key, merged, { ifMatch: found.version })) return;
+    }
+    throw new DocError("CONFLICT", `document "${id}" kept changing; try again`);
+  }
+  /**
+   * The encoded document, once it reads back and every stored entry has the shape the commands rely on. Yjs does not
+   * check types, so an update can put text where the editor expects blocks, or a thread with no messages, and then a
+   * command fails on every later call.
+   */
+  checked(id, doc) {
+    const refuse = (what) => new DocError("INVALID_INPUT", `the update would leave document "${id}" unreadable: ${what}`);
+    try {
+      doc.toMarkdown();
+      if (!doc.edits().every((e) => isObject(e) && isWho(e.author) && isString(e.at) && isString(e.op))) throw refuse("an edit log entry is malformed");
+      for (const [, t] of doc.ydoc.getMap("threads")) {
+        const messages = t instanceof Y.Map ? t.get("messages") : void 0;
+        const ok = t instanceof Y.Map && isAnchor(t.get("anchor")) && ["open", "resolved"].includes(t.get("status")) && messages instanceof Y.Array && messages.length > 0 && messages.toArray().every((m) => isObject(m) && isString(m.id) && isString(m.at) && isString(m.body) && isWho(m.author));
+        if (!ok) throw refuse("a thread is malformed");
+      }
+      for (const [, f] of doc.ydoc.getMap("suggestions")) {
+        const ok = f instanceof Y.Map && ["insert", "replace", "delete"].includes(f.get("kind")) && ["pending", "accepted", "rejected"].includes(f.get("status")) && isAnchor(f.get("anchor")) && isString(f.get("replacement")) && isString(f.get("createdAt")) && isWho(f.get("author"));
+        if (!ok) throw refuse("a suggestion is malformed");
+      }
+      new Suggestions(doc).list();
+      new Threads(doc).list();
+    } catch (error) {
+      throw error instanceof DocError ? error : refuse("a part holds the wrong kind of content");
+    }
+    return doc.encode();
+  }
+  fits(id, state) {
+    if (state.length > MAX_LIVE_BYTES) throw new DocError("INVALID_INPUT", `document "${id}" would pass ${MAX_LIVE_BYTES} bytes, the most a live room takes`);
+  }
+  async catalog(id, author) {
+    await this.store.transaction(async (tx) => {
+      if (await tx.get(CATALOG, id) === null) await tx.put(CATALOG, id, { createdBy: { kind: author.kind, name: author.name }, createdAt: Date.now() });
+    });
+  }
+  /** Who created the document and when, or null when it has no catalog entry (made before the catalog, or a failed catalog write). */
+  async info(id) {
+    this.key(id);
+    const entry = await this.store.get(CATALOG, id);
+    if (entry === null) return null;
+    const { createdBy, createdAt } = entry;
+    if (!createdBy || !PRINCIPAL_KINDS.includes(createdBy.kind) || typeof createdBy.name !== "string" || typeof createdAt !== "number") {
+      throw new DocError("INVALID_INPUT", `the catalog entry for "${id}" is damaged`);
+    }
+    return { createdBy, createdAt };
+  }
+  async read(id, run) {
+    const found = await this.blobs.get(this.key(id));
+    if (!found) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
+    return run(AgenticDoc.fromUpdate(found.data, this.options));
+  }
+  /**
+   * Load, run the change, and save only if nobody saved in between. When someone did, load again and
+   * run the change again, so a check such as "is it still pending" sees the new state.
+   */
+  async write(id, run) {
+    const key = this.key(id);
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const found = await this.blobs.get(key);
+      if (!found) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
+      const doc = AgenticDoc.fromUpdate(found.data, this.options);
+      const result = run(doc);
+      if (await this.blobs.put(key, doc.encode(), { ifMatch: found.version })) return result;
+    }
+    throw new DocError("CONFLICT", `document "${id}" kept changing; try again`);
+  }
+};
+
+export {
+  MAX_LIVE_BYTES,
+  DocsService
+};