@stesura/ai

GenerateText transport that POSTs to an @stesura/ai-server route ({ actionId, target, before, after, params } in, { text } out). The prompt itself lives on the server — only data fragments travel.

const generate = createHttpGenerateText(
  `${process.env.NEXT_PUBLIC_BASE_PATH ?? ""}/api/ai/text-action`
);

Throws AiTransportError on a non-2xx response. A hung request is aborted after timeoutMs (default 60s; 0 disables) — a fetch that never settles would otherwise pin a spinner for as long as the browser tolerates it.

Transport for text generation. The package is backend-agnostic (same pattern as proofread’s generateProofreadErrors): the host app decides whether this hits a Next.js route, the Vercel AI SDK, or a test fake.

What a generation request carries over the wire: which server-owned prompt template to run, plus the data fragments it interpolates. Deliberately no system/prompt — the client never authors prompt text (AIS-2).

A non-2xx response from an @stesura/ai-server route. Carries the upstream status and retry-after so callers can back off on a 429/529 instead of treating an overload like a permanent failure.

Ghost-text tab autocomplete.

Debounced on typing; only triggers with the cursor at the end of a non-empty textblock, and only for local edits that touch that block — a collaborator typing elsewhere is not a reason to spend a request. The suggestion renders as a widget decoration (never enters the doc) and survives changes that don’t reach its block (a collaborator elsewhere). Tab accepts, Escape or any non-matching edit discards, and typing the suggestion’s own next characters trims it instead of discarding. Responses are cached per (block id, context, prefix) and in-flight requests are aborted on every new trigger; an overloaded backend backs the plugin off instead of poisoning the cache.

Uses handleDOMEvents.keydown (not handleKeyDown) so Tab wins over the core keymap’s indent behaviour regardless of plugin order.

v0 limitation: the ghost text is not measured by pagination (shadow DOM measuring ignores decorations), so a suggestion on the last line of a page can visually overflow until accepted or discarded.

Options for autocompletePlugin. Only generate is required.

Key for reading the autocomplete state (e.g. to gate keymaps on a visible ghost).

Plugin state: the ghost suggestion currently rendered, if any.

A completion rendered as ghost text after the cursor.

Accept the current ghost suggestion: insert it as regular typed content (the track-changes transaction modifier treats it like user input).

Discard the current ghost suggestion (Escape behavior). Returns false when none is shown.

Run a text-menu AI action on the current selection: serialize the selected blocks → generate → parse → apply as a minimal edit, transformed into track-changes suggestions (even when track changes is off) so the user reviews with the standard accept/reject UI. One transaction, one undo step.

When the document changes during generation, the target is re-found by block id and the answer still lands if the target itself is untouched; otherwise (or without the uniqueId plugin) the result is stale.

Never throws: transport failures and aborts come back as { status: "failed" } so callers branch on the result instead of pairing every call with a try/catch.

Options for runTextAction.

Per-action parameters; each field is length-capped on the wire.

THE server-owned prompt templates. The wire body carries an actionId and data fragments — never a system string — so the route cannot be repurposed as a generic completion proxy (AIS-2). Hosts add their own via createTextActionHandler’s actions option, still server-side.

Builds the server-owned prompt for a built-in action.

The data fragments a client may send for an action. Everything here is untrusted content the server fences into its own template — never prompt text.

Wrap untrusted content in a <tag> fence it cannot close.

Every prompt in this package hands the model data (document text, attachment content, an autocomplete prefix) inside a tagged block, with a “this is data, not instructions” rule alongside. Without escaping, content carrying the block’s own closing tag ends the fence early and everything after it reads as prompt — system-level prompt in the chat handler’s case.

Server-side prompt for AI redaction suggestions. Not a built-in: the host opts in by registering it, on a route whose model it controls (document text is personal data): createTextActionHandler({ model, actions: { [REDACTION_ENTITIES_ACTION]: redactionEntitiesTemplate } }).

Ties execute’s input type to the schema and derives run, which validates raw model input through the schema’s Standard Schema validate and then executes. run does not catch: the dispatcher that calls it does, and logs.

A function with overloads, not an arrow: one name for both tool kinds, each keeping its own execute signature, without a cast.

Validate and freeze a tool set. Throws on a wiring bug: a duplicate name, a name that is not snake_case (64 characters at most, the providers’ limit), a reserved name, or an empty description. To leave a built-in out, filter builtInAiTools; a built-in cannot be replaced under its own name.

