agentic-documents 0.1.0 → 0.2.0

package/dist/chunk-IU3YIQ4Y.js

@@ -0,0 +1,232 @@
+import {
+  DocsService,
+  MAX_LIVE_BYTES
+} from "./chunk-FZA5LQV3.js";
+import {
+  commands
+} from "./chunk-GYQFTF2E.js";
+import {
+  DocError,
+  PRINCIPAL_KINDS,
+  parseAuthor
+} from "./chunk-YBBQNCMC.js";
+
+// src/worker.ts
+import { Hono } from "hono";
+import { assertRegion, parseRegion } from "agentic-identity";
+import { D1_SCHEMA, createD1Store, createR2Blobs } from "agentic-identity/cloudflare";
+var STATUS = {
+  NO_MATCH: 404,
+  NO_SECTION: 404,
+  NO_THREAD: 404,
+  NO_SUGGESTION: 404,
+  NO_DOCUMENT: 404,
+  AMBIGUOUS_MATCH: 409,
+  STALE_ANCHOR: 409,
+  ALREADY_DECIDED: 409,
+  DOCUMENT_EXISTS: 409,
+  CONFLICT: 409,
+  FORBIDDEN: 403,
+  LOCKED: 503,
+  MISCONFIGURED: 500
+};
+function same(a, b) {
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  return diff === 0;
+}
+var MIN_TOKEN_BYTES = 32;
+var warned = /* @__PURE__ */ new Set();
+function refuse(reason) {
+  if (!warned.has(reason)) {
+    warned.add(reason);
+    console.error(`AGENTIC_DOCS_TOKENS is refused: ${reason}`);
+  }
+  return void 0;
+}
+function identityOf(entry) {
+  const object = typeof entry === "object" && entry !== null && !Array.isArray(entry) ? entry : void 0;
+  if (object?.role !== void 0 && object.role !== "editor" && object.role !== "viewer") return void 0;
+  const role = object?.role ?? "editor";
+  const principal = principalOf(entry, object);
+  return principal && { principal, role };
+}
+function principalOf(entry, object) {
+  const who = typeof entry === "string" ? entry : object?.as;
+  const author = typeof who === "string" ? parseAuthor(who) : void 0;
+  if (!author || !PRINCIPAL_KINDS.includes(author.kind) || !author.name) return void 0;
+  if (object?.scopes === void 0) return author;
+  const scopes = object.scopes;
+  return Array.isArray(scopes) && scopes.every((s) => typeof s === "string" && s !== "") ? { ...author, scopes } : void 0;
+}
+function readTokens(raw) {
+  let table;
+  try {
+    table = JSON.parse(raw ?? "{}");
+  } catch {
+    return refuse("not valid JSON");
+  }
+  if (typeof table !== "object" || table === null || Array.isArray(table)) return refuse("not a JSON object");
+  const found = /* @__PURE__ */ new Map();
+  for (const [token, entry] of Object.entries(table)) {
+    if (new TextEncoder().encode(token).length < MIN_TOKEN_BYTES) return refuse(`a token is shorter than ${MIN_TOKEN_BYTES} bytes`);
+    const identity = identityOf(entry);
+    if (!identity) return refuse("an entry is not a valid kind:name or { as, scopes, role }");
+    found.set(token, identity);
+  }
+  return found;
+}
+function identityFor(tokens, bearer) {
+  let found;
+  for (const [token, identity] of readTokens(tokens) ?? []) if (same(token, bearer)) found = identity;
+  return found;
+}
+var fail = (code, message, status, matches = []) => Response.json({ error: { code, message, matches } }, { status });
+async function readCapped(request, cap) {
+  const tooBig = () => new DocError("INVALID_INPUT", `the update is over ${cap} bytes`);
+  if (Number(request.headers.get("content-length") ?? 0) > cap) throw tooBig();
+  const chunks = [];
+  let size = 0;
+  const reader = request.body?.getReader();
+  for (let part = await reader?.read(); part && !part.done; part = await reader?.read()) {
+    size += part.value.length;
+    if (size > cap) {
+      await reader?.cancel();
+      throw tooBig();
+    }
+    chunks.push(part.value);
+  }
+  const whole = new Uint8Array(size);
+  let at = 0;
+  for (const chunk of chunks) {
+    whole.set(chunk, at);
+    at += chunk.length;
+  }
+  return whole;
+}
+var DOC_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+function createApp(source, options = {}) {
+  const app2 = new Hono();
+  app2.use("*", async (c, next) => {
+    await next();
+    c.header("x-content-type-options", "nosniff");
+  });
+  app2.get("/health", (c) => c.json({ ok: true, pack: "agentic-documents" }));
+  app2.use("/api/v1/*", async (c, next) => {
+    const bearer = /^Bearer (.+)$/.exec(c.req.header("authorization") ?? "")?.[1];
+    const identity = bearer === void 0 ? void 0 : identityFor(c.env?.AGENTIC_DOCS_TOKENS, bearer);
+    if (!identity) return fail("UNAUTHENTICATED", "send a valid bearer token", 401);
+    c.set("author", identity.principal);
+    c.set("role", identity.role);
+    await next();
+  });
+  app2.get("/api/v1/me", (c) => {
+    const { kind, name, scopes } = c.get("author");
+    return c.json({ kind, name, scopes: scopes ?? [], role: c.get("role") });
+  });
+  app2.get("/api/v1/docs/:id/room", async (c) => {
+    if (!options.live) return fail("NOT_FOUND", "this server hosts no live rooms", 404);
+    if (!DOC_ID.test(c.req.param("id"))) return fail("INVALID_INPUT", `invalid document id "${c.req.param("id")}"`, 400);
+    const { contributors } = await options.live(c.env ?? {}).meta(c.req.param("id"));
+    return c.json({ contributors: contributors.map(({ id, kind, machine }) => ({ name: id, kind, machine })) });
+  });
+  app2.get("/api/v1/docs/:id/ws", (c) => {
+    const id = c.req.param("id");
+    if (!options.live) return fail("NOT_FOUND", "this server hosts no live rooms", 404);
+    if (c.req.header("upgrade") !== "websocket") return fail("UPGRADE_REQUIRED", "open this route as a WebSocket", 426);
+    if (!DOC_ID.test(id)) return fail("INVALID_INPUT", `invalid document id "${id}"`, 400);
+    const { kind, name } = c.get("author");
+    return options.live(c.env ?? {}).connect(id, c.req.raw, { principal: { id: name, kind }, role: c.get("role"), name });
+  });
+  async function run(c, command, input) {
+    try {
+      if (!command.readOnly && c.get("role") === "viewer") throw new DocError("FORBIDDEN", "this token is a viewer; it cannot change a document");
+      const result = await command.run(await (typeof source === "function" ? source(c.env ?? {}) : source), input, c.get("author"));
+      if (command.name === "export") {
+        const { data, contentType, encoding, format } = result;
+        const images = input.remoteImages === true || input.remoteImages === "true" ? "data: https:" : "data:";
+        const disposition = format === "odt" ? { "content-disposition": `attachment; filename="${input.id}.odt"` } : {};
+        const headers = { ...disposition, "content-type": contentType, "content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; img-src ${images}; sandbox` };
+        return encoding === "base64" ? c.body(Uint8Array.from(atob(data), (ch) => ch.charCodeAt(0)), 200, headers) : c.body(data, 200, headers);
+      }
+      if (typeof result === "string") return c.body(result, 200, { "content-type": "text/markdown; charset=utf-8" });
+      return c.json(result);
+    } catch (error) {
+      if (!(error instanceof DocError)) throw error;
+      return fail(error.code, error.message, STATUS[error.code] ?? 400, error.matches);
+    }
+  }
+  async function body(c) {
+    const parsed = await c.req.json().catch(() => void 0);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new DocError("INVALID_INPUT", "the body must be a JSON object");
+    }
+    return parsed;
+  }
+  const serviceOf = (c) => typeof source === "function" ? source(c.env ?? {}) : Promise.resolve(source);
+  app2.get("/api/v1/docs/:id/state", async (c) => {
+    const state = await (await serviceOf(c)).state(c.req.param("id"));
+    return c.body(new Uint8Array(state), 200, { "content-type": "application/octet-stream" });
+  });
+  app2.post("/api/v1/docs/:id/checkpoint", async (c) => {
+    if (c.get("role") === "viewer") throw new DocError("FORBIDDEN", "this token is a viewer; it cannot change a document");
+    const update = await readCapped(c.req.raw, MAX_LIVE_BYTES);
+    await (await serviceOf(c)).checkpoint(c.req.param("id"), update, c.get("author"));
+    return c.json({ ok: true });
+  });
+  const create = commands.find((c) => c.name === "new");
+  app2.post("/api/v1/docs", async (c) => run(c, create, await body(c)));
+  for (const command of commands.filter((c) => c !== create)) {
+    const path = `/api/v1/docs/:id/${command.name}`;
+    if (command.readOnly) app2.get(path, (c) => run(c, command, { ...c.req.query(), id: c.req.param("id") }));
+    else app2.post(path, async (c) => run(c, command, { ...await body(c), id: c.req.param("id") }));
+  }
+  app2.notFound(() => fail("NOT_FOUND", "no such route", 404));
+  app2.onError((error) => {
+    if (error instanceof DocError) return fail(error.code, error.message, STATUS[error.code] ?? 400, error.matches);
+    console.error(error instanceof Error ? error.name : "error");
+    return fail("INTERNAL", "the server could not finish the request", 500);
+  });
+  return app2;
+}
+var schemas = /* @__PURE__ */ new WeakMap();
+var urlSecret;
+function regionOf(env) {
+  let region;
+  try {
+    region = parseRegion(env.AGENTIC_DOCS_REGION);
+  } catch {
+    throw new DocError("MISCONFIGURED", 'set AGENTIC_DOCS_REGION to "eu" or "us" ("unknown" only for local development)');
+  }
+  if (region === "unknown" && env.AGENTIC_DOCS_UNSAFE_REGION !== "1") {
+    throw new DocError("MISCONFIGURED", 'the region "unknown" turns the residency check off; set AGENTIC_DOCS_UNSAFE_REGION=1 to accept that for local development');
+  }
+  return region;
+}
+async function serviceFor(env) {
+  if (!env.DB || !env.DOCS) throw new DocError("MISCONFIGURED", "bind a D1 database as DB and an R2 bucket as DOCS");
+  const region = regionOf(env);
+  const db = env.DB;
+  let ready = schemas.get(db);
+  if (!ready) {
+    ready = db.prepare(D1_SCHEMA).run().catch((error) => {
+      schemas.delete(db);
+      throw error;
+    });
+    schemas.set(db, ready);
+  }
+  await ready;
+  const store = createD1Store(db, { region });
+  const blobs = createR2Blobs(env.DOCS, { region, urlBase: "https://invalid.example/unused", urlSecret: urlSecret ??= `${crypto.randomUUID()}${crypto.randomUUID()}` });
+  assertRegion(region, store, blobs);
+  return new DocsService({ store, blobs });
+}
+var app = createApp(serviceFor);
+var worker_default = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+
+export {
+  createApp,
+  regionOf,
+  serviceFor,
+  worker_default
+};

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-BSXUNQDR.js → chunk-TFCRPEEM.js}

@@ -1,6 +1,6 @@
 import {
   DocError
-} from "./chunk-4YVWD5PH.js";
+} from "./chunk-YBBQNCMC.js";
 
 // src/adapters/file-blobs.ts
 import { createHash, randomUUID } from "crypto";