agentic-documents 0.3.0 → 0.5.0

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

@@ -1,10 +1,13 @@
+import {
+  Suggestions,
+  Threads,
+  isPerson
+} from "./chunk-UPEGODUV.js";
 import {
   AgenticDoc,
   DocError,
-  PRINCIPAL_KINDS,
-  Suggestions,
-  Threads
-} from "./chunk-YBBQNCMC.js";
+  PRINCIPAL_KINDS
+} from "./chunk-6QOYS63L.js";
 
 // src/service.ts
 import * as Y from "yjs";
@@ -16,7 +19,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 +53,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 +68,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 +80,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 +96,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 +118,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 +203,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`);
   }

package/dist/cli.js

@@ -2,24 +2,26 @@
 import {
   createFileBlobs,
   createFileStore
-} from "./chunk-TFCRPEEM.js";
+} from "./chunk-7R7ZPPRF.js";
 import {
   LiveService,
   whoAmI
-} from "./chunk-R5XUTBC3.js";
+} from "./chunk-E7B6T5WN.js";
 import {
   DocsService
-} from "./chunk-FZA5LQV3.js";
+} from "./chunk-YNHZCIGO.js";
 import {
   VERSION
 } from "./chunk-5Y66UCTE.js";
 import {
   commands
-} from "./chunk-GYQFTF2E.js";
+} from "./chunk-S6MQDWFK.js";
+import "./chunk-L6W2AQUF.js";
+import "./chunk-UPEGODUV.js";
 import {
   DocError,
   parseAuthor
-} from "./chunk-YBBQNCMC.js";
+} from "./chunk-6QOYS63L.js";
 
 // src/cli.ts
 import { readFileSync, writeFileSync } from "fs";
@@ -118,7 +120,7 @@ async function main(argv, env = process.env) {
     author = named && scopes?.length ? { ...named, scopes } : named;
   }
   if (name === "mcp") {
-    const { startMcp } = await import("./mcp-P2C75IIG.js");
+    const { startMcp } = await import("./mcp-ESSEG46C.js");
     await startMcp(service, author);
     return 0;
   }

package/dist/client.d.ts

@@ -0,0 +1,188 @@
+import { P as PrincipalKind, S as Section, E as EditEntry } from './doc-mJPajXEQ.js';
+export { A as Anchor } from './doc-mJPajXEQ.js';
+import { E as ExportFormat } from './export-Cwx276UP.js';
+import { D as DocErrorCode, S as Suggestion, T as Thread } from './review-Hgq8OgvD.js';
+import { D as DocSummary } from './service-CqKE9DKz.js';
+import 'yjs';
+import 'agentic-identity';
+
+/** The place an edit goes: a section id, or exact text. */
+type Where = {
+    section: string;
+    at?: "start" | "end";
+} | {
+    text: string;
+    occurrence?: number;
+    at?: "before" | "after";
+};
+interface Me {
+    kind: PrincipalKind;
+    name: string;
+    scopes: string[];
+    role: "editor" | "viewer";
+}
+interface Contributor {
+    name: string;
+    kind: string;
+    machine: boolean;
+}
+interface ClientOptions {
+    /** The Worker origin, for example `https://docs.example.com`. */
+    baseUrl: string;
+    /** A bearer token. It sets the author and the role. */
+    token: string;
+    /** Your own `fetch`. The default is the global one. */
+    fetch?: typeof fetch;
+}
+/** Every call takes this last. `signal` cancels the request. */
+interface CallOptions {
+    signal?: AbortSignal;
+}
+/** The codes a call can fail with. `BAD_RESPONSE` means a 2xx reply that does not have the expected shape. */
+type DocsApiErrorCode = DocErrorCode | "UNAUTHENTICATED" | "NOT_FOUND" | "UPGRADE_REQUIRED" | "INTERNAL" | "HTTP_ERROR" | "BAD_RESPONSE";
+/** The API refused a call, or sent a reply that is not what it should be. `code` is the API error code. */
+declare class DocsApiError extends Error {
+    readonly code: DocsApiErrorCode;
+    readonly status: number;
+    readonly matches: {
+        occurrence: number;
+        context: string;
+    }[];
+    constructor(code: DocsApiErrorCode, message: string, status: number, matches?: {
+        occurrence: number;
+        context: string;
+    }[]);
+}
+/**
+ * A client for one Worker. A call that fails with an API error throws `DocsApiError`. A network
+ * failure or an abort throws what `fetch` throws. The client never retries: a write is not safe to repeat.
+ */
+declare function createClient(options: ClientOptions): {
+    /** `GET /health`. It needs no token, but the client sends it anyway. */
+    health(call?: CallOptions): Promise<{
+        ok: boolean;
+        pack: string;
+    }>;
+    /** `GET /api/v1/me`: who the token stands for. */
+    me: (call?: CallOptions) => Promise<Me>;
+    /** `POST /api/v1/docs`. */
+    create: (input: {
+        id: string;
+        markdown?: string;
+    }, call?: CallOptions) => Promise<{
+        id: string;
+    }>;
+    /** `GET /api/v1/docs`: documents with titles, creators, and last edits. */
+    list: (call?: CallOptions) => Promise<DocSummary[]>;
+    /** `POST /rename`: give a document a title. */
+    rename: (id: string, input: {
+        title: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    /** `POST /remove`: delete a document. An agent needs the `docs:remove` scope. */
+    remove: (id: string, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    /** `GET /read`: the whole document, or one section, as Markdown. */
+    read(id: string, input?: {
+        section?: string;
+    }, call?: CallOptions): Promise<string>;
+    outline: (id: string, call?: CallOptions) => Promise<Section[]>;
+    edits: (id: string, call?: CallOptions) => Promise<EditEntry[]>;
+    insert: (id: string, input: Where & {
+        content: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    replace: (id: string, input: Where & {
+        content: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    delete: (id: string, input: Where, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    append: (id: string, input: {
+        content: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    suggest: (id: string, input: {
+        text: string;
+        replacement: string;
+        occurrence?: number;
+        at?: "before" | "after";
+    }, call?: CallOptions) => Promise<{
+        suggestion: string;
+    }>;
+    suggestions: (id: string, input?: {
+        status?: Suggestion["status"];
+    }, call?: CallOptions) => Promise<Suggestion[]>;
+    accept: (id: string, input: {
+        suggestion: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    reject: (id: string, input: {
+        suggestion: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    comment: (id: string, input: {
+        text: string;
+        body: string;
+        occurrence?: number;
+    }, call?: CallOptions) => Promise<{
+        thread: string;
+    }>;
+    reply: (id: string, input: {
+        thread: string;
+        body: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    resolve: (id: string, input: {
+        thread: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    reopen: (id: string, input: {
+        thread: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    threads: (id: string, input?: {
+        status?: Thread["status"];
+    }, call?: CallOptions) => Promise<Thread[]>;
+    /** `GET /export`. `md` and `html` return text. `odt` returns the file bytes. */
+    export: {
+        (id: string, input: {
+            format: "odt";
+            remoteImages?: boolean;
+        }, call?: CallOptions): Promise<Uint8Array>;
+        (id: string, input: {
+            format: "md" | "html";
+            remoteImages?: boolean;
+        }, call?: CallOptions): Promise<string>;
+        (id: string, input: {
+            format: ExportFormat;
+            remoteImages?: boolean;
+        }, call?: CallOptions): Promise<string | Uint8Array>;
+    };
+    /** `GET /room`: who sent updates in the live room. */
+    room: (id: string, call?: CallOptions) => Promise<{
+        contributors: Contributor[];
+    }>;
+    /** `GET /state`: the stored document as a Yjs update. */
+    state(id: string, call?: CallOptions): Promise<Uint8Array>;
+    /** `POST /checkpoint`: merge a Yjs update into the stored document. It makes the document when there is none, unless `create` is false: then it fails with `NO_DOCUMENT`. */
+    checkpoint(id: string, update: Uint8Array, call?: CallOptions & {
+        create?: boolean;
+    }): Promise<{
+        ok: true;
+    }>;
+};
+type DocsClient = ReturnType<typeof createClient>;
+
+export { type CallOptions, type ClientOptions, type Contributor, DocSummary, DocsApiError, type DocsApiErrorCode, type DocsClient, EditEntry, ExportFormat, type Me, Section, Suggestion, Thread, type Where, createClient };

package/dist/client.js

@@ -0,0 +1,121 @@
+// src/client.ts
+var DocsApiError = class extends Error {
+  constructor(code, message, status, matches = []) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.matches = matches;
+    this.name = "DocsApiError";
+  }
+  code;
+  status;
+  matches;
+};
+var enc = encodeURIComponent;
+function createClient(options) {
+  if (!options.token) throw new TypeError("createClient needs a token");
+  const base = options.baseUrl.replace(/\/+$/, "");
+  const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
+  const bad = (status, why) => new DocsApiError("BAD_RESPONSE", `the server sent a reply that is not valid: ${why}`, status);
+  const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+  const isMatch = (m) => isObject(m) && typeof m.occurrence === "number" && typeof m.context === "string";
+  async function send(path, init, call = {}, expect = "application/json") {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(init.query ?? {})) if (value !== void 0) params.set(key, String(value));
+    const qs = params.toString();
+    const url = `${base}${path}${qs ? `?${qs}` : ""}`;
+    const headers = { authorization: `Bearer ${options.token}` };
+    if (init.json) headers["content-type"] = "application/json";
+    const response = await doFetch(url, { method: init.method, headers, body: init.body, signal: call.signal });
+    if (response.ok) {
+      const type = (response.headers.get("content-type") ?? "").toLowerCase();
+      if (!type.startsWith(expect)) throw bad(response.status, `unexpected content type "${type}"`);
+      return response;
+    }
+    let error;
+    try {
+      const parsed = await response.json();
+      if (isObject(parsed.error)) error = parsed.error;
+    } catch {
+    }
+    throw new DocsApiError(
+      typeof error?.code === "string" ? error.code : "HTTP_ERROR",
+      typeof error?.message === "string" ? error.message : `the server answered ${response.status}`,
+      response.status,
+      Array.isArray(error?.matches) ? error.matches.filter(isMatch) : []
+    );
+  }
+  async function json(response, check, what) {
+    let value;
+    try {
+      value = await response.json();
+    } catch {
+      throw bad(response.status, "the body is not JSON");
+    }
+    if (!check(value)) throw bad(response.status, `expected ${what}`);
+    return value;
+  }
+  const doc = (id) => `/api/v1/docs/${enc(id)}`;
+  const isOk = (v) => isObject(v) && v.ok === true;
+  const isList = (v) => Array.isArray(v) && v.every(isObject);
+  const get = async (path, query, check, what, call) => await json(await send(path, { method: "GET", query }, call), check, what);
+  const post = async (path, body, check, what, call) => await json(await send(path, { method: "POST", json: true, body: JSON.stringify(body) }, call), check, what);
+  const ok = (path, body, call) => post(path, body, isOk, "{ ok: true }", call);
+  const list = (path, query, call) => get(path, query, isList, "a list", call);
+  const withKey = (path, body, key, call) => post(path, body, (v) => isObject(v) && typeof v[key] === "string", `{ ${key}: string }`, call);
+  return {
+    /** `GET /health`. It needs no token, but the client sends it anyway. */
+    async health(call) {
+      return await json(await send("/health", { method: "GET" }, call), (v) => isObject(v) && v.ok === true && typeof v.pack === "string", "{ ok, pack }");
+    },
+    /** `GET /api/v1/me`: who the token stands for. */
+    me: (call) => get("/api/v1/me", {}, (v) => isObject(v) && typeof v.kind === "string" && typeof v.name === "string" && Array.isArray(v.scopes) && (v.role === "editor" || v.role === "viewer"), "the token identity", call),
+    /** `POST /api/v1/docs`. */
+    create: (input, call) => withKey("/api/v1/docs", input, "id", call),
+    /** `GET /api/v1/docs`: documents with titles, creators, and last edits. */
+    list: (call) => list("/api/v1/docs", {}, call),
+    /** `POST /rename`: give a document a title. */
+    rename: (id, input, call) => ok(`${doc(id)}/rename`, input, call),
+    /** `POST /remove`: delete a document. An agent needs the `docs:remove` scope. */
+    remove: (id, call) => ok(`${doc(id)}/remove`, {}, call),
+    /** `GET /read`: the whole document, or one section, as Markdown. */
+    async read(id, input = {}, call) {
+      return (await send(`${doc(id)}/read`, { method: "GET", query: input }, call, "text/markdown")).text();
+    },
+    outline: (id, call) => list(`${doc(id)}/outline`, {}, call),
+    edits: (id, call) => list(`${doc(id)}/edits`, {}, call),
+    insert: (id, input, call) => ok(`${doc(id)}/insert`, input, call),
+    replace: (id, input, call) => ok(`${doc(id)}/replace`, input, call),
+    delete: (id, input, call) => ok(`${doc(id)}/delete`, input, call),
+    append: (id, input, call) => ok(`${doc(id)}/append`, input, call),
+    suggest: (id, input, call) => withKey(`${doc(id)}/suggest`, input, "suggestion", call),
+    suggestions: (id, input = {}, call) => list(`${doc(id)}/suggestions`, input, call),
+    accept: (id, input, call) => ok(`${doc(id)}/accept`, input, call),
+    reject: (id, input, call) => ok(`${doc(id)}/reject`, input, call),
+    comment: (id, input, call) => withKey(`${doc(id)}/comment`, input, "thread", call),
+    reply: (id, input, call) => ok(`${doc(id)}/reply`, input, call),
+    resolve: (id, input, call) => ok(`${doc(id)}/resolve`, input, call),
+    reopen: (id, input, call) => ok(`${doc(id)}/reopen`, input, call),
+    threads: (id, input = {}, call) => list(`${doc(id)}/threads`, input, call),
+    /** `GET /export`. `md` and `html` return text. `odt` returns the file bytes. */
+    export: (async (id, input, call) => {
+      const response = await send(`${doc(id)}/export`, { method: "GET", query: input }, call, { md: "text/markdown", html: "text/html", odt: "application/vnd.oasis.opendocument.text" }[input.format]);
+      return input.format === "odt" ? new Uint8Array(await response.arrayBuffer()) : response.text();
+    }),
+    /** `GET /room`: who sent updates in the live room. */
+    room: (id, call) => get(`${doc(id)}/room`, {}, (v) => isObject(v) && Array.isArray(v.contributors), "{ contributors }", call),
+    /** `GET /state`: the stored document as a Yjs update. */
+    async state(id, call) {
+      return new Uint8Array(await (await send(`${doc(id)}/state`, { method: "GET" }, call, "application/octet-stream")).arrayBuffer());
+    },
+    /** `POST /checkpoint`: merge a Yjs update into the stored document. It makes the document when there is none, unless `create` is false: then it fails with `NO_DOCUMENT`. */
+    async checkpoint(id, update, call) {
+      const query = call?.create === false ? { create: false } : void 0;
+      return await json(await send(`${doc(id)}/checkpoint`, { method: "POST", body: update, query }, call), isOk, "{ ok: true }");
+    }
+  };
+}
+export {
+  DocsApiError,
+  createClient
+};

package/dist/{service-BKkxEnaJ.d.ts → doc-mJPajXEQ.d.ts}

@@ -1,5 +1,4 @@
 import * as Y from 'yjs';
-import { Blobs, Store } from 'agentic-identity';
 
 /** A ProseMirror node in JSON form, the shape y-prosemirror reads and writes. */
 interface PmNode {
@@ -59,6 +58,8 @@ interface EditEntry {
     inserted: number;
     deleted: number;
     section?: string;
+    /** The Yjs client id of the replica that made the edit. Text it wrote carries this id, so a UI can mark text by author kind. Written by the client, like the rest of the log. */
+    client?: number;
     /** Set when an accepted suggestion caused the edit. `author` is who suggested it. */
     suggestion?: {
         id: string;
@@ -88,6 +89,8 @@ declare class AgenticDoc {
     readonly now: () => Date;
     constructor(ydoc?: Y.Doc, options?: DocOptions);
     static fromMarkdown(markdown: string, author: Principal, options?: DocOptions): AgenticDoc;
+    /** Make a document from blocks in ProseMirror JSON form. Blocks that the schema does not allow fail with INVALID_INPUT. */
+    static fromBlocks(content: PmNode[], author: Principal, options?: DocOptions): AgenticDoc;
     static fromUpdate(update: Uint8Array, options?: DocOptions): AgenticDoc;
     encode(): Uint8Array;
     applyUpdate(update: Uint8Array): void;
@@ -124,58 +127,4 @@ declare class AgenticDoc {
     append(markdown: string, author: Principal): void;
 }
 
-/** What the catalog keeps for each document. The author kind stays, so machine-made work stays labeled. */
-interface DocInfo {
-    createdBy: {
-        kind: PrincipalKind;
-        name: string;
-    };
-    createdAt: number;
-}
-interface DocsPorts {
-    /** Holds each document as a Yjs update. Saves are conditional on the version that was read. */
-    blobs: Blobs;
-    /** Holds the catalog: who created each document, and when. */
-    store: Store;
-}
-/** What every command needs: make a document, read it, and change it. A live room can stand behind it as well as the ports. */
-interface DocAccess {
-    create(id: string, markdown: string, author: Principal): Promise<void>;
-    read<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
-    write<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
-}
-/** Loads and saves documents as Yjs updates in a Blobs port. The CLI, MCP server, and API share it. */
-declare class DocsService implements DocAccess {
-    private readonly options;
-    private readonly blobs;
-    private readonly store;
-    constructor(ports: DocsPorts, options?: DocOptions);
-    private key;
-    create(id: string, markdown: string, author: Principal): Promise<void>;
-    /** The stored document as a Yjs update. A live client seeds its room from it. */
-    state(id: string): Promise<Uint8Array>;
-    /**
-     * 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.
-     */
-    checkpoint(id: string, update: Uint8Array, author: Principal): Promise<void>;
-    /**
-     * 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.
-     */
-    private checked;
-    private fits;
-    private catalog;
-    /** Who created the document and when, or null when it has no catalog entry (made before the catalog, or a failed catalog write). */
-    info(id: string): Promise<DocInfo | null>;
-    read<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
-    /**
-     * 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.
-     */
-    write<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
-}
-
-export { type Anchor as A, type DocAccess as D, type EditEntry as E, type Principal as P, type Section as S, type TextTarget as T, AgenticDoc as a, type AnchorTarget as b, type PmNode as c, type DocInfo as d, type DocOptions as e, type DocsPorts as f, DocsService as g, PRINCIPAL_KINDS as h, type PrincipalKind as i, type SectionTarget as j, type Target as k, blocksToMarkdown as l, markdownToBlocks as m, parseAuthor as p };
+export { type Anchor as A, type DocOptions as D, type EditEntry as E, type PrincipalKind as P, type Section as S, type Target as T, AgenticDoc as a, type PmNode as b, type Principal as c, type AnchorTarget as d, PRINCIPAL_KINDS as e, type SectionTarget as f, type TextTarget as g, blocksToMarkdown as h, markdownToBlocks as m, parseAuthor as p };

package/dist/export-Cwx276UP.d.ts

@@ -0,0 +1,17 @@
+import { a as AgenticDoc } from './doc-mJPajXEQ.js';
+
+declare const EXPORT_FORMATS: readonly ["md", "html", "odt"];
+type ExportFormat = (typeof EXPORT_FORMATS)[number];
+interface ExportOptions {
+    /** Keep `<img>` for web and relative sources. Opening the page then asks those hosts for the image. Off by default. */
+    remoteImages?: boolean;
+}
+interface ExportResult {
+    format: ExportFormat;
+    contentType: string;
+    encoding: "utf8" | "base64";
+    data: string;
+}
+declare function exportDoc(doc: AgenticDoc, format: ExportFormat, options?: ExportOptions): ExportResult;
+
+export { type ExportFormat as E, type ExportOptions as a, EXPORT_FORMATS as b, type ExportResult as c, exportDoc as e };

package/dist/formats.d.ts

@@ -0,0 +1,49 @@
+import { Limits, TextDoc } from 'agentic-formats';
+import { D as DocOptions, a as AgenticDoc, b as PmNode, c as Principal } from './doc-mJPajXEQ.js';
+import { a as ExportOptions } from './export-Cwx276UP.js';
+import 'yjs';
+
+declare const IMPORT_FORMATS: readonly ["md", "odt", "docx"];
+type ImportFormat = (typeof IMPORT_FORMATS)[number];
+declare const FILE_FORMATS: readonly ["md", "html", "odt", "docx"];
+type FileFormat = (typeof FILE_FORMATS)[number];
+declare const DOCX_MIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+interface ImportOptions {
+    /** Caps for the file. A file that goes past one is refused, never trimmed. The defaults are those of agentic-formats. */
+    limits?: Partial<Limits>;
+    doc?: DocOptions;
+}
+interface ImportResult {
+    doc: AgenticDoc;
+    /** The title the file holds, if any. */
+    title?: string;
+    /** One line for each part of the file that the document cannot hold. Empty when nothing was lost. */
+    warnings: string[];
+}
+interface FileResult {
+    format: FileFormat;
+    contentType: string;
+    /** Text for `md` and `html`. File bytes for `odt` and `docx`. */
+    data: string | Uint8Array;
+    /** One line for each part of the document that the format cannot hold. Empty when nothing was lost. */
+    warnings: string[];
+}
+/** Map document blocks to the neutral text model. A part the model cannot hold keeps its text and adds a warning. */
+declare function toTextDoc(blocks: PmNode[], title?: string): {
+    model: TextDoc;
+    warnings: string[];
+};
+/** Map the neutral text model to document blocks. A part the editor cannot hold keeps its text and adds a warning. */
+declare function fromTextDoc(model: TextDoc): {
+    blocks: PmNode[];
+    title?: string;
+    warnings: string[];
+};
+/** Read a file into a new document. The author makes the one `create` edit, so text from an agent stays labeled. */
+declare function importFile(input: string | Uint8Array, format: ImportFormat, author: Principal, options?: ImportOptions): ImportResult;
+/** Write a document as a file. `title` goes into the ODT and DOCX metadata. */
+declare function exportFile(doc: AgenticDoc, format: FileFormat, options?: ExportOptions & {
+    title?: string;
+}): FileResult;
+
+export { DOCX_MIME, FILE_FORMATS, type FileFormat, type FileResult, IMPORT_FORMATS, type ImportFormat, type ImportOptions, type ImportResult, exportFile, fromTextDoc, importFile, toTextDoc };