agentic-comments 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import {
+  FileStore,
+  lockTimeoutFrom,
+  operatorActor
+} from "./chunk-C43HLFQE.js";
+import {
+  VERSION
+} from "./chunk-RWMBGIAS.js";
+import {
+  CommentsService,
+  TEXT_ROOT
+} from "./chunk-ZCM2UDLN.js";
+import {
+  CommentsError
+} from "./chunk-C3P5TAC3.js";
+
+// src/cli.ts
+import { readFileSync, realpathSync } from "fs";
+import { pathToFileURL } from "url";
+var UsageError = class extends Error {
+};
+var FLAGS = {
+  "--file": "value",
+  "--as": "value",
+  "--body": "value",
+  "--mention": "many",
+  "--text-quote": "value",
+  "--occurrence": "value",
+  "--cell": "value",
+  "--slide": "value",
+  "--canvas": "value",
+  "--replace": "value",
+  "--value": "value",
+  "--summary": "value",
+  "--status": "value",
+  "--anchor-state": "value",
+  "--mentioning": "value",
+  "--text": "value",
+  "--text-file": "value"
+};
+var SHARED = ["--file", "--as"];
+var ANCHOR = ["--text-quote", "--occurrence", "--cell", "--slide", "--canvas"];
+var ALLOWED = {
+  init: ["--file", "--text", "--text-file"],
+  list: [...SHARED, "--status", "--anchor-state", "--mentioning"],
+  show: SHARED,
+  comment: [...SHARED, ...ANCHOR, "--body", "--mention"],
+  reply: [...SHARED, "--body", "--mention"],
+  resolve: SHARED,
+  reopen: SHARED,
+  relocate: SHARED,
+  suggestions: [...SHARED, "--status", "--anchor-state"],
+  suggest: [...SHARED, ...ANCHOR, "--replace", "--value", "--summary"],
+  accept: SHARED,
+  reject: SHARED,
+  mcp: SHARED
+};
+var TAKES_ID = ["show", "reply", "resolve", "reopen", "relocate", "accept", "reject"];
+var COMMANDS = ["init", "list", "show", "comment", "reply", "resolve", "reopen", "relocate", "suggestions", "suggest", "accept", "reject", "mcp"];
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (command === void 0 || command === "--help" || command === "-h") return { command: "help", flags: {}, many: {} };
+  if (command === "--version" || command === "-V") return { command: "version", flags: {}, many: {} };
+  if (!COMMANDS.includes(command)) throw new UsageError(`unknown command "${command}"`);
+  const parsed = { command, flags: {}, many: {} };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (!arg.startsWith("--")) {
+      if (parsed.id !== void 0) throw new UsageError(`unexpected argument "${arg}"`);
+      parsed.id = arg;
+      continue;
+    }
+    const kind = FLAGS[arg];
+    if (!kind) throw new UsageError(`unknown flag "${arg}"`);
+    const value = rest[++i];
+    if (value === void 0) throw new UsageError(`${arg} needs a value`);
+    if (kind === "many") (parsed.many[arg] ??= []).push(value);
+    else if (arg in parsed.flags) throw new UsageError(`${arg} was given twice`);
+    else parsed.flags[arg] = value;
+  }
+  const used = [...Object.keys(parsed.flags), ...Object.keys(parsed.many)];
+  const stray = used.find((f) => !ALLOWED[command].includes(f));
+  if (stray) throw new UsageError(`${stray} does not apply to ${command}`);
+  if (parsed.id !== void 0 && !TAKES_ID.includes(command)) throw new UsageError(`${command} takes no id`);
+  if (parsed.flags["--text"] !== void 0 && parsed.flags["--text-file"] !== void 0) throw new UsageError("give only one of --text, --text-file");
+  const occurrence = parsed.flags["--occurrence"];
+  if (occurrence !== void 0 && !/^[1-9]\d{0,8}$/.test(occurrence)) throw new UsageError("--occurrence must be a whole number, 1 or more");
+  return parsed;
+}
+function anchorOf(p) {
+  const given = ["--text-quote", "--cell", "--slide", "--canvas"].filter((f2) => p.flags[f2] !== void 0);
+  if (given.length !== 1) throw new UsageError("give exactly one of --text-quote, --cell, --slide, --canvas");
+  const f = given[0];
+  if (f === "--text-quote") {
+    const occurrence = p.flags["--occurrence"];
+    return { type: "text", quote: p.flags[f], ...occurrence === void 0 ? {} : { occurrence: Number(occurrence) } };
+  }
+  return f === "--cell" ? { type: "cell", key: p.flags[f] } : { type: f === "--slide" ? "slide" : "canvas", elementId: p.flags[f] };
+}
+function changeOf(p) {
+  const { "--replace": replace, "--value": value } = p.flags;
+  if (replace === void 0 === (value === void 0)) throw new UsageError("give exactly one of --replace, --value");
+  if (replace !== void 0) return { replace };
+  try {
+    return { value: JSON.parse(value) };
+  } catch {
+    throw new UsageError("--value must be JSON");
+  }
+}
+function need(p) {
+  if (p.id === void 0) throw new UsageError(`${p.command} needs an id`);
+  return p.id;
+}
+var HELP = `agentic-comments ${VERSION}
+Comment threads and suggestions anchored to any content, from people and agents.
+
+Usage: agentic-comments <command> [flags]
+
+Setup:
+  --file <path>     The store file. Or AGENTIC_COMMENTS_FILE. Default ./comments.ydoc.
+  --as <kind:name>  Who acts. Or AGENTIC_COMMENTS_AS. Kinds: human, agent_of_human, agent_of_agent, agent, user_token.
+  Scopes come only from AGENTIC_COMMENTS_SCOPES, a comma list such as comments:accept.
+
+Commands:
+  init [--text <t> | --text-file <p>]         Create the store.
+  list [--status s] [--anchor-state s] [--mentioning h]   List threads.
+  show <id>                                   Show one thread.
+  comment <anchor> --body <t> [--mention h]   Start a thread.
+  reply <id> --body <t> [--mention h]         Reply.
+  resolve <id> | reopen <id> | relocate <id>
+  suggestions [--status s] [--anchor-state s] List suggestions.
+  suggest <anchor> (--replace <t> | --value <json>) [--summary <t>]
+  accept <id> | reject <id>
+  mcp                                         Start the MCP server on stdio.
+
+An anchor is one of: --text-quote <q> [--occurrence n], --cell <key>, --slide <id>, --canvas <id>.
+Every result is JSON. An error is JSON on stderr, and the exit code is 1. A usage error exits 2.`;
+async function runCli(argv, io) {
+  let p;
+  try {
+    p = parseArgs(argv);
+  } catch (error) {
+    io.err(JSON.stringify({ error: { code: "USAGE", message: error.message } }));
+    return 2;
+  }
+  if (p.command === "help") return io.out(HELP), 0;
+  if (p.command === "version") return io.out(VERSION), 0;
+  try {
+    const store = new FileStore(p.flags["--file"] ?? io.env.AGENTIC_COMMENTS_FILE ?? "./comments.ydoc", { lockTimeoutMs: lockTimeoutFrom(io.env) });
+    if (p.command === "init") {
+      const seed = p.flags["--text-file"] !== void 0 ? readFileSync(p.flags["--text-file"], "utf8") : p.flags["--text"] ?? "";
+      store.create((ydoc) => ydoc.getText(TEXT_ROOT).insert(0, seed));
+      io.out(JSON.stringify({ created: store.path }));
+      return 0;
+    }
+    if (p.command === "mcp") {
+      const { startMcp } = await import("./mcp-BOJM5NE6.js");
+      await startMcp(store, operatorActor(p.flags["--as"] ?? io.env.AGENTIC_COMMENTS_AS, io.env.AGENTIC_COMMENTS_SCOPES));
+      return 0;
+    }
+    const service = new CommentsService(store, operatorActor(p.flags["--as"] ?? io.env.AGENTIC_COMMENTS_AS, io.env.AGENTIC_COMMENTS_SCOPES));
+    const mentions = p.many["--mention"];
+    const filter = { status: p.flags["--status"], anchorState: p.flags["--anchor-state"], mentioning: p.flags["--mentioning"] };
+    const clean = Object.fromEntries(Object.entries(filter).filter(([, v]) => v !== void 0));
+    const result = p.command === "list" ? service.threads(clean) : p.command === "show" ? service.thread(need(p)) : p.command === "comment" ? service.comment({ anchor: anchorOf(p), body: p.flags["--body"], ...mentions ? { mentions } : {} }) : p.command === "reply" ? service.reply(need(p), { body: p.flags["--body"], ...mentions ? { mentions } : {} }) : p.command === "resolve" ? service.resolve(need(p)) : p.command === "reopen" ? service.reopen(need(p)) : p.command === "relocate" ? service.relocate(need(p)) : p.command === "suggestions" ? service.suggestions(Object.fromEntries(Object.entries(clean).filter(([k]) => k !== "mentioning"))) : p.command === "suggest" ? service.suggest({ anchor: anchorOf(p), change: changeOf(p), ...p.flags["--summary"] === void 0 ? {} : { summary: p.flags["--summary"] } }) : p.command === "accept" ? service.accept(need(p)) : service.reject(need(p));
+    io.out(JSON.stringify(result));
+    return 0;
+  } catch (error) {
+    if (error instanceof UsageError) {
+      io.err(JSON.stringify({ error: { code: "USAGE", message: error.message } }));
+      return 2;
+    }
+    if (error instanceof CommentsError) {
+      io.err(JSON.stringify({ error: { code: error.code, message: error.message } }));
+      return error.code === "USAGE" ? 2 : 1;
+    }
+    throw error;
+  }
+}
+function isMainModule() {
+  const invoked = process.argv[1];
+  if (typeof invoked !== "string") return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(invoked)).href;
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  process.on("SIGXFSZ", () => void 0);
+  runCli(process.argv.slice(2), { out: (l) => console.log(l), err: (l) => console.error(l), env: process.env }).then(
+    (code) => {
+      if (code !== 0) process.exit(code);
+    },
+    (error) => {
+      console.error(JSON.stringify({ error: { code: "INTERNAL", message: error instanceof Error ? error.message : String(error) } }));
+      process.exit(1);
+    }
+  );
+}
+export {
+  parseArgs,
+  runCli
+};

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+import { A as Author, C as Comments, S as Suggestions } from './suggestions-U8tXRLZ5.js';
+export { a as ACCEPT_SCOPE, b as Actor, c as Anchor, d as AnchorKind, e as AnchorState, f as ApplyContext, g as CanvasAnchor, h as CellAnchor, i as CommentsOptions, M as Message, N as NewReply, j as NewSuggestion, k as NewThread, P as PRINCIPAL_KINDS, l as PrincipalKind, R as RelativePositionJson, m as RevertContext, n as SlideAnchor, o as StampInput, p as Suggestion, q as SuggestionFilter, r as SuggestionHost, T as TextAnchor, s as Thread, t as ThreadFilter, u as authorLabel, v as stamp, w as textAnchor, x as textOf } from './suggestions-U8tXRLZ5.js';
+import 'yjs';
+
+declare const VERSION: string;
+
+type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED" | "STORE_MISSING" | "STORE_EXISTS" | "STORE_CORRUPT" | "STORE_LOCKED" | "STORE_FULL" | "USAGE";
+declare class CommentsError extends Error {
+    readonly code: CommentsErrorCode;
+    constructor(code: CommentsErrorCode, message: string);
+}
+
+type CommentEventType = "thread.created" | "message.added" | "mention" | "thread.resolved" | "thread.reopened" | "suggestion.created" | "suggestion.accepted" | "suggestion.rejected";
+/**
+ * One change, in terms a notifier can route. It holds ids and never the text of a comment, a suggestion, or
+ * a change, so a log or a queue that stores it holds no content. Fetch the content with the ids.
+ */
+interface CommentEvent {
+    /**
+     * The same change has the same id on every replica, so a notifier can drop a repeat. A replica also drops
+     * a repeat it has seen, within its last `seenLimit` ids. Two accepts at once give one id with the actor of
+     * whichever replica you hear first, and the winner can differ. A host clock coarser than the rate of status
+     * changes can give two status events one id.
+     */
+    id: string;
+    type: CommentEventType;
+    /** When the change was made, as the data records it. */
+    at: string;
+    /** `local` when this replica made the change. `remote` when it came in from another replica. */
+    source: "local" | "remote";
+    /** Who made the change. `machineMade` is true for every kind but a signed-in person. */
+    actor: Author & {
+        machineMade: boolean;
+    };
+    /** What kind of content the thread or suggestion points at: text, cell, slide, canvas, or a custom kind. */
+    anchorType: string;
+    threadId?: string;
+    messageId?: string;
+    suggestionId?: string;
+    /** For a `mention` event: the handle that was named. */
+    mention?: string;
+}
+type CommentListener = (event: CommentEvent) => void | Promise<void>;
+interface NotificationsOptions {
+    /**
+     * Called when a listener throws or rejects (`source` is `listener`), or when a change in the data cannot
+     * be read (`source` is `data`). Without it, errors go to `errors()`.
+     */
+    onError?: (error: unknown, source: "listener" | "data") => void;
+    /** Drop every event until `unmute()`. Create the stream muted, and unmute after the first load, so old history is not sent. */
+    muted?: boolean;
+    /** How many event ids to remember so a repeat is dropped. A whole number, 1 or more. Default 10,000. */
+    seenLimit?: number;
+}
+/**
+ * An event stream for a notifier. It watches the thread and suggestion data, so it sees changes from other
+ * replicas too, and marks each as local or remote. It replays nothing it saw before it was created, but a first
+ * load into an empty document looks like new changes: create it muted and call `unmute()` after that load.
+ * Each id is delivered at most once per replica within the `seenLimit` window, and a listener that throws is
+ * not retried. A listener cannot break a write. A message past the read limit
+ * of a thread makes no event.
+ */
+declare class Notifications {
+    private readonly comments;
+    private readonly suggestions?;
+    private readonly options;
+    private readonly listeners;
+    private readonly seen;
+    private readonly failures;
+    private readonly stops;
+    private readonly queue;
+    private flushing;
+    private closed;
+    private readonly seenLimit;
+    private muted;
+    constructor(comments: Comments, suggestions?: Suggestions | undefined, options?: NotificationsOptions);
+    /** Receive every event from now on. Returns a function that stops it. */
+    subscribe(listener: CommentListener): () => void;
+    /** Start sending events, for a stream created with `muted: true`. */
+    unmute(): void;
+    /** Stop watching the document and drop every listener. */
+    close(): void;
+    /** The most recent errors, when no `onError` was given. */
+    errors(): {
+        source: "listener" | "data";
+        error: unknown;
+    }[];
+    private fail;
+    /** Data from a peer can be bad. A bad record makes no event, and never stops a write or the records after it. */
+    private guard;
+    private emit;
+    private flush;
+    private threadEvents;
+    private mentions;
+    private messageEvent;
+    private statusEvent;
+    private threadCreated;
+    private messagesAdded;
+    private statusChanged;
+    private created;
+    private decisionEvent;
+    private decided;
+}
+
+export { Author, type CommentEvent, type CommentEventType, type CommentListener, Comments, CommentsError, type CommentsErrorCode, Notifications, type NotificationsOptions, Suggestions, VERSION };

