agentic-documents 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 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.2.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
 
@@ -147,7 +200,7 @@ curl "$URL/api/v1/docs/plan/export?format=html" -H "authorization: Bearer $TOKEN
   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
+};

package/dist/chunk-GYQFTF2E.js

@@ -0,0 +1,389 @@
+import {
+  DocError,
+  Suggestions,
+  Threads
+} from "./chunk-YBBQNCMC.js";
+
+// src/odt.ts
+import { strToU8, zipSync } from "fflate";
+
+// src/package.ts
+var IMAGE_TYPES = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp" };
+var DATA_IMAGE = /^data:(image\/(?:png|jpeg|gif|webp));base64,([a-z0-9+/=]+)$/i;
+var FIXED_DATE = new Date(2e3, 0, 1);
+function toBase64(bytes) {
+  let text2 = "";
+  for (let i = 0; i < bytes.length; i += 32768) text2 += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(text2);
+}
+var fromBase64 = (value) => Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
+function imageSize(b) {
+  const v = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  if (b.length > 24 && v.getUint32(0) === 2303741511) return [v.getUint32(16), v.getUint32(20)];
+  if (b.length > 10 && v.getUint32(0) === 1195984440) return [v.getUint16(6, true), v.getUint16(8, true)];
+  if (b.length > 4 && v.getUint16(0) === 65496) {
+    for (let i = 2; i + 9 < b.length && b[i] === 255; i += 2 + v.getUint16(i + 2)) {
+      if (b[i + 1] >= 192 && b[i + 1] <= 207 && ![196, 200, 204].includes(b[i + 1])) return [v.getUint16(i + 7), v.getUint16(i + 5)];
+    }
+  }
+  return void 0;
+}
+
+// src/xml.ts
+var xmlEscape = (value) => String(value ?? "").replace(/[^\u0009\u000A\u000D -퟿-�\u{10000}-\u{10FFFF}]/gu, "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+var safeHref = (value) => {
+  const href = String(value ?? "").trim();
+  return /^(https?:|mailto:|#|[^:]*$)/i.test(href) ? href : void 0;
+};
+
+// src/odt.ts
+var ODT_MIME = "application/vnd.oasis.opendocument.text";
+var NS = 'xmlns:office="urn:oasis:names:tc:opendocument:xmlns:office:1.0" xmlns:text="urn:oasis:names:tc:opendocument:xmlns:text:1.0" xmlns:table="urn:oasis:names:tc:opendocument:xmlns:table:1.0" xmlns:style="urn:oasis:names:tc:opendocument:xmlns:style:1.0" xmlns:fo="urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:draw="urn:oasis:names:tc:opendocument:xmlns:drawing:1.0" xmlns:svg="urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0" xmlns:meta="urn:oasis:names:tc:opendocument:xmlns:meta:1.0" xmlns:manifest="urn:oasis:names:tc:opendocument:xmlns:manifest:1.0" office:version="1.3"';
+var XML = '<?xml version="1.0" encoding="UTF-8"?>\n';
+var SPANS = { bold: "B", italic: "I", strike: "S", code: "Source_20_Text" };
+var TASK = ["\u2610 ", "\u2611 "];
+var LEVELS = (kind) => Array.from(
+  { length: 10 },
+  (_, i) => kind === "bullet" ? `<text:list-level-style-bullet text:level="${i + 1}" text:bullet-char="\u2022"><style:list-level-properties text:list-level-position-and-space-mode="label-alignment"><style:list-level-label-alignment text:label-followed-by="listtab" fo:margin-left="${(i + 1) * 0.63}cm" fo:text-indent="-0.63cm"/></style:list-level-properties></text:list-level-style-bullet>` : `<text:list-level-style-number text:level="${i + 1}" style:num-suffix="." style:num-format="1"><style:list-level-properties text:list-level-position-and-space-mode="label-alignment"><style:list-level-label-alignment text:label-followed-by="listtab" fo:margin-left="${(i + 1) * 0.63}cm" fo:text-indent="-0.63cm"/></style:list-level-properties></text:list-level-style-number>`
+).join("");
+var SIZES = [24, 18, 14, 12, 11, 10];
+var STYLES = `${XML}<office:document-styles ${NS}><office:styles>
+<style:style style:name="Standard" style:family="paragraph" style:class="text"/>
+${SIZES.map((s, i) => `<style:style style:name="Heading_20_${i + 1}" style:display-name="Heading ${i + 1}" style:family="paragraph" style:parent-style-name="Standard" style:class="text"><style:text-properties fo:font-size="${s}pt" fo:font-weight="bold"/></style:style>`).join("\n")}
+<style:style style:name="Quotations" style:family="paragraph" style:parent-style-name="Standard" style:class="html"><style:paragraph-properties fo:margin-left="1cm" fo:margin-right="1cm"/></style:style>
+<style:style style:name="Preformatted_20_Text" style:display-name="Preformatted Text" style:family="paragraph" style:parent-style-name="Standard" style:class="html"><style:text-properties fo:font-family="Liberation Mono, Courier New, monospace" fo:font-size="10pt"/></style:style>
+<style:style style:name="Horizontal_20_Line" style:display-name="Horizontal Line" style:family="paragraph" style:parent-style-name="Standard" style:class="html"><style:paragraph-properties fo:border-bottom="0.5pt solid #808080" fo:padding="0cm" fo:margin-bottom="0.3cm"/></style:style>
+<style:style style:name="Source_20_Text" style:display-name="Source Text" style:family="text"><style:text-properties fo:font-family="Liberation Mono, Courier New, monospace"/></style:style>
+</office:styles></office:document-styles>`;
+var AUTO = `<style:style style:name="B" style:family="text"><style:text-properties fo:font-weight="bold"/></style:style>
+<style:style style:name="I" style:family="text"><style:text-properties fo:font-style="italic"/></style:style>
+<style:style style:name="S" style:family="text"><style:text-properties style:text-line-through-style="solid"/></style:style>
+<text:list-style style:name="Bullets">${LEVELS("bullet")}</text:list-style>
+<text:list-style style:name="Numbering">${LEVELS("number")}</text:list-style>`;
+var spaced = (s) => xmlEscape(s).replace(/\t/g, "<text:tab/>").replace(/\n/g, "<text:line-break/>").replace(/ +/g, (run, at, all) => at === 0 || at + run.length === all.length ? `<text:s text:c="${run.length}"/>` : run.length > 1 ? ` <text:s text:c="${run.length - 1}"/>` : run);
+function image(node, out) {
+  const alt = String(node.attrs?.alt ?? "");
+  const found = DATA_IMAGE.exec(String(node.attrs?.src ?? "").trim());
+  let data;
+  try {
+    data = found ? fromBase64(found[2]) : void 0;
+  } catch {
+    data = void 0;
+  }
+  if (!found || !data) return spaced(`[image${alt ? `: ${alt}` : ""}]`);
+  const ext = Object.keys(IMAGE_TYPES).find((k) => IMAGE_TYPES[k] === found[1].toLowerCase());
+  const name = `Image${out.images.length + 1}`;
+  out.images.push({ name: `Pictures/${name}.${ext}`, type: found[1].toLowerCase(), data });
+  const [w, h] = imageSize(data) ?? [320, 240];
+  const scale = Math.min(1, 16 / (w * 2.54 / 96));
+  const cm = (px) => (px * 2.54 * scale / 96).toFixed(2);
+  return `<draw:frame draw:name="${name}" text:anchor-type="as-char" svg:width="${cm(w)}cm" svg:height="${cm(h)}cm"><draw:image xlink:href="Pictures/${name}.${ext}" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad"/><svg:title>${xmlEscape(alt)}</svg:title></draw:frame>`;
+}
+function inline(nodes, out) {
+  return nodes.map((node) => {
+    if (node.type === "hardBreak") return "<text:line-break/>";
+    if (node.type === "image") return image(node, out);
+    return (node.marks ?? []).reduce((xml, mark) => {
+      if (mark.type === "link") {
+        const href = safeHref(mark.attrs?.href);
+        return href ? `<text:a xlink:type="simple" xlink:href="${xmlEscape(href)}">${xml}</text:a>` : xml;
+      }
+      return SPANS[mark.type] ? `<text:span text:style-name="${SPANS[mark.type]}">${xml}</text:span>` : xml;
+    }, spaced(node.text ?? ""));
+  }).join("");
+}
+function block(node, out, style = "Standard") {
+  const kids = node.content ?? [];
+  const p = (name, inner) => `<text:p text:style-name="${name}">${inner}</text:p>`;
+  switch (node.type) {
+    case "paragraph":
+      return p(style, inline(kids, out));
+    case "heading": {
+      const level = Math.min(6, Math.max(1, Math.trunc(Number(node.attrs?.level)) || 1));
+      return `<text:h text:style-name="Heading_20_${level}" text:outline-level="${level}">${inline(kids, out)}</text:h>`;
+    }
+    case "blockquote":
+      return kids.map((k) => block(k, out, "Quotations")).join("");
+    case "codeBlock":
+      return p("Preformatted_20_Text", spaced(kids.map((k) => k.text ?? "").join("")));
+    case "horizontalRule":
+      return `<text:p text:style-name="Horizontal_20_Line"/>`;
+    case "bulletList":
+    case "orderedList":
+    case "taskList": {
+      const ordered = node.type === "orderedList";
+      const start = Number(node.attrs?.start ?? 1);
+      const items = kids.map((item, i) => {
+        const [first, ...rest] = item.content ?? [];
+        const mark = item.type === "taskItem" && first ? { ...first, content: [{ type: "text", text: TASK[item.attrs?.checked ? 1 : 0] }, ...first.content ?? []] } : first;
+        const attr = ordered && i === 0 && start !== 1 ? ` text:start-value="${Math.trunc(start) || 1}"` : "";
+        return `<text:list-item${attr}>${[mark, ...rest].filter(Boolean).map((k) => block(k, out)).join("")}</text:list-item>`;
+      });
+      return `<text:list text:style-name="${ordered ? "Numbering" : "Bullets"}">${items.join("")}</text:list>`;
+    }
+    case "table": {
+      const cols = Math.max(0, ...kids.map((r) => r.content?.length ?? 0));
+      const row = (r) => `<table:table-row>${(r.content ?? []).map((c) => `<table:table-cell office:value-type="string">${(c.content ?? []).map((b) => block(b, out)).join("")}</table:table-cell>`).join("")}</table:table-row>`;
+      const header = kids[0]?.content?.length && kids[0].content.every((c) => c.type === "tableHeader");
+      const rows = header ? `<table:table-header-rows>${row(kids[0])}</table:table-header-rows>${kids.slice(1).map(row).join("")}` : kids.map(row).join("");
+      return `<table:table table:name="Table${++out.tables}">${cols ? `<table:table-column table:number-columns-repeated="${cols}"/>` : ""}${rows}</table:table>`;
+    }
+    default:
+      return "";
+  }
+}
+function exportOdt(blocks) {
+  const out = { images: [], tables: 0 };
+  const body = blocks.map((b) => block(b, out)).join("\n");
+  const content2 = `${XML}<office:document-content ${NS}><office:automatic-styles>${AUTO}</office:automatic-styles><office:body><office:text>${body}</office:text></office:body></office:document-content>`;
+  const entries = [
+    `<manifest:file-entry manifest:full-path="/" manifest:version="1.3" manifest:media-type="${ODT_MIME}"/>`,
+    ...["content.xml", "styles.xml", "meta.xml"].map((n) => `<manifest:file-entry manifest:full-path="${n}" manifest:media-type="text/xml"/>`),
+    ...out.images.map((i) => `<manifest:file-entry manifest:full-path="${i.name}" manifest:media-type="${i.type}"/>`)
+  ];
+  const meta = `${XML}<office:document-meta ${NS}><office:meta><meta:generator>agentic-documents</meta:generator></office:meta></office:document-meta>`;
+  const part = (text2) => [strToU8(text2), { mtime: FIXED_DATE }];
+  return zipSync({
+    mimetype: [strToU8(ODT_MIME), { level: 0, mtime: FIXED_DATE }],
+    // first and stored, so file sniffers can read it
+    "META-INF/manifest.xml": part(`${XML}<manifest:manifest ${NS}>${entries.join("")}</manifest:manifest>`),
+    "content.xml": part(content2),
+    "styles.xml": part(STYLES),
+    "meta.xml": part(meta),
+    ...Object.fromEntries(out.images.map((i) => [i.name, [i.data, { mtime: FIXED_DATE }]]))
+  });
+}
+
+// src/export.ts
+var EXPORT_FORMATS = ["md", "html", "odt"];
+var esc = (s) => String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+var url = (value) => /^(https?:|mailto:|[^:]*$)/i.test(String(value ?? "").trim()) ? esc(String(value).trim()) : "#";
+var integer = (value, fallback) => Number.isFinite(Number(value)) ? Math.trunc(Number(value)) : fallback;
+var INLINE_IMAGE = /^data:image\/(png|jpeg|gif|webp);base64,[a-z0-9+/=]+$/i;
+var textOf = (node) => node.text ?? (node.content ?? []).map(textOf).join("");
+var MARK_TAGS = { bold: "strong", italic: "em", strike: "s", code: "code" };
+function image2(node, remote) {
+  const src = String(node.attrs?.src ?? "").trim();
+  const alt = esc(node.attrs?.alt);
+  if (INLINE_IMAGE.test(src)) return `<img src="${src}" alt="${alt}">`;
+  if (remote && url(src) !== "#") return `<img src="${url(src)}" alt="${alt}">`;
+  return `<span class="image">[image${alt ? `: ${alt}` : ""}]</span>`;
+}
+function inline2(node, remote) {
+  if (node.type === "hardBreak") return "<br>";
+  if (node.type === "image") return image2(node, remote);
+  return (node.marks ?? []).reduce((html, mark) => {
+    if (mark.type === "link") return `<a href="${url(mark.attrs?.href)}">${html}</a>`;
+    const tag = MARK_TAGS[mark.type];
+    return tag ? `<${tag}>${html}</${tag}>` : html;
+  }, esc(node.text));
+}
+function block2(node, remote) {
+  const kids = (node.content ?? []).map((n) => block2(n, remote)).join("");
+  const text2 = (node.content ?? []).map((n) => inline2(n, remote)).join("");
+  switch (node.type) {
+    case "paragraph":
+      return `<p>${text2}</p>
+`;
+    case "heading": {
+      const level = Math.min(6, Math.max(1, integer(node.attrs?.level, 1)));
+      return `<h${level}>${text2}</h${level}>
+`;
+    }
+    case "blockquote":
+      return `<blockquote>
+${kids}</blockquote>
+`;
+    case "codeBlock": {
+      const lang = node.attrs?.language ? ` class="language-${esc(node.attrs.language)}"` : "";
+      return `<pre><code${lang}>${esc(textOf(node))}</code></pre>
+`;
+    }
+    case "horizontalRule":
+      return "<hr>\n";
+    case "bulletList":
+    case "taskList":
+      return `<ul>
+${kids}</ul>
+`;
+    case "orderedList":
+      return `<ol start="${integer(node.attrs?.start, 1)}">
+${kids}</ol>
+`;
+    case "listItem":
+      return `<li>${kids}</li>
+`;
+    case "taskItem":
+      return `<li><input type="checkbox" disabled${node.attrs?.checked ? " checked" : ""}> ${kids}</li>
+`;
+    case "table":
+      return `<table>
+${kids}</table>
+`;
+    case "tableRow":
+      return `<tr>${kids}</tr>
+`;
+    case "tableHeader":
+      return `<th>${kids}</th>`;
+    case "tableCell":
+      return `<td>${kids}</td>`;
+    default:
+      return "";
+  }
+}
+function toHtml(blocks, remote) {
+  const title = textOf(blocks.find((b) => b.type === "heading") ?? { type: "doc" }) || "Document";
+  const css = "body{font-family:system-ui,sans-serif;max-width:46rem;margin:2rem auto;padding:0 1rem;line-height:1.5}table{border-collapse:collapse}td,th{border:1px solid #888;padding:.25rem .5rem}pre{overflow:auto}";
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${esc(title)}</title>
+<style>${css}</style>
+</head>
+<body>
+${blocks.map((b) => block2(b, remote)).join("")}</body>
+</html>
+`;
+}
+function exportDoc(doc, format, options = {}) {
+  if (format === "html") {
+    return { format, contentType: "text/html; charset=utf-8", encoding: "utf8", data: toHtml(doc.toJSON().content ?? [], options.remoteImages === true) };
+  }
+  if (format === "odt") return { format, contentType: ODT_MIME, encoding: "base64", data: toBase64(exportOdt(doc.toJSON().content ?? [])) };
+  return { format, contentType: "text/markdown; charset=utf-8", encoding: "utf8", data: doc.toMarkdown() };
+}
+
+// src/commands.ts
+import { z } from "zod";
+var id = z.string().describe("Document id.");
+var content = z.string().describe("Markdown for a section target. Plain text for a text target.");
+var text = z.string().describe("Exact text to match. It must sit inside one block.");
+var occurrence = z.coerce.number().int().min(1).optional().describe("Which match, counting from 1, when the text matches more than once.");
+var side = z.enum(["before", "after"]).optional().describe("Put the new text before or after the match.");
+var thread = z.string().describe("Thread id.");
+var where = {
+  section: z.string().optional().describe("Section id from the outline. Use this or text."),
+  text: text.optional(),
+  occurrence,
+  at: z.enum(["start", "end", "before", "after"]).optional().describe("Insert at the start or end of a section, or before or after matched text.")
+};
+function target(input) {
+  const { section, text: text2, occurrence: occurrence2, at } = input;
+  if (section !== void 0) {
+    if (at !== void 0 && at !== "start" && at !== "end") throw new DocError("INVALID_INPUT", `at "${at}" does not fit a section; use start or end`);
+    return { section, at };
+  }
+  if (text2 !== void 0) {
+    if (at === "start" || at === "end") throw new DocError("INVALID_INPUT", `at "${at}" does not fit text; use before or after`);
+    return { text: text2, occurrence: occurrence2, at };
+  }
+  throw new DocError("INVALID_INPUT", "pass section or text");
+}
+var textTarget = (input) => ({
+  text: input.text,
+  occurrence: input.occurrence,
+  at: input.at
+});
+function command(name, description, readOnly, shape, run) {
+  return {
+    name,
+    description,
+    shape,
+    readOnly,
+    async run(service, raw, author) {
+      const parsed = z.object(shape).strict().safeParse(raw);
+      if (!parsed.success) {
+        throw new DocError("INVALID_INPUT", parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; "));
+      }
+      return run(service, parsed.data, author);
+    }
+  };
+}
+var ok = () => ({ ok: true });
+var commands = [
+  command("new", "Create a document, from Markdown if given.", false, { id, markdown: z.string().optional() }, async (s, i, a) => {
+    await s.create(i.id, i.markdown ?? "", a);
+    return { id: i.id };
+  }),
+  command(
+    "read",
+    "Read a document, or one section, as Markdown.",
+    true,
+    { id, section: where.section },
+    (s, i) => s.read(i.id, (d) => i.section ? d.readSection(i.section) : d.toMarkdown())
+  ),
+  command("outline", "List sections with their ids, levels, and titles.", true, { id }, (s, i) => s.read(i.id, (d) => d.outline())),
+  command("edits", "Read the edit log. It names each author kind and holds no content.", true, { id }, (s, i) => s.read(i.id, (d) => d.edits())),
+  command("insert", "Insert Markdown into a section, or plain text next to matched text.", false, { id, ...where, content }, async (s, i, a) => {
+    await s.write(i.id, (d) => d.insert(target(i), i.content, a));
+    return ok();
+  }),
+  command("replace", "Replace a section body (the heading stays), or the matched text.", false, { id, ...where, content }, async (s, i, a) => {
+    await s.write(i.id, (d) => d.replace(target(i), i.content, a));
+    return ok();
+  }),
+  command("delete", "Delete a section with its subsections, or the matched text.", false, { id, ...where }, async (s, i, a) => {
+    await s.write(i.id, (d) => d.delete(target(i), a));
+    return ok();
+  }),
+  command("append", "Add Markdown at the end of the document.", false, { id, content: z.string() }, async (s, i, a) => {
+    await s.write(i.id, (d) => d.append(i.content, a));
+    return ok();
+  }),
+  command("suggest", "Suggest an edit to matched text. An empty replacement suggests a delete.", false, { id, text, occurrence, at: side, replacement: z.string() }, async (s, i, a) => ({
+    suggestion: await s.write(i.id, (d) => new Suggestions(d).add(textTarget(i), i.replacement, a))
+  })),
+  command(
+    "suggestions",
+    "List suggested edits.",
+    true,
+    { id, status: z.enum(["pending", "accepted", "rejected"]).optional() },
+    (s, i) => s.read(i.id, (d) => new Suggestions(d).list({ status: i.status }))
+  ),
+  command("accept", "Accept a suggestion. The text changes now.", false, { id, suggestion: z.string() }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Suggestions(d).accept(i.suggestion, a));
+    return ok();
+  }),
+  command("reject", "Reject a suggestion. The text stays.", false, { id, suggestion: z.string() }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Suggestions(d).reject(i.suggestion, a));
+    return ok();
+  }),
+  command("comment", "Start a comment thread on matched text.", false, { id, text, occurrence, body: z.string() }, async (s, i, a) => ({
+    thread: await s.write(i.id, (d) => new Threads(d).add(textTarget(i), i.body, a))
+  })),
+  command("reply", "Reply in a comment thread.", false, { id, thread, body: z.string() }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Threads(d).reply(i.thread, i.body, a));
+    return ok();
+  }),
+  command("resolve", "Resolve a comment thread.", false, { id, thread }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Threads(d).resolve(i.thread, a));
+    return ok();
+  }),
+  command("reopen", "Reopen a comment thread.", false, { id, thread }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Threads(d).reopen(i.thread, a));
+    return ok();
+  }),
+  command(
+    "threads",
+    "List comment threads with their messages.",
+    true,
+    { id, status: z.enum(["open", "resolved"]).optional() },
+    (s, i) => s.read(i.id, (d) => new Threads(d).list({ status: i.status }))
+  ),
+  command(
+    "export",
+    "Export the document as Markdown (md), self-contained HTML (html), or OpenDocument text (odt, base64). HTML shows no remote image unless remoteImages is true.",
+    true,
+    { id, format: z.enum(EXPORT_FORMATS), remoteImages: z.union([z.boolean(), z.enum(["true", "false"])]).optional() },
+    (s, i) => s.read(i.id, (d) => exportDoc(d, i.format, { remoteImages: i.remoteImages === true || i.remoteImages === "true" }))
+  )
+];
+
+export {
+  ODT_MIME,
+  exportOdt,
+  EXPORT_FORMATS,
+  exportDoc,
+  commands
+};