agentic-documents 0.0.0-stage → 0.2.0

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+declare function main(argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+
+export { main };

package/dist/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import {
+  createFileBlobs,
+  createFileStore
+} from "./chunk-TFCRPEEM.js";
+import {
+  LiveService,
+  whoAmI
+} from "./chunk-R5XUTBC3.js";
+import {
+  DocsService
+} from "./chunk-FZA5LQV3.js";
+import {
+  VERSION
+} from "./chunk-5Y66UCTE.js";
+import {
+  commands
+} from "./chunk-GYQFTF2E.js";
+import {
+  DocError,
+  parseAuthor
+} from "./chunk-YBBQNCMC.js";
+
+// src/cli.ts
+import { readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { parseArgs } from "util";
+var NAME = "agentic-documents";
+var flagNames = [...new Set(commands.flatMap((c) => Object.keys(c.shape)))].filter((k) => k !== "id");
+var options = {
+  ...Object.fromEntries(flagNames.map((k) => [k, { type: "string" }])),
+  as: { type: "string" },
+  scopes: { type: "string" },
+  dir: { type: "string" },
+  live: { type: "string" },
+  file: { type: "string" },
+  out: { type: "string" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "V" }
+};
+function help() {
+  const lines = commands.map((c) => `  ${c.name.padEnd(12)}${c.description}`);
+  return [
+    `${NAME} ${VERSION}`,
+    "",
+    `Usage: ${NAME} <command> <id> [flags]`,
+    "",
+    "Commands:",
+    ...lines,
+    "  mcp         Start the MCP server on stdio.",
+    "",
+    "Flags:",
+    "  --as <kind:name>  Who makes the change. Or set AGENTIC_DOCS_AS. Kinds: human, agent_of_human,",
+    "                    agent_of_agent, agent, user_token.",
+    "  --scopes <a,b>    Rights for the author, such as docs:accept. Or set AGENTIC_DOCS_SCOPES. An agent",
+    "                    needs docs:accept to accept a suggestion.",
+    "  --live <url>      Join live rooms on this server, as the author of AGENTIC_DOCS_TOKEN. Or set",
+    "                    AGENTIC_DOCS_LIVE_URL. The server sets your author kind, so --as, --scopes, and --dir are refused.",
+    "  --dir <path>      Where documents live. Or set AGENTIC_DOCS_DIR. Default: .agentic-documents",
+    "  --file <path>     Read content (or markdown for new) from a file.",
+    "  --out <path>      Write the export to a file.",
+    "  --<field> <value> Any field of the command, such as --text, --section, --occurrence."
+  ].join("\n");
+}
+function bindValues(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const name = argv[i].startsWith("--") && !argv[i].includes("=") ? argv[i].slice(2) : void 0;
+    const takesValue = name !== void 0 && options[name]?.type === "string";
+    out.push(takesValue && i + 1 < argv.length ? `${argv[i]}=${argv[++i]}` : argv[i]);
+  }
+  return out;
+}
+async function main(argv, env = process.env) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: bindValues(argv), options, allowPositionals: true });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 2;
+  }
+  const { values, positionals } = parsed;
+  const [name, id] = positionals;
+  if (values.version || values.help || name === void 0) {
+    console.log(values.version ? VERSION : help());
+    return 0;
+  }
+  const liveUrl = values.live ?? (env.AGENTIC_DOCS_LIVE_URL || void 0);
+  let service;
+  let author;
+  if (liveUrl !== void 0) {
+    if (!/^https?:\/\/[^/\s]+/.test(liveUrl)) {
+      console.error(`--live needs an http:// or https:// address, not "${liveUrl}"`);
+      return 2;
+    }
+    if (values.as !== void 0 || values.scopes !== void 0 || values.dir !== void 0) {
+      console.error("--as, --scopes, and --dir do not apply with --live: the server sets the author kind and the scopes from the token, and keeps the documents.");
+      return 2;
+    }
+    const token = env.AGENTIC_DOCS_TOKEN;
+    if (!token) {
+      console.error("set AGENTIC_DOCS_TOKEN to a bearer token to join a live room");
+      return 2;
+    }
+    try {
+      author = (await whoAmI(liveUrl, token)).author;
+    } catch (error) {
+      if (!(error instanceof DocError)) throw error;
+      console.error(`${error.code}: ${error.message}`);
+      return 1;
+    }
+    service = new LiveService({ server: liveUrl, token });
+  } else {
+    const dir = values.dir ?? env.AGENTIC_DOCS_DIR ?? ".agentic-documents";
+    service = new DocsService({ blobs: createFileBlobs(join(dir, "blobs")), store: createFileStore(join(dir, "store")) });
+    const scopes = (values.scopes ?? env.AGENTIC_DOCS_SCOPES)?.split(",").map((s) => s.trim()).filter(Boolean);
+    const named = parseAuthor(values.as ?? env.AGENTIC_DOCS_AS);
+    author = named && scopes?.length ? { ...named, scopes } : named;
+  }
+  if (name === "mcp") {
+    const { startMcp } = await import("./mcp-P2C75IIG.js");
+    await startMcp(service, author);
+    return 0;
+  }
+  const command = commands.find((c) => c.name === name);
+  if (!command) {
+    console.error(`unknown command "${name}". Run "${NAME} --help".`);
+    return 2;
+  }
+  const { as: _as, scopes: _scopes, dir: _dir, live: _live, file, out, help: _help, version: _version, ...fields } = values;
+  const input = { ...command.shape.id ? { id } : {}, ...fields };
+  try {
+    if (file !== void 0) {
+      const key = "content" in command.shape ? "content" : "markdown" in command.shape ? "markdown" : void 0;
+      if (!key) throw new DocError("INVALID_INPUT", `"${name}" takes no --file`);
+      if (key in input) throw new DocError("INVALID_INPUT", `pass --file or --${key}, not both`);
+      input[key] = readFileSync(file, "utf8");
+    }
+    const result = await command.run(service, input, author);
+    if (name === "export") {
+      const { data, encoding } = result;
+      const bytes = encoding === "base64" ? Buffer.from(data, "base64") : data;
+      if (out === void 0) process.stdout.write(bytes);
+      else writeFileSync(out, bytes);
+    } else console.log(typeof result === "string" ? result.replace(/\n$/, "") : JSON.stringify(result, null, 2));
+    return 0;
+  } catch (error) {
+    if (!(error instanceof DocError)) throw error;
+    console.error(`${error.code}: ${error.message}`);
+    for (const m of error.matches) console.error(`  ${m.occurrence}: ...${m.context}...`);
+    return error.code === "INVALID_INPUT" ? 2 : 1;
+  }
+}
+main(process.argv.slice(2)).then(
+  (code) => {
+    if (code !== 0) process.exit(code);
+  },
+  (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+);
+export {
+  main
+};

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import { P as Principal, A as Anchor, a as AgenticDoc, T as TextTarget, b as AnchorTarget, D as DocAccess, c as PmNode } from './service-BKkxEnaJ.js';
+export { d as DocInfo, e as DocOptions, f as DocsPorts, g as DocsService, E as EditEntry, h as PRINCIPAL_KINDS, i as PrincipalKind, S as Section, j as SectionTarget, k as Target, l as blocksToMarkdown, m as markdownToBlocks, p as parseAuthor } from './service-BKkxEnaJ.js';
+import { Schema } from 'prosemirror-model';
+import { z } from 'zod';
+import { AdapterOptions, Blobs, Store } from 'agentic-identity';
+import 'yjs';
+
+type DocErrorCode = "NO_MATCH" | "AMBIGUOUS_MATCH" | "STALE_ANCHOR" | "NO_SECTION" | "INVALID_AUTHOR" | "INVALID_INPUT" | "NO_THREAD" | "NO_SUGGESTION" | "ALREADY_DECIDED" | "FORBIDDEN" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "LOCKED" | "CONFLICT" | "MISCONFIGURED";
+declare class DocError extends Error {
+    readonly code: DocErrorCode;
+    readonly matches: {
+        occurrence: number;
+        context: string;
+    }[];
+    constructor(code: DocErrorCode, message: string, matches?: {
+        occurrence: number;
+        context: string;
+    }[]);
+}
+
+declare const schema: Schema<string, string>;
+
+interface Message {
+    id: string;
+    at: string;
+    author: Principal;
+    body: string;
+}
+interface Thread {
+    id: string;
+    anchor: Anchor;
+    status: "open" | "resolved";
+    resolvedBy?: Principal;
+    resolvedAt?: string;
+    messages: Message[];
+    /** The anchored text no longer matches what the comment was made on. */
+    stale: boolean;
+    /** The text now under the anchor, or null when it is gone. */
+    currentText: string | null;
+}
+interface Suggestion {
+    id: string;
+    kind: "insert" | "replace" | "delete";
+    at?: "before" | "after";
+    anchor: Anchor;
+    replacement: string;
+    author: Principal;
+    createdAt: string;
+    status: "pending" | "accepted" | "rejected";
+    decidedBy?: Principal;
+    decidedAt?: string;
+    stale: boolean;
+}
+/** Comment threads anchored to text. Replies and status merge across replicas. */
+declare class Threads {
+    private readonly doc;
+    constructor(doc: AgenticDoc);
+    private get map();
+    private get;
+    private message;
+    add(target: TextTarget | AnchorTarget, body: string, author: Principal): string;
+    reply(id: string, body: string, author: Principal): void;
+    private setStatus;
+    resolve(id: string, author: Principal): void;
+    reopen(id: string, author: Principal): void;
+    list(filter?: {
+        status?: Thread["status"];
+    }): Thread[];
+}
+/** Suggested edits. Nothing changes in the text until a person, or an agent with the accept scope, accepts one. */
+declare class Suggestions {
+    private readonly doc;
+    constructor(doc: AgenticDoc);
+    private get map();
+    private get;
+    private read;
+    /** An `at` on the target means insert. An empty replacement means delete. */
+    add(target: TextTarget | AnchorTarget, replacement: string, author: Principal): string;
+    private decide;
+    /**
+     * Apply the edit as the accepting author. The check and the edit share one transaction. Accepting
+     * an accepted suggestion changes nothing. A stale anchor throws and the suggestion stays pending.
+     */
+    accept(id: string, author: Principal): void;
+    /** Same right as accept. A person can withdraw their own suggestion. An agent can never decide its own. */
+    reject(id: string, author: Principal): void;
+    list(filter?: {
+        status?: Suggestion["status"];
+    }): Suggestion[];
+}
+
+/** One table drives the CLI, the MCP server, and the HTTP API, so they stay the same. */
+interface Command {
+    name: string;
+    description: string;
+    shape: z.ZodRawShape;
+    readOnly: boolean;
+    run(service: DocAccess, input: Record<string, unknown>, author: Principal | undefined): Promise<unknown>;
+}
+declare const commands: Command[];
+
+declare const EXPORT_FORMATS: readonly ["md", "html", "odt"];
+type ExportFormat = (typeof EXPORT_FORMATS)[number];
+interface ExportOptions {
+    /** Keep `<img>` for web and relative sources. Opening the page then asks those hosts for the image. Off by default. */
+    remoteImages?: boolean;
+}
+interface ExportResult {
+    format: ExportFormat;
+    contentType: string;
+    encoding: "utf8" | "base64";
+    data: string;
+}
+declare function exportDoc(doc: AgenticDoc, format: ExportFormat, options?: ExportOptions): ExportResult;
+
+interface FileBlobsOptions extends AdapterOptions {
+    /** A lock older than this is taken over. Default 10 seconds. A save takes milliseconds. */
+    lockStaleMs?: number;
+    /** How long a writer waits for a lock before it fails with LOCKED. Default 5 seconds. */
+    lockTimeoutMs?: number;
+}
+/**
+ * Blobs kept as files under one directory. File names are key hashes, so no key leaves the folder.
+ * A write takes a lock file, checks the condition again, then writes a temp file and renames it into
+ * place. A reader never sees a torn file, and two processes cannot both pass the version check.
+ */
+declare function createFileBlobs(dir: string, options?: FileBlobsOptions): Blobs;
+
+/**
+ * A Store kept in one file. The file holds every doc as one snapshot, saved through the file Blobs
+ * adapter with a conditional write. Each call loads the newest snapshot, so several processes (CLI
+ * runs, MCP servers) share one dataset. A transaction holds a lock file from its first read to its
+ * commit, so a rival write waits and lands after it. The conditional write is a second guard: if the
+ * lock was lost and the snapshot changed, the transaction runs again on the new snapshot.
+ * The store re-reads and re-writes the whole snapshot on each call: it suits a small local catalog.
+ */
+declare function createFileStore(dir: string, options?: AdapterOptions & Pick<FileBlobsOptions, "lockStaleMs" | "lockTimeoutMs"> & {
+    shared?: string;
+}): Store;
+
+declare const ODT_MIME = "application/vnd.oasis.opendocument.text";
+/** Write blocks as an OpenDocument text file (.odt): content, styles, and images as embedded files. */
+declare function exportOdt(blocks: PmNode[]): Uint8Array;
+
+export { AgenticDoc, Anchor, AnchorTarget, type Command, DocError, type DocErrorCode, EXPORT_FORMATS, type ExportFormat, type ExportOptions, type ExportResult, type FileBlobsOptions, type Message, ODT_MIME, PmNode, Principal, type Suggestion, Suggestions, TextTarget, type Thread, Threads, commands, createFileBlobs, createFileStore, exportDoc, exportOdt, schema };

package/dist/index.js

@@ -0,0 +1,44 @@
+import {
+  createFileBlobs,
+  createFileStore
+} from "./chunk-TFCRPEEM.js";
+import {
+  DocsService
+} from "./chunk-FZA5LQV3.js";
+import {
+  EXPORT_FORMATS,
+  ODT_MIME,
+  commands,
+  exportDoc,
+  exportOdt
+} from "./chunk-GYQFTF2E.js";
+import {
+  AgenticDoc,
+  DocError,
+  PRINCIPAL_KINDS,
+  Suggestions,
+  Threads,
+  blocksToMarkdown,
+  markdownToBlocks,
+  parseAuthor,
+  schema
+} from "./chunk-YBBQNCMC.js";
+export {
+  AgenticDoc,
+  DocError,
+  DocsService,
+  EXPORT_FORMATS,
+  ODT_MIME,
+  PRINCIPAL_KINDS,
+  Suggestions,
+  Threads,
+  blocksToMarkdown,
+  commands,
+  createFileBlobs,
+  createFileStore,
+  exportDoc,
+  exportOdt,
+  markdownToBlocks,
+  parseAuthor,
+  schema
+};

package/dist/live-worker.d.ts

@@ -0,0 +1,20 @@
+import { createDurableObjectRealtime } from 'agentic-realtime/worker';
+export { SyncRoom } from 'agentic-realtime/worker';
+import { WorkerEnv } from './worker.js';
+import 'hono';
+import 'agentic-identity';
+import 'agentic-identity/cloudflare';
+import 'agentic-realtime';
+import './service-BKkxEnaJ.js';
+import 'yjs';
+
+type Namespace = Parameters<typeof createDurableObjectRealtime>[0];
+interface LiveEnv extends WorkerEnv {
+    /** Durable Object namespace of the live rooms. Bind `SyncRoom` to it. */
+    SYNC_ROOM?: Namespace;
+}
+declare const _default: {
+    fetch: (request: Request, env: LiveEnv, ctx: unknown) => Response | Promise<Response>;
+};
+
+export { type LiveEnv, _default as default };

package/dist/live-worker.js

@@ -0,0 +1,27 @@
+import {
+  createApp,
+  regionOf,
+  serviceFor
+} from "./chunk-IU3YIQ4Y.js";
+import "./chunk-FZA5LQV3.js";
+import "./chunk-GYQFTF2E.js";
+import {
+  DocError
+} from "./chunk-YBBQNCMC.js";
+
+// src/live-worker.ts
+import { createDurableObjectRealtime } from "agentic-realtime/worker";
+import { SyncRoom } from "agentic-realtime/worker";
+var app = createApp(serviceFor, {
+  live: (env) => {
+    const region = regionOf(env);
+    const rooms = env.SYNC_ROOM;
+    if (!rooms) throw new DocError("MISCONFIGURED", "bind a Durable Object namespace as SYNC_ROOM");
+    return createDurableObjectRealtime(rooms, region === "eu" ? "eu" : void 0);
+  }
+});
+var live_worker_default = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+export {
+  SyncRoom,
+  live_worker_default as default
+};

package/dist/live.d.ts

@@ -0,0 +1,73 @@
+import { Peer } from 'agentic-realtime/client';
+import { a as AgenticDoc, P as Principal, e as DocOptions, D as DocAccess } from './service-BKkxEnaJ.js';
+import 'yjs';
+import 'agentic-identity';
+
+interface LiveOptions {
+    /** The Worker address, such as `https://docs.example.com`. */
+    server: string;
+    /** Document id. */
+    id: string;
+    /** A bearer token. The server maps it to the author kind and the role. */
+    token: string;
+    /** The name other people see in presence. Defaults to the author name. */
+    name?: string;
+    /** Reconnect after a drop. Edits made offline merge when the socket returns. */
+    reconnect?: {
+        initialMs?: number;
+        maxMs?: number;
+    };
+    doc?: DocOptions;
+    /** Start an empty room from the stored document. Default true. A merge is safe when the room already holds it. */
+    seed?: boolean;
+}
+/** Who the server says the token is. */
+interface Me {
+    author: Principal;
+    role: "editor" | "viewer";
+}
+declare function whoAmI(server: string, token: string): Promise<Me>;
+/**
+ * One document, open in a live room. The author of every edit is the one the server reads from the
+ * token, so an agent token always writes agent edits. The room keeps the edits, the stored author
+ * label of each update, and the state for the next join.
+ */
+declare class LiveDoc {
+    readonly doc: AgenticDoc;
+    readonly me: Me;
+    private readonly client;
+    private readonly api;
+    private readonly refusedAtStart;
+    private constructor();
+    static join(options: LiveOptions): Promise<LiveDoc>;
+    /** Saves the room's state to the stored document, through the Blobs port. A viewer cannot save. */
+    save(): Promise<void>;
+    /** The other people and agents in the room. `machine` is true for an agent. */
+    get peers(): Peer[];
+    /** Why the room dropped an update, in order. */
+    get denied(): string[];
+    /**
+     * Runs one change as the token's author and waits until the room has it. A viewer fails before the change.
+     * After a refusal from the room the local copy still holds the change. Leave and join again.
+     */
+    edit<T>(run: (doc: AgenticDoc, author: Principal) => T): Promise<T>;
+    /** Waits until the room has every change made so far. */
+    flush(): Promise<void>;
+    leave(): Promise<void>;
+}
+/**
+ * The commands of the CLI and the MCP server, run in a live room. Each call joins the room, runs one
+ * change as the token's author, saves to the stored document, and leaves. A read joins and leaves.
+ */
+declare class LiveService implements DocAccess {
+    private readonly options;
+    constructor(options: Pick<LiveOptions, "server" | "token" | "name" | "doc">);
+    private join;
+    /** The room is only a copy, so a new document is made in the store. A room seeds from it on the next join. */
+    create(id: string, markdown: string): Promise<void>;
+    read<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+    write<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+    private exists;
+}
+
+export { LiveDoc, type LiveOptions, LiveService, type Me, whoAmI };

package/dist/live.js

@@ -0,0 +1,12 @@
+import {
+  LiveDoc,
+  LiveService,
+  whoAmI
+} from "./chunk-R5XUTBC3.js";
+import "./chunk-FZA5LQV3.js";
+import "./chunk-YBBQNCMC.js";
+export {
+  LiveDoc,
+  LiveService,
+  whoAmI
+};

package/dist/mcp-P2C75IIG.js

@@ -0,0 +1,40 @@
+import {
+  VERSION
+} from "./chunk-5Y66UCTE.js";
+import {
+  commands
+} from "./chunk-GYQFTF2E.js";
+import {
+  DocError
+} from "./chunk-YBBQNCMC.js";
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+function createMcpServer(service, author) {
+  const server = new McpServer({ name: "agentic-documents", version: VERSION });
+  for (const command of commands) {
+    server.registerTool(
+      `doc_${command.name}`,
+      { description: command.description, inputSchema: command.shape, annotations: { readOnlyHint: command.readOnly } },
+      async (input) => {
+        try {
+          const result = await command.run(service, input, author);
+          return { content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result) }] };
+        } catch (error) {
+          if (!(error instanceof DocError)) throw error;
+          const body = { error: { code: error.code, message: error.message, matches: error.matches } };
+          return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
+        }
+      }
+    );
+  }
+  return server;
+}
+async function startMcp(service, author) {
+  await createMcpServer(service, author).connect(new StdioServerTransport());
+}
+export {
+  createMcpServer,
+  startMcp
+};