agentic-documents 0.4.0 → 0.6.0

package/dist/{chunk-R5XUTBC3.js → chunk-CN6UAW7B.js}

@@ -1,12 +1,14 @@
 import {
   MAX_LIVE_BYTES
-} from "./chunk-FZA5LQV3.js";
+} from "./chunk-JBAQEIOH.js";
 import {
   AgenticDoc,
   DOC_ERROR_CODES,
-  DocError,
+  DocError
+} from "./chunk-GQ5E6T7Z.js";
+import {
   PRINCIPAL_KINDS
-} from "./chunk-YBBQNCMC.js";
+} from "./chunk-DWVJIKVT.js";
 
 // src/live.ts
 import * as Y from "yjs";
@@ -128,16 +130,37 @@ var LiveService = class {
       throw unreachable(error);
     }
   }
-  /** The room is only a copy, so a new document is made in the store. A room seeds from it on the next join. */
-  async create(id, markdown) {
-    const response = await fetch(`${base(this.options.server)}/api/v1/docs`, {
-      method: "POST",
-      headers: { authorization: `Bearer ${this.options.token}`, "content-type": "application/json" },
-      body: JSON.stringify({ id, markdown })
+  async call(path, init) {
+    const response = await fetch(`${base(this.options.server)}${path}`, {
+      method: init.method,
+      headers: { authorization: `Bearer ${this.options.token}`, ...init.body ? { "content-type": "application/json" } : {} },
+      body: init.body ? JSON.stringify(init.body) : void 0
     }).catch((error) => {
       throw unreachable(error);
     });
     if (!response.ok) throw await refusal(response, "the server refused the request");
+    return response;
+  }
+  /** The room is only a copy, so a new document is made in the store. A room seeds from it on the next join. */
+  async create(id, markdown) {
+    await this.call("/api/v1/docs", { method: "POST", body: { id, markdown } });
+  }
+  // The catalog lives in the store, not in a room, so these go to the HTTP API.
+  async list() {
+    const body = await (await this.call("/api/v1/docs", { method: "GET" })).json().catch(() => void 0);
+    const who = (w) => typeof w === "object" && w !== null && PRINCIPAL_KINDS.includes(w.kind) && typeof w.name === "string" && w.name !== "";
+    const row = (r) => {
+      const d = r;
+      return typeof r === "object" && r !== null && typeof d.id === "string" && typeof d.title === "string" && typeof d.createdAt === "number" && typeof d.updatedAt === "number" && who(d.createdBy) && who(d.updatedBy);
+    };
+    if (!Array.isArray(body) || !body.every(row)) throw new DocError("INVALID_INPUT", "the server sent a document list that is not valid");
+    return body;
+  }
+  async rename(id, title) {
+    await this.call(`/api/v1/docs/${encodeURIComponent(id)}/rename`, { method: "POST", body: { title } });
+  }
+  async remove(id) {
+    await this.call(`/api/v1/docs/${encodeURIComponent(id)}/remove`, { method: "POST", body: {} });
   }
   async read(id, run) {
     const live = await this.join(id);

package/dist/chunk-DWVJIKVT.js

@@ -0,0 +1,8 @@
+// src/kinds.ts
+var PRINCIPAL_KINDS = ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
+var isMachine = (kind) => kind !== "human";
+
+export {
+  PRINCIPAL_KINDS,
+  isMachine
+};

package/dist/{chunk-YBBQNCMC.js → chunk-GQ5E6T7Z.js}

@@ -1,3 +1,7 @@
+import {
+  PRINCIPAL_KINDS
+} from "./chunk-DWVJIKVT.js";
+
 // src/errors.ts
 var DOC_ERROR_CODES = ["NO_MATCH", "AMBIGUOUS_MATCH", "STALE_ANCHOR", "NO_SECTION", "INVALID_AUTHOR", "INVALID_INPUT", "NO_THREAD", "NO_SUGGESTION", "ALREADY_DECIDED", "FORBIDDEN", "NO_DOCUMENT", "DOCUMENT_EXISTS", "LOCKED", "CONFLICT", "MISCONFIGURED"];
 var DocError = class extends Error {
@@ -314,7 +318,6 @@ function settle(ydoc) {
 var PREAMBLE = "preamble";
 var FRAGMENT = "default";
 var CONTEXT_CHARS = 20;
-var PRINCIPAL_KINDS = ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
 var isSection = (t) => "section" in t;
 var isAnchor = (t) => "anchor" in t;
 function checkAuthor(author) {
@@ -361,9 +364,18 @@ var AgenticDoc = class _AgenticDoc {
     });
   }
   static fromMarkdown(markdown, author, options) {
+    checkAuthor(author);
+    return _AgenticDoc.fromBlocks(markdownToBlocks(markdown), author, options);
+  }
+  /** Make a document from blocks in ProseMirror JSON form. Blocks that the schema does not allow fail with INVALID_INPUT. */
+  static fromBlocks(content, author, options) {
     const who = checkAuthor(author);
+    try {
+      if (content.length > 0) schema.nodeFromJSON({ type: "doc", content }).check();
+    } catch (error) {
+      throw new DocError("INVALID_INPUT", `the blocks do not fit the document schema: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const doc = new _AgenticDoc(new Y2.Doc(), options);
-    const content = markdownToBlocks(markdown);
     doc.change("create", who, () => {
       doc.fragment.insert(0, toYBlocks(content));
       return { inserted: content.length, deleted: 0 };
@@ -397,7 +409,7 @@ var AgenticDoc = class _AgenticDoc {
   change(op, author, run, extra = {}) {
     const at = this.now().toISOString();
     this.ydoc.transact(() => {
-      const entry = { op, at, author, ...run(), ...extra };
+      const entry = { op, at, author, client: this.ydoc.clientID, ...run(), ...extra };
       if (entry.section === void 0) delete entry.section;
       this.log.push([entry]);
     });
@@ -546,199 +558,14 @@ var AgenticDoc = class _AgenticDoc {
   }
 };
 
-// src/review.ts
-import * as Y3 from "yjs";
-var newId = () => globalThis.crypto.randomUUID();
-function nonEmpty(value, what) {
-  if (typeof value !== "string" || value.trim() === "") throw new DocError("INVALID_INPUT", `${what} must not be empty`);
-  return value;
-}
-function anchorFor(doc, target) {
-  if ("anchor" in target) {
-    doc.resolve(target);
-    return target.anchor;
-  }
-  return doc.anchor(target.text, target.occurrence);
-}
-function isStale(doc, anchor) {
-  try {
-    doc.resolve({ anchor });
-    return { stale: false, currentText: anchor.text };
-  } catch (error) {
-    if (!(error instanceof DocError) || error.code !== "STALE_ANCHOR") throw error;
-    return { stale: true, currentText: null };
-  }
-}
-function fieldsOf(doc, name) {
-  return doc.ydoc.getMap(name);
-}
-var optional = (map, key) => map.has(key) ? { [key]: map.get(key) } : {};
-function setAll(map, values) {
-  for (const [key, value] of Object.entries(values)) if (value !== void 0) map.set(key, value);
-}
-var Threads = class {
-  constructor(doc) {
-    this.doc = doc;
-  }
-  doc;
-  get map() {
-    return fieldsOf(this.doc, "threads");
-  }
-  get(id) {
-    const thread = this.map.get(id);
-    if (!thread) throw new DocError("NO_THREAD", `no thread with id "${id}"`);
-    return thread;
-  }
-  message(body, author) {
-    return { id: newId(), at: this.doc.now().toISOString(), author, body };
-  }
-  add(target, body, author) {
-    const who = checkAuthor(author);
-    nonEmpty(body, "a comment");
-    const anchor = anchorFor(this.doc, target);
-    const id = newId();
-    this.doc.ydoc.transact(() => {
-      const thread = new Y3.Map();
-      this.map.set(id, thread);
-      setAll(thread, { anchor, status: "open" });
-      const messages = new Y3.Array();
-      thread.set("messages", messages);
-      messages.push([this.message(body, who)]);
-    });
-    return id;
-  }
-  reply(id, body, author) {
-    const who = checkAuthor(author);
-    nonEmpty(body, "a reply");
-    this.get(id).get("messages").push([this.message(body, who)]);
-  }
-  setStatus(id, status, author) {
-    const who = checkAuthor(author);
-    const thread = this.get(id);
-    this.doc.ydoc.transact(() => {
-      thread.set("status", status);
-      if (status === "open") {
-        thread.delete("resolvedBy");
-        thread.delete("resolvedAt");
-      } else setAll(thread, { resolvedBy: who, resolvedAt: this.doc.now().toISOString() });
-    });
-  }
-  resolve(id, author) {
-    this.setStatus(id, "resolved", author);
-  }
-  reopen(id, author) {
-    this.setStatus(id, "open", author);
-  }
-  list(filter = {}) {
-    return [...this.map.entries()].map(([id, t]) => {
-      const anchor = t.get("anchor");
-      return {
-        id,
-        anchor,
-        status: t.get("status"),
-        ...optional(t, "resolvedBy"),
-        ...optional(t, "resolvedAt"),
-        messages: t.get("messages").toArray(),
-        ...isStale(this.doc, anchor)
-      };
-    }).filter((t) => filter.status === void 0 || t.status === filter.status).sort((a, b) => a.messages[0].at.localeCompare(b.messages[0].at) || a.id.localeCompare(b.id));
-  }
-};
-var ACCEPT_SCOPE = "docs:accept";
-var sameWho = (a, b) => a.kind === b.kind && a.name === b.name;
-var isPerson = (who) => who.kind === "human" || who.kind === "user_token";
-var mayDecide = (who) => isPerson(who) || who.scopes?.includes(ACCEPT_SCOPE) === true;
-var Suggestions = class {
-  constructor(doc) {
-    this.doc = doc;
-  }
-  doc;
-  get map() {
-    return fieldsOf(this.doc, "suggestions");
-  }
-  get(id) {
-    const fields = this.map.get(id);
-    if (!fields) throw new DocError("NO_SUGGESTION", `no suggestion with id "${id}"`);
-    return { fields, suggestion: this.read(id, fields) };
-  }
-  read(id, f) {
-    const anchor = f.get("anchor");
-    return {
-      id,
-      kind: f.get("kind"),
-      ...optional(f, "at"),
-      anchor,
-      replacement: f.get("replacement"),
-      author: f.get("author"),
-      createdAt: f.get("createdAt"),
-      status: f.get("status"),
-      ...optional(f, "decidedBy"),
-      ...optional(f, "decidedAt"),
-      stale: isStale(this.doc, anchor).stale
-    };
-  }
-  /** An `at` on the target means insert. An empty replacement means delete. */
-  add(target, replacement, author) {
-    const who = checkAuthor(author);
-    const kind = target.at ? "insert" : replacement === "" ? "delete" : "replace";
-    if (kind === "insert") nonEmpty(replacement, "an inserted text");
-    const anchor = anchorFor(this.doc, target);
-    const id = newId();
-    this.doc.ydoc.transact(() => {
-      const fields = new Y3.Map();
-      this.map.set(id, fields);
-      setAll(fields, { kind, at: target.at, anchor, replacement, author: who, createdAt: this.doc.now().toISOString(), status: "pending" });
-    });
-    return id;
-  }
-  decide(fields, status, author, at) {
-    setAll(fields, { status, decidedBy: author, decidedAt: at });
-  }
-  /**
-   * Apply the edit as the accepting author. The check and the edit share one transaction. Accepting
-   * an accepted suggestion changes nothing. A stale anchor throws and the suggestion stays pending.
-   */
-  accept(id, author) {
-    const who = checkAuthor(author);
-    this.doc.ydoc.transact(() => {
-      const { fields, suggestion: s } = this.get(id);
-      if (!mayDecide(author) || sameWho(s.author, who)) {
-        throw new DocError("FORBIDDEN", `${who.kind}:${who.name} cannot accept this suggestion: a person who is not its author, or an agent with the ${ACCEPT_SCOPE} scope, can`);
-      }
-      if (s.status === "accepted") return;
-      if (s.status !== "pending") throw new DocError("ALREADY_DECIDED", `suggestion "${id}" is already ${s.status}`);
-      const { at, inserted } = this.doc.edit(s.kind, { anchor: s.anchor, at: s.at }, s.replacement, who, { suggestion: { id, author: s.author } });
-      const record = { by: who, at, ...inserted };
-      this.doc.ydoc.getMap(APPLIED).set(`${id}:${this.doc.ydoc.clientID}`, record);
-      this.decide(fields, "accepted", who, at);
-    });
-  }
-  /** Same right as accept. A person can withdraw their own suggestion. An agent can never decide its own. */
-  reject(id, author) {
-    const who = checkAuthor(author);
-    this.doc.ydoc.transact(() => {
-      const { fields, suggestion: s } = this.get(id);
-      if (!mayDecide(author) || !isPerson(who) && sameWho(s.author, who)) {
-        throw new DocError("FORBIDDEN", `${who.kind}:${who.name} cannot reject this suggestion: a person, or an agent with the ${ACCEPT_SCOPE} scope that did not write it, can`);
-      }
-      if (s.status !== "pending") throw new DocError("ALREADY_DECIDED", `suggestion "${id}" is already ${s.status}`);
-      this.decide(fields, "rejected", who, this.doc.now().toISOString());
-    });
-  }
-  list(filter = {}) {
-    return [...this.map.entries()].map(([id, f]) => this.read(id, f)).filter((s) => filter.status === void 0 || s.status === filter.status).sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
-  }
-};
-
 export {
   DOC_ERROR_CODES,
   DocError,
   markdownToBlocks,
   blocksToMarkdown,
   schema,
-  PRINCIPAL_KINDS,
+  APPLIED,
+  checkAuthor,
   parseAuthor,
-  AgenticDoc,
-  Threads,
-  Suggestions
+  AgenticDoc
 };

package/dist/{chunk-FZA5LQV3.js → chunk-JBAQEIOH.js}

@@ -1,10 +1,15 @@
 import {
-  AgenticDoc,
-  DocError,
-  PRINCIPAL_KINDS,
   Suggestions,
-  Threads
-} from "./chunk-YBBQNCMC.js";
+  Threads,
+  isPerson
+} from "./chunk-5IQX2W52.js";
+import {
+  AgenticDoc,
+  DocError
+} from "./chunk-GQ5E6T7Z.js";
+import {
+  PRINCIPAL_KINDS
+} from "./chunk-DWVJIKVT.js";
 
 // src/service.ts
 import * as Y from "yjs";
@@ -16,7 +21,10 @@ 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 ROOTS = /* @__PURE__ */ new Set(["default", "edits", "suggestions", "threads", "applied", "__tiptap_position_migrations:root:default"]);
+var MAX_TITLE = 120;
+var REMOVE_SCOPE = "docs:remove";
+var MAX_LISTED = 500;
 var DocsService = class {
   constructor(ports, options = {}) {
     this.options = options;
@@ -47,7 +55,7 @@ var DocsService = class {
    * 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) {
+  async checkpoint(id, update, author, options = {}) {
     const key = this.key(id);
     const scratch = new Y.Doc();
     try {
@@ -62,6 +70,7 @@ var DocsService = class {
     for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
       const found = await this.blobs.get(key);
       if (!found) {
+        if (options.create === false) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
         const created = AgenticDoc.fromUpdate(update, this.options);
         const fresh = this.checked(id, created);
         this.fits(id, fresh);
@@ -73,7 +82,10 @@ var DocsService = class {
       doc.applyUpdate(update);
       const merged = this.checked(id, doc);
       this.fits(id, merged);
-      if (await this.blobs.put(key, merged, { ifMatch: found.version })) return;
+      if (await this.blobs.put(key, merged, { ifMatch: found.version })) {
+        await this.touch(id, author);
+        return;
+      }
     }
     throw new DocError("CONFLICT", `document "${id}" kept changing; try again`);
   }
@@ -86,7 +98,7 @@ var DocsService = class {
     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");
+      if (!doc.edits().every((e) => isObject(e) && isWho(e.author) && isString(e.at) && isString(e.op) && (e.client === void 0 || Number.isSafeInteger(e.client) && e.client >= 0))) 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));
@@ -108,9 +120,71 @@ var DocsService = class {
   }
   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() });
+      if (await tx.get(CATALOG, id) === null) {
+        const now = Date.now();
+        const who = { kind: author.kind, name: author.name };
+        await tx.put(CATALOG, id, { createdBy: who, createdAt: now, updatedAt: now, updatedBy: who });
+      }
+    });
+  }
+  /**
+   * Record a save. The catalog is a side record that follows the blob, so a failure here never fails a save that worked:
+   * the caller would repeat a change that is not safe to repeat. A document with no catalog entry stays without one.
+   */
+  async touch(id, author) {
+    if (!author) return;
+    try {
+      await this.store.transaction(async (tx) => {
+        const entry = await tx.get(CATALOG, id);
+        if (entry !== null) await tx.put(CATALOG, id, { ...entry, updatedAt: Date.now(), updatedBy: { kind: author.kind, name: author.name } });
+      });
+    } catch {
+    }
+  }
+  /** Every cataloged document, newest first, up to ${MAX_LISTED}. A damaged entry is skipped, so one bad entry never hides the list. */
+  async list() {
+    const found = [];
+    let cursor;
+    do {
+      const page = await this.store.query(CATALOG, { orderBy: { field: "createdAt", direction: "desc" }, limit: 100, cursor });
+      for (const { id, data } of page.items) {
+        const entry = isObject(data) ? data : {};
+        const { createdBy, createdAt } = entry;
+        if (!isWho(createdBy) || typeof createdAt !== "number") continue;
+        const by = entry.updatedBy;
+        if (by !== void 0 && !isWho(by)) continue;
+        found.push({ id, title: typeof entry.title === "string" && entry.title !== "" ? entry.title : id, createdBy, createdAt, updatedAt: typeof entry.updatedAt === "number" ? entry.updatedAt : createdAt, updatedBy: by ?? createdBy });
+      }
+      cursor = page.nextCursor;
+    } while (cursor !== void 0 && found.length < MAX_LISTED);
+    return found.slice(0, MAX_LISTED);
+  }
+  /** Give the document a name. It does not change the text. */
+  async rename(id, title, author) {
+    const key = this.key(id);
+    const clean = title.trim();
+    if (clean === "" || [...clean].length > MAX_TITLE || /[\u0000-\u001f\u007f-\u009f\u00ad\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/.test(clean)) {
+      throw new DocError("INVALID_INPUT", `a title is 1 to ${MAX_TITLE} characters of plain text`);
+    }
+    const found = await this.blobs.get(key);
+    if (!found) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
+    const who = { kind: author.kind, name: author.name };
+    const first = AgenticDoc.fromUpdate(found.data, this.options).edits()[0];
+    const created = first ? { createdBy: { kind: first.author.kind, name: first.author.name }, createdAt: Date.parse(first.at) } : { createdBy: who, createdAt: Date.now() };
+    await this.store.transaction(async (tx) => {
+      const entry = await tx.get(CATALOG, id);
+      const now = Date.now();
+      await tx.put(CATALOG, id, entry === null ? { ...created, createdAt: Number.isFinite(created.createdAt) ? created.createdAt : now, title: clean, updatedAt: now, updatedBy: who } : { ...entry, title: clean, updatedAt: now, updatedBy: who });
     });
   }
+  /** Delete the document and its catalog entry. An agent needs the remove scope. A live room keeps its own copy of the text. */
+  async remove(id, author) {
+    const key = this.key(id);
+    if (!isPerson(author) && author.scopes?.includes(REMOVE_SCOPE) !== true) throw new DocError("FORBIDDEN", `an agent needs the ${REMOVE_SCOPE} scope to remove a document`);
+    if (!await this.blobs.head(key)) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
+    await this.store.delete(CATALOG, id);
+    await this.blobs.delete(key);
+  }
   /** 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);
@@ -131,14 +205,17 @@ var DocsService = class {
    * 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) {
+  async write(id, run, author) {
     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;
+      if (await this.blobs.put(key, doc.encode(), { ifMatch: found.version })) {
+        await this.touch(id, author);
+        return result;
+      }
     }
     throw new DocError("CONFLICT", `document "${id}" kept changing; try again`);
   }