Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
// IMPORTANT: this class runs inside the QuickJS sandbox via a generated bundle.
// If you change it, regenerate the sandbox (`bun scripts/generate-sandbox.ts`)
// or the AI's editor surface won't reflect your edits.
import { EditError } from './errors';
import type {
DatabaseQueryView,
DocumentOp,
Format,
ListKind,
MentionSpec,
NodeId,
NodeRef,
NodeSpec,
Position,
Ref,
Scope,
} from './ops';
type SetBlockTypeArgs =
| { block: 'paragraph' }
| { block: 'heading'; level: number }
| { block: 'quote' }
| { block: 'code'; language: string };
export type DocumentEditorOptions = {
/** Durable ids present in the document the model was shown. */
validIds: Iterable<NodeId>;
/** A pool of globally-unique ids the host pre-generated (the sandbox has no
* good entropy of its own). Each insert pops one and stamps it as the new
* node's durable id, so inserted ids never collide — across concurrent
* writers, repeated runs, or sessions. */
refs: string[];
};
/** Describe a non-string id argument without dumping a whole object. */
function describeBadId(value: unknown): string {
if (value === null) return 'null';
if (value === undefined) return 'undefined';
if (Array.isArray(value)) return `an array of ${value.length}`;
if (typeof value === 'object') {
const keys = Object.keys(value as object).slice(0, 4);
return `an object with keys [${keys.join(', ')}]`;
}
return `a ${typeof value} (${String(value)})`;
}
export class DocumentEditor {
private ops: DocumentOp[] = [];
private valid: Set<string>;
private refs: string[];
private refIdx = 0;
constructor(opts: DocumentEditorOptions) {
this.valid = new Set(opts.validIds);
this.refs = opts.refs;
}
private push(op: DocumentOp): this {
this.ops.push(op);
return this;
}
private requireId(id: NodeId): void {
// A non-string argument used to be stringified into the message, producing
// `unknown id "[object Object]"` — which tells the writer nothing about what
// it actually passed. Naming the type and the likely cause does.
if (typeof id !== 'string') {
throw new EditError(
`expected a node id string but got ${describeBadId(id)}. ` +
"Insert helpers return the new node's id directly, so use that value " +
'as-is rather than a property of it.'
);
}
if (id.length === 0) throw new EditError('node id is an empty string');
if (!this.valid.has(id)) {
throw new EditError(`unknown id "${id}"`);
}
}
private requireMatch(match: string): void {
if (match.length === 0) throw new EditError('match string is empty');
}
private mintRef(): Ref {
const ref = this.refs[this.refIdx++];
if (!ref) {
throw new EditError(
'too many inserts in one snippet (id pool exhausted)'
);
}
this.valid.add(ref);
return ref;
}
/** Hand the accumulated ops to the queue and reset. */
public drain(): DocumentOp[] {
const out = this.ops;
this.ops = [];
return out;
}
public format(
id: NodeId,
match: string,
format: Format,
on = true,
scope: Scope = { kind: 'all' }
): this {
this.requireId(id);
this.requireMatch(match);
return this.push({
kind: 'formatText',
node: id,
match,
format,
on,
scope,
});
}
public bold(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'bold', true, scope);
}
public italic(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'italic', true, scope);
}
public underline(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'underline', true, scope);
}
public strike(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'strike', true, scope);
}
public inlineCode(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'code', true, scope);
}
public unbold(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'bold', false, scope);
}
public unitalic(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'italic', false, scope);
}
public ununderline(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'underline', false, scope);
}
public unstrike(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'strike', false, scope);
}
public uninlineCode(id: NodeId, match: string, scope?: Scope): this {
return this.format(id, match, 'code', false, scope);
}
/** Strip all inline formatting from matched substrings (or the whole block if
* `match` is omitted). */
public clearFormat(
id: NodeId,
match?: string,
scope: Scope = { kind: 'all' }
): this {
this.requireId(id);
if (match !== undefined) this.requireMatch(match);
return this.push({ kind: 'clearFormat', node: id, match, scope });
}
public clearAllFormat(id: NodeId): this {
return this.clearFormat(id);
}
public highlight(
id: NodeId,
match: string,
scope: Scope = { kind: 'all' }
): this {
this.requireId(id);
this.requireMatch(match);
return this.push({ kind: 'markText', node: id, match, on: true, scope });
}
public unhighlight(
id: NodeId,
match: string,
scope: Scope = { kind: 'all' }
): this {
this.requireId(id);
this.requireMatch(match);
return this.push({ kind: 'markText', node: id, match, on: false, scope });
}
public link(
id: NodeId,
match: string,
url: string,
scope: Scope = { kind: 'all' }
): this {
this.requireId(id);
this.requireMatch(match);
return this.push({ kind: 'linkText', node: id, match, url, scope });
}
public unlink(
id: NodeId,
match: string,
scope: Scope = { kind: 'all' }
): this {
this.requireId(id);
this.requireMatch(match);
return this.push({ kind: 'linkText', node: id, match, url: null, scope });
}
public formatNode(node: NodeId, format: Format, on = true): this {
this.requireId(node);
return this.push({ kind: 'formatNode', node, format, on });
}
public boldNode(node: NodeId): this {
return this.formatNode(node, 'bold');
}
public italicNode(node: NodeId): this {
return this.formatNode(node, 'italic');
}
public underlineNode(node: NodeId): this {
return this.formatNode(node, 'underline');
}
public strikeNode(node: NodeId): this {
return this.formatNode(node, 'strike');
}
public codeNode(node: NodeId): this {
return this.formatNode(node, 'code');
}
public clearNodeFormat(node: NodeId): this {
this.requireId(node);
return this.push({ kind: 'clearNodeFormat', node });
}
public setText(id: NodeId, text: string): this {
this.requireId(id);
return this.push({ kind: 'setText', node: id, text });
}
public setEquation(id: NodeId, tex: string): this {
this.requireId(id);
return this.push({ kind: 'setEquation', node: id, tex });
}
public replace(
id: NodeId,
find: string,
to: string,
scope: Scope = { kind: 'all' }
): this {
this.requireId(id);
if (find.length === 0) throw new EditError('find string is empty');
return this.push({ kind: 'replaceText', node: id, find, to, scope });
}
public appendText(id: NodeId, text: string): this {
this.requireId(id);
return this.push({ kind: 'appendText', node: id, text });
}
public prependText(id: NodeId, text: string): this {
this.requireId(id);
return this.push({ kind: 'prependText', node: id, text });
}
private setBlockType(id: NodeId, args: SetBlockTypeArgs): this {
this.requireId(id);
return this.push({ kind: 'setBlockType', node: id, ...args });
}
private requireLanguage(language: string): void {
if (typeof language !== 'string' || language.trim().length === 0)
throw new EditError('code block language is required');
}
public convertToParagraph(id: NodeId): this {
return this.setBlockType(id, { block: 'paragraph' });
}
public convertToHeading(id: NodeId, level: number): this {
if (level < 1 || level > 6)
throw new EditError(`heading level must be 1-6, got ${level}`);
return this.setBlockType(id, { block: 'heading', level });
}
public convertToQuote(id: NodeId): this {
return this.setBlockType(id, { block: 'quote' });
}
public convertToCodeBlock(id: NodeId, language: string): this {
this.requireLanguage(language);
return this.setBlockType(id, { block: 'code', language });
}
public setLanguage(id: NodeId, language: string): this {
return this.convertToCodeBlock(id, language);
}
private toList(idOrIds: NodeId | NodeId[], list: ListKind): this {
const ids = Array.isArray(idOrIds) ? idOrIds : [idOrIds];
if (ids.length === 0)
throw new EditError('list requires at least one block');
for (const id of ids) this.requireId(id);
return this.push({ kind: 'setListType', nodes: ids, list });
}
public bulletList(idOrIds: NodeId | NodeId[]): this {
return this.toList(idOrIds, 'bullet');
}
public numberedList(idOrIds: NodeId | NodeId[]): this {
return this.toList(idOrIds, 'number');
}
public checklist(idOrIds: NodeId | NodeId[]): this {
return this.toList(idOrIds, 'check');
}
public setListType(id: NodeId, list: ListKind): this {
return this.toList(id, list);
}
public check(id: NodeId): this {
return this.setChecked(id, true);
}
public uncheck(id: NodeId): this {
return this.setChecked(id, false);
}
public setChecked(id: NodeId, checked: boolean): this {
this.requireId(id);
return this.push({ kind: 'setChecked', node: id, checked });
}
public indent(id: NodeId, by = 1): this {
this.requireId(id);
return this.push({
kind: 'setIndent',
node: id,
indent: by >= 0 ? 'in' : 'out',
});
}
public outdent(id: NodeId, by = 1): this {
return this.indent(id, -Math.abs(by));
}
public setIndent(id: NodeId, level: number): this {
this.requireId(id);
if (level < 0)
throw new EditError(`indent level must be >= 0, got ${level}`);
return this.push({ kind: 'setIndent', node: id, indent: level });
}
public insertListItemAfter(
id: NodeId,
text: string,
list: ListKind = 'bullet'
): Ref {
this.requireId(id);
const ref = this.mintRef();
this.push({ kind: 'insertListItemAfter', ref, node: id, text, list });
return ref;
}
public insertListItemBefore(
id: NodeId,
text: string,
list: ListKind = 'bullet'
): Ref {
this.requireId(id);
const ref = this.mintRef();
this.push({ kind: 'insertListItemBefore', ref, node: id, text, list });
return ref;
}
/** Append a new item to the end of a list, addressed by the list's own
* `<ul>`/`<ol>` id — works even when the list is empty (unlike
* `insertListItemAfter`, which needs an existing sibling item). */
public appendListItem(listId: NodeId, text: string): Ref {
this.requireId(listId);
const ref = this.mintRef();
this.push({ kind: 'appendListItem', ref, node: listId, text });
return ref;
}
/** Prepend a new item to the start of a list, addressed by the list's own
* `<ul>`/`<ol>` id — works even when the list is empty. */
public prependListItem(listId: NodeId, text: string): Ref {
this.requireId(listId);
const ref = this.mintRef();
this.push({ kind: 'prependListItem', ref, node: listId, text });
return ref;
}
public removeListItem(id: NodeId): this {
this.requireId(id);
return this.push({ kind: 'removeListItem', node: id });
}
private insert(spec: NodeSpec, at: Position): Ref {
this.requireAt(at);
const ref = this.mintRef();
this.push({ kind: 'insertNode', ref, spec, at });
return ref;
}
private requireAt(at: Position): void {
if ('after' in at) this.requireId(at.after);
else if ('before' in at) this.requireId(at.before);
}
public insertParagraphAfter(id: NodeId, text = ''): Ref {
return this.insert({ block: 'paragraph', text }, { after: id });
}
public insertParagraphBefore(id: NodeId, text = ''): Ref {
return this.insert({ block: 'paragraph', text }, { before: id });
}
public insertHeadingAfter(
id: NodeId,
level: 1 | 2 | 3 | 4 | 5 | 6,
text = ''
): Ref {
return this.insert({ block: 'heading', level, text }, { after: id });
}
public insertHeadingBefore(
id: NodeId,
level: 1 | 2 | 3 | 4 | 5 | 6,
text = ''
): Ref {
return this.insert({ block: 'heading', level, text }, { before: id });
}
public insertQuoteAfter(id: NodeId, text = ''): Ref {
return this.insert({ block: 'quote', text }, { after: id });
}
public insertCodeBlockAfter(id: NodeId, language: string, text = ''): Ref {
this.requireLanguage(language);
return this.insert({ block: 'code', language, text }, { after: id });
}
public insertBlockAfter(id: NodeId, spec: NodeSpec): Ref {
return this.insert(spec, { after: id });
}
public insertBlockBefore(id: NodeId, spec: NodeSpec): Ref {
return this.insert(spec, { before: id });
}
public appendParagraph(text = ''): Ref {
return this.insert({ block: 'paragraph', text }, { appendToRoot: true });
}
public prependParagraph(text = ''): Ref {
return this.insert({ block: 'paragraph', text }, { prependToRoot: true });
}
public appendBlock(spec: NodeSpec): Ref {
return this.insert(spec, { appendToRoot: true });
}
public prependBlock(spec: NodeSpec): Ref {
return this.insert(spec, { prependToRoot: true });
}
public move(id: NodeId, at: Position): this {
this.requireId(id);
this.requireAt(at);
return this.push({ kind: 'moveNode', node: id, at });
}
public remove(id: NodeId): this {
this.requireId(id);
return this.push({ kind: 'removeNode', node: id });
}
public removeMany(ids: NodeId[]): this {
for (const id of ids) this.remove(id);
return this;
}
public merge(ids: NodeId[], separator = ' '): this {
if (ids.length < 2)
throw new EditError('merge requires at least two blocks');
for (const id of ids) this.requireId(id);
return this.push({ kind: 'mergeBlocks', nodes: ids, separator });
}
public insertTableAfter(id: NodeId, rows: string[][]): Ref {
return this.buildTable(rows, { after: id });
}
public insertTableBefore(id: NodeId, rows: string[][]): Ref {
return this.buildTable(rows, { before: id });
}
public appendTable(rows: string[][]): Ref {
return this.buildTable(rows, { appendToRoot: true });
}
private buildTable(rows: string[][], at: Position): Ref {
if (rows.length === 0)
throw new EditError('table requires at least one row');
const empty = rows.map((row) => row.map(() => ''));
const ref = this.insert({ block: 'table', rows: empty }, at);
rows.forEach(
(row, r) =>
void row.forEach((cell, c) => {
if (cell) this.setCell(ref, r, c, cell);
})
);
return ref;
}
public setCell(table: NodeId, row: number, col: number, text: string): this {
this.requireId(table);
this.requireCell(row, col);
return this.push({ kind: 'setCell', table, row, col, text });
}
public addRow(table: NodeId, at?: number): this {
this.requireId(table);
return this.push({ kind: 'addRow', table, at });
}
public addColumn(table: NodeId, at?: number): this {
this.requireId(table);
return this.push({ kind: 'addColumn', table, at });
}
public removeRow(table: NodeId, row: number): this {
this.requireId(table);
this.requireCell(row, 0);
return this.push({ kind: 'removeRow', table, row });
}
public removeColumn(table: NodeId, col: number): this {
this.requireId(table);
this.requireCell(0, col);
return this.push({ kind: 'removeColumn', table, col });
}
private requireCell(row: number, col: number): void {
if (row < 0 || col < 0)
throw new EditError(`cell indices must be >= 0, got (${row}, ${col})`);
}
public insertDivider(afterId: NodeId): Ref {
return this.insert({ block: 'divider' }, { after: afterId });
}
public insertImage(
afterId: NodeId,
img: {
srcType: string;
url: string;
alt?: string;
width?: number;
height?: number;
}
): Ref {
return this.insert({ block: 'image', ...img }, { after: afterId });
}
public insertVideo(
afterId: NodeId,
vid: {
srcType: string;
url: string;
controls?: boolean;
width?: number;
height?: number;
}
): Ref {
return this.insert({ block: 'video', ...vid }, { after: afterId });
}
public insertEquation(afterId: NodeId, tex: string): Ref {
return this.insert({ block: 'equation', tex }, { after: afterId });
}
public insertInlineEquation(blockId: NodeId, at: number, tex: string): Ref {
return this.insertInline(blockId, at, { inline: 'equation', tex });
}
public insertTextAfterInline(inlineRef: NodeRef, text: string): this {
return this.push({
kind: 'insertTextAfterInline',
inline: inlineRef,
text,
});
}
public insertLineBreak(blockId: NodeId, at: number): Ref {
return this.insertInline(blockId, at, { inline: 'linebreak' });
}
public insertDate(
blockId: NodeId,
at: number,
isoDate: string,
displayFormat?: string
): Ref {
return this.insertInline(blockId, at, {
inline: 'date',
date: isoDate,
displayFormat,
});
}
/** @-mention a date/time. Same as `insertDate`. */
public mentionDate(
blockId: NodeId,
at: number,
isoDate: string,
displayFormat?: string
): Ref {
return this.insertDate(blockId, at, isoDate, displayFormat);
}
private insertInline(id: NodeId, at: number, spec: NodeSpec): Ref {
this.requireId(id);
if (at < 0) throw new EditError(`inline offset must be >= 0, got ${at}`);
const ref = this.mintRef();
this.push({ kind: 'insertInline', ref, node: id, at, spec });
return ref;
}
public insertMention(blockId: NodeId, at: number, mention: MentionSpec): Ref {
return this.insertInline(blockId, at, { inline: 'mention', mention });
}
public mentionUser(
blockId: NodeId,
at: number,
entity: { userId: string; email: string }
): Ref {
return this.insertMention(blockId, at, { kind: 'user', ...entity });
}
public mentionContact(
blockId: NodeId,
at: number,
entity: {
contactId: string;
name: string;
emailOrDomain: string;
isCompany: boolean;
}
): Ref {
return this.insertMention(blockId, at, { kind: 'contact', ...entity });
}
public mentionGroup(
blockId: NodeId,
at: number,
entity: { groupAlias: string }
): Ref {
return this.insertMention(blockId, at, { kind: 'group', ...entity });
}
public mentionDocument(
blockId: NodeId,
at: number,
entity: {
documentId: string;
documentName: string;
blockName: string;
blockParams?: Record<string, string>;
}
): Ref {
return this.insertMention(blockId, at, { kind: 'document', ...entity });
}
public mentionAgentSession(
blockId: NodeId,
at: number,
entity: { id: string; label?: string; expanded?: boolean }
): Ref {
return this.insertMention(blockId, at, {
kind: 'agent_session',
...entity,
});
}
public mentionPullRequest(
blockId: NodeId,
at: number,
entity: { id: string; label?: string }
): Ref {
return this.insertMention(blockId, at, { kind: 'pr', ...entity });
}
public mentionBookingLink(
blockId: NodeId,
at: number,
entity: {
profileId: string;
url: string;
slug?: string;
label?: string;
}
): Ref {
return this.insertMention(blockId, at, { kind: 'booking_link', ...entity });
}
public mentionTag(
blockId: NodeId,
at: number,
entity: {
optionId: string;
propertyDefinitionId: string;
scope: 'user' | 'team';
name: string;
color?: string;
}
): Ref {
return this.insertMention(blockId, at, { kind: 'tag', ...entity });
}
public setImageAlt(id: NodeId, alt: string): this {
this.requireId(id);
return this.push({ kind: 'setImageAlt', node: id, alt });
}
public setImageUrl(id: NodeId, url: string): this {
this.requireId(id);
return this.push({ kind: 'setImageUrl', node: id, url });
}
public setVideoUrl(id: NodeId, url: string): this {
this.requireId(id);
return this.push({ kind: 'setVideoUrl', node: id, url });
}
public setVideoControls(id: NodeId, controls: boolean): this {
this.requireId(id);
return this.push({ kind: 'setVideoControls', node: id, controls });
}
public setDate(id: NodeId, date: string, displayFormat?: string): this {
this.requireId(id);
return this.push({ kind: 'setDate', node: id, date, displayFormat });
}
private requireQueryBlock(query: string): void {
if (typeof query !== 'string' || !query.includes('<m-db-query>')) {
throw new EditError(
"pass the saved question's <m-db-query>…</m-db-query> block from the request, verbatim"
);
}
}
/** A saved database question (`<m-db-query>` block) as a live number, table, or chart. */
public insertDatabaseQueryAfter(id: NodeId, query: string): Ref {
this.requireQueryBlock(query);
return this.insert({ block: 'database-query', query }, { after: id });
}
public insertDatabaseQueryBefore(id: NodeId, query: string): Ref {
this.requireQueryBlock(query);
return this.insert({ block: 'database-query', query }, { before: id });
}
public appendDatabaseQuery(query: string): Ref {
this.requireQueryBlock(query);
return this.insert(
{ block: 'database-query', query },
{ appendToRoot: true }
);
}
/** A scalar answer inside a sentence, at character offset `at`. */
public insertInlineDatabaseQuery(
blockId: NodeId,
at: number,
query: string
): Ref {
this.requireQueryBlock(query);
return this.insertInline(blockId, at, { inline: 'database-query', query });
}
public setDatabaseQueryView(id: NodeId, view: DatabaseQueryView): this {
this.requireId(id);
if (!view || typeof view !== 'object' || !Object.keys(view).length) {
throw new EditError(
'pass at least one of displayMode, title, chart, or height'
);
}
return this.push({ kind: 'setDatabaseQueryView', node: id, view });
}
/** Show another table (and optionally view) of an embedded database card. */
public setDatabaseLocation(
id: NodeId,
location: { tableId: string; viewId?: string }
): this {
this.requireId(id);
if (typeof location?.tableId !== 'string' || !location.tableId) {
throw new EditError('setDatabaseLocation needs a tableId');
}
return this.push({
kind: 'setDatabaseLocation',
node: id,
tableId: location.tableId,
viewId: location.viewId,
});
}
}
function editorMethodNames(target: DocumentEditor): string[] {
const names = new Set<string>();
for (
let proto = target;
proto && proto !== Object.prototype;
proto = Object.getPrototypeOf(proto)
) {
for (const key of Object.getOwnPropertyNames(proto)) {
if (key === 'constructor' || key.startsWith('_')) continue;
if (typeof target[key as keyof DocumentEditor] === 'function') {
names.add(key);
}
}
}
return [...names];
}
function suggestMethods(wanted: string, names: string[]): string[] {
const normalizedWanted = wanted.toLowerCase();
const scored = names.map((name) => {
const normalizedName = name.toLowerCase();
let score = 0;
if (normalizedName === normalizedWanted) score = 1000;
else if (
normalizedName.includes(normalizedWanted) ||
normalizedWanted.includes(normalizedName)
) {
score = 100 + Math.min(normalizedName.length, normalizedWanted.length);
} else {
while (
score < normalizedName.length &&
score < normalizedWanted.length &&
normalizedName[score] === normalizedWanted[score]
) {
score++;
}
}
return { name, score };
});
scored.sort((a, b) => b.score - a.score);
return scored
.filter(({ score }) => score >= 3)
.slice(0, 3)
.map(({ name }) => name);
}
/** Create the write-only editor exposed to generated sandbox snippets. */
export function createDocumentEditor(
options: DocumentEditorOptions
): DocumentEditor {
const target = new DocumentEditor(options);
return new Proxy(target, {
get(editor, property) {
const value = editor[property as keyof DocumentEditor];
if (value !== undefined || typeof property !== 'string') {
return typeof value === 'function' ? value.bind(editor) : value;
}
return () => {
const suggestions = suggestMethods(property, editorMethodNames(editor));
throw new Error(
`editor.${property} does not exist` +
(suggestions.length
? `. Did you mean: ${suggestions.join(', ')}?`
: '.') +
' The editor is write-only — to inspect the document use the readDocument tool, not a call inside the snippet.'
);
};
},
});
}
export type { MentionSpec };