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
import { type Span, Telemetry } from '@macro-inc/observability';
import { tool } from 'ai';
import { z } from 'zod';
import type { LexicalSession } from '../ai-toolkit';
import type { AwarenessSource } from '../awareness';
import type { Doc } from '../doc';
import type { DocumentOp } from '../editor';
import type { DocumentOpQueueParams } from '../queue';
import { type CodeRunner, runEditorCode } from '../runtime';
export type RunCodeToolOptions = {
session: LexicalSession;
doc: Doc;
awarenessSource: AwarenessSource;
runner: CodeRunner;
params?: DocumentOpQueueParams;
typingAnimations?: boolean;
sleep?: (ms: number) => Promise<void>;
onOps?: (ops: DocumentOp[]) => void;
/** Called when a runCode call begins executing. */
onRunCode?: (snippets?: Record<string, string>) => void;
/** Parent for the per-call `edit.run_code` span (the dispatch span). */
span?: Span;
/** Called with the reply the coder receives. Recorded in the trace so a run
* can be diagnosed after the fact: without it, the trace shows the code a
* coder wrote but not what it was told, which is precisely the signal needed
* to explain why it retried. */
onRunCodeResult?: (result: string) => void;
};
/**
* One snippet as the model sends it. Snippets are a LIST of pairs rather than a
* `{ KEY: text }` object because Gemini's function declarations are an OpenAPI
* subset with no `additionalProperties`, and the AI SDK's Google provider drops
* that field when converting the schema — a record reaches Gemini as an object
* with no fields, and it sends `{}` while its code references `snippets.KEY`.
* Pairs survive the conversion on every provider we use, so there is one shape
* for every agent; the sandbox still sees the record the code indexes into.
*
* `text` also accepts a list of strings: coders routinely send an array when
* composing list content, and a strict string schema rejected 45 such calls
* across the prod corpus, each costing the coder its whole step.
*/
const SnippetPairSchema = z.object({
key: z.string().describe('the name referenced as `snippets.KEY` in code'),
text: z
.union([z.string(), z.array(z.string())])
.describe('the exact text, unescaped; a list of strings for list content'),
});
export type SnippetPair = z.infer<typeof SnippetPairSchema>;
const SnippetsSchema = z
.array(SnippetPairSchema)
.optional()
.describe(
'all text content your code inserts, as a list of { key, text } pairs. reference each as `snippets.KEY` in `code` instead of embedding it as a string literal (avoids escaping errors).'
);
/** The record the sandbox exposes as `snippets`; list values join with newlines
* since every editor primitive takes text, which is what the coder meant. */
export function snippetsToRecord(
snippets: SnippetPair[] | undefined
): Record<string, string> | undefined {
if (!snippets) return undefined;
return Object.fromEntries(
snippets.map(({ key, text }) => [
key,
Array.isArray(text) ? text.join('\n') : (text ?? ''),
])
);
}
/** The writer's one tool: run a JS snippet against `editor`, returning compact
* success or error output. The snippet's only scope is
* `editor` and `snippets`; the system animates + applies the resulting ops live. */
export function createRunCodeTool(opts: RunCodeToolOptions) {
return tool({
description:
"Run JS statements against `editor` (the ONLY in-scope value besides `snippets`) to edit the document — e.g. `editor.convertToHeading('b3', 2); editor.bold('b5', 'word')`. Returns `ok`, or an error naming a bad id so you can retry.",
inputSchema: z.object({
code: z.string(),
snippets: SnippetsSchema,
}),
// The agent's abort signal: a cancelled request stops applying ops.
execute: async ({ code, snippets }, { abortSignal }) => {
const flattened = snippetsToRecord(snippets);
opts.onRunCode?.(flattened);
const span = opts.span
? opts.span.span('edit.run_code')
: Telemetry.span('edit.run_code');
span.setAttr('code.bytes', code.length);
span.setAttr('snippets.count', Object.keys(snippets ?? {}).length);
try {
const result = await runEditorCode({
session: opts.session,
doc: opts.doc,
code,
awarenessSource: opts.awarenessSource,
snippets: flattened,
params: opts.params,
typingAnimations: opts.typingAnimations,
sleep: opts.sleep,
runner: opts.runner,
onOps: opts.onOps,
signal: abortSignal,
span,
});
opts.onRunCodeResult?.(result);
span.setAttr('result', result.startsWith('error:') ? 'error' : 'ok');
return result;
} catch (e) {
span.error(e);
throw e;
} finally {
span.end();
}
},
});
}