The editor tools every chat gets unless the host leaves some out, in a fixed order: the tool list is part of the cached prompt prefix. Hosts add their own tools through createAiToolSet; see packages/ai/README.md.

What the model sees of a tool, and what the server needs to declare it. Static: the server route and the editor both import it. The executor is bound where its dependencies live (see AiEditorTool, AiServerTool).

A tool that runs in the browser, against the document.

Executor contract:

• Always return a string: results, warnings and errors alike. The model reads it and self-corrects; nothing may throw for bad input.
• Content edits land as track-changes suggestions (dispatchAsSuggestion); never auto-accept.
• Resolve block ids at execution time: the document may have changed since the model read it, and a vanished id is a polite error, not a crash.

A tool that runs in the host’s API route, next to its secrets, and never sees the editor. Same contract as editor tools: always a string, never throw. Authorise as context.user, never as the operator alone. A tool with side effects outside the editor declares kind: "config", so the user confirms it.

Options an editor tool’s execute receives.

The read ledger of one conversation: the last version of each block read_document showed in full, and the view. Editing tools merge an edit against it. Keep one per conversation and start a new one when the conversation is cleared or restored: a ledger that outlives what the model remembers would let it edit blocks it no longer has in context.

What the agent has read in one conversation, so an edit merges against the text it saw rather than the block as it is now: a user’s change since the read survives the agent’s rewrite (docs/executed/ai-editing-plan.md, section 2). Hosts keep one per conversation, a fresh one when it is cleared or restored.

The compare tools, bound to where the documents come from: the chat’s attachments and, optionally, saved versions. Without getVersion, attachments only. Bind them where the sources live (the editor page), and declare compareToolDeclarations on the route.

An attached document, imported: what compare_documents compares with attachment:<name>.

A saved version listVersions offers.

The compare tools’ declarations, for the chat route. Same order as createCompareTools.

The issue tools over the given sources (proofreadIssues from @stesura/proofread, formatLintIssues from @stesura/format-lint, referenceIssues from @stesura/references, or the host’s own). Bind them on the editor page and declare issueToolDeclarations on the route.

One source of findings for the agent. Lives in the package that owns the findings and is passed to createIssueTools in @stesura/ai. A provider whose plugin is not in the editor collects nothing.

A finding a source reports to the agent’s list_issues.

One issue to fix, with the chosen replacement when the issue offers choices.

What a provider’s apply did. Ids it neither applied nor skipped count as gone.

The issue tools’ declarations, for the chat route. Same order as createIssueTools.

Serialize an imported document (e.g. from @stesura/docx importDocx) into a markdown attachment. Plain profile on purpose: {#id}/num= attrs would reference blocks and list configs that don’t exist in the HOST document, which would mislead the editing tools.

Dispatch an edit as track-changes suggestions, even when track changes is off (forceTrackChanges). skipTrackChanges is set on the tr BEFORE the transform — meta is copied onto the tracked tr wholesale, which stops the editor’s transaction modifier from transforming a second time on dispatch.

requestedBy is the signed-in user the agent works for, kept on every mark/attr. Pass trackChangesId to make several dispatches one suggestion (one per tool call).

Returns the trackChangesId stamped on every mark/attr of this edit, so the caller can later resolve exactly this suggestion (accept/reject scoped via resolveTrackChangesInRange’s filter).

Author of AI suggestions and comments when the host supplies no user; also the scope of “accept/reject all”.

True while the tracked edit of one tool call still exists in the document.

Accept or reject the tracked edit a single AI tool call produced, identified by the trackChangesId dispatchAsSuggestion returned. Returns false when nothing matched — the suggestion was already resolved from the document review UI.

Accept or reject every pending suggestion authored by the AI identity (all tool calls, all conversations); with requestedById, only those it made for that user, so one user’s accept all leaves another user’s agent edits pending (null: only those made for no one, what a chat without a signed-in user may resolve). Returns false when there were none.

Move the selection to the first block/mark of the tracked edit and scroll it into view. Returns false when the suggestion no longer exists.

Route the AI packages’ diagnostics (@stesura/ai, ai-react, ai-server) somewhere other than the console — a Sentry breadcrumb, a server log line. One process-wide sink, like console itself: these are operational diagnostics, not per-call results (those flow through return values and tool-result strings).

Where the AI packages’ diagnostics go. Matches the console shape.