agentic-comments 0.1.0 → 0.3.0

package/dist/chunk-IB6ANO32.js

@@ -0,0 +1,172 @@
+import {
+  Comments,
+  CommentsError,
+  Suggestions,
+  exact,
+  invalid,
+  textAnchor,
+  textOf,
+  textRange
+} from "./chunk-GSAJOCDV.js";
+
+// src/local-host.ts
+import * as Y from "yjs";
+var TEXT_ROOT = "text";
+var VALUES_ROOT = "values";
+var MAX_TEXT = 1e5;
+var refuse = (message) => {
+  throw new CommentsError("INVALID_INPUT", message);
+};
+function valueKey(anchor) {
+  const id = anchor.key ?? anchor.elementId;
+  return typeof id === "string" ? `${anchor.type}:${id}` : refuse("this anchor has no key or element id");
+}
+var localHost = {
+  parse(change, { anchor }) {
+    const c = change ?? {};
+    const keys = Object.keys(c);
+    if (anchor.type === "text") {
+      if (keys.length === 1 && keys[0] === "replace" && typeof c.replace === "string" && c.replace.length <= MAX_TEXT) return { replace: c.replace };
+      return refuse('a change for a text anchor is { "replace": text }');
+    }
+    if (keys.length === 1 && keys[0] === "value") return { value: c.value };
+    return refuse(`a change for a ${anchor.type} anchor is { "value": JSON }`);
+  },
+  apply(change, ctx) {
+    const c = change;
+    if (ctx.anchor.type === "text") {
+      if (typeof c.replace !== "string") throw new Error('a text anchor needs { "replace": text }');
+      const range = textRange(ctx.anchor, ctx.ydoc);
+      if (!range) throw new Error("the anchored text is gone");
+      range.type.delete(range.from, range.to - range.from);
+      range.type.insert(range.from, c.replace);
+      return {
+        kind: "text",
+        start: Y.relativePositionToJSON(Y.createRelativePositionFromTypeIndex(range.type, range.from, 0)),
+        end: Y.relativePositionToJSON(Y.createRelativePositionFromTypeIndex(range.type, range.from + c.replace.length, -1))
+      };
+    }
+    if (!("value" in c)) throw new Error('this anchor needs { "value": JSON }');
+    ctx.ydoc.getMap(VALUES_ROOT).set(valueKey(ctx.anchor), c.value);
+    return { kind: "value" };
+  },
+  revert(receipt, ctx) {
+    const r = receipt ?? {};
+    if (r.kind === "value") return;
+    if (r.kind !== "text" || typeof r.start !== "object" || r.start === null || typeof r.end !== "object" || r.end === null) {
+      throw new Error("the receipt is not a text receipt");
+    }
+    const at = (json) => {
+      try {
+        return Y.createAbsolutePositionFromRelativePosition(Y.createRelativePositionFromJSON(json), ctx.ydoc);
+      } catch {
+        return null;
+      }
+    };
+    const from = at(r.start);
+    const to = at(r.end);
+    if (from && to && from.type === to.type && from.type instanceof Y.Text && to.index > from.index) {
+      from.type.delete(from.index, to.index - from.index);
+    }
+  }
+};
+
+// src/service.ts
+var SHOWN = 5;
+function anchorFrom(ydoc, spec) {
+  const type = spec?.type;
+  if (type === "cell") {
+    const given2 = exact(spec, ["type", "key"], "a cell anchor");
+    return { type: "cell", key: given2.key };
+  }
+  if (type === "slide" || type === "canvas") {
+    const given2 = exact(spec, ["type", "elementId"], `a ${type} anchor`);
+    return { type, elementId: given2.elementId };
+  }
+  const given = exact(spec, ["type", "quote", "occurrence"], "a text anchor");
+  if (given.type !== "text") return invalid('an anchor type is "text", "cell", "slide", or "canvas"');
+  const quote = given.quote;
+  if (typeof quote !== "string" || quote === "") return invalid("a text anchor needs a quote");
+  const text = ydoc.getText(TEXT_ROOT);
+  const value = textOf(text);
+  const at = [];
+  for (let i = value.indexOf(quote); i >= 0; i = value.indexOf(quote, i + 1)) at.push(i);
+  if (at.length === 0) throw new CommentsError("INVALID_ANCHOR", `no text matches ${JSON.stringify(quote.slice(0, 40))}`);
+  const occurrence = given.occurrence;
+  if (occurrence !== void 0 && (!Number.isSafeInteger(occurrence) || occurrence < 1 || occurrence > at.length)) {
+    throw new CommentsError("INVALID_ANCHOR", `the quote has ${at.length} matches, not ${String(occurrence)}`);
+  }
+  if (occurrence === void 0 && at.length > 1) {
+    const offsets = at.slice(0, SHOWN).join(", ");
+    throw new CommentsError("INVALID_ANCHOR", `the quote matches ${at.length} places, at character offsets ${offsets}${at.length > SHOWN ? ", and more" : ""}; pass an occurrence from 1 to ${at.length}`);
+  }
+  const start = at[occurrence ? occurrence - 1 : 0];
+  return textAnchor(text, start, start + quote.length);
+}
+var CommentsService = class {
+  constructor(store, actor) {
+    this.store = store;
+    this.actor = actor;
+  }
+  store;
+  actor;
+  open(ydoc) {
+    ydoc.getText(TEXT_ROOT);
+    const comments = new Comments(ydoc);
+    return { comments, suggestions: new Suggestions(comments, localHost) };
+  }
+  read(fn) {
+    return this.store.read((ydoc) => fn(this.open(ydoc), ydoc));
+  }
+  write(fn) {
+    return this.store.write((ydoc) => fn(this.open(ydoc), ydoc));
+  }
+  threads(filter = {}) {
+    const given = exact(filter, ["status", "anchorState", "mentioning"], "a filter");
+    return this.read(({ comments }) => comments.list(given));
+  }
+  thread(id) {
+    return this.read(({ comments }) => comments.get(id));
+  }
+  comment(input) {
+    const given = exact(input, ["anchor", "body", "mentions"], "a comment");
+    return this.write(({ comments }, ydoc) => comments.add({ anchor: anchorFrom(ydoc, given.anchor), body: given.body, mentions: given.mentions }, this.actor));
+  }
+  reply(threadId, input) {
+    return this.write(({ comments }) => comments.reply(threadId, exact(input, ["body", "mentions"], "a reply"), this.actor));
+  }
+  resolve(threadId) {
+    return this.write(({ comments }) => comments.resolve(threadId, this.actor));
+  }
+  reopen(threadId) {
+    return this.write(({ comments }) => comments.reopen(threadId, this.actor));
+  }
+  relocate(threadId) {
+    return this.write(({ comments }) => comments.relocate(threadId, this.actor));
+  }
+  suggestions(filter = {}) {
+    const given = exact(filter, ["status", "anchorState"], "a filter");
+    return this.read(({ suggestions }) => suggestions.list(given));
+  }
+  suggest(input) {
+    const given = exact(input, ["anchor", "change", "summary"], "a suggestion");
+    return this.write(({ suggestions }, ydoc) => suggestions.add({ anchor: anchorFrom(ydoc, given.anchor), change: given.change, summary: given.summary }, this.actor));
+  }
+  accept(suggestionId) {
+    return this.write(({ suggestions }) => suggestions.accept(suggestionId, this.actor));
+  }
+  reject(suggestionId) {
+    return this.write(({ suggestions }) => suggestions.reject(suggestionId, this.actor));
+  }
+  /** The content text of the store. */
+  text() {
+    return this.read((_o, ydoc) => ydoc.getText(TEXT_ROOT).toString());
+  }
+};
+
+export {
+  TEXT_ROOT,
+  VALUES_ROOT,
+  localHost,
+  CommentsService
+};

