Tools for your agent

const definitions = editor.tools.getDefinitions();

const response = await yourModel.createMessage({
  messages,
  tools: definitions.map((tool) => ({
    name: tool.name,
    description: tool.description,
    input_schema: tool.inputSchema,
  })),
});

for (const call of response.toolCalls) {
  const result = await editor.tools.executeDynamic(call.name, call.input);
  messages.push({
    role: "tool",
    tool_call_id: call.id,
    content: result.ok
      ? (result.value.message ?? JSON.stringify(result.value.data))
      : `${result.error.code}: ${result.error.message}`,
  });
}

type ReviseToolResult<Name> =
  | { ok: true; value: ReviseToolResponse<Name> }
  | { ok: false; error: ReviseToolFailure<Name> }; // { callId, tool, code, message }

interface ReviseToolResponse<Name> {
  callId: string;
  tool: Name;
  message: string | null; // model-oriented explanation
  data: ReviseToolData<Name>; // typed structured metadata, per tool
  context: { format: "revise-html"; html: string } | null;
  suggestionIds: string[] | null; // tracked records this mutation created
}

const read = await editor.tools.call("read_blocks_from_index", {
  index: 0,
  context_notes: "Looking for the liability clause",
});

await editor.tools.call("replace", {
  id: "b12",
  replacements: [
    {
      find: "capped at the fees paid",
      replace: "capped at two years of fees paid",
      occurrence: "unique",
    },
  ],
});

const search = await editor.tools.call("search_document", {
  queries: ["Acme Corp."],
  page: 0,
  context_notes: "Renaming the counterparty throughout",
});

await editor.tools.call("replace", {
  search_result_id: search.data.search_result_id,
  replacements: [
    { find: "Acme Corp.", replace: "Acme Holdings Ltd.", occurrence: "all" },
  ],
});

await editor.tools.call("set_title", { title: "Exhibit A" }, {
  documentId: "exhibit-a",
});

// or bind a controller once
const exhibit = editor.tools.forDocument("exhibit-a");
await exhibit.execute("measure_document", {});

await editor.tools.call("style_blocks", input, { directMode: true });

import { readFile, writeFile } from "node:fs/promises";
import {
  createServerDocumentSession,
  decodeYDoc,
  encodeYDoc,
  fileToYDoc,
  ydocToDocx,
} from "@reviseio/sdk/backend";

const ydoc = await fileToYDoc(
  await readFile("agreement.docx"),
  "agreement.docx",
);
const document = await createServerDocumentSession(ydoc, {
  documentId: "agreement-1",
  mode: "suggesting",
});

const read = await document.tools.call("read_blocks_from_index", {
  index: 0,
  context_notes: "Locating the liability clause",
});
console.log(read.context?.html); // block-ID-preserving Revise semantic HTML

const search = await document.tools.call("search_document", {
  queries: ["fees paid"],
  page: 0,
  context_notes: "Liability cap",
});
const searchResultId = search.data.search_result_id;
if (!searchResultId) throw new Error("The search returned no editable matches");

// Exact-text changes require no authored HTML. Apply this one directly.
document.setEditingMode();
await document.tools.call(
  "replace",
  {
    search_result_id: searchResultId,
    replacements: [{ find: "fees paid", replace: "fees paid or payable" }],
  },
);

// Switch back whenever the workflow should produce tracked changes.
document.setSuggestingMode();
const governingLaw = await document.tools.call("search_document", {
  queries: ["Delaware"],
  page: 0,
  context_notes: "Suggesting a governing-law change",
});
const governingLawId = governingLaw.data.search_result_id;
if (!governingLawId) throw new Error("The governing-law text was not found");
const edit = await document.tools.call("replace", {
  search_result_id: governingLawId,
  replacements: [{ find: "Delaware", replace: "New York" }],
});

// Review by ID — the primary path. Mutation results report the tracked
// records they created; persist these with your review task.
const created = edit.suggestionIds ?? [];
const decision = document.acceptSuggestions(created);
// decision.resolved — settled now; decision.missing — stale or unknown IDs.

// Or inspect everything pending first. Records carry authorship, so a host
// can decide on its own agent's suggestions and leave collaborators' alone:
const mine = document
  .listSuggestions()
  .filter((record) => record.authorType === "ai");
// document.rejectSuggestions(mine.map((record) => record.id));

// Whole-document decisions exist, but they settle collaborators' pending
// suggestions too — reach for them only when the host owns the document:
// document.acceptAllSuggestions(); // or document.rejectAllSuggestions()

await writeFile("agreement.yjs", encodeYDoc(ydoc));
const restored = decodeYDoc(await readFile("agreement.yjs"));
await writeFile("agreement-amended.docx", await ydocToDocx(restored));
document.dispose();

const result = await document.tools.executeDynamic(call.name, call.input);
const toolMessage = result.ok
  ? (result.value.message ?? JSON.stringify(result.value.data))
  : `${result.error.code}: ${result.error.message}`;