revise 2.2.0 → 3.0.0

package/serverToolContract.d.ts

@@ -1,391 +0,0 @@
-/**
- * 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;
-}
-
-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;
-}
-
-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

@@ -1,250 +0,0 @@
-// 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: {
-    count?: number;
-    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>;
-    count?: number;
-    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;
-    left?: string;
-    right?: string;
-    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_row: {
-    rowIndex: 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: {
-    count?: number;
-    id?: string;
-    ids?: Array<string>;
-    search_result_id?: string;
-    through_end?: boolean;
-  };
-}
-
-export type ReviseToolName = keyof ReviseToolInputMap;
-export type ReviseToolInput<Name extends ReviseToolName> =
-  ReviseToolInputMap[Name];