agentic-comments 0.1.0 → 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

@@ -1,332 +1,105 @@
-import * as Y from 'yjs';
+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;
 
-/** A Yjs relative position as JSON. It names an item, not an index, so it follows its text. */
-interface RelativePositionJson {
-    type?: {
-        client: number;
-        clock: number;
-    };
-    tname?: string;
-    item?: {
-        client: number;
-        clock: number;
-    };
-    assoc?: number;
-}
-interface TextAnchor {
-    type: "text";
-    /** The text under the range when the comment was made. `Comments.add` checks it against the document. */
-    text: string;
-    start: RelativePositionJson;
-    end: RelativePositionJson;
-}
-interface CellAnchor {
-    type: "cell";
-    /** A cell key the host app defines, such as `Sheet1!B4` or a stable cell id. */
-    key: string;
-}
-interface SlideAnchor {
-    type: "slide";
-    elementId: string;
-}
-interface CanvasAnchor {
-    type: "canvas";
-    elementId: string;
-}
-/**
- * Where a thread points. A custom kind (see `AnchorKind`) returns its own shape, so narrow on `type`
- * before you read its fields.
- */
-type Anchor = TextAnchor | CellAnchor | SlideAnchor | CanvasAnchor;
-/** Teach `Comments` a new anchor type. `parse` returns a clean copy or throws. */
-interface AnchorKind {
-    type: string;
-    parse(raw: Record<string, unknown>): {
-        type: string;
-    };
-}
-/**
- * Whether the content under an anchor is still there.
- * `attached`: yes, as it was. `edited`: the range is there, with other text. `orphaned`: the content is
- * gone. `unknown`: nothing can tell, as for a cell with no host answer.
- */
-type AnchorState = {
-    state: "attached";
-} | {
-    state: "edited";
-    currentText: string;
-} | {
-    state: "orphaned";
-} | {
-    state: "unknown";
-};
-/** The text of a Yjs text type. An embed counts as one character, so indexes match Yjs positions. */
-declare function textOf(type: Y.Text | Y.XmlText): string;
-/** Pin a range of a Yjs text. Later edits by any replica do not move the anchor off its text. */
-declare function textAnchor(type: Y.Text | Y.XmlText, from: number, to: number): TextAnchor;
-
-declare const PRINCIPAL_KINDS: readonly ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
-type PrincipalKind = (typeof PRINCIPAL_KINDS)[number];
-/** What a thread keeps about who wrote a message. Scopes never reach storage. */
-interface Author {
-    kind: PrincipalKind;
-    name: string;
-}
-interface StampInput {
-    kind: PrincipalKind;
-    name: string;
-    /** Rights the host granted this principal, such as `comments:accept`. Used to decide, never stored. */
-    scopes?: string[];
-}
-/**
- * The only author a write accepts. The host makes one from the principal it authenticated, and an
- * operation never reads an author from its input. An object that `stamp()` did not make is refused,
- * and a stamped one cannot change.
- */
-declare class Actor implements Author {
-    readonly kind: PrincipalKind;
-    readonly name: string;
-    readonly scopes: readonly string[];
-    private constructor();
-    static of(input: StampInput): Actor;
-    static is(value: unknown): value is Actor;
-}
-/** Make the author for one authenticated principal. Throws when the kind or name is missing or wrong. */
-declare const stamp: (input: StampInput) => Actor;
-/** The label a UI shows. Agent work stays marked as machine-made. */
-declare function authorLabel(author: Author): "person" | "person via agent" | "agent";
-
-interface Message {
-    id: string;
-    at: string;
-    author: Author;
-    body: string;
-    /** Handles named in the body or listed on the input, without the `@`. */
-    mentions: string[];
-}
-interface Thread {
-    id: string;
-    anchor: Anchor;
-    status: "open" | "resolved";
-    /**
-     * The status change that won, and when. For a new thread, who opened it. Replicas that change the
-     * status at once agree on one change. Yjs picks it by client id, not by time.
-     */
-    statusBy: Author;
-    statusAt: string;
-    messages: Message[];
-    /** Whether the anchored content is still there. A thread whose content is gone stays readable. */
-    anchorState: AnchorState;
-    /** How many stored entries this read did not show: invalid ones, repeated ids, and valid ones past the read limit. `problems()` names them. */
-    skipped: number;
-}
-interface CommentsOptions {
-    now?: () => Date;
-    /** More anchor types. A type that is already built in is refused. */
-    anchors?: AnchorKind[];
-    /**
-     * Tell whether the content a cell, slide, canvas, or custom anchor points at still exists. Return `true`
-     * or `false`. Any other answer, or a throw, means unknown. Text anchors do not need it.
-     */
-    exists?: (anchor: Anchor) => boolean | undefined;
-}
-interface NewThread {
-    anchor: Anchor;
-    body: string;
-    mentions?: string[];
-}
-interface NewReply {
-    body: string;
-    mentions?: string[];
-}
-interface ThreadFilter {
-    status?: Thread["status"];
-    anchorType?: string;
-    /** A handle, with or without the `@`. */
-    mentioning?: string;
-    anchorState?: AnchorState["state"];
-}
-/** Comment threads on a Yjs document. Replies and status merge across replicas. */
-declare class Comments {
-    readonly ydoc: Y.Doc;
-    private readonly kinds;
-    private readonly now;
-    private readonly exists?;
-    /** Every replica of a document must register the same custom anchor kinds. Others read those threads as malformed. */
-    constructor(ydoc: Y.Doc, options?: CommentsOptions);
-    private get map();
-    /** The clock, as an ISO time. Used by `Suggestions`. */
-    time(): string;
-    /** Whether the content under an anchor is still there. This never throws. */
-    anchorState(anchor: Anchor): AnchorState;
-    /** Read an anchor from stored data. This does not check the document. */
-    parseAnchor(raw: unknown): Anchor;
-    /** Parse an anchor from input and check it against this document. Throws `INVALID_ANCHOR` when it fails. */
-    checkAnchor(raw: unknown): Anchor;
-    /** A text anchor must name text in this document, in order, and match its quote. */
-    private checkInDocument;
-    /** Build a message, and refuse it unless a read would show it back. Nothing is written yet. */
-    private message;
-    private readMessage;
-    /** A thread with a bad anchor or status is malformed. A bad message is skipped and named in `issues`. */
-    private read;
-    private fields;
-    /** Start a thread with its first message. The anchor and body are checked before anything is written. */
-    add(input: NewThread, actor: Actor): Thread;
-    /**
-     * Add a message. The resolved check runs on this replica only. A reply and a resolve made at once
-     * on two replicas both stay, and the merged thread is resolved with the reply in it.
-     */
-    reply(threadId: string, input: NewReply, actor: Actor): Message;
-    private setStatus;
-    /**
-     * Move a text anchor whose range is gone or edited to its quote, when the quote occurs exactly once in
-     * the same text. There is no fuzzy match. Throws `RELOCATE_FAILED` when it cannot say where. An attached
-     * thread is returned as it is.
-     */
-    relocate(threadId: string, actor: Actor): Thread;
-    resolve(threadId: string, actor: Actor): Thread;
-    reopen(threadId: string, actor: Actor): Thread;
-    get(threadId: string): Thread;
-    /** Threads in the order they were started. A malformed thread is skipped; `problems()` names it. */
-    list(filter?: ThreadFilter): Thread[];
-    /** Threads or messages that could not be read, for example from a replica that wrote bad data. */
-    problems(): {
-        id: string;
-        reason: string;
-    }[];
-    private readAll;
-}
-
-type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED";
+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);
 }
 
