agentic-comments 0.1.0 → 0.2.0

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
+};

package/dist/mcp-bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/mcp-bin.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import {
+  FileStore,
+  lockTimeoutFrom,
+  operatorActor
+} from "./chunk-C43HLFQE.js";
+import {
+  startMcp
+} from "./chunk-UE5ULEXU.js";
+import "./chunk-RWMBGIAS.js";
+import "./chunk-ZCM2UDLN.js";
+import "./chunk-C3P5TAC3.js";
+
+// src/mcp-bin.ts
+try {
+  const env = process.env;
+  await startMcp(new FileStore(env.AGENTIC_COMMENTS_FILE ?? "./comments.ydoc", { lockTimeoutMs: lockTimeoutFrom(env) }), operatorActor(env.AGENTIC_COMMENTS_AS, env.AGENTIC_COMMENTS_SCOPES));
+} catch (error) {
+  console.error(JSON.stringify({ error: { code: error.code ?? "INTERNAL", message: error instanceof Error ? error.message : String(error) } }));
+  process.exit(1);
+}

package/dist/suggestions-U8tXRLZ5.d.ts

@@ -0,0 +1,334 @@
+import * as Y from 'yjs';
+
+/** 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 Yjs map that holds the threads. `Notifications` watches it. */
+    get threadsMap(): Y.Map<Y.Map<unknown>>;
+    /** 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;
+}
+
+/** 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;
+}
+/**
+ * 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.
+ */
+interface SuggestionHost {
+    /** Check a change when it is suggested, with the anchor it is for. Return the clean change, or throw. */
+    parse?(change: unknown, context: {
+        anchor: Anchor;
+    }): unknown;
+    /**
+     * 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.
+     */
+    apply(change: unknown, context: ApplyContext): unknown;
+    /**
+     * 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.
+     */
+    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"];
+}
+/**
+ * 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.
+ */
+declare class Suggestions {
+    private readonly comments;
+    private readonly host;
+    private readonly onTransaction;
+    private failures;
+    constructor(comments: Comments, host: SuggestionHost);
+    /** Stop listening to the document. */
+    close(): void;
+    private get ydoc();
+    private get map();
+    /** The three Yjs maps that hold suggestions and their decisions. `Notifications` watches them. */
+    get maps(): {
+        suggestions: Y.Map<Y.Map<unknown>>;
+        applied: Y.Map<unknown>;
+        rejected: Y.Map<unknown>;
+    };
+    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;
+    }[];
+    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;
+}
+
+export { type Author as A, Comments as C, type Message as M, type NewReply as N, PRINCIPAL_KINDS as P, type RelativePositionJson as R, Suggestions as S, type TextAnchor as T, ACCEPT_SCOPE as a, Actor as b, type Anchor as c, type AnchorKind as d, type AnchorState as e, type ApplyContext as f, type CanvasAnchor as g, type CellAnchor as h, type CommentsOptions as i, type NewSuggestion as j, type NewThread as k, type PrincipalKind as l, type RevertContext as m, type SlideAnchor as n, type StampInput as o, type Suggestion as p, type SuggestionFilter as q, type SuggestionHost as r, type Thread as s, type ThreadFilter as t, authorLabel as u, stamp as v, textAnchor as w, textOf as x };

package/llms.txt

@@ -6,7 +6,8 @@ Keywords: comments,threads,mentions,suggestions,annotations,collaboration,agents
 
 - SDK: import { Comments, Suggestions, textAnchor } from "agentic-comments". The host calls stamp(); an agent never does.
 - Threads live on a Yjs document and merge across replicas.
-- The CLI and MCP server are not built yet.
+- Events: new Notifications(comments, suggestions).subscribe(listener). Ids only, never text.
+- CLI: agentic-comments <command>. MCP: agentic-comments mcp. Both use a local store file.
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-comments",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Comment threads and suggestions anchored to any content, from people and agents.",
   "keywords": [
     "comments",
@@ -10,7 +10,8 @@
     "annotations",
     "collaboration",
     "agents",
-    "yjs"
+    "yjs",
+    "mcp"
   ],
   "license": "MIT",
   "author": "Pooria Arab",
@@ -35,28 +36,43 @@
   "publishConfig": {
     "access": "public"
   },
+  "mcpName": "io.github.pooriaarab/agentic-comments",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./local": {
+      "types": "./dist/local.d.ts",
+      "import": "./dist/local.js"
     }
   },
+  "bin": {
+    "agentic-comments": "./dist/cli.js",
+    "agentic-comments-mcp": "./dist/mcp-bin.js"
+  },
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "clean": "rm -rf dist",
+    "prepack": "npm run build",
     "ci:local": "npm run build && npm run typecheck && npm test"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
     "yjs": "^13.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.6.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "yjs": "^13.6.0"
   }
 }