Skip to main content
Reference for AIActions helpers and the high-level action surface. AIActions exposes two layers of functionality:
  1. Wrapper methods on the AIActions instance (lifecycle & raw completions).
  2. Action helpers under ai.action, which combine prompting, response parsing, and editor updates.

​
Instance methods

​
waitUntilReady

Resolves once provider/user set-up completes. Safe to call multiple times. Returns: Promise<void> Example: 
await ai.waitUntilReady();
console.log('AI is ready!');

​
getIsReady

Returns true after initialisation. Returns: boolean Example: 
if (ai.getIsReady()) {
  console.log('AI is ready!');
}

​
getCompletion

Single-shot completion that includes the serialized document context. Parameters:
​
prompt
string
required
The user prompt for the AI
​
options
CompletionOptions
Optional completion configuration
Returns: Promise<string> Example: 
const response = await ai.getCompletion('Summarise the introduction', {
  temperature: 0.3,
  maxTokens: 600,
  stop: ['</summary>'],
  metadata: { documentId: 'contract-42' },
  providerOptions: { top_p: 0.9 },
});

​
streamCompletion

Streams a completion, firing hooks for each chunk and resolving with the full string. Parameters:
​
prompt
string
required
The user prompt for the AI
​
options
StreamOptions
Optional streaming configuration
Returns: Promise<string> Example: 
const response = await ai.streamCompletion('Explain the GDPR section', {
  temperature: 0.7,
  maxTokens: 1000,
});

​
getDocumentContext

Retrieves the current document context for AI processing. Returns the plain text content of the active editor document. Returns: string Example: 
const context = ai.getDocumentContext();
console.log('Document text:', context);

​
Action helpers

All actions return a Result object containing { success: boolean; results: FoundMatch[] }. Each FoundMatch includes the AI text (originalText, suggestedText) alongside the resolved document positions.

​
find

Finds the first occurrence and resolves its document positions. Parameters:
​
instruction
string
required
AI instruction describing what to find
Returns: Promise<Result> Example: 
const { success, results } = await ai.action.find('GDPR clause');
if (success && results[0]?.positions?.length) {
  console.log('Found at', results[0].positions[0]);
}

​
findAll

Finds every occurrence matching the instruction. Parameters:
​
instruction
string
required
AI instruction describing what to find
Returns: Promise<Result>

​
highlight

Highlights the first match in the editor with the specified color. Parameters:
​
instruction
string
required
AI instruction describing what to highlight
​
color
string
default:"#6CA0DC"
Hex color code for the highlight
Returns: Promise<Result>

​
replace

Replaces a single match with AI-generated text. Parameters:
​
instruction
string
required
AI instruction describing what to replace and how
Returns: Promise<Result> Example: 
await ai.action.replace('Replace "utilize" with "use"');

​
replaceAll

Replaces every match with AI-generated text. Parameters:
​
instruction
string
required
AI instruction describing what to replace and how
Returns: Promise<Result>

​
insertTrackedChange

Inserts a tracked change attributed to the configured user (e.g., “RedlineBot”). Parameters:
​
instruction
string
required
AI instruction describing what change to track
Returns: Promise<Result> Example: 
await ai.action.insertTrackedChange(
  'Rewrite the GDPR clause as bullet points'
);

​
insertTrackedChanges

Inserts tracked changes for multiple matches. Parameters:
​
instruction
string
required
AI instruction describing what changes to track
Returns: Promise<Result>

​
insertComment

Inserts a comment annotating the first match. Parameters:
​
instruction
string
required
AI instruction describing what to comment on
Returns: Promise<Result>

​
insertComments

Inserts comments for every match. Parameters:
​
instruction
string
required
AI instruction describing what to comment on
Returns: Promise<Result>

​
summarize

Returns AI-generated summary text in the suggestedText field. Streams results if the provider supports streaming. Parameters:
​
instruction
string
required
AI instruction describing what to summarize
Returns: Promise<Result> Example: 
const { results } = await ai.action.summarize('Summarize the introduction');
console.log(results[0]?.suggestedText);

​
insertContent

Inserts AI-generated content into the document at the current cursor position, or appends it to the end if no cursor location is set. Content streams directly into the editor as it arrives from the provider. Parameters:
​
instruction
string
required
AI instruction describing what content to insert
Returns: Promise<Result>

​
Types

​
Result

{
  success: boolean;
  results: FoundMatch[];
}
Standard result structure returned by all AI actions.

​
FoundMatch

{
  originalText?: string;
  suggestedText?: string;
  positions?: DocumentPosition[];
}
Represents a match found by AI operations, with optional original text, suggested replacement, and document positions.

​
DocumentPosition

{
  from: number;
  to: number;
}
Position range in the document (character offsets).

​
CompletionOptions

{
  temperature?: number;
  maxTokens?: number;
  stop?: string[];
  model?: string;
  signal?: AbortSignal;         // Cancel request
  metadata?: Record<string, unknown>;  // Custom metadata
  providerOptions?: Record<string, unknown>;  // Provider-specific options
  documentId?: string;          // Document tracking
}
Configuration options for getCompletion() calls.

​
StreamOptions

{
  temperature?: number;
  maxTokens?: number;
  stop?: string[];
  model?: string;
  signal?: AbortSignal;         // Cancel request
  metadata?: Record<string, unknown>;  // Custom metadata
  providerOptions?: Record<string, unknown>;  // Provider-specific options
  documentId?: string;          // Document tracking
  stream?: boolean;             // Force streaming on/off
}
Configuration options for streamCompletion() calls. Extends CompletionOptions with a stream flag.

​
Advanced Exports

For advanced use cases, the package exports additional classes and utilities:
  • AIActionsService - Core service with direct access to action implementations
  • EditorAdapter - Editor interaction layer for custom integrations
  • createAIProvider(config) - Factory function for creating AI providers
  • isAIProvider(value) - Type guard to check if value is an AIProvider
  • Utilities: validateInput(), parseJSON(), removeMarkdownCodeBlocks(), generateId()