-/** The scope that lets an agent accept or reject a suggestion that another principal wrote. */
-declare const ACCEPT_SCOPE = "comments:accept";
-interface Suggestion {
-    id: string;
-    anchor: Anchor;
-    /** Whether the anchored content is still there. Accept refuses an orphaned or edited one. */
-    anchorState: AnchorState;
-    /** What the host app proposes. This package never reads it. The host's `apply` does. */
-    change: unknown;
-    summary?: string;
-    author: Author;
-    createdAt: string;
-    status: "pending" | "accepted" | "rejected";
-    decidedBy?: Author;
-    decidedAt?: string;
-}
-interface ApplyContext {
-    suggestionId: string;
-    anchor: Anchor;
-    /** Who wrote the suggestion. */
-    author: Author;
-    /** Who accepts it. Label the edit with this author. */
-    by: Author;
-    ydoc: Y.Doc;
-}
-interface RevertContext {
-    suggestionId: string;
-    anchor: Anchor;
-    /** Who wrote the suggestion. */
-    author: Author;
-    /** Who made the application being undone. */
-    by: Author;
-    ydoc: Y.Doc;
-}
+type CommentEventType = "thread.created" | "message.added" | "mention" | "thread.resolved" | "thread.reopened" | "suggestion.created" | "suggestion.accepted" | "suggestion.rejected";
 /**
- * The host app's side. Each hook is synchronous, so the check and the edit stay in one step.
- * Make every edit in `ydoc`, so it merges with the rest.
+ * 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 SuggestionHost {
-    /** Check a change when it is suggested. Return the clean change, or throw. */
-    parse?(change: unknown): unknown;
+interface CommentEvent {
     /**
-     * Make the edit. Throw before you change anything when the edit cannot apply, for example when the
-     * anchored content changed. Yjs cannot undo a partial edit. If `apply` edits and then fails, the
-     * decision is recorded as accepted with no receipt, and `problems()` reports it. Return a receipt,
-     * JSON data that lets `revert` undo this edit.
+     * 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.
      */
-    apply(change: unknown, context: ApplyContext): unknown;
+    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 {
     /**
-     * Two replicas can accept one suggestion before they meet. Each applies the edit. After a merge one
-     * application stays and `revert` undoes each other. Every replica runs it at the same time, and the
-     * results must merge to one outcome, as a Yjs delete of the same range does. Throw before you change
-     * anything. A receipt comes from stored data. A peer that can write comment data can choose it, so
-     * check it before you use it. The anchor and the author are stored data too, so a check against them
-     * helps against a mistake and not against a peer that can write comment data.
+     * 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()`.
      */
-    revert?(receipt: unknown, context: RevertContext): void;
-    /** Say that applying the same change twice is harmless. Then `revert` is not needed, and a duplicate is not undone. */
-    idempotent?: boolean;
-}
-interface NewSuggestion {
-    anchor: Anchor;
-    change: unknown;
-    summary?: string;
-}
-interface SuggestionFilter {
-    status?: Suggestion["status"];
-    anchorState?: AnchorState["state"];
+    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;
 }
 /**
- * Suggested changes to content, from people and agents. Nothing changes until a person, or an agent
- * with the accept scope that did not write it, accepts. Accept and reject are safe across replicas.
+ * 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 Suggestions {
+declare class Notifications {
     private readonly comments;
-    private readonly host;
-    private readonly onTransaction;
-    private failures;
-    constructor(comments: Comments, host: SuggestionHost);
-    /** Stop listening to the document. */
+    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;
-    private get ydoc();
-    private get map();
-    private get applied();
-    private get rejected();
-    private change;
-    /**
-     * Records of one kind for one suggestion, in client order. A record that is not valid is not counted:
-     * one with no author or time, a receipt that is not small JSON, or a decider who decided their own work.
-     */
-    private records;
-    /** Group the entries of a decision map by suggestion id in one pass, so a read does not scan the map per suggestion. */
-    private index;
-    private read;
-    private fields;
-    /** Propose a change. Anyone can suggest. The host stamps the author. */
-    add(input: NewSuggestion, actor: Actor): Suggestion;
-    /** A person decides. An agent needs the accept scope, and never decides its own suggestion. */
-    private mayDecide;
-    /**
-     * Apply the change as the accepting author and record the decision, in one step. Accepting an
-     * accepted suggestion changes nothing. When `apply` throws, the suggestion stays pending.
-     */
-    accept(suggestionId: string, actor: Actor): Suggestion;
-    /** Same right as accept. A person can withdraw their own suggestion. */
-    reject(suggestionId: string, actor: Actor): Suggestion;
-    get(suggestionId: string): Suggestion;
-    /** In the order they were made. A malformed suggestion is skipped, and `problems()` names it. */
-    list(filter?: SuggestionFilter): Suggestion[];
-    /** Suggestions that could not be read, and reverts that failed. */
-    problems(): {
-        id: string;
-        reason: string;
+    /** The most recent errors, when no `onError` was given. */
+    errors(): {
+        source: "listener" | "data";
+        error: unknown;
     }[];
-    private readAll;
-    /**
-     * Two replicas can accept one suggestion before they meet. After a merge, the application of the
-     * lowest client id stays, and the host reverts each other one. Every replica reaches the same result.
-     * A revert that throws leaves its record, so the next merge tries again.
-     */
-    settle(): void;
+    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 { ACCEPT_SCOPE, Actor, type Anchor, type AnchorKind, type AnchorState, type ApplyContext, type Author, type CanvasAnchor, type CellAnchor, Comments, CommentsError, type CommentsErrorCode, type CommentsOptions, type Message, type NewReply, type NewSuggestion, type NewThread, PRINCIPAL_KINDS, type PrincipalKind, type RelativePositionJson, type RevertContext, type SlideAnchor, type StampInput, type Suggestion, type SuggestionFilter, type SuggestionHost, Suggestions, type TextAnchor, type Thread, type ThreadFilter, VERSION, authorLabel, stamp, textAnchor, textOf };
+export { Author, type CommentEvent, type CommentEventType, type CommentListener, Comments, CommentsError, type CommentsErrorCode, Notifications, type NotificationsOptions, Suggestions, VERSION };