@reviseio/engine 0.0.0-stage → 3.0.0

package/serverToolContract.d.ts

@@ -0,0 +1,420 @@
+/**
+ * The canonical tool contract, shared by both surfaces. The `Server` prefix
+ * marks the headless origin of these types, but since 1.0.0 the browser
+ * surface (`editor.tools`) speaks exactly the same envelope: `execute()`
+ * returns the same discriminated `ReviseToolResult`, `call()` throws the same
+ * `ReviseToolError`, and inputs are typed by the same generated map. Hosts
+ * can share result-handling code between web and Node verbatim.
+ */
+import type {
+  ReviseJsonObject,
+  ReviseJsonValue,
+  ReviseToolInput,
+  ReviseToolName,
+} from "./serverToolInputs.generated.js";
+
+export type {
+  ReviseJsonObject,
+  ReviseJsonPrimitive,
+  ReviseJsonValue,
+  ReviseToolInput,
+  ReviseToolInputMap,
+  ReviseToolName,
+} from "./serverToolInputs.generated.js";
+
+export type ServerDocumentMode = "editing" | "suggesting";
+
+export interface ServerDocumentSessionOptions {
+  documentId: string;
+  /**
+   * Initial mode; the session's mode methods can change it later. Defaults to
+   * "suggesting" — the same posture as the browser surface, and the safe one:
+   * a service proposes tracked changes unless it explicitly opts into
+   * applying edits directly.
+   */
+  mode?: ServerDocumentMode;
+  searchPageSize?: number;
+  /**
+   * Author name stamped on the suggestions and comments this session's tools
+   * create ("Claude", "Contracts bot"). It becomes `w:author` on DOCX
+   * revisions. Defaults to "Revise Agent".
+   */
+  agentName?: string;
+  /** How images inserted by URL are fetched (headless sessions embed them
+   * in the document; nothing goes through Revise). */
+  images?: ImageFetchPolicy;
+}
+
+/**
+ * Network policy for images an agent inserts by URL. Agent input decides the
+ * URL, so by default only public http(s) hosts are reachable: loopback,
+ * private, and link-local addresses are refused, every redirect is checked
+ * the same way, and the download is capped while it streams.
+ */
+export interface ImageFetchPolicy {
+  /** Allow loopback, private, and link-local addresses (the CLI does: it
+   * runs on the user's own machine, for the user). Default false. */
+  allowPrivateNetwork?: boolean;
+  /** Largest image accepted, in bytes. Default 20 MB. */
+  maxBytes?: number;
+  /** Replace the download entirely (a proxy, a cache, an allow-list). */
+  fetch?: (url: string, init: { signal: AbortSignal }) => Promise<Response>;
+}
+
+export interface ReviseToolCallOptions {
+  /** Apply this mutation directly, even when the session is suggesting. */
+  directMode?: boolean;
+}
+
+/** Discriminant of a pending tracked-suggestion record. */
+export type ReviseSuggestionType =
+  | "inline-text"
+  | "inline-format"
+  | "block-change"
+  | "block-insert"
+  | "block-delete"
+  | "table-change"
+  | "paragraph-split"
+  | "paragraph-merge";
+
+/**
+ * One pending tracked-suggestion record, projected for host review flows.
+ * Metadata fields are absent when the underlying record predates uniform
+ * authorship stamping or was written by an older client.
+ */
+export interface ReviseSuggestionRecord {
+  id: string;
+  /** Absent when only stamped content marks carry the suggestion, which is
+   * the norm for inline text edits and for restored documents. */
+  type?: ReviseSuggestionType;
+  /** The top-level block the suggestion targets, for block-scoped types. */
+  blockId?: string;
+  /** The table the suggestion targets, for table-change records. */
+  tableId?: string;
+  authorType?: "ai" | "human";
+  /** Author display name: an agent name or a human's display name. */
+  agentName?: string;
+  /** Provider-qualified model that authored an AI suggestion. */
+  agentModel?: string;
+  source?: string;
+  label?: string;
+  createdAt?: number;
+}
+
+/**
+ * Per-ID outcome of an accept or reject call. IDs a host persisted from an
+ * earlier tool result can go stale — a later suggestion can supersede an
+ * earlier one — so the settled and unknown sets are reported explicitly
+ * instead of an inferred count.
+ */
+export interface ReviseSuggestionDecision {
+  /** Requested IDs that were pending and are now settled. */
+  resolved: string[];
+  /** Requested IDs that were not pending suggestions when the call ran. */
+  missing: string[];
+  /** Requested IDs that were pending but could not be settled. Rare. */
+  unresolved: string[];
+}
+
+export interface ReviseToolDefinition<
+  Name extends ReviseToolName = ReviseToolName,
+> {
+  name: Name;
+  description: string;
+  inputSchema: ReviseJsonObject;
+}
+
+export interface ReviseReadCoverage {
+  requestedBlockCount: number;
+  readBlocksThisTurn: number;
+  readTokenBudgetMax: number;
+  requestedRanges: Array<{ start: number; end: number }>;
+  fullDocumentLoaded: boolean;
+}
+
+export interface ReviseReadData {
+  kind: "read_context";
+  tool: "read_blocks_from_index" | "read_specific_blocks";
+  loaded: ReviseJsonObject;
+  next: { index: number; blockId?: string } | null;
+  endOfDocument: boolean;
+  coverage: ReviseReadCoverage;
+}
+
+export interface ReviseSearchMatch {
+  blockId: string;
+  blockIndex: number;
+  matchedQueries?: string[];
+  matchedColors?: string[];
+}
+
+export interface ReviseSearchData {
+  kind: "search_context";
+  tool: "search_document" | "find_highlights";
+  queries?: string[];
+  color?: string;
+  totalMatches: number;
+  search_result_id?: string;
+  page: {
+    current: number;
+    total: number;
+    startResult: number;
+    endResult: number;
+  };
+  nextPage: number | null;
+  matches: ReviseSearchMatch[];
+  coverage: ReviseReadCoverage;
+}
+
+export interface ReviseDocumentMeasurementSection {
+  startIndex: number;
+  endIndex: number;
+  startBlockId: string;
+  endBlockId: string;
+  headingLevel: 1 | 2 | 3;
+  title: string;
+  wordCount: number;
+  paragraphCount: number;
+  characterCount: number;
+  inclusive: true;
+  blockCount: number;
+  pageStart?: number;
+  pageEnd?: number;
+}
+
+export interface ReviseDocumentMeasurementData {
+  kind: "document_measurement";
+  tool: "measure_document";
+  inclusive: true;
+  totalBlocks: number;
+  wordCount: number;
+  paragraphCount: number;
+  characterCount: number;
+  pageCount?: number;
+  fractionalPageCount?: number;
+  sections?: ReviseDocumentMeasurementSection[];
+  sectionCount?: number;
+  sectionOffset?: number;
+  sectionLimit?: number;
+  returnedSectionCount?: number;
+  hasMoreSections?: boolean;
+  nextSectionOffset?: number;
+}
+
+export interface ReviseMeasuredBlockRange {
+  startIndex: number;
+  endIndex: number;
+  startBlockId: string;
+  endBlockId: string;
+  inclusive: true;
+  blockCount: number;
+  wordCount: number;
+  paragraphCount: number;
+  characterCount: number;
+  pageStart?: number;
+  pageEnd?: number;
+}
+
+export interface ReviseBlockMeasurementData {
+  kind: "document_measurement";
+  tool: "measure_blocks";
+  inclusive: true;
+  totalBlocks: number;
+  ranges: ReviseMeasuredBlockRange[];
+  errors: Array<{
+    startBlockId?: string;
+    endBlockId?: string;
+    error: string;
+  }>;
+}
+
+export interface ReviseMutationData {
+  tool: string;
+  target_reference?: string;
+  summary?: string;
+  effect: {
+    requested_target_count: number;
+    changed_target_count: number;
+    removed_target_count: number;
+    inserted_block_count: number;
+    top_level_blocks_before: number;
+    top_level_blocks_after: number;
+    [key: string]: ReviseJsonValue;
+  };
+  before_block?: string;
+}
+
+export interface ReviseCommentData {
+  commentId: string;
+  /** The block the comment is anchored to. */
+  blockId: string;
+  /** Set when the requested block did not hold the anchor text and the
+   * comment went to the only read block that did. */
+  requestedBlockId?: string;
+  anchor: ReviseJsonObject;
+}
+
+type ReviseReadToolName = "read_blocks_from_index" | "read_specific_blocks";
+type ReviseSearchToolName = "search_document" | "find_highlights";
+type ReviseMeasurementToolName = "measure_document" | "measure_blocks";
+type ReviseSpecializedToolName =
+  | ReviseReadToolName
+  | ReviseSearchToolName
+  | ReviseMeasurementToolName
+  | "leave_comment";
+type ReviseMutationToolName = Exclude<
+  ReviseToolName,
+  ReviseSpecializedToolName
+>;
+
+export type ReviseToolDataMap = {
+  [Name in ReviseReadToolName]: ReviseReadData;
+} & {
+  [Name in ReviseSearchToolName]: ReviseSearchData;
+} & {
+  measure_document: ReviseDocumentMeasurementData;
+  measure_blocks: ReviseBlockMeasurementData;
+  leave_comment: ReviseCommentData;
+} & {
+  [Name in ReviseMutationToolName]: ReviseMutationData | null;
+};
+
+export type ReviseToolData<Name extends ReviseToolName> =
+  ReviseToolDataMap[Name];
+
+/**
+ * A tool's input as application code writes it for typed `execute()` and
+ * `call()`.
+ *
+ * `context_notes` is a model's working memory, carried from one read to the
+ * next, and the model-facing schemas require it. Host code keeps its own
+ * state, so the field is optional here and defaults to `"N/A"`.
+ * `executeDynamic()`, the path for model-provided calls, still requires it.
+ */
+export type ReviseHostToolInput<Name extends ReviseToolName> =
+  ReviseToolInput<Name> extends { context_notes: string }
+    ? Omit<ReviseToolInput<Name>, "context_notes"> & { context_notes?: string }
+    : ReviseToolInput<Name>;
+
+/** Tool arguments, with input optional only when its schema has no required fields. */
+export type ReviseToolArguments<Name extends ReviseToolName> =
+  Record<string, never> extends ReviseHostToolInput<Name>
+    ? [input?: ReviseHostToolInput<Name>, options?: ReviseToolCallOptions]
+    : [input: ReviseHostToolInput<Name>, options?: ReviseToolCallOptions];
+
+/** Semantic document context returned by read and search calls. */
+export interface ReviseDocumentContext {
+  format: "revise-html";
+  html: string;
+}
+
+/** A successful tool call, ready for application code or a model transcript. */
+export interface ReviseToolResponse<Name extends string = ReviseToolName> {
+  callId: string;
+  tool: Name;
+  /** Concise model-oriented summary of what happened. */
+  message: string | null;
+  /** Tool-specific structured data. Literal tool names infer this type. */
+  data: Name extends ReviseToolName
+    ? ReviseToolData<Name>
+    : ReviseJsonValue | null;
+  /** Block-ID-preserving semantic HTML, when the call loaded document text. */
+  context: ReviseDocumentContext | null;
+  /**
+   * For mutation tools, the tracked suggestion records this call created:
+   * non-empty only in suggesting mode. Empty when the edit applied directly,
+   * changed nothing, or extended an existing pending suggestion instead of
+   * creating its own record. Null for read, search, and measurement tools.
+   */
+  suggestionIds: string[] | null;
+  /**
+   * Image payload from browser-only tools (`view_image`). Never present on
+   * the server surface, whose sessions exclude the image pipeline.
+   */
+  image?: {
+    id: string;
+    fileName?: string;
+    urls?: string[];
+    dimensions?: Array<{ width: number; height: number }>;
+  };
+}
+
+/** An expected tool rejection: invalid input, stale context, or unavailable tool. */
+export interface ReviseToolFailure<Name extends string = ReviseToolName> {
+  callId: string;
+  tool: Name;
+  code: string;
+  message: string;
+  /** What the tool reported with the failure, when it says more than the
+   * message: for example `edit_table_cells`' per-cell `errors` and the
+   * `recovery_read` that fixes them. */
+  details?: unknown;
+}
+
+export type ReviseToolResult<Name extends string = ReviseToolName> =
+  | { ok: true; value: ReviseToolResponse<Name> }
+  | { ok: false; error: ReviseToolFailure<Name> };
+
+export interface ServerDocumentTools {
+  getDefinitions(): ReviseToolDefinition[];
+
+  /**
+   * Execute a known tool and preserve expected failures as a discriminated
+   * result. Environment and disposed-session errors still reject the promise.
+   */
+  execute<Name extends ReviseToolName>(
+    name: Name,
+    ...args: ReviseToolArguments<Name>
+  ): Promise<ReviseToolResult<Name>>;
+
+  /** Execute an untrusted model-provided name and JSON input. */
+  executeDynamic(
+    name: string,
+    input?: ReviseJsonObject,
+    options?: ReviseToolCallOptions,
+  ): Promise<ReviseToolResult<string>>;
+
+  /**
+   * Convenient application-code form. Returns only the successful response
+   * and throws ReviseToolError when the tool rejects the call.
+   */
+  call<Name extends ReviseToolName>(
+    name: Name,
+    ...args: ReviseToolArguments<Name>
+  ): Promise<ReviseToolResponse<Name>>;
+}
+
+export interface ServerDocumentSession {
+  /** Return the mode subsequent mutations will capture. */
+  getMode(): ServerDocumentMode;
+  /** Make subsequent mutations produce tracked suggestions. */
+  setSuggestingMode(): void;
+  /** Make subsequent mutations apply directly. */
+  setEditingMode(): void;
+  readonly tools: ServerDocumentTools;
+  /** IDs of pending tracked suggestions currently stored in the Y.Doc. */
+  getPendingSuggestionIds(): string[];
+  /**
+   * Every pending tracked suggestion in the Y.Doc as a reviewable record —
+   * including collaborators' suggestions in a shared document. Filter by
+   * author metadata before making bulk decisions on someone else's work.
+   */
+  listSuggestions(): ReviseSuggestionRecord[];
+  /**
+   * Accept specific pending suggestions by ID — the primary review path.
+   * Collect IDs from mutation results' `suggestionIds` or from
+   * `listSuggestions()`.
+   */
+  acceptSuggestions(suggestionIds: string[]): ReviseSuggestionDecision;
+  /** Reject specific pending suggestions by ID. */
+  rejectSuggestions(suggestionIds: string[]): ReviseSuggestionDecision;
+  /**
+   * Accept every pending suggestion in the Y.Doc, including collaborators'.
+   * Prefer `acceptSuggestions(ids)` unless the host owns the whole document.
+   */
+  acceptAllSuggestions(): ReviseSuggestionDecision;
+  /** Reject every pending suggestion in the Y.Doc, including collaborators'. */
+  rejectAllSuggestions(): ReviseSuggestionDecision;
+  /** Release observers without destroying the supplied Y.Doc. */
+  dispose(): void;
+}