package/dist/index.js

@@ -0,0 +1,223 @@
+import {
+  VERSION
+} from "./chunk-RWMBGIAS.js";
+import {
+  ACCEPT_SCOPE,
+  Actor,
+  Comments,
+  CommentsError,
+  PRINCIPAL_KINDS,
+  Suggestions,
+  authorLabel,
+  readAuthor,
+  stamp,
+  textAnchor,
+  textOf,
+  validDate
+} from "./chunk-C3P5TAC3.js";
+
+// src/notifications.ts
+import * as Y from "yjs";
+var DEFAULT_SEEN = 1e4;
+var ERROR_LIMIT = 100;
+var actorOf = (author) => ({ kind: author.kind, name: author.name, machineMade: author.kind !== "human" });
+var Notifications = class {
+  constructor(comments, suggestions, options = {}) {
+    this.comments = comments;
+    this.suggestions = suggestions;
+    this.options = options;
+    this.seenLimit = options.seenLimit ?? DEFAULT_SEEN;
+    if (!Number.isSafeInteger(this.seenLimit) || this.seenLimit < 1) throw new TypeError("seenLimit must be a whole number, 1 or more");
+    this.muted = options.muted === true;
+    const flush = () => this.flush();
+    comments.ydoc.on("afterAllTransactions", flush);
+    this.stops.push(() => comments.ydoc.off("afterAllTransactions", flush));
+    const threads = comments.threadsMap;
+    const onThreads = (events, tr) => this.threadEvents(events, tr.local ? "local" : "remote");
+    threads.observeDeep(onThreads);
+    this.stops.push(() => threads.unobserveDeep(onThreads));
+    if (suggestions) {
+      const { suggestions: made, applied, rejected } = suggestions.maps;
+      const onMade = (event, tr) => this.created(event, tr.local ? "local" : "remote");
+      const onApplied = (event, tr) => this.decided(event, tr.local ? "local" : "remote", "suggestion.accepted");
+      const onRejected = (event, tr) => this.decided(event, tr.local ? "local" : "remote", "suggestion.rejected");
+      made.observe(onMade);
+      applied.observe(onApplied);
+      rejected.observe(onRejected);
+      this.stops.push(() => made.unobserve(onMade), () => applied.unobserve(onApplied), () => rejected.unobserve(onRejected));
+    }
+  }
+  comments;
+  suggestions;
+  options;
+  listeners = /* @__PURE__ */ new Set();
+  seen = /* @__PURE__ */ new Set();
+  failures = [];
+  stops = [];
+  queue = [];
+  flushing = false;
+  closed = false;
+  seenLimit;
+  muted;
+  /** Receive every event from now on. Returns a function that stops it. */
+  subscribe(listener) {
+    if (typeof listener !== "function") throw new TypeError("a listener must be a function");
+    this.listeners.add(listener);
+    return () => void this.listeners.delete(listener);
+  }
+  /** Start sending events, for a stream created with `muted: true`. */
+  unmute() {
+    this.muted = false;
+  }
+  /** Stop watching the document and drop every listener. */
+  close() {
+    this.closed = true;
+    for (const stop of this.stops.splice(0)) stop();
+    this.listeners.clear();
+    this.queue.length = 0;
+  }
+  /** The most recent errors, when no `onError` was given. */
+  errors() {
+    return [...this.failures];
+  }
+  fail(error, source) {
+    try {
+      if (this.options.onError) this.options.onError(error, source);
+      else if (this.failures.push({ source, error }) > ERROR_LIMIT) this.failures.shift();
+    } catch {
+    }
+  }
+  /** Data from a peer can be bad. A bad record makes no event, and never stops a write or the records after it. */
+  guard(fn) {
+    try {
+      fn();
+    } catch (error) {
+      this.fail(error, "data");
+    }
+  }
+  emit(event) {
+    if (this.seen.has(event.id)) return;
+    this.seen.add(event.id);
+    if (this.seen.size > this.seenLimit) this.seen.delete(this.seen.values().next().value);
+    if (!this.muted) this.queue.push(event);
+  }
+  flush() {
+    if (this.flushing) return;
+    this.flushing = true;
+    try {
+      for (let event = this.queue.shift(); event; event = this.queue.shift()) {
+        for (const listener of [...this.listeners]) {
+          if (this.closed) return;
+          try {
+            const result = listener(event);
+            if (typeof result?.then === "function") Promise.resolve(result).catch((error) => this.fail(error, "listener"));
+          } catch (error) {
+            this.fail(error, "listener");
+          }
+        }
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+  threadEvents(events, source) {
+    const threads = this.comments.threadsMap;
+    for (const event of events) {
+      this.guard(() => {
+        const path = event.path;
+        if (event.target === threads) {
+          for (const [id, change] of event.keys) if (change.action === "add") this.guard(() => this.threadCreated(id, source));
+        } else if (path.length === 1 && event.target instanceof Y.Map) {
+          const keys = event.keys;
+          if (keys.get("messages")?.action === "add") this.threadCreated(String(path[0]), source);
+          const change = keys.get("state");
+          if (change) this.statusChanged(String(path[0]), change.oldValue, source);
+        } else if (path.length === 2 && path[1] === "messages" && event.target instanceof Y.Array) {
+          const ids = /* @__PURE__ */ new Set();
+          for (const item of event.changes.added) for (const raw of item.content.getContent()) ids.add(raw?.id);
+          this.messagesAdded(String(path[0]), ids, source);
+        }
+      });
+    }
+  }
+  mentions(thread, message, source) {
+    for (const handle of message.mentions) {
+      this.emit({ id: `mention:${thread.id}:${message.id}:${handle}`, type: "mention", at: message.at, source, actor: actorOf(message.author), anchorType: thread.anchor.type, threadId: thread.id, messageId: message.id, mention: handle });
+    }
+  }
+  messageEvent(thread, message, source) {
+    this.emit({ id: `message.added:${thread.id}:${message.id}`, type: "message.added", at: message.at, source, actor: actorOf(message.author), anchorType: thread.anchor.type, threadId: thread.id, messageId: message.id });
+    this.mentions(thread, message, source);
+  }
+  statusEvent(thread, source) {
+    const type = thread.status === "resolved" ? "thread.resolved" : "thread.reopened";
+    this.emit({ id: `${type}:${thread.id}:${thread.statusAt}:${thread.statusBy.kind}:${thread.statusBy.name}`, type, at: thread.statusAt, source, actor: actorOf(thread.statusBy), anchorType: thread.anchor.type, threadId: thread.id });
+  }
+  threadCreated(id, source) {
+    const thread = this.comments.get(id);
+    const stored = this.comments.threadsMap.get(id)?.get("messages");
+    const firstId = stored instanceof Y.Array ? stored.get(0)?.id : void 0;
+    const first = thread.messages.find((m) => m.id === firstId);
+    if (first) {
+      this.emit({ id: `thread.created:${id}`, type: "thread.created", at: first.at, source, actor: actorOf(first.author), anchorType: thread.anchor.type, threadId: id, messageId: first.id });
+      this.mentions(thread, first, source);
+    } else {
+      this.fail(new Error(`thread ${JSON.stringify(id.slice(0, 64))} has no valid first message, so it makes no thread.created event`), "data");
+    }
+    for (const message of thread.messages) if (message !== first) this.messageEvent(thread, message, source);
+    if (thread.status === "resolved") this.statusEvent(thread, source);
+  }
+  messagesAdded(threadId, ids, source) {
+    const thread = this.comments.get(threadId);
+    for (const message of thread.messages) if (ids.has(message.id)) this.messageEvent(thread, message, source);
+  }
+  statusChanged(threadId, before, source) {
+    const thread = this.comments.get(threadId);
+    const old = before ?? {};
+    const real = (old.status === "open" || old.status === "resolved") && readAuthor(old.by) !== void 0;
+    if (real && old.status !== thread.status) this.statusEvent(thread, source);
+  }
+  created(event, source) {
+    for (const [id, change] of event.keys) {
+      if (change.action !== "add") continue;
+      this.guard(() => {
+        const s = this.suggestions.get(id);
+        this.emit({ id: `suggestion.created:${id}`, type: "suggestion.created", at: s.createdAt, source, actor: actorOf(s.author), anchorType: s.anchor.type, suggestionId: id });
+        if (s.status !== "pending") this.decisionEvent(s, source);
+      });
+    }
+  }
+  decisionEvent(s, source) {
+    if (s.status === "pending" || !s.decidedBy || !s.decidedAt) return;
+    const type = s.status === "accepted" ? "suggestion.accepted" : "suggestion.rejected";
+    this.emit({ id: `${type}:${s.id}`, type, at: s.decidedAt, source, actor: actorOf(s.decidedBy), anchorType: s.anchor.type, suggestionId: s.id });
+  }
+  decided(event, source, type) {
+    for (const [key, change] of event.keys) {
+      if (change.action !== "add") continue;
+      try {
+        const raw = event.target.get(key);
+        if (!raw || readAuthor(raw.by) === void 0 || !validDate(raw.at)) throw new Error("a decision record is not valid");
+        const id = key.slice(0, key.lastIndexOf(":"));
+        const s = this.suggestions.get(id);
+        if (s.status === (type === "suggestion.accepted" ? "accepted" : "rejected")) this.decisionEvent(s, source);
+      } catch (error) {
+        this.fail(error, "data");
+      }
+    }
+  }
+};
+export {
+  ACCEPT_SCOPE,
+  Actor,
+  Comments,
+  CommentsError,
+  Notifications,
+  PRINCIPAL_KINDS,
+  Suggestions,
+  VERSION,
+  authorLabel,
+  stamp,
+  textAnchor,
+  textOf
+};

package/dist/local.d.ts

@@ -0,0 +1,112 @@
+import * as Y from 'yjs';
+import { b as Actor, s as Thread, M as Message, p as Suggestion, r as SuggestionHost } from './suggestions-U8tXRLZ5.js';
+
+/** The most bytes a saved document holds. A save over this is refused, so a file never grows past what a load accepts. */
+declare const MAX_FILE: number;
+interface FileStoreOptions {
+    /** How long a write waits for another process. A whole number of ms, 0 or more. Default 5,000. */
+    lockTimeoutMs?: number;
+}
+/** Read the lock timeout from `AGENTIC_COMMENTS_LOCK_TIMEOUT_MS`. Anything but a whole number of ms is an error. */
+declare function lockTimeoutFrom(env: Record<string, string | undefined>): number | undefined;
+/**
+ * One file that holds a Yjs document, with a hash so damage is seen. A write takes a lock file, loads the
+ * newest state, runs, and saves with a rename. If the file changed while it ran, it runs again on the new
+ * state. This is built for processes on one machine that share one process table. A lock held across
+ * containers or machines cannot be checked for a dead holder.
+ */
+declare class FileStore {
+    readonly path: string;
+    private readonly lockTimeoutMs;
+    constructor(path: string, options?: FileStoreOptions);
+    /** Create the file. `seed` fills the document before the first save. Refuses to overwrite, even when two run at once. */
+    create(seed?: (ydoc: Y.Doc) => void): void;
+    private load;
+    /** Read the newest saved state. Anything `fn` changes is not saved. */
+    read<T>(fn: (ydoc: Y.Doc) => T): T;
+    private acquire;
+    /**
+     * 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.
+     */
+    private clearStale;
+    /** Lock, load the newest state, run `fn`, and save. When `fn` throws, nothing is saved. */
+    write<T>(fn: (ydoc: Y.Doc) => T): T;
+}
+
+/** Where a comment or suggestion points, in terms a person or agent can write down. */
+type AnchorSpec = {
+    type: "text";
+    quote: string;
+    occurrence?: number;
+} | {
+    type: "cell";
+    key: string;
+} | {
+    type: "slide";
+    elementId: string;
+} | {
+    type: "canvas";
+    elementId: string;
+};
+interface ListFilter {
+    status?: string;
+    anchorState?: string;
+    mentioning?: string;
+}
+/**
+ * Every action the CLI and MCP server offer, on a local file store. Each call takes the actor the operator
+ * stamped, and no input carries an author, so both faces return the same shapes and obey the same rules.
+ */
+declare class CommentsService {
+    private readonly store;
+    private readonly actor;
+    constructor(store: FileStore, actor: Actor);
+    private open;
+    private read;
+    private write;
+    threads(filter?: ListFilter): Thread[];
+    thread(id: string): Thread;
+    comment(input: {
+        anchor: AnchorSpec;
+        body: string;
+        mentions?: string[];
+    }): Thread;
+    reply(threadId: string, input: {
+        body: string;
+        mentions?: string[];
+    }): Message;
+    resolve(threadId: string): Thread;
+    reopen(threadId: string): Thread;
+    relocate(threadId: string): Thread;
+    suggestions(filter?: ListFilter): Suggestion[];
+    suggest(input: {
+        anchor: AnchorSpec;
+        change: unknown;
+        summary?: string;
+    }): Suggestion;
+    accept(suggestionId: string): Suggestion;
+    reject(suggestionId: string): Suggestion;
+    /** The content text of the store. */
+    text(): string;
+}
+
+/** The root Y.Text that a local store keeps its content in. */
+declare const TEXT_ROOT = "text";
+/** The root Y.Map that holds values for cell, slide, canvas, and custom anchors. */
+declare const VALUES_ROOT = "values";
+/**
+ * The host for a local store. A text anchor takes `{ "replace": "text" }` and swaps the anchored range.
+ * Any other anchor takes `{ "value": <JSON> }` and sets that key in the values map.
+ */
+declare const localHost: SuggestionHost;
+
+/**
+ * Stamp the principal the operator set. `as` is `kind:name`, from a flag the operator wrote or from
+ * `AGENTIC_COMMENTS_AS`. Scopes come only from `AGENTIC_COMMENTS_SCOPES`, a comma list. A tool input
+ * never reaches this function, so an agent that calls a tool cannot pick its own kind or scopes.
+ */
+declare function operatorActor(as: string | undefined, scopes: string | undefined): Actor;
+
+export { type AnchorSpec, CommentsService, FileStore, type FileStoreOptions, type ListFilter, MAX_FILE, TEXT_ROOT, VALUES_ROOT, localHost, lockTimeoutFrom, operatorActor };

package/dist/local.js

@@ -0,0 +1,23 @@
+import {
+  FileStore,
+  MAX_FILE,
+  lockTimeoutFrom,
+  operatorActor
+} from "./chunk-C43HLFQE.js";
+import {
+  CommentsService,
+  TEXT_ROOT,
+  VALUES_ROOT,
+  localHost
+} from "./chunk-ZCM2UDLN.js";
+import "./chunk-C3P5TAC3.js";
+export {
+  CommentsService,
+  FileStore,
+  MAX_FILE,
+  TEXT_ROOT,
+  VALUES_ROOT,
+  localHost,
+  lockTimeoutFrom,
+  operatorActor
+};

package/dist/mcp-BOJM5NE6.js

@@ -0,0 +1,11 @@
+import {
+  createMcpServer,
+  startMcp
+} from "./chunk-UE5ULEXU.js";
+import "./chunk-RWMBGIAS.js";
+import "./chunk-ZCM2UDLN.js";
+import "./chunk-C3P5TAC3.js";
+export {
+  createMcpServer,
+  startMcp
+};