agentic-documents 0.0.0-stage → 0.2.0

package/dist/chunk-R5XUTBC3.js

@@ -0,0 +1,177 @@
+import {
+  MAX_LIVE_BYTES
+} from "./chunk-FZA5LQV3.js";
+import {
+  AgenticDoc,
+  DOC_ERROR_CODES,
+  DocError,
+  PRINCIPAL_KINDS
+} from "./chunk-YBBQNCMC.js";
+
+// src/live.ts
+import * as Y from "yjs";
+import { SyncClient } from "agentic-realtime/client";
+async function refusal(response, fallback) {
+  const { error } = await response.json().catch(() => ({}));
+  const code = DOC_ERROR_CODES.find((known) => known === error?.code) ?? (response.status >= 500 ? "MISCONFIGURED" : "INVALID_INPUT");
+  return new DocError(code, typeof error?.message === "string" ? error.message : `${fallback} (${response.status})`);
+}
+var base = (server) => server.replace(/\/$/, "");
+async function whoAmI(server, token) {
+  const response = await fetch(`${base(server)}/api/v1/me`, { headers: { authorization: `Bearer ${token}` } }).catch((error) => {
+    throw unreachable(error);
+  });
+  if (!response.ok) {
+    if (response.status === 401 || response.status === 403) throw new DocError("FORBIDDEN", `the server refused the token (${response.status})`);
+    throw await refusal(response, "the server could not say who the token is");
+  }
+  const body = await response.json();
+  const { kind, name, scopes, role } = body;
+  if (!PRINCIPAL_KINDS.includes(kind) || typeof name !== "string" || role !== "editor" && role !== "viewer") {
+    throw new DocError("INVALID_INPUT", "the server sent an identity this client does not know");
+  }
+  const granted = Array.isArray(scopes) ? scopes.filter((s) => typeof s === "string") : [];
+  return { author: { kind, name, ...granted.length ? { scopes: granted } : {} }, role };
+}
+var LiveDoc = class _LiveDoc {
+  constructor(doc, me, client, api, refusedAtStart) {
+    this.doc = doc;
+    this.me = me;
+    this.client = client;
+    this.api = api;
+    this.refusedAtStart = refusedAtStart;
+  }
+  doc;
+  me;
+  client;
+  api;
+  refusedAtStart;
+  static async join(options) {
+    const me = await whoAmI(options.server, options.token);
+    const url = new URL(`${base(options.server)}/api/v1/docs/${encodeURIComponent(options.id)}/ws`);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    const client = await SyncClient.connect({
+      url: url.toString(),
+      headers: { authorization: `Bearer ${options.token}` },
+      presence: { name: options.name ?? me.author.name },
+      reconnect: options.reconnect
+    });
+    const api = (path, init = {}) => fetch(`${base(options.server)}/api/v1/docs/${encodeURIComponent(options.id)}${path}`, {
+      ...init,
+      headers: { ...init.headers, authorization: `Bearer ${options.token}` }
+    });
+    try {
+      if (options.seed !== false) {
+        const stored = await api("/state");
+        if (stored.ok) {
+          const state = new Uint8Array(await stored.arrayBuffer());
+          if (state.length > MAX_LIVE_BYTES) throw new DocError("INVALID_INPUT", `the stored document is over ${MAX_LIVE_BYTES} bytes, the most a live room takes`);
+          Y.applyUpdate(client.doc, state);
+        } else if (stored.status !== 404) throw await refusal(stored, "could not read the stored document");
+        await client.flush();
+        if (me.role === "editor" && client.denied.length > 0) throw new DocError("FORBIDDEN", `the room refused the stored document: ${client.denied[0]}`);
+      }
+    } catch (error) {
+      await client.disconnect();
+      throw error instanceof DocError ? error : new DocError("INVALID_INPUT", `could not open the room: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return new _LiveDoc(new AgenticDoc(client.doc, options.doc), me, client, api, client.denied.length);
+  }
+  /** Saves the room's state to the stored document, through the Blobs port. A viewer cannot save. */
+  async save() {
+    if (this.me.role === "viewer") throw new DocError("FORBIDDEN", "this token is a viewer; it cannot change a document");
+    await this.client.flush();
+    const saved = await this.api("/checkpoint", { method: "POST", headers: { "content-type": "application/octet-stream" }, body: new Uint8Array(this.doc.encode()) });
+    if (!saved.ok) throw await refusal(saved, "the server did not save the document");
+  }
+  /** The other people and agents in the room. `machine` is true for an agent. */
+  get peers() {
+    return this.client.peers;
+  }
+  /** Why the room dropped an update, in order. */
+  get denied() {
+    return this.client.denied.slice(this.refusedAtStart);
+  }
+  /**
+   * Runs one change as the token's author and waits until the room has it. A viewer fails before the change.
+   * After a refusal from the room the local copy still holds the change. Leave and join again.
+   */
+  async edit(run) {
+    if (this.me.role === "viewer") throw new DocError("FORBIDDEN", "this token is a viewer; it cannot change a document");
+    const seen = this.denied.length;
+    const result = run(this.doc, this.me.author);
+    await this.client.flush();
+    if (this.denied.length > seen) throw new DocError("FORBIDDEN", `the room refused the edit: ${this.denied[seen]}`);
+    return result;
+  }
+  /** Waits until the room has every change made so far. */
+  flush() {
+    return this.client.flush();
+  }
+  async leave() {
+    await this.client.disconnect();
+  }
+};
+function unreachable(error) {
+  if (error instanceof DocError) return error;
+  return new DocError("MISCONFIGURED", `could not reach the live server: ${error instanceof Error ? error.message : String(error)}`);
+}
+var LiveService = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async join(id) {
+    try {
+      return await LiveDoc.join({ ...this.options, id });
+    } catch (error) {
+      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 })
+    }).catch((error) => {
+      throw unreachable(error);
+    });
+    if (!response.ok) throw await refusal(response, "the server refused the request");
+  }
+  async read(id, run) {
+    const live = await this.join(id);
+    try {
+      return run(this.exists(live, id));
+    } finally {
+      await live.leave();
+    }
+  }
+  async write(id, run) {
+    const live = await this.join(id);
+    try {
+      this.exists(live, id);
+      const result = await live.edit((doc) => run(doc));
+      try {
+        await live.save();
+      } catch (error) {
+        const why = error instanceof Error ? error.message : String(error);
+        throw new DocError(error instanceof DocError ? error.code : "MISCONFIGURED", `the room has the change, but it is not saved: ${why}. Do not repeat the change.`);
+      }
+      return result;
+    } finally {
+      await live.leave();
+    }
+  }
+  // A document that nobody made has an empty room and an empty log.
+  exists(live, id) {
+    if (live.doc.edits().length === 0) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
+    return live.doc;
+  }
+};
+
+export {
+  whoAmI,
+  LiveDoc,
+  LiveService
+};

package/dist/chunk-TFCRPEEM.js

@@ -0,0 +1,224 @@
+import {
+  DocError
+} from "./chunk-YBBQNCMC.js";
+
+// src/adapters/file-blobs.ts
+import { createHash, randomUUID } from "crypto";
+import { link, mkdir, open, readFile, rename, rm, stat, writeFile } from "fs/promises";
+import { resolve } from "path";
+import { assertBlobPutOptions, assertResponseHeaders, parseRegion } from "agentic-identity";
+var sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+var missing = (error) => error.code === "ENOENT";
+var HEADER = 4;
+function pack(data, contentType) {
+  const head = Buffer.from(JSON.stringify(contentType === void 0 ? {} : { contentType }));
+  const length = Buffer.alloc(HEADER);
+  length.writeUInt32BE(head.length);
+  return Buffer.concat([length, head, data]);
+}
+function unpack(file) {
+  const end = HEADER + file.readUInt32BE(0);
+  const { contentType } = JSON.parse(file.subarray(HEADER, end).toString("utf8"));
+  return {
+    data: new Uint8Array(file.subarray(end)),
+    version: createHash("sha256").update(file).digest("hex"),
+    ...contentType === void 0 ? {} : { contentType }
+  };
+}
+function createLocker(root, options = {}) {
+  const staleMs = options.lockStaleMs ?? 1e4;
+  const timeoutMs = options.lockTimeoutMs ?? 5e3;
+  async function clearStale(lock) {
+    let token;
+    let age;
+    try {
+      token = await readFile(lock, "utf8");
+      age = Date.now() - (await stat(lock)).mtimeMs;
+    } catch (error) {
+      if (missing(error)) return true;
+      throw error;
+    }
+    if (!(age > staleMs)) return false;
+    const moved = `${lock}.stale-${randomUUID()}`;
+    try {
+      await rename(lock, moved);
+    } catch (error) {
+      if (missing(error)) return true;
+      throw error;
+    }
+    if (await readFile(moved, "utf8").catch(() => token) !== token) await link(moved, lock).catch(() => void 0);
+    await rm(moved, { force: true });
+    return true;
+  }
+  async function locked(full, run) {
+    await mkdir(root, { recursive: true });
+    const lock = `${full}.lock`;
+    const token = randomUUID();
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      try {
+        const file = await open(lock, "wx");
+        await file.writeFile(token).finally(() => file.close());
+        break;
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        if (await clearStale(lock)) continue;
+        if (Date.now() >= deadline) throw new DocError("LOCKED", "another writer holds this document; try again");
+        await sleep(5 + Math.random() * 20);
+      }
+    }
+    const held = async () => await readFile(lock, "utf8").catch(() => null) === token;
+    try {
+      return await run(held);
+    } finally {
+      if (await held()) await rm(lock, { force: true });
+    }
+  }
+  return locked;
+}
+function createFileBlobs(dir, options = {}) {
+  const root = resolve(dir);
+  const locked = createLocker(root, options);
+  const now = options.now ?? Date.now;
+  const path = (key) => {
+    if (key === "") throw new Error("blob key must not be empty");
+    return resolve(root, createHash("sha256").update(key).digest("hex"));
+  };
+  async function read(full) {
+    try {
+      return unpack(await readFile(full));
+    } catch (error) {
+      if (missing(error)) return null;
+      throw error;
+    }
+  }
+  return {
+    region: options.region === void 0 ? "unknown" : parseRegion(options.region),
+    async put(key, data, opts) {
+      const full = path(key);
+      assertBlobPutOptions(opts);
+      return locked(full, async (held) => {
+        if (opts?.ifNoneMatch === "*" || opts?.ifMatch !== void 0) {
+          const current = await read(full);
+          if (opts.ifNoneMatch === "*" ? current !== null : current?.version !== opts.ifMatch) return null;
+        }
+        const file = pack(data, opts?.contentType);
+        const temp = `${full}.${randomUUID()}.tmp`;
+        try {
+          await writeFile(temp, file);
+          if (!await held()) throw new DocError("LOCKED", "the lock was taken over while writing; try again");
+          await rename(temp, full);
+        } finally {
+          await rm(temp, { force: true });
+        }
+        return { version: createHash("sha256").update(file).digest("hex") };
+      });
+    },
+    get: (key) => read(path(key)),
+    async head(key) {
+      const found = await read(path(key));
+      return found ? { size: found.data.length, version: found.version, ...found.contentType === void 0 ? {} : { contentType: found.contentType } } : null;
+    },
+    async delete(key) {
+      const full = path(key);
+      await locked(full, () => rm(full, { force: true }));
+    },
+    /** A local path with its expiry. Nothing serves or checks it: it exists so the port is whole. */
+    async signedUrl(key, opts) {
+      const full = path(key);
+      const { method, expiresInSeconds } = opts;
+      if (!Number.isInteger(expiresInSeconds) || expiresInSeconds < 1 || expiresInSeconds > 604800) {
+        throw new RangeError("expiresInSeconds must be an integer from 1 to 604800");
+      }
+      assertResponseHeaders(opts);
+      const extra = [
+        opts.responseContentDisposition === void 0 ? "" : `&disposition=${encodeURIComponent(opts.responseContentDisposition)}`,
+        opts.responseContentType === void 0 ? "" : `&type=${encodeURIComponent(opts.responseContentType)}`
+      ].join("");
+      return `file://${full}?method=${method}&expires=${now() + expiresInSeconds * 1e3}${extra}`;
+    }
+  };
+}
+
+// src/adapters/file-store.ts
+import { createMemoryStore, StoreConflictError } from "agentic-identity";
+import { resolve as resolve2 } from "path";
+var KEY = "store";
+var ATTEMPTS = 64;
+function createFileStore(dir, options = {}) {
+  const { shared: _shared, ...rest } = options;
+  const memoryOptions = { region: rest.region, now: rest.now };
+  const blobs = createFileBlobs(dir, options);
+  const locked = createLocker(resolve2(dir), options);
+  const mutex = resolve2(dir, "store-mutex");
+  const region = createMemoryStore(memoryOptions).region;
+  async function load() {
+    const found = await blobs.get(KEY);
+    const rows = /* @__PURE__ */ new Map();
+    const memory = createMemoryStore(memoryOptions);
+    if (found) {
+      for (const row of JSON.parse(new TextDecoder().decode(found.data))) {
+        rows.set(JSON.stringify([row[0], row[1]]), row);
+        await memory.put(row[0], row[1], row[2]);
+      }
+    }
+    return { memory, rows, version: found?.version };
+  }
+  async function save(rows, changes, version) {
+    if (changes.length === 0) return true;
+    for (const [collection, id, doc] of changes) {
+      const key = JSON.stringify([collection, id]);
+      if (doc === null) rows.delete(key);
+      else rows.set(key, [collection, id, doc]);
+    }
+    const data = new TextEncoder().encode(JSON.stringify([...rows.values()]));
+    const saved = await blobs.put(KEY, data, version === void 0 ? { ifNoneMatch: "*" } : { ifMatch: version });
+    return saved !== null;
+  }
+  const recording = (ops, changes) => ({
+    ...ops,
+    put: async (collection, id, doc) => {
+      await ops.put(collection, id, doc);
+      changes.push([collection, id, doc]);
+    },
+    delete: async (collection, id) => {
+      await ops.delete(collection, id);
+      changes.push([collection, id, null]);
+    }
+  });
+  const transaction = async (fn) => {
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const done = await locked(mutex, async (held) => {
+        const { memory, rows, version } = await load();
+        let changes = [];
+        const result = await memory.transaction((tx) => {
+          changes = [];
+          return fn(recording(tx, changes));
+        });
+        if (changes.length > 0 && !await held()) throw new DocError("LOCKED", "the lock was taken over during the transaction; try again");
+        return await save(rows, changes, version) ? { result } : void 0;
+      });
+      if (done) return done.result;
+    }
+    throw new StoreConflictError(`transaction kept conflicting after ${ATTEMPTS} attempts`);
+  };
+  return {
+    region,
+    get: async (collection, id) => (await load()).memory.get(collection, id),
+    query: async (collection, query) => (await load()).memory.query(collection, query),
+    put: (collection, id, doc) => transaction(async (tx) => {
+      await tx.get(collection, id);
+      await tx.put(collection, id, doc);
+    }),
+    delete: (collection, id) => transaction(async (tx) => {
+      await tx.get(collection, id);
+      await tx.delete(collection, id);
+    }),
+    transaction
+  };
+}
+
+export {
+  createFileBlobs,
+  createFileStore
+};