package/serverToolInputs.generated.d.ts

@@ -0,0 +1,264 @@
+// Input types for every Revise tool, generated from the tool schemas.
+export type ReviseJsonPrimitive = string | number | boolean | null;
+export type ReviseJsonValue =
+  | ReviseJsonPrimitive
+  | ReviseJsonValue[]
+  | { [key: string]: ReviseJsonValue };
+export type ReviseJsonObject = { [key: string]: ReviseJsonValue };
+
+export interface ReviseToolInputMap {
+  read_blocks_from_index: {
+    context_notes: string;
+    index: number;
+  };
+  search_document: {
+    context_notes: string;
+    page: number;
+    queries: Array<string>;
+  };
+  find_highlights: {
+    color?: "yellow" | "orange" | "green" | "blue" | "purple" | "pink" | "gray";
+    context_notes: string;
+    page: number;
+  };
+  read_specific_blocks: {
+    block_ids: Array<string>;
+    context_notes: string;
+  };
+  read_table: {
+    cell_id?: string;
+    column_count?: number;
+    column_start?: number;
+    context_notes: string;
+    continuation_revision?: string;
+    mode?: "summary" | "rows" | "cell_text";
+    row_count?: number;
+    row_ids?: Array<string>;
+    row_start?: number;
+    table_id: string;
+    text_offset?: number;
+  };
+  measure_document: {
+    heading_levels?: Array<1 | 2 | 3>;
+    include_sections?: boolean;
+    section_limit?: number;
+    section_offset?: number;
+  };
+  measure_blocks: {
+    mode?: "inclusive";
+    ranges: Array<{
+      end_block_id?: string;
+      start_block_id: string;
+    }>;
+  };
+  insert_block: {
+    content: Array<string>;
+    position: "before" | "after";
+    referenceId: string;
+  };
+  insert_footnote: {
+    find: string;
+    id: string;
+    kind?: "footnote" | "endnote";
+    text: string;
+  };
+  remove_blocks: {
+    end_id?: string;
+    id?: string;
+    ids?: Array<string>;
+    search_result_id?: string;
+    through_end?: boolean;
+  };
+  append_to_paragraph: {
+    content: string;
+    id: string;
+  };
+  break_paragraph: {
+    id: string;
+    substring: string;
+  };
+  join_paragraphs: {
+    firstId: string;
+    secondId: string;
+    separator?: string;
+  };
+  replace_block: {
+    content: Array<string>;
+    end_id?: string;
+    id?: string;
+    search_result_id?: string;
+  };
+  style_blocks: {
+    attrs: Array<{
+      name: string;
+      value: string | number | boolean | null;
+    }>;
+    search_result_id?: string;
+    selectors: string | Array<string>;
+  };
+  clear_formatting: {
+    id: string | Array<string>;
+  };
+  set_title: {
+    title: string;
+  };
+  set_page_layout: {
+    blockSpacing?: string;
+    clearPageBorders?: boolean;
+    columnCount?: 1 | 2 | 3;
+    columnGap?: string;
+    indentStep?: string;
+    margin?: string;
+    marginBottom?: string;
+    marginLeft?: string;
+    marginRight?: string;
+    marginTop?: string;
+    noteMode?: "footnotes" | "endnotes";
+    orientation?: "portrait" | "landscape";
+    pageBorders?: {
+      bottom?: {
+        color: string;
+        spacePt: number;
+        style: "single" | "double" | "dotted" | "dashed";
+        widthPt: number;
+      };
+      display: "allPages" | "firstPage" | "notFirstPage";
+      left?: {
+        color: string;
+        spacePt: number;
+        style: "single" | "double" | "dotted" | "dashed";
+        widthPt: number;
+      };
+      offsetFrom: "page" | "text";
+      right?: {
+        color: string;
+        spacePt: number;
+        style: "single" | "double" | "dotted" | "dashed";
+        widthPt: number;
+      };
+      top?: {
+        color: string;
+        spacePt: number;
+        style: "single" | "double" | "dotted" | "dashed";
+        widthPt: number;
+      };
+      zOrder: "front" | "back";
+    };
+    pageHeight?: string;
+    pageNumberFormat?: "decimal" | "lowerRoman" | "upperRoman";
+    pageNumberPosition?:
+      | "top-left"
+      | "top-right"
+      | "bottom-left"
+      | "bottom-right";
+    pageNumberRestart?: boolean;
+    pageNumberStart?: number;
+    pageSize?:
+      | "letter"
+      | "tabloid"
+      | "legal"
+      | "statement"
+      | "executive"
+      | "folio"
+      | "a3"
+      | "a4"
+      | "a5"
+      | "b4"
+      | "b5";
+    pageWidth?: string;
+    pageless?: boolean;
+    preset?: "apa7";
+    sectionIndex?: number;
+    showPageNumbers?: boolean;
+  };
+  set_header_footer: {
+    center?: string;
+    clear?: boolean;
+    image?: {
+      alt?: string;
+      height?: number;
+      image_id?: string;
+      url?: string;
+      width?: number;
+      zone?: "left" | "center" | "right";
+    };
+    left?: string;
+    right?: string;
+    sectionIndex?: number;
+    side: "header" | "footer";
+    slot?: "default" | "first" | "even";
+  };
+  replace: {
+    id?: string;
+    replacements: Array<{
+      comment?: string;
+      find: string;
+      occurrence?: "unique" | "all";
+      replace: string;
+    }>;
+    search_result_id?: string;
+  };
+  leave_comment: {
+    acknowledge_existing_thread_ids?: Array<string>;
+    anchor?:
+      | {
+          text: string;
+        }
+      | {
+          end_text: string;
+          start_text: string;
+        }
+      | {
+          whole_block: true;
+        };
+    comment: string;
+    id?: string;
+    reply_to_comment_id?: string;
+  };
+  insert_table_row: {
+    content: Array<string>;
+    position: "before" | "after";
+    referenceIndex?: number;
+    referenceRowId?: string;
+    tableId: string;
+  };
+  remove_table_rows: {
+    rowIds?: Array<string>;
+    rowIndices?: Array<number>;
+    tableId: string;
+  };
+  insert_table_column: {
+    content: Array<string>;
+    position: "before" | "after";
+    referenceIndex: number;
+    tableId: string;
+  };
+  remove_table_column: {
+    columnIndex: number;
+    tableId: string;
+  };
+  edit_table_cells: {
+    cells: Array<{
+      column: number;
+      row_id: string;
+      text: string;
+    }>;
+    mode: "fill_if_empty" | "replace";
+    table_id: string;
+  };
+  remove_block: {
+    end_id?: string;
+    id?: string;
+    ids?: Array<string>;
+    search_result_id?: string;
+    through_end?: boolean;
+  };
+  remove_table_row: {
+    tableId: string;
+    rowIndex: number;
+  };
+}
+
+export type ReviseToolName = keyof ReviseToolInputMap;
+export type ReviseToolInput<Name extends ReviseToolName> =
+  ReviseToolInputMap[Name];