package/dist/chunk-TTTX3R6M.js

@@ -0,0 +1,86 @@
+import {
+  VERSION
+} from "./chunk-GMA5I5L6.js";
+import {
+  CommentsService
+} from "./chunk-IB6ANO32.js";
+import {
+  CommentsError
+} from "./chunk-GSAJOCDV.js";
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+var anchor = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text"), quote: z.string().describe("Exact text to anchor to."), occurrence: z.number().int().min(1).optional().describe("Which match, when the quote occurs more than once.") }).strict(),
+  z.object({ type: z.literal("cell"), key: z.string() }).strict(),
+  z.object({ type: z.literal("slide"), elementId: z.string() }).strict(),
+  z.object({ type: z.literal("canvas"), elementId: z.string() }).strict()
+]).describe("Where the thread or suggestion points.");
+var id = z.string().describe("The thread or suggestion id.");
+var body = z.string().describe("The message text. Write @handle to mention someone.");
+var mentions = z.array(z.string()).optional().describe("Extra handles to mention.");
+function ok(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+function failure(error) {
+  const known = error instanceof CommentsError;
+  return { content: [{ type: "text", text: JSON.stringify({ error: { code: known ? error.code : "INTERNAL", message: error instanceof Error ? error.message : String(error) } }) }], isError: true };
+}
+function createMcpServer(store, actor) {
+  const service = new CommentsService(store, actor);
+  const server = new McpServer({ name: "agentic-comments", version: VERSION });
+  const tools = /* @__PURE__ */ new Map();
+  const tool = (name, description, shape, readOnly, run) => {
+    const strict = z.object(shape).strict();
+    tools.set(name, { strict, run });
+    server.registerTool(name, { description, inputSchema: strict, annotations: { readOnlyHint: readOnly, destructiveHint: false, openWorldHint: false } }, (() => {
+      throw new Error("calls are handled by the server");
+    }));
+  };
+  const state = z.enum(["attached", "edited", "orphaned", "unknown"]).optional();
+  tool("list_threads", "List comment threads. Each has an anchorState: an orphaned thread lost its content but stays readable.", { status: z.enum(["open", "resolved"]).optional(), anchorState: state, mentioning: z.string().optional() }, true, (i) => service.threads(i));
+  tool("get_thread", "Read one thread with its messages.", { id }, true, (i) => service.thread(i.id));
+  tool("add_comment", "Start a thread on text, a cell, a slide element, or a canvas element.", { anchor, body, mentions }, false, (i) => service.comment(i));
+  tool("reply_to_thread", "Reply to an open thread. Reopen a resolved thread first.", { id, body, mentions }, false, (i) => service.reply(i.id, { body: i.body, mentions: i.mentions }));
+  tool("resolve_thread", "Resolve a thread.", { id }, false, (i) => service.resolve(i.id));
+  tool("reopen_thread", "Reopen a resolved thread.", { id }, false, (i) => service.reopen(i.id));
+  tool("relocate_thread", "Move a text anchor to its quote when the quote occurs exactly once.", { id }, false, (i) => service.relocate(i.id));
+  tool("list_suggestions", "List suggested changes.", { status: z.enum(["pending", "accepted", "rejected"]).optional(), anchorState: state }, true, (i) => service.suggestions(i));
+  tool(
+    "suggest_change",
+    'Suggest a change. For a text anchor the change is {"replace": "new text"}. For another anchor it is {"value": <JSON>}.',
+    { anchor, change: z.union([z.object({ replace: z.string() }).strict(), z.object({ value: z.unknown() }).strict()]), summary: z.string().optional() },
+    false,
+    (i) => service.suggest(i)
+  );
+  tool("accept_suggestion", "Accept a suggestion. Needs the accept scope for an agent, and never works on your own suggestion.", { id }, false, (i) => service.accept(i.id));
+  tool("reject_suggestion", "Reject a suggestion. Same rights as accept.", { id }, false, (i) => service.reject(i.id));
+  server.server.setRequestHandler(CallToolRequestSchema, (request) => {
+    const entry = tools.get(request.params.name);
+    if (!entry) return failure(new CommentsError("INVALID_INPUT", `there is no tool named ${JSON.stringify(request.params.name.slice(0, 60))}`));
+    try {
+      const checked = entry.strict.safeParse(request.params.arguments ?? {});
+      if (!checked.success) {
+        const where = checked.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        throw new CommentsError("INVALID_INPUT", `the tool input is refused: ${where.slice(0, 400)}`);
+      }
+      return ok(entry.run(checked.data));
+    } catch (error) {
+      return failure(error);
+    }
+  });
+  return server;
+}
+async function startMcp(store, actor) {
+  process.on("SIGXFSZ", () => void 0);
+  const server = createMcpServer(store, actor);
+  await server.connect(new StdioServerTransport());
+}
+
+export {
+  createMcpServer,
+  startMcp
+};

package/dist/chunk-YU5U4P22.js

@@ -0,0 +1,262 @@
+import {
+  CommentsError,
+  PRINCIPAL_KINDS,
+  stamp
+} from "./chunk-GSAJOCDV.js";
+
+// src/file-store.ts
+import { createHash } from "crypto";
+import { closeSync, existsSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeSync } from "fs";
+import { dirname, resolve } from "path";
+import * as Y from "yjs";
+var MAX_FILE = 50 * 1024 * 1024;
+var MAGIC = Buffer.from("ACV1");
+var HASH = 32;
+var POLL_MS = 25;
+var EMPTY_LOCK_MS = 2e3;
+var LOCK_MAX_AGE_MS = 6e4;
+var ATTEMPTS = 4;
+function lockTimeoutFrom(env) {
+  const raw = env.AGENTIC_COMMENTS_LOCK_TIMEOUT_MS;
+  if (raw === void 0) return void 0;
+  if (!/^\d{1,9}$/.test(raw)) throw new CommentsError("USAGE", "AGENTIC_COMMENTS_LOCK_TIMEOUT_MS must be a whole number of milliseconds");
+  return Number(raw);
+}
+var sleep = (ms) => void Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+var digest = (data) => createHash("sha256").update(data).digest();
+function encode(ydoc) {
+  const update = Y.encodeStateAsUpdate(ydoc);
+  return Buffer.concat([MAGIC, digest(update), update]);
+}
+function decode(bytes, path) {
+  const body = bytes.subarray(MAGIC.length + HASH);
+  if (bytes.length < MAGIC.length + HASH || !bytes.subarray(0, MAGIC.length).equals(MAGIC) || !bytes.subarray(MAGIC.length, MAGIC.length + HASH).equals(digest(body))) {
+    throw new CommentsError("STORE_CORRUPT", `${path} is not a saved document, or it is damaged`);
+  }
+  const ydoc = new Y.Doc();
+  try {
+    Y.applyUpdate(ydoc, new Uint8Array(body));
+  } catch {
+    throw new CommentsError("STORE_CORRUPT", `${path} is not a saved document, or it is damaged`);
+  }
+  return ydoc;
+}
+function writeAll(handle, data) {
+  let done = 0;
+  while (done < data.length) {
+    const wrote = writeSync(handle, data, done, data.length - done);
+    if (wrote <= 0) throw Object.assign(new Error("a write made no progress"), { code: "ENOSPC" });
+    done += wrote;
+  }
+}
+var FULL = /* @__PURE__ */ new Set(["ENOSPC", "EFBIG", "EDQUOT"]);
+function writeDurably(path, data) {
+  let handle;
+  try {
+    handle = openSync(path, "wx");
+    writeAll(handle, data);
+    fsyncSync(handle);
+  } catch (error) {
+    if (handle !== void 0) closeSync(handle);
+    handle = void 0;
+    try {
+      unlinkSync(path);
+    } catch {
+    }
+    if (FULL.has(error.code ?? "")) throw new CommentsError("STORE_FULL", "the file could not be written: the disk is full or a file size limit applies");
+    throw error;
+  }
+  closeSync(handle);
+}
+function syncDirectory(path) {
+  try {
+    const handle = openSync(dirname(path), "r");
+    try {
+      fsyncSync(handle);
+    } finally {
+      closeSync(handle);
+    }
+  } catch {
+  }
+}
+var identity = (path) => {
+  const s = statSync(path);
+  return `${s.ino}:${s.size}:${s.mtimeMs}`;
+};
+var FileStore = class {
+  path;
+  lockTimeoutMs;
+  constructor(path, options = {}) {
+    const given = resolve(path);
+    this.path = existsSync(given) ? realpathSync(given) : given;
+    const timeout = options.lockTimeoutMs ?? 5e3;
+    if (!Number.isSafeInteger(timeout) || timeout < 0) throw new CommentsError("INVALID_INPUT", "lockTimeoutMs must be a whole number of milliseconds, 0 or more");
+    this.lockTimeoutMs = timeout;
+  }
+  /** Create the file. `seed` fills the document before the first save. Refuses to overwrite, even when two run at once. */
+  create(seed = () => void 0) {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const ydoc = new Y.Doc();
+    seed(ydoc);
+    const data = encode(ydoc);
+    if (data.length > MAX_FILE) throw new CommentsError("STORE_FULL", `the document is larger than ${MAX_FILE} bytes`);
+    const temporary = `${this.path}.tmp-${process.pid}-${globalThis.crypto.randomUUID()}`;
+    writeDurably(temporary, data);
+    try {
+      linkSync(temporary, this.path);
+    } catch (error) {
+      const code = error.code;
+      if (code === "EEXIST") throw new CommentsError("STORE_EXISTS", `${this.path} already exists`);
+      if (code !== "EPERM" && code !== "ENOTSUP" && code !== "EXDEV" && code !== "ENOSYS") throw error;
+      if (existsSync(this.path)) throw new CommentsError("STORE_EXISTS", `${this.path} already exists`);
+      renameSync(temporary, this.path);
+    } finally {
+      try {
+        unlinkSync(temporary);
+      } catch {
+      }
+    }
+    syncDirectory(this.path);
+  }
+  load() {
+    if (!existsSync(this.path)) throw new CommentsError("STORE_MISSING", `${this.path} does not exist; run init first`);
+    if (statSync(this.path).size > MAX_FILE) throw new CommentsError("STORE_CORRUPT", `${this.path} is larger than ${MAX_FILE} bytes`);
+    const seen = identity(this.path);
+    return { ydoc: decode(readFileSync(this.path), this.path), seen };
+  }
+  /** Read the newest saved state. Anything `fn` changes is not saved. */
+  read(fn) {
+    return fn(this.load().ydoc);
+  }
+  acquire(lock, mine) {
+    const deadline = Date.now() + this.lockTimeoutMs;
+    for (; ; ) {
+      try {
+        const handle = openSync(lock, "wx");
+        try {
+          writeAll(handle, Buffer.from(mine));
+        } catch (error) {
+          closeSync(handle);
+          try {
+            unlinkSync(lock);
+          } catch {
+          }
+          if (FULL.has(error.code ?? "")) throw new CommentsError("STORE_FULL", "the lock could not be written: the disk is full");
+          throw error;
+        }
+        closeSync(handle);
+        return;
+      } catch (error) {
+        if (error instanceof CommentsError) throw error;
+        if (error.code !== "EEXIST") throw new CommentsError("STORE_LOCKED", `${lock} cannot be created: ${error.code ?? "an error"}`);
+      }
+      if (this.clearStale(lock, mine)) continue;
+      if (Date.now() >= deadline) {
+        throw new CommentsError("STORE_LOCKED", `${lock} is held by another process; remove it only if nothing uses ${this.path}`);
+      }
+      sleep(POLL_MS);
+    }
+  }
+  /**
+    * Clear a lock whose holder is dead (or is this process, with another mark), an empty one older than a
+  * short time, or any one more than a minute old or a minute in the future. The lock moves to a unique name
+    * first, so only one process clears it. If the moved lock is not the one we looked at, it goes back.
+    */
+  clearStale(lock, mine) {
+    let held;
+    let age;
+    try {
+      held = readFileSync(lock, "utf8").trim();
+      age = Date.now() - statSync(lock).mtimeMs;
+    } catch (error) {
+      return error.code === "ENOENT";
+    }
+    const pid = Number(held.split(":")[0]);
+    const well = /^\d{1,10}(:[\w-]{1,64})?$/.test(held) && pid > 0;
+    const left = well && (!alive(pid) || pid === process.pid && held !== mine);
+    const old = age > LOCK_MAX_AGE_MS || age < -LOCK_MAX_AGE_MS;
+    if (!left && !(held === "" && age > EMPTY_LOCK_MS) && !old) return false;
+    const tomb = `${lock}.stale-${process.pid}-${globalThis.crypto.randomUUID()}`;
+    try {
+      renameSync(lock, tomb);
+    } catch {
+      return true;
+    }
+    try {
+      if (readFileSync(tomb, "utf8").trim() !== held) {
+        try {
+          linkSync(tomb, lock);
+        } catch {
+        }
+        return false;
+      }
+    } catch {
+      return true;
+    } finally {
+      try {
+        unlinkSync(tomb);
+      } catch {
+      }
+    }
+    return true;
+  }
+  /** Lock, load the newest state, run `fn`, and save. When `fn` throws, nothing is saved. */
+  write(fn) {
+    const lock = `${this.path}.lock`;
+    const mine = `${process.pid}:${globalThis.crypto.randomUUID()}`;
+    this.acquire(lock, mine);
+    try {
+      for (let attempt = 1; ; attempt++) {
+        const { ydoc, seen } = this.load();
+        const result = fn(ydoc);
+        const data = encode(ydoc);
+        if (data.length > MAX_FILE) throw new CommentsError("STORE_FULL", `the document would pass ${MAX_FILE} bytes, so the change was not saved`);
+        if (identity(this.path) !== seen) {
+          if (attempt >= ATTEMPTS) throw new CommentsError("STORE_LOCKED", `${this.path} kept changing while it was saved`);
+          continue;
+        }
+        const temporary = `${this.path}.tmp-${process.pid}-${globalThis.crypto.randomUUID()}`;
+        writeDurably(temporary, data);
+        try {
+          renameSync(temporary, this.path);
+        } catch (error) {
+          unlinkSync(temporary);
+          throw error;
+        }
+        syncDirectory(this.path);
+        return result;
+      }
+    } finally {
+      try {
+        if (readFileSync(lock, "utf8") === mine) unlinkSync(lock);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/operator.ts
+function operatorActor(as, scopes) {
+  const value = as?.trim();
+  const cut = value === void 0 ? -1 : value.indexOf(":");
+  if (value === void 0 || cut < 1 || cut === value.length - 1) {
+    throw new CommentsError("INVALID_AUTHOR", `set the principal as kind:name, for example human:ada. Kinds: ${PRINCIPAL_KINDS.join(", ")}`);
+  }
+  const list = scopes === void 0 || scopes.trim() === "" ? [] : scopes.split(",").map((s) => s.trim());
+  return stamp({ kind: value.slice(0, cut), name: value.slice(cut + 1), scopes: list });
+}
+
+export {
+  MAX_FILE,
+  lockTimeoutFrom,
+  FileStore,
+  operatorActor
+};

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+interface CliIo {
+    out(line: string): void;
+    err(line: string): void;
+    env: Record<string, string | undefined>;
+}
+interface Parsed {
+    command: string;
+    id?: string;
+    flags: Record<string, string>;
+    many: Record<string, string[]>;
+}
+declare function parseArgs(argv: string[]): Parsed;
+declare function runCli(argv: string[], io: CliIo): Promise<number>;
+
+export { type CliIo, parseArgs, runCli };